+++ /dev/null
-\input texinfo @c -*-texinfo-*-
-@setfilename gdc.info
-@settitle The GNU D Compiler
-
-@c Merge the standard indexes into a single one.
-@syncodeindex fn cp
-@syncodeindex vr cp
-@syncodeindex ky cp
-@syncodeindex pg cp
-@syncodeindex tp cp
-
-@include gcc-common.texi
-
-@c Copyright years for this manual.
-@set copyrights-d 2006-2022
-
-@copying
-@c man begin COPYRIGHT
-Copyright @copyright{} @value{copyrights-d} Free Software Foundation, Inc.
-
-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
-@c man end
-section entitled ``GNU Free Documentation License''.
-@ignore
-@c man begin COPYRIGHT
-man page gfdl(7).
-@c man end
-@end ignore
-@end copying
-
-@ifinfo
-@format
-@dircategory Software development
-@direntry
-* gdc: (gdc). A GCC-based compiler for the D language
-@end direntry
-@end format
-
-@insertcopying
-@end ifinfo
-
-@titlepage
-@title The GNU D Compiler
-@versionsubtitle
-@author David Friedman, Iain Buclaw
-
-@page
-@vskip 0pt plus 1filll
-Published by the Free Software Foundation @*
-51 Franklin Street, Fifth Floor@*
-Boston, MA 02110-1301, USA@*
-@sp 1
-@insertcopying
-@end titlepage
-@contents
-@page
-
-@node Top
-@top Introduction
-
-This manual describes how to use @command{gdc}, the GNU compiler for
-the D programming language. This manual is specifically about
-@command{gdc}. For more information about the D programming
-language in general, including language specifications and standard
-package documentation, see @uref{https://dlang.org/}.
-
-@menu
-* Copying:: The GNU General Public License.
-* GNU Free Documentation License::
- How you can share and copy this manual.
-* Invoking gdc:: How to run gdc.
-* Index:: Index.
-@end menu
-
-
-@include gpl_v3.texi
-
-@include fdl.texi
-
-
-@node Invoking gdc
-@chapter Invoking gdc
-
-@c man title gdc A GCC-based compiler for the D language
-
-@ignore
-@c man begin SYNOPSIS gdc
-gdc [@option{-c}|@option{-S}] [@option{-g}] [@option{-pg}]
- [@option{-O}@var{level}] [@option{-W}@var{warn}@dots{}]
- [@option{-I}@var{dir}@dots{}] [@option{-L}@var{dir}@dots{}]
- [@option{-f}@var{option}@dots{}] [@option{-m}@var{machine-option}@dots{}]
- [@option{-o} @var{outfile}] [@@@var{file}] @var{infile}@dots{}
-
-Only the most useful options are listed here; see below for the
-remainder.
-@c man end
-@c man begin SEEALSO
-gpl(7), gfdl(7), fsf-funding(7), gcc(1)
-and the Info entries for @file{gdc} and @file{gcc}.
-@c man end
-@end ignore
-
-@c man begin DESCRIPTION gdc
-
-The @command{gdc} command is the GNU compiler for the D language and
-supports many of the same options as @command{gcc}. @xref{Option Summary, ,
-Option Summary, gcc, Using the GNU Compiler Collection (GCC)}.
-This manual only documents the options specific to @command{gdc}.
-
-@c man end
-
-@menu
-* Input and Output files:: Controlling the kind of output:
- an executable, object files, assembler files,
-* Runtime Options:: Options controlling runtime behavior
-* Directory Options:: Where to find module files
-* Code Generation:: Options controlling the output of gdc
-* Warnings:: Options controlling warnings specific to gdc
-* Linking:: Options influencing the linking step
-* Developer Options:: Options useful for developers of gdc
-@end menu
-
-@c man begin OPTIONS
-
-@node Input and Output files
-@section Input and Output files
-@cindex suffixes for D source
-@cindex D source file suffixes
-
-For any given input file, the file name suffix determines what kind of
-compilation is done. The following kinds of input file names are supported:
-
-@table @gcctabopt
-@item @var{file}.d
-D source files.
-@item @var{file}.dd
-Ddoc source files.
-@item @var{file}.di
-D interface files.
-@end table
-
-You can specify more than one input file on the @command{gdc} command line,
-each being compiled separately in the compilation process. If you specify a
-@code{-o @var{file}} option, all the input files are compiled together,
-producing a single output file, named @var{file}. This is allowed even
-when using @code{-S} or @code{-c}.
-
-@cindex D interface files.
-A D interface file contains only what an import of the module needs,
-rather than the whole implementation of that module. They can be created
-by @command{gdc} from a D source file by using the @code{-H} option.
-When the compiler resolves an import declaration, it searches for matching
-@file{.di} files first, then for @file{.d}.
-
-@cindex Ddoc source files.
-A Ddoc source file contains code in the D macro processor language. It is
-primarily designed for use in producing user documentation from embedded
-comments, with a slight affinity towards HTML generation. If a @file{.d}
-source file starts with the string @code{Ddoc} then it is treated as general
-purpose documentation, not as a D source file.
-
-@node Runtime Options
-@section Runtime Options
-@cindex options, runtime
-
-These options affect the runtime behavior of programs compiled with
-@command{gdc}.
-
-@table @gcctabopt
-
-@item -fall-instantiations
-@cindex @option{-fall-instantiations}
-@cindex @option{-fno-all-instantiations}
-Generate code for all template instantiations. The default template emission
-strategy is to not generate code for declarations that were either
-instantiated speculatively, such as from @code{__traits(compiles, ...)}, or
-that come from an imported module not being compiled.
-
-@item -fno-assert
-@cindex @option{-fassert}
-@cindex @option{-fno-assert}
-Turn off code generation for @code{assert} contracts.
-
-@item -fno-bounds-check
-@cindex @option{-fbounds-check}
-@cindex @option{-fno-bounds-check}
-Turns off array bounds checking for all functions, which can improve
-performance for code that uses arrays extensively. Note that this
-can result in unpredictable behavior if the code in question actually
-does violate array bounds constraints. It is safe to use this option
-if you are sure that your code never throws a @code{RangeError}.
-
-@item -fbounds-check=@var{value}
-@cindex @option{-fbounds-check=}
-An alternative to @option{-fbounds-check} that allows more control
-as to where bounds checking is turned on or off. The following values
-are supported:
-
-@table @samp
-@item on
-Turns on array bounds checking for all functions.
-@item safeonly
-Turns on array bounds checking only for @code{@@safe} functions.
-@item off
-Turns off array bounds checking completely.
-@end table
-
-@item -fno-builtin
-@cindex @option{-fbuiltin}
-@cindex @option{-fno-builtin}
-Don't recognize built-in functions unless they begin with the prefix
-@samp{__builtin_}. By default, the compiler will recognize when a
-function in the @code{core.stdc} package is a built-in function.
-
-@item -fcheckaction=@var{value}
-@cindex @option{-fcheckaction}
-This option controls what code is generated on an assertion, bounds check, or
-final switch failure. The following values are supported:
-
-@table @samp
-@item context
-Throw an @code{AssertError} with extra context information.
-@item halt
-Halt the program execution.
-@item throw
-Throw an @code{AssertError} (the default).
-@end table
-
-@item -fdebug
-@item -fdebug=@var{value}
-@cindex @option{-fdebug}
-@cindex @option{-fno-debug}
-Turn on compilation of conditional @code{debug} code into the program.
-The @option{-fdebug} option itself sets the debug level to @code{1},
-while @option{-fdebug=} enables @code{debug} code that are identified
-by any of the following values:
-
-@table @samp
-@item level
-Sets the debug level to @var{level}, any @code{debug} code <= @var{level}
-is compiled into the program.
-@item ident
-Turns on compilation of any @code{debug} code identified by @var{ident}.
-@end table
-
-@item -fno-druntime
-@cindex @option{-fdruntime}
-@cindex @option{-fno-druntime}
-Implements @uref{https://dlang.org/spec/betterc.html}. Assumes that
-compilation targets an environment without a D runtime library.
-
-This is equivalent to compiling with the following options:
-
-@example
-gdc -nophoboslib -fno-exceptions -fno-moduleinfo -fno-rtti
-@end example
-
-@item -fextern-std=@var{standard}
-@cindex @option{-fextern-std}
-Sets the C++ name mangling compatibility to the version identified by
-@var{standard}. The following values are supported:
-
-@table @samp
-@item c++98
-@item c++03
-Sets @code{__traits(getTargetInfo, "cppStd")} to @code{199711}.
-@item c++11
-Sets @code{__traits(getTargetInfo, "cppStd")} to @code{201103}.
-@item c++14
-Sets @code{__traits(getTargetInfo, "cppStd")} to @code{201402}.
-@item c++17
-Sets @code{__traits(getTargetInfo, "cppStd")} to @code{201703}.
-This is the default.
-@item c++20
-Sets @code{__traits(getTargetInfo, "cppStd")} to @code{202002}.
-@end table
-
-@item -fno-invariants
-@cindex @option{-finvariants}
-@cindex @option{-fno-invariants}
-Turns off code generation for class @code{invariant} contracts.
-
-@item -fmain
-@cindex @option{-fmain}
-Generates a default @code{main()} function when compiling. This is useful when
-unittesting a library, as it enables running the unittests in a library without
-having to manually define an entry-point function. This option does nothing
-when @code{main} is already defined in user code.
-
-@item -fno-moduleinfo
-@cindex @option{-fmoduleinfo}
-@cindex @option{-fno-moduleinfo}
-Turns off generation of the @code{ModuleInfo} and related functions
-that would become unreferenced without it, which may allow linking
-to programs not written in D. Functions that are not be generated
-include module constructors and destructors (@code{static this} and
-@code{static ~this}), @code{unittest} code, and @code{DSO} registry
-functions for dynamically linked code.
-
-@item -fonly=@var{filename}
-@cindex @option{-fonly}
-Tells the compiler to parse and run semantic analysis on all modules
-on the command line, but only generate code for the module specified
-by @var{filename}.
-
-@item -fno-postconditions
-@cindex @option{-fpostconditions}
-@cindex @option{-fno-postconditions}
-Turns off code generation for postcondition @code{out} contracts.
-
-@item -fno-preconditions
-@cindex @option{-fpreconditions}
-@cindex @option{-fno-preconditions}
-Turns off code generation for precondition @code{in} contracts.
-
-@item -fpreview=@var{id}
-@cindex @option{-fpreview}
-Turns on an upcoming D language change identified by @var{id}. The following
-values are supported:
-
-@table @samp
-@item all
-Turns on all upcoming D language features.
-@item dip1000
-Implements @uref{https://github.com/dlang/DIPs/blob/master/DIPs/other/DIP1000.md}
-(Scoped pointers).
-@item dip1008
-Implements @uref{https://github.com/dlang/DIPs/blob/master/DIPs/other/DIP1008.md}
-(Allow exceptions in @code{@@nogc} code).
-@item dip1021
-Implements @uref{https://github.com/dlang/DIPs/blob/master/DIPs/accepted/DIP1021.md}
-(Mutable function arguments).
-@item dip25
-Implements @uref{https://github.com/dlang/DIPs/blob/master/DIPs/archive/DIP25.md}
-(Sealed references).
-@item dtorfields
-Turns on generation for destructing fields of partially constructed objects.
-@item fieldwise
-Turns on generation of struct equality to use field-wise comparisons.
-@item fixaliasthis
-Implements new lookup rules that check the current scope for @code{alias this}
-before searching in upper scopes.
-@item fiximmutableconv
-Disallows unsound immutable conversions that were formerly incorrectly
-permitted.
-@item in
-Implements @code{in} parameters to mean @code{scope const [ref]} and accepts
-rvalues.
-@item inclusiveincontracts
-Implements @code{in} contracts of overridden methods to be a superset of parent
-contract.
-@item intpromote
-Implements C-style integral promotion for unary @code{+}, @code{-} and @code{~}
-expressions.
-@item nosharedaccess
-Turns off and disallows all access to shared memory objects.
-@item rvaluerefparam
-Implements rvalue arguments to @code{ref} parameters.
-@item systemvariables
-Disables access to variables marked @code{@@system} from @code{@@safe} code.
-@end table
-
-@item -frelease
-@cindex @option{-frelease}
-@cindex @option{-fno-release}
-Turns on compiling in release mode, which means not emitting runtime
-checks for contracts and asserts. Array bounds checking is not done
-for @code{@@system} and @code{@@trusted} functions, and assertion
-failures are undefined behavior.
-
-This is equivalent to compiling with the following options:
-
-@example
-gdc -fno-assert -fbounds-check=safe -fno-invariants \
- -fno-postconditions -fno-preconditions -fno-switch-errors
-@end example
-
-@item -frevert=
-@cindex @option{-frevert}
-Turns off a D language feature identified by @var{id}. The following values
-are supported:
-
-@table @samp
-@item all
-Turns off all revertable D language features.
-@item dip25
-Reverts @uref{https://github.com/dlang/DIPs/blob/master/DIPs/archive/DIP25.md}
-(Sealed references).
-@item dtorfields
-Turns off generation for destructing fields of partially constructed objects.
-@item markdown
-Turns off Markdown replacements in Ddoc comments.
-@end table
-
-@item -fno-rtti
-@cindex @option{-frtti}
-@cindex @option{-fno-rtti}
-Turns off generation of run-time type information for all user defined types.
-Any code that uses features of the language that require access to this
-information will result in an error.
-
-@item -fno-switch-errors
-@cindex @option{-fswitch-errors}
-@cindex @option{-fno-switch-errors}
-This option controls what code is generated when no case is matched
-in a @code{final switch} statement. The default run time behavior
-is to throw a @code{SwitchError}. Turning off @option{-fswitch-errors}
-means that instead the execution of the program is immediately halted.
-
-@item -funittest
-@cindex @option{-funittest}
-@cindex @option{-fno-unittest}
-Turns on compilation of @code{unittest} code, and turns on the
-@code{version(unittest)} identifier. This implies @option{-fassert}.
-
-@item -fversion=@var{value}
-@cindex @option{-fversion}
-Turns on compilation of conditional @code{version} code into the program
-identified by any of the following values:
-
-@table @samp
-@item level
-Sets the version level to @var{level}, any @code{version} code >= @var{level}
-is compiled into the program.
-@item ident
-Turns on compilation of @code{version} code identified by @var{ident}.
-@end table
-
-@item -fno-weak-templates
-@cindex @option{-fweak-templates}
-@cindex @option{-fno-weak-templates}
-Turns off emission of declarations that can be defined in multiple objects as
-weak symbols. The default is to emit all public symbols as weak, unless the
-target lacks support for weak symbols. Disabling this option means that common
-symbols are instead put in COMDAT or become private.
-
-@end table
-
-@node Directory Options
-@section Options for Directory Search
-@cindex directory options
-@cindex options, directory search
-@cindex search path
-
-These options specify directories to search for files, libraries, and
-other parts of the compiler:
-
-@table @gcctabopt
-
-@item -I@var{dir}
-@cindex @option{-I}
-Specify a directory to use when searching for imported modules at
-compile time. Multiple @option{-I} options can be used, and the
-paths are searched in the same order.
-
-@item -J@var{dir}
-@cindex @option{-J}
-Specify a directory to use when searching for files in string imports
-at compile time. This switch is required in order to use
-@code{import(file)} expressions. Multiple @option{-J} options can be
-used, and the paths are searched in the same order.
-
-@item -L@var{dir}
-@cindex @option{-L}
-When linking, specify a library search directory, as with @command{gcc}.
-
-@item -B@var{dir}
-@cindex @option{-B}
-This option specifies where to find the executables, libraries,
-source files, and data files of the compiler itself, as with @command{gcc}.
-
-@item -fmodule-file=@var{module}=@var{spec}
-@cindex @option{-fmodule-file}
-This option manipulates file paths of imported modules, such that if an
-imported module matches all or the leftmost part of @var{module}, the file
-path in @var{spec} is used as the location to search for D sources.
-This is used when the source file path and names are not the same as the
-package and module hierarchy. Consider the following examples:
-
-@example
-gdc test.d -fmodule-file=A.B=foo.d -fmodule-file=C=bar
-@end example
-
-This will tell the compiler to search in all import paths for the source
-file @var{foo.d} when importing @var{A.B}, and the directory @var{bar/}
-when importing @var{C}, as annotated in the following D code:
-
-@example
-module test;
-import A.B; // Matches A.B, searches for foo.d
-import C.D.E; // Matches C, searches for bar/D/E.d
-import A.B.C; // No match, searches for A/B/C.d
-@end example
-
-@item -imultilib @var{dir}
-@cindex @option{-imultilib}
-Use @var{dir} as a subdirectory of the gcc directory containing
-target-specific D sources and interfaces.
-
-@item -iprefix @var{prefix}
-@cindex @option{-iprefix}
-Specify @var{prefix} as the prefix for the gcc directory containing
-target-specific D sources and interfaces. If the @var{prefix} represents
-a directory, you should include the final @code{'/'}.
-
-@item -nostdinc
-@cindex @option{-nostdinc}
-Do not search the standard system directories for D source and interface
-files. Only the directories that have been specified with @option{-I} options
-(and the directory of the current file, if appropriate) are searched.
-
-@end table
-
-@node Code Generation
-@section Code Generation
-@cindex options, code generation
-
-In addition to the many @command{gcc} options controlling code generation,
-@command{gdc} has several options specific to itself.
-
-@table @gcctabopt
-
-@item -H
-@cindex @option{-H}
-Generates D interface files for all modules being compiled. The compiler
-determines the output file based on the name of the input file, removes
-any directory components and suffix, and applies the @file{.di} suffix.
-
-@item -Hd @var{dir}
-@cindex @option{-Hd}
-Same as @option{-H}, but writes interface files to directory @var{dir}.
-This option can be used with @option{-Hf @var{file}} to independently set the
-output file and directory path.
-
-@item -Hf @var{file}
-@cindex @option{-Hf}
-Same as @option{-H} but writes interface files to @var{file}. This option can
-be used with @option{-Hd @var{dir}} to independently set the output file and
-directory path.
-
-@item -M
-@cindex @option{-M}
-Output the module dependencies of all source files being compiled in a
-format suitable for @command{make}. The compiler outputs one
-@command{make} rule containing the object file name for that source file,
-a colon, and the names of all imported files.
-
-@item -MM
-@cindex @option{-MM}
-Like @option{-M} but does not mention imported modules from the D standard
-library package directories.
-
-@item -MF @var{file}
-@cindex @option{-MF}
-When used with @option{-M} or @option{-MM}, specifies a @var{file} to write
-the dependencies to. When used with the driver options @option{-MD} or
-@option{-MMD}, @option{-MF} overrides the default dependency output file.
-
-@item -MG
-@cindex @option{-MG}
-This option is for compatibility with @command{gcc}, and is ignored by the
-compiler.
-
-@item -MP
-@cindex @option{-MP}
-Outputs a phony target for each dependency other than the modules being
-compiled, causing each to depend on nothing.
-
-@item -MT @var{target}
-@cindex @option{-MT}
-Change the @var{target} of the rule emitted by dependency generation
-to be exactly the string you specify. If you want multiple targets,
-you can specify them as a single argument to @option{-MT}, or use
-multiple @option{-MT} options.
-
-@item -MQ @var{target}
-@cindex @option{-MQ}
-Same as @option{-MT}, but it quotes any characters which are special to
-@command{make}.
-
-@item -MD
-@cindex @option{-MD}
-This option is equivalent to @option{-M -MF @var{file}}. The driver
-determines @var{file} by removing any directory components and suffix
-from the input file, and then adding a @file{.deps} suffix.
-
-@item -MMD
-@cindex @option{-MMD}
-Like @option{-MD} but does not mention imported modules from the D standard
-library package directories.
-
-@item -X
-@cindex @option{-X}
-Output information describing the contents of all source files being
-compiled in JSON format to a file. The driver determines @var{file} by
-removing any directory components and suffix from the input file, and then
-adding a @file{.json} suffix.
-
-@item -Xf @var{file}
-@cindex @option{-Xf}
-Same as @option{-X}, but writes all JSON contents to the specified
-@var{file}.
-
-@item -fdoc
-@cindex @option{-fdoc}
-Generates @code{Ddoc} documentation and writes it to a file. The compiler
-determines @var{file} by removing any directory components and suffix
-from the input file, and then adding a @file{.html} suffix.
-
-@item -fdoc-dir=@var{dir}
-@cindex @option{-fdoc-dir}
-Same as @option{-fdoc}, but writes documentation to directory @var{dir}.
-This option can be used with @option{-fdoc-file=@var{file}} to
-independently set the output file and directory path.
-
-@item -fdoc-file=@var{file}
-@cindex @option{-fdoc-file}
-Same as @option{-fdoc}, but writes documentation to @var{file}. This
-option can be used with @option{-fdoc-dir=@var{dir}} to independently
-set the output file and directory path.
-
-@item -fdoc-inc=@var{file}
-@cindex @option{-fdoc-inc}
-Specify @var{file} as a @var{Ddoc} macro file to be read. Multiple
-@option{-fdoc-inc} options can be used, and files are read and processed
-in the same order.
-
-@item -fdump-c++-spec=@var{file}
-For D source files, generate corresponding C++ declarations in @var{file}.
-
-@item -fdump-c++-spec-verbose
-In conjunction with @option{-fdump-c++-spec=} above, add comments for ignored
-declarations in the generated C++ header.
-
-@item -fsave-mixins=@var{file}
-@cindex @option{-fsave-mixins}
-Generates code expanded from D @code{mixin} statements and writes the
-processed sources to @var{file}. This is useful to debug errors in compilation
-and provides source for debuggers to show when requested.
-
-@end table
-
-@node Warnings
-@section Warnings
-@cindex options to control warnings
-@cindex warning messages
-@cindex messages, warning
-@cindex suppressing warnings
-
-Warnings are diagnostic messages that report constructions that
-are not inherently erroneous but that are risky or suggest there
-is likely to be a bug in the program. Unless @option{-Werror} is
-specified, they do not prevent compilation of the program.
-
-@table @gcctabopt
-
-@item -Wall
-@cindex @option{-Wall}
-@cindex @option{-Wno-all}
-Turns on all warnings messages. Warnings are not a defined part of
-the D language, and all constructs for which this may generate a
-warning message are valid code.
-
-@item -Walloca
-@cindex @option{-Walloca}
-This option warns on all uses of "alloca" in the source.
-
-@item -Walloca-larger-than=@var{n}
-@cindex @option{-Walloca-larger-than}
-@cindex @option{-Wno-alloca-larger-than}
-Warn on unbounded uses of alloca, and on bounded uses of alloca
-whose bound can be larger than @var{n} bytes.
-@option{-Wno-alloca-larger-than} disables
-@option{-Walloca-larger-than} warning and is equivalent to
-@option{-Walloca-larger-than=@var{SIZE_MAX}} or larger.
-
-@item -Wcast-result
-@cindex @option{-Wcast-result}
-@cindex @option{-Wno-cast-result}
-Warn about casts that will produce a null or zero result. Currently
-this is only done for casting between an imaginary and non-imaginary
-data type, or casting between a D and C++ class.
-
-@item -Wno-deprecated
-@cindex @option{-Wdeprecated}
-@cindex @option{-Wno-deprecated}
-Do not warn about usage of deprecated features and symbols with
-@code{deprecated} attributes.
-
-@item -Werror
-@cindex @option{-Werror}
-@cindex @option{-Wno-error}
-Turns all warnings into errors.
-
-@item -Wspeculative
-@cindex @option{-Wspeculative}
-@cindex @option{-Wno-speculative}
-List all error messages from speculative compiles, such as
-@code{__traits(compiles, ...)}. This option does not report
-messages as warnings, and these messages therefore never become
-errors when the @option{-Werror} option is also used.
-
-@item -Wtemplates
-@cindex @option{-Wtemplates}
-@cindex @option{-Wno-templates}
-Warn when a template instantiation is encountered. Some coding
-rules disallow templates, and this may be used to enforce that rule.
-
-@item -Wunknown-pragmas
-@cindex @option{-Wunknown-pragmas}
-@cindex @option{-Wno-unknown-pragmas}
-Warn when a @code{pragma()} is encountered that is not understood by
-@command{gdc}. This differs from @option{-fignore-unknown-pragmas}
-where a pragma that is part of the D language, but not implemented by
-the compiler, won't get reported.
-
-@item -Wno-varargs
-@cindex Wvarargs
-@cindex Wno-varargs
-Do not warn upon questionable usage of the macros used to handle variable
-arguments like @code{va_start}.
-
-@item -fignore-unknown-pragmas
-@cindex @option{-fignore-unknown-pragmas}
-@cindex @option{-fno-ignore-unknown-pragmas}
-Turns off errors for unsupported pragmas.
-
-@item -fmax-errors=@var{n}
-@cindex @option{-fmax-errors}
-Limits the maximum number of error messages to @var{n}, at which point
-@command{gdc} bails out rather than attempting to continue processing the
-source code. If @var{n} is 0 (the default), there is no limit on the
-number of error messages produced.
-
-@item -fsyntax-only
-@cindex @option{-fsyntax-only}
-@cindex @option{-fno-syntax-only}
-Check the code for syntax errors, but do not actually compile it. This
-can be used in conjunction with @option{-fdoc} or @option{-H} to generate
-files for each module present on the command-line, but no other output
-file.
-
-@item -ftransition=@var{id}
-@cindex @option{-ftransition}
-Report additional information about D language changes identified by
-@var{id}. The following values are supported:
-
-@table @samp
-@item all
-List information on all D language transitions.
-@item complex
-List all usages of complex or imaginary types.
-@item field
-List all non-mutable fields which occupy an object instance.
-@item in
-List all usages of @code{in} on parameter.
-@item nogc
-List all hidden GC allocations.
-@item templates
-List statistics on template instantiations.
-@item tls
-List all variables going into thread local storage.
-@item vmarkdown
-List instances of Markdown replacements in Ddoc.
-@end table
-
-@end table
-
-@node Linking
-@section Options for Linking
-@cindex options, linking
-@cindex linking, static
-
-These options come into play when the compiler links object files into an
-executable output file. They are meaningless if the compiler is not doing
-a link step.
-
-@table @gcctabopt
-
-@item -defaultlib=@var{libname}
-@cindex @option{-defaultlib=}
-Specify the library to use instead of libphobos when linking. Options
-specifying the linkage of libphobos, such as @option{-static-libphobos}
-or @option{-shared-libphobos}, are ignored.
-
-@item -debuglib=@var{libname}
-@cindex @option{-debuglib=}
-Specify the debug library to use instead of libphobos when linking.
-This option has no effect unless the @option{-g} option was also given
-on the command line. Options specifying the linkage of libphobos, such
-as @option{-static-libphobos} or @option{-shared-libphobos}, are ignored.
-
-@item -nophoboslib
-@cindex @option{-nophoboslib}
-Do not use the Phobos or D runtime library when linking. Options specifying
-the linkage of libphobos, such as @option{-static-libphobos} or
-@option{-shared-libphobos}, are ignored. The standard system libraries are
-used normally, unless @option{-nostdlib} or @option{-nodefaultlibs} is used.
-
-@item -shared-libphobos
-@cindex @option{-shared-libphobos}
-On systems that provide @file{libgphobos} and @file{libgdruntime} as a
-shared and a static library, this option forces the use of the shared
-version. If no shared version was built when the compiler was configured,
-this option has no effect.
-
-@item -static-libphobos
-@cindex @option{-static-libphobos}
-On systems that provide @file{libgphobos} and @file{libgdruntime} as a
-shared and a static library, this option forces the use of the static
-version. If no static version was built when the compiler was configured,
-this option has no effect.
-
-@end table
-
-@node Developer Options
-@section Developer Options
-@cindex developer options
-@cindex debug dump options
-@cindex dump options
-
-This section describes command-line options that are primarily of
-interest to developers or language tooling.
-
-@table @gcctabopt
-
-@item -fdump-d-original
-@cindex @option{-fdump-d-original}
-Output the internal front-end AST after the @code{semantic3} stage.
-This option is only useful for debugging the GNU D compiler itself.
-
-@item -v
-@cindex @option{-v}
-Dump information about the compiler language processing stages as the source
-program is being compiled. This includes listing all modules that are
-processed through the @code{parse}, @code{semantic}, @code{semantic2}, and
-@code{semantic3} stages; all @code{import} modules and their file paths;
-and all @code{function} bodies that are being compiled.
-
-@end table
-
-@c man end
-
-@node Index
-@unnumbered Index
-
-@printindex cp
-
-@bye
+++ /dev/null
-@c Copyright (C) 2019-2022 Free Software Foundation, Inc.
-@c This is part of the GCC manual.
-@c For copying conditions, see the file gcc.texi.
-@c Contributed by David Malcolm <dmalcolm@redhat.com>.
-
-@node Static Analyzer
-@chapter Static Analyzer
-@cindex analyzer
-@cindex static analysis
-@cindex static analyzer
-
-@menu
-* Analyzer Internals:: Analyzer Internals
-* Debugging the Analyzer:: Useful debugging tips
-@end menu
-
-@node Analyzer Internals
-@section Analyzer Internals
-@cindex analyzer, internals
-@cindex static analyzer, internals
-
-@subsection Overview
-
-The analyzer implementation works on the gimple-SSA representation.
-(I chose this in the hopes of making it easy to work with LTO to
-do whole-program analysis).
-
-The implementation is read-only: it doesn't attempt to change anything,
-just emit warnings.
-
-The gimple representation can be seen using @option{-fdump-ipa-analyzer}.
-@quotation Tip
-If the analyzer ICEs before this is written out, one workaround is to use
-@option{--param=analyzer-bb-explosion-factor=0} to force the analyzer
-to bail out after analyzing the first basic block.
-@end quotation
-
-First, we build a @code{supergraph} which combines the callgraph and all
-of the CFGs into a single directed graph, with both interprocedural and
-intraprocedural edges. The nodes and edges in the supergraph are called
-``supernodes'' and ``superedges'', and often referred to in code as
-@code{snodes} and @code{sedges}. Basic blocks in the CFGs are split at
-interprocedural calls, so there can be more than one supernode per
-basic block. Most statements will be in just one supernode, but a call
-statement can appear in two supernodes: at the end of one for the call,
-and again at the start of another for the return.
-
-The supergraph can be seen using @option{-fdump-analyzer-supergraph}.
-
-We then build an @code{analysis_plan} which walks the callgraph to
-determine which calls might be suitable for being summarized (rather
-than fully explored) and thus in what order to explore the functions.
-
-Next is the heart of the analyzer: we use a worklist to explore state
-within the supergraph, building an "exploded graph".
-Nodes in the exploded graph correspond to <point,@w{ }state> pairs, as in
- "Precise Interprocedural Dataflow Analysis via Graph Reachability"
- (Thomas Reps, Susan Horwitz and Mooly Sagiv).
-
-We reuse nodes for <point, state> pairs we've already seen, and avoid
-tracking state too closely, so that (hopefully) we rapidly converge
-on a final exploded graph, and terminate the analysis. We also bail
-out if the number of exploded <end-of-basic-block, state> nodes gets
-larger than a particular multiple of the total number of basic blocks
-(to ensure termination in the face of pathological state-explosion
-cases, or bugs). We also stop exploring a point once we hit a limit
-of states for that point.
-
-We can identify problems directly when processing a <point,@w{ }state>
-instance. For example, if we're finding the successors of
-
-@smallexample
- <point: before-stmt: "free (ptr);",
- state: @{"ptr": freed@}>
-@end smallexample
-
-then we can detect a double-free of "ptr". We can then emit a path
-to reach the problem by finding the simplest route through the graph.
-
-Program points in the analysis are much more fine-grained than in the
-CFG and supergraph, with points (and thus potentially exploded nodes)
-for various events, including before individual statements.
-By default the exploded graph merges multiple consecutive statements
-in a supernode into one exploded edge to minimize the size of the
-exploded graph. This can be suppressed via
-@option{-fanalyzer-fine-grained}.
-The fine-grained approach seems to make things simpler and more debuggable
-that other approaches I tried, in that each point is responsible for one
-thing.
-
-Program points in the analysis also have a "call string" identifying the
-stack of callsites below them, so that paths in the exploded graph
-correspond to interprocedurally valid paths: we always return to the
-correct call site, propagating state information accordingly.
-We avoid infinite recursion by stopping the analysis if a callsite
-appears more than @code{analyzer-max-recursion-depth} in a callstring
-(defaulting to 2).
-
-@subsection Graphs
-
-Nodes and edges in the exploded graph are called ``exploded nodes'' and
-``exploded edges'' and often referred to in the code as
-@code{enodes} and @code{eedges} (especially when distinguishing them
-from the @code{snodes} and @code{sedges} in the supergraph).
-
-Each graph numbers its nodes, giving unique identifiers - supernodes
-are referred to throughout dumps in the form @samp{SN': @var{index}} and
-exploded nodes in the form @samp{EN: @var{index}} (e.g. @samp{SN: 2} and
-@samp{EN:29}).
-
-The supergraph can be seen using @option{-fdump-analyzer-supergraph-graph}.
-
-The exploded graph can be seen using @option{-fdump-analyzer-exploded-graph}
-and other dump options. Exploded nodes are color-coded in the .dot output
-based on state-machine states to make it easier to see state changes at
-a glance.
-
-@subsection State Tracking
-
-There's a tension between:
-@itemize @bullet
-@item
-precision of analysis in the straight-line case, vs
-@item
-exponential blow-up in the face of control flow.
-@end itemize
-
-For example, in general, given this CFG:
-
-@smallexample
- A
- / \
- B C
- \ /
- D
- / \
- E F
- \ /
- G
-@end smallexample
-
-we want to avoid differences in state-tracking in B and C from
-leading to blow-up. If we don't prevent state blowup, we end up
-with exponential growth of the exploded graph like this:
-
-@smallexample
-
- 1:A
- / \
- / \
- / \
- 2:B 3:C
- | |
- 4:D 5:D (2 exploded nodes for D)
- / \ / \
- 6:E 7:F 8:E 9:F
- | | | |
- 10:G 11:G 12:G 13:G (4 exploded nodes for G)
-
-@end smallexample
-
-Similar issues arise with loops.
-
-To prevent this, we follow various approaches:
-
-@enumerate a
-@item
-state pruning: which tries to discard state that won't be relevant
-later on withing the function.
-This can be disabled via @option{-fno-analyzer-state-purge}.
-
-@item
-state merging. We can try to find the commonality between two
-program_state instances to make a third, simpler program_state.
-We have two strategies here:
-
- @enumerate
- @item
- the worklist keeps new nodes for the same program_point together,
- and tries to merge them before processing, and thus before they have
- successors. Hence, in the above, the two nodes for D (4 and 5) reach
- the front of the worklist together, and we create a node for D with
- the merger of the incoming states.
-
- @item
- try merging with the state of existing enodes for the program_point
- (which may have already been explored). There will be duplication,
- but only one set of duplication; subsequent duplicates are more likely
- to hit the cache. In particular, (hopefully) all merger chains are
- finite, and so we guarantee termination.
- This is intended to help with loops: we ought to explore the first
- iteration, and then have a "subsequent iterations" exploration,
- which uses a state merged from that of the first, to be more abstract.
- @end enumerate
-
-We avoid merging pairs of states that have state-machine differences,
-as these are the kinds of differences that are likely to be most
-interesting. So, for example, given:
-
-@smallexample
- if (condition)
- ptr = malloc (size);
- else
- ptr = local_buf;
-
- .... do things with 'ptr'
-
- if (condition)
- free (ptr);
-
- ...etc
-@end smallexample
-
-then we end up with an exploded graph that looks like this:
-
-@smallexample
-
- if (condition)
- / T \ F
- --------- ----------
- / \
- ptr = malloc (size) ptr = local_buf
- | |
- copy of copy of
- "do things with 'ptr'" "do things with 'ptr'"
- with ptr: heap-allocated with ptr: stack-allocated
- | |
- if (condition) if (condition)
- | known to be T | known to be F
- free (ptr); |
- \ /
- -----------------------------
- | ('ptr' is pruned, so states can be merged)
- etc
-
-@end smallexample
-
-where some duplication has occurred, but only for the places where the
-the different paths are worth exploringly separately.
-
-Merging can be disabled via @option{-fno-analyzer-state-merge}.
-@end enumerate
-
-@subsection Region Model
-
-Part of the state stored at a @code{exploded_node} is a @code{region_model}.
-This is an implementation of the region-based ternary model described in
-@url{https://www.researchgate.net/publication/221430855_A_Memory_Model_for_Static_Analysis_of_C_Programs,
-"A Memory Model for Static Analysis of C Programs"}
-(Zhongxing Xu, Ted Kremenek, and Jian Zhang).
-
-A @code{region_model} encapsulates a representation of the state of
-memory, with a @code{store} recording a binding between @code{region}
-instances, to @code{svalue} instances. The bindings are organized into
-clusters, where regions accessible via well-defined pointer arithmetic
-are in the same cluster. The representation is graph-like because values
-can be pointers to regions. It also stores a constraint_manager,
-capturing relationships between the values.
-
-Because each node in the @code{exploded_graph} has a @code{region_model},
-and each of the latter is graph-like, the @code{exploded_graph} is in some
-ways a graph of graphs.
-
-Here's an example of printing a @code{program_state}, showing the
-@code{region_model} within it, along with state for the @code{malloc}
-state machine.
-
-@smallexample
-(gdb) call debug (*this)
-rmodel:
-stack depth: 1
- frame (index 0): frame: ‘test’@@1
-clusters within frame: ‘test’@@1
- cluster for: ptr_3: &HEAP_ALLOCATED_REGION(12)
-m_called_unknown_fn: FALSE
-constraint_manager:
- equiv classes:
- constraints:
-malloc:
- 0x2e89590: &HEAP_ALLOCATED_REGION(12): unchecked ('ptr_3')
-@end smallexample
-
-This is the state at the point of returning from @code{calls_malloc} back
-to @code{test} in the following:
-
-@smallexample
-void *
-calls_malloc (void)
-@{
- void *result = malloc (1024);
- return result;
-@}
-
-void test (void)
-@{
- void *ptr = calls_malloc ();
- /* etc. */
-@}
-@end smallexample
-
-Within the store, there is the cluster for @code{ptr_3} within the frame
-for @code{test}, where the whole cluster is bound to a pointer value,
-pointing at @code{HEAP_ALLOCATED_REGION(12)}. Additionally, this pointer
-has the @code{unchecked} state for the @code{malloc} state machine
-indicating it hasn't yet been checked against NULL since the allocation
-call.
-
-@subsection Analyzer Paths
-
-We need to explain to the user what the problem is, and to persuade them
-that there really is a problem. Hence having a @code{diagnostic_path}
-isn't just an incidental detail of the analyzer; it's required.
-
-Paths ought to be:
-@itemize @bullet
-@item
-interprocedurally-valid
-@item
-feasible
-@end itemize
-
-Without state-merging, all paths in the exploded graph are feasible
-(in terms of constraints being satisfied).
-With state-merging, paths in the exploded graph can be infeasible.
-
-We collate warnings and only emit them for the simplest path
-e.g. for a bug in a utility function, with lots of routes to calling it,
-we only emit the simplest path (which could be intraprocedural, if
-it can be reproduced without a caller).
-
-We thus want to find the shortest feasible path through the exploded
-graph from the origin to the exploded node at which the diagnostic was
-saved. Unfortunately, if we simply find the shortest such path and
-check if it's feasible we might falsely reject the diagnostic, as there
-might be a longer path that is feasible. Examples include the cases
-where the diagnostic requires us to go at least once around a loop for a
-later condition to be satisfied, or where for a later condition to be
-satisfied we need to enter a suite of code that the simpler path skips.
-
-We attempt to find the shortest feasible path to each diagnostic by
-first constructing a ``trimmed graph'' from the exploded graph,
-containing only those nodes and edges from which there are paths to
-the target node, and using Dijkstra's algorithm to order the trimmed
-nodes by minimal distance to the target.
-
-We then use a worklist to iteratively build a ``feasible graph''
-(actually a tree), capturing the pertinent state along each path, in
-which every path to a ``feasible node'' is feasible by construction,
-restricting ourselves to the trimmed graph to ensure we stay on target,
-and ordering the worklist so that the first feasible path we find to the
-target node is the shortest possible path. Hence we start by trying the
-shortest possible path, but if that fails, we explore progressively
-longer paths, eventually trying iterations through loops. The
-exploration is captured in the feasible_graph, which can be dumped as a
-.dot file via @option{-fdump-analyzer-feasibility} to visualize the
-exploration. The indices of the feasible nodes show the order in which
-they were created. We effectively explore the tree of feasible paths in
-order of shortest path until we either find a feasible path to the
-target node, or hit a limit and give up.
-
-This is something of a brute-force approach, but the trimmed graph
-hopefully keeps the complexity manageable.
-
-This algorithm can be disabled (for debugging purposes) via
-@option{-fno-analyzer-feasibility}, which simply uses the shortest path,
-and notes if it is infeasible.
-
-The above gives us a shortest feasible @code{exploded_path} through the
-@code{exploded_graph} (a list of @code{exploded_edge *}). We use this
-@code{exploded_path} to build a @code{diagnostic_path} (a list of
-@strong{events} for the diagnostic subsystem) - specifically a
-@code{checker_path}.
-
-Having built the @code{checker_path}, we prune it to try to eliminate
-events that aren't relevant, to minimize how much the user has to read.
-
-After pruning, we notify each event in the path of its ID and record the
-IDs of interesting events, allowing for events to refer to other events
-in their descriptions. The @code{pending_diagnostic} class has various
-vfuncs to support emitting more precise descriptions, so that e.g.
-
-@itemize @bullet
-@item
-a deref-of-unchecked-malloc diagnostic might use:
-@smallexample
- returning possibly-NULL pointer to 'make_obj' from 'allocator'
-@end smallexample
-for a @code{return_event} to make it clearer how the unchecked value moves
-from callee back to caller
-@item
-a double-free diagnostic might use:
-@smallexample
- second 'free' here; first 'free' was at (3)
-@end smallexample
-and a use-after-free might use
-@smallexample
- use after 'free' here; memory was freed at (2)
-@end smallexample
-@end itemize
-
-At this point we can emit the diagnostic.
-
-@subsection Limitations
-
-@itemize @bullet
-@item
-Only for C so far
-@item
-The implementation of call summaries is currently very simplistic.
-@item
-Lack of function pointer analysis
-@item
-The constraint-handling code assumes reflexivity in some places
-(that values are equal to themselves), which is not the case for NaN.
-As a simple workaround, constraints on floating-point values are
-currently ignored.
-@item
-There are various other limitations in the region model (grep for TODO/xfail
-in the testsuite).
-@item
-The constraint_manager's implementation of transitivity is currently too
-expensive to enable by default and so must be manually enabled via
-@option{-fanalyzer-transitivity}).
-@item
-The checkers are currently hardcoded and don't allow for user extensibility
-(e.g. adding allocate/release pairs).
-@item
-Although the analyzer's test suite has a proof-of-concept test case for
-LTO, LTO support hasn't had extensive testing. There are various
-lang-specific things in the analyzer that assume C rather than LTO.
-For example, SSA names are printed to the user in ``raw'' form, rather
-than printing the underlying variable name.
-@end itemize
-
-Some ideas for other checkers
-@itemize @bullet
-@item
-File-descriptor-based APIs
-@item
-Linux kernel internal APIs
-@item
-Signal handling
-@end itemize
-
-@node Debugging the Analyzer
-@section Debugging the Analyzer
-@cindex analyzer, debugging
-@cindex static analyzer, debugging
-
-@subsection Special Functions for Debugging the Analyzer
-
-The analyzer recognizes various special functions by name, for use
-in debugging the analyzer. Declarations can be seen in the testsuite
-in @file{analyzer-decls.h}. None of these functions are actually
-implemented.
-
-Add:
-@smallexample
- __analyzer_break ();
-@end smallexample
-to the source being analyzed to trigger a breakpoint in the analyzer when
-that source is reached. By putting a series of these in the source, it's
-much easier to effectively step through the program state as it's analyzed.
-
-The analyzer handles:
-
-@smallexample
-__analyzer_describe (0, expr);
-@end smallexample
-
-by emitting a warning describing the 2nd argument (which can be of any
-type), at a verbosity level given by the 1st argument. This is for use when
-debugging, and may be of use in DejaGnu tests.
-
-@smallexample
-__analyzer_dump ();
-@end smallexample
-
-will dump the copious information about the analyzer's state each time it
-reaches the call in its traversal of the source.
-
-@smallexample
-extern void __analyzer_dump_capacity (const void *ptr);
-@end smallexample
-
-will emit a warning describing the capacity of the base region of
-the region pointed to by the 1st argument.
-
-@smallexample
-extern void __analyzer_dump_escaped (void);
-@end smallexample
-
-will emit a warning giving the number of decls that have escaped on this
-analysis path, followed by a comma-separated list of their names,
-in alphabetical order.
-
-@smallexample
-__analyzer_dump_path ();
-@end smallexample
-
-will emit a placeholder ``note'' diagnostic with a path to that call site,
-if the analyzer finds a feasible path to it.
-
-The builtin @code{__analyzer_dump_exploded_nodes} will emit a warning
-after analysis containing information on all of the exploded nodes at that
-program point:
-
-@smallexample
- __analyzer_dump_exploded_nodes (0);
-@end smallexample
-
-will output the number of ``processed'' nodes, and the IDs of
-both ``processed'' and ``merger'' nodes, such as:
-
-@smallexample
-warning: 2 processed enodes: [EN: 56, EN: 58] merger(s): [EN: 54-55, EN: 57, EN: 59]
-@end smallexample
-
-With a non-zero argument
-
-@smallexample
- __analyzer_dump_exploded_nodes (1);
-@end smallexample
-
-it will also dump all of the states within the ``processed'' nodes.
-
-@smallexample
- __analyzer_dump_region_model ();
-@end smallexample
-will dump the region_model's state to stderr.
-
-@smallexample
-__analyzer_dump_state ("malloc", ptr);
-@end smallexample
-
-will emit a warning describing the state of the 2nd argument
-(which can be of any type) with respect to the state machine with
-a name matching the 1st argument (which must be a string literal).
-This is for use when debugging, and may be of use in DejaGnu tests.
-
-@smallexample
-__analyzer_eval (expr);
-@end smallexample
-will emit a warning with text "TRUE", FALSE" or "UNKNOWN" based on the
-truthfulness of the argument. This is useful for writing DejaGnu tests.
-
-@smallexample
-__analyzer_get_unknown_ptr ();
-@end smallexample
-will obtain an unknown @code{void *}.
-
-@subsection Other Debugging Techniques
-
-The option @option{-fdump-analyzer-json} will dump both the supergraph
-and the exploded graph in compressed JSON form.
-
-One approach when tracking down where a particular bogus state is
-introduced into the @code{exploded_graph} is to add custom code to
-@code{program_state::validate}.
-
-The debug function @code{region::is_named_decl_p} can be used when debugging,
-such as for assertions and conditional breakpoints. For example, when
-tracking down a bug in handling a decl called @code{yy_buffer_stack}, I
-temporarily added a:
-@smallexample
- gcc_assert (!m_base_region->is_named_decl_p ("yy_buffer_stack"));
-@end smallexample
-to @code{binding_cluster::mark_as_escaped} to trap a point where
-@code{yy_buffer_stack} was mistakenly being treated as having escaped.
+++ /dev/null
-@c Copyright (C) 2012-2022 Free Software Foundation, Inc.
-@c This is part of the GCC manual.
-@c For copying conditions, see the file gcc/doc/include/fdl.texi.
-
-@c This file is generated automatically using
-@c gcc/config/avr/gen-avr-mmcu-texi.cc from:
-@c gcc/config/avr/avr-arch.h
-@c gcc/config/avr/avr-devices.cc
-@c gcc/config/avr/avr-mcus.def
-
-@c Please do not edit manually.
-
-@table @code
-
-@item avr2
-``Classic'' devices with up to 8@tie{}KiB of program memory.
-@*@var{mcu}@tie{}= @code{attiny22}, @code{attiny26}, @code{at90s2313}, @code{at90s2323}, @code{at90s2333}, @code{at90s2343}, @code{at90s4414}, @code{at90s4433}, @code{at90s4434}, @code{at90c8534}, @code{at90s8515}, @code{at90s8535}.
-
-@item avr25
-``Classic'' devices with up to 8@tie{}KiB of program memory and with the @code{MOVW} instruction.
-@*@var{mcu}@tie{}= @code{attiny13}, @code{attiny13a}, @code{attiny24}, @code{attiny24a}, @code{attiny25}, @code{attiny261}, @code{attiny261a}, @code{attiny2313}, @code{attiny2313a}, @code{attiny43u}, @code{attiny44}, @code{attiny44a}, @code{attiny45}, @code{attiny48}, @code{attiny441}, @code{attiny461}, @code{attiny461a}, @code{attiny4313}, @code{attiny84}, @code{attiny84a}, @code{attiny85}, @code{attiny87}, @code{attiny88}, @code{attiny828}, @code{attiny841}, @code{attiny861}, @code{attiny861a}, @code{ata5272}, @code{ata6616c}, @code{at86rf401}.
-
-@item avr3
-``Classic'' devices with 16@tie{}KiB up to 64@tie{}KiB of program memory.
-@*@var{mcu}@tie{}= @code{at76c711}, @code{at43usb355}.
-
-@item avr31
-``Classic'' devices with 128@tie{}KiB of program memory.
-@*@var{mcu}@tie{}= @code{atmega103}, @code{at43usb320}.
-
-@item avr35
-``Classic'' devices with 16@tie{}KiB up to 64@tie{}KiB of program memory and with the @code{MOVW} instruction.
-@*@var{mcu}@tie{}= @code{attiny167}, @code{attiny1634}, @code{atmega8u2}, @code{atmega16u2}, @code{atmega32u2}, @code{ata5505}, @code{ata6617c}, @code{ata664251}, @code{at90usb82}, @code{at90usb162}.
-
-@item avr4
-``Enhanced'' devices with up to 8@tie{}KiB of program memory.
-@*@var{mcu}@tie{}= @code{atmega48}, @code{atmega48a}, @code{atmega48p}, @code{atmega48pa}, @code{atmega48pb}, @code{atmega8}, @code{atmega8a}, @code{atmega8hva}, @code{atmega88}, @code{atmega88a}, @code{atmega88p}, @code{atmega88pa}, @code{atmega88pb}, @code{atmega8515}, @code{atmega8535}, @code{ata6285}, @code{ata6286}, @code{ata6289}, @code{ata6612c}, @code{at90pwm1}, @code{at90pwm2}, @code{at90pwm2b}, @code{at90pwm3}, @code{at90pwm3b}, @code{at90pwm81}.
-
-@item avr5
-``Enhanced'' devices with 16@tie{}KiB up to 64@tie{}KiB of program memory.
-@*@var{mcu}@tie{}= @code{atmega16}, @code{atmega16a}, @code{atmega16hva}, @code{atmega16hva2}, @code{atmega16hvb}, @code{atmega16hvbrevb}, @code{atmega16m1}, @code{atmega16u4}, @code{atmega161}, @code{atmega162}, @code{atmega163}, @code{atmega164a}, @code{atmega164p}, @code{atmega164pa}, @code{atmega165}, @code{atmega165a}, @code{atmega165p}, @code{atmega165pa}, @code{atmega168}, @code{atmega168a}, @code{atmega168p}, @code{atmega168pa}, @code{atmega168pb}, @code{atmega169}, @code{atmega169a}, @code{atmega169p}, @code{atmega169pa}, @code{atmega32}, @code{atmega32a}, @code{atmega32c1}, @code{atmega32hvb}, @code{atmega32hvbrevb}, @code{atmega32m1}, @code{atmega32u4}, @code{atmega32u6}, @code{atmega323}, @code{atmega324a}, @code{atmega324p}, @code{atmega324pa}, @code{atmega324pb}, @code{atmega325}, @code{atmega325a}, @code{atmega325p}, @code{atmega325pa}, @code{atmega328}, @code{atmega328p}, @code{atmega328pb}, @code{atmega329}, @code{atmega329a}, @code{atmega329p}, @code{atmega329pa}, @code{atmega3250}, @code{atmega3250a}, @code{atmega3250p}, @code{atmega3250pa}, @code{atmega3290}, @code{atmega3290a}, @code{atmega3290p}, @code{atmega3290pa}, @code{atmega406}, @code{atmega64}, @code{atmega64a}, @code{atmega64c1}, @code{atmega64hve}, @code{atmega64hve2}, @code{atmega64m1}, @code{atmega64rfr2}, @code{atmega640}, @code{atmega644}, @code{atmega644a}, @code{atmega644p}, @code{atmega644pa}, @code{atmega644rfr2}, @code{atmega645}, @code{atmega645a}, @code{atmega645p}, @code{atmega649}, @code{atmega649a}, @code{atmega649p}, @code{atmega6450}, @code{atmega6450a}, @code{atmega6450p}, @code{atmega6490}, @code{atmega6490a}, @code{atmega6490p}, @code{ata5795}, @code{ata5790}, @code{ata5790n}, @code{ata5791}, @code{ata6613c}, @code{ata6614q}, @code{ata5782}, @code{ata5831}, @code{ata8210}, @code{ata8510}, @code{ata5702m322}, @code{at90pwm161}, @code{at90pwm216}, @code{at90pwm316}, @code{at90can32}, @code{at90can64}, @code{at90scr100}, @code{at90usb646}, @code{at90usb647}, @code{at94k}, @code{m3000}.
-
-@item avr51
-``Enhanced'' devices with 128@tie{}KiB of program memory.
-@*@var{mcu}@tie{}= @code{atmega128}, @code{atmega128a}, @code{atmega128rfa1}, @code{atmega128rfr2}, @code{atmega1280}, @code{atmega1281}, @code{atmega1284}, @code{atmega1284p}, @code{atmega1284rfr2}, @code{at90can128}, @code{at90usb1286}, @code{at90usb1287}.
-
-@item avr6
-``Enhanced'' devices with 3-byte PC, i.e.@: with more than 128@tie{}KiB of program memory.
-@*@var{mcu}@tie{}= @code{atmega256rfr2}, @code{atmega2560}, @code{atmega2561}, @code{atmega2564rfr2}.
-
-@item avrxmega2
-``XMEGA'' devices with more than 8@tie{}KiB and up to 64@tie{}KiB of program memory.
-@*@var{mcu}@tie{}= @code{atxmega8e5}, @code{atxmega16a4}, @code{atxmega16a4u}, @code{atxmega16c4}, @code{atxmega16d4}, @code{atxmega16e5}, @code{atxmega32a4}, @code{atxmega32a4u}, @code{atxmega32c3}, @code{atxmega32c4}, @code{atxmega32d3}, @code{atxmega32d4}, @code{atxmega32e5}, @code{avr64da28}, @code{avr64da32}, @code{avr64da48}, @code{avr64da64}, @code{avr64db28}, @code{avr64db32}, @code{avr64db48}, @code{avr64db64}.
-
-@item avrxmega3
-``XMEGA'' devices with up to 64@tie{}KiB of combined program memory and RAM, and with program memory visible in the RAM address space.
-@*@var{mcu}@tie{}= @code{attiny202}, @code{attiny204}, @code{attiny212}, @code{attiny214}, @code{attiny402}, @code{attiny404}, @code{attiny406}, @code{attiny412}, @code{attiny414}, @code{attiny416}, @code{attiny417}, @code{attiny804}, @code{attiny806}, @code{attiny807}, @code{attiny814}, @code{attiny816}, @code{attiny817}, @code{attiny1604}, @code{attiny1606}, @code{attiny1607}, @code{attiny1614}, @code{attiny1616}, @code{attiny1617}, @code{attiny3214}, @code{attiny3216}, @code{attiny3217}, @code{atmega808}, @code{atmega809}, @code{atmega1608}, @code{atmega1609}, @code{atmega3208}, @code{atmega3209}, @code{atmega4808}, @code{atmega4809}, @code{avr32da28}, @code{avr32da32}, @code{avr32da48}, @code{avr32db28}, @code{avr32db32}, @code{avr32db48}.
-
-@item avrxmega4
-``XMEGA'' devices with more than 64@tie{}KiB and up to 128@tie{}KiB of program memory.
-@*@var{mcu}@tie{}= @code{atxmega64a3}, @code{atxmega64a3u}, @code{atxmega64a4u}, @code{atxmega64b1}, @code{atxmega64b3}, @code{atxmega64c3}, @code{atxmega64d3}, @code{atxmega64d4}, @code{avr128da28}, @code{avr128da32}, @code{avr128da48}, @code{avr128da64}, @code{avr128db28}, @code{avr128db32}, @code{avr128db48}, @code{avr128db64}.
-
-@item avrxmega5
-``XMEGA'' devices with more than 64@tie{}KiB and up to 128@tie{}KiB of program memory and more than 64@tie{}KiB of RAM.
-@*@var{mcu}@tie{}= @code{atxmega64a1}, @code{atxmega64a1u}.
-
-@item avrxmega6
-``XMEGA'' devices with more than 128@tie{}KiB of program memory.
-@*@var{mcu}@tie{}= @code{atxmega128a3}, @code{atxmega128a3u}, @code{atxmega128b1}, @code{atxmega128b3}, @code{atxmega128c3}, @code{atxmega128d3}, @code{atxmega128d4}, @code{atxmega192a3}, @code{atxmega192a3u}, @code{atxmega192c3}, @code{atxmega192d3}, @code{atxmega256a3}, @code{atxmega256a3b}, @code{atxmega256a3bu}, @code{atxmega256a3u}, @code{atxmega256c3}, @code{atxmega256d3}, @code{atxmega384c3}, @code{atxmega384d3}.
-
-@item avrxmega7
-``XMEGA'' devices with more than 128@tie{}KiB of program memory and more than 64@tie{}KiB of RAM.
-@*@var{mcu}@tie{}= @code{atxmega128a1}, @code{atxmega128a1u}, @code{atxmega128a4u}.
-
-@item avrtiny
-``TINY'' Tiny core devices with 512@tie{}B up to 4@tie{}KiB of program memory.
-@*@var{mcu}@tie{}= @code{attiny4}, @code{attiny5}, @code{attiny9}, @code{attiny10}, @code{attiny20}, @code{attiny40}.
-
-@item avr1
-This ISA is implemented by the minimal AVR core and supported for assembler only.
-@*@var{mcu}@tie{}= @code{attiny11}, @code{attiny12}, @code{attiny15}, @code{attiny28}, @code{at90s1200}.
-
-@end table
+++ /dev/null
-@c Copyright (C) 1988-2022 Free Software Foundation, Inc.
-@c This is part of the GCC manual.
-@c For copying conditions, see the file gcc.texi.
-
-@node Bugs
-@chapter Reporting Bugs
-@cindex bugs
-@cindex reporting bugs
-
-Your bug reports play an essential role in making GCC reliable.
-
-When you encounter a problem, the first thing to do is to see if it is
-already known. @xref{Trouble}. If it isn't known, then you should
-report the problem.
-
-@menu
-* Criteria: Bug Criteria. Have you really found a bug?
-* Reporting: Bug Reporting. How to report a bug effectively.
-@end menu
-
-@node Bug Criteria
-@section Have You Found a Bug?
-@cindex bug criteria
-
-If you are not sure whether you have found a bug, here are some guidelines:
-
-@itemize @bullet
-@cindex fatal signal
-@cindex core dump
-@item
-If the compiler gets a fatal signal, for any input whatever, that is a
-compiler bug. Reliable compilers never crash.
-
-@cindex invalid assembly code
-@cindex assembly code, invalid
-@item
-If the compiler produces invalid assembly code, for any input whatever
-(except an @code{asm} statement), that is a compiler bug, unless the
-compiler reports errors (not just warnings) which would ordinarily
-prevent the assembler from being run.
-
-@cindex undefined behavior
-@cindex undefined function value
-@cindex increment operators
-@item
-If the compiler produces valid assembly code that does not correctly
-execute the input source code, that is a compiler bug.
-
-However, you must double-check to make sure, because you may have a
-program whose behavior is undefined, which happened by chance to give
-the desired results with another C or C++ compiler.
-
-For example, in many nonoptimizing compilers, you can write @samp{x;}
-at the end of a function instead of @samp{return x;}, with the same
-results. But the value of the function is undefined if @code{return}
-is omitted; it is not a bug when GCC produces different results.
-
-Problems often result from expressions with two increment operators,
-as in @code{f (*p++, *p++)}. Your previous compiler might have
-interpreted that expression the way you intended; GCC might
-interpret it another way. Neither compiler is wrong. The bug is
-in your code.
-
-After you have localized the error to a single source line, it should
-be easy to check for these things. If your program is correct and
-well defined, you have found a compiler bug.
-
-@item
-If the compiler produces an error message for valid input, that is a
-compiler bug.
-
-@cindex invalid input
-@item
-If the compiler does not produce an error message for invalid input,
-that is a compiler bug. However, you should note that your idea of
-``invalid input'' might be someone else's idea of ``an extension'' or
-``support for traditional practice''.
-
-@item
-If you are an experienced user of one of the languages GCC supports, your
-suggestions for improvement of GCC are welcome in any case.
-@end itemize
-
-@node Bug Reporting
-@section How and Where to Report Bugs
-@cindex compiler bugs, reporting
-
-Bugs should be reported to the bug database at @value{BUGURL}.
+++ /dev/null
-@c -*-texinfo-*-
-@c Copyright (C) 2001-2022 Free Software Foundation, Inc.
-@c This is part of the GCC manual.
-@c For copying conditions, see the file gcc.texi.
-
-@c ---------------------------------------------------------------------
-@c Control Flow Graph
-@c ---------------------------------------------------------------------
-
-@node Control Flow
-@chapter Control Flow Graph
-@cindex CFG, Control Flow Graph
-@findex basic-block.h
-
-A control flow graph (CFG) is a data structure built on top of the
-intermediate code representation (the RTL or @code{GIMPLE} instruction
-stream) abstracting the control flow behavior of a function that is
-being compiled. The CFG is a directed graph where the vertices
-represent basic blocks and edges represent possible transfer of
-control flow from one basic block to another. The data structures
-used to represent the control flow graph are defined in
-@file{basic-block.h}.
-
-In GCC, the representation of control flow is maintained throughout
-the compilation process, from constructing the CFG early in
-@code{pass_build_cfg} to @code{pass_free_cfg} (see @file{passes.def}).
-The CFG takes various different modes and may undergo extensive
-manipulations, but the graph is always valid between its construction
-and its release. This way, transfer of information such as data flow,
-a measured profile, or the loop tree, can be propagated through the
-passes pipeline, and even from @code{GIMPLE} to @code{RTL}.
-
-Often the CFG may be better viewed as integral part of instruction
-chain, than structure built on the top of it. Updating the compiler's
-intermediate representation for instructions cannot be easily done
-without proper maintenance of the CFG simultaneously.
-
-@menu
-* Basic Blocks:: The definition and representation of basic blocks.
-* Edges:: Types of edges and their representation.
-* Profile information:: Representation of frequencies and probabilities.
-* Maintaining the CFG:: Keeping the control flow graph and up to date.
-* Liveness information:: Using and maintaining liveness information.
-@end menu
-
-
-@node Basic Blocks
-@section Basic Blocks
-
-@cindex basic block
-@findex basic_block
-A basic block is a straight-line sequence of code with only one entry
-point and only one exit. In GCC, basic blocks are represented using
-the @code{basic_block} data type.
-
-@findex ENTRY_BLOCK_PTR, EXIT_BLOCK_PTR
-Special basic blocks represent possible entry and exit points of a
-function. These blocks are called @code{ENTRY_BLOCK_PTR} and
-@code{EXIT_BLOCK_PTR}. These blocks do not contain any code.
-
-@findex BASIC_BLOCK
-The @code{BASIC_BLOCK} array contains all basic blocks in an
-unspecified order. Each @code{basic_block} structure has a field
-that holds a unique integer identifier @code{index} that is the
-index of the block in the @code{BASIC_BLOCK} array.
-The total number of basic blocks in the function is
-@code{n_basic_blocks}. Both the basic block indices and
-the total number of basic blocks may vary during the compilation
-process, as passes reorder, create, duplicate, and destroy basic
-blocks. The index for any block should never be greater than
-@code{last_basic_block}. The indices 0 and 1 are special codes
-reserved for @code{ENTRY_BLOCK} and @code{EXIT_BLOCK}, the
-indices of @code{ENTRY_BLOCK_PTR} and @code{EXIT_BLOCK_PTR}.
-
-@findex next_bb, prev_bb, FOR_EACH_BB, FOR_ALL_BB
-Two pointer members of the @code{basic_block} structure are the
-pointers @code{next_bb} and @code{prev_bb}. These are used to keep
-doubly linked chain of basic blocks in the same order as the
-underlying instruction stream. The chain of basic blocks is updated
-transparently by the provided API for manipulating the CFG@. The macro
-@code{FOR_EACH_BB} can be used to visit all the basic blocks in
-lexicographical order, except @code{ENTRY_BLOCK} and @code{EXIT_BLOCK}.
-The macro @code{FOR_ALL_BB} also visits all basic blocks in
-lexicographical order, including @code{ENTRY_BLOCK} and @code{EXIT_BLOCK}.
-
-@findex post_order_compute, inverted_post_order_compute, walk_dominator_tree
-The functions @code{post_order_compute} and @code{inverted_post_order_compute}
-can be used to compute topological orders of the CFG. The orders are
-stored as vectors of basic block indices. The @code{BASIC_BLOCK} array
-can be used to iterate each basic block by index.
-Dominator traversals are also possible using
-@code{walk_dominator_tree}. Given two basic blocks A and B, block A
-dominates block B if A is @emph{always} executed before B@.
-
-Each @code{basic_block} also contains pointers to the first
-instruction (the @dfn{head}) and the last instruction (the @dfn{tail})
-or @dfn{end} of the instruction stream contained in a basic block. In
-fact, since the @code{basic_block} data type is used to represent
-blocks in both major intermediate representations of GCC (@code{GIMPLE}
-and RTL), there are pointers to the head and end of a basic block for
-both representations, stored in intermediate representation specific
-data in the @code{il} field of @code{struct basic_block_def}.
-
-@findex CODE_LABEL
-@findex NOTE_INSN_BASIC_BLOCK
-For RTL, these pointers are @code{BB_HEAD} and @code{BB_END}.
-
-@cindex insn notes, notes
-@findex NOTE_INSN_BASIC_BLOCK
-In the RTL representation of a function, the instruction stream
-contains not only the ``real'' instructions, but also @dfn{notes}
-or @dfn{insn notes} (to distinguish them from @dfn{reg notes}).
-Any function that moves or duplicates the basic blocks needs
-to take care of updating of these notes. Many of these notes expect
-that the instruction stream consists of linear regions, so updating
-can sometimes be tedious. All types of insn notes are defined
-in @file{insn-notes.def}.
-
-In the RTL function representation, the instructions contained in a
-basic block always follow a @code{NOTE_INSN_BASIC_BLOCK}, but zero
-or more @code{CODE_LABEL} nodes can precede the block note.
-A basic block ends with a control flow instruction or with the last
-instruction before the next @code{CODE_LABEL} or
-@code{NOTE_INSN_BASIC_BLOCK}.
-By definition, a @code{CODE_LABEL} cannot appear in the middle of
-the instruction stream of a basic block.
-
-@findex can_fallthru
-@cindex table jump
-In addition to notes, the jump table vectors are also represented as
-``pseudo-instructions'' inside the insn stream. These vectors never
-appear in the basic block and should always be placed just after the
-table jump instructions referencing them. After removing the
-table-jump it is often difficult to eliminate the code computing the
-address and referencing the vector, so cleaning up these vectors is
-postponed until after liveness analysis. Thus the jump table vectors
-may appear in the insn stream unreferenced and without any purpose.
-Before any edge is made @dfn{fall-thru}, the existence of such
-construct in the way needs to be checked by calling
-@code{can_fallthru} function.
-
-@cindex GIMPLE statement iterators
-For the @code{GIMPLE} representation, the PHI nodes and statements
-contained in a basic block are in a @code{gimple_seq} pointed to by
-the basic block intermediate language specific pointers.
-Abstract containers and iterators are used to access the PHI nodes
-and statements in a basic blocks. These iterators are called
-@dfn{GIMPLE statement iterators} (GSIs). Grep for @code{^gsi}
-in the various @file{gimple-*} and @file{tree-*} files.
-There is a @code{gimple_stmt_iterator} type for iterating over
-all kinds of statement, and a @code{gphi_iterator} subclass for
-iterating over PHI nodes.
-The following snippet will pretty-print all PHI nodes the statements
-of the current function in the GIMPLE representation.
-
-@smallexample
-basic_block bb;
-
-FOR_EACH_BB (bb)
- @{
- gphi_iterator pi;
- gimple_stmt_iterator si;
-
- for (pi = gsi_start_phis (bb); !gsi_end_p (pi); gsi_next (&pi))
- @{
- gphi *phi = pi.phi ();
- print_gimple_stmt (dump_file, phi, 0, TDF_SLIM);
- @}
- for (si = gsi_start_bb (bb); !gsi_end_p (si); gsi_next (&si))
- @{
- gimple stmt = gsi_stmt (si);
- print_gimple_stmt (dump_file, stmt, 0, TDF_SLIM);
- @}
- @}
-@end smallexample
-
-
-@node Edges
-@section Edges
-
-@cindex edge in the flow graph
-@findex edge
-Edges represent possible control flow transfers from the end of some
-basic block A to the head of another basic block B@. We say that A is
-a predecessor of B, and B is a successor of A@. Edges are represented
-in GCC with the @code{edge} data type. Each @code{edge} acts as a
-link between two basic blocks: The @code{src} member of an edge
-points to the predecessor basic block of the @code{dest} basic block.
-The members @code{preds} and @code{succs} of the @code{basic_block} data
-type point to type-safe vectors of edges to the predecessors and
-successors of the block.
-
-@cindex edge iterators
-When walking the edges in an edge vector, @dfn{edge iterators} should
-be used. Edge iterators are constructed using the
-@code{edge_iterator} data structure and several methods are available
-to operate on them:
-
-@ftable @code
-@item ei_start
-This function initializes an @code{edge_iterator} that points to the
-first edge in a vector of edges.
-
-@item ei_last
-This function initializes an @code{edge_iterator} that points to the
-last edge in a vector of edges.
-
-@item ei_end_p
-This predicate is @code{true} if an @code{edge_iterator} represents
-the last edge in an edge vector.
-
-@item ei_one_before_end_p
-This predicate is @code{true} if an @code{edge_iterator} represents
-the second last edge in an edge vector.
-
-@item ei_next
-This function takes a pointer to an @code{edge_iterator} and makes it
-point to the next edge in the sequence.
-
-@item ei_prev
-This function takes a pointer to an @code{edge_iterator} and makes it
-point to the previous edge in the sequence.
-
-@item ei_edge
-This function returns the @code{edge} currently pointed to by an
-@code{edge_iterator}.
-
-@item ei_safe_edge
-This function returns the @code{edge} currently pointed to by an
-@code{edge_iterator}, but returns @code{NULL} if the iterator is
-pointing at the end of the sequence. This function has been provided
-for existing code makes the assumption that a @code{NULL} edge
-indicates the end of the sequence.
-
-@end ftable
-
-The convenience macro @code{FOR_EACH_EDGE} can be used to visit all of
-the edges in a sequence of predecessor or successor edges. It must
-not be used when an element might be removed during the traversal,
-otherwise elements will be missed. Here is an example of how to use
-the macro:
-
-@smallexample
-edge e;
-edge_iterator ei;
-
-FOR_EACH_EDGE (e, ei, bb->succs)
- @{
- if (e->flags & EDGE_FALLTHRU)
- break;
- @}
-@end smallexample
-
-@findex fall-thru
-There are various reasons why control flow may transfer from one block
-to another. One possibility is that some instruction, for example a
-@code{CODE_LABEL}, in a linearized instruction stream just always
-starts a new basic block. In this case a @dfn{fall-thru} edge links
-the basic block to the first following basic block. But there are
-several other reasons why edges may be created. The @code{flags}
-field of the @code{edge} data type is used to store information
-about the type of edge we are dealing with. Each edge is of one of
-the following types:
-
-@table @emph
-@item jump
-No type flags are set for edges corresponding to jump instructions.
-These edges are used for unconditional or conditional jumps and in
-RTL also for table jumps. They are the easiest to manipulate as they
-may be freely redirected when the flow graph is not in SSA form.
-
-@item fall-thru
-@findex EDGE_FALLTHRU, force_nonfallthru
-Fall-thru edges are present in case where the basic block may continue
-execution to the following one without branching. These edges have
-the @code{EDGE_FALLTHRU} flag set. Unlike other types of edges, these
-edges must come into the basic block immediately following in the
-instruction stream. The function @code{force_nonfallthru} is
-available to insert an unconditional jump in the case that redirection
-is needed. Note that this may require creation of a new basic block.
-
-@item exception handling
-@cindex exception handling
-@findex EDGE_ABNORMAL, EDGE_EH
-Exception handling edges represent possible control transfers from a
-trapping instruction to an exception handler. The definition of
-``trapping'' varies. In C++, only function calls can throw, but for
-Ada exceptions like division by zero or segmentation fault are
-defined and thus each instruction possibly throwing this kind of
-exception needs to be handled as control flow instruction. Exception
-edges have the @code{EDGE_ABNORMAL} and @code{EDGE_EH} flags set.
-
-@findex purge_dead_edges
-When updating the instruction stream it is easy to change possibly
-trapping instruction to non-trapping, by simply removing the exception
-edge. The opposite conversion is difficult, but should not happen
-anyway. The edges can be eliminated via @code{purge_dead_edges} call.
-
-@findex REG_EH_REGION, EDGE_ABNORMAL_CALL
-In the RTL representation, the destination of an exception edge is
-specified by @code{REG_EH_REGION} note attached to the insn.
-In case of a trapping call the @code{EDGE_ABNORMAL_CALL} flag is set
-too. In the @code{GIMPLE} representation, this extra flag is not set.
-
-@findex may_trap_p, tree_could_trap_p
-In the RTL representation, the predicate @code{may_trap_p} may be used
-to check whether instruction still may trap or not. For the tree
-representation, the @code{tree_could_trap_p} predicate is available,
-but this predicate only checks for possible memory traps, as in
-dereferencing an invalid pointer location.
-
-
-@item sibling calls
-@cindex sibling call
-@findex EDGE_ABNORMAL, EDGE_SIBCALL
-Sibling calls or tail calls terminate the function in a non-standard
-way and thus an edge to the exit must be present.
-@code{EDGE_SIBCALL} and @code{EDGE_ABNORMAL} are set in such case.
-These edges only exist in the RTL representation.
-
-@item computed jumps
-@cindex computed jump
-@findex EDGE_ABNORMAL
-Computed jumps contain edges to all labels in the function referenced
-from the code. All those edges have @code{EDGE_ABNORMAL} flag set.
-The edges used to represent computed jumps often cause compile time
-performance problems, since functions consisting of many taken labels
-and many computed jumps may have @emph{very} dense flow graphs, so
-these edges need to be handled with special care. During the earlier
-stages of the compilation process, GCC tries to avoid such dense flow
-graphs by factoring computed jumps. For example, given the following
-series of jumps,
-
-@smallexample
- goto *x;
- [ @dots{} ]
-
- goto *x;
- [ @dots{} ]
-
- goto *x;
- [ @dots{} ]
-@end smallexample
-
-@noindent
-factoring the computed jumps results in the following code sequence
-which has a much simpler flow graph:
-
-@smallexample
- goto y;
- [ @dots{} ]
-
- goto y;
- [ @dots{} ]
-
- goto y;
- [ @dots{} ]
-
-y:
- goto *x;
-@end smallexample
-
-@findex pass_duplicate_computed_gotos
-However, the classic problem with this transformation is that it has a
-runtime cost in there resulting code: An extra jump. Therefore, the
-computed jumps are un-factored in the later passes of the compiler
-(in the pass called @code{pass_duplicate_computed_gotos}).
-Be aware of that when you work on passes in that area. There have
-been numerous examples already where the compile time for code with
-unfactored computed jumps caused some serious headaches.
-
-@item nonlocal goto handlers
-@cindex nonlocal goto handler
-@findex EDGE_ABNORMAL, EDGE_ABNORMAL_CALL
-GCC allows nested functions to return into caller using a @code{goto}
-to a label passed to as an argument to the callee. The labels passed
-to nested functions contain special code to cleanup after function
-call. Such sections of code are referred to as ``nonlocal goto
-receivers''. If a function contains such nonlocal goto receivers, an
-edge from the call to the label is created with the
-@code{EDGE_ABNORMAL} and @code{EDGE_ABNORMAL_CALL} flags set.
-
-@item function entry points
-@cindex function entry point, alternate function entry point
-@findex LABEL_ALTERNATE_NAME
-By definition, execution of function starts at basic block 0, so there
-is always an edge from the @code{ENTRY_BLOCK_PTR} to basic block 0.
-There is no @code{GIMPLE} representation for alternate entry points at
-this moment. In RTL, alternate entry points are specified by
-@code{CODE_LABEL} with @code{LABEL_ALTERNATE_NAME} defined. This
-feature is currently used for multiple entry point prologues and is
-limited to post-reload passes only. This can be used by back-ends to
-emit alternate prologues for functions called from different contexts.
-In future full support for multiple entry functions defined by Fortran
-90 needs to be implemented.
-
-@item function exits
-In the pre-reload representation a function terminates after the last
-instruction in the insn chain and no explicit return instructions are
-used. This corresponds to the fall-thru edge into exit block. After
-reload, optimal RTL epilogues are used that use explicit (conditional)
-return instructions that are represented by edges with no flags set.
-
-@end table
-
-
-@node Profile information
-@section Profile information
-
-@cindex profile representation
-In many cases a compiler must make a choice whether to trade speed in
-one part of code for speed in another, or to trade code size for code
-speed. In such cases it is useful to know information about how often
-some given block will be executed. That is the purpose for
-maintaining profile within the flow graph.
-GCC can handle profile information obtained through @dfn{profile
-feedback}, but it can also estimate branch probabilities based on
-statics and heuristics.
-
-@cindex profile feedback
-The feedback based profile is produced by compiling the program with
-instrumentation, executing it on a train run and reading the numbers
-of executions of basic blocks and edges back to the compiler while
-re-compiling the program to produce the final executable. This method
-provides very accurate information about where a program spends most
-of its time on the train run. Whether it matches the average run of
-course depends on the choice of train data set, but several studies
-have shown that the behavior of a program usually changes just
-marginally over different data sets.
-
-@cindex Static profile estimation
-@cindex branch prediction
-@findex predict.def
-When profile feedback is not available, the compiler may be asked to
-attempt to predict the behavior of each branch in the program using a
-set of heuristics (see @file{predict.def} for details) and compute
-estimated frequencies of each basic block by propagating the
-probabilities over the graph.
-
-@findex frequency, count, BB_FREQ_BASE
-Each @code{basic_block} contains two integer fields to represent
-profile information: @code{frequency} and @code{count}. The
-@code{frequency} is an estimation how often is basic block executed
-within a function. It is represented as an integer scaled in the
-range from 0 to @code{BB_FREQ_BASE}. The most frequently executed
-basic block in function is initially set to @code{BB_FREQ_BASE} and
-the rest of frequencies are scaled accordingly. During optimization,
-the frequency of the most frequent basic block can both decrease (for
-instance by loop unrolling) or grow (for instance by cross-jumping
-optimization), so scaling sometimes has to be performed multiple
-times.
-
-@findex gcov_type
-The @code{count} contains hard-counted numbers of execution measured
-during training runs and is nonzero only when profile feedback is
-available. This value is represented as the host's widest integer
-(typically a 64 bit integer) of the special type @code{gcov_type}.
-
-Most optimization passes can use only the frequency information of a
-basic block, but a few passes may want to know hard execution counts.
-The frequencies should always match the counts after scaling, however
-during updating of the profile information numerical error may
-accumulate into quite large errors.
-
-@findex REG_BR_PROB_BASE, EDGE_FREQUENCY
-Each edge also contains a branch probability field: an integer in the
-range from 0 to @code{REG_BR_PROB_BASE}. It represents probability of
-passing control from the end of the @code{src} basic block to the
-@code{dest} basic block, i.e.@: the probability that control will flow
-along this edge. The @code{EDGE_FREQUENCY} macro is available to
-compute how frequently a given edge is taken. There is a @code{count}
-field for each edge as well, representing same information as for a
-basic block.
-
-The basic block frequencies are not represented in the instruction
-stream, but in the RTL representation the edge frequencies are
-represented for conditional jumps (via the @code{REG_BR_PROB}
-macro) since they are used when instructions are output to the
-assembly file and the flow graph is no longer maintained.
-
-@cindex reverse probability
-The probability that control flow arrives via a given edge to its
-destination basic block is called @dfn{reverse probability} and is not
-directly represented, but it may be easily computed from frequencies
-of basic blocks.
-
-@findex redirect_edge_and_branch
-Updating profile information is a delicate task that can unfortunately
-not be easily integrated with the CFG manipulation API@. Many of the
-functions and hooks to modify the CFG, such as
-@code{redirect_edge_and_branch}, do not have enough information to
-easily update the profile, so updating it is in the majority of cases
-left up to the caller. It is difficult to uncover bugs in the profile
-updating code, because they manifest themselves only by producing
-worse code, and checking profile consistency is not possible because
-of numeric error accumulation. Hence special attention needs to be
-given to this issue in each pass that modifies the CFG@.
-
-@findex REG_BR_PROB_BASE, BB_FREQ_BASE, count
-It is important to point out that @code{REG_BR_PROB_BASE} and
-@code{BB_FREQ_BASE} are both set low enough to be possible to compute
-second power of any frequency or probability in the flow graph, it is
-not possible to even square the @code{count} field, as modern CPUs are
-fast enough to execute $2^32$ operations quickly.
-
-
-@node Maintaining the CFG
-@section Maintaining the CFG
-@findex cfghooks.h
-
-An important task of each compiler pass is to keep both the control
-flow graph and all profile information up-to-date. Reconstruction of
-the control flow graph after each pass is not an option, since it may be
-very expensive and lost profile information cannot be reconstructed at
-all.
-
-GCC has two major intermediate representations, and both use the
-@code{basic_block} and @code{edge} data types to represent control
-flow. Both representations share as much of the CFG maintenance code
-as possible. For each representation, a set of @dfn{hooks} is defined
-so that each representation can provide its own implementation of CFG
-manipulation routines when necessary. These hooks are defined in
-@file{cfghooks.h}. There are hooks for almost all common CFG
-manipulations, including block splitting and merging, edge redirection
-and creating and deleting basic blocks. These hooks should provide
-everything you need to maintain and manipulate the CFG in both the RTL
-and @code{GIMPLE} representation.
-
-At the moment, the basic block boundaries are maintained transparently
-when modifying instructions, so there rarely is a need to move them
-manually (such as in case someone wants to output instruction outside
-basic block explicitly).
-
-@findex BLOCK_FOR_INSN, gimple_bb
-In the RTL representation, each instruction has a
-@code{BLOCK_FOR_INSN} value that represents pointer to the basic block
-that contains the instruction. In the @code{GIMPLE} representation, the
-function @code{gimple_bb} returns a pointer to the basic block
-containing the queried statement.
-
-@cindex GIMPLE statement iterators
-When changes need to be applied to a function in its @code{GIMPLE}
-representation, @dfn{GIMPLE statement iterators} should be used. These
-iterators provide an integrated abstraction of the flow graph and the
-instruction stream. Block statement iterators are constructed using
-the @code{gimple_stmt_iterator} data structure and several modifiers are
-available, including the following:
-
-@ftable @code
-@item gsi_start
-This function initializes a @code{gimple_stmt_iterator} that points to
-the first non-empty statement in a basic block.
-
-@item gsi_last
-This function initializes a @code{gimple_stmt_iterator} that points to
-the last statement in a basic block.
-
-@item gsi_end_p
-This predicate is @code{true} if a @code{gimple_stmt_iterator}
-represents the end of a basic block.
-
-@item gsi_next
-This function takes a @code{gimple_stmt_iterator} and makes it point to
-its successor.
-
-@item gsi_prev
-This function takes a @code{gimple_stmt_iterator} and makes it point to
-its predecessor.
-
-@item gsi_insert_after
-This function inserts a statement after the @code{gimple_stmt_iterator}
-passed in. The final parameter determines whether the statement
-iterator is updated to point to the newly inserted statement, or left
-pointing to the original statement.
-
-@item gsi_insert_before
-This function inserts a statement before the @code{gimple_stmt_iterator}
-passed in. The final parameter determines whether the statement
-iterator is updated to point to the newly inserted statement, or left
-pointing to the original statement.
-
-@item gsi_remove
-This function removes the @code{gimple_stmt_iterator} passed in and
-rechains the remaining statements in a basic block, if any.
-@end ftable
-
-@findex BB_HEAD, BB_END
-In the RTL representation, the macros @code{BB_HEAD} and @code{BB_END}
-may be used to get the head and end @code{rtx} of a basic block. No
-abstract iterators are defined for traversing the insn chain, but you
-can just use @code{NEXT_INSN} and @code{PREV_INSN} instead. @xref{Insns}.
-
-@findex purge_dead_edges
-Usually a code manipulating pass simplifies the instruction stream and
-the flow of control, possibly eliminating some edges. This may for
-example happen when a conditional jump is replaced with an
-unconditional jump. Updating of edges
-is not transparent and each optimization pass is required to do so
-manually. However only few cases occur in practice. The pass may
-call @code{purge_dead_edges} on a given basic block to remove
-superfluous edges, if any.
-
-@findex redirect_edge_and_branch, redirect_jump
-Another common scenario is redirection of branch instructions, but
-this is best modeled as redirection of edges in the control flow graph
-and thus use of @code{redirect_edge_and_branch} is preferred over more
-low level functions, such as @code{redirect_jump} that operate on RTL
-chain only. The CFG hooks defined in @file{cfghooks.h} should provide
-the complete API required for manipulating and maintaining the CFG@.
-
-@findex split_block
-It is also possible that a pass has to insert control flow instruction
-into the middle of a basic block, thus creating an entry point in the
-middle of the basic block, which is impossible by definition: The
-block must be split to make sure it only has one entry point, i.e.@: the
-head of the basic block. The CFG hook @code{split_block} may be used
-when an instruction in the middle of a basic block has to become the
-target of a jump or branch instruction.
-
-@findex insert_insn_on_edge
-@findex commit_edge_insertions
-@findex gsi_insert_on_edge
-@findex gsi_commit_edge_inserts
-@cindex edge splitting
-For a global optimizer, a common operation is to split edges in the
-flow graph and insert instructions on them. In the RTL
-representation, this can be easily done using the
-@code{insert_insn_on_edge} function that emits an instruction
-``on the edge'', caching it for a later @code{commit_edge_insertions}
-call that will take care of moving the inserted instructions off the
-edge into the instruction stream contained in a basic block. This
-includes the creation of new basic blocks where needed. In the
-@code{GIMPLE} representation, the equivalent functions are
-@code{gsi_insert_on_edge} which inserts a block statement
-iterator on an edge, and @code{gsi_commit_edge_inserts} which flushes
-the instruction to actual instruction stream.
-
-@findex verify_flow_info
-@cindex CFG verification
-While debugging the optimization pass, the @code{verify_flow_info}
-function may be useful to find bugs in the control flow graph updating
-code.
-
-
-@node Liveness information
-@section Liveness information
-@cindex Liveness representation
-Liveness information is useful to determine whether some register is
-``live'' at given point of program, i.e.@: that it contains a value that
-may be used at a later point in the program. This information is
-used, for instance, during register allocation, as the pseudo
-registers only need to be assigned to a unique hard register or to a
-stack slot if they are live. The hard registers and stack slots may
-be freely reused for other values when a register is dead.
-
-Liveness information is available in the back end starting with
-@code{pass_df_initialize} and ending with @code{pass_df_finish}. Three
-flavors of live analysis are available: With @code{LR}, it is possible
-to determine at any point @code{P} in the function if the register may be
-used on some path from @code{P} to the end of the function. With
-@code{UR}, it is possible to determine if there is a path from the
-beginning of the function to @code{P} that defines the variable.
-@code{LIVE} is the intersection of the @code{LR} and @code{UR} and a
-variable is live at @code{P} if there is both an assignment that reaches
-it from the beginning of the function and a use that can be reached on
-some path from @code{P} to the end of the function.
-
-In general @code{LIVE} is the most useful of the three. The macros
-@code{DF_[LR,UR,LIVE]_[IN,OUT]} can be used to access this information.
-The macros take a basic block number and return a bitmap that is indexed
-by the register number. This information is only guaranteed to be up to
-date after calls are made to @code{df_analyze}. See the file
-@code{df-core.cc} for details on using the dataflow.
-
-
-@findex REG_DEAD, REG_UNUSED
-The liveness information is stored partly in the RTL instruction stream
-and partly in the flow graph. Local information is stored in the
-instruction stream: Each instruction may contain @code{REG_DEAD} notes
-representing that the value of a given register is no longer needed, or
-@code{REG_UNUSED} notes representing that the value computed by the
-instruction is never used. The second is useful for instructions
-computing multiple values at once.
-
+++ /dev/null
-@c Copyright (C) 1988-2022 Free Software Foundation, Inc.
-@c This is part of the GCC manual.
-@c For copying conditions, see the file gcc.texi.
-
-@node Collect2
-@chapter @code{collect2}
-
-GCC uses a utility called @code{collect2} on nearly all systems to arrange
-to call various initialization functions at start time.
-
-The program @code{collect2} works by linking the program once and
-looking through the linker output file for symbols with particular names
-indicating they are constructor functions. If it finds any, it
-creates a new temporary @samp{.c} file containing a table of them,
-compiles it, and links the program a second time including that file.
-
-@findex __main
-@cindex constructors, automatic calls
-The actual calls to the constructors are carried out by a subroutine
-called @code{__main}, which is called (automatically) at the beginning
-of the body of @code{main} (provided @code{main} was compiled with GNU
-CC)@. Calling @code{__main} is necessary, even when compiling C code, to
-allow linking C and C++ object code together. (If you use
-@option{-nostdlib}, you get an unresolved reference to @code{__main},
-since it's defined in the standard GCC library. Include @option{-lgcc} at
-the end of your compiler command line to resolve this reference.)
-
-The program @code{collect2} is installed as @code{ld} in the directory
-where the passes of the compiler are installed. When @code{collect2}
-needs to find the @emph{real} @code{ld}, it tries the following file
-names:
-
-@itemize @bullet
-@item
-a hard coded linker file name, if GCC was configured with the
-@option{--with-ld} option.
-
-@item
-@file{real-ld} in the directories listed in the compiler's search
-directories.
-
-@item
-@file{real-ld} in the directories listed in the environment variable
-@code{PATH}.
-
-@item
-The file specified in the @code{REAL_LD_FILE_NAME} configuration macro,
-if specified.
-
-@item
-@file{ld} in the compiler's search directories, except that
-@code{collect2} will not execute itself recursively.
-
-@item
-@file{ld} in @code{PATH}.
-@end itemize
-
-``The compiler's search directories'' means all the directories where
-@command{gcc} searches for passes of the compiler. This includes
-directories that you specify with @option{-B}.
-
-Cross-compilers search a little differently:
-
-@itemize @bullet
-@item
-@file{real-ld} in the compiler's search directories.
-
-@item
-@file{@var{target}-real-ld} in @code{PATH}.
-
-@item
-The file specified in the @code{REAL_LD_FILE_NAME} configuration macro,
-if specified.
-
-@item
-@file{ld} in the compiler's search directories.
-
-@item
-@file{@var{target}-ld} in @code{PATH}.
-@end itemize
-
-@code{collect2} explicitly avoids running @code{ld} using the file name
-under which @code{collect2} itself was invoked. In fact, it remembers
-up a list of such names---in case one copy of @code{collect2} finds
-another copy (or version) of @code{collect2} installed as @code{ld} in a
-second place in the search path.
-
-@code{collect2} searches for the utilities @code{nm} and @code{strip}
-using the same algorithm as above for @code{ld}.
+++ /dev/null
-@c Copyright (C) 2002-2022 Free Software Foundation, Inc.
-@c This is part of the GCC manual.
-@c For copying conditions, see the file gcc.texi.
-
-@node Compatibility
-@chapter Binary Compatibility
-@cindex binary compatibility
-@cindex ABI
-@cindex application binary interface
-
-Binary compatibility encompasses several related concepts:
-
-@table @dfn
-@item application binary interface (ABI)
-The set of runtime conventions followed by all of the tools that deal
-with binary representations of a program, including compilers, assemblers,
-linkers, and language runtime support.
-Some ABIs are formal with a written specification, possibly designed
-by multiple interested parties. Others are simply the way things are
-actually done by a particular set of tools.
-
-@item ABI conformance
-A compiler conforms to an ABI if it generates code that follows all of
-the specifications enumerated by that ABI@.
-A library conforms to an ABI if it is implemented according to that ABI@.
-An application conforms to an ABI if it is built using tools that conform
-to that ABI and does not contain source code that specifically changes
-behavior specified by the ABI@.
-
-@item calling conventions
-Calling conventions are a subset of an ABI that specify of how arguments
-are passed and function results are returned.
-
-@item interoperability
-Different sets of tools are interoperable if they generate files that
-can be used in the same program. The set of tools includes compilers,
-assemblers, linkers, libraries, header files, startup files, and debuggers.
-Binaries produced by different sets of tools are not interoperable unless
-they implement the same ABI@. This applies to different versions of the
-same tools as well as tools from different vendors.
-
-@item intercallability
-Whether a function in a binary built by one set of tools can call a
-function in a binary built by a different set of tools is a subset
-of interoperability.
-
-@item implementation-defined features
-Language standards include lists of implementation-defined features whose
-behavior can vary from one implementation to another. Some of these
-features are normally covered by a platform's ABI and others are not.
-The features that are not covered by an ABI generally affect how a
-program behaves, but not intercallability.
-
-@item compatibility
-Conformance to the same ABI and the same behavior of implementation-defined
-features are both relevant for compatibility.
-@end table
-
-The application binary interface implemented by a C or C++ compiler
-affects code generation and runtime support for:
-
-@itemize @bullet
-@item
-size and alignment of data types
-@item
-layout of structured types
-@item
-calling conventions
-@item
-register usage conventions
-@item
-interfaces for runtime arithmetic support
-@item
-object file formats
-@end itemize
-
-In addition, the application binary interface implemented by a C++ compiler
-affects code generation and runtime support for:
-@itemize @bullet
-@item
-name mangling
-@item
-exception handling
-@item
-invoking constructors and destructors
-@item
-layout, alignment, and padding of classes
-@item
-layout and alignment of virtual tables
-@end itemize
-
-Some GCC compilation options cause the compiler to generate code that
-does not conform to the platform's default ABI@. Other options cause
-different program behavior for implementation-defined features that are
-not covered by an ABI@. These options are provided for consistency with
-other compilers that do not follow the platform's default ABI or the
-usual behavior of implementation-defined features for the platform.
-Be very careful about using such options.
-
-Most platforms have a well-defined ABI that covers C code, but ABIs
-that cover C++ functionality are not yet common.
-
-Starting with GCC 3.2, GCC binary conventions for C++ are based on a
-written, vendor-neutral C++ ABI that was designed to be specific to
-64-bit Itanium but also includes generic specifications that apply to
-any platform.
-This C++ ABI is also implemented by other compiler vendors on some
-platforms, notably GNU/Linux and BSD systems.
-We have tried hard to provide a stable ABI that will be compatible with
-future GCC releases, but it is possible that we will encounter problems
-that make this difficult. Such problems could include different
-interpretations of the C++ ABI by different vendors, bugs in the ABI, or
-bugs in the implementation of the ABI in different compilers.
-GCC's @option{-Wabi} switch warns when G++ generates code that is
-probably not compatible with the C++ ABI@.
-
-The C++ library used with a C++ compiler includes the Standard C++
-Library, with functionality defined in the C++ Standard, plus language
-runtime support. The runtime support is included in a C++ ABI, but there
-is no formal ABI for the Standard C++ Library. Two implementations
-of that library are interoperable if one follows the de-facto ABI of the
-other and if they are both built with the same compiler, or with compilers
-that conform to the same ABI for C++ compiler and runtime support.
-
-When G++ and another C++ compiler conform to the same C++ ABI, but the
-implementations of the Standard C++ Library that they normally use do not
-follow the same ABI for the Standard C++ Library, object files built with
-those compilers can be used in the same program only if they use the same
-C++ library. This requires specifying the location of the C++ library
-header files when invoking the compiler whose usual library is not being
-used. The location of GCC's C++ header files depends on how the GCC
-build was configured, but can be seen by using the G++ @option{-v} option.
-With default configuration options for G++ 3.3 the compile line for a
-different C++ compiler needs to include
-
-@smallexample
- -I@var{gcc_install_directory}/include/c++/3.3
-@end smallexample
-
-Similarly, compiling code with G++ that must use a C++ library other
-than the GNU C++ library requires specifying the location of the header
-files for that other library.
-
-The most straightforward way to link a program to use a particular
-C++ library is to use a C++ driver that specifies that C++ library by
-default. The @command{g++} driver, for example, tells the linker where
-to find GCC's C++ library (@file{libstdc++}) plus the other libraries
-and startup files it needs, in the proper order.
-
-If a program must use a different C++ library and it's not possible
-to do the final link using a C++ driver that uses that library by default,
-it is necessary to tell @command{g++} the location and name of that
-library. It might also be necessary to specify different startup files
-and other runtime support libraries, and to suppress the use of GCC's
-support libraries with one or more of the options @option{-nostdlib},
-@option{-nostartfiles}, and @option{-nodefaultlibs}.
+++ /dev/null
-@c Copyright (C) 1988-2022 Free Software Foundation, Inc.
-@c This is part of the GCC manual.
-@c For copying conditions, see the file gcc.texi.
-
-@node Configuration Files
-@subsubsection Files Created by @code{configure}
-
-Here we spell out what files will be set up by @file{configure} in the
-@file{gcc} directory. Some other files are created as temporary files
-in the configuration process, and are not used in the subsequent
-build; these are not documented.
-
-@itemize @bullet
-@item
-@file{Makefile} is constructed from @file{Makefile.in}, together with
-the host and target fragments (@pxref{Fragments, , Makefile
-Fragments}) @file{t-@var{target}} and @file{x-@var{host}} from
-@file{config}, if any, and language Makefile fragments
-@file{@var{language}/Make-lang.in}.
-@item
-@file{auto-host.h} contains information about the host machine
-determined by @file{configure}. If the host machine is different from
-the build machine, then @file{auto-build.h} is also created,
-containing such information about the build machine.
-@item
-@file{config.status} is a script that may be run to recreate the
-current configuration.
-@item
-@file{configargs.h} is a header containing details of the arguments
-passed to @file{configure} to configure GCC, and of the thread model
-used.
-@item
-@file{cstamp-h} is used as a timestamp.
-@item
-If a language @file{config-lang.in} file (@pxref{Front End Config, ,
-The Front End @file{config-lang.in} File}) sets @code{outputs}, then
-the files listed in @code{outputs} there are also generated.
-@end itemize
-
-The following configuration headers are created from the Makefile,
-using @file{mkconfig.sh}, rather than directly by @file{configure}.
-@file{config.h}, @file{bconfig.h} and @file{tconfig.h} all contain the
-@file{xm-@var{machine}.h} header, if any, appropriate to the host,
-build and target machines respectively, the configuration headers for
-the target, and some definitions; for the host and build machines,
-these include the autoconfigured headers generated by
-@file{configure}. The other configuration headers are determined by
-@file{config.gcc}. They also contain the typedefs for @code{rtx},
-@code{rtvec} and @code{tree}.
-
-@itemize @bullet
-@item
-@file{config.h}, for use in programs that run on the host machine.
-@item
-@file{bconfig.h}, for use in programs that run on the build machine.
-@item
-@file{tconfig.h}, for use in programs and libraries for the target
-machine.
-@item
-@file{tm_p.h}, which includes the header @file{@var{machine}-protos.h}
-that contains prototypes for functions in the target
-@file{@var{machine}.c} file. The
-@file{@var{machine}-protos.h} header is included after the @file{rtl.h}
-and/or @file{tree.h} would have been included.
-The @file{tm_p.h} also
-includes the header @file{tm-preds.h} which is generated by
-@file{genpreds} program during the build to define the declarations
-and inline functions for the predicate functions.
-@end itemize
+++ /dev/null
-@c Copyright (C) 2001-2022 Free Software Foundation, Inc.
-@c This is part of the GCC manual.
-@c For copying conditions, see the file gcc.texi.
-
-@node Configure Terms
-@section Configure Terms and History
-@cindex configure terms
-@cindex canadian
-
-The configure and build process has a long and colorful history, and can
-be confusing to anyone who doesn't know why things are the way they are.
-While there are other documents which describe the configuration process
-in detail, here are a few things that everyone working on GCC should
-know.
-
-There are three system names that the build knows about: the machine you
-are building on (@dfn{build}), the machine that you are building for
-(@dfn{host}), and the machine that GCC will produce code for
-(@dfn{target}). When you configure GCC, you specify these with
-@option{--build=}, @option{--host=}, and @option{--target=}.
-
-Specifying the host without specifying the build should be avoided, as
-@command{configure} may (and once did) assume that the host you specify
-is also the build, which may not be true.
-
-If build, host, and target are all the same, this is called a
-@dfn{native}. If build and host are the same but target is different,
-this is called a @dfn{cross}. If build, host, and target are all
-different this is called a @dfn{canadian} (for obscure reasons dealing
-with Canada's political party and the background of the person working
-on the build at that time). If host and target are the same, but build
-is different, you are using a cross-compiler to build a native for a
-different system. Some people call this a @dfn{host-x-host},
-@dfn{crossed native}, or @dfn{cross-built native}. If build and target
-are the same, but host is different, you are using a cross compiler to
-build a cross compiler that produces code for the machine you're
-building on. This is rare, so there is no common way of describing it.
-There is a proposal to call this a @dfn{crossback}.
-
-If build and host are the same, the GCC you are building will also be
-used to build the target libraries (like @code{libstdc++}). If build and host
-are different, you must have already built and installed a cross
-compiler that will be used to build the target libraries (if you
-configured with @option{--target=foo-bar}, this compiler will be called
-@command{foo-bar-gcc}).
-
-In the case of target libraries, the machine you're building for is the
-machine you specified with @option{--target}. So, build is the machine
-you're building on (no change there), host is the machine you're
-building for (the target libraries are built for the target, so host is
-the target you specified), and target doesn't apply (because you're not
-building a compiler, you're building libraries). The configure/make
-process will adjust these variables as needed. It also sets
-@code{$with_cross_host} to the original @option{--host} value in case you
-need it.
-
-The @code{libiberty} support library is built up to three times: once
-for the host, once for the target (even if they are the same), and once
-for the build if build and host are different. This allows it to be
-used by all programs which are generated in the course of the build
-process.
+++ /dev/null
-@c Copyright (C) 1988-2022 Free Software Foundation, Inc.
-@c This is part of the GCC manual.
-@c For copying conditions, see the file gcc.texi.
-
-@node Contributors
-@unnumbered Contributors to GCC
-@cindex contributors
-
-The GCC project would like to thank its many contributors. Without them the
-project would not have been nearly as successful as it has been. Any omissions
-in this list are accidental. Feel free to contact
-@email{law@@redhat.com} or @email{gerald@@pfeifer.com} if you have been left
-out or some of your contributions are not listed. Please keep this list in
-alphabetical order.
-
-@itemize @bullet
-
-@item
-Analog Devices helped implement the support for complex data types
-and iterators.
-
-@item
-John David Anglin for threading-related fixes and improvements to
-libstdc++-v3, and the HP-UX port.
-
-@item
-James van Artsdalen wrote the code that makes efficient use of
-the Intel 80387 register stack.
-
-@item
-Abramo and Roberto Bagnara for the SysV68 Motorola 3300 Delta Series
-port.
-
-@item
-Alasdair Baird for various bug fixes.
-
-@item
-Giovanni Bajo for analyzing lots of complicated C++ problem reports.
-
-@item
-Peter Barada for his work to improve code generation for new
-ColdFire cores.
-
-@item
-Gerald Baumgartner added the signature extension to the C++ front end.
-
-@item
-Godmar Back for his Java improvements and encouragement.
-
-@item
-Scott Bambrough for help porting the Java compiler.
-
-@item
-Wolfgang Bangerth for processing tons of bug reports.
-
-@item
-Jon Beniston for his Microsoft Windows port of Java and port to Lattice Mico32.
-
-@item
-Daniel Berlin for better DWARF 2 support, faster/better optimizations,
-improved alias analysis, plus migrating GCC to Bugzilla.
-
-@item
-Geoff Berry for his Java object serialization work and various patches.
-
-@item
-David Binderman tests weekly snapshots of GCC trunk against Fedora Rawhide
-for several architectures.
-
-@item
-Laurynas Biveinis for memory management work and DJGPP port fixes.
-
-@item
-Uros Bizjak for the implementation of x87 math built-in functions and
-for various middle end and i386 back end improvements and bug fixes.
-
-@item
-Eric Blake for helping to make GCJ and libgcj conform to the
-specifications.
-
-@item
-Janne Blomqvist for contributions to GNU Fortran.
-
-@item
-Hans-J. Boehm for his garbage collector, IA-64 libffi port, and other
-Java work.
-
-@item
-Segher Boessenkool for helping maintain the PowerPC port and the
-instruction combiner plus various contributions to the middle end.
-
-@item
-Neil Booth for work on cpplib, lang hooks, debug hooks and other
-miscellaneous clean-ups.
-
-@item
-Steven Bosscher for integrating the GNU Fortran front end into GCC and for
-contributing to the tree-ssa branch.
-
-@item
-Eric Botcazou for fixing middle- and backend bugs left and right.
-
-@item
-Per Bothner for his direction via the steering committee and various
-improvements to the infrastructure for supporting new languages. Chill
-front end implementation. Initial implementations of
-cpplib, fix-header, config.guess, libio, and past C++ library (libg++)
-maintainer. Dreaming up, designing and implementing much of GCJ@.
-
-@item
-Devon Bowen helped port GCC to the Tahoe.
-
-@item
-Don Bowman for mips-vxworks contributions.
-
-@item
-James Bowman for the FT32 port.
-
-@item
-Dave Brolley for work on cpplib and Chill.
-
-@item
-Paul Brook for work on the ARM architecture and maintaining GNU Fortran.
-
-@item
-Robert Brown implemented the support for Encore 32000 systems.
-
-@item
-Christian Bruel for improvements to local store elimination.
-
-@item
-Herman A.J. ten Brugge for various fixes.
-
-@item
-Joerg Brunsmann for Java compiler hacking and help with the GCJ FAQ@.
-
-@item
-Joe Buck for his direction via the steering committee from its creation
-to 2013.
-
-@item
-Iain Buclaw for the D frontend.
-
-@item
-Craig Burley for leadership of the G77 Fortran effort.
-
-@item
-Tobias Burnus for contributions to GNU Fortran.
-
-@item
-Stephan Buys for contributing Doxygen notes for libstdc++.
-
-@item
-Paolo Carlini for libstdc++ work: lots of efficiency improvements to
-the C++ strings, streambufs and formatted I/O, hard detective work on
-the frustrating localization issues, and keeping up with the problem reports.
-
-@item
-John Carr for his alias work, SPARC hacking, infrastructure improvements,
-previous contributions to the steering committee, loop optimizations, etc.
-
-@item
-Stephane Carrez for 68HC11 and 68HC12 ports.
-
-@item
-Steve Chamberlain for support for the Renesas SH and H8 processors
-and the PicoJava processor, and for GCJ config fixes.
-
-@item
-Glenn Chambers for help with the GCJ FAQ@.
-
-@item
-John-Marc Chandonia for various libgcj patches.
-
-@item
-Denis Chertykov for contributing and maintaining the AVR port, the first GCC port
-for an 8-bit architecture.
-
-@item
-Kito Cheng for his work on the RISC-V port, including bringing up the test
-suite and maintenance.
-
-@item
-Scott Christley for his Objective-C contributions.
-
-@item
-Eric Christopher for his Java porting help and clean-ups.
-
-@item
-Branko Cibej for more warning contributions.
-
-@item
-The @uref{https://www.gnu.org/software/classpath/,,GNU Classpath project}
-for all of their merged runtime code.
-
-@item
-Nick Clifton for arm, mcore, fr30, v850, m32r, msp430 rx work,
-@option{--help}, and other random hacking.
-
-@item
-Michael Cook for libstdc++ cleanup patches to reduce warnings.
-
-@item
-R. Kelley Cook for making GCC buildable from a read-only directory as
-well as other miscellaneous build process and documentation clean-ups.
-
-@item
-Ralf Corsepius for SH testing and minor bug fixing.
-
-@item
-Fran@,{c}ois-Xavier Coudert for contributions to GNU Fortran.
-
-@item
-Stan Cox for care and feeding of the x86 port and lots of behind
-the scenes hacking.
-
-@item
-Alex Crain provided changes for the 3b1.
-
-@item
-Ian Dall for major improvements to the NS32k port.
-
-@item
-Paul Dale for his work to add uClinux platform support to the
-m68k backend.
-
-@item
-Palmer Dabbelt for his work maintaining the RISC-V port.
-
-@item
-Dario Dariol contributed the four varieties of sample programs
-that print a copy of their source.
-
-@item
-Russell Davidson for fstream and stringstream fixes in libstdc++.
-
-@item
-Bud Davis for work on the G77 and GNU Fortran compilers.
-
-@item
-Mo DeJong for GCJ and libgcj bug fixes.
-
-@item
-Jerry DeLisle for contributions to GNU Fortran.
-
-@item
-DJ Delorie for the DJGPP port, build and libiberty maintenance,
-various bug fixes, and the M32C, MeP, MSP430, and RL78 ports.
-
-@item
-Arnaud Desitter for helping to debug GNU Fortran.
-
-@item
-Gabriel Dos Reis for contributions to G++, contributions and
-maintenance of GCC diagnostics infrastructure, libstdc++-v3,
-including @code{valarray<>}, @code{complex<>}, maintaining the numerics library
-(including that pesky @code{<limits>} :-) and keeping up-to-date anything
-to do with numbers.
-
-@item
-Ulrich Drepper for his work on glibc, testing of GCC using glibc, ISO C99
-support, CFG dumping support, etc., plus support of the C++ runtime
-libraries including for all kinds of C interface issues, contributing and
-maintaining @code{complex<>}, sanity checking and disbursement, configuration
-architecture, libio maintenance, and early math work.
-
-@item
-Fran@,{c}ois Dumont for his work on libstdc++-v3, especially maintaining and
-improving @code{debug-mode} and associative and unordered containers.
-
-@item
-Zdenek Dvorak for a new loop unroller and various fixes.
-
-@item
-Michael Eager for his work on the Xilinx MicroBlaze port.
-
-@item
-Richard Earnshaw for his ongoing work with the ARM@.
-
-@item
-David Edelsohn for his direction via the steering committee, ongoing work
-with the RS6000/PowerPC port, help cleaning up Haifa loop changes,
-doing the entire AIX port of libstdc++ with his bare hands, and for
-ensuring GCC properly keeps working on AIX@.
-
-@item
-Kevin Ediger for the floating point formatting of num_put::do_put in
-libstdc++.
-
-@item
-Phil Edwards for libstdc++ work including configuration hackery,
-documentation maintainer, chief breaker of the web pages, the occasional
-iostream bug fix, and work on shared library symbol versioning.
-
-@item
-Paul Eggert for random hacking all over GCC@.
-
-@item
-Mark Elbrecht for various DJGPP improvements, and for libstdc++
-configuration support for locales and fstream-related fixes.
-
-@item
-Vadim Egorov for libstdc++ fixes in strings, streambufs, and iostreams.
-
-@item
-Christian Ehrhardt for dealing with bug reports.
-
-@item
-Ben Elliston for his work to move the Objective-C runtime into its
-own subdirectory and for his work on autoconf.
-
-@item
-Revital Eres for work on the PowerPC 750CL port.
-
-@item
-Marc Espie for OpenBSD support.
-
-@item
-Doug Evans for much of the global optimization framework, arc, m32r,
-and SPARC work.
-
-@item
-Christopher Faylor for his work on the Cygwin port and for caring and
-feeding the gcc.gnu.org box and saving its users tons of spam.
-
-@item
-Fred Fish for BeOS support and Ada fixes.
-
-@item
-Ivan Fontes Garcia for the Portuguese translation of the GCJ FAQ@.
-
-@item
-Peter Gerwinski for various bug fixes and the Pascal front end.
-
-@item
-Kaveh R.@: Ghazi for his direction via the steering committee, amazing
-work to make @samp{-W -Wall -W* -Werror} useful, and
-testing GCC on a plethora of platforms. Kaveh extends his gratitude to
-the CAIP Center at Rutgers University for providing him with computing
-resources to work on Free Software from the late 1980s to 2010.
-
-@item
-John Gilmore for a donation to the FSF earmarked improving GNU Java.
-
-@item
-Judy Goldberg for c++ contributions.
-
-@item
-Torbjorn Granlund for various fixes and the c-torture testsuite,
-multiply- and divide-by-constant optimization, improved long long
-support, improved leaf function register allocation, and his direction
-via the steering committee.
-
-@item
-Jonny Grant for improvements to @code{collect2's} @option{--help} documentation.
-
-@item
-Anthony Green for his @option{-Os} contributions, the moxie port, and
-Java front end work.
-
-@item
-Stu Grossman for gdb hacking, allowing GCJ developers to debug Java code.
-
-@item
-Michael K. Gschwind contributed the port to the PDP-11.
-
-@item
-Richard Biener for his ongoing middle-end contributions and bug fixes
-and for release management.
-
-@item
-Ron Guilmette implemented the @command{protoize} and @command{unprotoize}
-tools, the support for DWARF 1 symbolic debugging information, and much of
-the support for System V Release 4. He has also worked heavily on the
-Intel 386 and 860 support.
-
-@item
-Sumanth Gundapaneni for contributing the CR16 port.
-
-@item
-Mostafa Hagog for Swing Modulo Scheduling (SMS) and post reload GCSE@.
-
-@item
-Bruno Haible for improvements in the runtime overhead for EH, new
-warnings and assorted bug fixes.
-
-@item
-Andrew Haley for his amazing Java compiler and library efforts.
-
-@item
-Chris Hanson assisted in making GCC work on HP-UX for the 9000 series 300.
-
-@item
-Michael Hayes for various thankless work he's done trying to get
-the c30/c40 ports functional. Lots of loop and unroll improvements and
-fixes.
-
-@item
-Dara Hazeghi for wading through myriads of target-specific bug reports.
-
-@item
-Kate Hedstrom for staking the G77 folks with an initial testsuite.
-
-@item
-Richard Henderson for his ongoing SPARC, alpha, ia32, and ia64 work, loop
-opts, and generally fixing lots of old problems we've ignored for
-years, flow rewrite and lots of further stuff, including reviewing
-tons of patches.
-
-@item
-Aldy Hernandez for working on the PowerPC port, SIMD support, and
-various fixes.
-
-@item
-Nobuyuki Hikichi of Software Research Associates, Tokyo, contributed
-the support for the Sony NEWS machine.
-
-@item
-Kazu Hirata for caring and feeding the Renesas H8/300 port and various fixes.
-
-@item
-Katherine Holcomb for work on GNU Fortran.
-
-@item
-Manfred Hollstein for his ongoing work to keep the m88k alive, lots
-of testing and bug fixing, particularly of GCC configury code.
-
-@item
-Steve Holmgren for MachTen patches.
-
-@item
-Mat Hostetter for work on the TILE-Gx and TILEPro ports.
-
-@item
-Jan Hubicka for his x86 port improvements.
-
-@item
-Falk Hueffner for working on C and optimization bug reports.
-
-@item
-Bernardo Innocenti for his m68k work, including merging of
-ColdFire improvements and uClinux support.
-
-@item
-Christian Iseli for various bug fixes.
-
-@item
-Kamil Iskra for general m68k hacking.
-
-@item
-Lee Iverson for random fixes and MIPS testing.
-
-@item
-Balaji V. Iyer for Cilk+ development and merging.
-
-@item
-Andreas Jaeger for testing and benchmarking of GCC and various bug fixes.
-
-@item
-Martin Jambor for his work on inter-procedural optimizations, the
-switch conversion pass, and scalar replacement of aggregates.
-
-@item
-Jakub Jelinek for his SPARC work and sibling call optimizations as well
-as lots of bug fixes and test cases, and for improving the Java build
-system.
-
-@item
-Janis Johnson for ia64 testing and fixes, her quality improvement
-sidetracks, and web page maintenance.
-
-@item
-Kean Johnston for SCO OpenServer support and various fixes.
-
-@item
-Tim Josling for the sample language treelang based originally on Richard
-Kenner's ``toy'' language.
-
-@item
-Nicolai Josuttis for additional libstdc++ documentation.
-
-@item
-Klaus Kaempf for his ongoing work to make alpha-vms a viable target.
-
-@item
-Steven G. Kargl for work on GNU Fortran.
-
-@item
-David Kashtan of SRI adapted GCC to VMS@.
-
-@item
-Ryszard Kabatek for many, many libstdc++ bug fixes and optimizations of
-strings, especially member functions, and for auto_ptr fixes.
-
-@item
-Geoffrey Keating for his ongoing work to make the PPC work for GNU/Linux
-and his automatic regression tester.
-
-@item
-Brendan Kehoe for his ongoing work with G++ and for a lot of early work
-in just about every part of libstdc++.
-
-@item
-Oliver M. Kellogg of Deutsche Aerospace contributed the port to the
-MIL-STD-1750A@.
-
-@item
-Richard Kenner of the New York University Ultracomputer Research
-Laboratory wrote the machine descriptions for the AMD 29000, the DEC
-Alpha, the IBM RT PC, and the IBM RS/6000 as well as the support for
-instruction attributes. He also made changes to better support RISC
-processors including changes to common subexpression elimination,
-strength reduction, function calling sequence handling, and condition
-code support, in addition to generalizing the code for frame pointer
-elimination and delay slot scheduling. Richard Kenner was also the
-head maintainer of GCC for several years.
-
-@item
-Mumit Khan for various contributions to the Cygwin and Mingw32 ports and
-maintaining binary releases for Microsoft Windows hosts, and for massive libstdc++
-porting work to Cygwin/Mingw32.
-
-@item
-Robin Kirkham for cpu32 support.
-
-@item
-Mark Klein for PA improvements.
-
-@item
-Thomas Koenig for various bug fixes.
-
-@item
-Bruce Korb for the new and improved fixincludes code.
-
-@item
-Benjamin Kosnik for his G++ work and for leading the libstdc++-v3 effort.
-
-@item
-Maxim Kuvyrkov for contributions to the instruction scheduler, the Android
-and m68k/Coldfire ports, and optimizations.
-
-@item
-Charles LaBrec contributed the support for the Integrated Solutions
-68020 system.
-
-@item
-Asher Langton and Mike Kumbera for contributing Cray pointer support
-to GNU Fortran, and for other GNU Fortran improvements.
-
-@item
-Jeff Law for his direction via the steering committee, coordinating the
-entire egcs project and GCC 2.95, rolling out snapshots and releases,
-handling merges from GCC2, reviewing tons of patches that might have
-fallen through the cracks else, and random but extensive hacking.
-
-@item
-Walter Lee for work on the TILE-Gx and TILEPro ports.
-
-@item
-Marc Lehmann for his direction via the steering committee and helping
-with analysis and improvements of x86 performance.
-
-@item
-Victor Leikehman for work on GNU Fortran.
-
-@item
-Ted Lemon wrote parts of the RTL reader and printer.
-
-@item
-Kriang Lerdsuwanakij for C++ improvements including template as template
-parameter support, and many C++ fixes.
-
-@item
-Warren Levy for tremendous work on libgcj (Java Runtime Library) and
-random work on the Java front end.
-
-@item
-Alain Lichnewsky ported GCC to the MIPS CPU@.
-
-@item
-Oskar Liljeblad for hacking on AWT and his many Java bug reports and
-patches.
-
-@item
-Robert Lipe for OpenServer support, new testsuites, testing, etc.
-
-@item
-Chen Liqin for various S+core related fixes/improvement, and for
-maintaining the S+core port.
-
-@item
-Martin Liska for his work on identical code folding, the sanitizers,
-HSA, general bug fixing and for running automated regression testing of GCC
-and reporting numerous bugs.
-
-@item
-Weiwen Liu for testing and various bug fixes.
-
-@item
-Manuel L@'opez-Ib@'a@~nez for improving @option{-Wconversion} and
-many other diagnostics fixes and improvements.
-
-@item
-Dave Love for his ongoing work with the Fortran front end and
-runtime libraries.
-
-@item
-Martin von L@"owis for internal consistency checking infrastructure,
-various C++ improvements including namespace support, and tons of
-assistance with libstdc++/compiler merges.
-
-@item
-H.J. Lu for his previous contributions to the steering committee, many x86
-bug reports, prototype patches, and keeping the GNU/Linux ports working.
-
-@item
-Greg McGary for random fixes and (someday) bounded pointers.
-
-@item
-Andrew MacLeod for his ongoing work in building a real EH system,
-various code generation improvements, work on the global optimizer, etc.
-
-@item
-Vladimir Makarov for hacking some ugly i960 problems, PowerPC hacking
-improvements to compile-time performance, overall knowledge and
-direction in the area of instruction scheduling, design and
-implementation of the automaton based instruction scheduler and
-design and implementation of the integrated and local register allocators.
-
-@item
-David Malcolm for his work on improving GCC diagnostics, JIT, self-tests
-and unit testing.
-
-@item
-Bob Manson for his behind the scenes work on dejagnu.
-
-@item
-John Marino for contributing the DragonFly BSD port.
-
-@item
-Philip Martin for lots of libstdc++ string and vector iterator fixes and
-improvements, and string clean up and testsuites.
-
-@item
-Michael Matz for his work on dominance tree discovery, the x86-64 port,
-link-time optimization framework and general optimization improvements.
-
-@item
-All of the Mauve project contributors for Java test code.
-
-@item
-Bryce McKinlay for numerous GCJ and libgcj fixes and improvements.
-
-@item
-Adam Megacz for his work on the Microsoft Windows port of GCJ@.
-
-@item
-Michael Meissner for LRS framework, ia32, m32r, v850, m88k, MIPS,
-powerpc, haifa, ECOFF debug support, and other assorted hacking.
-
-@item
-Jason Merrill for his direction via the steering committee and leading
-the G++ effort.
-
-@item
-Martin Michlmayr for testing GCC on several architectures using the
-entire Debian archive.
-
-@item
-David Miller for his direction via the steering committee, lots of
-SPARC work, improvements in jump.cc and interfacing with the Linux kernel
-developers.
-
-@item
-Gary Miller ported GCC to Charles River Data Systems machines.
-
-@item
-Alfred Minarik for libstdc++ string and ios bug fixes, and turning the
-entire libstdc++ testsuite namespace-compatible.
-
-@item
-Mark Mitchell for his direction via the steering committee, mountains of
-C++ work, load/store hoisting out of loops, alias analysis improvements,
-ISO C @code{restrict} support, and serving as release manager from 2000
-to 2011.
-
-@item
-Alan Modra for various GNU/Linux bits and testing.
-
-@item
-Toon Moene for his direction via the steering committee, Fortran
-maintenance, and his ongoing work to make us make Fortran run fast.
-
-@item
-Jason Molenda for major help in the care and feeding of all the services
-on the gcc.gnu.org (formerly egcs.cygnus.com) machine---mail, web
-services, ftp services, etc etc. Doing all this work on scrap paper and
-the backs of envelopes would have been@dots{} difficult.
-
-@item
-Catherine Moore for fixing various ugly problems we have sent her
-way, including the haifa bug which was killing the Alpha & PowerPC
-Linux kernels.
-
-@item
-Mike Moreton for his various Java patches.
-
-@item
-David Mosberger-Tang for various Alpha improvements, and for the initial
-IA-64 port.
-
-@item
-Stephen Moshier contributed the floating point emulator that assists in
-cross-compilation and permits support for floating point numbers wider
-than 64 bits and for ISO C99 support.
-
-@item
-Bill Moyer for his behind the scenes work on various issues.
-
-@item
-Philippe De Muyter for his work on the m68k port.
-
-@item
-Joseph S. Myers for his work on the PDP-11 port, format checking and ISO
-C99 support, and continuous emphasis on (and contributions to) documentation.
-
-@item
-Nathan Myers for his work on libstdc++-v3: architecture and authorship
-through the first three snapshots, including implementation of locale
-infrastructure, string, shadow C headers, and the initial project
-documentation (DESIGN, CHECKLIST, and so forth). Later, more work on
-MT-safe string and shadow headers.
-
-@item
-Felix Natter for documentation on porting libstdc++.
-
-@item
-Nathanael Nerode for cleaning up the configuration/build process.
-
-@item
-NeXT, Inc.@: donated the front end that supports the Objective-C
-language.
-
-@item
-Hans-Peter Nilsson for the CRIS and MMIX ports, improvements to the search
-engine setup, various documentation fixes and other small fixes.
-
-@item
-Geoff Noer for his work on getting cygwin native builds working.
-
-@item
-Vegard Nossum for running automated regression testing of GCC and reporting
-numerous bugs.
-
-@item
-Diego Novillo for his work on Tree SSA, OpenMP, SPEC performance
-tracking web pages, GIMPLE tuples, and assorted fixes.
-
-@item
-David O'Brien for the FreeBSD/alpha, FreeBSD/AMD x86-64, FreeBSD/ARM,
-FreeBSD/PowerPC, and FreeBSD/SPARC64 ports and related infrastructure
-improvements.
-
-@item
-Alexandre Oliva for various build infrastructure improvements, scripts and
-amazing testing work, including keeping libtool issues sane and happy.
-
-@item
-Stefan Olsson for work on mt_alloc.
-
-@item
-Melissa O'Neill for various NeXT fixes.
-
-@item
-Rainer Orth for random MIPS work, including improvements to GCC's o32
-ABI support, improvements to dejagnu's MIPS support, Java configuration
-clean-ups and porting work, and maintaining the IRIX, Solaris 2, and
-Tru64 UNIX ports.
-
-@item
-Steven Pemberton for his contribution of @file{enquire} which allowed GCC to
-determine various properties of the floating point unit and generate
-@file{float.h} in older versions of GCC.
-
-@item
-Hartmut Penner for work on the s390 port.
-
-@item
-Paul Petersen wrote the machine description for the Alliant FX/8.
-
-@item
-Alexandre Petit-Bianco for implementing much of the Java compiler and
-continued Java maintainership.
-
-@item
-Matthias Pfaller for major improvements to the NS32k port.
-
-@item
-Gerald Pfeifer for his direction via the steering committee, pointing
-out lots of problems we need to solve, maintenance of the web pages, and
-taking care of documentation maintenance in general.
-
-@item
-Marek Polacek for his work on the C front end, the sanitizers and general
-bug fixing.
-
-@item
-Andrew Pinski for processing bug reports by the dozen.
-
-@item
-Ovidiu Predescu for his work on the Objective-C front end and runtime
-libraries.
-
-@item
-Jerry Quinn for major performance improvements in C++ formatted I/O@.
-
-@item
-Ken Raeburn for various improvements to checker, MIPS ports and various
-cleanups in the compiler.
-
-@item
-Rolf W. Rasmussen for hacking on AWT@.
-
-@item
-David Reese of Sun Microsystems contributed to the Solaris on PowerPC
-port.
-
-@item
-John Regehr for running automated regression testing of GCC and reporting
-numerous bugs.
-
-@item
-Volker Reichelt for running automated regression testing of GCC and reporting
-numerous bugs and for keeping up with the problem reports.
-
-@item
-Joern Rennecke for maintaining the sh port, loop, regmove & reload
-hacking and developing and maintaining the Epiphany port.
-
-@item
-Loren J. Rittle for improvements to libstdc++-v3 including the FreeBSD
-port, threading fixes, thread-related configury changes, critical
-threading documentation, and solutions to really tricky I/O problems,
-as well as keeping GCC properly working on FreeBSD and continuous testing.
-
-@item
-Craig Rodrigues for processing tons of bug reports.
-
-@item
-Ola R@"onnerup for work on mt_alloc.
-
-@item
-Gavin Romig-Koch for lots of behind the scenes MIPS work.
-
-@item
-David Ronis inspired and encouraged Craig to rewrite the G77
-documentation in texinfo format by contributing a first pass at a
-translation of the old @file{g77-0.5.16/f/DOC} file.
-
-@item
-Ken Rose for fixes to GCC's delay slot filling code.
-
-@item
-Ira Rosen for her contributions to the auto-vectorizer.
-
-@item
-Paul Rubin wrote most of the preprocessor.
-
-@item
-P@'etur Run@'olfsson for major performance improvements in C++ formatted I/O and
-large file support in C++ filebuf.
-
-@item
-Chip Salzenberg for libstdc++ patches and improvements to locales, traits,
-Makefiles, libio, libtool hackery, and ``long long'' support.
-
-@item
-Juha Sarlin for improvements to the H8 code generator.
-
-@item
-Greg Satz assisted in making GCC work on HP-UX for the 9000 series 300.
-
-@item
-Roger Sayle for improvements to constant folding and GCC's RTL optimizers
-as well as for fixing numerous bugs.
-
-@item
-Bradley Schatz for his work on the GCJ FAQ@.
-
-@item
-Peter Schauer wrote the code to allow debugging to work on the Alpha.
-
-@item
-William Schelter did most of the work on the Intel 80386 support.
-
-@item
-Tobias Schl@"uter for work on GNU Fortran.
-
-@item
-Bernd Schmidt for various code generation improvements and major
-work in the reload pass, serving as release manager for
-GCC 2.95.3, and work on the Blackfin and C6X ports.
-
-@item
-Peter Schmid for constant testing of libstdc++---especially application
-testing, going above and beyond what was requested for the release
-criteria---and libstdc++ header file tweaks.
-
-@item
-Jason Schroeder for jcf-dump patches.
-
-@item
-Andreas Schwab for his work on the m68k port.
-
-@item
-Lars Segerlund for work on GNU Fortran.
-
-@item
-Dodji Seketeli for numerous C++ bug fixes and debug info improvements.
-
-@item
-Tim Shen for major work on @code{<regex>}.
-
-@item
-Joel Sherrill for his direction via the steering committee, RTEMS
-contributions and RTEMS testing.
-
-@item
-Nathan Sidwell for many C++ fixes/improvements.
-
-@item
-Jeffrey Siegal for helping RMS with the original design of GCC, some
-code which handles the parse tree and RTL data structures, constant
-folding and help with the original VAX & m68k ports.
-
-@item
-Kenny Simpson for prompting libstdc++ fixes due to defect reports from
-the LWG (thereby keeping GCC in line with updates from the ISO)@.
-
-@item
-Franz Sirl for his ongoing work with making the PPC port stable
-for GNU/Linux.
-
-@item
-Andrey Slepuhin for assorted AIX hacking.
-
-@item
-Trevor Smigiel for contributing the SPU port.
-
-@item
-Christopher Smith did the port for Convex machines.
-
-@item
-Danny Smith for his major efforts on the Mingw (and Cygwin) ports.
-Retired from GCC maintainership August 2010, having mentored two
-new maintainers into the role.
-
-@item
-Randy Smith finished the Sun FPA support.
-
-@item
-Ed Smith-Rowland for his continuous work on libstdc++-v3, special functions,
-@code{<random>}, and various improvements to C++11 features.
-
-@item
-Scott Snyder for queue, iterator, istream, and string fixes and libstdc++
-testsuite entries. Also for providing the patch to G77 to add
-rudimentary support for @code{INTEGER*1}, @code{INTEGER*2}, and
-@code{LOGICAL*1}.
-
-@item
-Zdenek Sojka for running automated regression testing of GCC and reporting
-numerous bugs.
-
-@item
-Arseny Solokha for running automated regression testing of GCC and reporting
-numerous bugs.
-
-@item
-Jayant Sonar for contributing the CR16 port.
-
-@item
-Brad Spencer for contributions to the GLIBCPP_FORCE_NEW technique.
-
-@item
-Richard Stallman, for writing the original GCC and launching the GNU project.
-
-@item
-Jan Stein of the Chalmers Computer Society provided support for
-Genix, as well as part of the 32000 machine description.
-
-@item
-Gerhard Steinmetz for running automated regression testing of GCC and reporting
-numerous bugs.
-
-@item
-Nigel Stephens for various mips16 related fixes/improvements.
-
-@item
-Jonathan Stone wrote the machine description for the Pyramid computer.
-
-@item
-Graham Stott for various infrastructure improvements.
-
-@item
-John Stracke for his Java HTTP protocol fixes.
-
-@item
-Mike Stump for his Elxsi port, G++ contributions over the years and more
-recently his vxworks contributions
-
-@item
-Jeff Sturm for Java porting help, bug fixes, and encouragement.
-
-@item
-Zhendong Su for running automated regression testing of GCC and reporting
-numerous bugs.
-
-@item
-Chengnian Sun for running automated regression testing of GCC and reporting
-numerous bugs.
-
-@item
-Shigeya Suzuki for this fixes for the bsdi platforms.
-
-@item
-Ian Lance Taylor for the Go frontend, the initial mips16 and mips64
-support, general configury hacking, fixincludes, etc.
-
-@item
-Holger Teutsch provided the support for the Clipper CPU@.
-
-@item
-Gary Thomas for his ongoing work to make the PPC work for GNU/Linux.
-
-@item
-Paul Thomas for contributions to GNU Fortran.
-
-@item
-Philipp Thomas for random bug fixes throughout the compiler
-
-@item
-Jason Thorpe for thread support in libstdc++ on NetBSD@.
-
-@item
-Kresten Krab Thorup wrote the run time support for the Objective-C
-language and the fantastic Java bytecode interpreter.
-
-@item
-Michael Tiemann for random bug fixes, the first instruction scheduler,
-initial C++ support, function integration, NS32k, SPARC and M88k
-machine description work, delay slot scheduling.
-
-@item
-Andreas Tobler for his work porting libgcj to Darwin.
-
-@item
-Teemu Torma for thread safe exception handling support.
-
-@item
-Leonard Tower wrote parts of the parser, RTL generator, and RTL
-definitions, and of the VAX machine description.
-
-@item
-Daniel Towner and Hariharan Sandanagobalane contributed and
-maintain the picoChip port.
-
-@item
-Tom Tromey for internationalization support and for his many Java
-contributions and libgcj maintainership.
-
-@item
-Lassi Tuura for improvements to config.guess to determine HP processor
-types.
-
-@item
-Petter Urkedal for libstdc++ CXXFLAGS, math, and algorithms fixes.
-
-@item
-Andy Vaught for the design and initial implementation of the GNU Fortran
-front end.
-
-@item
-Brent Verner for work with the libstdc++ cshadow files and their
-associated configure steps.
-
-@item
-Todd Vierling for contributions for NetBSD ports.
-
-@item
-Andrew Waterman for contributing the RISC-V port, as well as maintaining it.
-
-@item
-Jonathan Wakely for contributing libstdc++ Doxygen notes and XHTML
-guidance and maintaining libstdc++.
-
-@item
-Dean Wakerley for converting the install documentation from HTML to texinfo
-in time for GCC 3.0.
-
-@item
-Krister Walfridsson for random bug fixes.
-
-@item
-Feng Wang for contributions to GNU Fortran.
-
-@item
-Stephen M. Webb for time and effort on making libstdc++ shadow files
-work with the tricky Solaris 8+ headers, and for pushing the build-time
-header tree. Also, for starting and driving the @code{<regex>} effort.
-
-@item
-John Wehle for various improvements for the x86 code generator,
-related infrastructure improvements to help x86 code generation,
-value range propagation and other work, WE32k port.
-
-@item
-Ulrich Weigand for work on the s390 port.
-
-@item
-Janus Weil for contributions to GNU Fortran.
-
-@item
-Zack Weinberg for major work on cpplib and various other bug fixes.
-
-@item
-Matt Welsh for help with Linux Threads support in GCJ@.
-
-@item
-Urban Widmark for help fixing java.io.
-
-@item
-Mark Wielaard for new Java library code and his work integrating with
-Classpath.
-
-@item
-Dale Wiles helped port GCC to the Tahoe.
-
-@item
-Bob Wilson from Tensilica, Inc.@: for the Xtensa port.
-
-@item
-Jim Wilson for his direction via the steering committee, tackling hard
-problems in various places that nobody else wanted to work on, strength
-reduction and other loop optimizations.
-
-@item
-Paul Woegerer and Tal Agmon for the CRX port.
-
-@item
-Carlo Wood for various fixes.
-
-@item
-Tom Wood for work on the m88k port.
-
-@item
-Chung-Ju Wu for his work on the Andes NDS32 port.
-
-@item
-Canqun Yang for work on GNU Fortran.
-
-@item
-Masanobu Yuhara of Fujitsu Laboratories implemented the machine
-description for the Tron architecture (specifically, the Gmicro).
-
-@item
-Kevin Zachmann helped port GCC to the Tahoe.
-
-@item
-Ayal Zaks for Swing Modulo Scheduling (SMS).
-
-@item
-Qirun Zhang for running automated regression testing of GCC and reporting
-numerous bugs.
-
-@item
-Xiaoqiang Zhang for work on GNU Fortran.
-
-@item
-Gilles Zunino for help porting Java to Irix.
-
-@end itemize
-
-The following people are recognized for their contributions to GNAT,
-the Ada front end of GCC:
-@itemize @bullet
-@item
-Bernard Banner
-
-@item
-Romain Berrendonner
-
-@item
-Geert Bosch
-
-@item
-Emmanuel Briot
-
-@item
-Joel Brobecker
-
-@item
-Ben Brosgol
-
-@item
-Vincent Celier
-
-@item
-Arnaud Charlet
-
-@item
-Chien Chieng
-
-@item
-Cyrille Comar
-
-@item
-Cyrille Crozes
-
-@item
-Robert Dewar
-
-@item
-Gary Dismukes
-
-@item
-Robert Duff
-
-@item
-Ed Falis
-
-@item
-Ramon Fernandez
-
-@item
-Sam Figueroa
-
-@item
-Vasiliy Fofanov
-
-@item
-Michael Friess
-
-@item
-Franco Gasperoni
-
-@item
-Ted Giering
-
-@item
-Matthew Gingell
-
-@item
-Laurent Guerby
-
-@item
-Jerome Guitton
-
-@item
-Olivier Hainque
-
-@item
-Jerome Hugues
-
-@item
-Hristian Kirtchev
-
-@item
-Jerome Lambourg
-
-@item
-Bruno Leclerc
-
-@item
-Albert Lee
-
-@item
-Sean McNeil
-
-@item
-Javier Miranda
-
-@item
-Laurent Nana
-
-@item
-Pascal Obry
-
-@item
-Dong-Ik Oh
-
-@item
-Laurent Pautet
-
-@item
-Brett Porter
-
-@item
-Thomas Quinot
-
-@item
-Nicolas Roche
-
-@item
-Pat Rogers
-
-@item
-Jose Ruiz
-
-@item
-Douglas Rupp
-
-@item
-Sergey Rybin
-
-@item
-Gail Schenker
-
-@item
-Ed Schonberg
-
-@item
-Nicolas Setton
-
-@item
-Samuel Tardieu
-
-@end itemize
-
-
-The following people are recognized for their contributions of new
-features, bug reports, testing and integration of classpath/libgcj for
-GCC version 4.1:
-@itemize @bullet
-@item
-Lillian Angel for @code{JTree} implementation and lots Free Swing
-additions and bug fixes.
-
-@item
-Wolfgang Baer for @code{GapContent} bug fixes.
-
-@item
-Anthony Balkissoon for @code{JList}, Free Swing 1.5 updates and mouse event
-fixes, lots of Free Swing work including @code{JTable} editing.
-
-@item
-Stuart Ballard for RMI constant fixes.
-
-@item
-Goffredo Baroncelli for @code{HTTPURLConnection} fixes.
-
-@item
-Gary Benson for @code{MessageFormat} fixes.
-
-@item
-Daniel Bonniot for @code{Serialization} fixes.
-
-@item
-Chris Burdess for lots of gnu.xml and http protocol fixes, @code{StAX}
-and @code{DOM xml:id} support.
-
-@item
-Ka-Hing Cheung for @code{TreePath} and @code{TreeSelection} fixes.
-
-@item
-Archie Cobbs for build fixes, VM interface updates,
-@code{URLClassLoader} updates.
-
-@item
-Kelley Cook for build fixes.
-
-@item
-Martin Cordova for Suggestions for better @code{SocketTimeoutException}.
-
-@item
-David Daney for @code{BitSet} bug fixes, @code{HttpURLConnection}
-rewrite and improvements.
-
-@item
-Thomas Fitzsimmons for lots of upgrades to the gtk+ AWT and Cairo 2D
-support. Lots of imageio framework additions, lots of AWT and Free
-Swing bug fixes.
-
-@item
-Jeroen Frijters for @code{ClassLoader} and nio cleanups, serialization fixes,
-better @code{Proxy} support, bug fixes and IKVM integration.
-
-@item
-Santiago Gala for @code{AccessControlContext} fixes.
-
-@item
-Nicolas Geoffray for @code{VMClassLoader} and @code{AccessController}
-improvements.
-
-@item
-David Gilbert for @code{basic} and @code{metal} icon and plaf support
-and lots of documenting, Lots of Free Swing and metal theme
-additions. @code{MetalIconFactory} implementation.
-
-@item
-Anthony Green for @code{MIDI} framework, @code{ALSA} and @code{DSSI}
-providers.
-
-@item
-Andrew Haley for @code{Serialization} and @code{URLClassLoader} fixes,
-gcj build speedups.
-
-@item
-Kim Ho for @code{JFileChooser} implementation.
-
-@item
-Andrew John Hughes for @code{Locale} and net fixes, URI RFC2986
-updates, @code{Serialization} fixes, @code{Properties} XML support and
-generic branch work, VMIntegration guide update.
-
-@item
-Bastiaan Huisman for @code{TimeZone} bug fixing.
-
-@item
-Andreas Jaeger for mprec updates.
-
-@item
-Paul Jenner for better @option{-Werror} support.
-
-@item
-Ito Kazumitsu for @code{NetworkInterface} implementation and updates.
-
-@item
-Roman Kennke for @code{BoxLayout}, @code{GrayFilter} and
-@code{SplitPane}, plus bug fixes all over. Lots of Free Swing work
-including styled text.
-
-@item
-Simon Kitching for @code{String} cleanups and optimization suggestions.
-
-@item
-Michael Koch for configuration fixes, @code{Locale} updates, bug and
-build fixes.
-
-@item
-Guilhem Lavaux for configuration, thread and channel fixes and Kaffe
-integration. JCL native @code{Pointer} updates. Logger bug fixes.
-
-@item
-David Lichteblau for JCL support library global/local reference
-cleanups.
-
-@item
-Aaron Luchko for JDWP updates and documentation fixes.
-
-@item
-Ziga Mahkovec for @code{Graphics2D} upgraded to Cairo 0.5 and new regex
-features.
-
-@item
-Sven de Marothy for BMP imageio support, CSS and @code{TextLayout}
-fixes. @code{GtkImage} rewrite, 2D, awt, free swing and date/time fixes and
-implementing the Qt4 peers.
-
-@item
-Casey Marshall for crypto algorithm fixes, @code{FileChannel} lock,
-@code{SystemLogger} and @code{FileHandler} rotate implementations, NIO
-@code{FileChannel.map} support, security and policy updates.
-
-@item
-Bryce McKinlay for RMI work.
-
-@item
-Audrius Meskauskas for lots of Free Corba, RMI and HTML work plus
-testing and documenting.
-
-@item
-Kalle Olavi Niemitalo for build fixes.
-
-@item
-Rainer Orth for build fixes.
-
-@item
-Andrew Overholt for @code{File} locking fixes.
-
-@item
-Ingo Proetel for @code{Image}, @code{Logger} and @code{URLClassLoader}
-updates.
-
-@item
-Olga Rodimina for @code{MenuSelectionManager} implementation.
-
-@item
-Jan Roehrich for @code{BasicTreeUI} and @code{JTree} fixes.
-
-@item
-Julian Scheid for documentation updates and gjdoc support.
-
-@item
-Christian Schlichtherle for zip fixes and cleanups.
-
-@item
-Robert Schuster for documentation updates and beans fixes,
-@code{TreeNode} enumerations and @code{ActionCommand} and various
-fixes, XML and URL, AWT and Free Swing bug fixes.
-
-@item
-Keith Seitz for lots of JDWP work.
-
-@item
-Christian Thalinger for 64-bit cleanups, Configuration and VM
-interface fixes and @code{CACAO} integration, @code{fdlibm} updates.
-
-@item
-Gael Thomas for @code{VMClassLoader} boot packages support suggestions.
-
-@item
-Andreas Tobler for Darwin and Solaris testing and fixing, @code{Qt4}
-support for Darwin/OS X, @code{Graphics2D} support, @code{gtk+}
-updates.
-
-@item
-Dalibor Topic for better @code{DEBUG} support, build cleanups and
-Kaffe integration. @code{Qt4} build infrastructure, @code{SHA1PRNG}
-and @code{GdkPixbugDecoder} updates.
-
-@item
-Tom Tromey for Eclipse integration, generics work, lots of bug fixes
-and gcj integration including coordinating The Big Merge.
-
-@item
-Mark Wielaard for bug fixes, packaging and release management,
-@code{Clipboard} implementation, system call interrupts and network
-timeouts and @code{GdkPixpufDecoder} fixes.
-
-@end itemize
-
-
-In addition to the above, all of which also contributed time and energy in
-testing GCC, we would like to thank the following for their contributions
-to testing:
-
-@itemize @bullet
-@item
-Michael Abd-El-Malek
-
-@item
-Thomas Arend
-
-@item
-Bonzo Armstrong
-
-@item
-Steven Ashe
-
-@item
-Chris Baldwin
-
-@item
-David Billinghurst
-
-@item
-Jim Blandy
-
-@item
-Stephane Bortzmeyer
-
-@item
-Horst von Brand
-
-@item
-Frank Braun
-
-@item
-Rodney Brown
-
-@item
-Sidney Cadot
-
-@item
-Bradford Castalia
-
-@item
-Robert Clark
-
-@item
-Jonathan Corbet
-
-@item
-Ralph Doncaster
-
-@item
-Richard Emberson
-
-@item
-Levente Farkas
-
-@item
-Graham Fawcett
-
-@item
-Mark Fernyhough
-
-@item
-Robert A. French
-
-@item
-J@"orgen Freyh
-
-@item
-Mark K. Gardner
-
-@item
-Charles-Antoine Gauthier
-
-@item
-Yung Shing Gene
-
-@item
-David Gilbert
-
-@item
-Simon Gornall
-
-@item
-Fred Gray
-
-@item
-John Griffin
-
-@item
-Patrik Hagglund
-
-@item
-Phil Hargett
-
-@item
-Amancio Hasty
-
-@item
-Takafumi Hayashi
-
-@item
-Bryan W. Headley
-
-@item
-Kevin B. Hendricks
-
-@item
-Joep Jansen
-
-@item
-Christian Joensson
-
-@item
-Michel Kern
-
-@item
-David Kidd
-
-@item
-Tobias Kuipers
-
-@item
-Anand Krishnaswamy
-
-@item
-A. O. V. Le Blanc
-
-@item
-llewelly
-
-@item
-Damon Love
-
-@item
-Brad Lucier
-
-@item
-Matthias Klose
-
-@item
-Martin Knoblauch
-
-@item
-Rick Lutowski
-
-@item
-Jesse Macnish
-
-@item
-Stefan Morrell
-
-@item
-Anon A. Mous
-
-@item
-Matthias Mueller
-
-@item
-Pekka Nikander
-
-@item
-Rick Niles
-
-@item
-Jon Olson
-
-@item
-Magnus Persson
-
-@item
-Chris Pollard
-
-@item
-Richard Polton
-
-@item
-Derk Reefman
-
-@item
-David Rees
-
-@item
-Paul Reilly
-
-@item
-Tom Reilly
-
-@item
-Torsten Rueger
-
-@item
-Danny Sadinoff
-
-@item
-Marc Schifer
-
-@item
-Erik Schnetter
-
-@item
-Wayne K. Schroll
-
-@item
-David Schuler
-
-@item
-Vin Shelton
-
-@item
-Tim Souder
-
-@item
-Adam Sulmicki
-
-@item
-Bill Thorson
-
-@item
-George Talbot
-
-@item
-Pedro A. M. Vazquez
-
-@item
-Gregory Warnes
-
-@item
-Ian Watson
-
-@item
-David E. Young
-
-@item
-And many others
-@end itemize
-
-And finally we'd like to thank everyone who uses the compiler, provides
-feedback and generally reminds us why we're doing this work in the first
-place.
+++ /dev/null
-@c Copyright (C) 1988-2022 Free Software Foundation, Inc.
-@c This is part of the GCC manual.
-@c For copying conditions, see the file gcc.texi.
-
-@node Contributing
-@chapter Contributing to GCC Development
-
-If you would like to help pretest GCC releases to assure they work well,
-current development sources are available via Git (see
-@uref{https://gcc.gnu.org/git.html}). Source and binary snapshots are
-also available for FTP; see @uref{https://gcc.gnu.org/snapshots.html}.
-
-If you would like to work on improvements to GCC, please read the
-advice at these URLs:
-
-@smallexample
-@uref{https://gcc.gnu.org/contribute.html}
-@uref{https://gcc.gnu.org/contributewhy.html}
-@end smallexample
-
-@noindent
-for information on how to make useful contributions and avoid
-duplication of effort. Suggested projects are listed at
-@uref{https://gcc.gnu.org/projects/}.
+++ /dev/null
-\input texinfo
-@setfilename cpp.info
-@settitle The C Preprocessor
-@setchapternewpage off
-@c @smallbook
-@c @cropmarks
-@c @finalout
-
-@include gcc-common.texi
-
-@copying
-@c man begin COPYRIGHT
-Copyright @copyright{} 1987-2022 Free Software Foundation, Inc.
-
-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. A copy of
-the license is included in the
-@c man end
-section entitled ``GNU Free Documentation License''.
-@ignore
-@c man begin COPYRIGHT
-man page gfdl(7).
-@c man end
-@end ignore
-
-@c man begin COPYRIGHT
-This manual contains no Invariant Sections. The Front-Cover Texts are
-(a) (see below), and the Back-Cover Texts are (b) (see below).
-
-(a) The FSF's Front-Cover Text is:
-
- A GNU Manual
-
-(b) The FSF's Back-Cover Text is:
-
- You have freedom to copy and modify this GNU Manual, like GNU
- software. Copies published by the Free Software Foundation raise
- funds for GNU development.
-@c man end
-@end copying
-
-@c Create a separate index for command line options.
-@defcodeindex op
-@syncodeindex vr op
-
-@c Used in cppopts.texi and cppenv.texi.
-@set cppmanual
-
-@ifinfo
-@dircategory Software development
-@direntry
-* Cpp: (cpp). The GNU C preprocessor.
-@end direntry
-@end ifinfo
-
-@titlepage
-@title The C Preprocessor
-@versionsubtitle
-@author Richard M. Stallman, Zachary Weinberg
-@page
-@c There is a fill at the bottom of the page, so we need a filll to
-@c override it.
-@vskip 0pt plus 1filll
-@insertcopying
-@end titlepage
-@contents
-@page
-
-@ifnottex
-@node Top
-@top
-The C preprocessor implements the macro language used to transform C,
-C++, and Objective-C programs before they are compiled. It can also be
-useful on its own.
-
-@menu
-* Overview::
-* Header Files::
-* Macros::
-* Conditionals::
-* Diagnostics::
-* Line Control::
-* Pragmas::
-* Other Directives::
-* Preprocessor Output::
-* Traditional Mode::
-* Implementation Details::
-* Invocation::
-* Environment Variables::
-* GNU Free Documentation License::
-* Index of Directives::
-* Option Index::
-* Concept Index::
-
-@detailmenu
- --- The Detailed Node Listing ---
-
-Overview
-
-* Character sets::
-* Initial processing::
-* Tokenization::
-* The preprocessing language::
-
-Header Files
-
-* Include Syntax::
-* Include Operation::
-* Search Path::
-* Once-Only Headers::
-* Alternatives to Wrapper #ifndef::
-* Computed Includes::
-* Wrapper Headers::
-* System Headers::
-
-Macros
-
-* Object-like Macros::
-* Function-like Macros::
-* Macro Arguments::
-* Stringizing::
-* Concatenation::
-* Variadic Macros::
-* Predefined Macros::
-* Undefining and Redefining Macros::
-* Directives Within Macro Arguments::
-* Macro Pitfalls::
-
-Predefined Macros
-
-* Standard Predefined Macros::
-* Common Predefined Macros::
-* System-specific Predefined Macros::
-* C++ Named Operators::
-
-Macro Pitfalls
-
-* Misnesting::
-* Operator Precedence Problems::
-* Swallowing the Semicolon::
-* Duplication of Side Effects::
-* Self-Referential Macros::
-* Argument Prescan::
-* Newlines in Arguments::
-
-Conditionals
-
-* Conditional Uses::
-* Conditional Syntax::
-* Deleted Code::
-
-Conditional Syntax
-
-* Ifdef::
-* If::
-* Defined::
-* Else::
-* Elif::
-
-Implementation Details
-
-* Implementation-defined behavior::
-* Implementation limits::
-* Obsolete Features::
-
-Obsolete Features
-
-* Obsolete Features::
-
-@end detailmenu
-@end menu
-
-@insertcopying
-@end ifnottex
-
-@node Overview
-@chapter Overview
-@c man begin DESCRIPTION
-The C preprocessor, often known as @dfn{cpp}, is a @dfn{macro processor}
-that is used automatically by the C compiler to transform your program
-before compilation. It is called a macro processor because it allows
-you to define @dfn{macros}, which are brief abbreviations for longer
-constructs.
-
-The C preprocessor is intended to be used only with C, C++, and
-Objective-C source code. In the past, it has been abused as a general
-text processor. It will choke on input which does not obey C's lexical
-rules. For example, apostrophes will be interpreted as the beginning of
-character constants, and cause errors. Also, you cannot rely on it
-preserving characteristics of the input which are not significant to
-C-family languages. If a Makefile is preprocessed, all the hard tabs
-will be removed, and the Makefile will not work.
-
-Having said that, you can often get away with using cpp on things which
-are not C@. Other Algol-ish programming languages are often safe
-(Ada, etc.) So is assembly, with caution. @option{-traditional-cpp}
-mode preserves more white space, and is otherwise more permissive. Many
-of the problems can be avoided by writing C or C++ style comments
-instead of native language comments, and keeping macros simple.
-
-Wherever possible, you should use a preprocessor geared to the language
-you are writing in. Modern versions of the GNU assembler have macro
-facilities. Most high level programming languages have their own
-conditional compilation and inclusion mechanism. If all else fails,
-try a true general text processor, such as GNU M4.
-
-C preprocessors vary in some details. This manual discusses the GNU C
-preprocessor, which provides a small superset of the features of ISO
-Standard C@. In its default mode, the GNU C preprocessor does not do a
-few things required by the standard. These are features which are
-rarely, if ever, used, and may cause surprising changes to the meaning
-of a program which does not expect them. To get strict ISO Standard C,
-you should use the @option{-std=c90}, @option{-std=c99},
-@option{-std=c11} or @option{-std=c17} options, depending
-on which version of the standard you want. To get all the mandatory
-diagnostics, you must also use @option{-pedantic}. @xref{Invocation}.
-
-This manual describes the behavior of the ISO preprocessor. To
-minimize gratuitous differences, where the ISO preprocessor's
-behavior does not conflict with traditional semantics, the
-traditional preprocessor should behave the same way. The various
-differences that do exist are detailed in the section @ref{Traditional
-Mode}.
-
-For clarity, unless noted otherwise, references to @samp{CPP} in this
-manual refer to GNU CPP@.
-@c man end
-
-@menu
-* Character sets::
-* Initial processing::
-* Tokenization::
-* The preprocessing language::
-@end menu
-
-@node Character sets
-@section Character sets
-
-Source code character set processing in C and related languages is
-rather complicated. The C standard discusses two character sets, but
-there are really at least four.
-
-The files input to CPP might be in any character set at all. CPP's
-very first action, before it even looks for line boundaries, is to
-convert the file into the character set it uses for internal
-processing. That set is what the C standard calls the @dfn{source}
-character set. It must be isomorphic with ISO 10646, also known as
-Unicode. CPP uses the UTF-8 encoding of Unicode.
-
-The character sets of the input files are specified using the
-@option{-finput-charset=} option.
-
-All preprocessing work (the subject of the rest of this manual) is
-carried out in the source character set. If you request textual
-output from the preprocessor with the @option{-E} option, it will be
-in UTF-8.
-
-After preprocessing is complete, string and character constants are
-converted again, into the @dfn{execution} character set. This
-character set is under control of the user; the default is UTF-8,
-matching the source character set. Wide string and character
-constants have their own character set, which is not called out
-specifically in the standard. Again, it is under control of the user.
-The default is UTF-16 or UTF-32, whichever fits in the target's
-@code{wchar_t} type, in the target machine's byte
-order.@footnote{UTF-16 does not meet the requirements of the C
-standard for a wide character set, but the choice of 16-bit
-@code{wchar_t} is enshrined in some system ABIs so we cannot fix
-this.} Octal and hexadecimal escape sequences do not undergo
-conversion; @t{'\x12'} has the value 0x12 regardless of the currently
-selected execution character set. All other escapes are replaced by
-the character in the source character set that they represent, then
-converted to the execution character set, just like unescaped
-characters.
-
-In identifiers, characters outside the ASCII range can be specified
-with the @samp{\u} and @samp{\U} escapes or used directly in the input
-encoding. If strict ISO C90 conformance is specified with an option
-such as @option{-std=c90}, or @option{-fno-extended-identifiers} is
-used, then those constructs are not permitted in identifiers.
-
-@node Initial processing
-@section Initial processing
-
-The preprocessor performs a series of textual transformations on its
-input. These happen before all other processing. Conceptually, they
-happen in a rigid order, and the entire file is run through each
-transformation before the next one begins. CPP actually does them
-all at once, for performance reasons. These transformations correspond
-roughly to the first three ``phases of translation'' described in the C
-standard.
-
-@enumerate
-@item
-@cindex line endings
-The input file is read into memory and broken into lines.
-
-Different systems use different conventions to indicate the end of a
-line. GCC accepts the ASCII control sequences @kbd{LF}, @kbd{@w{CR
-LF}} and @kbd{CR} as end-of-line markers. These are the canonical
-sequences used by Unix, DOS and VMS, and the classic Mac OS (before
-OSX) respectively. You may therefore safely copy source code written
-on any of those systems to a different one and use it without
-conversion. (GCC may lose track of the current line number if a file
-doesn't consistently use one convention, as sometimes happens when it
-is edited on computers with different conventions that share a network
-file system.)
-
-If the last line of any input file lacks an end-of-line marker, the end
-of the file is considered to implicitly supply one. The C standard says
-that this condition provokes undefined behavior, so GCC will emit a
-warning message.
-
-@item
-@cindex trigraphs
-@anchor{trigraphs}If trigraphs are enabled, they are replaced by their
-corresponding single characters. By default GCC ignores trigraphs,
-but if you request a strictly conforming mode with the @option{-std}
-option, or you specify the @option{-trigraphs} option, then it
-converts them.
-
-These are nine three-character sequences, all starting with @samp{??},
-that are defined by ISO C to stand for single characters. They permit
-obsolete systems that lack some of C's punctuation to use C@. For
-example, @samp{??/} stands for @samp{\}, so @t{'??/n'} is a character
-constant for a newline.
-
-Trigraphs are not popular and many compilers implement them
-incorrectly. Portable code should not rely on trigraphs being either
-converted or ignored. With @option{-Wtrigraphs} GCC will warn you
-when a trigraph may change the meaning of your program if it were
-converted. @xref{Wtrigraphs}.
-
-In a string constant, you can prevent a sequence of question marks
-from being confused with a trigraph by inserting a backslash between
-the question marks, or by separating the string literal at the
-trigraph and making use of string literal concatenation. @t{"(??\?)"}
-is the string @samp{(???)}, not @samp{(?]}. Traditional C compilers
-do not recognize these idioms.
-
-The nine trigraphs and their replacements are
-
-@smallexample
-Trigraph: ??( ??) ??< ??> ??= ??/ ??' ??! ??-
-Replacement: [ ] @{ @} # \ ^ | ~
-@end smallexample
-
-@item
-@cindex continued lines
-@cindex backslash-newline
-Continued lines are merged into one long line.
-
-A continued line is a line which ends with a backslash, @samp{\}. The
-backslash is removed and the following line is joined with the current
-one. No space is inserted, so you may split a line anywhere, even in
-the middle of a word. (It is generally more readable to split lines
-only at white space.)
-
-The trailing backslash on a continued line is commonly referred to as a
-@dfn{backslash-newline}.
-
-If there is white space between a backslash and the end of a line, that
-is still a continued line. However, as this is usually the result of an
-editing mistake, and many compilers will not accept it as a continued
-line, GCC will warn you about it.
-
-@item
-@cindex comments
-@cindex line comments
-@cindex block comments
-All comments are replaced with single spaces.
-
-There are two kinds of comments. @dfn{Block comments} begin with
-@samp{/*} and continue until the next @samp{*/}. Block comments do not
-nest:
-
-@smallexample
-/* @r{this is} /* @r{one comment} */ @r{text outside comment}
-@end smallexample
-
-@dfn{Line comments} begin with @samp{//} and continue to the end of the
-current line. Line comments do not nest either, but it does not matter,
-because they would end in the same place anyway.
-
-@smallexample
-// @r{this is} // @r{one comment}
-@r{text outside comment}
-@end smallexample
-@end enumerate
-
-It is safe to put line comments inside block comments, or vice versa.
-
-@smallexample
-@group
-/* @r{block comment}
- // @r{contains line comment}
- @r{yet more comment}
- */ @r{outside comment}
-
-// @r{line comment} /* @r{contains block comment} */
-@end group
-@end smallexample
-
-But beware of commenting out one end of a block comment with a line
-comment.
-
-@smallexample
-@group
- // @r{l.c.} /* @r{block comment begins}
- @r{oops! this isn't a comment anymore} */
-@end group
-@end smallexample
-
-Comments are not recognized within string literals.
-@t{@w{"/* blah */"}} is the string constant @samp{@w{/* blah */}}, not
-an empty string.
-
-Line comments are not in the 1989 edition of the C standard, but they
-are recognized by GCC as an extension. In C++ and in the 1999 edition
-of the C standard, they are an official part of the language.
-
-Since these transformations happen before all other processing, you can
-split a line mechanically with backslash-newline anywhere. You can
-comment out the end of a line. You can continue a line comment onto the
-next line with backslash-newline. You can even split @samp{/*},
-@samp{*/}, and @samp{//} onto multiple lines with backslash-newline.
-For example:
-
-@smallexample
-@group
-/\
-*
-*/ # /*
-*/ defi\
-ne FO\
-O 10\
-20
-@end group
-@end smallexample
-
-@noindent
-is equivalent to @code{@w{#define FOO 1020}}. All these tricks are
-extremely confusing and should not be used in code intended to be
-readable.
-
-There is no way to prevent a backslash at the end of a line from being
-interpreted as a backslash-newline. This cannot affect any correct
-program, however.
-
-@node Tokenization
-@section Tokenization
-
-@cindex tokens
-@cindex preprocessing tokens
-After the textual transformations are finished, the input file is
-converted into a sequence of @dfn{preprocessing tokens}. These mostly
-correspond to the syntactic tokens used by the C compiler, but there are
-a few differences. White space separates tokens; it is not itself a
-token of any kind. Tokens do not have to be separated by white space,
-but it is often necessary to avoid ambiguities.
-
-When faced with a sequence of characters that has more than one possible
-tokenization, the preprocessor is greedy. It always makes each token,
-starting from the left, as big as possible before moving on to the next
-token. For instance, @code{a+++++b} is interpreted as
-@code{@w{a ++ ++ + b}}, not as @code{@w{a ++ + ++ b}}, even though the
-latter tokenization could be part of a valid C program and the former
-could not.
-
-Once the input file is broken into tokens, the token boundaries never
-change, except when the @samp{##} preprocessing operator is used to paste
-tokens together. @xref{Concatenation}. For example,
-
-@smallexample
-@group
-#define foo() bar
-foo()baz
- @expansion{} bar baz
-@emph{not}
- @expansion{} barbaz
-@end group
-@end smallexample
-
-The compiler does not re-tokenize the preprocessor's output. Each
-preprocessing token becomes one compiler token.
-
-@cindex identifiers
-Preprocessing tokens fall into five broad classes: identifiers,
-preprocessing numbers, string literals, punctuators, and other. An
-@dfn{identifier} is the same as an identifier in C: any sequence of
-letters, digits, or underscores, which begins with a letter or
-underscore. Keywords of C have no significance to the preprocessor;
-they are ordinary identifiers. You can define a macro whose name is a
-keyword, for instance. The only identifier which can be considered a
-preprocessing keyword is @code{defined}. @xref{Defined}.
-
-This is mostly true of other languages which use the C preprocessor.
-However, a few of the keywords of C++ are significant even in the
-preprocessor. @xref{C++ Named Operators}.
-
-In the 1999 C standard, identifiers may contain letters which are not
-part of the ``basic source character set'', at the implementation's
-discretion (such as accented Latin letters, Greek letters, or Chinese
-ideograms). This may be done with an extended character set, or the
-@samp{\u} and @samp{\U} escape sequences.
-
-As an extension, GCC treats @samp{$} as a letter. This is for
-compatibility with some systems, such as VMS, where @samp{$} is commonly
-used in system-defined function and object names. @samp{$} is not a
-letter in strictly conforming mode, or if you specify the @option{-$}
-option. @xref{Invocation}.
-
-@cindex numbers
-@cindex preprocessing numbers
-A @dfn{preprocessing number} has a rather bizarre definition. The
-category includes all the normal integer and floating point constants
-one expects of C, but also a number of other things one might not
-initially recognize as a number. Formally, preprocessing numbers begin
-with an optional period, a required decimal digit, and then continue
-with any sequence of letters, digits, underscores, periods, and
-exponents. Exponents are the two-character sequences @samp{e+},
-@samp{e-}, @samp{E+}, @samp{E-}, @samp{p+}, @samp{p-}, @samp{P+}, and
-@samp{P-}. (The exponents that begin with @samp{p} or @samp{P} are
-used for hexadecimal floating-point constants.)
-
-The purpose of this unusual definition is to isolate the preprocessor
-from the full complexity of numeric constants. It does not have to
-distinguish between lexically valid and invalid floating-point numbers,
-which is complicated. The definition also permits you to split an
-identifier at any position and get exactly two tokens, which can then be
-pasted back together with the @samp{##} operator.
-
-It's possible for preprocessing numbers to cause programs to be
-misinterpreted. For example, @code{0xE+12} is a preprocessing number
-which does not translate to any valid numeric constant, therefore a
-syntax error. It does not mean @code{@w{0xE + 12}}, which is what you
-might have intended.
-
-@cindex string literals
-@cindex string constants
-@cindex character constants
-@cindex header file names
-@c the @: prevents makeinfo from turning '' into ".
-@dfn{String literals} are string constants, character constants, and
-header file names (the argument of @samp{#include}).@footnote{The C
-standard uses the term @dfn{string literal} to refer only to what we are
-calling @dfn{string constants}.} String constants and character
-constants are straightforward: @t{"@dots{}"} or @t{'@dots{}'}. In
-either case embedded quotes should be escaped with a backslash:
-@t{'\'@:'} is the character constant for @samp{'}. There is no limit on
-the length of a character constant, but the value of a character
-constant that contains more than one character is
-implementation-defined. @xref{Implementation Details}.
-
-Header file names either look like string constants, @t{"@dots{}"}, or are
-written with angle brackets instead, @t{<@dots{}>}. In either case,
-backslash is an ordinary character. There is no way to escape the
-closing quote or angle bracket. The preprocessor looks for the header
-file in different places depending on which form you use. @xref{Include
-Operation}.
-
-No string literal may extend past the end of a line. You may use continued
-lines instead, or string constant concatenation.
-
-@cindex punctuators
-@cindex digraphs
-@cindex alternative tokens
-@dfn{Punctuators} are all the usual bits of punctuation which are
-meaningful to C and C++. All but three of the punctuation characters in
-ASCII are C punctuators. The exceptions are @samp{@@}, @samp{$}, and
-@samp{`}. In addition, all the two- and three-character operators are
-punctuators. There are also six @dfn{digraphs}, which the C++ standard
-calls @dfn{alternative tokens}, which are merely alternate ways to spell
-other punctuators. This is a second attempt to work around missing
-punctuation in obsolete systems. It has no negative side effects,
-unlike trigraphs, but does not cover as much ground. The digraphs and
-their corresponding normal punctuators are:
-
-@smallexample
-Digraph: <% %> <: :> %: %:%:
-Punctuator: @{ @} [ ] # ##
-@end smallexample
-
-@cindex other tokens
-Any other single byte is considered ``other'' and passed on to the
-preprocessor's output unchanged. The C compiler will almost certainly
-reject source code containing ``other'' tokens. In ASCII, the only
-``other'' characters are @samp{@@}, @samp{$}, @samp{`}, and control
-characters other than NUL (all bits zero). (Note that @samp{$} is
-normally considered a letter.) All bytes with the high bit set
-(numeric range 0x7F--0xFF) that were not succesfully interpreted as
-part of an extended character in the input encoding are also ``other''
-in the present implementation.
-
-NUL is a special case because of the high probability that its
-appearance is accidental, and because it may be invisible to the user
-(many terminals do not display NUL at all). Within comments, NULs are
-silently ignored, just as any other character would be. In running
-text, NUL is considered white space. For example, these two directives
-have the same meaning.
-
-@smallexample
-#define X^@@1
-#define X 1
-@end smallexample
-
-@noindent
-(where @samp{^@@} is ASCII NUL)@. Within string or character constants,
-NULs are preserved. In the latter two cases the preprocessor emits a
-warning message.
-
-@node The preprocessing language
-@section The preprocessing language
-@cindex directives
-@cindex preprocessing directives
-@cindex directive line
-@cindex directive name
-
-After tokenization, the stream of tokens may simply be passed straight
-to the compiler's parser. However, if it contains any operations in the
-@dfn{preprocessing language}, it will be transformed first. This stage
-corresponds roughly to the standard's ``translation phase 4'' and is
-what most people think of as the preprocessor's job.
-
-The preprocessing language consists of @dfn{directives} to be executed
-and @dfn{macros} to be expanded. Its primary capabilities are:
-
-@itemize @bullet
-@item
-Inclusion of header files. These are files of declarations that can be
-substituted into your program.
-
-@item
-Macro expansion. You can define @dfn{macros}, which are abbreviations
-for arbitrary fragments of C code. The preprocessor will replace the
-macros with their definitions throughout the program. Some macros are
-automatically defined for you.
-
-@item
-Conditional compilation. You can include or exclude parts of the
-program according to various conditions.
-
-@item
-Line control. If you use a program to combine or rearrange source files
-into an intermediate file which is then compiled, you can use line
-control to inform the compiler where each source line originally came
-from.
-
-@item
-Diagnostics. You can detect problems at compile time and issue errors
-or warnings.
-@end itemize
-
-There are a few more, less useful, features.
-
-Except for expansion of predefined macros, all these operations are
-triggered with @dfn{preprocessing directives}. Preprocessing directives
-are lines in your program that start with @samp{#}. Whitespace is
-allowed before and after the @samp{#}. The @samp{#} is followed by an
-identifier, the @dfn{directive name}. It specifies the operation to
-perform. Directives are commonly referred to as @samp{#@var{name}}
-where @var{name} is the directive name. For example, @samp{#define} is
-the directive that defines a macro.
-
-The @samp{#} which begins a directive cannot come from a macro
-expansion. Also, the directive name is not macro expanded. Thus, if
-@code{foo} is defined as a macro expanding to @code{define}, that does
-not make @samp{#foo} a valid preprocessing directive.
-
-The set of valid directive names is fixed. Programs cannot define new
-preprocessing directives.
-
-Some directives require arguments; these make up the rest of the
-directive line and must be separated from the directive name by
-whitespace. For example, @samp{#define} must be followed by a macro
-name and the intended expansion of the macro.
-
-A preprocessing directive cannot cover more than one line. The line
-may, however, be continued with backslash-newline, or by a block comment
-which extends past the end of the line. In either case, when the
-directive is processed, the continuations have already been merged with
-the first line to make one long line.
-
-@node Header Files
-@chapter Header Files
-
-@cindex header file
-A header file is a file containing C declarations and macro definitions
-(@pxref{Macros}) to be shared between several source files. You request
-the use of a header file in your program by @dfn{including} it, with the
-C preprocessing directive @samp{#include}.
-
-Header files serve two purposes.
-
-@itemize @bullet
-@item
-@cindex system header files
-System header files declare the interfaces to parts of the operating
-system. You include them in your program to supply the definitions and
-declarations you need to invoke system calls and libraries.
-
-@item
-Your own header files contain declarations for interfaces between the
-source files of your program. Each time you have a group of related
-declarations and macro definitions all or most of which are needed in
-several different source files, it is a good idea to create a header
-file for them.
-@end itemize
-
-Including a header file produces the same results as copying the header
-file into each source file that needs it. Such copying would be
-time-consuming and error-prone. With a header file, the related
-declarations appear in only one place. If they need to be changed, they
-can be changed in one place, and programs that include the header file
-will automatically use the new version when next recompiled. The header
-file eliminates the labor of finding and changing all the copies as well
-as the risk that a failure to find one copy will result in
-inconsistencies within a program.
-
-In C, the usual convention is to give header files names that end with
-@file{.h}. It is most portable to use only letters, digits, dashes, and
-underscores in header file names, and at most one dot.
-
-@menu
-* Include Syntax::
-* Include Operation::
-* Search Path::
-* Once-Only Headers::
-* Alternatives to Wrapper #ifndef::
-* Computed Includes::
-* Wrapper Headers::
-* System Headers::
-@end menu
-
-@node Include Syntax
-@section Include Syntax
-
-@findex #include
-Both user and system header files are included using the preprocessing
-directive @samp{#include}. It has two variants:
-
-@table @code
-@item #include <@var{file}>
-This variant is used for system header files. It searches for a file
-named @var{file} in a standard list of system directories. You can prepend
-directories to this list with the @option{-I} option (@pxref{Invocation}).
-
-@item #include "@var{file}"
-This variant is used for header files of your own program. It
-searches for a file named @var{file} first in the directory containing
-the current file, then in the quote directories and then the same
-directories used for @code{<@var{file}>}. You can prepend directories
-to the list of quote directories with the @option{-iquote} option.
-@end table
-
-The argument of @samp{#include}, whether delimited with quote marks or
-angle brackets, behaves like a string constant in that comments are not
-recognized, and macro names are not expanded. Thus, @code{@w{#include
-<x/*y>}} specifies inclusion of a system header file named @file{x/*y}.
-
-However, if backslashes occur within @var{file}, they are considered
-ordinary text characters, not escape characters. None of the character
-escape sequences appropriate to string constants in C are processed.
-Thus, @code{@w{#include "x\n\\y"}} specifies a filename containing three
-backslashes. (Some systems interpret @samp{\} as a pathname separator.
-All of these also interpret @samp{/} the same way. It is most portable
-to use only @samp{/}.)
-
-It is an error if there is anything (other than comments) on the line
-after the file name.
-
-@node Include Operation
-@section Include Operation
-
-The @samp{#include} directive works by directing the C preprocessor to
-scan the specified file as input before continuing with the rest of the
-current file. The output from the preprocessor contains the output
-already generated, followed by the output resulting from the included
-file, followed by the output that comes from the text after the
-@samp{#include} directive. For example, if you have a header file
-@file{header.h} as follows,
-
-@smallexample
-char *test (void);
-@end smallexample
-
-@noindent
-and a main program called @file{program.c} that uses the header file,
-like this,
-
-@smallexample
-int x;
-#include "header.h"
-
-int
-main (void)
-@{
- puts (test ());
-@}
-@end smallexample
-
-@noindent
-the compiler will see the same token stream as it would if
-@file{program.c} read
-
-@smallexample
-int x;
-char *test (void);
-
-int
-main (void)
-@{
- puts (test ());
-@}
-@end smallexample
-
-Included files are not limited to declarations and macro definitions;
-those are merely the typical uses. Any fragment of a C program can be
-included from another file. The include file could even contain the
-beginning of a statement that is concluded in the containing file, or
-the end of a statement that was started in the including file. However,
-an included file must consist of complete tokens. Comments and string
-literals which have not been closed by the end of an included file are
-invalid. For error recovery, they are considered to end at the end of
-the file.
-
-To avoid confusion, it is best if header files contain only complete
-syntactic units---function declarations or definitions, type
-declarations, etc.
-
-The line following the @samp{#include} directive is always treated as a
-separate line by the C preprocessor, even if the included file lacks a
-final newline.
-
-@node Search Path
-@section Search Path
-
-By default, the preprocessor looks for header files included by the quote
-form of the directive @code{@w{#include "@var{file}"}} first relative to
-the directory of the current file, and then in a preconfigured list
-of standard system directories.
-For example, if @file{/usr/include/sys/stat.h} contains
-@code{@w{#include "types.h"}}, GCC looks for @file{types.h} first in
-@file{/usr/include/sys}, then in its usual search path.
-
-For the angle-bracket form @code{@w{#include <@var{file}>}}, the
-preprocessor's default behavior is to look only in the standard system
-directories. The exact search directory list depends on the target
-system, how GCC is configured, and where it is installed. You can
-find the default search directory list for your version of CPP by
-invoking it with the @option{-v} option. For example,
-
-@smallexample
-cpp -v /dev/null -o /dev/null
-@end smallexample
-
-There are a number of command-line options you can use to add
-additional directories to the search path.
-The most commonly-used option is @option{-I@var{dir}}, which causes
-@var{dir} to be searched after the current directory (for the quote
-form of the directive) and ahead of the standard system directories.
-You can specify multiple @option{-I} options on the command line,
-in which case the directories are searched in left-to-right order.
-
-If you need separate control over the search paths for the quote and
-angle-bracket forms of the @samp{#include} directive, you can use the
-@option{-iquote} and/or @option{-isystem} options instead of @option{-I}.
-@xref{Invocation}, for a detailed description of these options, as
-well as others that are less generally useful.
-
-If you specify other options on the command line, such as @option{-I},
-that affect where the preprocessor searches for header files, the
-directory list printed by the @option{-v} option reflects the actual
-search path used by the preprocessor.
-
-Note that you can also prevent the preprocessor from searching any of
-the default system header directories with the @option{-nostdinc}
-option. This is useful when you are compiling an operating system
-kernel or some other program that does not use the standard C library
-facilities, or the standard C library itself.
-
-@node Once-Only Headers
-@section Once-Only Headers
-@cindex repeated inclusion
-@cindex including just once
-@cindex wrapper @code{#ifndef}
-
-If a header file happens to be included twice, the compiler will process
-its contents twice. This is very likely to cause an error, e.g.@: when the
-compiler sees the same structure definition twice. Even if it does not,
-it will certainly waste time.
-
-The standard way to prevent this is to enclose the entire real contents
-of the file in a conditional, like this:
-
-@smallexample
-@group
-/* File foo. */
-#ifndef FILE_FOO_SEEN
-#define FILE_FOO_SEEN
-
-@var{the entire file}
-
-#endif /* !FILE_FOO_SEEN */
-@end group
-@end smallexample
-
-This construct is commonly known as a @dfn{wrapper #ifndef}.
-When the header is included again, the conditional will be false,
-because @code{FILE_FOO_SEEN} is defined. The preprocessor will skip
-over the entire contents of the file, and the compiler will not see it
-twice.
-
-CPP optimizes even further. It remembers when a header file has a
-wrapper @samp{#ifndef}. If a subsequent @samp{#include} specifies that
-header, and the macro in the @samp{#ifndef} is still defined, it does
-not bother to rescan the file at all.
-
-You can put comments outside the wrapper. They will not interfere with
-this optimization.
-
-@cindex controlling macro
-@cindex guard macro
-The macro @code{FILE_FOO_SEEN} is called the @dfn{controlling macro} or
-@dfn{guard macro}. In a user header file, the macro name should not
-begin with @samp{_}. In a system header file, it should begin with
-@samp{__} to avoid conflicts with user programs. In any kind of header
-file, the macro name should contain the name of the file and some
-additional text, to avoid conflicts with other header files.
-
-@node Alternatives to Wrapper #ifndef
-@section Alternatives to Wrapper #ifndef
-
-CPP supports two more ways of indicating that a header file should be
-read only once. Neither one is as portable as a wrapper @samp{#ifndef}
-and we recommend you do not use them in new programs, with the caveat
-that @samp{#import} is standard practice in Objective-C.
-
-@findex #import
-CPP supports a variant of @samp{#include} called @samp{#import} which
-includes a file, but does so at most once. If you use @samp{#import}
-instead of @samp{#include}, then you don't need the conditionals
-inside the header file to prevent multiple inclusion of the contents.
-@samp{#import} is standard in Objective-C, but is considered a
-deprecated extension in C and C++.
-
-@samp{#import} is not a well designed feature. It requires the users of
-a header file to know that it should only be included once. It is much
-better for the header file's implementor to write the file so that users
-don't need to know this. Using a wrapper @samp{#ifndef} accomplishes
-this goal.
-
-In the present implementation, a single use of @samp{#import} will
-prevent the file from ever being read again, by either @samp{#import} or
-@samp{#include}. You should not rely on this; do not use both
-@samp{#import} and @samp{#include} to refer to the same header file.
-
-Another way to prevent a header file from being included more than once
-is with the @samp{#pragma once} directive (@pxref{Pragmas}).
-@samp{#pragma once} does not have the problems that @samp{#import} does,
-but it is not recognized by all preprocessors, so you cannot rely on it
-in a portable program.
-
-@node Computed Includes
-@section Computed Includes
-@cindex computed includes
-@cindex macros in include
-
-Sometimes it is necessary to select one of several different header
-files to be included into your program. They might specify
-configuration parameters to be used on different sorts of operating
-systems, for instance. You could do this with a series of conditionals,
-
-@smallexample
-#if SYSTEM_1
-# include "system_1.h"
-#elif SYSTEM_2
-# include "system_2.h"
-#elif SYSTEM_3
-@dots{}
-#endif
-@end smallexample
-
-That rapidly becomes tedious. Instead, the preprocessor offers the
-ability to use a macro for the header name. This is called a
-@dfn{computed include}. Instead of writing a header name as the direct
-argument of @samp{#include}, you simply put a macro name there instead:
-
-@smallexample
-#define SYSTEM_H "system_1.h"
-@dots{}
-#include SYSTEM_H
-@end smallexample
-
-@noindent
-@code{SYSTEM_H} will be expanded, and the preprocessor will look for
-@file{system_1.h} as if the @samp{#include} had been written that way
-originally. @code{SYSTEM_H} could be defined by your Makefile with a
-@option{-D} option.
-
-You must be careful when you define the macro. @samp{#define} saves
-tokens, not text. The preprocessor has no way of knowing that the macro
-will be used as the argument of @samp{#include}, so it generates
-ordinary tokens, not a header name. This is unlikely to cause problems
-if you use double-quote includes, which are close enough to string
-constants. If you use angle brackets, however, you may have trouble.
-
-The syntax of a computed include is actually a bit more general than the
-above. If the first non-whitespace character after @samp{#include} is
-not @samp{"} or @samp{<}, then the entire line is macro-expanded
-like running text would be.
-
-If the line expands to a single string constant, the contents of that
-string constant are the file to be included. CPP does not re-examine the
-string for embedded quotes, but neither does it process backslash
-escapes in the string. Therefore
-
-@smallexample
-#define HEADER "a\"b"
-#include HEADER
-@end smallexample
-
-@noindent
-looks for a file named @file{a\"b}. CPP searches for the file according
-to the rules for double-quoted includes.
-
-If the line expands to a token stream beginning with a @samp{<} token
-and including a @samp{>} token, then the tokens between the @samp{<} and
-the first @samp{>} are combined to form the filename to be included.
-Any whitespace between tokens is reduced to a single space; then any
-space after the initial @samp{<} is retained, but a trailing space
-before the closing @samp{>} is ignored. CPP searches for the file
-according to the rules for angle-bracket includes.
-
-In either case, if there are any tokens on the line after the file name,
-an error occurs and the directive is not processed. It is also an error
-if the result of expansion does not match either of the two expected
-forms.
-
-These rules are implementation-defined behavior according to the C
-standard. To minimize the risk of different compilers interpreting your
-computed includes differently, we recommend you use only a single
-object-like macro which expands to a string constant. This will also
-minimize confusion for people reading your program.
-
-@node Wrapper Headers
-@section Wrapper Headers
-@cindex wrapper headers
-@cindex overriding a header file
-@findex #include_next
-
-Sometimes it is necessary to adjust the contents of a system-provided
-header file without editing it directly. GCC's @command{fixincludes}
-operation does this, for example. One way to do that would be to create
-a new header file with the same name and insert it in the search path
-before the original header. That works fine as long as you're willing
-to replace the old header entirely. But what if you want to refer to
-the old header from the new one?
-
-You cannot simply include the old header with @samp{#include}. That
-will start from the beginning, and find your new header again. If your
-header is not protected from multiple inclusion (@pxref{Once-Only
-Headers}), it will recurse infinitely and cause a fatal error.
-
-You could include the old header with an absolute pathname:
-@smallexample
-#include "/usr/include/old-header.h"
-@end smallexample
-@noindent
-This works, but is not clean; should the system headers ever move, you
-would have to edit the new headers to match.
-
-There is no way to solve this problem within the C standard, but you can
-use the GNU extension @samp{#include_next}. It means, ``Include the
-@emph{next} file with this name''. This directive works like
-@samp{#include} except in searching for the specified file: it starts
-searching the list of header file directories @emph{after} the directory
-in which the current file was found.
-
-Suppose you specify @option{-I /usr/local/include}, and the list of
-directories to search also includes @file{/usr/include}; and suppose
-both directories contain @file{signal.h}. Ordinary @code{@w{#include
-<signal.h>}} finds the file under @file{/usr/local/include}. If that
-file contains @code{@w{#include_next <signal.h>}}, it starts searching
-after that directory, and finds the file in @file{/usr/include}.
-
-@samp{#include_next} does not distinguish between @code{<@var{file}>}
-and @code{"@var{file}"} inclusion, nor does it check that the file you
-specify has the same name as the current file. It simply looks for the
-file named, starting with the directory in the search path after the one
-where the current file was found.
-
-The use of @samp{#include_next} can lead to great confusion. We
-recommend it be used only when there is no other alternative. In
-particular, it should not be used in the headers belonging to a specific
-program; it should be used only to make global corrections along the
-lines of @command{fixincludes}.
-
-@node System Headers
-@section System Headers
-@cindex system header files
-
-The header files declaring interfaces to the operating system and
-runtime libraries often cannot be written in strictly conforming C@.
-Therefore, GCC gives code found in @dfn{system headers} special
-treatment. All warnings, other than those generated by @samp{#warning}
-(@pxref{Diagnostics}), are suppressed while GCC is processing a system
-header. Macros defined in a system header are immune to a few warnings
-wherever they are expanded. This immunity is granted on an ad-hoc
-basis, when we find that a warning generates lots of false positives
-because of code in macros defined in system headers.
-
-Normally, only the headers found in specific directories are considered
-system headers. These directories are determined when GCC is compiled.
-There are, however, two ways to make normal headers into system headers:
-
-@itemize @bullet
-@item
-Header files found in directories added to the search path with the
-@option{-isystem} and @option{-idirafter} command-line options are
-treated as system headers for the purposes of diagnostics.
-
-@item
-@findex #pragma GCC system_header
-There is also a directive, @code{@w{#pragma GCC system_header}}, which
-tells GCC to consider the rest of the current include file a system
-header, no matter where it was found. Code that comes before the
-@samp{#pragma} in the file is not affected. @code{@w{#pragma GCC
-system_header}} has no effect in the primary source file.
-@end itemize
-
-On some targets, such as RS/6000 AIX, GCC implicitly surrounds all
-system headers with an @samp{extern "C"} block when compiling as C++.
-
-@node Macros
-@chapter Macros
-
-A @dfn{macro} is a fragment of code which has been given a name.
-Whenever the name is used, it is replaced by the contents of the macro.
-There are two kinds of macros. They differ mostly in what they look
-like when they are used. @dfn{Object-like} macros resemble data objects
-when used, @dfn{function-like} macros resemble function calls.
-
-You may define any valid identifier as a macro, even if it is a C
-keyword. The preprocessor does not know anything about keywords. This
-can be useful if you wish to hide a keyword such as @code{const} from an
-older compiler that does not understand it. However, the preprocessor
-operator @code{defined} (@pxref{Defined}) can never be defined as a
-macro, and C++'s named operators (@pxref{C++ Named Operators}) cannot be
-macros when you are compiling C++.
-
-@menu
-* Object-like Macros::
-* Function-like Macros::
-* Macro Arguments::
-* Stringizing::
-* Concatenation::
-* Variadic Macros::
-* Predefined Macros::
-* Undefining and Redefining Macros::
-* Directives Within Macro Arguments::
-* Macro Pitfalls::
-@end menu
-
-@node Object-like Macros
-@section Object-like Macros
-@cindex object-like macro
-@cindex symbolic constants
-@cindex manifest constants
-
-An @dfn{object-like macro} is a simple identifier which will be replaced
-by a code fragment. It is called object-like because it looks like a
-data object in code that uses it. They are most commonly used to give
-symbolic names to numeric constants.
-
-@findex #define
-You create macros with the @samp{#define} directive. @samp{#define} is
-followed by the name of the macro and then the token sequence it should
-be an abbreviation for, which is variously referred to as the macro's
-@dfn{body}, @dfn{expansion} or @dfn{replacement list}. For example,
-
-@smallexample
-#define BUFFER_SIZE 1024
-@end smallexample
-
-@noindent
-defines a macro named @code{BUFFER_SIZE} as an abbreviation for the
-token @code{1024}. If somewhere after this @samp{#define} directive
-there comes a C statement of the form
-
-@smallexample
-foo = (char *) malloc (BUFFER_SIZE);
-@end smallexample
-
-@noindent
-then the C preprocessor will recognize and @dfn{expand} the macro
-@code{BUFFER_SIZE}. The C compiler will see the same tokens as it would
-if you had written
-
-@smallexample
-foo = (char *) malloc (1024);
-@end smallexample
-
-By convention, macro names are written in uppercase. Programs are
-easier to read when it is possible to tell at a glance which names are
-macros.
-
-The macro's body ends at the end of the @samp{#define} line. You may
-continue the definition onto multiple lines, if necessary, using
-backslash-newline. When the macro is expanded, however, it will all
-come out on one line. For example,
-
-@smallexample
-#define NUMBERS 1, \
- 2, \
- 3
-int x[] = @{ NUMBERS @};
- @expansion{} int x[] = @{ 1, 2, 3 @};
-@end smallexample
-
-@noindent
-The most common visible consequence of this is surprising line numbers
-in error messages.
-
-There is no restriction on what can go in a macro body provided it
-decomposes into valid preprocessing tokens. Parentheses need not
-balance, and the body need not resemble valid C code. (If it does not,
-you may get error messages from the C compiler when you use the macro.)
-
-The C preprocessor scans your program sequentially. Macro definitions
-take effect at the place you write them. Therefore, the following input
-to the C preprocessor
-
-@smallexample
-foo = X;
-#define X 4
-bar = X;
-@end smallexample
-
-@noindent
-produces
-
-@smallexample
-foo = X;
-bar = 4;
-@end smallexample
-
-When the preprocessor expands a macro name, the macro's expansion
-replaces the macro invocation, then the expansion is examined for more
-macros to expand. For example,
-
-@smallexample
-@group
-#define TABLESIZE BUFSIZE
-#define BUFSIZE 1024
-TABLESIZE
- @expansion{} BUFSIZE
- @expansion{} 1024
-@end group
-@end smallexample
-
-@noindent
-@code{TABLESIZE} is expanded first to produce @code{BUFSIZE}, then that
-macro is expanded to produce the final result, @code{1024}.
-
-Notice that @code{BUFSIZE} was not defined when @code{TABLESIZE} was
-defined. The @samp{#define} for @code{TABLESIZE} uses exactly the
-expansion you specify---in this case, @code{BUFSIZE}---and does not
-check to see whether it too contains macro names. Only when you
-@emph{use} @code{TABLESIZE} is the result of its expansion scanned for
-more macro names.
-
-This makes a difference if you change the definition of @code{BUFSIZE}
-at some point in the source file. @code{TABLESIZE}, defined as shown,
-will always expand using the definition of @code{BUFSIZE} that is
-currently in effect:
-
-@smallexample
-#define BUFSIZE 1020
-#define TABLESIZE BUFSIZE
-#undef BUFSIZE
-#define BUFSIZE 37
-@end smallexample
-
-@noindent
-Now @code{TABLESIZE} expands (in two stages) to @code{37}.
-
-If the expansion of a macro contains its own name, either directly or
-via intermediate macros, it is not expanded again when the expansion is
-examined for more macros. This prevents infinite recursion.
-@xref{Self-Referential Macros}, for the precise details.
-
-@node Function-like Macros
-@section Function-like Macros
-@cindex function-like macros
-
-You can also define macros whose use looks like a function call. These
-are called @dfn{function-like macros}. To define a function-like macro,
-you use the same @samp{#define} directive, but you put a pair of
-parentheses immediately after the macro name. For example,
-
-@smallexample
-#define lang_init() c_init()
-lang_init()
- @expansion{} c_init()
-@end smallexample
-
-A function-like macro is only expanded if its name appears with a pair
-of parentheses after it. If you write just the name, it is left alone.
-This can be useful when you have a function and a macro of the same
-name, and you wish to use the function sometimes.
-
-@smallexample
-extern void foo(void);
-#define foo() /* @r{optimized inline version} */
-@dots{}
- foo();
- funcptr = foo;
-@end smallexample
-
-Here the call to @code{foo()} will use the macro, but the function
-pointer will get the address of the real function. If the macro were to
-be expanded, it would cause a syntax error.
-
-If you put spaces between the macro name and the parentheses in the
-macro definition, that does not define a function-like macro, it defines
-an object-like macro whose expansion happens to begin with a pair of
-parentheses.
-
-@smallexample
-#define lang_init () c_init()
-lang_init()
- @expansion{} () c_init()()
-@end smallexample
-
-The first two pairs of parentheses in this expansion come from the
-macro. The third is the pair that was originally after the macro
-invocation. Since @code{lang_init} is an object-like macro, it does not
-consume those parentheses.
-
-@node Macro Arguments
-@section Macro Arguments
-@cindex arguments
-@cindex macros with arguments
-@cindex arguments in macro definitions
-
-Function-like macros can take @dfn{arguments}, just like true functions.
-To define a macro that uses arguments, you insert @dfn{parameters}
-between the pair of parentheses in the macro definition that make the
-macro function-like. The parameters must be valid C identifiers,
-separated by commas and optionally whitespace.
-
-To invoke a macro that takes arguments, you write the name of the macro
-followed by a list of @dfn{actual arguments} in parentheses, separated
-by commas. The invocation of the macro need not be restricted to a
-single logical line---it can cross as many lines in the source file as
-you wish. The number of arguments you give must match the number of
-parameters in the macro definition. When the macro is expanded, each
-use of a parameter in its body is replaced by the tokens of the
-corresponding argument. (You need not use all of the parameters in the
-macro body.)
-
-As an example, here is a macro that computes the minimum of two numeric
-values, as it is defined in many C programs, and some uses.
-
-@smallexample
-#define min(X, Y) ((X) < (Y) ? (X) : (Y))
- x = min(a, b); @expansion{} x = ((a) < (b) ? (a) : (b));
- y = min(1, 2); @expansion{} y = ((1) < (2) ? (1) : (2));
- z = min(a + 28, *p); @expansion{} z = ((a + 28) < (*p) ? (a + 28) : (*p));
-@end smallexample
-
-@noindent
-(In this small example you can already see several of the dangers of
-macro arguments. @xref{Macro Pitfalls}, for detailed explanations.)
-
-Leading and trailing whitespace in each argument is dropped, and all
-whitespace between the tokens of an argument is reduced to a single
-space. Parentheses within each argument must balance; a comma within
-such parentheses does not end the argument. However, there is no
-requirement for square brackets or braces to balance, and they do not
-prevent a comma from separating arguments. Thus,
-
-@smallexample
-macro (array[x = y, x + 1])
-@end smallexample
-
-@noindent
-passes two arguments to @code{macro}: @code{array[x = y} and @code{x +
-1]}. If you want to supply @code{array[x = y, x + 1]} as an argument,
-you can write it as @code{array[(x = y, x + 1)]}, which is equivalent C
-code.
-
-All arguments to a macro are completely macro-expanded before they are
-substituted into the macro body. After substitution, the complete text
-is scanned again for macros to expand, including the arguments. This rule
-may seem strange, but it is carefully designed so you need not worry
-about whether any function call is actually a macro invocation. You can
-run into trouble if you try to be too clever, though. @xref{Argument
-Prescan}, for detailed discussion.
-
-For example, @code{min (min (a, b), c)} is first expanded to
-
-@smallexample
- min (((a) < (b) ? (a) : (b)), (c))
-@end smallexample
-
-@noindent
-and then to
-
-@smallexample
-@group
-((((a) < (b) ? (a) : (b))) < (c)
- ? (((a) < (b) ? (a) : (b)))
- : (c))
-@end group
-@end smallexample
-
-@noindent
-(Line breaks shown here for clarity would not actually be generated.)
-
-@cindex empty macro arguments
-You can leave macro arguments empty; this is not an error to the
-preprocessor (but many macros will then expand to invalid code).
-You cannot leave out arguments entirely; if a macro takes two arguments,
-there must be exactly one comma at the top level of its argument list.
-Here are some silly examples using @code{min}:
-
-@smallexample
-min(, b) @expansion{} (( ) < (b) ? ( ) : (b))
-min(a, ) @expansion{} ((a ) < ( ) ? (a ) : ( ))
-min(,) @expansion{} (( ) < ( ) ? ( ) : ( ))
-min((,),) @expansion{} (((,)) < ( ) ? ((,)) : ( ))
-
-min() @error{} macro "min" requires 2 arguments, but only 1 given
-min(,,) @error{} macro "min" passed 3 arguments, but takes just 2
-@end smallexample
-
-Whitespace is not a preprocessing token, so if a macro @code{foo} takes
-one argument, @code{@w{foo ()}} and @code{@w{foo ( )}} both supply it an
-empty argument. Previous GNU preprocessor implementations and
-documentation were incorrect on this point, insisting that a
-function-like macro that takes a single argument be passed a space if an
-empty argument was required.
-
-Macro parameters appearing inside string literals are not replaced by
-their corresponding actual arguments.
-
-@smallexample
-#define foo(x) x, "x"
-foo(bar) @expansion{} bar, "x"
-@end smallexample
-
-@node Stringizing
-@section Stringizing
-@cindex stringizing
-@cindex @samp{#} operator
-
-Sometimes you may want to convert a macro argument into a string
-constant. Parameters are not replaced inside string constants, but you
-can use the @samp{#} preprocessing operator instead. When a macro
-parameter is used with a leading @samp{#}, the preprocessor replaces it
-with the literal text of the actual argument, converted to a string
-constant. Unlike normal parameter replacement, the argument is not
-macro-expanded first. This is called @dfn{stringizing}.
-
-There is no way to combine an argument with surrounding text and
-stringize it all together. Instead, you can write a series of adjacent
-string constants and stringized arguments. The preprocessor
-replaces the stringized arguments with string constants. The C
-compiler then combines all the adjacent string constants into one
-long string.
-
-Here is an example of a macro definition that uses stringizing:
-
-@smallexample
-@group
-#define WARN_IF(EXP) \
-do @{ if (EXP) \
- fprintf (stderr, "Warning: " #EXP "\n"); @} \
-while (0)
-WARN_IF (x == 0);
- @expansion{} do @{ if (x == 0)
- fprintf (stderr, "Warning: " "x == 0" "\n"); @} while (0);
-@end group
-@end smallexample
-
-@noindent
-The argument for @code{EXP} is substituted once, as-is, into the
-@code{if} statement, and once, stringized, into the argument to
-@code{fprintf}. If @code{x} were a macro, it would be expanded in the
-@code{if} statement, but not in the string.
-
-The @code{do} and @code{while (0)} are a kludge to make it possible to
-write @code{WARN_IF (@var{arg});}, which the resemblance of
-@code{WARN_IF} to a function would make C programmers want to do; see
-@ref{Swallowing the Semicolon}.
-
-Stringizing in C involves more than putting double-quote characters
-around the fragment. The preprocessor backslash-escapes the quotes
-surrounding embedded string constants, and all backslashes within string and
-character constants, in order to get a valid C string constant with the
-proper contents. Thus, stringizing @code{@w{p = "foo\n";}} results in
-@t{@w{"p = \"foo\\n\";"}}. However, backslashes that are not inside string
-or character constants are not duplicated: @samp{\n} by itself
-stringizes to @t{"\n"}.
-
-All leading and trailing whitespace in text being stringized is
-ignored. Any sequence of whitespace in the middle of the text is
-converted to a single space in the stringized result. Comments are
-replaced by whitespace long before stringizing happens, so they
-never appear in stringized text.
-
-There is no way to convert a macro argument into a character constant.
-
-If you want to stringize the result of expansion of a macro argument,
-you have to use two levels of macros.
-
-@smallexample
-#define xstr(s) str(s)
-#define str(s) #s
-#define foo 4
-str (foo)
- @expansion{} "foo"
-xstr (foo)
- @expansion{} xstr (4)
- @expansion{} str (4)
- @expansion{} "4"
-@end smallexample
-
-@code{s} is stringized when it is used in @code{str}, so it is not
-macro-expanded first. But @code{s} is an ordinary argument to
-@code{xstr}, so it is completely macro-expanded before @code{xstr}
-itself is expanded (@pxref{Argument Prescan}). Therefore, by the time
-@code{str} gets to its argument, it has already been macro-expanded.
-
-@node Concatenation
-@section Concatenation
-@cindex concatenation
-@cindex token pasting
-@cindex token concatenation
-@cindex @samp{##} operator
-
-It is often useful to merge two tokens into one while expanding macros.
-This is called @dfn{token pasting} or @dfn{token concatenation}. The
-@samp{##} preprocessing operator performs token pasting. When a macro
-is expanded, the two tokens on either side of each @samp{##} operator
-are combined into a single token, which then replaces the @samp{##} and
-the two original tokens in the macro expansion. Usually both will be
-identifiers, or one will be an identifier and the other a preprocessing
-number. When pasted, they make a longer identifier. This isn't the
-only valid case. It is also possible to concatenate two numbers (or a
-number and a name, such as @code{1.5} and @code{e3}) into a number.
-Also, multi-character operators such as @code{+=} can be formed by
-token pasting.
-
-However, two tokens that don't together form a valid token cannot be
-pasted together. For example, you cannot concatenate @code{x} with
-@code{+} in either order. If you try, the preprocessor issues a warning
-and emits the two tokens. Whether it puts white space between the
-tokens is undefined. It is common to find unnecessary uses of @samp{##}
-in complex macros. If you get this warning, it is likely that you can
-simply remove the @samp{##}.
-
-Both the tokens combined by @samp{##} could come from the macro body,
-but you could just as well write them as one token in the first place.
-Token pasting is most useful when one or both of the tokens comes from a
-macro argument. If either of the tokens next to an @samp{##} is a
-parameter name, it is replaced by its actual argument before @samp{##}
-executes. As with stringizing, the actual argument is not
-macro-expanded first. If the argument is empty, that @samp{##} has no
-effect.
-
-Keep in mind that the C preprocessor converts comments to whitespace
-before macros are even considered. Therefore, you cannot create a
-comment by concatenating @samp{/} and @samp{*}. You can put as much
-whitespace between @samp{##} and its operands as you like, including
-comments, and you can put comments in arguments that will be
-concatenated. However, it is an error if @samp{##} appears at either
-end of a macro body.
-
-Consider a C program that interprets named commands. There probably
-needs to be a table of commands, perhaps an array of structures declared
-as follows:
-
-@smallexample
-@group
-struct command
-@{
- char *name;
- void (*function) (void);
-@};
-@end group
-
-@group
-struct command commands[] =
-@{
- @{ "quit", quit_command @},
- @{ "help", help_command @},
- @dots{}
-@};
-@end group
-@end smallexample
-
-It would be cleaner not to have to give each command name twice, once in
-the string constant and once in the function name. A macro which takes the
-name of a command as an argument can make this unnecessary. The string
-constant can be created with stringizing, and the function name by
-concatenating the argument with @samp{_command}. Here is how it is done:
-
-@smallexample
-#define COMMAND(NAME) @{ #NAME, NAME ## _command @}
-
-struct command commands[] =
-@{
- COMMAND (quit),
- COMMAND (help),
- @dots{}
-@};
-@end smallexample
-
-@node Variadic Macros
-@section Variadic Macros
-@cindex variable number of arguments
-@cindex macros with variable arguments
-@cindex variadic macros
-
-A macro can be declared to accept a variable number of arguments much as
-a function can. The syntax for defining the macro is similar to that of
-a function. Here is an example:
-
-@smallexample
-#define eprintf(...) fprintf (stderr, __VA_ARGS__)
-@end smallexample
-
-This kind of macro is called @dfn{variadic}. When the macro is invoked,
-all the tokens in its argument list after the last named argument (this
-macro has none), including any commas, become the @dfn{variable
-argument}. This sequence of tokens replaces the identifier
-@code{@w{__VA_ARGS__}} in the macro body wherever it appears. Thus, we
-have this expansion:
-
-@smallexample
-eprintf ("%s:%d: ", input_file, lineno)
- @expansion{} fprintf (stderr, "%s:%d: ", input_file, lineno)
-@end smallexample
-
-The variable argument is completely macro-expanded before it is inserted
-into the macro expansion, just like an ordinary argument. You may use
-the @samp{#} and @samp{##} operators to stringize the variable argument
-or to paste its leading or trailing token with another token. (But see
-below for an important special case for @samp{##}.)
-
-If your macro is complicated, you may want a more descriptive name for
-the variable argument than @code{@w{__VA_ARGS__}}. CPP permits
-this, as an extension. You may write an argument name immediately
-before the @samp{...}; that name is used for the variable argument.
-The @code{eprintf} macro above could be written
-
-@smallexample
-#define eprintf(args...) fprintf (stderr, args)
-@end smallexample
-
-@noindent
-using this extension. You cannot use @code{@w{__VA_ARGS__}} and this
-extension in the same macro.
-
-You can have named arguments as well as variable arguments in a variadic
-macro. We could define @code{eprintf} like this, instead:
-
-@smallexample
-#define eprintf(format, ...) fprintf (stderr, format, __VA_ARGS__)
-@end smallexample
-
-@noindent
-This formulation looks more descriptive, but historically it was less
-flexible: you had to supply at least one argument after the format
-string. In standard C, you could not omit the comma separating the
-named argument from the variable arguments. (Note that this
-restriction has been lifted in C++20, and never existed in GNU C; see
-below.)
-
-Furthermore, if you left the variable argument empty, you would have
-gotten a syntax error, because there would have been an extra comma
-after the format string.
-
-@smallexample
-eprintf("success!\n", );
- @expansion{} fprintf(stderr, "success!\n", );
-@end smallexample
-
-This has been fixed in C++20, and GNU CPP also has a pair of
-extensions which deal with this problem.
-
-First, in GNU CPP, and in C++ beginning in C++20, you are allowed to
-leave the variable argument out entirely:
-
-@smallexample
-eprintf ("success!\n")
- @expansion{} fprintf(stderr, "success!\n", );
-@end smallexample
-
-@noindent
-Second, C++20 introduces the @code{@w{__VA_OPT__}} function macro.
-This macro may only appear in the definition of a variadic macro. If
-the variable argument has any tokens, then a @code{@w{__VA_OPT__}}
-invocation expands to its argument; but if the variable argument does
-not have any tokens, the @code{@w{__VA_OPT__}} expands to nothing:
-
-@smallexample
-#define eprintf(format, ...) \
- fprintf (stderr, format __VA_OPT__(,) __VA_ARGS__)
-@end smallexample
-
-@code{@w{__VA_OPT__}} is also available in GNU C and GNU C++.
-
-Historically, GNU CPP has also had another extension to handle the
-trailing comma: the @samp{##} token paste operator has a special
-meaning when placed between a comma and a variable argument. Despite
-the introduction of @code{@w{__VA_OPT__}}, this extension remains
-supported in GNU CPP, for backward compatibility. If you write
-
-@smallexample
-#define eprintf(format, ...) fprintf (stderr, format, ##__VA_ARGS__)
-@end smallexample
-
-@noindent
-and the variable argument is left out when the @code{eprintf} macro is
-used, then the comma before the @samp{##} will be deleted. This does
-@emph{not} happen if you pass an empty argument, nor does it happen if
-the token preceding @samp{##} is anything other than a comma.
-
-@smallexample
-eprintf ("success!\n")
- @expansion{} fprintf(stderr, "success!\n");
-@end smallexample
-
-@noindent
-The above explanation is ambiguous about the case where the only macro
-parameter is a variable arguments parameter, as it is meaningless to
-try to distinguish whether no argument at all is an empty argument or
-a missing argument.
-CPP retains the comma when conforming to a specific C
-standard. Otherwise the comma is dropped as an extension to the standard.
-
-The C standard
-mandates that the only place the identifier @code{@w{__VA_ARGS__}}
-can appear is in the replacement list of a variadic macro. It may not
-be used as a macro name, macro argument name, or within a different type
-of macro. It may also be forbidden in open text; the standard is
-ambiguous. We recommend you avoid using it except for its defined
-purpose.
-
-Likewise, C++ forbids @code{@w{__VA_OPT__}} anywhere outside the
-replacement list of a variadic macro.
-
-Variadic macros became a standard part of the C language with C99.
-GNU CPP previously supported them
-with a named variable argument
-(@samp{args...}, not @samp{...} and @code{@w{__VA_ARGS__}}), which
-is still supported for backward compatibility.
-
-@node Predefined Macros
-@section Predefined Macros
-
-@cindex predefined macros
-Several object-like macros are predefined; you use them without
-supplying their definitions. They fall into three classes: standard,
-common, and system-specific.
-
-In C++, there is a fourth category, the named operators. They act like
-predefined macros, but you cannot undefine them.
-
-@menu
-* Standard Predefined Macros::
-* Common Predefined Macros::
-* System-specific Predefined Macros::
-* C++ Named Operators::
-@end menu
-
-@node Standard Predefined Macros
-@subsection Standard Predefined Macros
-@cindex standard predefined macros.
-
-The standard predefined macros are specified by the relevant
-language standards, so they are available with all compilers that
-implement those standards. Older compilers may not provide all of
-them. Their names all start with double underscores.
-
-@table @code
-@item __FILE__
-This macro expands to the name of the current input file, in the form of
-a C string constant. This is the path by which the preprocessor opened
-the file, not the short name specified in @samp{#include} or as the
-input file name argument. For example,
-@code{"/usr/local/include/myheader.h"} is a possible expansion of this
-macro.
-
-@item __LINE__
-This macro expands to the current input line number, in the form of a
-decimal integer constant. While we call it a predefined macro, it's
-a pretty strange macro, since its ``definition'' changes with each
-new line of source code.
-@end table
-
-@code{__FILE__} and @code{__LINE__} are useful in generating an error
-message to report an inconsistency detected by the program; the message
-can state the source line at which the inconsistency was detected. For
-example,
-
-@smallexample
-fprintf (stderr, "Internal error: "
- "negative string length "
- "%d at %s, line %d.",
- length, __FILE__, __LINE__);
-@end smallexample
-
-An @samp{#include} directive changes the expansions of @code{__FILE__}
-and @code{__LINE__} to correspond to the included file. At the end of
-that file, when processing resumes on the input file that contained
-the @samp{#include} directive, the expansions of @code{__FILE__} and
-@code{__LINE__} revert to the values they had before the
-@samp{#include} (but @code{__LINE__} is then incremented by one as
-processing moves to the line after the @samp{#include}).
-
-A @samp{#line} directive changes @code{__LINE__}, and may change
-@code{__FILE__} as well. @xref{Line Control}.
-
-C99 introduced @code{__func__}, and GCC has provided @code{__FUNCTION__}
-for a long time. Both of these are strings containing the name of the
-current function (there are slight semantic differences; see the GCC
-manual). Neither of them is a macro; the preprocessor does not know the
-name of the current function. They tend to be useful in conjunction
-with @code{__FILE__} and @code{__LINE__}, though.
-
-@table @code
-
-@item __DATE__
-This macro expands to a string constant that describes the date on which
-the preprocessor is being run. The string constant contains eleven
-characters and looks like @code{@w{"Feb 12 1996"}}. If the day of the
-month is less than 10, it is padded with a space on the left.
-
-If GCC cannot determine the current date, it will emit a warning message
-(once per compilation) and @code{__DATE__} will expand to
-@code{@w{"??? ?? ????"}}.
-
-@item __TIME__
-This macro expands to a string constant that describes the time at
-which the preprocessor is being run. The string constant contains
-eight characters and looks like @code{"23:59:01"}.
-
-If GCC cannot determine the current time, it will emit a warning message
-(once per compilation) and @code{__TIME__} will expand to
-@code{"??:??:??"}.
-
-@item __STDC__
-In normal operation, this macro expands to the constant 1, to signify
-that this compiler conforms to ISO Standard C@. If GNU CPP is used with
-a compiler other than GCC, this is not necessarily true; however, the
-preprocessor always conforms to the standard unless the
-@option{-traditional-cpp} option is used.
-
-This macro is not defined if the @option{-traditional-cpp} option is used.
-
-On some hosts, the system compiler uses a different convention, where
-@code{__STDC__} is normally 0, but is 1 if the user specifies strict
-conformance to the C Standard. CPP follows the host convention when
-processing system header files, but when processing user files
-@code{__STDC__} is always 1. This has been reported to cause problems;
-for instance, some versions of Solaris provide X Windows headers that
-expect @code{__STDC__} to be either undefined or 1. @xref{Invocation}.
-
-@item __STDC_VERSION__
-This macro expands to the C Standard's version number, a long integer
-constant of the form @code{@var{yyyy}@var{mm}L} where @var{yyyy} and
-@var{mm} are the year and month of the Standard version. This signifies
-which version of the C Standard the compiler conforms to. Like
-@code{__STDC__}, this is not necessarily accurate for the entire
-implementation, unless GNU CPP is being used with GCC@.
-
-The value @code{199409L} signifies the 1989 C standard as amended in
-1994, which is the current default; the value @code{199901L} signifies
-the 1999 revision of the C standard; the value @code{201112L}
-signifies the 2011 revision of the C standard; the value
-@code{201710L} signifies the 2017 revision of the C standard (which is
-otherwise identical to the 2011 version apart from correction of
-defects). An unspecified value larger than @code{201710L} is used for
-the experimental @option{-std=c2x} and @option{-std=gnu2x} modes.
-
-This macro is not defined if the @option{-traditional-cpp} option is
-used, nor when compiling C++ or Objective-C@.
-
-@item __STDC_HOSTED__
-This macro is defined, with value 1, if the compiler's target is a
-@dfn{hosted environment}. A hosted environment has the complete
-facilities of the standard C library available.
-
-@item __cplusplus
-This macro is defined when the C++ compiler is in use. You can use
-@code{__cplusplus} to test whether a header is compiled by a C compiler
-or a C++ compiler. This macro is similar to @code{__STDC_VERSION__}, in
-that it expands to a version number. Depending on the language standard
-selected, the value of the macro is
-@code{199711L} for the 1998 C++ standard,
-@code{201103L} for the 2011 C++ standard,
-@code{201402L} for the 2014 C++ standard,
-@code{201703L} for the 2017 C++ standard,
-@code{202002L} for the 2020 C++ standard,
-or an unspecified value strictly larger than @code{202002L} for the
-experimental languages enabled by @option{-std=c++23} and
-@option{-std=gnu++23}.
-
-@item __OBJC__
-This macro is defined, with value 1, when the Objective-C compiler is in
-use. You can use @code{__OBJC__} to test whether a header is compiled
-by a C compiler or an Objective-C compiler.
-
-@item __ASSEMBLER__
-This macro is defined with value 1 when preprocessing assembly
-language.
-
-@end table
-
-@node Common Predefined Macros
-@subsection Common Predefined Macros
-@cindex common predefined macros
-
-The common predefined macros are GNU C extensions. They are available
-with the same meanings regardless of the machine or operating system on
-which you are using GNU C or GNU Fortran. Their names all start with
-double underscores.
-
-@table @code
-
-@item __COUNTER__
-This macro expands to sequential integral values starting from 0. In
-conjunction with the @code{##} operator, this provides a convenient means to
-generate unique identifiers. Care must be taken to ensure that
-@code{__COUNTER__} is not expanded prior to inclusion of precompiled headers
-which use it. Otherwise, the precompiled headers will not be used.
-
-@item __GFORTRAN__
-The GNU Fortran compiler defines this.
-
-@item __GNUC__
-@itemx __GNUC_MINOR__
-@itemx __GNUC_PATCHLEVEL__
-These macros are defined by all GNU compilers that use the C
-preprocessor: C, C++, Objective-C and Fortran. Their values are the major
-version, minor version, and patch level of the compiler, as integer
-constants. For example, GCC version @var{x}.@var{y}.@var{z}
-defines @code{__GNUC__} to @var{x}, @code{__GNUC_MINOR__} to @var{y},
-and @code{__GNUC_PATCHLEVEL__} to @var{z}. These
-macros are also defined if you invoke the preprocessor directly.
-
-If all you need to know is whether or not your program is being compiled
-by GCC, or a non-GCC compiler that claims to accept the GNU C dialects,
-you can simply test @code{__GNUC__}. If you need to write code
-which depends on a specific version, you must be more careful. Each
-time the minor version is increased, the patch level is reset to zero;
-each time the major version is increased, the
-minor version and patch level are reset. If you wish to use the
-predefined macros directly in the conditional, you will need to write it
-like this:
-
-@smallexample
-/* @r{Test for GCC > 3.2.0} */
-#if __GNUC__ > 3 || \
- (__GNUC__ == 3 && (__GNUC_MINOR__ > 2 || \
- (__GNUC_MINOR__ == 2 && \
- __GNUC_PATCHLEVEL__ > 0))
-@end smallexample
-
-@noindent
-Another approach is to use the predefined macros to
-calculate a single number, then compare that against a threshold:
-
-@smallexample
-#define GCC_VERSION (__GNUC__ * 10000 \
- + __GNUC_MINOR__ * 100 \
- + __GNUC_PATCHLEVEL__)
-@dots{}
-/* @r{Test for GCC > 3.2.0} */
-#if GCC_VERSION > 30200
-@end smallexample
-
-@noindent
-Many people find this form easier to understand.
-
-@item __GNUG__
-The GNU C++ compiler defines this. Testing it is equivalent to
-testing @code{@w{(__GNUC__ && __cplusplus)}}.
-
-@item __STRICT_ANSI__
-GCC defines this macro if and only if the @option{-ansi} switch, or a
-@option{-std} switch specifying strict conformance to some version of ISO C
-or ISO C++, was specified when GCC was invoked. It is defined to @samp{1}.
-This macro exists primarily to direct GNU libc's header files to use only
-definitions found in standard C.
-
-@item __BASE_FILE__
-This macro expands to the name of the main input file, in the form
-of a C string constant. This is the source file that was specified
-on the command line of the preprocessor or C compiler.
-
-@item __FILE_NAME__
-This macro expands to the basename of the current input file, in the
-form of a C string constant. This is the last path component by which
-the preprocessor opened the file. For example, processing
-@code{"/usr/local/include/myheader.h"} would set this
-macro to @code{"myheader.h"}.
-
-@item __INCLUDE_LEVEL__
-This macro expands to a decimal integer constant that represents the
-depth of nesting in include files. The value of this macro is
-incremented on every @samp{#include} directive and decremented at the
-end of every included file. It starts out at 0, its value within the
-base file specified on the command line.
-
-@item __ELF__
-This macro is defined if the target uses the ELF object format.
-
-@item __VERSION__
-This macro expands to a string constant which describes the version of
-the compiler in use. You should not rely on its contents having any
-particular form, but it can be counted on to contain at least the
-release number.
-
-@item __OPTIMIZE__
-@itemx __OPTIMIZE_SIZE__
-@itemx __NO_INLINE__
-These macros describe the compilation mode. @code{__OPTIMIZE__} is
-defined in all optimizing compilations. @code{__OPTIMIZE_SIZE__} is
-defined if the compiler is optimizing for size, not speed.
-@code{__NO_INLINE__} is defined if no functions will be inlined into
-their callers (when not optimizing, or when inlining has been
-specifically disabled by @option{-fno-inline}).
-
-These macros cause certain GNU header files to provide optimized
-definitions, using macros or inline functions, of system library
-functions. You should not use these macros in any way unless you make
-sure that programs will execute with the same effect whether or not they
-are defined. If they are defined, their value is 1.
-
-@item __GNUC_GNU_INLINE__
-GCC defines this macro if functions declared @code{inline} will be
-handled in GCC's traditional gnu90 mode. Object files will contain
-externally visible definitions of all functions declared @code{inline}
-without @code{extern} or @code{static}. They will not contain any
-definitions of any functions declared @code{extern inline}.
-
-@item __GNUC_STDC_INLINE__
-GCC defines this macro if functions declared @code{inline} will be
-handled according to the ISO C99 or later standards. Object files will contain
-externally visible definitions of all functions declared @code{extern
-inline}. They will not contain definitions of any functions declared
-@code{inline} without @code{extern}.
-
-If this macro is defined, GCC supports the @code{gnu_inline} function
-attribute as a way to always get the gnu90 behavior.
-
-@item __CHAR_UNSIGNED__
-GCC defines this macro if and only if the data type @code{char} is
-unsigned on the target machine. It exists to cause the standard header
-file @file{limits.h} to work correctly. You should not use this macro
-yourself; instead, refer to the standard macros defined in @file{limits.h}.
-
-@item __WCHAR_UNSIGNED__
-Like @code{__CHAR_UNSIGNED__}, this macro is defined if and only if the
-data type @code{wchar_t} is unsigned and the front-end is in C++ mode.
-
-@item __REGISTER_PREFIX__
-This macro expands to a single token (not a string constant) which is
-the prefix applied to CPU register names in assembly language for this
-target. You can use it to write assembly that is usable in multiple
-environments. For example, in the @code{m68k-aout} environment it
-expands to nothing, but in the @code{m68k-coff} environment it expands
-to a single @samp{%}.
-
-@item __USER_LABEL_PREFIX__
-This macro expands to a single token which is the prefix applied to
-user labels (symbols visible to C code) in assembly. For example, in
-the @code{m68k-aout} environment it expands to an @samp{_}, but in the
-@code{m68k-coff} environment it expands to nothing.
-
-This macro will have the correct definition even if
-@option{-f(no-)underscores} is in use, but it will not be correct if
-target-specific options that adjust this prefix are used (e.g.@: the
-OSF/rose @option{-mno-underscores} option).
-
-@item __SIZE_TYPE__
-@itemx __PTRDIFF_TYPE__
-@itemx __WCHAR_TYPE__
-@itemx __WINT_TYPE__
-@itemx __INTMAX_TYPE__
-@itemx __UINTMAX_TYPE__
-@itemx __SIG_ATOMIC_TYPE__
-@itemx __INT8_TYPE__
-@itemx __INT16_TYPE__
-@itemx __INT32_TYPE__
-@itemx __INT64_TYPE__
-@itemx __UINT8_TYPE__
-@itemx __UINT16_TYPE__
-@itemx __UINT32_TYPE__
-@itemx __UINT64_TYPE__
-@itemx __INT_LEAST8_TYPE__
-@itemx __INT_LEAST16_TYPE__
-@itemx __INT_LEAST32_TYPE__
-@itemx __INT_LEAST64_TYPE__
-@itemx __UINT_LEAST8_TYPE__
-@itemx __UINT_LEAST16_TYPE__
-@itemx __UINT_LEAST32_TYPE__
-@itemx __UINT_LEAST64_TYPE__
-@itemx __INT_FAST8_TYPE__
-@itemx __INT_FAST16_TYPE__
-@itemx __INT_FAST32_TYPE__
-@itemx __INT_FAST64_TYPE__
-@itemx __UINT_FAST8_TYPE__
-@itemx __UINT_FAST16_TYPE__
-@itemx __UINT_FAST32_TYPE__
-@itemx __UINT_FAST64_TYPE__
-@itemx __INTPTR_TYPE__
-@itemx __UINTPTR_TYPE__
-These macros are defined to the correct underlying types for the
-@code{size_t}, @code{ptrdiff_t}, @code{wchar_t}, @code{wint_t},
-@code{intmax_t}, @code{uintmax_t}, @code{sig_atomic_t}, @code{int8_t},
-@code{int16_t}, @code{int32_t}, @code{int64_t}, @code{uint8_t},
-@code{uint16_t}, @code{uint32_t}, @code{uint64_t},
-@code{int_least8_t}, @code{int_least16_t}, @code{int_least32_t},
-@code{int_least64_t}, @code{uint_least8_t}, @code{uint_least16_t},
-@code{uint_least32_t}, @code{uint_least64_t}, @code{int_fast8_t},
-@code{int_fast16_t}, @code{int_fast32_t}, @code{int_fast64_t},
-@code{uint_fast8_t}, @code{uint_fast16_t}, @code{uint_fast32_t},
-@code{uint_fast64_t}, @code{intptr_t}, and @code{uintptr_t} typedefs,
-respectively. They exist to make the standard header files
-@file{stddef.h}, @file{stdint.h}, and @file{wchar.h} work correctly.
-You should not use these macros directly; instead, include the
-appropriate headers and use the typedefs. Some of these macros may
-not be defined on particular systems if GCC does not provide a
-@file{stdint.h} header on those systems.
-
-@item __CHAR_BIT__
-Defined to the number of bits used in the representation of the
-@code{char} data type. It exists to make the standard header given
-numerical limits work correctly. You should not use
-this macro directly; instead, include the appropriate headers.
-
-@item __SCHAR_MAX__
-@itemx __WCHAR_MAX__
-@itemx __SHRT_MAX__
-@itemx __INT_MAX__
-@itemx __LONG_MAX__
-@itemx __LONG_LONG_MAX__
-@itemx __WINT_MAX__
-@itemx __SIZE_MAX__
-@itemx __PTRDIFF_MAX__
-@itemx __INTMAX_MAX__
-@itemx __UINTMAX_MAX__
-@itemx __SIG_ATOMIC_MAX__
-@itemx __INT8_MAX__
-@itemx __INT16_MAX__
-@itemx __INT32_MAX__
-@itemx __INT64_MAX__
-@itemx __UINT8_MAX__
-@itemx __UINT16_MAX__
-@itemx __UINT32_MAX__
-@itemx __UINT64_MAX__
-@itemx __INT_LEAST8_MAX__
-@itemx __INT_LEAST16_MAX__
-@itemx __INT_LEAST32_MAX__
-@itemx __INT_LEAST64_MAX__
-@itemx __UINT_LEAST8_MAX__
-@itemx __UINT_LEAST16_MAX__
-@itemx __UINT_LEAST32_MAX__
-@itemx __UINT_LEAST64_MAX__
-@itemx __INT_FAST8_MAX__
-@itemx __INT_FAST16_MAX__
-@itemx __INT_FAST32_MAX__
-@itemx __INT_FAST64_MAX__
-@itemx __UINT_FAST8_MAX__
-@itemx __UINT_FAST16_MAX__
-@itemx __UINT_FAST32_MAX__
-@itemx __UINT_FAST64_MAX__
-@itemx __INTPTR_MAX__
-@itemx __UINTPTR_MAX__
-@itemx __WCHAR_MIN__
-@itemx __WINT_MIN__
-@itemx __SIG_ATOMIC_MIN__
-Defined to the maximum value of the @code{signed char}, @code{wchar_t},
-@code{signed short},
-@code{signed int}, @code{signed long}, @code{signed long long},
-@code{wint_t}, @code{size_t}, @code{ptrdiff_t},
-@code{intmax_t}, @code{uintmax_t}, @code{sig_atomic_t}, @code{int8_t},
-@code{int16_t}, @code{int32_t}, @code{int64_t}, @code{uint8_t},
-@code{uint16_t}, @code{uint32_t}, @code{uint64_t},
-@code{int_least8_t}, @code{int_least16_t}, @code{int_least32_t},
-@code{int_least64_t}, @code{uint_least8_t}, @code{uint_least16_t},
-@code{uint_least32_t}, @code{uint_least64_t}, @code{int_fast8_t},
-@code{int_fast16_t}, @code{int_fast32_t}, @code{int_fast64_t},
-@code{uint_fast8_t}, @code{uint_fast16_t}, @code{uint_fast32_t},
-@code{uint_fast64_t}, @code{intptr_t}, and @code{uintptr_t} types and
-to the minimum value of the @code{wchar_t}, @code{wint_t}, and
-@code{sig_atomic_t} types respectively. They exist to make the
-standard header given numerical limits work correctly. You should not
-use these macros directly; instead, include the appropriate headers.
-Some of these macros may not be defined on particular systems if GCC
-does not provide a @file{stdint.h} header on those systems.
-
-@item __INT8_C
-@itemx __INT16_C
-@itemx __INT32_C
-@itemx __INT64_C
-@itemx __UINT8_C
-@itemx __UINT16_C
-@itemx __UINT32_C
-@itemx __UINT64_C
-@itemx __INTMAX_C
-@itemx __UINTMAX_C
-Defined to implementations of the standard @file{stdint.h} macros with
-the same names without the leading @code{__}. They exist the make the
-implementation of that header work correctly. You should not use
-these macros directly; instead, include the appropriate headers. Some
-of these macros may not be defined on particular systems if GCC does
-not provide a @file{stdint.h} header on those systems.
-
-@item __SCHAR_WIDTH__
-@itemx __SHRT_WIDTH__
-@itemx __INT_WIDTH__
-@itemx __LONG_WIDTH__
-@itemx __LONG_LONG_WIDTH__
-@itemx __PTRDIFF_WIDTH__
-@itemx __SIG_ATOMIC_WIDTH__
-@itemx __SIZE_WIDTH__
-@itemx __WCHAR_WIDTH__
-@itemx __WINT_WIDTH__
-@itemx __INT_LEAST8_WIDTH__
-@itemx __INT_LEAST16_WIDTH__
-@itemx __INT_LEAST32_WIDTH__
-@itemx __INT_LEAST64_WIDTH__
-@itemx __INT_FAST8_WIDTH__
-@itemx __INT_FAST16_WIDTH__
-@itemx __INT_FAST32_WIDTH__
-@itemx __INT_FAST64_WIDTH__
-@itemx __INTPTR_WIDTH__
-@itemx __INTMAX_WIDTH__
-Defined to the bit widths of the corresponding types. They exist to
-make the implementations of @file{limits.h} and @file{stdint.h} behave
-correctly. You should not use these macros directly; instead, include
-the appropriate headers. Some of these macros may not be defined on
-particular systems if GCC does not provide a @file{stdint.h} header on
-those systems.
-
-@item __SIZEOF_INT__
-@itemx __SIZEOF_LONG__
-@itemx __SIZEOF_LONG_LONG__
-@itemx __SIZEOF_SHORT__
-@itemx __SIZEOF_POINTER__
-@itemx __SIZEOF_FLOAT__
-@itemx __SIZEOF_DOUBLE__
-@itemx __SIZEOF_LONG_DOUBLE__
-@itemx __SIZEOF_SIZE_T__
-@itemx __SIZEOF_WCHAR_T__
-@itemx __SIZEOF_WINT_T__
-@itemx __SIZEOF_PTRDIFF_T__
-Defined to the number of bytes of the C standard data types: @code{int},
-@code{long}, @code{long long}, @code{short}, @code{void *}, @code{float},
-@code{double}, @code{long double}, @code{size_t}, @code{wchar_t}, @code{wint_t}
-and @code{ptrdiff_t}.
-
-@item __BYTE_ORDER__
-@itemx __ORDER_LITTLE_ENDIAN__
-@itemx __ORDER_BIG_ENDIAN__
-@itemx __ORDER_PDP_ENDIAN__
-@code{__BYTE_ORDER__} is defined to one of the values
-@code{__ORDER_LITTLE_ENDIAN__}, @code{__ORDER_BIG_ENDIAN__}, or
-@code{__ORDER_PDP_ENDIAN__} to reflect the layout of multi-byte and
-multi-word quantities in memory. If @code{__BYTE_ORDER__} is equal to
-@code{__ORDER_LITTLE_ENDIAN__} or @code{__ORDER_BIG_ENDIAN__}, then
-multi-byte and multi-word quantities are laid out identically: the
-byte (word) at the lowest address is the least significant or most
-significant byte (word) of the quantity, respectively. If
-@code{__BYTE_ORDER__} is equal to @code{__ORDER_PDP_ENDIAN__}, then
-bytes in 16-bit words are laid out in a little-endian fashion, whereas
-the 16-bit subwords of a 32-bit quantity are laid out in big-endian
-fashion.
-
-You should use these macros for testing like this:
-
-@smallexample
-/* @r{Test for a little-endian machine} */
-#if __BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__
-@end smallexample
-
-@item __FLOAT_WORD_ORDER__
-@code{__FLOAT_WORD_ORDER__} is defined to one of the values
-@code{__ORDER_LITTLE_ENDIAN__} or @code{__ORDER_BIG_ENDIAN__} to reflect
-the layout of the words of multi-word floating-point quantities.
-
-@item __DEPRECATED
-This macro is defined, with value 1, when compiling a C++ source file
-with warnings about deprecated constructs enabled. These warnings are
-enabled by default, but can be disabled with @option{-Wno-deprecated}.
-
-@item __EXCEPTIONS
-This macro is defined, with value 1, when compiling a C++ source file
-with exceptions enabled. If @option{-fno-exceptions} is used when
-compiling the file, then this macro is not defined.
-
-@item __GXX_RTTI
-This macro is defined, with value 1, when compiling a C++ source file
-with runtime type identification enabled. If @option{-fno-rtti} is
-used when compiling the file, then this macro is not defined.
-
-@item __USING_SJLJ_EXCEPTIONS__
-This macro is defined, with value 1, if the compiler uses the old
-mechanism based on @code{setjmp} and @code{longjmp} for exception
-handling.
-
-@item __GXX_EXPERIMENTAL_CXX0X__
-This macro is defined when compiling a C++ source file with C++11 features
-enabled, i.e., for all C++ language dialects except @option{-std=c++98}
-and @option{-std=gnu++98}. This macro is obsolete, but can be used to
-detect experimental C++0x features in very old versions of GCC. Since
-GCC 4.7.0 the @code{__cplusplus} macro is defined correctly, so most
-code should test @code{__cplusplus >= 201103L} instead of using this
-macro.
-
-@item __GXX_WEAK__
-This macro is defined when compiling a C++ source file. It has the
-value 1 if the compiler will use weak symbols, COMDAT sections, or
-other similar techniques to collapse symbols with ``vague linkage''
-that are defined in multiple translation units. If the compiler will
-not collapse such symbols, this macro is defined with value 0. In
-general, user code should not need to make use of this macro; the
-purpose of this macro is to ease implementation of the C++ runtime
-library provided with G++.
-
-@item __NEXT_RUNTIME__
-This macro is defined, with value 1, if (and only if) the NeXT runtime
-(as in @option{-fnext-runtime}) is in use for Objective-C@. If the GNU
-runtime is used, this macro is not defined, so that you can use this
-macro to determine which runtime (NeXT or GNU) is being used.
-
-@item __LP64__
-@itemx _LP64
-These macros are defined, with value 1, if (and only if) the compilation
-is for a target where @code{long int} and pointer both use 64-bits and
-@code{int} uses 32-bit.
-
-@item __SSP__
-This macro is defined, with value 1, when @option{-fstack-protector} is in
-use.
-
-@item __SSP_ALL__
-This macro is defined, with value 2, when @option{-fstack-protector-all} is
-in use.
-
-@item __SSP_STRONG__
-This macro is defined, with value 3, when @option{-fstack-protector-strong} is
-in use.
-
-@item __SSP_EXPLICIT__
-This macro is defined, with value 4, when @option{-fstack-protector-explicit} is
-in use.
-
-@item __SANITIZE_ADDRESS__
-This macro is defined, with value 1, when @option{-fsanitize=address}
-or @option{-fsanitize=kernel-address} are in use.
-
-@item __SANITIZE_THREAD__
-This macro is defined, with value 1, when @option{-fsanitize=thread} is in use.
-
-@item __TIMESTAMP__
-This macro expands to a string constant that describes the date and time
-of the last modification of the current source file. The string constant
-contains abbreviated day of the week, month, day of the month, time in
-hh:mm:ss form, year and looks like @code{@w{"Sun Sep 16 01:03:52 1973"}}.
-If the day of the month is less than 10, it is padded with a space on the left.
-
-If GCC cannot determine the current date, it will emit a warning message
-(once per compilation) and @code{__TIMESTAMP__} will expand to
-@code{@w{"??? ??? ?? ??:??:?? ????"}}.
-
-@item __GCC_HAVE_SYNC_COMPARE_AND_SWAP_1
-@itemx __GCC_HAVE_SYNC_COMPARE_AND_SWAP_2
-@itemx __GCC_HAVE_SYNC_COMPARE_AND_SWAP_4
-@itemx __GCC_HAVE_SYNC_COMPARE_AND_SWAP_8
-@itemx __GCC_HAVE_SYNC_COMPARE_AND_SWAP_16
-These macros are defined when the target processor supports atomic compare
-and swap operations on operands 1, 2, 4, 8 or 16 bytes in length, respectively.
-
-@item __HAVE_SPECULATION_SAFE_VALUE
-This macro is defined with the value 1 to show that this version of GCC
-supports @code{__builtin_speculation_safe_value}.
-
-@item __GCC_HAVE_DWARF2_CFI_ASM
-This macro is defined when the compiler is emitting DWARF CFI directives
-to the assembler. When this is defined, it is possible to emit those same
-directives in inline assembly.
-
-@item __FP_FAST_FMA
-@itemx __FP_FAST_FMAF
-@itemx __FP_FAST_FMAL
-These macros are defined with value 1 if the backend supports the
-@code{fma}, @code{fmaf}, and @code{fmal} builtin functions, so that
-the include file @file{math.h} can define the macros
-@code{FP_FAST_FMA}, @code{FP_FAST_FMAF}, and @code{FP_FAST_FMAL}
-for compatibility with the 1999 C standard.
-
-@item __FP_FAST_FMAF16
-@itemx __FP_FAST_FMAF32
-@itemx __FP_FAST_FMAF64
-@itemx __FP_FAST_FMAF128
-@itemx __FP_FAST_FMAF32X
-@itemx __FP_FAST_FMAF64X
-@itemx __FP_FAST_FMAF128X
-These macros are defined with the value 1 if the backend supports the
-@code{fma} functions using the additional @code{_Float@var{n}} and
-@code{_Float@var{n}x} types that are defined in ISO/IEC TS
-18661-3:2015. The include file @file{math.h} can define the
-@code{FP_FAST_FMAF@var{n}} and @code{FP_FAST_FMAF@var{n}x} macros if
-the user defined @code{__STDC_WANT_IEC_60559_TYPES_EXT__} before
-including @file{math.h}.
-
-@item __GCC_IEC_559
-This macro is defined to indicate the intended level of support for
-IEEE 754 (IEC 60559) floating-point arithmetic. It expands to a
-nonnegative integer value. If 0, it indicates that the combination of
-the compiler configuration and the command-line options is not
-intended to support IEEE 754 arithmetic for @code{float} and
-@code{double} as defined in C99 and C11 Annex F (for example, that the
-standard rounding modes and exceptions are not supported, or that
-optimizations are enabled that conflict with IEEE 754 semantics). If
-1, it indicates that IEEE 754 arithmetic is intended to be supported;
-this does not mean that all relevant language features are supported
-by GCC. If 2 or more, it additionally indicates support for IEEE
-754-2008 (in particular, that the binary encodings for quiet and
-signaling NaNs are as specified in IEEE 754-2008).
-
-This macro does not indicate the default state of command-line options
-that control optimizations that C99 and C11 permit to be controlled by
-standard pragmas, where those standards do not require a particular
-default state. It does not indicate whether optimizations respect
-signaling NaN semantics (the macro for that is
-@code{__SUPPORT_SNAN__}). It does not indicate support for decimal
-floating point or the IEEE 754 binary16 and binary128 types.
-
-@item __GCC_IEC_559_COMPLEX
-This macro is defined to indicate the intended level of support for
-IEEE 754 (IEC 60559) floating-point arithmetic for complex numbers, as
-defined in C99 and C11 Annex G. It expands to a nonnegative integer
-value. If 0, it indicates that the combination of the compiler
-configuration and the command-line options is not intended to support
-Annex G requirements (for example, because @option{-fcx-limited-range}
-was used). If 1 or more, it indicates that it is intended to support
-those requirements; this does not mean that all relevant language
-features are supported by GCC.
-
-@item __NO_MATH_ERRNO__
-This macro is defined if @option{-fno-math-errno} is used, or enabled
-by another option such as @option{-ffast-math} or by default.
-
-@item __RECIPROCAL_MATH__
-This macro is defined if @option{-freciprocal-math} is used, or enabled
-by another option such as @option{-ffast-math} or by default.
-
-@item __NO_SIGNED_ZEROS__
-This macro is defined if @option{-fno-signed-zeros} is used, or enabled
-by another option such as @option{-ffast-math} or by default.
-
-@item __NO_TRAPPING_MATH__
-This macro is defined if @option{-fno-trapping-math} is used.
-
-@item __ASSOCIATIVE_MATH__
-This macro is defined if @option{-fassociative-math} is used, or enabled
-by another option such as @option{-ffast-math} or by default.
-
-@item __ROUNDING_MATH__
-This macro is defined if @option{-frounding-math} is used.
-
-@item __GNUC_EXECUTION_CHARSET_NAME
-@itemx __GNUC_WIDE_EXECUTION_CHARSET_NAME
-These macros are defined to expand to a narrow string literal of
-the name of the narrow and wide compile-time execution character
-set used. It directly reflects the name passed to the options
-@option{-fexec-charset} and @option{-fwide-exec-charset}, or the defaults
-documented for those options (that is, it can expand to something like
-@code{"UTF-8"}). @xref{Invocation}.
-@end table
-
-@node System-specific Predefined Macros
-@subsection System-specific Predefined Macros
-
-@cindex system-specific predefined macros
-@cindex predefined macros, system-specific
-@cindex reserved namespace
-
-The C preprocessor normally predefines several macros that indicate what
-type of system and machine is in use. They are obviously different on
-each target supported by GCC@. This manual, being for all systems and
-machines, cannot tell you what their names are, but you can use
-@command{cpp -dM} to see them all. @xref{Invocation}. All system-specific
-predefined macros expand to a constant value, so you can test them with
-either @samp{#ifdef} or @samp{#if}.
-
-The C standard requires that all system-specific macros be part of the
-@dfn{reserved namespace}. All names which begin with two underscores,
-or an underscore and a capital letter, are reserved for the compiler and
-library to use as they wish. However, historically system-specific
-macros have had names with no special prefix; for instance, it is common
-to find @code{unix} defined on Unix systems. For all such macros, GCC
-provides a parallel macro with two underscores added at the beginning
-and the end. If @code{unix} is defined, @code{__unix__} will be defined
-too. There will never be more than two underscores; the parallel of
-@code{_mips} is @code{__mips__}.
-
-When the @option{-ansi} option, or any @option{-std} option that
-requests strict conformance, is given to the compiler, all the
-system-specific predefined macros outside the reserved namespace are
-suppressed. The parallel macros, inside the reserved namespace, remain
-defined.
-
-We are slowly phasing out all predefined macros which are outside the
-reserved namespace. You should never use them in new programs, and we
-encourage you to correct older code to use the parallel macros whenever
-you find it. We don't recommend you use the system-specific macros that
-are in the reserved namespace, either. It is better in the long run to
-check specifically for features you need, using a tool such as
-@command{autoconf}.
-
-@node C++ Named Operators
-@subsection C++ Named Operators
-@cindex named operators
-@cindex C++ named operators
-@cindex @file{iso646.h}
-
-In C++, there are eleven keywords which are simply alternate spellings
-of operators normally written with punctuation. These keywords are
-treated as such even in the preprocessor. They function as operators in
-@samp{#if}, and they cannot be defined as macros or poisoned. In C, you
-can request that those keywords take their C++ meaning by including
-@file{iso646.h}. That header defines each one as a normal object-like
-macro expanding to the appropriate punctuator.
-
-These are the named operators and their corresponding punctuators:
-
-@multitable {Named Operator} {Punctuator}
-@item Named Operator @tab Punctuator
-@item @code{and} @tab @code{&&}
-@item @code{and_eq} @tab @code{&=}
-@item @code{bitand} @tab @code{&}
-@item @code{bitor} @tab @code{|}
-@item @code{compl} @tab @code{~}
-@item @code{not} @tab @code{!}
-@item @code{not_eq} @tab @code{!=}
-@item @code{or} @tab @code{||}
-@item @code{or_eq} @tab @code{|=}
-@item @code{xor} @tab @code{^}
-@item @code{xor_eq} @tab @code{^=}
-@end multitable
-
-@node Undefining and Redefining Macros
-@section Undefining and Redefining Macros
-@cindex undefining macros
-@cindex redefining macros
-@findex #undef
-
-If a macro ceases to be useful, it may be @dfn{undefined} with the
-@samp{#undef} directive. @samp{#undef} takes a single argument, the
-name of the macro to undefine. You use the bare macro name, even if the
-macro is function-like. It is an error if anything appears on the line
-after the macro name. @samp{#undef} has no effect if the name is not a
-macro.
-
-@smallexample
-#define FOO 4
-x = FOO; @expansion{} x = 4;
-#undef FOO
-x = FOO; @expansion{} x = FOO;
-@end smallexample
-
-Once a macro has been undefined, that identifier may be @dfn{redefined}
-as a macro by a subsequent @samp{#define} directive. The new definition
-need not have any resemblance to the old definition.
-
-However, if an identifier which is currently a macro is redefined, then
-the new definition must be @dfn{effectively the same} as the old one.
-Two macro definitions are effectively the same if:
-@itemize @bullet
-@item Both are the same type of macro (object- or function-like).
-@item All the tokens of the replacement list are the same.
-@item If there are any parameters, they are the same.
-@item Whitespace appears in the same places in both. It need not be
-exactly the same amount of whitespace, though. Remember that comments
-count as whitespace.
-@end itemize
-
-@noindent
-These definitions are effectively the same:
-@smallexample
-#define FOUR (2 + 2)
-#define FOUR (2 + 2)
-#define FOUR (2 /* @r{two} */ + 2)
-@end smallexample
-@noindent
-but these are not:
-@smallexample
-#define FOUR (2 + 2)
-#define FOUR ( 2+2 )
-#define FOUR (2 * 2)
-#define FOUR(score,and,seven,years,ago) (2 + 2)
-@end smallexample
-
-If a macro is redefined with a definition that is not effectively the
-same as the old one, the preprocessor issues a warning and changes the
-macro to use the new definition. If the new definition is effectively
-the same, the redefinition is silently ignored. This allows, for
-instance, two different headers to define a common macro. The
-preprocessor will only complain if the definitions do not match.
-
-@node Directives Within Macro Arguments
-@section Directives Within Macro Arguments
-@cindex macro arguments and directives
-
-Occasionally it is convenient to use preprocessor directives within
-the arguments of a macro. The C and C++ standards declare that
-behavior in these cases is undefined. GNU CPP
-processes arbitrary directives within macro arguments in
-exactly the same way as it would have processed the directive were the
-function-like macro invocation not present.
-
-If, within a macro invocation, that macro is redefined, then the new
-definition takes effect in time for argument pre-expansion, but the
-original definition is still used for argument replacement. Here is a
-pathological example:
-
-@smallexample
-#define f(x) x x
-f (1
-#undef f
-#define f 2
-f)
-@end smallexample
-
-@noindent
-which expands to
-
-@smallexample
-1 2 1 2
-@end smallexample
-
-@noindent
-with the semantics described above.
-
-@node Macro Pitfalls
-@section Macro Pitfalls
-@cindex problems with macros
-@cindex pitfalls of macros
-
-In this section we describe some special rules that apply to macros and
-macro expansion, and point out certain cases in which the rules have
-counter-intuitive consequences that you must watch out for.
-
-@menu
-* Misnesting::
-* Operator Precedence Problems::
-* Swallowing the Semicolon::
-* Duplication of Side Effects::
-* Self-Referential Macros::
-* Argument Prescan::
-* Newlines in Arguments::
-@end menu
-
-@node Misnesting
-@subsection Misnesting
-
-When a macro is called with arguments, the arguments are substituted
-into the macro body and the result is checked, together with the rest of
-the input file, for more macro calls. It is possible to piece together
-a macro call coming partially from the macro body and partially from the
-arguments. For example,
-
-@smallexample
-#define twice(x) (2*(x))
-#define call_with_1(x) x(1)
-call_with_1 (twice)
- @expansion{} twice(1)
- @expansion{} (2*(1))
-@end smallexample
-
-Macro definitions do not have to have balanced parentheses. By writing
-an unbalanced open parenthesis in a macro body, it is possible to create
-a macro call that begins inside the macro body but ends outside of it.
-For example,
-
-@smallexample
-#define strange(file) fprintf (file, "%s %d",
-@dots{}
-strange(stderr) p, 35)
- @expansion{} fprintf (stderr, "%s %d", p, 35)
-@end smallexample
-
-The ability to piece together a macro call can be useful, but the use of
-unbalanced open parentheses in a macro body is just confusing, and
-should be avoided.
-
-@node Operator Precedence Problems
-@subsection Operator Precedence Problems
-@cindex parentheses in macro bodies
-
-You may have noticed that in most of the macro definition examples shown
-above, each occurrence of a macro argument name had parentheses around
-it. In addition, another pair of parentheses usually surround the
-entire macro definition. Here is why it is best to write macros that
-way.
-
-Suppose you define a macro as follows,
-
-@smallexample
-#define ceil_div(x, y) (x + y - 1) / y
-@end smallexample
-
-@noindent
-whose purpose is to divide, rounding up. (One use for this operation is
-to compute how many @code{int} objects are needed to hold a certain
-number of @code{char} objects.) Then suppose it is used as follows:
-
-@smallexample
-a = ceil_div (b & c, sizeof (int));
- @expansion{} a = (b & c + sizeof (int) - 1) / sizeof (int);
-@end smallexample
-
-@noindent
-This does not do what is intended. The operator-precedence rules of
-C make it equivalent to this:
-
-@smallexample
-a = (b & (c + sizeof (int) - 1)) / sizeof (int);
-@end smallexample
-
-@noindent
-What we want is this:
-
-@smallexample
-a = ((b & c) + sizeof (int) - 1)) / sizeof (int);
-@end smallexample
-
-@noindent
-Defining the macro as
-
-@smallexample
-#define ceil_div(x, y) ((x) + (y) - 1) / (y)
-@end smallexample
-
-@noindent
-provides the desired result.
-
-Unintended grouping can result in another way. Consider @code{sizeof
-ceil_div(1, 2)}. That has the appearance of a C expression that would
-compute the size of the type of @code{ceil_div (1, 2)}, but in fact it
-means something very different. Here is what it expands to:
-
-@smallexample
-sizeof ((1) + (2) - 1) / (2)
-@end smallexample
-
-@noindent
-This would take the size of an integer and divide it by two. The
-precedence rules have put the division outside the @code{sizeof} when it
-was intended to be inside.
-
-Parentheses around the entire macro definition prevent such problems.
-Here, then, is the recommended way to define @code{ceil_div}:
-
-@smallexample
-#define ceil_div(x, y) (((x) + (y) - 1) / (y))
-@end smallexample
-
-@node Swallowing the Semicolon
-@subsection Swallowing the Semicolon
-@cindex semicolons (after macro calls)
-
-Often it is desirable to define a macro that expands into a compound
-statement. Consider, for example, the following macro, that advances a
-pointer (the argument @code{p} says where to find it) across whitespace
-characters:
-
-@smallexample
-#define SKIP_SPACES(p, limit) \
-@{ char *lim = (limit); \
- while (p < lim) @{ \
- if (*p++ != ' ') @{ \
- p--; break; @}@}@}
-@end smallexample
-
-@noindent
-Here backslash-newline is used to split the macro definition, which must
-be a single logical line, so that it resembles the way such code would
-be laid out if not part of a macro definition.
-
-A call to this macro might be @code{SKIP_SPACES (p, lim)}. Strictly
-speaking, the call expands to a compound statement, which is a complete
-statement with no need for a semicolon to end it. However, since it
-looks like a function call, it minimizes confusion if you can use it
-like a function call, writing a semicolon afterward, as in
-@code{SKIP_SPACES (p, lim);}
-
-This can cause trouble before @code{else} statements, because the
-semicolon is actually a null statement. Suppose you write
-
-@smallexample
-if (*p != 0)
- SKIP_SPACES (p, lim);
-else @dots{}
-@end smallexample
-
-@noindent
-The presence of two statements---the compound statement and a null
-statement---in between the @code{if} condition and the @code{else}
-makes invalid C code.
-
-The definition of the macro @code{SKIP_SPACES} can be altered to solve
-this problem, using a @code{do @dots{} while} statement. Here is how:
-
-@smallexample
-#define SKIP_SPACES(p, limit) \
-do @{ char *lim = (limit); \
- while (p < lim) @{ \
- if (*p++ != ' ') @{ \
- p--; break; @}@}@} \
-while (0)
-@end smallexample
-
-Now @code{SKIP_SPACES (p, lim);} expands into
-
-@smallexample
-do @{@dots{}@} while (0);
-@end smallexample
-
-@noindent
-which is one statement. The loop executes exactly once; most compilers
-generate no extra code for it.
-
-@node Duplication of Side Effects
-@subsection Duplication of Side Effects
-
-@cindex side effects (in macro arguments)
-@cindex unsafe macros
-Many C programs define a macro @code{min}, for ``minimum'', like this:
-
-@smallexample
-#define min(X, Y) ((X) < (Y) ? (X) : (Y))
-@end smallexample
-
-When you use this macro with an argument containing a side effect,
-as shown here,
-
-@smallexample
-next = min (x + y, foo (z));
-@end smallexample
-
-@noindent
-it expands as follows:
-
-@smallexample
-next = ((x + y) < (foo (z)) ? (x + y) : (foo (z)));
-@end smallexample
-
-@noindent
-where @code{x + y} has been substituted for @code{X} and @code{foo (z)}
-for @code{Y}.
-
-The function @code{foo} is used only once in the statement as it appears
-in the program, but the expression @code{foo (z)} has been substituted
-twice into the macro expansion. As a result, @code{foo} might be called
-two times when the statement is executed. If it has side effects or if
-it takes a long time to compute, the results might not be what you
-intended. We say that @code{min} is an @dfn{unsafe} macro.
-
-The best solution to this problem is to define @code{min} in a way that
-computes the value of @code{foo (z)} only once. The C language offers
-no standard way to do this, but it can be done with GNU extensions as
-follows:
-
-@smallexample
-#define min(X, Y) \
-(@{ typeof (X) x_ = (X); \
- typeof (Y) y_ = (Y); \
- (x_ < y_) ? x_ : y_; @})
-@end smallexample
-
-The @samp{(@{ @dots{} @})} notation produces a compound statement that
-acts as an expression. Its value is the value of its last statement.
-This permits us to define local variables and assign each argument to
-one. The local variables have underscores after their names to reduce
-the risk of conflict with an identifier of wider scope (it is impossible
-to avoid this entirely). Now each argument is evaluated exactly once.
-
-If you do not wish to use GNU C extensions, the only solution is to be
-careful when @emph{using} the macro @code{min}. For example, you can
-calculate the value of @code{foo (z)}, save it in a variable, and use
-that variable in @code{min}:
-
-@smallexample
-@group
-#define min(X, Y) ((X) < (Y) ? (X) : (Y))
-@dots{}
-@{
- int tem = foo (z);
- next = min (x + y, tem);
-@}
-@end group
-@end smallexample
-
-@noindent
-(where we assume that @code{foo} returns type @code{int}).
-
-@node Self-Referential Macros
-@subsection Self-Referential Macros
-@cindex self-reference
-
-A @dfn{self-referential} macro is one whose name appears in its
-definition. Recall that all macro definitions are rescanned for more
-macros to replace. If the self-reference were considered a use of the
-macro, it would produce an infinitely large expansion. To prevent this,
-the self-reference is not considered a macro call. It is passed into
-the preprocessor output unchanged. Consider an example:
-
-@smallexample
-#define foo (4 + foo)
-@end smallexample
-
-@noindent
-where @code{foo} is also a variable in your program.
-
-Following the ordinary rules, each reference to @code{foo} will expand
-into @code{(4 + foo)}; then this will be rescanned and will expand into
-@code{(4 + (4 + foo))}; and so on until the computer runs out of memory.
-
-The self-reference rule cuts this process short after one step, at
-@code{(4 + foo)}. Therefore, this macro definition has the possibly
-useful effect of causing the program to add 4 to the value of @code{foo}
-wherever @code{foo} is referred to.
-
-In most cases, it is a bad idea to take advantage of this feature. A
-person reading the program who sees that @code{foo} is a variable will
-not expect that it is a macro as well. The reader will come across the
-identifier @code{foo} in the program and think its value should be that
-of the variable @code{foo}, whereas in fact the value is four greater.
-
-One common, useful use of self-reference is to create a macro which
-expands to itself. If you write
-
-@smallexample
-#define EPERM EPERM
-@end smallexample
-
-@noindent
-then the macro @code{EPERM} expands to @code{EPERM}. Effectively, it is
-left alone by the preprocessor whenever it's used in running text. You
-can tell that it's a macro with @samp{#ifdef}. You might do this if you
-want to define numeric constants with an @code{enum}, but have
-@samp{#ifdef} be true for each constant.
-
-If a macro @code{x} expands to use a macro @code{y}, and the expansion of
-@code{y} refers to the macro @code{x}, that is an @dfn{indirect
-self-reference} of @code{x}. @code{x} is not expanded in this case
-either. Thus, if we have
-
-@smallexample
-#define x (4 + y)
-#define y (2 * x)
-@end smallexample
-
-@noindent
-then @code{x} and @code{y} expand as follows:
-
-@smallexample
-@group
-x @expansion{} (4 + y)
- @expansion{} (4 + (2 * x))
-
-y @expansion{} (2 * x)
- @expansion{} (2 * (4 + y))
-@end group
-@end smallexample
-
-@noindent
-Each macro is expanded when it appears in the definition of the other
-macro, but not when it indirectly appears in its own definition.
-
-@node Argument Prescan
-@subsection Argument Prescan
-@cindex expansion of arguments
-@cindex macro argument expansion
-@cindex prescan of macro arguments
-
-Macro arguments are completely macro-expanded before they are
-substituted into a macro body, unless they are stringized or pasted
-with other tokens. After substitution, the entire macro body, including
-the substituted arguments, is scanned again for macros to be expanded.
-The result is that the arguments are scanned @emph{twice} to expand
-macro calls in them.
-
-Most of the time, this has no effect. If the argument contained any
-macro calls, they are expanded during the first scan. The result
-therefore contains no macro calls, so the second scan does not change
-it. If the argument were substituted as given, with no prescan, the
-single remaining scan would find the same macro calls and produce the
-same results.
-
-You might expect the double scan to change the results when a
-self-referential macro is used in an argument of another macro
-(@pxref{Self-Referential Macros}): the self-referential macro would be
-expanded once in the first scan, and a second time in the second scan.
-However, this is not what happens. The self-references that do not
-expand in the first scan are marked so that they will not expand in the
-second scan either.
-
-You might wonder, ``Why mention the prescan, if it makes no difference?
-And why not skip it and make the preprocessor faster?'' The answer is
-that the prescan does make a difference in three special cases:
-
-@itemize @bullet
-@item
-Nested calls to a macro.
-
-We say that @dfn{nested} calls to a macro occur when a macro's argument
-contains a call to that very macro. For example, if @code{f} is a macro
-that expects one argument, @code{f (f (1))} is a nested pair of calls to
-@code{f}. The desired expansion is made by expanding @code{f (1)} and
-substituting that into the definition of @code{f}. The prescan causes
-the expected result to happen. Without the prescan, @code{f (1)} itself
-would be substituted as an argument, and the inner use of @code{f} would
-appear during the main scan as an indirect self-reference and would not
-be expanded.
-
-@item
-Macros that call other macros that stringize or concatenate.
-
-If an argument is stringized or concatenated, the prescan does not
-occur. If you @emph{want} to expand a macro, then stringize or
-concatenate its expansion, you can do that by causing one macro to call
-another macro that does the stringizing or concatenation. For
-instance, if you have
-
-@smallexample
-#define AFTERX(x) X_ ## x
-#define XAFTERX(x) AFTERX(x)
-#define TABLESIZE 1024
-#define BUFSIZE TABLESIZE
-@end smallexample
-
-then @code{AFTERX(BUFSIZE)} expands to @code{X_BUFSIZE}, and
-@code{XAFTERX(BUFSIZE)} expands to @code{X_1024}. (Not to
-@code{X_TABLESIZE}. Prescan always does a complete expansion.)
-
-@item
-Macros used in arguments, whose expansions contain unshielded commas.
-
-This can cause a macro expanded on the second scan to be called with the
-wrong number of arguments. Here is an example:
-
-@smallexample
-#define foo a,b
-#define bar(x) lose(x)
-#define lose(x) (1 + (x))
-@end smallexample
-
-We would like @code{bar(foo)} to turn into @code{(1 + (foo))}, which
-would then turn into @code{(1 + (a,b))}. Instead, @code{bar(foo)}
-expands into @code{lose(a,b)}, and you get an error because @code{lose}
-requires a single argument. In this case, the problem is easily solved
-by the same parentheses that ought to be used to prevent misnesting of
-arithmetic operations:
-
-@smallexample
-#define foo (a,b)
-@exdent or
-#define bar(x) lose((x))
-@end smallexample
-
-The extra pair of parentheses prevents the comma in @code{foo}'s
-definition from being interpreted as an argument separator.
-
-@end itemize
-
-@node Newlines in Arguments
-@subsection Newlines in Arguments
-@cindex newlines in macro arguments
-
-The invocation of a function-like macro can extend over many logical
-lines. However, in the present implementation, the entire expansion
-comes out on one line. Thus line numbers emitted by the compiler or
-debugger refer to the line the invocation started on, which might be
-different to the line containing the argument causing the problem.
-
-Here is an example illustrating this:
-
-@smallexample
-#define ignore_second_arg(a,b,c) a; c
-
-ignore_second_arg (foo (),
- ignored (),
- syntax error);
-@end smallexample
-
-@noindent
-The syntax error triggered by the tokens @code{syntax error} results in
-an error message citing line three---the line of ignore_second_arg---
-even though the problematic code comes from line five.
-
-We consider this a bug, and intend to fix it in the near future.
-
-@node Conditionals
-@chapter Conditionals
-@cindex conditionals
-
-A @dfn{conditional} is a directive that instructs the preprocessor to
-select whether or not to include a chunk of code in the final token
-stream passed to the compiler. Preprocessor conditionals can test
-arithmetic expressions, or whether a name is defined as a macro, or both
-simultaneously using the special @code{defined} operator.
-
-A conditional in the C preprocessor resembles in some ways an @code{if}
-statement in C, but it is important to understand the difference between
-them. The condition in an @code{if} statement is tested during the
-execution of your program. Its purpose is to allow your program to
-behave differently from run to run, depending on the data it is
-operating on. The condition in a preprocessing conditional directive is
-tested when your program is compiled. Its purpose is to allow different
-code to be included in the program depending on the situation at the
-time of compilation.
-
-However, the distinction is becoming less clear. Modern compilers often
-do test @code{if} statements when a program is compiled, if their
-conditions are known not to vary at run time, and eliminate code which
-can never be executed. If you can count on your compiler to do this,
-you may find that your program is more readable if you use @code{if}
-statements with constant conditions (perhaps determined by macros). Of
-course, you can only use this to exclude code, not type definitions or
-other preprocessing directives, and you can only do it if the code
-remains syntactically valid when it is not to be used.
-
-@menu
-* Conditional Uses::
-* Conditional Syntax::
-* Deleted Code::
-@end menu
-
-@node Conditional Uses
-@section Conditional Uses
-
-There are three general reasons to use a conditional.
-
-@itemize @bullet
-@item
-A program may need to use different code depending on the machine or
-operating system it is to run on. In some cases the code for one
-operating system may be erroneous on another operating system; for
-example, it might refer to data types or constants that do not exist on
-the other system. When this happens, it is not enough to avoid
-executing the invalid code. Its mere presence will cause the compiler
-to reject the program. With a preprocessing conditional, the offending
-code can be effectively excised from the program when it is not valid.
-
-@item
-You may want to be able to compile the same source file into two
-different programs. One version might make frequent time-consuming
-consistency checks on its intermediate data, or print the values of
-those data for debugging, and the other not.
-
-@item
-A conditional whose condition is always false is one way to exclude code
-from the program but keep it as a sort of comment for future reference.
-@end itemize
-
-Simple programs that do not need system-specific logic or complex
-debugging hooks generally will not need to use preprocessing
-conditionals.
-
-@node Conditional Syntax
-@section Conditional Syntax
-
-@findex #if
-A conditional in the C preprocessor begins with a @dfn{conditional
-directive}: @samp{#if}, @samp{#ifdef} or @samp{#ifndef}.
-
-@menu
-* Ifdef::
-* If::
-* Defined::
-* Else::
-* Elif::
-* @code{__has_attribute}::
-* @code{__has_cpp_attribute}::
-* @code{__has_c_attribute}::
-* @code{__has_builtin}::
-* @code{__has_include}::
-@end menu
-
-@node Ifdef
-@subsection Ifdef
-@findex #ifdef
-@findex #endif
-
-The simplest sort of conditional is
-
-@smallexample
-@group
-#ifdef @var{MACRO}
-
-@var{controlled text}
-
-#endif /* @var{MACRO} */
-@end group
-@end smallexample
-
-@cindex conditional group
-This block is called a @dfn{conditional group}. @var{controlled text}
-will be included in the output of the preprocessor if and only if
-@var{MACRO} is defined. We say that the conditional @dfn{succeeds} if
-@var{MACRO} is defined, @dfn{fails} if it is not.
-
-The @var{controlled text} inside of a conditional can include
-preprocessing directives. They are executed only if the conditional
-succeeds. You can nest conditional groups inside other conditional
-groups, but they must be completely nested. In other words,
-@samp{#endif} always matches the nearest @samp{#ifdef} (or
-@samp{#ifndef}, or @samp{#if}). Also, you cannot start a conditional
-group in one file and end it in another.
-
-Even if a conditional fails, the @var{controlled text} inside it is
-still run through initial transformations and tokenization. Therefore,
-it must all be lexically valid C@. Normally the only way this matters is
-that all comments and string literals inside a failing conditional group
-must still be properly ended.
-
-The comment following the @samp{#endif} is not required, but it is a
-good practice if there is a lot of @var{controlled text}, because it
-helps people match the @samp{#endif} to the corresponding @samp{#ifdef}.
-Older programs sometimes put @var{MACRO} directly after the
-@samp{#endif} without enclosing it in a comment. This is invalid code
-according to the C standard. CPP accepts it with a warning. It
-never affects which @samp{#ifndef} the @samp{#endif} matches.
-
-@findex #ifndef
-Sometimes you wish to use some code if a macro is @emph{not} defined.
-You can do this by writing @samp{#ifndef} instead of @samp{#ifdef}.
-One common use of @samp{#ifndef} is to include code only the first
-time a header file is included. @xref{Once-Only Headers}.
-
-Macro definitions can vary between compilations for several reasons.
-Here are some samples.
-
-@itemize @bullet
-@item
-Some macros are predefined on each kind of machine
-(@pxref{System-specific Predefined Macros}). This allows you to provide
-code specially tuned for a particular machine.
-
-@item
-System header files define more macros, associated with the features
-they implement. You can test these macros with conditionals to avoid
-using a system feature on a machine where it is not implemented.
-
-@item
-Macros can be defined or undefined with the @option{-D} and @option{-U}
-command-line options when you compile the program. You can arrange to
-compile the same source file into two different programs by choosing a
-macro name to specify which program you want, writing conditionals to
-test whether or how this macro is defined, and then controlling the
-state of the macro with command-line options, perhaps set in the
-Makefile. @xref{Invocation}.
-
-@item
-Your program might have a special header file (often called
-@file{config.h}) that is adjusted when the program is compiled. It can
-define or not define macros depending on the features of the system and
-the desired capabilities of the program. The adjustment can be
-automated by a tool such as @command{autoconf}, or done by hand.
-@end itemize
-
-@node If
-@subsection If
-
-The @samp{#if} directive allows you to test the value of an arithmetic
-expression, rather than the mere existence of one macro. Its syntax is
-
-@smallexample
-@group
-#if @var{expression}
-
-@var{controlled text}
-
-#endif /* @var{expression} */
-@end group
-@end smallexample
-
-@var{expression} is a C expression of integer type, subject to stringent
-restrictions. It may contain
-
-@itemize @bullet
-@item
-Integer constants.
-
-@item
-Character constants, which are interpreted as they would be in normal
-code.
-
-@item
-Arithmetic operators for addition, subtraction, multiplication,
-division, bitwise operations, shifts, comparisons, and logical
-operations (@code{&&} and @code{||}). The latter two obey the usual
-short-circuiting rules of standard C@.
-
-@item
-Macros. All macros in the expression are expanded before actual
-computation of the expression's value begins.
-
-@item
-Uses of the @code{defined} operator, which lets you check whether macros
-are defined in the middle of an @samp{#if}.
-
-@item
-Identifiers that are not macros, which are all considered to be the
-number zero. This allows you to write @code{@w{#if MACRO}} instead of
-@code{@w{#ifdef MACRO}}, if you know that MACRO, when defined, will
-always have a nonzero value. Function-like macros used without their
-function call parentheses are also treated as zero.
-
-In some contexts this shortcut is undesirable. The @option{-Wundef}
-option causes GCC to warn whenever it encounters an identifier which is
-not a macro in an @samp{#if}.
-@end itemize
-
-The preprocessor does not know anything about types in the language.
-Therefore, @code{sizeof} operators are not recognized in @samp{#if}, and
-neither are @code{enum} constants. They will be taken as identifiers
-which are not macros, and replaced by zero. In the case of
-@code{sizeof}, this is likely to cause the expression to be invalid.
-
-The preprocessor calculates the value of @var{expression}. It carries
-out all calculations in the widest integer type known to the compiler;
-on most machines supported by GCC this is 64 bits. This is not the same
-rule as the compiler uses to calculate the value of a constant
-expression, and may give different results in some cases. If the value
-comes out to be nonzero, the @samp{#if} succeeds and the @var{controlled
-text} is included; otherwise it is skipped.
-
-@node Defined
-@subsection Defined
-
-@cindex @code{defined}
-The special operator @code{defined} is used in @samp{#if} and
-@samp{#elif} expressions to test whether a certain name is defined as a
-macro. @code{defined @var{name}} and @code{defined (@var{name})} are
-both expressions whose value is 1 if @var{name} is defined as a macro at
-the current point in the program, and 0 otherwise. Thus, @code{@w{#if
-defined MACRO}} is precisely equivalent to @code{@w{#ifdef MACRO}}.
-
-@code{defined} is useful when you wish to test more than one macro for
-existence at once. For example,
-
-@smallexample
-#if defined (__vax__) || defined (__ns16000__)
-@end smallexample
-
-@noindent
-would succeed if either of the names @code{__vax__} or
-@code{__ns16000__} is defined as a macro.
-
-Conditionals written like this:
-
-@smallexample
-#if defined BUFSIZE && BUFSIZE >= 1024
-@end smallexample
-
-@noindent
-can generally be simplified to just @code{@w{#if BUFSIZE >= 1024}},
-since if @code{BUFSIZE} is not defined, it will be interpreted as having
-the value zero.
-
-If the @code{defined} operator appears as a result of a macro expansion,
-the C standard says the behavior is undefined. GNU cpp treats it as a
-genuine @code{defined} operator and evaluates it normally. It will warn
-wherever your code uses this feature if you use the command-line option
-@option{-Wpedantic}, since other compilers may handle it differently. The
-warning is also enabled by @option{-Wextra}, and can also be enabled
-individually with @option{-Wexpansion-to-defined}.
-
-@node Else
-@subsection Else
-
-@findex #else
-The @samp{#else} directive can be added to a conditional to provide
-alternative text to be used if the condition fails. This is what it
-looks like:
-
-@smallexample
-@group
-#if @var{expression}
-@var{text-if-true}
-#else /* Not @var{expression} */
-@var{text-if-false}
-#endif /* Not @var{expression} */
-@end group
-@end smallexample
-
-@noindent
-If @var{expression} is nonzero, the @var{text-if-true} is included and
-the @var{text-if-false} is skipped. If @var{expression} is zero, the
-opposite happens.
-
-You can use @samp{#else} with @samp{#ifdef} and @samp{#ifndef}, too.
-
-@node Elif
-@subsection Elif
-
-@findex #elif
-One common case of nested conditionals is used to check for more than two
-possible alternatives. For example, you might have
-
-@smallexample
-#if X == 1
-@dots{}
-#else /* X != 1 */
-#if X == 2
-@dots{}
-#else /* X != 2 */
-@dots{}
-#endif /* X != 2 */
-#endif /* X != 1 */
-@end smallexample
-
-Another conditional directive, @samp{#elif}, allows this to be
-abbreviated as follows:
-
-@smallexample
-#if X == 1
-@dots{}
-#elif X == 2
-@dots{}
-#else /* X != 2 and X != 1*/
-@dots{}
-#endif /* X != 2 and X != 1*/
-@end smallexample
-
-@samp{#elif} stands for ``else if''. Like @samp{#else}, it goes in the
-middle of a conditional group and subdivides it; it does not require a
-matching @samp{#endif} of its own. Like @samp{#if}, the @samp{#elif}
-directive includes an expression to be tested. The text following the
-@samp{#elif} is processed only if the original @samp{#if}-condition
-failed and the @samp{#elif} condition succeeds.
-
-More than one @samp{#elif} can go in the same conditional group. Then
-the text after each @samp{#elif} is processed only if the @samp{#elif}
-condition succeeds after the original @samp{#if} and all previous
-@samp{#elif} directives within it have failed.
-
-@samp{#else} is allowed after any number of @samp{#elif} directives, but
-@samp{#elif} may not follow @samp{#else}.
-
-@node @code{__has_attribute}
-@subsection @code{__has_attribute}
-@cindex @code{__has_attribute}
-
-The special operator @code{__has_attribute (@var{operand})} may be used
-in @samp{#if} and @samp{#elif} expressions to test whether the attribute
-referenced by its @var{operand} is recognized by GCC. Using the operator
-in other contexts is not valid. In C code, if compiling for strict
-conformance to standards before C2x, @var{operand} must be
-a valid identifier. Otherwise, @var{operand} may be optionally
-introduced by the @code{@var{attribute-scope}::} prefix.
-The @var{attribute-scope} prefix identifies the ``namespace'' within
-which the attribute is recognized. The scope of GCC attributes is
-@samp{gnu} or @samp{__gnu__}. The @code{__has_attribute} operator by
-itself, without any @var{operand} or parentheses, acts as a predefined
-macro so that support for it can be tested in portable code. Thus,
-the recommended use of the operator is as follows:
-
-@smallexample
-#if defined __has_attribute
-# if __has_attribute (nonnull)
-# define ATTR_NONNULL __attribute__ ((nonnull))
-# endif
-#endif
-@end smallexample
-
-The first @samp{#if} test succeeds only when the operator is supported
-by the version of GCC (or another compiler) being used. Only when that
-test succeeds is it valid to use @code{__has_attribute} as a preprocessor
-operator. As a result, combining the two tests into a single expression as
-shown below would only be valid with a compiler that supports the operator
-but not with others that don't.
-
-@smallexample
-#if defined __has_attribute && __has_attribute (nonnull) /* not portable */
-@dots{}
-#endif
-@end smallexample
-
-@node @code{__has_cpp_attribute}
-@subsection @code{__has_cpp_attribute}
-@cindex @code{__has_cpp_attribute}
-
-The special operator @code{__has_cpp_attribute (@var{operand})} may be used
-in @samp{#if} and @samp{#elif} expressions in C++ code to test whether
-the attribute referenced by its @var{operand} is recognized by GCC.
-@code{__has_cpp_attribute (@var{operand})} is equivalent to
-@code{__has_attribute (@var{operand})} except that when @var{operand}
-designates a supported standard attribute it evaluates to an integer
-constant of the form @code{YYYYMM} indicating the year and month when
-the attribute was first introduced into the C++ standard. For additional
-information including the dates of the introduction of current standard
-attributes, see @w{@uref{https://isocpp.org/std/standing-documents/sd-6-sg10-feature-test-recommendations/,
-SD-6: SG10 Feature Test Recommendations}}.
-
-@node @code{__has_c_attribute}
-@subsection @code{__has_c_attribute}
-@cindex @code{__has_c_attribute}
-
-The special operator @code{__has_c_attribute (@var{operand})} may be
-used in @samp{#if} and @samp{#elif} expressions in C code to test
-whether the attribute referenced by its @var{operand} is recognized by
-GCC in attributes using the @samp{[[]]} syntax. GNU attributes must
-be specified with the scope @samp{gnu} or @samp{__gnu__} with
-@code{__has_c_attribute}. When @var{operand} designates a supported
-standard attribute it evaluates to an integer constant of the form
-@code{YYYYMM} indicating the year and month when the attribute was
-first introduced into the C standard, or when the syntax of operands
-to the attribute was extended in the C standard.
-
-@node @code{__has_builtin}
-@subsection @code{__has_builtin}
-@cindex @code{__has_builtin}
-
-The special operator @code{__has_builtin (@var{operand})} may be used in
-constant integer contexts and in preprocessor @samp{#if} and @samp{#elif}
-expressions to test whether the symbol named by its @var{operand} is
-recognized as a built-in function by GCC in the current language and
-conformance mode. It evaluates to a constant integer with a nonzero
-value if the argument refers to such a function, and to zero otherwise.
-The operator may also be used in preprocessor @samp{#if} and @samp{#elif}
-expressions. The @code{__has_builtin} operator by itself, without any
-@var{operand} or parentheses, acts as a predefined macro so that support
-for it can be tested in portable code. Thus, the recommended use of
-the operator is as follows:
-
-@smallexample
-#if defined __has_builtin
-# if __has_builtin (__builtin_object_size)
-# define builtin_object_size(ptr) __builtin_object_size (ptr, 2)
-# endif
-#endif
-#ifndef builtin_object_size
-# define builtin_object_size(ptr) ((size_t)-1)
-#endif
-@end smallexample
-
-@node @code{__has_include}
-@subsection @code{__has_include}
-@cindex @code{__has_include}
-
-The special operator @code{__has_include (@var{operand})} may be used in
-@samp{#if} and @samp{#elif} expressions to test whether the header referenced
-by its @var{operand} can be included using the @samp{#include} directive. Using
-the operator in other contexts is not valid. The @var{operand} takes
-the same form as the file in the @samp{#include} directive (@pxref{Include
-Syntax}) and evaluates to a nonzero value if the header can be included and
-to zero otherwise. Note that that the ability to include a header doesn't
-imply that the header doesn't contain invalid constructs or @samp{#error}
-directives that would cause the preprocessor to fail.
-
-The @code{__has_include} operator by itself, without any @var{operand} or
-parentheses, acts as a predefined macro so that support for it can be tested
-in portable code. Thus, the recommended use of the operator is as follows:
-
-@smallexample
-#if defined __has_include
-# if __has_include (<stdatomic.h>)
-# include <stdatomic.h>
-# endif
-#endif
-@end smallexample
-
-The first @samp{#if} test succeeds only when the operator is supported
-by the version of GCC (or another compiler) being used. Only when that
-test succeeds is it valid to use @code{__has_include} as a preprocessor
-operator. As a result, combining the two tests into a single expression
-as shown below would only be valid with a compiler that supports the operator
-but not with others that don't.
-
-@smallexample
-#if defined __has_include && __has_include ("header.h") /* not portable */
-@dots{}
-#endif
-@end smallexample
-
-@node Deleted Code
-@section Deleted Code
-@cindex commenting out code
-
-If you replace or delete a part of the program but want to keep the old
-code around for future reference, you often cannot simply comment it
-out. Block comments do not nest, so the first comment inside the old
-code will end the commenting-out. The probable result is a flood of
-syntax errors.
-
-One way to avoid this problem is to use an always-false conditional
-instead. For instance, put @code{#if 0} before the deleted code and
-@code{#endif} after it. This works even if the code being turned
-off contains conditionals, but they must be entire conditionals
-(balanced @samp{#if} and @samp{#endif}).
-
-Some people use @code{#ifdef notdef} instead. This is risky, because
-@code{notdef} might be accidentally defined as a macro, and then the
-conditional would succeed. @code{#if 0} can be counted on to fail.
-
-Do not use @code{#if 0} for comments which are not C code. Use a real
-comment, instead. The interior of @code{#if 0} must consist of complete
-tokens; in particular, single-quote characters must balance. Comments
-often contain unbalanced single-quote characters (known in English as
-apostrophes). These confuse @code{#if 0}. They don't confuse
-@samp{/*}.
-
-@node Diagnostics
-@chapter Diagnostics
-@cindex diagnostic
-@cindex reporting errors
-@cindex reporting warnings
-
-@findex #error
-The directive @samp{#error} causes the preprocessor to report a fatal
-error. The tokens forming the rest of the line following @samp{#error}
-are used as the error message.
-
-You would use @samp{#error} inside of a conditional that detects a
-combination of parameters which you know the program does not properly
-support. For example, if you know that the program will not run
-properly on a VAX, you might write
-
-@smallexample
-@group
-#ifdef __vax__
-#error "Won't work on VAXen. See comments at get_last_object."
-#endif
-@end group
-@end smallexample
-
-If you have several configuration parameters that must be set up by
-the installation in a consistent way, you can use conditionals to detect
-an inconsistency and report it with @samp{#error}. For example,
-
-@smallexample
-#if !defined(FOO) && defined(BAR)
-#error "BAR requires FOO."
-#endif
-@end smallexample
-
-@findex #warning
-The directive @samp{#warning} is like @samp{#error}, but causes the
-preprocessor to issue a warning and continue preprocessing. The tokens
-following @samp{#warning} are used as the warning message.
-
-You might use @samp{#warning} in obsolete header files, with a message
-directing the user to the header file which should be used instead.
-
-Neither @samp{#error} nor @samp{#warning} macro-expands its argument.
-Internal whitespace sequences are each replaced with a single space.
-The line must consist of complete tokens. It is wisest to make the
-argument of these directives be a single string constant; this avoids
-problems with apostrophes and the like.
-
-@node Line Control
-@chapter Line Control
-@cindex line control
-
-The C preprocessor informs the C compiler of the location in your source
-code where each token came from. Presently, this is just the file name
-and line number. All the tokens resulting from macro expansion are
-reported as having appeared on the line of the source file where the
-outermost macro was used. We intend to be more accurate in the future.
-
-If you write a program which generates source code, such as the
-@command{bison} parser generator, you may want to adjust the preprocessor's
-notion of the current file name and line number by hand. Parts of the
-output from @command{bison} are generated from scratch, other parts come
-from a standard parser file. The rest are copied verbatim from
-@command{bison}'s input. You would like compiler error messages and
-symbolic debuggers to be able to refer to @code{bison}'s input file.
-
-@findex #line
-@command{bison} or any such program can arrange this by writing
-@samp{#line} directives into the output file. @samp{#line} is a
-directive that specifies the original line number and source file name
-for subsequent input in the current preprocessor input file.
-@samp{#line} has three variants:
-
-@table @code
-@item #line @var{linenum}
-@var{linenum} is a non-negative decimal integer constant. It specifies
-the line number which should be reported for the following line of
-input. Subsequent lines are counted from @var{linenum}.
-
-@item #line @var{linenum} @var{filename}
-@var{linenum} is the same as for the first form, and has the same
-effect. In addition, @var{filename} is a string constant. The
-following line and all subsequent lines are reported to come from the
-file it specifies, until something else happens to change that.
-@var{filename} is interpreted according to the normal rules for a string
-constant: backslash escapes are interpreted. This is different from
-@samp{#include}.
-
-@item #line @var{anything else}
-@var{anything else} is checked for macro calls, which are expanded.
-The result should match one of the above two forms.
-@end table
-
-@samp{#line} directives alter the results of the @code{__FILE__} and
-@code{__LINE__} predefined macros from that point on. @xref{Standard
-Predefined Macros}. They do not have any effect on @samp{#include}'s
-idea of the directory containing the current file.
-
-@node Pragmas
-@chapter Pragmas
-
-@cindex pragma directive
-
-The @samp{#pragma} directive is the method specified by the C standard
-for providing additional information to the compiler, beyond what is
-conveyed in the language itself. The forms of this directive
-(commonly known as @dfn{pragmas}) specified by C standard are prefixed with
-@code{STDC}. A C compiler is free to attach any meaning it likes to other
-pragmas. Most GNU-defined, supported pragmas have been given a
-@code{GCC} prefix.
-
-@cindex @code{_Pragma}
-C99 introduced the @code{@w{_Pragma}} operator. This feature addresses a
-major problem with @samp{#pragma}: being a directive, it cannot be
-produced as the result of macro expansion. @code{@w{_Pragma}} is an
-operator, much like @code{sizeof} or @code{defined}, and can be embedded
-in a macro.
-
-Its syntax is @code{@w{_Pragma (@var{string-literal})}}, where
-@var{string-literal} can be either a normal or wide-character string
-literal. It is destringized, by replacing all @samp{\\} with a single
-@samp{\} and all @samp{\"} with a @samp{"}. The result is then
-processed as if it had appeared as the right hand side of a
-@samp{#pragma} directive. For example,
-
-@smallexample
-_Pragma ("GCC dependency \"parse.y\"")
-@end smallexample
-
-@noindent
-has the same effect as @code{#pragma GCC dependency "parse.y"}. The
-same effect could be achieved using macros, for example
-
-@smallexample
-#define DO_PRAGMA(x) _Pragma (#x)
-DO_PRAGMA (GCC dependency "parse.y")
-@end smallexample
-
-The standard is unclear on where a @code{_Pragma} operator can appear.
-The preprocessor does not accept it within a preprocessing conditional
-directive like @samp{#if}. To be safe, you are probably best keeping it
-out of directives other than @samp{#define}, and putting it on a line of
-its own.
-
-This manual documents the pragmas which are meaningful to the
-preprocessor itself. Other pragmas are meaningful to the C or C++
-compilers. They are documented in the GCC manual.
-
-GCC plugins may provide their own pragmas.
-
-@ftable @code
-@item #pragma GCC dependency
-@code{#pragma GCC dependency} allows you to check the relative dates of
-the current file and another file. If the other file is more recent than
-the current file, a warning is issued. This is useful if the current
-file is derived from the other file, and should be regenerated. The
-other file is searched for using the normal include search path.
-Optional trailing text can be used to give more information in the
-warning message.
-
-@smallexample
-#pragma GCC dependency "parse.y"
-#pragma GCC dependency "/usr/include/time.h" rerun fixincludes
-@end smallexample
-
-@item #pragma GCC poison
-Sometimes, there is an identifier that you want to remove completely
-from your program, and make sure that it never creeps back in. To
-enforce this, you can @dfn{poison} the identifier with this pragma.
-@code{#pragma GCC poison} is followed by a list of identifiers to
-poison. If any of those identifiers appears anywhere in the source
-after the directive, it is a hard error. For example,
-
-@smallexample
-#pragma GCC poison printf sprintf fprintf
-sprintf(some_string, "hello");
-@end smallexample
-
-@noindent
-will produce an error.
-
-If a poisoned identifier appears as part of the expansion of a macro
-which was defined before the identifier was poisoned, it will @emph{not}
-cause an error. This lets you poison an identifier without worrying
-about system headers defining macros that use it.
-
-For example,
-
-@smallexample
-#define strrchr rindex
-#pragma GCC poison rindex
-strrchr(some_string, 'h');
-@end smallexample
-
-@noindent
-will not produce an error.
-
-@item #pragma GCC system_header
-This pragma takes no arguments. It causes the rest of the code in the
-current file to be treated as if it came from a system header.
-@xref{System Headers}.
-
-@item #pragma GCC warning
-@itemx #pragma GCC error
-@code{#pragma GCC warning "message"} causes the preprocessor to issue
-a warning diagnostic with the text @samp{message}. The message
-contained in the pragma must be a single string literal. Similarly,
-@code{#pragma GCC error "message"} issues an error message. Unlike
-the @samp{#warning} and @samp{#error} directives, these pragmas can be
-embedded in preprocessor macros using @samp{_Pragma}.
-
-@item #pragma once
-If @code{#pragma once} is seen when scanning a header file, that
-file will never be read again, no matter what. It is a less-portable
-alternative to using @samp{#ifndef} to guard the contents of header files
-against multiple inclusions.
-
-@end ftable
-
-@node Other Directives
-@chapter Other Directives
-
-@findex #ident
-@findex #sccs
-The @samp{#ident} directive takes one argument, a string constant. On
-some systems, that string constant is copied into a special segment of
-the object file. On other systems, the directive is ignored. The
-@samp{#sccs} directive is a synonym for @samp{#ident}.
-
-These directives are not part of the C standard, but they are not
-official GNU extensions either. What historical information we have
-been able to find, suggests they originated with System V@.
-
-@cindex null directive
-The @dfn{null directive} consists of a @samp{#} followed by a newline,
-with only whitespace (including comments) in between. A null directive
-is understood as a preprocessing directive but has no effect on the
-preprocessor output. The primary significance of the existence of the
-null directive is that an input line consisting of just a @samp{#} will
-produce no output, rather than a line of output containing just a
-@samp{#}. Supposedly some old C programs contain such lines.
-
-@node Preprocessor Output
-@chapter Preprocessor Output
-
-When the C preprocessor is used with the C, C++, or Objective-C
-compilers, it is integrated into the compiler and communicates a stream
-of binary tokens directly to the compiler's parser. However, it can
-also be used in the more conventional standalone mode, where it produces
-textual output.
-@c FIXME: Document the library interface.
-
-@cindex output format
-The output from the C preprocessor looks much like the input, except
-that all preprocessing directive lines have been replaced with blank
-lines and all comments with spaces. Long runs of blank lines are
-discarded.
-
-The ISO standard specifies that it is implementation defined whether a
-preprocessor preserves whitespace between tokens, or replaces it with
-e.g.@: a single space. In GNU CPP, whitespace between tokens is collapsed
-to become a single space, with the exception that the first token on a
-non-directive line is preceded with sufficient spaces that it appears in
-the same column in the preprocessed output that it appeared in the
-original source file. This is so the output is easy to read.
-CPP does not insert any
-whitespace where there was none in the original source, except where
-necessary to prevent an accidental token paste.
-
-@cindex linemarkers
-Source file name and line number information is conveyed by lines
-of the form
-
-@smallexample
-# @var{linenum} @var{filename} @var{flags}
-@end smallexample
-
-@noindent
-These are called @dfn{linemarkers}. They are inserted as needed into
-the output (but never within a string or character constant). They mean
-that the following line originated in file @var{filename} at line
-@var{linenum}. @var{filename} will never contain any non-printing
-characters; they are replaced with octal escape sequences.
-
-After the file name comes zero or more flags, which are @samp{1},
-@samp{2}, @samp{3}, or @samp{4}. If there are multiple flags, spaces
-separate them. Here is what the flags mean:
-
-@table @samp
-@item 1
-This indicates the start of a new file.
-@item 2
-This indicates returning to a file (after having included another file).
-@item 3
-This indicates that the following text comes from a system header file,
-so certain warnings should be suppressed.
-@item 4
-This indicates that the following text should be treated as being
-wrapped in an implicit @code{extern "C"} block.
-@c maybe cross reference SYSTEM_IMPLICIT_EXTERN_C
-@end table
-
-As an extension, the preprocessor accepts linemarkers in non-assembler
-input files. They are treated like the corresponding @samp{#line}
-directive, (@pxref{Line Control}), except that trailing flags are
-permitted, and are interpreted with the meanings described above. If
-multiple flags are given, they must be in ascending order.
-
-Some directives may be duplicated in the output of the preprocessor.
-These are @samp{#ident} (always), @samp{#pragma} (only if the
-preprocessor does not handle the pragma itself), and @samp{#define} and
-@samp{#undef} (with certain debugging options). If this happens, the
-@samp{#} of the directive will always be in the first column, and there
-will be no space between the @samp{#} and the directive name. If macro
-expansion happens to generate tokens which might be mistaken for a
-duplicated directive, a space will be inserted between the @samp{#} and
-the directive name.
-
-@node Traditional Mode
-@chapter Traditional Mode
-
-Traditional (pre-standard) C preprocessing is rather different from
-the preprocessing specified by the standard. When the preprocessor
-is invoked with the
-@option{-traditional-cpp} option, it attempts to emulate a traditional
-preprocessor.
-
-This mode is not useful for compiling C code with GCC,
-but is intended for use with non-C preprocessing applications. Thus
-traditional mode semantics are supported only when invoking
-the preprocessor explicitly, and not in the compiler front ends.
-
-The implementation does not correspond precisely to the behavior of
-early pre-standard versions of GCC, nor to any true traditional preprocessor.
-After all, inconsistencies among traditional implementations were a
-major motivation for C standardization. However, we intend that it
-should be compatible with true traditional preprocessors in all ways
-that actually matter.
-
-@menu
-* Traditional lexical analysis::
-* Traditional macros::
-* Traditional miscellany::
-* Traditional warnings::
-@end menu
-
-@node Traditional lexical analysis
-@section Traditional lexical analysis
-
-The traditional preprocessor does not decompose its input into tokens
-the same way a standards-conforming preprocessor does. The input is
-simply treated as a stream of text with minimal internal form.
-
-This implementation does not treat trigraphs (@pxref{trigraphs})
-specially since they were an invention of the standards committee. It
-handles arbitrarily-positioned escaped newlines properly and splices
-the lines as you would expect; many traditional preprocessors did not
-do this.
-
-The form of horizontal whitespace in the input file is preserved in
-the output. In particular, hard tabs remain hard tabs. This can be
-useful if, for example, you are preprocessing a Makefile.
-
-Traditional CPP only recognizes C-style block comments, and treats the
-@samp{/*} sequence as introducing a comment only if it lies outside
-quoted text. Quoted text is introduced by the usual single and double
-quotes, and also by an initial @samp{<} in a @code{#include}
-directive.
-
-Traditionally, comments are completely removed and are not replaced
-with a space. Since a traditional compiler does its own tokenization
-of the output of the preprocessor, this means that comments can
-effectively be used as token paste operators. However, comments
-behave like separators for text handled by the preprocessor itself,
-since it doesn't re-lex its input. For example, in
-
-@smallexample
-#if foo/**/bar
-@end smallexample
-
-@noindent
-@samp{foo} and @samp{bar} are distinct identifiers and expanded
-separately if they happen to be macros. In other words, this
-directive is equivalent to
-
-@smallexample
-#if foo bar
-@end smallexample
-
-@noindent
-rather than
-
-@smallexample
-#if foobar
-@end smallexample
-
-Generally speaking, in traditional mode an opening quote need not have
-a matching closing quote. In particular, a macro may be defined with
-replacement text that contains an unmatched quote. Of course, if you
-attempt to compile preprocessed output containing an unmatched quote
-you will get a syntax error.
-
-However, all preprocessing directives other than @code{#define}
-require matching quotes. For example:
-
-@smallexample
-#define m This macro's fine and has an unmatched quote
-"/* This is not a comment. */
-/* @r{This is a comment. The following #include directive
- is ill-formed.} */
-#include <stdio.h
-@end smallexample
-
-Just as for the ISO preprocessor, what would be a closing quote can be
-escaped with a backslash to prevent the quoted text from closing.
-
-@node Traditional macros
-@section Traditional macros
-
-The major difference between traditional and ISO macros is that the
-former expand to text rather than to a token sequence. CPP removes
-all leading and trailing horizontal whitespace from a macro's
-replacement text before storing it, but preserves the form of internal
-whitespace.
-
-One consequence is that it is legitimate for the replacement text to
-contain an unmatched quote (@pxref{Traditional lexical analysis}). An
-unclosed string or character constant continues into the text
-following the macro call. Similarly, the text at the end of a macro's
-expansion can run together with the text after the macro invocation to
-produce a single token.
-
-Normally comments are removed from the replacement text after the
-macro is expanded, but if the @option{-CC} option is passed on the
-command-line comments are preserved. (In fact, the current
-implementation removes comments even before saving the macro
-replacement text, but it careful to do it in such a way that the
-observed effect is identical even in the function-like macro case.)
-
-The ISO stringizing operator @samp{#} and token paste operator
-@samp{##} have no special meaning. As explained later, an effect
-similar to these operators can be obtained in a different way. Macro
-names that are embedded in quotes, either from the main file or after
-macro replacement, do not expand.
-
-CPP replaces an unquoted object-like macro name with its replacement
-text, and then rescans it for further macros to replace. Unlike
-standard macro expansion, traditional macro expansion has no provision
-to prevent recursion. If an object-like macro appears unquoted in its
-replacement text, it will be replaced again during the rescan pass,
-and so on @emph{ad infinitum}. GCC detects when it is expanding
-recursive macros, emits an error message, and continues after the
-offending macro invocation.
-
-@smallexample
-#define PLUS +
-#define INC(x) PLUS+x
-INC(foo);
- @expansion{} ++foo;
-@end smallexample
-
-Function-like macros are similar in form but quite different in
-behavior to their ISO counterparts. Their arguments are contained
-within parentheses, are comma-separated, and can cross physical lines.
-Commas within nested parentheses are not treated as argument
-separators. Similarly, a quote in an argument cannot be left
-unclosed; a following comma or parenthesis that comes before the
-closing quote is treated like any other character. There is no
-facility for handling variadic macros.
-
-This implementation removes all comments from macro arguments, unless
-the @option{-C} option is given. The form of all other horizontal
-whitespace in arguments is preserved, including leading and trailing
-whitespace. In particular
-
-@smallexample
-f( )
-@end smallexample
-
-@noindent
-is treated as an invocation of the macro @samp{f} with a single
-argument consisting of a single space. If you want to invoke a
-function-like macro that takes no arguments, you must not leave any
-whitespace between the parentheses.
-
-If a macro argument crosses a new line, the new line is replaced with
-a space when forming the argument. If the previous line contained an
-unterminated quote, the following line inherits the quoted state.
-
-Traditional preprocessors replace parameters in the replacement text
-with their arguments regardless of whether the parameters are within
-quotes or not. This provides a way to stringize arguments. For
-example
-
-@smallexample
-#define str(x) "x"
-str(/* @r{A comment} */some text )
- @expansion{} "some text "
-@end smallexample
-
-@noindent
-Note that the comment is removed, but that the trailing space is
-preserved. Here is an example of using a comment to effect token
-pasting.
-
-@smallexample
-#define suffix(x) foo_/**/x
-suffix(bar)
- @expansion{} foo_bar
-@end smallexample
-
-@node Traditional miscellany
-@section Traditional miscellany
-
-Here are some things to be aware of when using the traditional
-preprocessor.
-
-@itemize @bullet
-@item
-Preprocessing directives are recognized only when their leading
-@samp{#} appears in the first column. There can be no whitespace
-between the beginning of the line and the @samp{#}, but whitespace can
-follow the @samp{#}.
-
-@item
-A true traditional C preprocessor does not recognize @samp{#error} or
-@samp{#pragma}, and may not recognize @samp{#elif}. CPP supports all
-the directives in traditional mode that it supports in ISO mode,
-including extensions, with the exception that the effects of
-@samp{#pragma GCC poison} are undefined.
-
-@item
-__STDC__ is not defined.
-
-@item
-If you use digraphs the behavior is undefined.
-
-@item
-If a line that looks like a directive appears within macro arguments,
-the behavior is undefined.
-
-@end itemize
-
-@node Traditional warnings
-@section Traditional warnings
-You can request warnings about features that did not exist, or worked
-differently, in traditional C with the @option{-Wtraditional} option.
-GCC does not warn about features of ISO C which you must use when you
-are using a conforming compiler, such as the @samp{#} and @samp{##}
-operators.
-
-Presently @option{-Wtraditional} warns about:
-
-@itemize @bullet
-@item
-Macro parameters that appear within string literals in the macro body.
-In traditional C macro replacement takes place within string literals,
-but does not in ISO C@.
-
-@item
-In traditional C, some preprocessor directives did not exist.
-Traditional preprocessors would only consider a line to be a directive
-if the @samp{#} appeared in column 1 on the line. Therefore
-@option{-Wtraditional} warns about directives that traditional C
-understands but would ignore because the @samp{#} does not appear as the
-first character on the line. It also suggests you hide directives like
-@samp{#pragma} not understood by traditional C by indenting them. Some
-traditional implementations would not recognize @samp{#elif}, so it
-suggests avoiding it altogether.
-
-@item
-A function-like macro that appears without an argument list. In some
-traditional preprocessors this was an error. In ISO C it merely means
-that the macro is not expanded.
-
-@item
-The unary plus operator. This did not exist in traditional C@.
-
-@item
-The @samp{U} and @samp{LL} integer constant suffixes, which were not
-available in traditional C@. (Traditional C does support the @samp{L}
-suffix for simple long integer constants.) You are not warned about
-uses of these suffixes in macros defined in system headers. For
-instance, @code{UINT_MAX} may well be defined as @code{4294967295U}, but
-you will not be warned if you use @code{UINT_MAX}.
-
-You can usually avoid the warning, and the related warning about
-constants which are so large that they are unsigned, by writing the
-integer constant in question in hexadecimal, with no U suffix. Take
-care, though, because this gives the wrong result in exotic cases.
-@end itemize
-
-@node Implementation Details
-@chapter Implementation Details
-
-Here we document details of how the preprocessor's implementation
-affects its user-visible behavior. You should try to avoid undue
-reliance on behavior described here, as it is possible that it will
-change subtly in future implementations.
-
-Also documented here are obsolete features still supported by CPP@.
-
-@menu
-* Implementation-defined behavior::
-* Implementation limits::
-* Obsolete Features::
-@end menu
-
-@node Implementation-defined behavior
-@section Implementation-defined behavior
-@cindex implementation-defined behavior
-
-This is how CPP behaves in all the cases which the C standard
-describes as @dfn{implementation-defined}. This term means that the
-implementation is free to do what it likes, but must document its choice
-and stick to it.
-@c FIXME: Check the C++ standard for more implementation-defined stuff.
-
-@itemize @bullet
-@need 1000
-@item The mapping of physical source file multi-byte characters to the
-execution character set.
-
-The input character set can be specified using the
-@option{-finput-charset} option, while the execution character set may
-be controlled using the @option{-fexec-charset} and
-@option{-fwide-exec-charset} options.
-
-@item Identifier characters.
-@anchor{Identifier characters}
-
-The C and C++ standards allow identifiers to be composed of @samp{_}
-and the alphanumeric characters. C++ also allows universal character
-names. C99 and later C standards permit both universal character
-names and implementation-defined characters. In both C and C++ modes,
-GCC accepts in identifiers exactly those extended characters that
-correspond to universal character names permitted by the chosen
-standard.
-
-GCC allows the @samp{$} character in identifiers as an extension for
-most targets. This is true regardless of the @option{std=} switch,
-since this extension cannot conflict with standards-conforming
-programs. When preprocessing assembler, however, dollars are not
-identifier characters by default.
-
-Currently the targets that by default do not permit @samp{$} are AVR,
-IP2K, MMIX, MIPS Irix 3, ARM aout, and PowerPC targets for the AIX
-operating system.
-
-You can override the default with @option{-fdollars-in-identifiers} or
-@option{-fno-dollars-in-identifiers}. @xref{fdollars-in-identifiers}.
-
-@item Non-empty sequences of whitespace characters.
-
-In textual output, each whitespace sequence is collapsed to a single
-space. For aesthetic reasons, the first token on each non-directive
-line of output is preceded with sufficient spaces that it appears in the
-same column as it did in the original source file.
-
-@item The numeric value of character constants in preprocessor expressions.
-
-The preprocessor and compiler interpret character constants in the
-same way; i.e.@: escape sequences such as @samp{\a} are given the
-values they would have on the target machine.
-
-The compiler evaluates a multi-character character constant a character
-at a time, shifting the previous value left by the number of bits per
-target character, and then or-ing in the bit-pattern of the new
-character truncated to the width of a target character. The final
-bit-pattern is given type @code{int}, and is therefore signed,
-regardless of whether single characters are signed or not.
-If there are more
-characters in the constant than would fit in the target @code{int} the
-compiler issues a warning, and the excess leading characters are
-ignored.
-
-For example, @code{'ab'} for a target with an 8-bit @code{char} would be
-interpreted as @w{@samp{(int) ((unsigned char) 'a' * 256 + (unsigned char)
-'b')}}, and @code{'\234a'} as @w{@samp{(int) ((unsigned char) '\234' *
-256 + (unsigned char) 'a')}}.
-
-@item Source file inclusion.
-
-For a discussion on how the preprocessor locates header files,
-@ref{Include Operation}.
-
-@item Interpretation of the filename resulting from a macro-expanded
-@samp{#include} directive.
-
-@xref{Computed Includes}.
-
-@item Treatment of a @samp{#pragma} directive that after macro-expansion
-results in a standard pragma.
-
-No macro expansion occurs on any @samp{#pragma} directive line, so the
-question does not arise.
-
-Note that GCC does not yet implement any of the standard
-pragmas.
-
-@end itemize
-
-@node Implementation limits
-@section Implementation limits
-@cindex implementation limits
-
-CPP has a small number of internal limits. This section lists the
-limits which the C standard requires to be no lower than some minimum,
-and all the others known. It is intended that there should be as few limits
-as possible. If you encounter an undocumented or inconvenient limit,
-please report that as a bug. @xref{Bugs, , Reporting Bugs, gcc, Using
-the GNU Compiler Collection (GCC)}.
-
-Where we say something is limited @dfn{only by available memory}, that
-means that internal data structures impose no intrinsic limit, and space
-is allocated with @code{malloc} or equivalent. The actual limit will
-therefore depend on many things, such as the size of other things
-allocated by the compiler at the same time, the amount of memory
-consumed by other processes on the same computer, etc.
-
-@itemize @bullet
-
-@item Nesting levels of @samp{#include} files.
-
-We impose an arbitrary limit of 200 levels, to avoid runaway recursion.
-The standard requires at least 15 levels.
-
-@item Nesting levels of conditional inclusion.
-
-The C standard mandates this be at least 63. CPP is limited only by
-available memory.
-
-@item Levels of parenthesized expressions within a full expression.
-
-The C standard requires this to be at least 63. In preprocessor
-conditional expressions, it is limited only by available memory.
-
-@item Significant initial characters in an identifier or macro name.
-
-The preprocessor treats all characters as significant. The C standard
-requires only that the first 63 be significant.
-
-@item Number of macros simultaneously defined in a single translation unit.
-
-The standard requires at least 4095 be possible. CPP is limited only
-by available memory.
-
-@item Number of parameters in a macro definition and arguments in a macro call.
-
-We allow @code{USHRT_MAX}, which is no smaller than 65,535. The minimum
-required by the standard is 127.
-
-@item Number of characters on a logical source line.
-
-The C standard requires a minimum of 4096 be permitted. CPP places
-no limits on this, but you may get incorrect column numbers reported in
-diagnostics for lines longer than 65,535 characters.
-
-@item Maximum size of a source file.
-
-The standard does not specify any lower limit on the maximum size of a
-source file. GNU cpp maps files into memory, so it is limited by the
-available address space. This is generally at least two gigabytes.
-Depending on the operating system, the size of physical memory may or
-may not be a limitation.
-
-@end itemize
-
-@node Obsolete Features
-@section Obsolete Features
-
-CPP has some features which are present mainly for compatibility with
-older programs. We discourage their use in new code. In some cases,
-we plan to remove the feature in a future version of GCC@.
-
-@subsection Assertions
-@cindex assertions
-
-@dfn{Assertions} are a deprecated alternative to macros in writing
-conditionals to test what sort of computer or system the compiled
-program will run on. Assertions are usually predefined, but you can
-define them with preprocessing directives or command-line options.
-
-Assertions were intended to provide a more systematic way to describe
-the compiler's target system and we added them for compatibility with
-existing compilers. In practice they are just as unpredictable as the
-system-specific predefined macros. In addition, they are not part of
-any standard, and only a few compilers support them.
-Therefore, the use of assertions is @strong{less} portable than the use
-of system-specific predefined macros. We recommend you do not use them at
-all.
-
-@cindex predicates
-An assertion looks like this:
-
-@smallexample
-#@var{predicate} (@var{answer})
-@end smallexample
-
-@noindent
-@var{predicate} must be a single identifier. @var{answer} can be any
-sequence of tokens; all characters are significant except for leading
-and trailing whitespace, and differences in internal whitespace
-sequences are ignored. (This is similar to the rules governing macro
-redefinition.) Thus, @code{(x + y)} is different from @code{(x+y)} but
-equivalent to @code{@w{( x + y )}}. Parentheses do not nest inside an
-answer.
-
-@cindex testing predicates
-To test an assertion, you write it in an @samp{#if}. For example, this
-conditional succeeds if either @code{vax} or @code{ns16000} has been
-asserted as an answer for @code{machine}.
-
-@smallexample
-#if #machine (vax) || #machine (ns16000)
-@end smallexample
-
-@noindent
-You can test whether @emph{any} answer is asserted for a predicate by
-omitting the answer in the conditional:
-
-@smallexample
-#if #machine
-@end smallexample
-
-@findex #assert
-Assertions are made with the @samp{#assert} directive. Its sole
-argument is the assertion to make, without the leading @samp{#} that
-identifies assertions in conditionals.
-
-@smallexample
-#assert @var{predicate} (@var{answer})
-@end smallexample
-
-@noindent
-You may make several assertions with the same predicate and different
-answers. Subsequent assertions do not override previous ones for the
-same predicate. All the answers for any given predicate are
-simultaneously true.
-
-@cindex assertions, canceling
-@findex #unassert
-Assertions can be canceled with the @samp{#unassert} directive. It
-has the same syntax as @samp{#assert}. In that form it cancels only the
-answer which was specified on the @samp{#unassert} line; other answers
-for that predicate remain true. You can cancel an entire predicate by
-leaving out the answer:
-
-@smallexample
-#unassert @var{predicate}
-@end smallexample
-
-@noindent
-In either form, if no such assertion has been made, @samp{#unassert} has
-no effect.
-
-You can also make or cancel assertions using command-line options.
-@xref{Invocation}.
-
-@node Invocation
-@chapter Invocation
-@cindex invocation
-@cindex command line
-
-Most often when you use the C preprocessor you do not have to invoke it
-explicitly: the C compiler does so automatically. However, the
-preprocessor is sometimes useful on its own. You can invoke the
-preprocessor either with the @command{cpp} command, or via @command{gcc -E}.
-In GCC, the preprocessor is actually integrated with the compiler
-rather than a separate program, and both of these commands invoke
-GCC and tell it to stop after the preprocessing phase.
-
-The @command{cpp} options listed here are also accepted by
-@command{gcc} and have the same meaning. Likewise the @command{cpp}
-command accepts all the usual @command{gcc} driver options, although those
-pertaining to compilation phases after preprocessing are ignored.
-
-Only options specific to preprocessing behavior are documented here.
-Refer to the GCC manual for full documentation of other driver options.
-
-@ignore
-@c man begin SYNOPSIS
-cpp [@option{-D}@var{macro}[=@var{defn}]@dots{}] [@option{-U}@var{macro}]
- [@option{-I}@var{dir}@dots{}] [@option{-iquote}@var{dir}@dots{}]
- [@option{-M}|@option{-MM}] [@option{-MG}] [@option{-MF} @var{filename}]
- [@option{-MP}] [@option{-MQ} @var{target}@dots{}]
- [@option{-MT} @var{target}@dots{}]
- @var{infile} [[@option{-o}] @var{outfile}]
-
-Only the most useful options are given above; see below for a more
-complete list of preprocessor-specific options.
-In addition, @command{cpp} accepts most @command{gcc} driver options, which
-are not listed here. Refer to the GCC documentation for details.
-@c man end
-@c man begin SEEALSO
-gpl(7), gfdl(7), fsf-funding(7),
-gcc(1), and the Info entries for @file{cpp} and @file{gcc}.
-@c man end
-@end ignore
-
-@c man begin OPTIONS
-The @command{cpp} command expects two file names as arguments, @var{infile} and
-@var{outfile}. The preprocessor reads @var{infile} together with any
-other files it specifies with @samp{#include}. All the output generated
-by the combined input files is written in @var{outfile}.
-
-Either @var{infile} or @var{outfile} may be @option{-}, which as
-@var{infile} means to read from standard input and as @var{outfile}
-means to write to standard output. If either file is omitted, it
-means the same as if @option{-} had been specified for that file.
-You can also use the @option{-o @var{outfile}} option to specify the
-output file.
-
-Unless otherwise noted, or the option ends in @samp{=}, all options
-which take an argument may have that argument appear either immediately
-after the option, or with a space between option and argument:
-@option{-Ifoo} and @option{-I foo} have the same effect.
-
-@cindex grouping options
-@cindex options, grouping
-Many options have multi-letter names; therefore multiple single-letter
-options may @emph{not} be grouped: @option{-dM} is very different from
-@w{@samp{-d -M}}.
-
-@cindex options
-
-@table @gcctabopt
-@include cppopts.texi
-@include cppdiropts.texi
-@include cppwarnopts.texi
-@end table
-@c man end
-
-@node Environment Variables
-@chapter Environment Variables
-@cindex environment variables
-@c man begin ENVIRONMENT
-
-This section describes the environment variables that affect how CPP
-operates. You can use them to specify directories or prefixes to use
-when searching for include files, or to control dependency output.
-
-Note that you can also specify places to search using options such as
-@option{-I}, and control dependency output with options like
-@option{-M} (@pxref{Invocation}). These take precedence over
-environment variables, which in turn take precedence over the
-configuration of GCC@.
-
-@include cppenv.texi
-@c man end
-
-@page
-@include fdl.texi
-
-@page
-@node Index of Directives
-@unnumbered Index of Directives
-@printindex fn
-
-@node Option Index
-@unnumbered Option Index
-@noindent
-CPP's command-line options and environment variables are indexed here
-without any initial @samp{-} or @samp{--}.
-@printindex op
-
-@page
-@node Concept Index
-@unnumbered Concept Index
-@printindex cp
-
-@bye
+++ /dev/null
-@c Copyright (C) 1999-2022 Free Software Foundation, Inc.
-@c This is part of the CPP and GCC manuals.
-@c For copying conditions, see the file gcc.texi.
-
-@c ---------------------------------------------------------------------
-@c Options affecting include directory search in the preprocessor
-@c ---------------------------------------------------------------------
-
-@c If this file is included with the flag ``cppmanual'' set, it is
-@c formatted for inclusion in the CPP manual; otherwise the main GCC manual.
-
-@item -I @var{dir}
-@itemx -iquote @var{dir}
-@itemx -isystem @var{dir}
-@itemx -idirafter @var{dir}
-@opindex I
-@opindex iquote
-@opindex isystem
-@opindex idirafter
-Add the directory @var{dir} to the list of directories to be searched
-for header files during preprocessing.
-@ifset cppmanual
-@xref{Search Path}.
-@end ifset
-If @var{dir} begins with @samp{=} or @code{$SYSROOT}, then the @samp{=}
-or @code{$SYSROOT} is replaced by the sysroot prefix; see
-@option{--sysroot} and @option{-isysroot}.
-
-Directories specified with @option{-iquote} apply only to the quote
-form of the directive, @code{@w{#include "@var{file}"}}.
-Directories specified with @option{-I}, @option{-isystem},
-or @option{-idirafter} apply to lookup for both the
-@code{@w{#include "@var{file}"}} and
-@code{@w{#include <@var{file}>}} directives.
-
-You can specify any number or combination of these options on the
-command line to search for header files in several directories.
-The lookup order is as follows:
-
-@enumerate
-@item
-For the quote form of the include directive, the directory of the current
-file is searched first.
-
-@item
-For the quote form of the include directive, the directories specified
-by @option{-iquote} options are searched in left-to-right order,
-as they appear on the command line.
-
-@item
-Directories specified with @option{-I} options are scanned in
-left-to-right order.
-
-@item
-Directories specified with @option{-isystem} options are scanned in
-left-to-right order.
-
-@item
-Standard system directories are scanned.
-
-@item
-Directories specified with @option{-idirafter} options are scanned in
-left-to-right order.
-@end enumerate
-
-You can use @option{-I} to override a system header
-file, substituting your own version, since these directories are
-searched before the standard system header file directories.
-However, you should
-not use this option to add directories that contain vendor-supplied
-system header files; use @option{-isystem} for that.
-
-The @option{-isystem} and @option{-idirafter} options also mark the directory
-as a system directory, so that it gets the same special treatment that
-is applied to the standard system directories.
-@ifset cppmanual
-@xref{System Headers}.
-@end ifset
-
-If a standard system include directory, or a directory specified with
-@option{-isystem}, is also specified with @option{-I}, the @option{-I}
-option is ignored. The directory is still searched but as a
-system directory at its normal position in the system include chain.
-This is to ensure that GCC's procedure to fix buggy system headers and
-the ordering for the @code{#include_next} directive are not inadvertently
-changed.
-If you really need to change the search order for system directories,
-use the @option{-nostdinc} and/or @option{-isystem} options.
-@ifset cppmanual
-@xref{System Headers}.
-@end ifset
-
-@item -I-
-@opindex I-
-Split the include path.
-This option has been deprecated. Please use @option{-iquote} instead for
-@option{-I} directories before the @option{-I-} and remove the @option{-I-}
-option.
-
-Any directories specified with @option{-I}
-options before @option{-I-} are searched only for headers requested with
-@code{@w{#include "@var{file}"}}; they are not searched for
-@code{@w{#include <@var{file}>}}. If additional directories are
-specified with @option{-I} options after the @option{-I-}, those
-directories are searched for all @samp{#include} directives.
-
-In addition, @option{-I-} inhibits the use of the directory of the current
-file directory as the first search directory for @code{@w{#include
-"@var{file}"}}. There is no way to override this effect of @option{-I-}.
-@ifset cppmanual
-@xref{Search Path}.
-@end ifset
-
-@item -iprefix @var{prefix}
-@opindex iprefix
-Specify @var{prefix} as the prefix for subsequent @option{-iwithprefix}
-options. If the prefix represents a directory, you should include the
-final @samp{/}.
-
-@item -iwithprefix @var{dir}
-@itemx -iwithprefixbefore @var{dir}
-@opindex iwithprefix
-@opindex iwithprefixbefore
-Append @var{dir} to the prefix specified previously with
-@option{-iprefix}, and add the resulting directory to the include search
-path. @option{-iwithprefixbefore} puts it in the same place @option{-I}
-would; @option{-iwithprefix} puts it where @option{-idirafter} would.
-
-@item -isysroot @var{dir}
-@opindex isysroot
-This option is like the @option{--sysroot} option, but applies only to
-header files (except for Darwin targets, where it applies to both header
-files and libraries). See the @option{--sysroot} option for more
-information.
-
-@item -imultilib @var{dir}
-@opindex imultilib
-Use @var{dir} as a subdirectory of the directory containing
-target-specific C++ headers.
-
-@item -nostdinc
-@opindex nostdinc
-Do not search the standard system directories for header files.
-Only the directories explicitly specified with @option{-I},
-@option{-iquote}, @option{-isystem}, and/or @option{-idirafter}
-options (and the directory of the current file, if appropriate)
-are searched.
-
-@item -nostdinc++
-@opindex nostdinc++
-Do not search for header files in the C++-specific standard directories,
-but do still search the other standard directories. (This option is
-used when building the C++ library.)
-
+++ /dev/null
-@c Copyright (C) 1999-2022 Free Software Foundation, Inc.
-@c This is part of the CPP and GCC manuals.
-@c For copying conditions, see the file gcc.texi.
-
-@c ---------------------------------------------------------------------
-@c Environment variables affecting the preprocessor
-@c ---------------------------------------------------------------------
-
-@c If this file is included with the flag ``cppmanual'' set, it is
-@c formatted for inclusion in the CPP manual; otherwise the main GCC manual.
-
-@vtable @env
-@item CPATH
-@itemx C_INCLUDE_PATH
-@itemx CPLUS_INCLUDE_PATH
-@itemx OBJC_INCLUDE_PATH
-@c Commented out until ObjC++ is part of GCC:
-@c @itemx OBJCPLUS_INCLUDE_PATH
-Each variable's value is a list of directories separated by a special
-character, much like @env{PATH}, in which to look for header files.
-The special character, @code{PATH_SEPARATOR}, is target-dependent and
-determined at GCC build time. For Microsoft Windows-based targets it is a
-semicolon, and for almost all other targets it is a colon.
-
-@env{CPATH} specifies a list of directories to be searched as if
-specified with @option{-I}, but after any paths given with @option{-I}
-options on the command line. This environment variable is used
-regardless of which language is being preprocessed.
-
-The remaining environment variables apply only when preprocessing the
-particular language indicated. Each specifies a list of directories
-to be searched as if specified with @option{-isystem}, but after any
-paths given with @option{-isystem} options on the command line.
-
-In all these variables, an empty element instructs the compiler to
-search its current working directory. Empty elements can appear at the
-beginning or end of a path. For instance, if the value of
-@env{CPATH} is @code{:/special/include}, that has the same
-effect as @samp{@w{-I. -I/special/include}}.
-
-@c man end
-@ifset cppmanual
-See also @ref{Search Path}.
-@end ifset
-@c man begin ENVIRONMENT
-
-@item DEPENDENCIES_OUTPUT
-@cindex dependencies for make as output
-If this variable is set, its value specifies how to output
-dependencies for Make based on the non-system header files processed
-by the compiler. System header files are ignored in the dependency
-output.
-
-The value of @env{DEPENDENCIES_OUTPUT} can be just a file name, in
-which case the Make rules are written to that file, guessing the target
-name from the source file name. Or the value can have the form
-@samp{@var{file} @var{target}}, in which case the rules are written to
-file @var{file} using @var{target} as the target name.
-
-In other words, this environment variable is equivalent to combining
-the options @option{-MM} and @option{-MF}
-@ifset cppmanual
-(@pxref{Invocation}),
-@end ifset
-@ifclear cppmanual
-(@pxref{Preprocessor Options}),
-@end ifclear
-with an optional @option{-MT} switch too.
-
-@item SUNPRO_DEPENDENCIES
-@cindex dependencies for make as output
-This variable is the same as @env{DEPENDENCIES_OUTPUT} (see above),
-except that system header files are not ignored, so it implies
-@option{-M} rather than @option{-MM}. However, the dependence on the
-main input file is omitted.
-@ifset cppmanual
-@xref{Invocation}.
-@end ifset
-@ifclear cppmanual
-@xref{Preprocessor Options}.
-@end ifclear
-
-@item SOURCE_DATE_EPOCH
-If this variable is set, its value specifies a UNIX timestamp to be
-used in replacement of the current date and time in the @code{__DATE__}
-and @code{__TIME__} macros, so that the embedded timestamps become
-reproducible.
-
-The value of @env{SOURCE_DATE_EPOCH} must be a UNIX timestamp,
-defined as the number of seconds (excluding leap seconds) since
-01 Jan 1970 00:00:00 represented in ASCII; identical to the output of
-@code{date +%s} on GNU/Linux and other systems that support the
-@code{%s} extension in the @code{date} command.
-
-The value should be a known timestamp such as the last modification
-time of the source or package and it should be set by the build
-process.
-
-@end vtable
+++ /dev/null
-\input texinfo
-@setfilename cppinternals.info
-@settitle The GNU C Preprocessor Internals
-
-@include gcc-common.texi
-
-@ifinfo
-@dircategory Software development
-@direntry
-* Cpplib: (cppinternals). Cpplib internals.
-@end direntry
-@end ifinfo
-
-@c @smallbook
-@c @cropmarks
-@c @finalout
-@setchapternewpage odd
-@ifinfo
-This file documents the internals of the GNU C Preprocessor.
-
-Copyright (C) 2000-2022 Free Software Foundation, Inc.
-
-Permission is granted to make and distribute verbatim copies of
-this manual provided the copyright notice and this permission notice
-are preserved on all copies.
-
-@ignore
-Permission is granted to process this file through Tex and print the
-results, provided the printed document carries copying permission
-notice identical to this one except for the removal of this paragraph
-(this paragraph not being relevant to the printed manual).
-
-@end ignore
-Permission is granted to copy and distribute modified versions of this
-manual under the conditions for verbatim copying, provided also that
-the entire resulting derived work is distributed under the terms of a
-permission notice identical to this one.
-
-Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified versions.
-@end ifinfo
-
-@titlepage
-@title Cpplib Internals
-@versionsubtitle
-@author Neil Booth
-@page
-@vskip 0pt plus 1filll
-@c man begin COPYRIGHT
-Copyright @copyright{} 2000-2022 Free Software Foundation, Inc.
-
-Permission is granted to make and distribute verbatim copies of
-this manual provided the copyright notice and this permission notice
-are preserved on all copies.
-
-Permission is granted to copy and distribute modified versions of this
-manual under the conditions for verbatim copying, provided also that
-the entire resulting derived work is distributed under the terms of a
-permission notice identical to this one.
-
-Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified versions.
-@c man end
-@end titlepage
-@contents
-@page
-
-@ifnottex
-@node Top
-@top
-@chapter Cpplib---the GNU C Preprocessor
-
-The GNU C preprocessor is
-implemented as a library, @dfn{cpplib}, so it can be easily shared between
-a stand-alone preprocessor, and a preprocessor integrated with the C,
-C++ and Objective-C front ends. It is also available for use by other
-programs, though this is not recommended as its exposed interface has
-not yet reached a point of reasonable stability.
-
-The library has been written to be re-entrant, so that it can be used
-to preprocess many files simultaneously if necessary. It has also been
-written with the preprocessing token as the fundamental unit; the
-preprocessor in previous versions of GCC would operate on text strings
-as the fundamental unit.
-
-This brief manual documents the internals of cpplib, and explains some
-of the tricky issues. It is intended that, along with the comments in
-the source code, a reasonably competent C programmer should be able to
-figure out what the code is doing, and why things have been implemented
-the way they have.
-
-@menu
-* Conventions:: Conventions used in the code.
-* Lexer:: The combined C, C++ and Objective-C Lexer.
-* Hash Nodes:: All identifiers are entered into a hash table.
-* Macro Expansion:: Macro expansion algorithm.
-* Token Spacing:: Spacing and paste avoidance issues.
-* Line Numbering:: Tracking location within files.
-* Guard Macros:: Optimizing header files with guard macros.
-* Files:: File handling.
-* Concept Index:: Index.
-@end menu
-@end ifnottex
-
-@node Conventions
-@unnumbered Conventions
-@cindex interface
-@cindex header files
-
-cpplib has two interfaces---one is exposed internally only, and the
-other is for both internal and external use.
-
-The convention is that functions and types that are exposed to multiple
-files internally are prefixed with @samp{_cpp_}, and are to be found in
-the file @file{internal.h}. Functions and types exposed to external
-clients are in @file{cpplib.h}, and prefixed with @samp{cpp_}. For
-historical reasons this is no longer quite true, but we should strive to
-stick to it.
-
-We are striving to reduce the information exposed in @file{cpplib.h} to the
-bare minimum necessary, and then to keep it there. This makes clear
-exactly what external clients are entitled to assume, and allows us to
-change internals in the future without worrying whether library clients
-are perhaps relying on some kind of undocumented implementation-specific
-behavior.
-
-@node Lexer
-@unnumbered The Lexer
-@cindex lexer
-@cindex newlines
-@cindex escaped newlines
-
-@section Overview
-The lexer is contained in the file @file{lex.cc}. It is a hand-coded
-lexer, and not implemented as a state machine. It can understand C, C++
-and Objective-C source code, and has been extended to allow reasonably
-successful preprocessing of assembly language. The lexer does not make
-an initial pass to strip out trigraphs and escaped newlines, but handles
-them as they are encountered in a single pass of the input file. It
-returns preprocessing tokens individually, not a line at a time.
-
-It is mostly transparent to users of the library, since the library's
-interface for obtaining the next token, @code{cpp_get_token}, takes care
-of lexing new tokens, handling directives, and expanding macros as
-necessary. However, the lexer does expose some functionality so that
-clients of the library can easily spell a given token, such as
-@code{cpp_spell_token} and @code{cpp_token_len}. These functions are
-useful when generating diagnostics, and for emitting the preprocessed
-output.
-
-@section Lexing a token
-Lexing of an individual token is handled by @code{_cpp_lex_direct} and
-its subroutines. In its current form the code is quite complicated,
-with read ahead characters and such-like, since it strives to not step
-back in the character stream in preparation for handling non-ASCII file
-encodings. The current plan is to convert any such files to UTF-8
-before processing them. This complexity is therefore unnecessary and
-will be removed, so I'll not discuss it further here.
-
-The job of @code{_cpp_lex_direct} is simply to lex a token. It is not
-responsible for issues like directive handling, returning lookahead
-tokens directly, multiple-include optimization, or conditional block
-skipping. It necessarily has a minor r@^ole to play in memory
-management of lexed lines. I discuss these issues in a separate section
-(@pxref{Lexing a line}).
-
-The lexer places the token it lexes into storage pointed to by the
-variable @code{cur_token}, and then increments it. This variable is
-important for correct diagnostic positioning. Unless a specific line
-and column are passed to the diagnostic routines, they will examine the
-@code{line} and @code{col} values of the token just before the location
-that @code{cur_token} points to, and use that location to report the
-diagnostic.
-
-The lexer does not consider whitespace to be a token in its own right.
-If whitespace (other than a new line) precedes a token, it sets the
-@code{PREV_WHITE} bit in the token's flags. Each token has its
-@code{line} and @code{col} variables set to the line and column of the
-first character of the token. This line number is the line number in
-the translation unit, and can be converted to a source (file, line) pair
-using the line map code.
-
-The first token on a logical, i.e.@: unescaped, line has the flag
-@code{BOL} set for beginning-of-line. This flag is intended for
-internal use, both to distinguish a @samp{#} that begins a directive
-from one that doesn't, and to generate a call-back to clients that want
-to be notified about the start of every non-directive line with tokens
-on it. Clients cannot reliably determine this for themselves: the first
-token might be a macro, and the tokens of a macro expansion do not have
-the @code{BOL} flag set. The macro expansion may even be empty, and the
-next token on the line certainly won't have the @code{BOL} flag set.
-
-New lines are treated specially; exactly how the lexer handles them is
-context-dependent. The C standard mandates that directives are
-terminated by the first unescaped newline character, even if it appears
-in the middle of a macro expansion. Therefore, if the state variable
-@code{in_directive} is set, the lexer returns a @code{CPP_EOF} token,
-which is normally used to indicate end-of-file, to indicate
-end-of-directive. In a directive a @code{CPP_EOF} token never means
-end-of-file. Conveniently, if the caller was @code{collect_args}, it
-already handles @code{CPP_EOF} as if it were end-of-file, and reports an
-error about an unterminated macro argument list.
-
-The C standard also specifies that a new line in the middle of the
-arguments to a macro is treated as whitespace. This white space is
-important in case the macro argument is stringized. The state variable
-@code{parsing_args} is nonzero when the preprocessor is collecting the
-arguments to a macro call. It is set to 1 when looking for the opening
-parenthesis to a function-like macro, and 2 when collecting the actual
-arguments up to the closing parenthesis, since these two cases need to
-be distinguished sometimes. One such time is here: the lexer sets the
-@code{PREV_WHITE} flag of a token if it meets a new line when
-@code{parsing_args} is set to 2. It doesn't set it if it meets a new
-line when @code{parsing_args} is 1, since then code like
-
-@smallexample
-#define foo() bar
-foo
-baz
-@end smallexample
-
-@noindent would be output with an erroneous space before @samp{baz}:
-
-@smallexample
-foo
- baz
-@end smallexample
-
-This is a good example of the subtlety of getting token spacing correct
-in the preprocessor; there are plenty of tests in the testsuite for
-corner cases like this.
-
-The lexer is written to treat each of @samp{\r}, @samp{\n}, @samp{\r\n}
-and @samp{\n\r} as a single new line indicator. This allows it to
-transparently preprocess MS-DOS, Macintosh and Unix files without their
-needing to pass through a special filter beforehand.
-
-We also decided to treat a backslash, either @samp{\} or the trigraph
-@samp{??/}, separated from one of the above newline indicators by
-non-comment whitespace only, as intending to escape the newline. It
-tends to be a typing mistake, and cannot reasonably be mistaken for
-anything else in any of the C-family grammars. Since handling it this
-way is not strictly conforming to the ISO standard, the library issues a
-warning wherever it encounters it.
-
-Handling newlines like this is made simpler by doing it in one place
-only. The function @code{handle_newline} takes care of all newline
-characters, and @code{skip_escaped_newlines} takes care of arbitrarily
-long sequences of escaped newlines, deferring to @code{handle_newline}
-to handle the newlines themselves.
-
-The most painful aspect of lexing ISO-standard C and C++ is handling
-trigraphs and backlash-escaped newlines. Trigraphs are processed before
-any interpretation of the meaning of a character is made, and unfortunately
-there is a trigraph representation for a backslash, so it is possible for
-the trigraph @samp{??/} to introduce an escaped newline.
-
-Escaped newlines are tedious because theoretically they can occur
-anywhere---between the @samp{+} and @samp{=} of the @samp{+=} token,
-within the characters of an identifier, and even between the @samp{*}
-and @samp{/} that terminates a comment. Moreover, you cannot be sure
-there is just one---there might be an arbitrarily long sequence of them.
-
-So, for example, the routine that lexes a number, @code{parse_number},
-cannot assume that it can scan forwards until the first non-number
-character and be done with it, because this could be the @samp{\}
-introducing an escaped newline, or the @samp{?} introducing the trigraph
-sequence that represents the @samp{\} of an escaped newline. If it
-encounters a @samp{?} or @samp{\}, it calls @code{skip_escaped_newlines}
-to skip over any potential escaped newlines before checking whether the
-number has been finished.
-
-Similarly code in the main body of @code{_cpp_lex_direct} cannot simply
-check for a @samp{=} after a @samp{+} character to determine whether it
-has a @samp{+=} token; it needs to be prepared for an escaped newline of
-some sort. Such cases use the function @code{get_effective_char}, which
-returns the first character after any intervening escaped newlines.
-
-The lexer needs to keep track of the correct column position, including
-counting tabs as specified by the @option{-ftabstop=} option. This
-should be done even within C-style comments; they can appear in the
-middle of a line, and we want to report diagnostics in the correct
-position for text appearing after the end of the comment.
-
-@anchor{Invalid identifiers}
-Some identifiers, such as @code{__VA_ARGS__} and poisoned identifiers,
-may be invalid and require a diagnostic. However, if they appear in a
-macro expansion we don't want to complain with each use of the macro.
-It is therefore best to catch them during the lexing stage, in
-@code{parse_identifier}. In both cases, whether a diagnostic is needed
-or not is dependent upon the lexer's state. For example, we don't want
-to issue a diagnostic for re-poisoning a poisoned identifier, or for
-using @code{__VA_ARGS__} in the expansion of a variable-argument macro.
-Therefore @code{parse_identifier} makes use of state flags to determine
-whether a diagnostic is appropriate. Since we change state on a
-per-token basis, and don't lex whole lines at a time, this is not a
-problem.
-
-Another place where state flags are used to change behavior is whilst
-lexing header names. Normally, a @samp{<} would be lexed as a single
-token. After a @code{#include} directive, though, it should be lexed as
-a single token as far as the nearest @samp{>} character. Note that we
-don't allow the terminators of header names to be escaped; the first
-@samp{"} or @samp{>} terminates the header name.
-
-Interpretation of some character sequences depends upon whether we are
-lexing C, C++ or Objective-C, and on the revision of the standard in
-force. For example, @samp{::} is a single token in C++, but in C it is
-two separate @samp{:} tokens and almost certainly a syntax error. Such
-cases are handled by @code{_cpp_lex_direct} based upon command-line
-flags stored in the @code{cpp_options} structure.
-
-Once a token has been lexed, it leads an independent existence. The
-spelling of numbers, identifiers and strings is copied to permanent
-storage from the original input buffer, so a token remains valid and
-correct even if its source buffer is freed with @code{_cpp_pop_buffer}.
-The storage holding the spellings of such tokens remains until the
-client program calls cpp_destroy, probably at the end of the translation
-unit.
-
-@anchor{Lexing a line}
-@section Lexing a line
-@cindex token run
-
-When the preprocessor was changed to return pointers to tokens, one
-feature I wanted was some sort of guarantee regarding how long a
-returned pointer remains valid. This is important to the stand-alone
-preprocessor, the future direction of the C family front ends, and even
-to cpplib itself internally.
-
-Occasionally the preprocessor wants to be able to peek ahead in the
-token stream. For example, after the name of a function-like macro, it
-wants to check the next token to see if it is an opening parenthesis.
-Another example is that, after reading the first few tokens of a
-@code{#pragma} directive and not recognizing it as a registered pragma,
-it wants to backtrack and allow the user-defined handler for unknown
-pragmas to access the full @code{#pragma} token stream. The stand-alone
-preprocessor wants to be able to test the current token with the
-previous one to see if a space needs to be inserted to preserve their
-separate tokenization upon re-lexing (paste avoidance), so it needs to
-be sure the pointer to the previous token is still valid. The
-recursive-descent C++ parser wants to be able to perform tentative
-parsing arbitrarily far ahead in the token stream, and then to be able
-to jump back to a prior position in that stream if necessary.
-
-The rule I chose, which is fairly natural, is to arrange that the
-preprocessor lex all tokens on a line consecutively into a token buffer,
-which I call a @dfn{token run}, and when meeting an unescaped new line
-(newlines within comments do not count either), to start lexing back at
-the beginning of the run. Note that we do @emph{not} lex a line of
-tokens at once; if we did that @code{parse_identifier} would not have
-state flags available to warn about invalid identifiers (@pxref{Invalid
-identifiers}).
-
-In other words, accessing tokens that appeared earlier in the current
-line is valid, but since each logical line overwrites the tokens of the
-previous line, tokens from prior lines are unavailable. In particular,
-since a directive only occupies a single logical line, this means that
-the directive handlers like the @code{#pragma} handler can jump around
-in the directive's tokens if necessary.
-
-Two issues remain: what about tokens that arise from macro expansions,
-and what happens when we have a long line that overflows the token run?
-
-Since we promise clients that we preserve the validity of pointers that
-we have already returned for tokens that appeared earlier in the line,
-we cannot reallocate the run. Instead, on overflow it is expanded by
-chaining a new token run on to the end of the existing one.
-
-The tokens forming a macro's replacement list are collected by the
-@code{#define} handler, and placed in storage that is only freed by
-@code{cpp_destroy}. So if a macro is expanded in the line of tokens,
-the pointers to the tokens of its expansion that are returned will always
-remain valid. However, macros are a little trickier than that, since
-they give rise to three sources of fresh tokens. They are the built-in
-macros like @code{__LINE__}, and the @samp{#} and @samp{##} operators
-for stringizing and token pasting. I handled this by allocating
-space for these tokens from the lexer's token run chain. This means
-they automatically receive the same lifetime guarantees as lexed tokens,
-and we don't need to concern ourselves with freeing them.
-
-Lexing into a line of tokens solves some of the token memory management
-issues, but not all. The opening parenthesis after a function-like
-macro name might lie on a different line, and the front ends definitely
-want the ability to look ahead past the end of the current line. So
-cpplib only moves back to the start of the token run at the end of a
-line if the variable @code{keep_tokens} is zero. Line-buffering is
-quite natural for the preprocessor, and as a result the only time cpplib
-needs to increment this variable is whilst looking for the opening
-parenthesis to, and reading the arguments of, a function-like macro. In
-the near future cpplib will export an interface to increment and
-decrement this variable, so that clients can share full control over the
-lifetime of token pointers too.
-
-The routine @code{_cpp_lex_token} handles moving to new token runs,
-calling @code{_cpp_lex_direct} to lex new tokens, or returning
-previously-lexed tokens if we stepped back in the token stream. It also
-checks each token for the @code{BOL} flag, which might indicate a
-directive that needs to be handled, or require a start-of-line call-back
-to be made. @code{_cpp_lex_token} also handles skipping over tokens in
-failed conditional blocks, and invalidates the control macro of the
-multiple-include optimization if a token was successfully lexed outside
-a directive. In other words, its callers do not need to concern
-themselves with such issues.
-
-@node Hash Nodes
-@unnumbered Hash Nodes
-@cindex hash table
-@cindex identifiers
-@cindex macros
-@cindex assertions
-@cindex named operators
-
-When cpplib encounters an ``identifier'', it generates a hash code for
-it and stores it in the hash table. By ``identifier'' we mean tokens
-with type @code{CPP_NAME}; this includes identifiers in the usual C
-sense, as well as keywords, directive names, macro names and so on. For
-example, all of @code{pragma}, @code{int}, @code{foo} and
-@code{__GNUC__} are identifiers and hashed when lexed.
-
-Each node in the hash table contain various information about the
-identifier it represents. For example, its length and type. At any one
-time, each identifier falls into exactly one of three categories:
-
-@itemize @bullet
-@item Macros
-
-These have been declared to be macros, either on the command line or
-with @code{#define}. A few, such as @code{__TIME__} are built-ins
-entered in the hash table during initialization. The hash node for a
-normal macro points to a structure with more information about the
-macro, such as whether it is function-like, how many arguments it takes,
-and its expansion. Built-in macros are flagged as special, and instead
-contain an enum indicating which of the various built-in macros it is.
-
-@item Assertions
-
-Assertions are in a separate namespace to macros. To enforce this, cpp
-actually prepends a @code{#} character before hashing and entering it in
-the hash table. An assertion's node points to a chain of answers to
-that assertion.
-
-@item Void
-
-Everything else falls into this category---an identifier that is not
-currently a macro, or a macro that has since been undefined with
-@code{#undef}.
-
-When preprocessing C++, this category also includes the named operators,
-such as @code{xor}. In expressions these behave like the operators they
-represent, but in contexts where the spelling of a token matters they
-are spelt differently. This spelling distinction is relevant when they
-are operands of the stringizing and pasting macro operators @code{#} and
-@code{##}. Named operator hash nodes are flagged, both to catch the
-spelling distinction and to prevent them from being defined as macros.
-@end itemize
-
-The same identifiers share the same hash node. Since each identifier
-token, after lexing, contains a pointer to its hash node, this is used
-to provide rapid lookup of various information. For example, when
-parsing a @code{#define} statement, CPP flags each argument's identifier
-hash node with the index of that argument. This makes duplicated
-argument checking an O(1) operation for each argument. Similarly, for
-each identifier in the macro's expansion, lookup to see if it is an
-argument, and which argument it is, is also an O(1) operation. Further,
-each directive name, such as @code{endif}, has an associated directive
-enum stored in its hash node, so that directive lookup is also O(1).
-
-@node Macro Expansion
-@unnumbered Macro Expansion Algorithm
-@cindex macro expansion
-
-Macro expansion is a tricky operation, fraught with nasty corner cases
-and situations that render what you thought was a nifty way to
-optimize the preprocessor's expansion algorithm wrong in quite subtle
-ways.
-
-I strongly recommend you have a good grasp of how the C and C++
-standards require macros to be expanded before diving into this
-section, let alone the code!. If you don't have a clear mental
-picture of how things like nested macro expansion, stringizing and
-token pasting are supposed to work, damage to your sanity can quickly
-result.
-
-@section Internal representation of macros
-@cindex macro representation (internal)
-
-The preprocessor stores macro expansions in tokenized form. This
-saves repeated lexing passes during expansion, at the cost of a small
-increase in memory consumption on average. The tokens are stored
-contiguously in memory, so a pointer to the first one and a token
-count is all you need to get the replacement list of a macro.
-
-If the macro is a function-like macro the preprocessor also stores its
-parameters, in the form of an ordered list of pointers to the hash
-table entry of each parameter's identifier. Further, in the macro's
-stored expansion each occurrence of a parameter is replaced with a
-special token of type @code{CPP_MACRO_ARG}. Each such token holds the
-index of the parameter it represents in the parameter list, which
-allows rapid replacement of parameters with their arguments during
-expansion. Despite this optimization it is still necessary to store
-the original parameters to the macro, both for dumping with e.g.,
-@option{-dD}, and to warn about non-trivial macro redefinitions when
-the parameter names have changed.
-
-@section Macro expansion overview
-The preprocessor maintains a @dfn{context stack}, implemented as a
-linked list of @code{cpp_context} structures, which together represent
-the macro expansion state at any one time. The @code{struct
-cpp_reader} member variable @code{context} points to the current top
-of this stack. The top normally holds the unexpanded replacement list
-of the innermost macro under expansion, except when cpplib is about to
-pre-expand an argument, in which case it holds that argument's
-unexpanded tokens.
-
-When there are no macros under expansion, cpplib is in @dfn{base
-context}. All contexts other than the base context contain a
-contiguous list of tokens delimited by a starting and ending token.
-When not in base context, cpplib obtains the next token from the list
-of the top context. If there are no tokens left in the list, it pops
-that context off the stack, and subsequent ones if necessary, until an
-unexhausted context is found or it returns to base context. In base
-context, cpplib reads tokens directly from the lexer.
-
-If it encounters an identifier that is both a macro and enabled for
-expansion, cpplib prepares to push a new context for that macro on the
-stack by calling the routine @code{enter_macro_context}. When this
-routine returns, the new context will contain the unexpanded tokens of
-the replacement list of that macro. In the case of function-like
-macros, @code{enter_macro_context} also replaces any parameters in the
-replacement list, stored as @code{CPP_MACRO_ARG} tokens, with the
-appropriate macro argument. If the standard requires that the
-parameter be replaced with its expanded argument, the argument will
-have been fully macro expanded first.
-
-@code{enter_macro_context} also handles special macros like
-@code{__LINE__}. Although these macros expand to a single token which
-cannot contain any further macros, for reasons of token spacing
-(@pxref{Token Spacing}) and simplicity of implementation, cpplib
-handles these special macros by pushing a context containing just that
-one token.
-
-The final thing that @code{enter_macro_context} does before returning
-is to mark the macro disabled for expansion (except for special macros
-like @code{__TIME__}). The macro is re-enabled when its context is
-later popped from the context stack, as described above. This strict
-ordering ensures that a macro is disabled whilst its expansion is
-being scanned, but that it is @emph{not} disabled whilst any arguments
-to it are being expanded.
-
-@section Scanning the replacement list for macros to expand
-The C standard states that, after any parameters have been replaced
-with their possibly-expanded arguments, the replacement list is
-scanned for nested macros. Further, any identifiers in the
-replacement list that are not expanded during this scan are never
-again eligible for expansion in the future, if the reason they were
-not expanded is that the macro in question was disabled.
-
-Clearly this latter condition can only apply to tokens resulting from
-argument pre-expansion. Other tokens never have an opportunity to be
-re-tested for expansion. It is possible for identifiers that are
-function-like macros to not expand initially but to expand during a
-later scan. This occurs when the identifier is the last token of an
-argument (and therefore originally followed by a comma or a closing
-parenthesis in its macro's argument list), and when it replaces its
-parameter in the macro's replacement list, the subsequent token
-happens to be an opening parenthesis (itself possibly the first token
-of an argument).
-
-It is important to note that when cpplib reads the last token of a
-given context, that context still remains on the stack. Only when
-looking for the @emph{next} token do we pop it off the stack and drop
-to a lower context. This makes backing up by one token easy, but more
-importantly ensures that the macro corresponding to the current
-context is still disabled when we are considering the last token of
-its replacement list for expansion (or indeed expanding it). As an
-example, which illustrates many of the points above, consider
-
-@smallexample
-#define foo(x) bar x
-foo(foo) (2)
-@end smallexample
-
-@noindent which fully expands to @samp{bar foo (2)}. During pre-expansion
-of the argument, @samp{foo} does not expand even though the macro is
-enabled, since it has no following parenthesis [pre-expansion of an
-argument only uses tokens from that argument; it cannot take tokens
-from whatever follows the macro invocation]. This still leaves the
-argument token @samp{foo} eligible for future expansion. Then, when
-re-scanning after argument replacement, the token @samp{foo} is
-rejected for expansion, and marked ineligible for future expansion,
-since the macro is now disabled. It is disabled because the
-replacement list @samp{bar foo} of the macro is still on the context
-stack.
-
-If instead the algorithm looked for an opening parenthesis first and
-then tested whether the macro were disabled it would be subtly wrong.
-In the example above, the replacement list of @samp{foo} would be
-popped in the process of finding the parenthesis, re-enabling
-@samp{foo} and expanding it a second time.
-
-@section Looking for a function-like macro's opening parenthesis
-Function-like macros only expand when immediately followed by a
-parenthesis. To do this cpplib needs to temporarily disable macros
-and read the next token. Unfortunately, because of spacing issues
-(@pxref{Token Spacing}), there can be fake padding tokens in-between,
-and if the next real token is not a parenthesis cpplib needs to be
-able to back up that one token as well as retain the information in
-any intervening padding tokens.
-
-Backing up more than one token when macros are involved is not
-permitted by cpplib, because in general it might involve issues like
-restoring popped contexts onto the context stack, which are too hard.
-Instead, searching for the parenthesis is handled by a special
-function, @code{funlike_invocation_p}, which remembers padding
-information as it reads tokens. If the next real token is not an
-opening parenthesis, it backs up that one token, and then pushes an
-extra context just containing the padding information if necessary.
-
-@section Marking tokens ineligible for future expansion
-As discussed above, cpplib needs a way of marking tokens as
-unexpandable. Since the tokens cpplib handles are read-only once they
-have been lexed, it instead makes a copy of the token and adds the
-flag @code{NO_EXPAND} to the copy.
-
-For efficiency and to simplify memory management by avoiding having to
-remember to free these tokens, they are allocated as temporary tokens
-from the lexer's current token run (@pxref{Lexing a line}) using the
-function @code{_cpp_temp_token}. The tokens are then re-used once the
-current line of tokens has been read in.
-
-This might sound unsafe. However, tokens runs are not re-used at the
-end of a line if it happens to be in the middle of a macro argument
-list, and cpplib only wants to back-up more than one lexer token in
-situations where no macro expansion is involved, so the optimization
-is safe.
-
-@node Token Spacing
-@unnumbered Token Spacing
-@cindex paste avoidance
-@cindex spacing
-@cindex token spacing
-
-First, consider an issue that only concerns the stand-alone
-preprocessor: there needs to be a guarantee that re-reading its preprocessed
-output results in an identical token stream. Without taking special
-measures, this might not be the case because of macro substitution.
-For example:
-
-@smallexample
-#define PLUS +
-#define EMPTY
-#define f(x) =x=
-+PLUS -EMPTY- PLUS+ f(=)
- @expansion{} + + - - + + = = =
-@emph{not}
- @expansion{} ++ -- ++ ===
-@end smallexample
-
-One solution would be to simply insert a space between all adjacent
-tokens. However, we would like to keep space insertion to a minimum,
-both for aesthetic reasons and because it causes problems for people who
-still try to abuse the preprocessor for things like Fortran source and
-Makefiles.
-
-For now, just notice that when tokens are added (or removed, as shown by
-the @code{EMPTY} example) from the original lexed token stream, we need
-to check for accidental token pasting. We call this @dfn{paste
-avoidance}. Token addition and removal can only occur because of macro
-expansion, but accidental pasting can occur in many places: both before
-and after each macro replacement, each argument replacement, and
-additionally each token created by the @samp{#} and @samp{##} operators.
-
-Look at how the preprocessor gets whitespace output correct
-normally. The @code{cpp_token} structure contains a flags byte, and one
-of those flags is @code{PREV_WHITE}. This is flagged by the lexer, and
-indicates that the token was preceded by whitespace of some form other
-than a new line. The stand-alone preprocessor can use this flag to
-decide whether to insert a space between tokens in the output.
-
-Now consider the result of the following macro expansion:
-
-@smallexample
-#define add(x, y, z) x + y +z;
-sum = add (1,2, 3);
- @expansion{} sum = 1 + 2 +3;
-@end smallexample
-
-The interesting thing here is that the tokens @samp{1} and @samp{2} are
-output with a preceding space, and @samp{3} is output without a
-preceding space, but when lexed none of these tokens had that property.
-Careful consideration reveals that @samp{1} gets its preceding
-whitespace from the space preceding @samp{add} in the macro invocation,
-@emph{not} replacement list. @samp{2} gets its whitespace from the
-space preceding the parameter @samp{y} in the macro replacement list,
-and @samp{3} has no preceding space because parameter @samp{z} has none
-in the replacement list.
-
-Once lexed, tokens are effectively fixed and cannot be altered, since
-pointers to them might be held in many places, in particular by
-in-progress macro expansions. So instead of modifying the two tokens
-above, the preprocessor inserts a special token, which I call a
-@dfn{padding token}, into the token stream to indicate that spacing of
-the subsequent token is special. The preprocessor inserts padding
-tokens in front of every macro expansion and expanded macro argument.
-These point to a @dfn{source token} from which the subsequent real token
-should inherit its spacing. In the above example, the source tokens are
-@samp{add} in the macro invocation, and @samp{y} and @samp{z} in the
-macro replacement list, respectively.
-
-It is quite easy to get multiple padding tokens in a row, for example if
-a macro's first replacement token expands straight into another macro.
-
-@smallexample
-#define foo bar
-#define bar baz
-[foo]
- @expansion{} [baz]
-@end smallexample
-
-Here, two padding tokens are generated with sources the @samp{foo} token
-between the brackets, and the @samp{bar} token from foo's replacement
-list, respectively. Clearly the first padding token is the one to
-use, so the output code should contain a rule that the first
-padding token in a sequence is the one that matters.
-
-But what if a macro expansion is left? Adjusting the above
-example slightly:
-
-@smallexample
-#define foo bar
-#define bar EMPTY baz
-#define EMPTY
-[foo] EMPTY;
- @expansion{} [ baz] ;
-@end smallexample
-
-As shown, now there should be a space before @samp{baz} and the
-semicolon in the output.
-
-The rules we decided above fail for @samp{baz}: we generate three
-padding tokens, one per macro invocation, before the token @samp{baz}.
-We would then have it take its spacing from the first of these, which
-carries source token @samp{foo} with no leading space.
-
-It is vital that cpplib get spacing correct in these examples since any
-of these macro expansions could be stringized, where spacing matters.
-
-So, this demonstrates that not just entering macro and argument
-expansions, but leaving them requires special handling too. I made
-cpplib insert a padding token with a @code{NULL} source token when
-leaving macro expansions, as well as after each replaced argument in a
-macro's replacement list. It also inserts appropriate padding tokens on
-either side of tokens created by the @samp{#} and @samp{##} operators.
-I expanded the rule so that, if we see a padding token with a
-@code{NULL} source token, @emph{and} that source token has no leading
-space, then we behave as if we have seen no padding tokens at all. A
-quick check shows this rule will then get the above example correct as
-well.
-
-Now a relationship with paste avoidance is apparent: we have to be
-careful about paste avoidance in exactly the same locations we have
-padding tokens in order to get white space correct. This makes
-implementation of paste avoidance easy: wherever the stand-alone
-preprocessor is fixing up spacing because of padding tokens, and it
-turns out that no space is needed, it has to take the extra step to
-check that a space is not needed after all to avoid an accidental paste.
-The function @code{cpp_avoid_paste} advises whether a space is required
-between two consecutive tokens. To avoid excessive spacing, it tries
-hard to only require a space if one is likely to be necessary, but for
-reasons of efficiency it is slightly conservative and might recommend a
-space where one is not strictly needed.
-
-@node Line Numbering
-@unnumbered Line numbering
-@cindex line numbers
-
-@section Just which line number anyway?
-
-There are three reasonable requirements a cpplib client might have for
-the line number of a token passed to it:
-
-@itemize @bullet
-@item
-The source line it was lexed on.
-@item
-The line it is output on. This can be different to the line it was
-lexed on if, for example, there are intervening escaped newlines or
-C-style comments. For example:
-
-@smallexample
-foo /* @r{A long
-comment} */ bar \
-baz
-@result{}
-foo bar baz
-@end smallexample
-
-@item
-If the token results from a macro expansion, the line of the macro name,
-or possibly the line of the closing parenthesis in the case of
-function-like macro expansion.
-@end itemize
-
-The @code{cpp_token} structure contains @code{line} and @code{col}
-members. The lexer fills these in with the line and column of the first
-character of the token. Consequently, but maybe unexpectedly, a token
-from the replacement list of a macro expansion carries the location of
-the token within the @code{#define} directive, because cpplib expands a
-macro by returning pointers to the tokens in its replacement list. The
-current implementation of cpplib assigns tokens created from built-in
-macros and the @samp{#} and @samp{##} operators the location of the most
-recently lexed token. This is a because they are allocated from the
-lexer's token runs, and because of the way the diagnostic routines infer
-the appropriate location to report.
-
-The diagnostic routines in cpplib display the location of the most
-recently @emph{lexed} token, unless they are passed a specific line and
-column to report. For diagnostics regarding tokens that arise from
-macro expansions, it might also be helpful for the user to see the
-original location in the macro definition that the token came from.
-Since that is exactly the information each token carries, such an
-enhancement could be made relatively easily in future.
-
-The stand-alone preprocessor faces a similar problem when determining
-the correct line to output the token on: the position attached to a
-token is fairly useless if the token came from a macro expansion. All
-tokens on a logical line should be output on its first physical line, so
-the token's reported location is also wrong if it is part of a physical
-line other than the first.
-
-To solve these issues, cpplib provides a callback that is generated
-whenever it lexes a preprocessing token that starts a new logical line
-other than a directive. It passes this token (which may be a
-@code{CPP_EOF} token indicating the end of the translation unit) to the
-callback routine, which can then use the line and column of this token
-to produce correct output.
-
-@section Representation of line numbers
-
-As mentioned above, cpplib stores with each token the line number that
-it was lexed on. In fact, this number is not the number of the line in
-the source file, but instead bears more resemblance to the number of the
-line in the translation unit.
-
-The preprocessor maintains a monotonic increasing line count, which is
-incremented at every new line character (and also at the end of any
-buffer that does not end in a new line). Since a line number of zero is
-useful to indicate certain special states and conditions, this variable
-starts counting from one.
-
-This variable therefore uniquely enumerates each line in the translation
-unit. With some simple infrastructure, it is straight forward to map
-from this to the original source file and line number pair, saving space
-whenever line number information needs to be saved. The code the
-implements this mapping lies in the files @file{line-map.cc} and
-@file{line-map.h}.
-
-Command-line macros and assertions are implemented by pushing a buffer
-containing the right hand side of an equivalent @code{#define} or
-@code{#assert} directive. Some built-in macros are handled similarly.
-Since these are all processed before the first line of the main input
-file, it will typically have an assigned line closer to twenty than to
-one.
-
-@node Guard Macros
-@unnumbered The Multiple-Include Optimization
-@cindex guard macros
-@cindex controlling macros
-@cindex multiple-include optimization
-
-Header files are often of the form
-
-@smallexample
-#ifndef FOO
-#define FOO
-@dots{}
-#endif
-@end smallexample
-
-@noindent
-to prevent the compiler from processing them more than once. The
-preprocessor notices such header files, so that if the header file
-appears in a subsequent @code{#include} directive and @code{FOO} is
-defined, then it is ignored and it doesn't preprocess or even re-open
-the file a second time. This is referred to as the @dfn{multiple
-include optimization}.
-
-Under what circumstances is such an optimization valid? If the file
-were included a second time, it can only be optimized away if that
-inclusion would result in no tokens to return, and no relevant
-directives to process. Therefore the current implementation imposes
-requirements and makes some allowances as follows:
-
-@enumerate
-@item
-There must be no tokens outside the controlling @code{#if}-@code{#endif}
-pair, but whitespace and comments are permitted.
-
-@item
-There must be no directives outside the controlling directive pair, but
-the @dfn{null directive} (a line containing nothing other than a single
-@samp{#} and possibly whitespace) is permitted.
-
-@item
-The opening directive must be of the form
-
-@smallexample
-#ifndef FOO
-@end smallexample
-
-or
-
-@smallexample
-#if !defined FOO [equivalently, #if !defined(FOO)]
-@end smallexample
-
-@item
-In the second form above, the tokens forming the @code{#if} expression
-must have come directly from the source file---no macro expansion must
-have been involved. This is because macro definitions can change, and
-tracking whether or not a relevant change has been made is not worth the
-implementation cost.
-
-@item
-There can be no @code{#else} or @code{#elif} directives at the outer
-conditional block level, because they would probably contain something
-of interest to a subsequent pass.
-@end enumerate
-
-First, when pushing a new file on the buffer stack,
-@code{_stack_include_file} sets the controlling macro @code{mi_cmacro} to
-@code{NULL}, and sets @code{mi_valid} to @code{true}. This indicates
-that the preprocessor has not yet encountered anything that would
-invalidate the multiple-include optimization. As described in the next
-few paragraphs, these two variables having these values effectively
-indicates top-of-file.
-
-When about to return a token that is not part of a directive,
-@code{_cpp_lex_token} sets @code{mi_valid} to @code{false}. This
-enforces the constraint that tokens outside the controlling conditional
-block invalidate the optimization.
-
-The @code{do_if}, when appropriate, and @code{do_ifndef} directive
-handlers pass the controlling macro to the function
-@code{push_conditional}. cpplib maintains a stack of nested conditional
-blocks, and after processing every opening conditional this function
-pushes an @code{if_stack} structure onto the stack. In this structure
-it records the controlling macro for the block, provided there is one
-and we're at top-of-file (as described above). If an @code{#elif} or
-@code{#else} directive is encountered, the controlling macro for that
-block is cleared to @code{NULL}. Otherwise, it survives until the
-@code{#endif} closing the block, upon which @code{do_endif} sets
-@code{mi_valid} to true and stores the controlling macro in
-@code{mi_cmacro}.
-
-@code{_cpp_handle_directive} clears @code{mi_valid} when processing any
-directive other than an opening conditional and the null directive.
-With this, and requiring top-of-file to record a controlling macro, and
-no @code{#else} or @code{#elif} for it to survive and be copied to
-@code{mi_cmacro} by @code{do_endif}, we have enforced the absence of
-directives outside the main conditional block for the optimization to be
-on.
-
-Note that whilst we are inside the conditional block, @code{mi_valid} is
-likely to be reset to @code{false}, but this does not matter since
-the closing @code{#endif} restores it to @code{true} if appropriate.
-
-Finally, since @code{_cpp_lex_direct} pops the file off the buffer stack
-at @code{EOF} without returning a token, if the @code{#endif} directive
-was not followed by any tokens, @code{mi_valid} is @code{true} and
-@code{_cpp_pop_file_buffer} remembers the controlling macro associated
-with the file. Subsequent calls to @code{stack_include_file} result in
-no buffer being pushed if the controlling macro is defined, effecting
-the optimization.
-
-A quick word on how we handle the
-
-@smallexample
-#if !defined FOO
-@end smallexample
-
-@noindent
-case. @code{_cpp_parse_expr} and @code{parse_defined} take steps to see
-whether the three stages @samp{!}, @samp{defined-expression} and
-@samp{end-of-directive} occur in order in a @code{#if} expression. If
-so, they return the guard macro to @code{do_if} in the variable
-@code{mi_ind_cmacro}, and otherwise set it to @code{NULL}.
-@code{enter_macro_context} sets @code{mi_valid} to false, so if a macro
-was expanded whilst parsing any part of the expression, then the
-top-of-file test in @code{push_conditional} fails and the optimization
-is turned off.
-
-@node Files
-@unnumbered File Handling
-@cindex files
-
-Fairly obviously, the file handling code of cpplib resides in the file
-@file{files.cc}. It takes care of the details of file searching,
-opening, reading and caching, for both the main source file and all the
-headers it recursively includes.
-
-The basic strategy is to minimize the number of system calls. On many
-systems, the basic @code{open ()} and @code{fstat ()} system calls can
-be quite expensive. For every @code{#include}-d file, we need to try
-all the directories in the search path until we find a match. Some
-projects, such as glibc, pass twenty or thirty include paths on the
-command line, so this can rapidly become time consuming.
-
-For a header file we have not encountered before we have little choice
-but to do this. However, it is often the case that the same headers are
-repeatedly included, and in these cases we try to avoid repeating the
-filesystem queries whilst searching for the correct file.
-
-For each file we try to open, we store the constructed path in a splay
-tree. This path first undergoes simplification by the function
-@code{_cpp_simplify_pathname}. For example,
-@file{/usr/include/bits/../foo.h} is simplified to
-@file{/usr/include/foo.h} before we enter it in the splay tree and try
-to @code{open ()} the file. CPP will then find subsequent uses of
-@file{foo.h}, even as @file{/usr/include/foo.h}, in the splay tree and
-save system calls.
-
-Further, it is likely the file contents have also been cached, saving a
-@code{read ()} system call. We don't bother caching the contents of
-header files that are re-inclusion protected, and whose re-inclusion
-macro is defined when we leave the header file for the first time. If
-the host supports it, we try to map suitably large files into memory,
-rather than reading them in directly.
-
-The include paths are internally stored on a null-terminated
-singly-linked list, starting with the @code{"header.h"} directory search
-chain, which then links into the @code{<header.h>} directory chain.
-
-Files included with the @code{<foo.h>} syntax start the lookup directly
-in the second half of this chain. However, files included with the
-@code{"foo.h"} syntax start at the beginning of the chain, but with one
-extra directory prepended. This is the directory of the current file;
-the one containing the @code{#include} directive. Prepending this
-directory on a per-file basis is handled by the function
-@code{search_from}.
-
-Note that a header included with a directory component, such as
-@code{#include "mydir/foo.h"} and opened as
-@file{/usr/local/include/mydir/foo.h}, will have the complete path minus
-the basename @samp{foo.h} as the current directory.
-
-Enough information is stored in the splay tree that CPP can immediately
-tell whether it can skip the header file because of the multiple include
-optimization, whether the file didn't exist or couldn't be opened for
-some reason, or whether the header was flagged not to be re-used, as it
-is with the obsolete @code{#import} directive.
-
-For the benefit of MS-DOS filesystems with an 8.3 filename limitation,
-CPP offers the ability to treat various include file names as aliases
-for the real header files with shorter names. The map from one to the
-other is found in a special file called @samp{header.gcc}, stored in the
-command line (or system) include directories to which the mapping
-applies. This may be higher up the directory tree than the full path to
-the file minus the base name.
-
-@node Concept Index
-@unnumbered Concept Index
-@printindex cp
-
-@bye
+++ /dev/null
-@c Copyright (C) 1999-2022 Free Software Foundation, Inc.
-@c This is part of the CPP and GCC manuals.
-@c For copying conditions, see the file gcc.texi.
-
-@c ---------------------------------------------------------------------
-@c Options affecting the preprocessor
-@c ---------------------------------------------------------------------
-
-@c If this file is included with the flag ``cppmanual'' set, it is
-@c formatted for inclusion in the CPP manual; otherwise the main GCC manual.
-
-@item -D @var{name}
-@opindex D
-Predefine @var{name} as a macro, with definition @code{1}.
-
-@item -D @var{name}=@var{definition}
-The contents of @var{definition} are tokenized and processed as if
-they appeared during translation phase three in a @samp{#define}
-directive. In particular, the definition is truncated by
-embedded newline characters.
-
-If you are invoking the preprocessor from a shell or shell-like
-program you may need to use the shell's quoting syntax to protect
-characters such as spaces that have a meaning in the shell syntax.
-
-If you wish to define a function-like macro on the command line, write
-its argument list with surrounding parentheses before the equals sign
-(if any). Parentheses are meaningful to most shells, so you should
-quote the option. With @command{sh} and @command{csh},
-@option{-D'@var{name}(@var{args@dots{}})=@var{definition}'} works.
-
-@option{-D} and @option{-U} options are processed in the order they
-are given on the command line. All @option{-imacros @var{file}} and
-@option{-include @var{file}} options are processed after all
-@option{-D} and @option{-U} options.
-
-@item -U @var{name}
-@opindex U
-Cancel any previous definition of @var{name}, either built in or
-provided with a @option{-D} option.
-
-@item -include @var{file}
-@opindex include
-Process @var{file} as if @code{#include "file"} appeared as the first
-line of the primary source file. However, the first directory searched
-for @var{file} is the preprocessor's working directory @emph{instead of}
-the directory containing the main source file. If not found there, it
-is searched for in the remainder of the @code{#include "@dots{}"} search
-chain as normal.
-
-If multiple @option{-include} options are given, the files are included
-in the order they appear on the command line.
-
-@item -imacros @var{file}
-@opindex imacros
-Exactly like @option{-include}, except that any output produced by
-scanning @var{file} is thrown away. Macros it defines remain defined.
-This allows you to acquire all the macros from a header without also
-processing its declarations.
-
-All files specified by @option{-imacros} are processed before all files
-specified by @option{-include}.
-
-@item -undef
-@opindex undef
-Do not predefine any system-specific or GCC-specific macros. The
-standard predefined macros remain defined.
-@ifset cppmanual
-@xref{Standard Predefined Macros}.
-@end ifset
-
-@item -pthread
-@opindex pthread
-Define additional macros required for using the POSIX threads library.
-You should use this option consistently for both compilation and linking.
-This option is supported on GNU/Linux targets, most other Unix derivatives,
-and also on x86 Cygwin and MinGW targets.
-
-@item -M
-@opindex M
-@cindex @command{make}
-@cindex dependencies, @command{make}
-Instead of outputting the result of preprocessing, output a rule
-suitable for @command{make} describing the dependencies of the main
-source file. The preprocessor outputs one @command{make} rule containing
-the object file name for that source file, a colon, and the names of all
-the included files, including those coming from @option{-include} or
-@option{-imacros} command-line options.
-
-Unless specified explicitly (with @option{-MT} or @option{-MQ}), the
-object file name consists of the name of the source file with any
-suffix replaced with object file suffix and with any leading directory
-parts removed. If there are many included files then the rule is
-split into several lines using @samp{\}-newline. The rule has no
-commands.
-
-This option does not suppress the preprocessor's debug output, such as
-@option{-dM}. To avoid mixing such debug output with the dependency
-rules you should explicitly specify the dependency output file with
-@option{-MF}, or use an environment variable like
-@env{DEPENDENCIES_OUTPUT} (@pxref{Environment Variables}). Debug output
-is still sent to the regular output stream as normal.
-
-Passing @option{-M} to the driver implies @option{-E}, and suppresses
-warnings with an implicit @option{-w}.
-
-@item -MM
-@opindex MM
-Like @option{-M} but do not mention header files that are found in
-system header directories, nor header files that are included,
-directly or indirectly, from such a header.
-
-This implies that the choice of angle brackets or double quotes in an
-@samp{#include} directive does not in itself determine whether that
-header appears in @option{-MM} dependency output.
-
-@anchor{dashMF}
-@item -MF @var{file}
-@opindex MF
-When used with @option{-M} or @option{-MM}, specifies a
-file to write the dependencies to. If no @option{-MF} switch is given
-the preprocessor sends the rules to the same place it would send
-preprocessed output.
-
-When used with the driver options @option{-MD} or @option{-MMD},
-@option{-MF} overrides the default dependency output file.
-
-If @var{file} is @file{-}, then the dependencies are written to @file{stdout}.
-
-@item -MG
-@opindex MG
-In conjunction with an option such as @option{-M} requesting
-dependency generation, @option{-MG} assumes missing header files are
-generated files and adds them to the dependency list without raising
-an error. The dependency filename is taken directly from the
-@code{#include} directive without prepending any path. @option{-MG}
-also suppresses preprocessed output, as a missing header file renders
-this useless.
-
-This feature is used in automatic updating of makefiles.
-
-@item -Mno-modules
-@opindex Mno-modules
-Disable dependency generation for compiled module interfaces.
-
-@item -MP
-@opindex MP
-This option instructs CPP to add a phony target for each dependency
-other than the main file, causing each to depend on nothing. These
-dummy rules work around errors @command{make} gives if you remove header
-files without updating the @file{Makefile} to match.
-
-This is typical output:
-
-@smallexample
-test.o: test.c test.h
-
-test.h:
-@end smallexample
-
-@item -MT @var{target}
-@opindex MT
-
-Change the target of the rule emitted by dependency generation. By
-default CPP takes the name of the main input file, deletes any
-directory components and any file suffix such as @samp{.c}, and
-appends the platform's usual object suffix. The result is the target.
-
-An @option{-MT} option sets the target to be exactly the string you
-specify. If you want multiple targets, you can specify them as a single
-argument to @option{-MT}, or use multiple @option{-MT} options.
-
-For example, @option{@w{-MT '$(objpfx)foo.o'}} might give
-
-@smallexample
-$(objpfx)foo.o: foo.c
-@end smallexample
-
-@item -MQ @var{target}
-@opindex MQ
-
-Same as @option{-MT}, but it quotes any characters which are special to
-Make. @option{@w{-MQ '$(objpfx)foo.o'}} gives
-
-@smallexample
-$$(objpfx)foo.o: foo.c
-@end smallexample
-
-The default target is automatically quoted, as if it were given with
-@option{-MQ}.
-
-@item -MD
-@opindex MD
-@option{-MD} is equivalent to @option{-M -MF @var{file}}, except that
-@option{-E} is not implied. The driver determines @var{file} based on
-whether an @option{-o} option is given. If it is, the driver uses its
-argument but with a suffix of @file{.d}, otherwise it takes the name
-of the input file, removes any directory components and suffix, and
-applies a @file{.d} suffix.
-
-If @option{-MD} is used in conjunction with @option{-E}, any
-@option{-o} switch is understood to specify the dependency output file
-(@pxref{dashMF,,-MF}), but if used without @option{-E}, each @option{-o}
-is understood to specify a target object file.
-
-Since @option{-E} is not implied, @option{-MD} can be used to generate
-a dependency output file as a side effect of the compilation process.
-
-@item -MMD
-@opindex MMD
-Like @option{-MD} except mention only user header files, not system
-header files.
-
-@item -fpreprocessed
-@opindex fpreprocessed
-Indicate to the preprocessor that the input file has already been
-preprocessed. This suppresses things like macro expansion, trigraph
-conversion, escaped newline splicing, and processing of most directives.
-The preprocessor still recognizes and removes comments, so that you can
-pass a file preprocessed with @option{-C} to the compiler without
-problems. In this mode the integrated preprocessor is little more than
-a tokenizer for the front ends.
-
-@option{-fpreprocessed} is implicit if the input file has one of the
-extensions @samp{.i}, @samp{.ii} or @samp{.mi}. These are the
-extensions that GCC uses for preprocessed files created by
-@option{-save-temps}.
-
-@item -fdirectives-only
-@opindex fdirectives-only
-When preprocessing, handle directives, but do not expand macros.
-
-The option's behavior depends on the @option{-E} and @option{-fpreprocessed}
-options.
-
-With @option{-E}, preprocessing is limited to the handling of directives
-such as @code{#define}, @code{#ifdef}, and @code{#error}. Other
-preprocessor operations, such as macro expansion and trigraph
-conversion are not performed. In addition, the @option{-dD} option is
-implicitly enabled.
-
-With @option{-fpreprocessed}, predefinition of command line and most
-builtin macros is disabled. Macros such as @code{__LINE__}, which are
-contextually dependent, are handled normally. This enables compilation of
-files previously preprocessed with @code{-E -fdirectives-only}.
-
-With both @option{-E} and @option{-fpreprocessed}, the rules for
-@option{-fpreprocessed} take precedence. This enables full preprocessing of
-files previously preprocessed with @code{-E -fdirectives-only}.
-
-@item -fdollars-in-identifiers
-@opindex fdollars-in-identifiers
-@anchor{fdollars-in-identifiers}
-Accept @samp{$} in identifiers.
-@ifset cppmanual
-@xref{Identifier characters}.
-@end ifset
-
-@item -fextended-identifiers
-@opindex fextended-identifiers
-Accept universal character names and extended characters in
-identifiers. This option is enabled by default for C99 (and later C
-standard versions) and C++.
-
-@item -fno-canonical-system-headers
-@opindex fno-canonical-system-headers
-When preprocessing, do not shorten system header paths with canonicalization.
-
-@item -fmax-include-depth=@var{depth}
-@opindex fmax-include-depth
-Set the maximum depth of the nested #include. The default is 200.
-
-@item -ftabstop=@var{width}
-@opindex ftabstop
-Set the distance between tab stops. This helps the preprocessor report
-correct column numbers in warnings or errors, even if tabs appear on the
-line. If the value is less than 1 or greater than 100, the option is
-ignored. The default is 8.
-
-@item -ftrack-macro-expansion@r{[}=@var{level}@r{]}
-@opindex ftrack-macro-expansion
-Track locations of tokens across macro expansions. This allows the
-compiler to emit diagnostic about the current macro expansion stack
-when a compilation error occurs in a macro expansion. Using this
-option makes the preprocessor and the compiler consume more
-memory. The @var{level} parameter can be used to choose the level of
-precision of token location tracking thus decreasing the memory
-consumption if necessary. Value @samp{0} of @var{level} de-activates
-this option. Value @samp{1} tracks tokens locations in a
-degraded mode for the sake of minimal memory overhead. In this mode
-all tokens resulting from the expansion of an argument of a
-function-like macro have the same location. Value @samp{2} tracks
-tokens locations completely. This value is the most memory hungry.
-When this option is given no argument, the default parameter value is
-@samp{2}.
-
-Note that @code{-ftrack-macro-expansion=2} is activated by default.
-
-@item -fmacro-prefix-map=@var{old}=@var{new}
-@opindex fmacro-prefix-map
-When preprocessing files residing in directory @file{@var{old}},
-expand the @code{__FILE__} and @code{__BASE_FILE__} macros as if the
-files resided in directory @file{@var{new}} instead. This can be used
-to change an absolute path to a relative path by using @file{.} for
-@var{new} which can result in more reproducible builds that are
-location independent. This option also affects
-@code{__builtin_FILE()} during compilation. See also
-@option{-ffile-prefix-map}.
-
-@item -fexec-charset=@var{charset}
-@opindex fexec-charset
-@cindex character set, execution
-Set the execution character set, used for string and character
-constants. The default is UTF-8. @var{charset} can be any encoding
-supported by the system's @code{iconv} library routine.
-
-@item -fwide-exec-charset=@var{charset}
-@opindex fwide-exec-charset
-@cindex character set, wide execution
-Set the wide execution character set, used for wide string and
-character constants. The default is one of UTF-32BE, UTF-32LE, UTF-16BE,
-or UTF-16LE, whichever corresponds to the width of @code{wchar_t} and the
-big-endian or little-endian byte order being used for code generation. As
-with @option{-fexec-charset}, @var{charset} can be any encoding supported
-by the system's @code{iconv} library routine; however, you will have
-problems with encodings that do not fit exactly in @code{wchar_t}.
-
-@item -finput-charset=@var{charset}
-@opindex finput-charset
-@cindex character set, input
-Set the input character set, used for translation from the character
-set of the input file to the source character set used by GCC@. If the
-locale does not specify, or GCC cannot get this information from the
-locale, the default is UTF-8. This can be overridden by either the locale
-or this command-line option. Currently the command-line option takes
-precedence if there's a conflict. @var{charset} can be any encoding
-supported by the system's @code{iconv} library routine.
-
-@ifclear cppmanual
-@item -fpch-deps
-@opindex fpch-deps
-When using precompiled headers (@pxref{Precompiled Headers}), this flag
-causes the dependency-output flags to also list the files from the
-precompiled header's dependencies. If not specified, only the
-precompiled header are listed and not the files that were used to
-create it, because those files are not consulted when a precompiled
-header is used.
-
-@item -fpch-preprocess
-@opindex fpch-preprocess
-This option allows use of a precompiled header (@pxref{Precompiled
-Headers}) together with @option{-E}. It inserts a special @code{#pragma},
-@code{#pragma GCC pch_preprocess "@var{filename}"} in the output to mark
-the place where the precompiled header was found, and its @var{filename}.
-When @option{-fpreprocessed} is in use, GCC recognizes this @code{#pragma}
-and loads the PCH@.
-
-This option is off by default, because the resulting preprocessed output
-is only really suitable as input to GCC@. It is switched on by
-@option{-save-temps}.
-
-You should not write this @code{#pragma} in your own code, but it is
-safe to edit the filename if the PCH file is available in a different
-location. The filename may be absolute or it may be relative to GCC's
-current directory.
-@end ifclear
-
-@item -fworking-directory
-@opindex fworking-directory
-@opindex fno-working-directory
-Enable generation of linemarkers in the preprocessor output that
-let the compiler know the current working directory at the time of
-preprocessing. When this option is enabled, the preprocessor
-emits, after the initial linemarker, a second linemarker with the
-current working directory followed by two slashes. GCC uses this
-directory, when it's present in the preprocessed input, as the
-directory emitted as the current working directory in some debugging
-information formats. This option is implicitly enabled if debugging
-information is enabled, but this can be inhibited with the negated
-form @option{-fno-working-directory}. If the @option{-P} flag is
-present in the command line, this option has no effect, since no
-@code{#line} directives are emitted whatsoever.
-
-@item -A @var{predicate}=@var{answer}
-@opindex A
-Make an assertion with the predicate @var{predicate} and answer
-@var{answer}. This form is preferred to the older form @option{-A
-@var{predicate}(@var{answer})}, which is still supported, because
-it does not use shell special characters.
-@ifset cppmanual
-@xref{Obsolete Features}.
-@end ifset
-
-@item -A -@var{predicate}=@var{answer}
-Cancel an assertion with the predicate @var{predicate} and answer
-@var{answer}.
-
-@item -C
-@opindex C
-Do not discard comments. All comments are passed through to the output
-file, except for comments in processed directives, which are deleted
-along with the directive.
-
-You should be prepared for side effects when using @option{-C}; it
-causes the preprocessor to treat comments as tokens in their own right.
-For example, comments appearing at the start of what would be a
-directive line have the effect of turning that line into an ordinary
-source line, since the first token on the line is no longer a @samp{#}.
-
-@item -CC
-@opindex CC
-Do not discard comments, including during macro expansion. This is
-like @option{-C}, except that comments contained within macros are
-also passed through to the output file where the macro is expanded.
-
-In addition to the side effects of the @option{-C} option, the
-@option{-CC} option causes all C++-style comments inside a macro
-to be converted to C-style comments. This is to prevent later use
-of that macro from inadvertently commenting out the remainder of
-the source line.
-
-The @option{-CC} option is generally used to support lint comments.
-
-@item -P
-@opindex P
-Inhibit generation of linemarkers in the output from the preprocessor.
-This might be useful when running the preprocessor on something that is
-not C code, and will be sent to a program which might be confused by the
-linemarkers.
-@ifset cppmanual
-@xref{Preprocessor Output}.
-@end ifset
-
-@cindex traditional C language
-@cindex C language, traditional
-@item -traditional
-@itemx -traditional-cpp
-@opindex traditional-cpp
-@opindex traditional
-
-Try to imitate the behavior of pre-standard C preprocessors, as
-opposed to ISO C preprocessors.
-@ifset cppmanual
-@xref{Traditional Mode}.
-@end ifset
-@ifclear cppmanual
-See the GNU CPP manual for details.
-@end ifclear
-
-Note that GCC does not otherwise attempt to emulate a pre-standard
-C compiler, and these options are only supported with the @option{-E}
-switch, or when invoking CPP explicitly.
-
-@item -trigraphs
-@opindex trigraphs
-Support ISO C trigraphs.
-These are three-character sequences, all starting with @samp{??}, that
-are defined by ISO C to stand for single characters. For example,
-@samp{??/} stands for @samp{\}, so @samp{'??/n'} is a character
-constant for a newline.
-@ifset cppmanual
-@xref{Initial processing}.
-@end ifset
-
-@ifclear cppmanual
-The nine trigraphs and their replacements are
-
-@smallexample
-Trigraph: ??( ??) ??< ??> ??= ??/ ??' ??! ??-
-Replacement: [ ] @{ @} # \ ^ | ~
-@end smallexample
-@end ifclear
-
-By default, GCC ignores trigraphs, but in
-standard-conforming modes it converts them. See the @option{-std} and
-@option{-ansi} options.
-
-@item -remap
-@opindex remap
-Enable special code to work around file systems which only permit very
-short file names, such as MS-DOS@.
-
-@item -H
-@opindex H
-Print the name of each header file used, in addition to other normal
-activities. Each name is indented to show how deep in the
-@samp{#include} stack it is. Precompiled header files are also
-printed, even if they are found to be invalid; an invalid precompiled
-header file is printed with @samp{...x} and a valid one with @samp{...!} .
-
-@item -d@var{letters}
-@opindex d
-Says to make debugging dumps during compilation as specified by
-@var{letters}. The flags documented here are those relevant to the
-preprocessor. Other @var{letters} are interpreted
-by the compiler proper, or reserved for future versions of GCC, and so
-are silently ignored. If you specify @var{letters} whose behavior
-conflicts, the result is undefined.
-@ifclear cppmanual
-@xref{Developer Options}, for more information.
-@end ifclear
-
-@table @gcctabopt
-@item -dM
-@opindex dM
-Instead of the normal output, generate a list of @samp{#define}
-directives for all the macros defined during the execution of the
-preprocessor, including predefined macros. This gives you a way of
-finding out what is predefined in your version of the preprocessor.
-Assuming you have no file @file{foo.h}, the command
-
-@smallexample
-touch foo.h; cpp -dM foo.h
-@end smallexample
-
-@noindent
-shows all the predefined macros.
-
-@ifclear cppmanual
-If you use @option{-dM} without the @option{-E} option, @option{-dM} is
-interpreted as a synonym for @option{-fdump-rtl-mach}.
-@xref{Developer Options, , ,gcc}.
-@end ifclear
-
-@item -dD
-@opindex dD
-Like @option{-dM} except in two respects: it does @emph{not} include the
-predefined macros, and it outputs @emph{both} the @samp{#define}
-directives and the result of preprocessing. Both kinds of output go to
-the standard output file.
-
-@item -dN
-@opindex dN
-Like @option{-dD}, but emit only the macro names, not their expansions.
-
-@item -dI
-@opindex dI
-Output @samp{#include} directives in addition to the result of
-preprocessing.
-
-@item -dU
-@opindex dU
-Like @option{-dD} except that only macros that are expanded, or whose
-definedness is tested in preprocessor directives, are output; the
-output is delayed until the use or test of the macro; and
-@samp{#undef} directives are also output for macros tested but
-undefined at the time.
-@end table
-
-@item -fdebug-cpp
-@opindex fdebug-cpp
-This option is only useful for debugging GCC. When used from CPP or with
-@option{-E}, it dumps debugging information about location maps. Every
-token in the output is preceded by the dump of the map its location
-belongs to.
-
-When used from GCC without @option{-E}, this option has no effect.
+++ /dev/null
-@c Copyright (C) 1999-2022 Free Software Foundation, Inc.
-@c This is part of the CPP and GCC manuals.
-@c For copying conditions, see the file gcc.texi.
-
-@c ---------------------------------------------------------------------
-@c Options affecting preprocessor warnings
-@c ---------------------------------------------------------------------
-
-@c If this file is included with the flag ``cppmanual'' set, it is
-@c formatted for inclusion in the CPP manual; otherwise the main GCC manual.
-
-@item -Wcomment
-@itemx -Wcomments
-@opindex Wcomment
-@opindex Wcomments
-Warn whenever a comment-start sequence @samp{/*} appears in a @samp{/*}
-comment, or whenever a backslash-newline appears in a @samp{//} comment.
-This warning is enabled by @option{-Wall}.
-
-@item -Wtrigraphs
-@opindex Wtrigraphs
-@anchor{Wtrigraphs}
-Warn if any trigraphs are encountered that might change the meaning of
-the program. Trigraphs within comments are not warned about,
-except those that would form escaped newlines.
-
-This option is implied by @option{-Wall}. If @option{-Wall} is not
-given, this option is still enabled unless trigraphs are enabled. To
-get trigraph conversion without warnings, but get the other
-@option{-Wall} warnings, use @samp{-trigraphs -Wall -Wno-trigraphs}.
-
-@item -Wundef
-@opindex Wundef
-@opindex Wno-undef
-Warn if an undefined identifier is evaluated in an @code{#if} directive.
-Such identifiers are replaced with zero.
-
-@item -Wexpansion-to-defined
-@opindex Wexpansion-to-defined
-Warn whenever @samp{defined} is encountered in the expansion of a macro
-(including the case where the macro is expanded by an @samp{#if} directive).
-Such usage is not portable.
-This warning is also enabled by @option{-Wpedantic} and @option{-Wextra}.
-
-@item -Wunused-macros
-@opindex Wunused-macros
-Warn about macros defined in the main file that are unused. A macro
-is @dfn{used} if it is expanded or tested for existence at least once.
-The preprocessor also warns if the macro has not been used at the
-time it is redefined or undefined.
-
-Built-in macros, macros defined on the command line, and macros
-defined in include files are not warned about.
-
-@emph{Note:} If a macro is actually used, but only used in skipped
-conditional blocks, then the preprocessor reports it as unused. To avoid the
-warning in such a case, you might improve the scope of the macro's
-definition by, for example, moving it into the first skipped block.
-Alternatively, you could provide a dummy use with something like:
-
-@smallexample
-#if defined the_macro_causing_the_warning
-#endif
-@end smallexample
-
-@item -Wno-endif-labels
-@opindex Wno-endif-labels
-@opindex Wendif-labels
-Do not warn whenever an @code{#else} or an @code{#endif} are followed by text.
-This sometimes happens in older programs with code of the form
-
-@smallexample
-#if FOO
-@dots{}
-#else FOO
-@dots{}
-#endif FOO
-@end smallexample
-
-@noindent
-The second and third @code{FOO} should be in comments.
-This warning is on by default.
+++ /dev/null
-c Copyright (C) 1988-2022 Free Software Foundation, Inc.
-
-@c This is part of the GCC manual.
-@c For copying conditions, see the file gcc.texi.
-
-@node C Extensions
-@chapter Extensions to the C Language Family
-@cindex extensions, C language
-@cindex C language extensions
-
-@opindex pedantic
-GNU C provides several language features not found in ISO standard C@.
-(The @option{-pedantic} option directs GCC to print a warning message if
-any of these features is used.) To test for the availability of these
-features in conditional compilation, check for a predefined macro
-@code{__GNUC__}, which is always defined under GCC@.
-
-These extensions are available in C and Objective-C@. Most of them are
-also available in C++. @xref{C++ Extensions,,Extensions to the
-C++ Language}, for extensions that apply @emph{only} to C++.
-
-Some features that are in ISO C99 but not C90 or C++ are also, as
-extensions, accepted by GCC in C90 mode and in C++.
-
-@menu
-* Statement Exprs:: Putting statements and declarations inside expressions.
-* Local Labels:: Labels local to a block.
-* Labels as Values:: Getting pointers to labels, and computed gotos.
-* Nested Functions:: Nested function in GNU C.
-* Nonlocal Gotos:: Nonlocal gotos.
-* Constructing Calls:: Dispatching a call to another function.
-* Typeof:: @code{typeof}: referring to the type of an expression.
-* Conditionals:: Omitting the middle operand of a @samp{?:} expression.
-* __int128:: 128-bit integers---@code{__int128}.
-* Long Long:: Double-word integers---@code{long long int}.
-* Complex:: Data types for complex numbers.
-* Floating Types:: Additional Floating Types.
-* Half-Precision:: Half-Precision Floating Point.
-* Decimal Float:: Decimal Floating Types.
-* Hex Floats:: Hexadecimal floating-point constants.
-* Fixed-Point:: Fixed-Point Types.
-* Named Address Spaces::Named address spaces.
-* Zero Length:: Zero-length arrays.
-* Empty Structures:: Structures with no members.
-* Variable Length:: Arrays whose length is computed at run time.
-* Variadic Macros:: Macros with a variable number of arguments.
-* Escaped Newlines:: Slightly looser rules for escaped newlines.
-* Subscripting:: Any array can be subscripted, even if not an lvalue.
-* Pointer Arith:: Arithmetic on @code{void}-pointers and function pointers.
-* Variadic Pointer Args:: Pointer arguments to variadic functions.
-* Pointers to Arrays:: Pointers to arrays with qualifiers work as expected.
-* Initializers:: Non-constant initializers.
-* Compound Literals:: Compound literals give structures, unions
- or arrays as values.
-* Designated Inits:: Labeling elements of initializers.
-* Case Ranges:: `case 1 ... 9' and such.
-* Cast to Union:: Casting to union type from any member of the union.
-* Mixed Labels and Declarations:: Mixing declarations, labels and code.
-* Function Attributes:: Declaring that functions have no side effects,
- or that they can never return.
-* Variable Attributes:: Specifying attributes of variables.
-* Type Attributes:: Specifying attributes of types.
-* Label Attributes:: Specifying attributes on labels.
-* Enumerator Attributes:: Specifying attributes on enumerators.
-* Statement Attributes:: Specifying attributes on statements.
-* Attribute Syntax:: Formal syntax for attributes.
-* Function Prototypes:: Prototype declarations and old-style definitions.
-* C++ Comments:: C++ comments are recognized.
-* Dollar Signs:: Dollar sign is allowed in identifiers.
-* Character Escapes:: @samp{\e} stands for the character @key{ESC}.
-* Alignment:: Determining the alignment of a function, type or variable.
-* Inline:: Defining inline functions (as fast as macros).
-* Volatiles:: What constitutes an access to a volatile object.
-* Using Assembly Language with C:: Instructions and extensions for interfacing C with assembler.
-* Alternate Keywords:: @code{__const__}, @code{__asm__}, etc., for header files.
-* Incomplete Enums:: @code{enum foo;}, with details to follow.
-* Function Names:: Printable strings which are the name of the current
- function.
-* Return Address:: Getting the return or frame address of a function.
-* Vector Extensions:: Using vector instructions through built-in functions.
-* Offsetof:: Special syntax for implementing @code{offsetof}.
-* __sync Builtins:: Legacy built-in functions for atomic memory access.
-* __atomic Builtins:: Atomic built-in functions with memory model.
-* Integer Overflow Builtins:: Built-in functions to perform arithmetics and
- arithmetic overflow checking.
-* x86 specific memory model extensions for transactional memory:: x86 memory models.
-* Object Size Checking:: Built-in functions for limited buffer overflow
- checking.
-* Other Builtins:: Other built-in functions.
-* Target Builtins:: Built-in functions specific to particular targets.
-* Target Format Checks:: Format checks specific to particular targets.
-* Pragmas:: Pragmas accepted by GCC.
-* Unnamed Fields:: Unnamed struct/union fields within structs/unions.
-* Thread-Local:: Per-thread variables.
-* Binary constants:: Binary constants using the @samp{0b} prefix.
-@end menu
-
-@node Statement Exprs
-@section Statements and Declarations in Expressions
-@cindex statements inside expressions
-@cindex declarations inside expressions
-@cindex expressions containing statements
-@cindex macros, statements in expressions
-
-@c the above section title wrapped and causes an underfull hbox.. i
-@c changed it from "within" to "in". --mew 4feb93
-A compound statement enclosed in parentheses may appear as an expression
-in GNU C@. This allows you to use loops, switches, and local variables
-within an expression.
-
-Recall that a compound statement is a sequence of statements surrounded
-by braces; in this construct, parentheses go around the braces. For
-example:
-
-@smallexample
-(@{ int y = foo (); int z;
- if (y > 0) z = y;
- else z = - y;
- z; @})
-@end smallexample
-
-@noindent
-is a valid (though slightly more complex than necessary) expression
-for the absolute value of @code{foo ()}.
-
-The last thing in the compound statement should be an expression
-followed by a semicolon; the value of this subexpression serves as the
-value of the entire construct. (If you use some other kind of statement
-last within the braces, the construct has type @code{void}, and thus
-effectively no value.)
-
-This feature is especially useful in making macro definitions ``safe'' (so
-that they evaluate each operand exactly once). For example, the
-``maximum'' function is commonly defined as a macro in standard C as
-follows:
-
-@smallexample
-#define max(a,b) ((a) > (b) ? (a) : (b))
-@end smallexample
-
-@noindent
-@cindex side effects, macro argument
-But this definition computes either @var{a} or @var{b} twice, with bad
-results if the operand has side effects. In GNU C, if you know the
-type of the operands (here taken as @code{int}), you can avoid this
-problem by defining the macro as follows:
-
-@smallexample
-#define maxint(a,b) \
- (@{int _a = (a), _b = (b); _a > _b ? _a : _b; @})
-@end smallexample
-
-Note that introducing variable declarations (as we do in @code{maxint}) can
-cause variable shadowing, so while this example using the @code{max} macro
-produces correct results:
-@smallexample
-int _a = 1, _b = 2, c;
-c = max (_a, _b);
-@end smallexample
-@noindent
-this example using maxint will not:
-@smallexample
-int _a = 1, _b = 2, c;
-c = maxint (_a, _b);
-@end smallexample
-
-This problem may for instance occur when we use this pattern recursively, like
-so:
-
-@smallexample
-#define maxint3(a, b, c) \
- (@{int _a = (a), _b = (b), _c = (c); maxint (maxint (_a, _b), _c); @})
-@end smallexample
-
-Embedded statements are not allowed in constant expressions, such as
-the value of an enumeration constant, the width of a bit-field, or
-the initial value of a static variable.
-
-If you don't know the type of the operand, you can still do this, but you
-must use @code{typeof} or @code{__auto_type} (@pxref{Typeof}).
-
-In G++, the result value of a statement expression undergoes array and
-function pointer decay, and is returned by value to the enclosing
-expression. For instance, if @code{A} is a class, then
-
-@smallexample
- A a;
-
- (@{a;@}).Foo ()
-@end smallexample
-
-@noindent
-constructs a temporary @code{A} object to hold the result of the
-statement expression, and that is used to invoke @code{Foo}.
-Therefore the @code{this} pointer observed by @code{Foo} is not the
-address of @code{a}.
-
-In a statement expression, any temporaries created within a statement
-are destroyed at that statement's end. This makes statement
-expressions inside macros slightly different from function calls. In
-the latter case temporaries introduced during argument evaluation are
-destroyed at the end of the statement that includes the function
-call. In the statement expression case they are destroyed during
-the statement expression. For instance,
-
-@smallexample
-#define macro(a) (@{__typeof__(a) b = (a); b + 3; @})
-template<typename T> T function(T a) @{ T b = a; return b + 3; @}
-
-void foo ()
-@{
- macro (X ());
- function (X ());
-@}
-@end smallexample
-
-@noindent
-has different places where temporaries are destroyed. For the
-@code{macro} case, the temporary @code{X} is destroyed just after
-the initialization of @code{b}. In the @code{function} case that
-temporary is destroyed when the function returns.
-
-These considerations mean that it is probably a bad idea to use
-statement expressions of this form in header files that are designed to
-work with C++. (Note that some versions of the GNU C Library contained
-header files using statement expressions that lead to precisely this
-bug.)
-
-Jumping into a statement expression with @code{goto} or using a
-@code{switch} statement outside the statement expression with a
-@code{case} or @code{default} label inside the statement expression is
-not permitted. Jumping into a statement expression with a computed
-@code{goto} (@pxref{Labels as Values}) has undefined behavior.
-Jumping out of a statement expression is permitted, but if the
-statement expression is part of a larger expression then it is
-unspecified which other subexpressions of that expression have been
-evaluated except where the language definition requires certain
-subexpressions to be evaluated before or after the statement
-expression. A @code{break} or @code{continue} statement inside of
-a statement expression used in @code{while}, @code{do} or @code{for}
-loop or @code{switch} statement condition
-or @code{for} statement init or increment expressions jumps to an
-outer loop or @code{switch} statement if any (otherwise it is an error),
-rather than to the loop or @code{switch} statement in whose condition
-or init or increment expression it appears.
-In any case, as with a function call, the evaluation of a
-statement expression is not interleaved with the evaluation of other
-parts of the containing expression. For example,
-
-@smallexample
- foo (), ((@{ bar1 (); goto a; 0; @}) + bar2 ()), baz();
-@end smallexample
-
-@noindent
-calls @code{foo} and @code{bar1} and does not call @code{baz} but
-may or may not call @code{bar2}. If @code{bar2} is called, it is
-called after @code{foo} and before @code{bar1}.
-
-@node Local Labels
-@section Locally Declared Labels
-@cindex local labels
-@cindex macros, local labels
-
-GCC allows you to declare @dfn{local labels} in any nested block
-scope. A local label is just like an ordinary label, but you can
-only reference it (with a @code{goto} statement, or by taking its
-address) within the block in which it is declared.
-
-A local label declaration looks like this:
-
-@smallexample
-__label__ @var{label};
-@end smallexample
-
-@noindent
-or
-
-@smallexample
-__label__ @var{label1}, @var{label2}, /* @r{@dots{}} */;
-@end smallexample
-
-Local label declarations must come at the beginning of the block,
-before any ordinary declarations or statements.
-
-The label declaration defines the label @emph{name}, but does not define
-the label itself. You must do this in the usual way, with
-@code{@var{label}:}, within the statements of the statement expression.
-
-The local label feature is useful for complex macros. If a macro
-contains nested loops, a @code{goto} can be useful for breaking out of
-them. However, an ordinary label whose scope is the whole function
-cannot be used: if the macro can be expanded several times in one
-function, the label is multiply defined in that function. A
-local label avoids this problem. For example:
-
-@smallexample
-#define SEARCH(value, array, target) \
-do @{ \
- __label__ found; \
- typeof (target) _SEARCH_target = (target); \
- typeof (*(array)) *_SEARCH_array = (array); \
- int i, j; \
- int value; \
- for (i = 0; i < max; i++) \
- for (j = 0; j < max; j++) \
- if (_SEARCH_array[i][j] == _SEARCH_target) \
- @{ (value) = i; goto found; @} \
- (value) = -1; \
- found:; \
-@} while (0)
-@end smallexample
-
-This could also be written using a statement expression:
-
-@smallexample
-#define SEARCH(array, target) \
-(@{ \
- __label__ found; \
- typeof (target) _SEARCH_target = (target); \
- typeof (*(array)) *_SEARCH_array = (array); \
- int i, j; \
- int value; \
- for (i = 0; i < max; i++) \
- for (j = 0; j < max; j++) \
- if (_SEARCH_array[i][j] == _SEARCH_target) \
- @{ value = i; goto found; @} \
- value = -1; \
- found: \
- value; \
-@})
-@end smallexample
-
-Local label declarations also make the labels they declare visible to
-nested functions, if there are any. @xref{Nested Functions}, for details.
-
-@node Labels as Values
-@section Labels as Values
-@cindex labels as values
-@cindex computed gotos
-@cindex goto with computed label
-@cindex address of a label
-
-You can get the address of a label defined in the current function
-(or a containing function) with the unary operator @samp{&&}. The
-value has type @code{void *}. This value is a constant and can be used
-wherever a constant of that type is valid. For example:
-
-@smallexample
-void *ptr;
-/* @r{@dots{}} */
-ptr = &&foo;
-@end smallexample
-
-To use these values, you need to be able to jump to one. This is done
-with the computed goto statement@footnote{The analogous feature in
-Fortran is called an assigned goto, but that name seems inappropriate in
-C, where one can do more than simply store label addresses in label
-variables.}, @code{goto *@var{exp};}. For example,
-
-@smallexample
-goto *ptr;
-@end smallexample
-
-@noindent
-Any expression of type @code{void *} is allowed.
-
-One way of using these constants is in initializing a static array that
-serves as a jump table:
-
-@smallexample
-static void *array[] = @{ &&foo, &&bar, &&hack @};
-@end smallexample
-
-@noindent
-Then you can select a label with indexing, like this:
-
-@smallexample
-goto *array[i];
-@end smallexample
-
-@noindent
-Note that this does not check whether the subscript is in bounds---array
-indexing in C never does that.
-
-Such an array of label values serves a purpose much like that of the
-@code{switch} statement. The @code{switch} statement is cleaner, so
-use that rather than an array unless the problem does not fit a
-@code{switch} statement very well.
-
-Another use of label values is in an interpreter for threaded code.
-The labels within the interpreter function can be stored in the
-threaded code for super-fast dispatching.
-
-You may not use this mechanism to jump to code in a different function.
-If you do that, totally unpredictable things happen. The best way to
-avoid this is to store the label address only in automatic variables and
-never pass it as an argument.
-
-An alternate way to write the above example is
-
-@smallexample
-static const int array[] = @{ &&foo - &&foo, &&bar - &&foo,
- &&hack - &&foo @};
-goto *(&&foo + array[i]);
-@end smallexample
-
-@noindent
-This is more friendly to code living in shared libraries, as it reduces
-the number of dynamic relocations that are needed, and by consequence,
-allows the data to be read-only.
-This alternative with label differences is not supported for the AVR target,
-please use the first approach for AVR programs.
-
-The @code{&&foo} expressions for the same label might have different
-values if the containing function is inlined or cloned. If a program
-relies on them being always the same,
-@code{__attribute__((__noinline__,__noclone__))} should be used to
-prevent inlining and cloning. If @code{&&foo} is used in a static
-variable initializer, inlining and cloning is forbidden.
-
-@node Nested Functions
-@section Nested Functions
-@cindex nested functions
-@cindex downward funargs
-@cindex thunks
-
-A @dfn{nested function} is a function defined inside another function.
-Nested functions are supported as an extension in GNU C, but are not
-supported by GNU C++.
-
-The nested function's name is local to the block where it is defined.
-For example, here we define a nested function named @code{square}, and
-call it twice:
-
-@smallexample
-@group
-foo (double a, double b)
-@{
- double square (double z) @{ return z * z; @}
-
- return square (a) + square (b);
-@}
-@end group
-@end smallexample
-
-The nested function can access all the variables of the containing
-function that are visible at the point of its definition. This is
-called @dfn{lexical scoping}. For example, here we show a nested
-function which uses an inherited variable named @code{offset}:
-
-@smallexample
-@group
-bar (int *array, int offset, int size)
-@{
- int access (int *array, int index)
- @{ return array[index + offset]; @}
- int i;
- /* @r{@dots{}} */
- for (i = 0; i < size; i++)
- /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */
-@}
-@end group
-@end smallexample
-
-Nested function definitions are permitted within functions in the places
-where variable definitions are allowed; that is, in any block, mixed
-with the other declarations and statements in the block.
-
-It is possible to call the nested function from outside the scope of its
-name by storing its address or passing the address to another function:
-
-@smallexample
-hack (int *array, int size)
-@{
- void store (int index, int value)
- @{ array[index] = value; @}
-
- intermediate (store, size);
-@}
-@end smallexample
-
-Here, the function @code{intermediate} receives the address of
-@code{store} as an argument. If @code{intermediate} calls @code{store},
-the arguments given to @code{store} are used to store into @code{array}.
-But this technique works only so long as the containing function
-(@code{hack}, in this example) does not exit.
-
-If you try to call the nested function through its address after the
-containing function exits, all hell breaks loose. If you try
-to call it after a containing scope level exits, and if it refers
-to some of the variables that are no longer in scope, you may be lucky,
-but it's not wise to take the risk. If, however, the nested function
-does not refer to anything that has gone out of scope, you should be
-safe.
-
-GCC implements taking the address of a nested function using a technique
-called @dfn{trampolines}. This technique was described in
-@cite{Lexical Closures for C++} (Thomas M. Breuel, USENIX
-C++ Conference Proceedings, October 17-21, 1988).
-
-A nested function can jump to a label inherited from a containing
-function, provided the label is explicitly declared in the containing
-function (@pxref{Local Labels}). Such a jump returns instantly to the
-containing function, exiting the nested function that did the
-@code{goto} and any intermediate functions as well. Here is an example:
-
-@smallexample
-@group
-bar (int *array, int offset, int size)
-@{
- __label__ failure;
- int access (int *array, int index)
- @{
- if (index > size)
- goto failure;
- return array[index + offset];
- @}
- int i;
- /* @r{@dots{}} */
- for (i = 0; i < size; i++)
- /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */
- /* @r{@dots{}} */
- return 0;
-
- /* @r{Control comes here from @code{access}
- if it detects an error.} */
- failure:
- return -1;
-@}
-@end group
-@end smallexample
-
-A nested function always has no linkage. Declaring one with
-@code{extern} or @code{static} is erroneous. If you need to declare the nested function
-before its definition, use @code{auto} (which is otherwise meaningless
-for function declarations).
-
-@smallexample
-bar (int *array, int offset, int size)
-@{
- __label__ failure;
- auto int access (int *, int);
- /* @r{@dots{}} */
- int access (int *array, int index)
- @{
- if (index > size)
- goto failure;
- return array[index + offset];
- @}
- /* @r{@dots{}} */
-@}
-@end smallexample
-
-@node Nonlocal Gotos
-@section Nonlocal Gotos
-@cindex nonlocal gotos
-
-GCC provides the built-in functions @code{__builtin_setjmp} and
-@code{__builtin_longjmp} which are similar to, but not interchangeable
-with, the C library functions @code{setjmp} and @code{longjmp}.
-The built-in versions are used internally by GCC's libraries
-to implement exception handling on some targets. You should use the
-standard C library functions declared in @code{<setjmp.h>} in user code
-instead of the builtins.
-
-The built-in versions of these functions use GCC's normal
-mechanisms to save and restore registers using the stack on function
-entry and exit. The jump buffer argument @var{buf} holds only the
-information needed to restore the stack frame, rather than the entire
-set of saved register values.
-
-An important caveat is that GCC arranges to save and restore only
-those registers known to the specific architecture variant being
-compiled for. This can make @code{__builtin_setjmp} and
-@code{__builtin_longjmp} more efficient than their library
-counterparts in some cases, but it can also cause incorrect and
-mysterious behavior when mixing with code that uses the full register
-set.
-
-You should declare the jump buffer argument @var{buf} to the
-built-in functions as:
-
-@smallexample
-#include <stdint.h>
-intptr_t @var{buf}[5];
-@end smallexample
-
-@deftypefn {Built-in Function} {int} __builtin_setjmp (intptr_t *@var{buf})
-This function saves the current stack context in @var{buf}.
-@code{__builtin_setjmp} returns 0 when returning directly,
-and 1 when returning from @code{__builtin_longjmp} using the same
-@var{buf}.
-@end deftypefn
-
-@deftypefn {Built-in Function} {void} __builtin_longjmp (intptr_t *@var{buf}, int @var{val})
-This function restores the stack context in @var{buf},
-saved by a previous call to @code{__builtin_setjmp}. After
-@code{__builtin_longjmp} is finished, the program resumes execution as
-if the matching @code{__builtin_setjmp} returns the value @var{val},
-which must be 1.
-
-Because @code{__builtin_longjmp} depends on the function return
-mechanism to restore the stack context, it cannot be called
-from the same function calling @code{__builtin_setjmp} to
-initialize @var{buf}. It can only be called from a function called
-(directly or indirectly) from the function calling @code{__builtin_setjmp}.
-@end deftypefn
-
-@node Constructing Calls
-@section Constructing Function Calls
-@cindex constructing calls
-@cindex forwarding calls
-
-Using the built-in functions described below, you can record
-the arguments a function received, and call another function
-with the same arguments, without knowing the number or types
-of the arguments.
-
-You can also record the return value of that function call,
-and later return that value, without knowing what data type
-the function tried to return (as long as your caller expects
-that data type).
-
-However, these built-in functions may interact badly with some
-sophisticated features or other extensions of the language. It
-is, therefore, not recommended to use them outside very simple
-functions acting as mere forwarders for their arguments.
-
-@deftypefn {Built-in Function} {void *} __builtin_apply_args ()
-This built-in function returns a pointer to data
-describing how to perform a call with the same arguments as are passed
-to the current function.
-
-The function saves the arg pointer register, structure value address,
-and all registers that might be used to pass arguments to a function
-into a block of memory allocated on the stack. Then it returns the
-address of that block.
-@end deftypefn
-
-@deftypefn {Built-in Function} {void *} __builtin_apply (void (*@var{function})(), void *@var{arguments}, size_t @var{size})
-This built-in function invokes @var{function}
-with a copy of the parameters described by @var{arguments}
-and @var{size}.
-
-The value of @var{arguments} should be the value returned by
-@code{__builtin_apply_args}. The argument @var{size} specifies the size
-of the stack argument data, in bytes.
-
-This function returns a pointer to data describing
-how to return whatever value is returned by @var{function}. The data
-is saved in a block of memory allocated on the stack.
-
-It is not always simple to compute the proper value for @var{size}. The
-value is used by @code{__builtin_apply} to compute the amount of data
-that should be pushed on the stack and copied from the incoming argument
-area.
-@end deftypefn
-
-@deftypefn {Built-in Function} {void} __builtin_return (void *@var{result})
-This built-in function returns the value described by @var{result} from
-the containing function. You should specify, for @var{result}, a value
-returned by @code{__builtin_apply}.
-@end deftypefn
-
-@deftypefn {Built-in Function} {} __builtin_va_arg_pack ()
-This built-in function represents all anonymous arguments of an inline
-function. It can be used only in inline functions that are always
-inlined, never compiled as a separate function, such as those using
-@code{__attribute__ ((__always_inline__))} or
-@code{__attribute__ ((__gnu_inline__))} extern inline functions.
-It must be only passed as last argument to some other function
-with variable arguments. This is useful for writing small wrapper
-inlines for variable argument functions, when using preprocessor
-macros is undesirable. For example:
-@smallexample
-extern int myprintf (FILE *f, const char *format, ...);
-extern inline __attribute__ ((__gnu_inline__)) int
-myprintf (FILE *f, const char *format, ...)
-@{
- int r = fprintf (f, "myprintf: ");
- if (r < 0)
- return r;
- int s = fprintf (f, format, __builtin_va_arg_pack ());
- if (s < 0)
- return s;
- return r + s;
-@}
-@end smallexample
-@end deftypefn
-
-@deftypefn {Built-in Function} {size_t} __builtin_va_arg_pack_len ()
-This built-in function returns the number of anonymous arguments of
-an inline function. It can be used only in inline functions that
-are always inlined, never compiled as a separate function, such
-as those using @code{__attribute__ ((__always_inline__))} or
-@code{__attribute__ ((__gnu_inline__))} extern inline functions.
-For example following does link- or run-time checking of open
-arguments for optimized code:
-@smallexample
-#ifdef __OPTIMIZE__
-extern inline __attribute__((__gnu_inline__)) int
-myopen (const char *path, int oflag, ...)
-@{
- if (__builtin_va_arg_pack_len () > 1)
- warn_open_too_many_arguments ();
-
- if (__builtin_constant_p (oflag))
- @{
- if ((oflag & O_CREAT) != 0 && __builtin_va_arg_pack_len () < 1)
- @{
- warn_open_missing_mode ();
- return __open_2 (path, oflag);
- @}
- return open (path, oflag, __builtin_va_arg_pack ());
- @}
-
- if (__builtin_va_arg_pack_len () < 1)
- return __open_2 (path, oflag);
-
- return open (path, oflag, __builtin_va_arg_pack ());
-@}
-#endif
-@end smallexample
-@end deftypefn
-
-@node Typeof
-@section Referring to a Type with @code{typeof}
-@findex typeof
-@findex sizeof
-@cindex macros, types of arguments
-
-Another way to refer to the type of an expression is with @code{typeof}.
-The syntax of using of this keyword looks like @code{sizeof}, but the
-construct acts semantically like a type name defined with @code{typedef}.
-
-There are two ways of writing the argument to @code{typeof}: with an
-expression or with a type. Here is an example with an expression:
-
-@smallexample
-typeof (x[0](1))
-@end smallexample
-
-@noindent
-This assumes that @code{x} is an array of pointers to functions;
-the type described is that of the values of the functions.
-
-Here is an example with a typename as the argument:
-
-@smallexample
-typeof (int *)
-@end smallexample
-
-@noindent
-Here the type described is that of pointers to @code{int}.
-
-If you are writing a header file that must work when included in ISO C
-programs, write @code{__typeof__} instead of @code{typeof}.
-@xref{Alternate Keywords}.
-
-A @code{typeof} construct can be used anywhere a typedef name can be
-used. For example, you can use it in a declaration, in a cast, or inside
-of @code{sizeof} or @code{typeof}.
-
-The operand of @code{typeof} is evaluated for its side effects if and
-only if it is an expression of variably modified type or the name of
-such a type.
-
-@code{typeof} is often useful in conjunction with
-statement expressions (@pxref{Statement Exprs}).
-Here is how the two together can
-be used to define a safe ``maximum'' macro which operates on any
-arithmetic type and evaluates each of its arguments exactly once:
-
-@smallexample
-#define max(a,b) \
- (@{ typeof (a) _a = (a); \
- typeof (b) _b = (b); \
- _a > _b ? _a : _b; @})
-@end smallexample
-
-@cindex underscores in variables in macros
-@cindex @samp{_} in variables in macros
-@cindex local variables in macros
-@cindex variables, local, in macros
-@cindex macros, local variables in
-
-The reason for using names that start with underscores for the local
-variables is to avoid conflicts with variable names that occur within the
-expressions that are substituted for @code{a} and @code{b}. Eventually we
-hope to design a new form of declaration syntax that allows you to declare
-variables whose scopes start only after their initializers; this will be a
-more reliable way to prevent such conflicts.
-
-@noindent
-Some more examples of the use of @code{typeof}:
-
-@itemize @bullet
-@item
-This declares @code{y} with the type of what @code{x} points to.
-
-@smallexample
-typeof (*x) y;
-@end smallexample
-
-@item
-This declares @code{y} as an array of such values.
-
-@smallexample
-typeof (*x) y[4];
-@end smallexample
-
-@item
-This declares @code{y} as an array of pointers to characters:
-
-@smallexample
-typeof (typeof (char *)[4]) y;
-@end smallexample
-
-@noindent
-It is equivalent to the following traditional C declaration:
-
-@smallexample
-char *y[4];
-@end smallexample
-
-To see the meaning of the declaration using @code{typeof}, and why it
-might be a useful way to write, rewrite it with these macros:
-
-@smallexample
-#define pointer(T) typeof(T *)
-#define array(T, N) typeof(T [N])
-@end smallexample
-
-@noindent
-Now the declaration can be rewritten this way:
-
-@smallexample
-array (pointer (char), 4) y;
-@end smallexample
-
-@noindent
-Thus, @code{array (pointer (char), 4)} is the type of arrays of 4
-pointers to @code{char}.
-@end itemize
-
-In GNU C, but not GNU C++, you may also declare the type of a variable
-as @code{__auto_type}. In that case, the declaration must declare
-only one variable, whose declarator must just be an identifier, the
-declaration must be initialized, and the type of the variable is
-determined by the initializer; the name of the variable is not in
-scope until after the initializer. (In C++, you should use C++11
-@code{auto} for this purpose.) Using @code{__auto_type}, the
-``maximum'' macro above could be written as:
-
-@smallexample
-#define max(a,b) \
- (@{ __auto_type _a = (a); \
- __auto_type _b = (b); \
- _a > _b ? _a : _b; @})
-@end smallexample
-
-Using @code{__auto_type} instead of @code{typeof} has two advantages:
-
-@itemize @bullet
-@item Each argument to the macro appears only once in the expansion of
-the macro. This prevents the size of the macro expansion growing
-exponentially when calls to such macros are nested inside arguments of
-such macros.
-
-@item If the argument to the macro has variably modified type, it is
-evaluated only once when using @code{__auto_type}, but twice if
-@code{typeof} is used.
-@end itemize
-
-@node Conditionals
-@section Conditionals with Omitted Operands
-@cindex conditional expressions, extensions
-@cindex omitted middle-operands
-@cindex middle-operands, omitted
-@cindex extensions, @code{?:}
-@cindex @code{?:} extensions
-
-The middle operand in a conditional expression may be omitted. Then
-if the first operand is nonzero, its value is the value of the conditional
-expression.
-
-Therefore, the expression
-
-@smallexample
-x ? : y
-@end smallexample
-
-@noindent
-has the value of @code{x} if that is nonzero; otherwise, the value of
-@code{y}.
-
-This example is perfectly equivalent to
-
-@smallexample
-x ? x : y
-@end smallexample
-
-@cindex side effect in @code{?:}
-@cindex @code{?:} side effect
-@noindent
-In this simple case, the ability to omit the middle operand is not
-especially useful. When it becomes useful is when the first operand does,
-or may (if it is a macro argument), contain a side effect. Then repeating
-the operand in the middle would perform the side effect twice. Omitting
-the middle operand uses the value already computed without the undesirable
-effects of recomputing it.
-
-@node __int128
-@section 128-bit Integers
-@cindex @code{__int128} data types
-
-As an extension the integer scalar type @code{__int128} is supported for
-targets which have an integer mode wide enough to hold 128 bits.
-Simply write @code{__int128} for a signed 128-bit integer, or
-@code{unsigned __int128} for an unsigned 128-bit integer. There is no
-support in GCC for expressing an integer constant of type @code{__int128}
-for targets with @code{long long} integer less than 128 bits wide.
-
-@node Long Long
-@section Double-Word Integers
-@cindex @code{long long} data types
-@cindex double-word arithmetic
-@cindex multiprecision arithmetic
-@cindex @code{LL} integer suffix
-@cindex @code{ULL} integer suffix
-
-ISO C99 and ISO C++11 support data types for integers that are at least
-64 bits wide, and as an extension GCC supports them in C90 and C++98 modes.
-Simply write @code{long long int} for a signed integer, or
-@code{unsigned long long int} for an unsigned integer. To make an
-integer constant of type @code{long long int}, add the suffix @samp{LL}
-to the integer. To make an integer constant of type @code{unsigned long
-long int}, add the suffix @samp{ULL} to the integer.
-
-You can use these types in arithmetic like any other integer types.
-Addition, subtraction, and bitwise boolean operations on these types
-are open-coded on all types of machines. Multiplication is open-coded
-if the machine supports a fullword-to-doubleword widening multiply
-instruction. Division and shifts are open-coded only on machines that
-provide special support. The operations that are not open-coded use
-special library routines that come with GCC@.
-
-There may be pitfalls when you use @code{long long} types for function
-arguments without function prototypes. If a function
-expects type @code{int} for its argument, and you pass a value of type
-@code{long long int}, confusion results because the caller and the
-subroutine disagree about the number of bytes for the argument.
-Likewise, if the function expects @code{long long int} and you pass
-@code{int}. The best way to avoid such problems is to use prototypes.
-
-@node Complex
-@section Complex Numbers
-@cindex complex numbers
-@cindex @code{_Complex} keyword
-@cindex @code{__complex__} keyword
-
-ISO C99 supports complex floating data types, and as an extension GCC
-supports them in C90 mode and in C++. GCC also supports complex integer data
-types which are not part of ISO C99. You can declare complex types
-using the keyword @code{_Complex}. As an extension, the older GNU
-keyword @code{__complex__} is also supported.
-
-For example, @samp{_Complex double x;} declares @code{x} as a
-variable whose real part and imaginary part are both of type
-@code{double}. @samp{_Complex short int y;} declares @code{y} to
-have real and imaginary parts of type @code{short int}; this is not
-likely to be useful, but it shows that the set of complex types is
-complete.
-
-To write a constant with a complex data type, use the suffix @samp{i} or
-@samp{j} (either one; they are equivalent). For example, @code{2.5fi}
-has type @code{_Complex float} and @code{3i} has type
-@code{_Complex int}. Such a constant always has a pure imaginary
-value, but you can form any complex value you like by adding one to a
-real constant. This is a GNU extension; if you have an ISO C99
-conforming C library (such as the GNU C Library), and want to construct complex
-constants of floating type, you should include @code{<complex.h>} and
-use the macros @code{I} or @code{_Complex_I} instead.
-
-The ISO C++14 library also defines the @samp{i} suffix, so C++14 code
-that includes the @samp{<complex>} header cannot use @samp{i} for the
-GNU extension. The @samp{j} suffix still has the GNU meaning.
-
-GCC can handle both implicit and explicit casts between the @code{_Complex}
-types and other @code{_Complex} types as casting both the real and imaginary
-parts to the scalar type.
-GCC can handle implicit and explicit casts from a scalar type to a @code{_Complex}
-type and where the imaginary part will be considered zero.
-The C front-end can handle implicit and explicit casts from a @code{_Complex} type
-to a scalar type where the imaginary part will be ignored. In C++ code, this cast
-is considered illformed and G++ will error out.
-
-GCC provides a built-in function @code{__builtin_complex} will can be used to
-construct a complex value.
-
-@cindex @code{__real__} keyword
-@cindex @code{__imag__} keyword
-
-GCC has a few extensions which can be used to extract the real
-and the imaginary part of the complex-valued expression. Note
-these expressions are lvalues if the @var{exp} is an lvalue.
-These expressions operands have the type of a complex type
-which might get prompoted to a complex type from a scalar type.
-E.g. @code{__real__ (int)@var{x}} is the same as casting to
-@code{_Complex int} before @code{__real__} is done.
-
-@multitable @columnfractions .4 .6
-@headitem Expression @tab Description
-@item @code{__real__ @var{exp}}
-@tab Extract the real part of @var{exp}.
-@item @code{__imag__ @var{exp}}
-@tab Extract the imaginary part of @var{exp}.
-@end multitable
-
-For values of floating point, you should use the ISO C99
-functions, declared in @code{<complex.h>} and also provided as
-built-in functions by GCC@.
-
-@multitable @columnfractions .4 .2 .2 .2
-@headitem Expression @tab float @tab double @tab long double
-@item @code{__real__ @var{exp}}
-@tab @code{crealf} @tab @code{creal} @tab @code{creall}
-@item @code{__imag__ @var{exp}}
-@tab @code{cimagf} @tab @code{cimag} @tab @code{cimagl}
-@end multitable
-
-@cindex complex conjugation
-The operator @samp{~} performs complex conjugation when used on a value
-with a complex type. This is a GNU extension; for values of
-floating type, you should use the ISO C99 functions @code{conjf},
-@code{conj} and @code{conjl}, declared in @code{<complex.h>} and also
-provided as built-in functions by GCC@. Note unlike the @code{__real__}
-and @code{__imag__} operators, this operator will not do an implicit cast
-to the complex type because the @samp{~} is already a normal operator.
-
-GCC can allocate complex automatic variables in a noncontiguous
-fashion; it's even possible for the real part to be in a register while
-the imaginary part is on the stack (or vice versa). Only the DWARF
-debug info format can represent this, so use of DWARF is recommended.
-If you are using the stabs debug info format, GCC describes a noncontiguous
-complex variable as if it were two separate variables of noncomplex type.
-If the variable's actual name is @code{foo}, the two fictitious
-variables are named @code{foo$real} and @code{foo$imag}. You can
-examine and set these two fictitious variables with your debugger.
-
-@deftypefn {Built-in Function} @var{type} __builtin_complex (@var{real}, @var{imag})
-
-The built-in function @code{__builtin_complex} is provided for use in
-implementing the ISO C11 macros @code{CMPLXF}, @code{CMPLX} and
-@code{CMPLXL}. @var{real} and @var{imag} must have the same type, a
-real binary floating-point type, and the result has the corresponding
-complex type with real and imaginary parts @var{real} and @var{imag}.
-Unlike @samp{@var{real} + I * @var{imag}}, this works even when
-infinities, NaNs and negative zeros are involved.
-
-@end deftypefn
-
-@node Floating Types
-@section Additional Floating Types
-@cindex additional floating types
-@cindex @code{_Float@var{n}} data types
-@cindex @code{_Float@var{n}x} data types
-@cindex @code{__float80} data type
-@cindex @code{__float128} data type
-@cindex @code{__ibm128} data type
-@cindex @code{w} floating point suffix
-@cindex @code{q} floating point suffix
-@cindex @code{W} floating point suffix
-@cindex @code{Q} floating point suffix
-
-ISO/IEC TS 18661-3:2015 defines C support for additional floating
-types @code{_Float@var{n}} and @code{_Float@var{n}x}, and GCC supports
-these type names; the set of types supported depends on the target
-architecture. These types are not supported when compiling C++.
-Constants with these types use suffixes @code{f@var{n}} or
-@code{F@var{n}} and @code{f@var{n}x} or @code{F@var{n}x}. These type
-names can be used together with @code{_Complex} to declare complex
-types.
-
-As an extension, GNU C and GNU C++ support additional floating
-types, which are not supported by all targets.
-@itemize @bullet
-@item @code{__float128} is available on i386, x86_64, IA-64, and
-hppa HP-UX, as well as on PowerPC GNU/Linux targets that enable
-the vector scalar (VSX) instruction set. @code{__float128} supports
-the 128-bit floating type. On i386, x86_64, PowerPC, and IA-64
-other than HP-UX, @code{__float128} is an alias for @code{_Float128}.
-On hppa and IA-64 HP-UX, @code{__float128} is an alias for @code{long
-double}.
-
-@item @code{__float80} is available on the i386, x86_64, and IA-64
-targets, and supports the 80-bit (@code{XFmode}) floating type. It is
-an alias for the type name @code{_Float64x} on these targets.
-
-@item @code{__ibm128} is available on PowerPC targets, and provides
-access to the IBM extended double format which is the current format
-used for @code{long double}. When @code{long double} transitions to
-@code{__float128} on PowerPC in the future, @code{__ibm128} will remain
-for use in conversions between the two types.
-@end itemize
-
-Support for these additional types includes the arithmetic operators:
-add, subtract, multiply, divide; unary arithmetic operators;
-relational operators; equality operators; and conversions to and from
-integer and other floating types. Use a suffix @samp{w} or @samp{W}
-in a literal constant of type @code{__float80} or type
-@code{__ibm128}. Use a suffix @samp{q} or @samp{Q} for @code{__float128}.
-
-In order to use @code{_Float128}, @code{__float128}, and @code{__ibm128}
-on PowerPC Linux systems, you must use the @option{-mfloat128} option. It is
-expected in future versions of GCC that @code{_Float128} and @code{__float128}
-will be enabled automatically.
-
-The @code{_Float128} type is supported on all systems where
-@code{__float128} is supported or where @code{long double} has the
-IEEE binary128 format. The @code{_Float64x} type is supported on all
-systems where @code{__float128} is supported. The @code{_Float32}
-type is supported on all systems supporting IEEE binary32; the
-@code{_Float64} and @code{_Float32x} types are supported on all systems
-supporting IEEE binary64. The @code{_Float16} type is supported on AArch64
-systems by default, on ARM systems when the IEEE format for 16-bit
-floating-point types is selected with @option{-mfp16-format=ieee} and,
-for both C and C++, on x86 systems with SSE2 enabled. GCC does not currently
-support @code{_Float128x} on any systems.
-
-On the i386, x86_64, IA-64, and HP-UX targets, you can declare complex
-types using the corresponding internal complex type, @code{XCmode} for
-@code{__float80} type and @code{TCmode} for @code{__float128} type:
-
-@smallexample
-typedef _Complex float __attribute__((mode(TC))) _Complex128;
-typedef _Complex float __attribute__((mode(XC))) _Complex80;
-@end smallexample
-
-On the PowerPC Linux VSX targets, you can declare complex types using
-the corresponding internal complex type, @code{KCmode} for
-@code{__float128} type and @code{ICmode} for @code{__ibm128} type:
-
-@smallexample
-typedef _Complex float __attribute__((mode(KC))) _Complex_float128;
-typedef _Complex float __attribute__((mode(IC))) _Complex_ibm128;
-@end smallexample
-
-@node Half-Precision
-@section Half-Precision Floating Point
-@cindex half-precision floating point
-@cindex @code{__fp16} data type
-@cindex @code{__Float16} data type
-
-On ARM and AArch64 targets, GCC supports half-precision (16-bit) floating
-point via the @code{__fp16} type defined in the ARM C Language Extensions.
-On ARM systems, you must enable this type explicitly with the
-@option{-mfp16-format} command-line option in order to use it.
-On x86 targets with SSE2 enabled, GCC supports half-precision (16-bit)
-floating point via the @code{_Float16} type. For C++, x86 provides a builtin
-type named @code{_Float16} which contains same data format as C.
-
-ARM targets support two incompatible representations for half-precision
-floating-point values. You must choose one of the representations and
-use it consistently in your program.
-
-Specifying @option{-mfp16-format=ieee} selects the IEEE 754-2008 format.
-This format can represent normalized values in the range of @math{2^{-14}} to 65504.
-There are 11 bits of significand precision, approximately 3
-decimal digits.
-
-Specifying @option{-mfp16-format=alternative} selects the ARM
-alternative format. This representation is similar to the IEEE
-format, but does not support infinities or NaNs. Instead, the range
-of exponents is extended, so that this format can represent normalized
-values in the range of @math{2^{-14}} to 131008.
-
-The GCC port for AArch64 only supports the IEEE 754-2008 format, and does
-not require use of the @option{-mfp16-format} command-line option.
-
-The @code{__fp16} type may only be used as an argument to intrinsics defined
-in @code{<arm_fp16.h>}, or as a storage format. For purposes of
-arithmetic and other operations, @code{__fp16} values in C or C++
-expressions are automatically promoted to @code{float}.
-
-The ARM target provides hardware support for conversions between
-@code{__fp16} and @code{float} values
-as an extension to VFP and NEON (Advanced SIMD), and from ARMv8-A provides
-hardware support for conversions between @code{__fp16} and @code{double}
-values. GCC generates code using these hardware instructions if you
-compile with options to select an FPU that provides them;
-for example, @option{-mfpu=neon-fp16 -mfloat-abi=softfp},
-in addition to the @option{-mfp16-format} option to select
-a half-precision format.
-
-Language-level support for the @code{__fp16} data type is
-independent of whether GCC generates code using hardware floating-point
-instructions. In cases where hardware support is not specified, GCC
-implements conversions between @code{__fp16} and other types as library
-calls.
-
-It is recommended that portable code use the @code{_Float16} type defined
-by ISO/IEC TS 18661-3:2015. @xref{Floating Types}.
-
-On x86 targets with SSE2 enabled, without @option{-mavx512fp16},
-all operations will be emulated by software emulation and the @code{float}
-instructions. The default behavior for @code{FLT_EVAL_METHOD} is to keep the
-intermediate result of the operation as 32-bit precision. This may lead to
-inconsistent behavior between software emulation and AVX512-FP16 instructions.
-Using @option{-fexcess-precision=16} will force round back after each operation.
-
-Using @option{-mavx512fp16} will generate AVX512-FP16 instructions instead of
-software emulation. The default behavior of @code{FLT_EVAL_METHOD} is to round
-after each operation. The same is true with @option{-fexcess-precision=standard}
-and @option{-mfpmath=sse}. If there is no @option{-mfpmath=sse},
-@option{-fexcess-precision=standard} alone does the same thing as before,
-It is useful for code that does not have @code{_Float16} and runs on the x87
-FPU.
-
-@node Decimal Float
-@section Decimal Floating Types
-@cindex decimal floating types
-@cindex @code{_Decimal32} data type
-@cindex @code{_Decimal64} data type
-@cindex @code{_Decimal128} data type
-@cindex @code{df} integer suffix
-@cindex @code{dd} integer suffix
-@cindex @code{dl} integer suffix
-@cindex @code{DF} integer suffix
-@cindex @code{DD} integer suffix
-@cindex @code{DL} integer suffix
-
-As an extension, GNU C supports decimal floating types as
-defined in the N1312 draft of ISO/IEC WDTR24732. Support for decimal
-floating types in GCC will evolve as the draft technical report changes.
-Calling conventions for any target might also change. Not all targets
-support decimal floating types.
-
-The decimal floating types are @code{_Decimal32}, @code{_Decimal64}, and
-@code{_Decimal128}. They use a radix of ten, unlike the floating types
-@code{float}, @code{double}, and @code{long double} whose radix is not
-specified by the C standard but is usually two.
-
-Support for decimal floating types includes the arithmetic operators
-add, subtract, multiply, divide; unary arithmetic operators;
-relational operators; equality operators; and conversions to and from
-integer and other floating types. Use a suffix @samp{df} or
-@samp{DF} in a literal constant of type @code{_Decimal32}, @samp{dd}
-or @samp{DD} for @code{_Decimal64}, and @samp{dl} or @samp{DL} for
-@code{_Decimal128}.
-
-GCC support of decimal float as specified by the draft technical report
-is incomplete:
-
-@itemize @bullet
-@item
-When the value of a decimal floating type cannot be represented in the
-integer type to which it is being converted, the result is undefined
-rather than the result value specified by the draft technical report.
-
-@item
-GCC does not provide the C library functionality associated with
-@file{math.h}, @file{fenv.h}, @file{stdio.h}, @file{stdlib.h}, and
-@file{wchar.h}, which must come from a separate C library implementation.
-Because of this the GNU C compiler does not define macro
-@code{__STDC_DEC_FP__} to indicate that the implementation conforms to
-the technical report.
-@end itemize
-
-Types @code{_Decimal32}, @code{_Decimal64}, and @code{_Decimal128}
-are supported by the DWARF debug information format.
-
-@node Hex Floats
-@section Hex Floats
-@cindex hex floats
-
-ISO C99 and ISO C++17 support floating-point numbers written not only in
-the usual decimal notation, such as @code{1.55e1}, but also numbers such as
-@code{0x1.fp3} written in hexadecimal format. As a GNU extension, GCC
-supports this in C90 mode (except in some cases when strictly
-conforming) and in C++98, C++11 and C++14 modes. In that format the
-@samp{0x} hex introducer and the @samp{p} or @samp{P} exponent field are
-mandatory. The exponent is a decimal number that indicates the power of
-2 by which the significant part is multiplied. Thus @samp{0x1.f} is
-@tex
-$1 {15\over16}$,
-@end tex
-@ifnottex
-1 15/16,
-@end ifnottex
-@samp{p3} multiplies it by 8, and the value of @code{0x1.fp3}
-is the same as @code{1.55e1}.
-
-Unlike for floating-point numbers in the decimal notation the exponent
-is always required in the hexadecimal notation. Otherwise the compiler
-would not be able to resolve the ambiguity of, e.g., @code{0x1.f}. This
-could mean @code{1.0f} or @code{1.9375} since @samp{f} is also the
-extension for floating-point constants of type @code{float}.
-
-@node Fixed-Point
-@section Fixed-Point Types
-@cindex fixed-point types
-@cindex @code{_Fract} data type
-@cindex @code{_Accum} data type
-@cindex @code{_Sat} data type
-@cindex @code{hr} fixed-suffix
-@cindex @code{r} fixed-suffix
-@cindex @code{lr} fixed-suffix
-@cindex @code{llr} fixed-suffix
-@cindex @code{uhr} fixed-suffix
-@cindex @code{ur} fixed-suffix
-@cindex @code{ulr} fixed-suffix
-@cindex @code{ullr} fixed-suffix
-@cindex @code{hk} fixed-suffix
-@cindex @code{k} fixed-suffix
-@cindex @code{lk} fixed-suffix
-@cindex @code{llk} fixed-suffix
-@cindex @code{uhk} fixed-suffix
-@cindex @code{uk} fixed-suffix
-@cindex @code{ulk} fixed-suffix
-@cindex @code{ullk} fixed-suffix
-@cindex @code{HR} fixed-suffix
-@cindex @code{R} fixed-suffix
-@cindex @code{LR} fixed-suffix
-@cindex @code{LLR} fixed-suffix
-@cindex @code{UHR} fixed-suffix
-@cindex @code{UR} fixed-suffix
-@cindex @code{ULR} fixed-suffix
-@cindex @code{ULLR} fixed-suffix
-@cindex @code{HK} fixed-suffix
-@cindex @code{K} fixed-suffix
-@cindex @code{LK} fixed-suffix
-@cindex @code{LLK} fixed-suffix
-@cindex @code{UHK} fixed-suffix
-@cindex @code{UK} fixed-suffix
-@cindex @code{ULK} fixed-suffix
-@cindex @code{ULLK} fixed-suffix
-
-As an extension, GNU C supports fixed-point types as
-defined in the N1169 draft of ISO/IEC DTR 18037. Support for fixed-point
-types in GCC will evolve as the draft technical report changes.
-Calling conventions for any target might also change. Not all targets
-support fixed-point types.
-
-The fixed-point types are
-@code{short _Fract},
-@code{_Fract},
-@code{long _Fract},
-@code{long long _Fract},
-@code{unsigned short _Fract},
-@code{unsigned _Fract},
-@code{unsigned long _Fract},
-@code{unsigned long long _Fract},
-@code{_Sat short _Fract},
-@code{_Sat _Fract},
-@code{_Sat long _Fract},
-@code{_Sat long long _Fract},
-@code{_Sat unsigned short _Fract},
-@code{_Sat unsigned _Fract},
-@code{_Sat unsigned long _Fract},
-@code{_Sat unsigned long long _Fract},
-@code{short _Accum},
-@code{_Accum},
-@code{long _Accum},
-@code{long long _Accum},
-@code{unsigned short _Accum},
-@code{unsigned _Accum},
-@code{unsigned long _Accum},
-@code{unsigned long long _Accum},
-@code{_Sat short _Accum},
-@code{_Sat _Accum},
-@code{_Sat long _Accum},
-@code{_Sat long long _Accum},
-@code{_Sat unsigned short _Accum},
-@code{_Sat unsigned _Accum},
-@code{_Sat unsigned long _Accum},
-@code{_Sat unsigned long long _Accum}.
-
-Fixed-point data values contain fractional and optional integral parts.
-The format of fixed-point data varies and depends on the target machine.
-
-Support for fixed-point types includes:
-@itemize @bullet
-@item
-prefix and postfix increment and decrement operators (@code{++}, @code{--})
-@item
-unary arithmetic operators (@code{+}, @code{-}, @code{!})
-@item
-binary arithmetic operators (@code{+}, @code{-}, @code{*}, @code{/})
-@item
-binary shift operators (@code{<<}, @code{>>})
-@item
-relational operators (@code{<}, @code{<=}, @code{>=}, @code{>})
-@item
-equality operators (@code{==}, @code{!=})
-@item
-assignment operators (@code{+=}, @code{-=}, @code{*=}, @code{/=},
-@code{<<=}, @code{>>=})
-@item
-conversions to and from integer, floating-point, or fixed-point types
-@end itemize
-
-Use a suffix in a fixed-point literal constant:
-@itemize
-@item @samp{hr} or @samp{HR} for @code{short _Fract} and
-@code{_Sat short _Fract}
-@item @samp{r} or @samp{R} for @code{_Fract} and @code{_Sat _Fract}
-@item @samp{lr} or @samp{LR} for @code{long _Fract} and
-@code{_Sat long _Fract}
-@item @samp{llr} or @samp{LLR} for @code{long long _Fract} and
-@code{_Sat long long _Fract}
-@item @samp{uhr} or @samp{UHR} for @code{unsigned short _Fract} and
-@code{_Sat unsigned short _Fract}
-@item @samp{ur} or @samp{UR} for @code{unsigned _Fract} and
-@code{_Sat unsigned _Fract}
-@item @samp{ulr} or @samp{ULR} for @code{unsigned long _Fract} and
-@code{_Sat unsigned long _Fract}
-@item @samp{ullr} or @samp{ULLR} for @code{unsigned long long _Fract}
-and @code{_Sat unsigned long long _Fract}
-@item @samp{hk} or @samp{HK} for @code{short _Accum} and
-@code{_Sat short _Accum}
-@item @samp{k} or @samp{K} for @code{_Accum} and @code{_Sat _Accum}
-@item @samp{lk} or @samp{LK} for @code{long _Accum} and
-@code{_Sat long _Accum}
-@item @samp{llk} or @samp{LLK} for @code{long long _Accum} and
-@code{_Sat long long _Accum}
-@item @samp{uhk} or @samp{UHK} for @code{unsigned short _Accum} and
-@code{_Sat unsigned short _Accum}
-@item @samp{uk} or @samp{UK} for @code{unsigned _Accum} and
-@code{_Sat unsigned _Accum}
-@item @samp{ulk} or @samp{ULK} for @code{unsigned long _Accum} and
-@code{_Sat unsigned long _Accum}
-@item @samp{ullk} or @samp{ULLK} for @code{unsigned long long _Accum}
-and @code{_Sat unsigned long long _Accum}
-@end itemize
-
-GCC support of fixed-point types as specified by the draft technical report
-is incomplete:
-
-@itemize @bullet
-@item
-Pragmas to control overflow and rounding behaviors are not implemented.
-@end itemize
-
-Fixed-point types are supported by the DWARF debug information format.
-
-@node Named Address Spaces
-@section Named Address Spaces
-@cindex Named Address Spaces
-
-As an extension, GNU C supports named address spaces as
-defined in the N1275 draft of ISO/IEC DTR 18037. Support for named
-address spaces in GCC will evolve as the draft technical report
-changes. Calling conventions for any target might also change. At
-present, only the AVR, M32C, PRU, RL78, and x86 targets support
-address spaces other than the generic address space.
-
-Address space identifiers may be used exactly like any other C type
-qualifier (e.g., @code{const} or @code{volatile}). See the N1275
-document for more details.
-
-@anchor{AVR Named Address Spaces}
-@subsection AVR Named Address Spaces
-
-On the AVR target, there are several address spaces that can be used
-in order to put read-only data into the flash memory and access that
-data by means of the special instructions @code{LPM} or @code{ELPM}
-needed to read from flash.
-
-Devices belonging to @code{avrtiny} and @code{avrxmega3} can access
-flash memory by means of @code{LD*} instructions because the flash
-memory is mapped into the RAM address space. There is @emph{no need}
-for language extensions like @code{__flash} or attribute
-@ref{AVR Variable Attributes,,@code{progmem}}.
-The default linker description files for these devices cater for that
-feature and @code{.rodata} stays in flash: The compiler just generates
-@code{LD*} instructions, and the linker script adds core specific
-offsets to all @code{.rodata} symbols: @code{0x4000} in the case of
-@code{avrtiny} and @code{0x8000} in the case of @code{avrxmega3}.
-See @ref{AVR Options} for a list of respective devices.
-
-For devices not in @code{avrtiny} or @code{avrxmega3},
-any data including read-only data is located in RAM (the generic
-address space) because flash memory is not visible in the RAM address
-space. In order to locate read-only data in flash memory @emph{and}
-to generate the right instructions to access this data without
-using (inline) assembler code, special address spaces are needed.
-
-@table @code
-@item __flash
-@cindex @code{__flash} AVR Named Address Spaces
-The @code{__flash} qualifier locates data in the
-@code{.progmem.data} section. Data is read using the @code{LPM}
-instruction. Pointers to this address space are 16 bits wide.
-
-@item __flash1
-@itemx __flash2
-@itemx __flash3
-@itemx __flash4
-@itemx __flash5
-@cindex @code{__flash1} AVR Named Address Spaces
-@cindex @code{__flash2} AVR Named Address Spaces
-@cindex @code{__flash3} AVR Named Address Spaces
-@cindex @code{__flash4} AVR Named Address Spaces
-@cindex @code{__flash5} AVR Named Address Spaces
-These are 16-bit address spaces locating data in section
-@code{.progmem@var{N}.data} where @var{N} refers to
-address space @code{__flash@var{N}}.
-The compiler sets the @code{RAMPZ} segment register appropriately
-before reading data by means of the @code{ELPM} instruction.
-
-@item __memx
-@cindex @code{__memx} AVR Named Address Spaces
-This is a 24-bit address space that linearizes flash and RAM:
-If the high bit of the address is set, data is read from
-RAM using the lower two bytes as RAM address.
-If the high bit of the address is clear, data is read from flash
-with @code{RAMPZ} set according to the high byte of the address.
-@xref{AVR Built-in Functions,,@code{__builtin_avr_flash_segment}}.
-
-Objects in this address space are located in @code{.progmemx.data}.
-@end table
-
-@b{Example}
-
-@smallexample
-char my_read (const __flash char ** p)
-@{
- /* p is a pointer to RAM that points to a pointer to flash.
- The first indirection of p reads that flash pointer
- from RAM and the second indirection reads a char from this
- flash address. */
-
- return **p;
-@}
-
-/* Locate array[] in flash memory */
-const __flash int array[] = @{ 3, 5, 7, 11, 13, 17, 19 @};
-
-int i = 1;
-
-int main (void)
-@{
- /* Return 17 by reading from flash memory */
- return array[array[i]];
-@}
-@end smallexample
-
-@noindent
-For each named address space supported by avr-gcc there is an equally
-named but uppercase built-in macro defined.
-The purpose is to facilitate testing if respective address space
-support is available or not:
-
-@smallexample
-#ifdef __FLASH
-const __flash int var = 1;
-
-int read_var (void)
-@{
- return var;
-@}
-#else
-#include <avr/pgmspace.h> /* From AVR-LibC */
-
-const int var PROGMEM = 1;
-
-int read_var (void)
-@{
- return (int) pgm_read_word (&var);
-@}
-#endif /* __FLASH */
-@end smallexample
-
-@noindent
-Notice that attribute @ref{AVR Variable Attributes,,@code{progmem}}
-locates data in flash but
-accesses to these data read from generic address space, i.e.@:
-from RAM,
-so that you need special accessors like @code{pgm_read_byte}
-from @w{@uref{http://nongnu.org/avr-libc/user-manual/,AVR-LibC}}
-together with attribute @code{progmem}.
-
-@noindent
-@b{Limitations and caveats}
-
-@itemize
-@item
-Reading across the 64@tie{}KiB section boundary of
-the @code{__flash} or @code{__flash@var{N}} address spaces
-shows undefined behavior. The only address space that
-supports reading across the 64@tie{}KiB flash segment boundaries is
-@code{__memx}.
-
-@item
-If you use one of the @code{__flash@var{N}} address spaces
-you must arrange your linker script to locate the
-@code{.progmem@var{N}.data} sections according to your needs.
-
-@item
-Any data or pointers to the non-generic address spaces must
-be qualified as @code{const}, i.e.@: as read-only data.
-This still applies if the data in one of these address
-spaces like software version number or calibration lookup table are intended to
-be changed after load time by, say, a boot loader. In this case
-the right qualification is @code{const} @code{volatile} so that the compiler
-must not optimize away known values or insert them
-as immediates into operands of instructions.
-
-@item
-The following code initializes a variable @code{pfoo}
-located in static storage with a 24-bit address:
-@smallexample
-extern const __memx char foo;
-const __memx void *pfoo = &foo;
-@end smallexample
-
-@item
-On the reduced Tiny devices like ATtiny40, no address spaces are supported.
-Just use vanilla C / C++ code without overhead as outlined above.
-Attribute @code{progmem} is supported but works differently,
-see @ref{AVR Variable Attributes}.
-
-@end itemize
-
-@subsection M32C Named Address Spaces
-@cindex @code{__far} M32C Named Address Spaces
-
-On the M32C target, with the R8C and M16C CPU variants, variables
-qualified with @code{__far} are accessed using 32-bit addresses in
-order to access memory beyond the first 64@tie{}Ki bytes. If
-@code{__far} is used with the M32CM or M32C CPU variants, it has no
-effect.
-
-@subsection PRU Named Address Spaces
-@cindex @code{__regio_symbol} PRU Named Address Spaces
-
-On the PRU target, variables qualified with @code{__regio_symbol} are
-aliases used to access the special I/O CPU registers. They must be
-declared as @code{extern} because such variables will not be allocated in
-any data memory. They must also be marked as @code{volatile}, and can
-only be 32-bit integer types. The only names those variables can have
-are @code{__R30} and @code{__R31}, representing respectively the
-@code{R30} and @code{R31} special I/O CPU registers. Hence the following
-example is the only valid usage of @code{__regio_symbol}:
-
-@smallexample
-extern volatile __regio_symbol uint32_t __R30;
-extern volatile __regio_symbol uint32_t __R31;
-@end smallexample
-
-@subsection RL78 Named Address Spaces
-@cindex @code{__far} RL78 Named Address Spaces
-
-On the RL78 target, variables qualified with @code{__far} are accessed
-with 32-bit pointers (20-bit addresses) rather than the default 16-bit
-addresses. Non-far variables are assumed to appear in the topmost
-64@tie{}KiB of the address space.
-
-@subsection x86 Named Address Spaces
-@cindex x86 named address spaces
-
-On the x86 target, variables may be declared as being relative
-to the @code{%fs} or @code{%gs} segments.
-
-@table @code
-@item __seg_fs
-@itemx __seg_gs
-@cindex @code{__seg_fs} x86 named address space
-@cindex @code{__seg_gs} x86 named address space
-The object is accessed with the respective segment override prefix.
-
-The respective segment base must be set via some method specific to
-the operating system. Rather than require an expensive system call
-to retrieve the segment base, these address spaces are not considered
-to be subspaces of the generic (flat) address space. This means that
-explicit casts are required to convert pointers between these address
-spaces and the generic address space. In practice the application
-should cast to @code{uintptr_t} and apply the segment base offset
-that it installed previously.
-
-The preprocessor symbols @code{__SEG_FS} and @code{__SEG_GS} are
-defined when these address spaces are supported.
-@end table
-
-@node Zero Length
-@section Arrays of Length Zero
-@cindex arrays of length zero
-@cindex zero-length arrays
-@cindex length-zero arrays
-@cindex flexible array members
-
-Declaring zero-length arrays is allowed in GNU C as an extension.
-A zero-length array can be useful as the last element of a structure
-that is really a header for a variable-length object:
-
-@smallexample
-struct line @{
- int length;
- char contents[0];
-@};
-
-struct line *thisline = (struct line *)
- malloc (sizeof (struct line) + this_length);
-thisline->length = this_length;
-@end smallexample
-
-Although the size of a zero-length array is zero, an array member of
-this kind may increase the size of the enclosing type as a result of tail
-padding. The offset of a zero-length array member from the beginning
-of the enclosing structure is the same as the offset of an array with
-one or more elements of the same type. The alignment of a zero-length
-array is the same as the alignment of its elements.
-
-Declaring zero-length arrays in other contexts, including as interior
-members of structure objects or as non-member objects, is discouraged.
-Accessing elements of zero-length arrays declared in such contexts is
-undefined and may be diagnosed.
-
-In the absence of the zero-length array extension, in ISO C90
-the @code{contents} array in the example above would typically be declared
-to have a single element. Unlike a zero-length array which only contributes
-to the size of the enclosing structure for the purposes of alignment,
-a one-element array always occupies at least as much space as a single
-object of the type. Although using one-element arrays this way is
-discouraged, GCC handles accesses to trailing one-element array members
-analogously to zero-length arrays.
-
-The preferred mechanism to declare variable-length types like
-@code{struct line} above is the ISO C99 @dfn{flexible array member},
-with slightly different syntax and semantics:
-
-@itemize @bullet
-@item
-Flexible array members are written as @code{contents[]} without
-the @code{0}.
-
-@item
-Flexible array members have incomplete type, and so the @code{sizeof}
-operator may not be applied. As a quirk of the original implementation
-of zero-length arrays, @code{sizeof} evaluates to zero.
-
-@item
-Flexible array members may only appear as the last member of a
-@code{struct} that is otherwise non-empty.
-
-@item
-A structure containing a flexible array member, or a union containing
-such a structure (possibly recursively), may not be a member of a
-structure or an element of an array. (However, these uses are
-permitted by GCC as extensions.)
-@end itemize
-
-Non-empty initialization of zero-length
-arrays is treated like any case where there are more initializer
-elements than the array holds, in that a suitable warning about ``excess
-elements in array'' is given, and the excess elements (all of them, in
-this case) are ignored.
-
-GCC allows static initialization of flexible array members.
-This is equivalent to defining a new structure containing the original
-structure followed by an array of sufficient size to contain the data.
-E.g.@: in the following, @code{f1} is constructed as if it were declared
-like @code{f2}.
-
-@smallexample
-struct f1 @{
- int x; int y[];
-@} f1 = @{ 1, @{ 2, 3, 4 @} @};
-
-struct f2 @{
- struct f1 f1; int data[3];
-@} f2 = @{ @{ 1 @}, @{ 2, 3, 4 @} @};
-@end smallexample
-
-@noindent
-The convenience of this extension is that @code{f1} has the desired
-type, eliminating the need to consistently refer to @code{f2.f1}.
-
-This has symmetry with normal static arrays, in that an array of
-unknown size is also written with @code{[]}.
-
-Of course, this extension only makes sense if the extra data comes at
-the end of a top-level object, as otherwise we would be overwriting
-data at subsequent offsets. To avoid undue complication and confusion
-with initialization of deeply nested arrays, we simply disallow any
-non-empty initialization except when the structure is the top-level
-object. For example:
-
-@smallexample
-struct foo @{ int x; int y[]; @};
-struct bar @{ struct foo z; @};
-
-struct foo a = @{ 1, @{ 2, 3, 4 @} @}; // @r{Valid.}
-struct bar b = @{ @{ 1, @{ 2, 3, 4 @} @} @}; // @r{Invalid.}
-struct bar c = @{ @{ 1, @{ @} @} @}; // @r{Valid.}
-struct foo d[1] = @{ @{ 1, @{ 2, 3, 4 @} @} @}; // @r{Invalid.}
-@end smallexample
-
-@node Empty Structures
-@section Structures with No Members
-@cindex empty structures
-@cindex zero-size structures
-
-GCC permits a C structure to have no members:
-
-@smallexample
-struct empty @{
-@};
-@end smallexample
-
-The structure has size zero. In C++, empty structures are part
-of the language. G++ treats empty structures as if they had a single
-member of type @code{char}.
-
-@node Variable Length
-@section Arrays of Variable Length
-@cindex variable-length arrays
-@cindex arrays of variable length
-@cindex VLAs
-
-Variable-length automatic arrays are allowed in ISO C99, and as an
-extension GCC accepts them in C90 mode and in C++. These arrays are
-declared like any other automatic arrays, but with a length that is not
-a constant expression. The storage is allocated at the point of
-declaration and deallocated when the block scope containing the declaration
-exits. For
-example:
-
-@smallexample
-FILE *
-concat_fopen (char *s1, char *s2, char *mode)
-@{
- char str[strlen (s1) + strlen (s2) + 1];
- strcpy (str, s1);
- strcat (str, s2);
- return fopen (str, mode);
-@}
-@end smallexample
-
-@cindex scope of a variable length array
-@cindex variable-length array scope
-@cindex deallocating variable length arrays
-Jumping or breaking out of the scope of the array name deallocates the
-storage. Jumping into the scope is not allowed; you get an error
-message for it.
-
-@cindex variable-length array in a structure
-As an extension, GCC accepts variable-length arrays as a member of
-a structure or a union. For example:
-
-@smallexample
-void
-foo (int n)
-@{
- struct S @{ int x[n]; @};
-@}
-@end smallexample
-
-@cindex @code{alloca} vs variable-length arrays
-You can use the function @code{alloca} to get an effect much like
-variable-length arrays. The function @code{alloca} is available in
-many other C implementations (but not in all). On the other hand,
-variable-length arrays are more elegant.
-
-There are other differences between these two methods. Space allocated
-with @code{alloca} exists until the containing @emph{function} returns.
-The space for a variable-length array is deallocated as soon as the array
-name's scope ends, unless you also use @code{alloca} in this scope.
-
-You can also use variable-length arrays as arguments to functions:
-
-@smallexample
-struct entry
-tester (int len, char data[len][len])
-@{
- /* @r{@dots{}} */
-@}
-@end smallexample
-
-The length of an array is computed once when the storage is allocated
-and is remembered for the scope of the array in case you access it with
-@code{sizeof}.
-
-If you want to pass the array first and the length afterward, you can
-use a forward declaration in the parameter list---another GNU extension.
-
-@smallexample
-struct entry
-tester (int len; char data[len][len], int len)
-@{
- /* @r{@dots{}} */
-@}
-@end smallexample
-
-@cindex parameter forward declaration
-The @samp{int len} before the semicolon is a @dfn{parameter forward
-declaration}, and it serves the purpose of making the name @code{len}
-known when the declaration of @code{data} is parsed.
-
-You can write any number of such parameter forward declarations in the
-parameter list. They can be separated by commas or semicolons, but the
-last one must end with a semicolon, which is followed by the ``real''
-parameter declarations. Each forward declaration must match a ``real''
-declaration in parameter name and data type. ISO C99 does not support
-parameter forward declarations.
-
-@node Variadic Macros
-@section Macros with a Variable Number of Arguments.
-@cindex variable number of arguments
-@cindex macro with variable arguments
-@cindex rest argument (in macro)
-@cindex variadic macros
-
-In the ISO C standard of 1999, a macro can be declared to accept a
-variable number of arguments much as a function can. The syntax for
-defining the macro is similar to that of a function. Here is an
-example:
-
-@smallexample
-#define debug(format, ...) fprintf (stderr, format, __VA_ARGS__)
-@end smallexample
-
-@noindent
-Here @samp{@dots{}} is a @dfn{variable argument}. In the invocation of
-such a macro, it represents the zero or more tokens until the closing
-parenthesis that ends the invocation, including any commas. This set of
-tokens replaces the identifier @code{__VA_ARGS__} in the macro body
-wherever it appears. See the CPP manual for more information.
-
-GCC has long supported variadic macros, and used a different syntax that
-allowed you to give a name to the variable arguments just like any other
-argument. Here is an example:
-
-@smallexample
-#define debug(format, args...) fprintf (stderr, format, args)
-@end smallexample
-
-@noindent
-This is in all ways equivalent to the ISO C example above, but arguably
-more readable and descriptive.
-
-GNU CPP has two further variadic macro extensions, and permits them to
-be used with either of the above forms of macro definition.
-
-In standard C, you are not allowed to leave the variable argument out
-entirely; but you are allowed to pass an empty argument. For example,
-this invocation is invalid in ISO C, because there is no comma after
-the string:
-
-@smallexample
-debug ("A message")
-@end smallexample
-
-GNU CPP permits you to completely omit the variable arguments in this
-way. In the above examples, the compiler would complain, though since
-the expansion of the macro still has the extra comma after the format
-string.
-
-To help solve this problem, CPP behaves specially for variable arguments
-used with the token paste operator, @samp{##}. If instead you write
-
-@smallexample
-#define debug(format, ...) fprintf (stderr, format, ## __VA_ARGS__)
-@end smallexample
-
-@noindent
-and if the variable arguments are omitted or empty, the @samp{##}
-operator causes the preprocessor to remove the comma before it. If you
-do provide some variable arguments in your macro invocation, GNU CPP
-does not complain about the paste operation and instead places the
-variable arguments after the comma. Just like any other pasted macro
-argument, these arguments are not macro expanded.
-
-@node Escaped Newlines
-@section Slightly Looser Rules for Escaped Newlines
-@cindex escaped newlines
-@cindex newlines (escaped)
-
-The preprocessor treatment of escaped newlines is more relaxed
-than that specified by the C90 standard, which requires the newline
-to immediately follow a backslash.
-GCC's implementation allows whitespace in the form
-of spaces, horizontal and vertical tabs, and form feeds between the
-backslash and the subsequent newline. The preprocessor issues a
-warning, but treats it as a valid escaped newline and combines the two
-lines to form a single logical line. This works within comments and
-tokens, as well as between tokens. Comments are @emph{not} treated as
-whitespace for the purposes of this relaxation, since they have not
-yet been replaced with spaces.
-
-@node Subscripting
-@section Non-Lvalue Arrays May Have Subscripts
-@cindex subscripting
-@cindex arrays, non-lvalue
-
-@cindex subscripting and function values
-In ISO C99, arrays that are not lvalues still decay to pointers, and
-may be subscripted, although they may not be modified or used after
-the next sequence point and the unary @samp{&} operator may not be
-applied to them. As an extension, GNU C allows such arrays to be
-subscripted in C90 mode, though otherwise they do not decay to
-pointers outside C99 mode. For example,
-this is valid in GNU C though not valid in C90:
-
-@smallexample
-@group
-struct foo @{int a[4];@};
-
-struct foo f();
-
-bar (int index)
-@{
- return f().a[index];
-@}
-@end group
-@end smallexample
-
-@node Pointer Arith
-@section Arithmetic on @code{void}- and Function-Pointers
-@cindex void pointers, arithmetic
-@cindex void, size of pointer to
-@cindex function pointers, arithmetic
-@cindex function, size of pointer to
-
-In GNU C, addition and subtraction operations are supported on pointers to
-@code{void} and on pointers to functions. This is done by treating the
-size of a @code{void} or of a function as 1.
-
-A consequence of this is that @code{sizeof} is also allowed on @code{void}
-and on function types, and returns 1.
-
-@opindex Wpointer-arith
-The option @option{-Wpointer-arith} requests a warning if these extensions
-are used.
-
-@node Variadic Pointer Args
-@section Pointer Arguments in Variadic Functions
-@cindex pointer arguments in variadic functions
-@cindex variadic functions, pointer arguments
-
-Standard C requires that pointer types used with @code{va_arg} in
-functions with variable argument lists either must be compatible with
-that of the actual argument, or that one type must be a pointer to
-@code{void} and the other a pointer to a character type. GNU C
-implements the POSIX XSI extension that additionally permits the use
-of @code{va_arg} with a pointer type to receive arguments of any other
-pointer type.
-
-In particular, in GNU C @samp{va_arg (ap, void *)} can safely be used
-to consume an argument of any pointer type.
-
-@node Pointers to Arrays
-@section Pointers to Arrays with Qualifiers Work as Expected
-@cindex pointers to arrays
-@cindex const qualifier
-
-In GNU C, pointers to arrays with qualifiers work similar to pointers
-to other qualified types. For example, a value of type @code{int (*)[5]}
-can be used to initialize a variable of type @code{const int (*)[5]}.
-These types are incompatible in ISO C because the @code{const} qualifier
-is formally attached to the element type of the array and not the
-array itself.
-
-@smallexample
-extern void
-transpose (int N, int M, double out[M][N], const double in[N][M]);
-double x[3][2];
-double y[2][3];
-@r{@dots{}}
-transpose(3, 2, y, x);
-@end smallexample
-
-@node Initializers
-@section Non-Constant Initializers
-@cindex initializers, non-constant
-@cindex non-constant initializers
-
-As in standard C++ and ISO C99, the elements of an aggregate initializer for an
-automatic variable are not required to be constant expressions in GNU C@.
-Here is an example of an initializer with run-time varying elements:
-
-@smallexample
-foo (float f, float g)
-@{
- float beat_freqs[2] = @{ f-g, f+g @};
- /* @r{@dots{}} */
-@}
-@end smallexample
-
-@node Compound Literals
-@section Compound Literals
-@cindex constructor expressions
-@cindex initializations in expressions
-@cindex structures, constructor expression
-@cindex expressions, constructor
-@cindex compound literals
-@c The GNU C name for what C99 calls compound literals was "constructor expressions".
-
-A compound literal looks like a cast of a brace-enclosed aggregate
-initializer list. Its value is an object of the type specified in
-the cast, containing the elements specified in the initializer.
-Unlike the result of a cast, a compound literal is an lvalue. ISO
-C99 and later support compound literals. As an extension, GCC
-supports compound literals also in C90 mode and in C++, although
-as explained below, the C++ semantics are somewhat different.
-
-Usually, the specified type of a compound literal is a structure. Assume
-that @code{struct foo} and @code{structure} are declared as shown:
-
-@smallexample
-struct foo @{int a; char b[2];@} structure;
-@end smallexample
-
-@noindent
-Here is an example of constructing a @code{struct foo} with a compound literal:
-
-@smallexample
-structure = ((struct foo) @{x + y, 'a', 0@});
-@end smallexample
-
-@noindent
-This is equivalent to writing the following:
-
-@smallexample
-@{
- struct foo temp = @{x + y, 'a', 0@};
- structure = temp;
-@}
-@end smallexample
-
-You can also construct an array, though this is dangerous in C++, as
-explained below. If all the elements of the compound literal are
-(made up of) simple constant expressions suitable for use in
-initializers of objects of static storage duration, then the compound
-literal can be coerced to a pointer to its first element and used in
-such an initializer, as shown here:
-
-@smallexample
-char **foo = (char *[]) @{ "x", "y", "z" @};
-@end smallexample
-
-Compound literals for scalar types and union types are also allowed. In
-the following example the variable @code{i} is initialized to the value
-@code{2}, the result of incrementing the unnamed object created by
-the compound literal.
-
-@smallexample
-int i = ++(int) @{ 1 @};
-@end smallexample
-
-As a GNU extension, GCC allows initialization of objects with static storage
-duration by compound literals (which is not possible in ISO C99 because
-the initializer is not a constant).
-It is handled as if the object were initialized only with the brace-enclosed
-list if the types of the compound literal and the object match.
-The elements of the compound literal must be constant.
-If the object being initialized has array type of unknown size, the size is
-determined by the size of the compound literal.
-
-@smallexample
-static struct foo x = (struct foo) @{1, 'a', 'b'@};
-static int y[] = (int []) @{1, 2, 3@};
-static int z[] = (int [3]) @{1@};
-@end smallexample
-
-@noindent
-The above lines are equivalent to the following:
-@smallexample
-static struct foo x = @{1, 'a', 'b'@};
-static int y[] = @{1, 2, 3@};
-static int z[] = @{1, 0, 0@};
-@end smallexample
-
-In C, a compound literal designates an unnamed object with static or
-automatic storage duration. In C++, a compound literal designates a
-temporary object that only lives until the end of its full-expression.
-As a result, well-defined C code that takes the address of a subobject
-of a compound literal can be undefined in C++, so G++ rejects
-the conversion of a temporary array to a pointer. For instance, if
-the array compound literal example above appeared inside a function,
-any subsequent use of @code{foo} in C++ would have undefined behavior
-because the lifetime of the array ends after the declaration of @code{foo}.
-
-As an optimization, G++ sometimes gives array compound literals longer
-lifetimes: when the array either appears outside a function or has
-a @code{const}-qualified type. If @code{foo} and its initializer had
-elements of type @code{char *const} rather than @code{char *}, or if
-@code{foo} were a global variable, the array would have static storage
-duration. But it is probably safest just to avoid the use of array
-compound literals in C++ code.
-
-@node Designated Inits
-@section Designated Initializers
-@cindex initializers with labeled elements
-@cindex labeled elements in initializers
-@cindex case labels in initializers
-@cindex designated initializers
-
-Standard C90 requires the elements of an initializer to appear in a fixed
-order, the same as the order of the elements in the array or structure
-being initialized.
-
-In ISO C99 you can give the elements in any order, specifying the array
-indices or structure field names they apply to, and GNU C allows this as
-an extension in C90 mode as well. This extension is not
-implemented in GNU C++.
-
-To specify an array index, write
-@samp{[@var{index}] =} before the element value. For example,
-
-@smallexample
-int a[6] = @{ [4] = 29, [2] = 15 @};
-@end smallexample
-
-@noindent
-is equivalent to
-
-@smallexample
-int a[6] = @{ 0, 0, 15, 0, 29, 0 @};
-@end smallexample
-
-@noindent
-The index values must be constant expressions, even if the array being
-initialized is automatic.
-
-An alternative syntax for this that has been obsolete since GCC 2.5 but
-GCC still accepts is to write @samp{[@var{index}]} before the element
-value, with no @samp{=}.
-
-To initialize a range of elements to the same value, write
-@samp{[@var{first} ... @var{last}] = @var{value}}. This is a GNU
-extension. For example,
-
-@smallexample
-int widths[] = @{ [0 ... 9] = 1, [10 ... 99] = 2, [100] = 3 @};
-@end smallexample
-
-@noindent
-If the value in it has side effects, the side effects happen only once,
-not for each initialized field by the range initializer.
-
-@noindent
-Note that the length of the array is the highest value specified
-plus one.
-
-In a structure initializer, specify the name of a field to initialize
-with @samp{.@var{fieldname} =} before the element value. For example,
-given the following structure,
-
-@smallexample
-struct point @{ int x, y; @};
-@end smallexample
-
-@noindent
-the following initialization
-
-@smallexample
-struct point p = @{ .y = yvalue, .x = xvalue @};
-@end smallexample
-
-@noindent
-is equivalent to
-
-@smallexample
-struct point p = @{ xvalue, yvalue @};
-@end smallexample
-
-Another syntax that has the same meaning, obsolete since GCC 2.5, is
-@samp{@var{fieldname}:}, as shown here:
-
-@smallexample
-struct point p = @{ y: yvalue, x: xvalue @};
-@end smallexample
-
-Omitted fields are implicitly initialized the same as for objects
-that have static storage duration.
-
-@cindex designators
-The @samp{[@var{index}]} or @samp{.@var{fieldname}} is known as a
-@dfn{designator}. You can also use a designator (or the obsolete colon
-syntax) when initializing a union, to specify which element of the union
-should be used. For example,
-
-@smallexample
-union foo @{ int i; double d; @};
-
-union foo f = @{ .d = 4 @};
-@end smallexample
-
-@noindent
-converts 4 to a @code{double} to store it in the union using
-the second element. By contrast, casting 4 to type @code{union foo}
-stores it into the union as the integer @code{i}, since it is
-an integer. @xref{Cast to Union}.
-
-You can combine this technique of naming elements with ordinary C
-initialization of successive elements. Each initializer element that
-does not have a designator applies to the next consecutive element of the
-array or structure. For example,
-
-@smallexample
-int a[6] = @{ [1] = v1, v2, [4] = v4 @};
-@end smallexample
-
-@noindent
-is equivalent to
-
-@smallexample
-int a[6] = @{ 0, v1, v2, 0, v4, 0 @};
-@end smallexample
-
-Labeling the elements of an array initializer is especially useful
-when the indices are characters or belong to an @code{enum} type.
-For example:
-
-@smallexample
-int whitespace[256]
- = @{ [' '] = 1, ['\t'] = 1, ['\h'] = 1,
- ['\f'] = 1, ['\n'] = 1, ['\r'] = 1 @};
-@end smallexample
-
-@cindex designator lists
-You can also write a series of @samp{.@var{fieldname}} and
-@samp{[@var{index}]} designators before an @samp{=} to specify a
-nested subobject to initialize; the list is taken relative to the
-subobject corresponding to the closest surrounding brace pair. For
-example, with the @samp{struct point} declaration above:
-
-@smallexample
-struct point ptarray[10] = @{ [2].y = yv2, [2].x = xv2, [0].x = xv0 @};
-@end smallexample
-
-If the same field is initialized multiple times, or overlapping
-fields of a union are initialized, the value from the last
-initialization is used. When a field of a union is itself a structure,
-the entire structure from the last field initialized is used. If any previous
-initializer has side effect, it is unspecified whether the side effect
-happens or not. Currently, GCC discards the side-effecting
-initializer expressions and issues a warning.
-
-@node Case Ranges
-@section Case Ranges
-@cindex case ranges
-@cindex ranges in case statements
-
-You can specify a range of consecutive values in a single @code{case} label,
-like this:
-
-@smallexample
-case @var{low} ... @var{high}:
-@end smallexample
-
-@noindent
-This has the same effect as the proper number of individual @code{case}
-labels, one for each integer value from @var{low} to @var{high}, inclusive.
-
-This feature is especially useful for ranges of ASCII character codes:
-
-@smallexample
-case 'A' ... 'Z':
-@end smallexample
-
-@strong{Be careful:} Write spaces around the @code{...}, for otherwise
-it may be parsed wrong when you use it with integer values. For example,
-write this:
-
-@smallexample
-case 1 ... 5:
-@end smallexample
-
-@noindent
-rather than this:
-
-@smallexample
-case 1...5:
-@end smallexample
-
-@node Cast to Union
-@section Cast to a Union Type
-@cindex cast to a union
-@cindex union, casting to a
-
-A cast to a union type is a C extension not available in C++. It looks
-just like ordinary casts with the constraint that the type specified is
-a union type. You can specify the type either with the @code{union}
-keyword or with a @code{typedef} name that refers to a union. The result
-of a cast to a union is a temporary rvalue of the union type with a member
-whose type matches that of the operand initialized to the value of
-the operand. The effect of a cast to a union is similar to a compound
-literal except that it yields an rvalue like standard casts do.
-@xref{Compound Literals}.
-
-Expressions that may be cast to the union type are those whose type matches
-at least one of the members of the union. Thus, given the following union
-and variables:
-
-@smallexample
-union foo @{ int i; double d; @};
-int x;
-double y;
-union foo z;
-@end smallexample
-
-@noindent
-both @code{x} and @code{y} can be cast to type @code{union foo} and
-the following assignments
-@smallexample
- z = (union foo) x;
- z = (union foo) y;
-@end smallexample
-are shorthand equivalents of these
-@smallexample
- z = (union foo) @{ .i = x @};
- z = (union foo) @{ .d = y @};
-@end smallexample
-
-However, @code{(union foo) FLT_MAX;} is not a valid cast because the union
-has no member of type @code{float}.
-
-Using the cast as the right-hand side of an assignment to a variable of
-union type is equivalent to storing in a member of the union with
-the same type
-
-@smallexample
-union foo u;
-/* @r{@dots{}} */
-u = (union foo) x @equiv{} u.i = x
-u = (union foo) y @equiv{} u.d = y
-@end smallexample
-
-You can also use the union cast as a function argument:
-
-@smallexample
-void hack (union foo);
-/* @r{@dots{}} */
-hack ((union foo) x);
-@end smallexample
-
-@node Mixed Labels and Declarations
-@section Mixed Declarations, Labels and Code
-@cindex mixed declarations and code
-@cindex declarations, mixed with code
-@cindex code, mixed with declarations
-
-ISO C99 and ISO C++ allow declarations and code to be freely mixed
-within compound statements. ISO C2X allows labels to be
-placed before declarations and at the end of a compound statement.
-As an extension, GNU C also allows all this in C90 mode. For example,
-you could do:
-
-@smallexample
-int i;
-/* @r{@dots{}} */
-i++;
-int j = i + 2;
-@end smallexample
-
-Each identifier is visible from where it is declared until the end of
-the enclosing block.
-
-@node Function Attributes
-@section Declaring Attributes of Functions
-@cindex function attributes
-@cindex declaring attributes of functions
-@cindex @code{volatile} applied to function
-@cindex @code{const} applied to function
-
-In GNU C and C++, you can use function attributes to specify certain
-function properties that may help the compiler optimize calls or
-check code more carefully for correctness. For example, you
-can use attributes to specify that a function never returns
-(@code{noreturn}), returns a value depending only on the values of
-its arguments (@code{const}), or has @code{printf}-style arguments
-(@code{format}).
-
-You can also use attributes to control memory placement, code
-generation options or call/return conventions within the function
-being annotated. Many of these attributes are target-specific. For
-example, many targets support attributes for defining interrupt
-handler functions, which typically must follow special register usage
-and return conventions. Such attributes are described in the subsection
-for each target. However, a considerable number of attributes are
-supported by most, if not all targets. Those are described in
-the @ref{Common Function Attributes} section.
-
-Function attributes are introduced by the @code{__attribute__} keyword
-in the declaration of a function, followed by an attribute specification
-enclosed in double parentheses. You can specify multiple attributes in
-a declaration by separating them by commas within the double parentheses
-or by immediately following one attribute specification with another.
-@xref{Attribute Syntax}, for the exact rules on attribute syntax and
-placement. Compatible attribute specifications on distinct declarations
-of the same function are merged. An attribute specification that is not
-compatible with attributes already applied to a declaration of the same
-function is ignored with a warning.
-
-Some function attributes take one or more arguments that refer to
-the function's parameters by their positions within the function parameter
-list. Such attribute arguments are referred to as @dfn{positional arguments}.
-Unless specified otherwise, positional arguments that specify properties
-of parameters with pointer types can also specify the same properties of
-the implicit C++ @code{this} argument in non-static member functions, and
-of parameters of reference to a pointer type. For ordinary functions,
-position one refers to the first parameter on the list. In C++ non-static
-member functions, position one refers to the implicit @code{this} pointer.
-The same restrictions and effects apply to function attributes used with
-ordinary functions or C++ member functions.
-
-GCC also supports attributes on
-variable declarations (@pxref{Variable Attributes}),
-labels (@pxref{Label Attributes}),
-enumerators (@pxref{Enumerator Attributes}),
-statements (@pxref{Statement Attributes}),
-types (@pxref{Type Attributes}),
-and on field declarations (for @code{tainted_args}).
-
-There is some overlap between the purposes of attributes and pragmas
-(@pxref{Pragmas,,Pragmas Accepted by GCC}). It has been
-found convenient to use @code{__attribute__} to achieve a natural
-attachment of attributes to their corresponding declarations, whereas
-@code{#pragma} is of use for compatibility with other compilers
-or constructs that do not naturally form part of the grammar.
-
-In addition to the attributes documented here,
-GCC plugins may provide their own attributes.
-
-@menu
-* Common Function Attributes::
-* AArch64 Function Attributes::
-* AMD GCN Function Attributes::
-* ARC Function Attributes::
-* ARM Function Attributes::
-* AVR Function Attributes::
-* Blackfin Function Attributes::
-* BPF Function Attributes::
-* C-SKY Function Attributes::
-* Epiphany Function Attributes::
-* H8/300 Function Attributes::
-* IA-64 Function Attributes::
-* M32C Function Attributes::
-* M32R/D Function Attributes::
-* m68k Function Attributes::
-* MCORE Function Attributes::
-* MeP Function Attributes::
-* MicroBlaze Function Attributes::
-* Microsoft Windows Function Attributes::
-* MIPS Function Attributes::
-* MSP430 Function Attributes::
-* NDS32 Function Attributes::
-* Nios II Function Attributes::
-* Nvidia PTX Function Attributes::
-* PowerPC Function Attributes::
-* RISC-V Function Attributes::
-* RL78 Function Attributes::
-* RX Function Attributes::
-* S/390 Function Attributes::
-* SH Function Attributes::
-* Symbian OS Function Attributes::
-* V850 Function Attributes::
-* Visium Function Attributes::
-* x86 Function Attributes::
-* Xstormy16 Function Attributes::
-@end menu
-
-@node Common Function Attributes
-@subsection Common Function Attributes
-
-The following attributes are supported on most targets.
-
-@table @code
-@c Keep this table alphabetized by attribute name. Treat _ as space.
-
-@item access (@var{access-mode}, @var{ref-index})
-@itemx access (@var{access-mode}, @var{ref-index}, @var{size-index})
-
-The @code{access} attribute enables the detection of invalid or unsafe
-accesses by functions to which they apply or their callers, as well as
-write-only accesses to objects that are never read from. Such accesses
-may be diagnosed by warnings such as @option{-Wstringop-overflow},
-@option{-Wuninitialized}, @option{-Wunused}, and others.
-
-The @code{access} attribute specifies that a function to whose by-reference
-arguments the attribute applies accesses the referenced object according to
-@var{access-mode}. The @var{access-mode} argument is required and must be
-one of four names: @code{read_only}, @code{read_write}, @code{write_only},
-or @code{none}. The remaining two are positional arguments.
-
-The required @var{ref-index} positional argument denotes a function
-argument of pointer (or in C++, reference) type that is subject to
-the access. The same pointer argument can be referenced by at most one
-distinct @code{access} attribute.
-
-The optional @var{size-index} positional argument denotes a function
-argument of integer type that specifies the maximum size of the access.
-The size is the number of elements of the type referenced by @var{ref-index},
-or the number of bytes when the pointer type is @code{void*}. When no
-@var{size-index} argument is specified, the pointer argument must be either
-null or point to a space that is suitably aligned and large for at least one
-object of the referenced type (this implies that a past-the-end pointer is
-not a valid argument). The actual size of the access may be less but it
-must not be more.
-
-The @code{read_only} access mode specifies that the pointer to which it
-applies is used to read the referenced object but not write to it. Unless
-the argument specifying the size of the access denoted by @var{size-index}
-is zero, the referenced object must be initialized. The mode implies
-a stronger guarantee than the @code{const} qualifier which, when cast away
-from a pointer, does not prevent the pointed-to object from being modified.
-Examples of the use of the @code{read_only} access mode is the argument to
-the @code{puts} function, or the second and third arguments to
-the @code{memcpy} function.
-
-@smallexample
-__attribute__ ((access (read_only, 1))) int puts (const char*);
-__attribute__ ((access (read_only, 2, 3))) void* memcpy (void*, const void*, size_t);
-@end smallexample
-
-The @code{read_write} access mode applies to arguments of pointer types
-without the @code{const} qualifier. It specifies that the pointer to which
-it applies is used to both read and write the referenced object. Unless
-the argument specifying the size of the access denoted by @var{size-index}
-is zero, the object referenced by the pointer must be initialized. An example
-of the use of the @code{read_write} access mode is the first argument to
-the @code{strcat} function.
-
-@smallexample
-__attribute__ ((access (read_write, 1), access (read_only, 2))) char* strcat (char*, const char*);
-@end smallexample
-
-The @code{write_only} access mode applies to arguments of pointer types
-without the @code{const} qualifier. It specifies that the pointer to which
-it applies is used to write to the referenced object but not read from it.
-The object referenced by the pointer need not be initialized. An example
-of the use of the @code{write_only} access mode is the first argument to
-the @code{strcpy} function, or the first two arguments to the @code{fgets}
-function.
-
-@smallexample
-__attribute__ ((access (write_only, 1), access (read_only, 2))) char* strcpy (char*, const char*);
-__attribute__ ((access (write_only, 1, 2), access (read_write, 3))) int fgets (char*, int, FILE*);
-@end smallexample
-
-The access mode @code{none} specifies that the pointer to which it applies
-is not used to access the referenced object at all. Unless the pointer is
-null the pointed-to object must exist and have at least the size as denoted
-by the @var{size-index} argument. When the optional @var{size-index}
-argument is omitted for an argument of @code{void*} type the actual pointer
-agument is ignored. The referenced object need not be initialized.
-The mode is intended to be used as a means to help validate the expected
-object size, for example in functions that call @code{__builtin_object_size}.
-@xref{Object Size Checking}.
-
-Note that the @code{access} attribute merely specifies how an object
-referenced by the pointer argument can be accessed; it does not imply that
-an access @strong{will} happen. Also, the @code{access} attribute does not
-imply the attribute @code{nonnull}; it may be appropriate to add both attributes
-at the declaration of a function that unconditionally manipulates a buffer via
-a pointer argument. See the @code{nonnull} attribute for more information and
-caveats.
-
-@item alias ("@var{target}")
-@cindex @code{alias} function attribute
-The @code{alias} attribute causes the declaration to be emitted as an alias
-for another symbol, which must have been previously declared with the same
-type, and for variables, also the same size and alignment. Declaring an alias
-with a different type than the target is undefined and may be diagnosed. As
-an example, the following declarations:
-
-@smallexample
-void __f () @{ /* @r{Do something.} */; @}
-void f () __attribute__ ((weak, alias ("__f")));
-@end smallexample
-
-@noindent
-define @samp{f} to be a weak alias for @samp{__f}. In C++, the mangled name
-for the target must be used. It is an error if @samp{__f} is not defined in
-the same translation unit.
-
-This attribute requires assembler and object file support,
-and may not be available on all targets.
-
-@item aligned
-@itemx aligned (@var{alignment})
-@cindex @code{aligned} function attribute
-The @code{aligned} attribute specifies a minimum alignment for
-the first instruction of the function, measured in bytes. When specified,
-@var{alignment} must be an integer constant power of 2. Specifying no
-@var{alignment} argument implies the ideal alignment for the target.
-The @code{__alignof__} operator can be used to determine what that is
-(@pxref{Alignment}). The attribute has no effect when a definition for
-the function is not provided in the same translation unit.
-
-The attribute cannot be used to decrease the alignment of a function
-previously declared with a more restrictive alignment; only to increase
-it. Attempts to do otherwise are diagnosed. Some targets specify
-a minimum default alignment for functions that is greater than 1. On
-such targets, specifying a less restrictive alignment is silently ignored.
-Using the attribute overrides the effect of the @option{-falign-functions}
-(@pxref{Optimize Options}) option for this function.
-
-Note that the effectiveness of @code{aligned} attributes may be
-limited by inherent limitations in the system linker
-and/or object file format. On some systems, the
-linker is only able to arrange for functions to be aligned up to a
-certain maximum alignment. (For some linkers, the maximum supported
-alignment may be very very small.) See your linker documentation for
-further information.
-
-The @code{aligned} attribute can also be used for variables and fields
-(@pxref{Variable Attributes}.)
-
-@item alloc_align (@var{position})
-@cindex @code{alloc_align} function attribute
-The @code{alloc_align} attribute may be applied to a function that
-returns a pointer and takes at least one argument of an integer or
-enumerated type.
-It indicates that the returned pointer is aligned on a boundary given
-by the function argument at @var{position}. Meaningful alignments are
-powers of 2 greater than one. GCC uses this information to improve
-pointer alignment analysis.
-
-The function parameter denoting the allocated alignment is specified by
-one constant integer argument whose number is the argument of the attribute.
-Argument numbering starts at one.
-
-For instance,
-
-@smallexample
-void* my_memalign (size_t, size_t) __attribute__ ((alloc_align (1)));
-@end smallexample
-
-@noindent
-declares that @code{my_memalign} returns memory with minimum alignment
-given by parameter 1.
-
-@item alloc_size (@var{position})
-@itemx alloc_size (@var{position-1}, @var{position-2})
-@cindex @code{alloc_size} function attribute
-The @code{alloc_size} attribute may be applied to a function that
-returns a pointer and takes at least one argument of an integer or
-enumerated type.
-It indicates that the returned pointer points to memory whose size is
-given by the function argument at @var{position-1}, or by the product
-of the arguments at @var{position-1} and @var{position-2}. Meaningful
-sizes are positive values less than @code{PTRDIFF_MAX}. GCC uses this
-information to improve the results of @code{__builtin_object_size}.
-
-The function parameter(s) denoting the allocated size are specified by
-one or two integer arguments supplied to the attribute. The allocated size
-is either the value of the single function argument specified or the product
-of the two function arguments specified. Argument numbering starts at
-one for ordinary functions, and at two for C++ non-static member functions.
-
-For instance,
-
-@smallexample
-void* my_calloc (size_t, size_t) __attribute__ ((alloc_size (1, 2)));
-void* my_realloc (void*, size_t) __attribute__ ((alloc_size (2)));
-@end smallexample
-
-@noindent
-declares that @code{my_calloc} returns memory of the size given by
-the product of parameter 1 and 2 and that @code{my_realloc} returns memory
-of the size given by parameter 2.
-
-@item always_inline
-@cindex @code{always_inline} function attribute
-Generally, functions are not inlined unless optimization is specified.
-For functions declared inline, this attribute inlines the function
-independent of any restrictions that otherwise apply to inlining.
-Failure to inline such a function is diagnosed as an error.
-Note that if such a function is called indirectly the compiler may
-or may not inline it depending on optimization level and a failure
-to inline an indirect call may or may not be diagnosed.
-
-@item artificial
-@cindex @code{artificial} function attribute
-This attribute is useful for small inline wrappers that if possible
-should appear during debugging as a unit. Depending on the debug
-info format it either means marking the function as artificial
-or using the caller location for all instructions within the inlined
-body.
-
-@item assume_aligned (@var{alignment})
-@itemx assume_aligned (@var{alignment}, @var{offset})
-@cindex @code{assume_aligned} function attribute
-The @code{assume_aligned} attribute may be applied to a function that
-returns a pointer. It indicates that the returned pointer is aligned
-on a boundary given by @var{alignment}. If the attribute has two
-arguments, the second argument is misalignment @var{offset}. Meaningful
-values of @var{alignment} are powers of 2 greater than one. Meaningful
-values of @var{offset} are greater than zero and less than @var{alignment}.
-
-For instance
-
-@smallexample
-void* my_alloc1 (size_t) __attribute__((assume_aligned (16)));
-void* my_alloc2 (size_t) __attribute__((assume_aligned (32, 8)));
-@end smallexample
-
-@noindent
-declares that @code{my_alloc1} returns 16-byte aligned pointers and
-that @code{my_alloc2} returns a pointer whose value modulo 32 is equal
-to 8.
-
-@item cold
-@cindex @code{cold} function attribute
-The @code{cold} attribute on functions is used to inform the compiler that
-the function is unlikely to be executed. The function is optimized for
-size rather than speed and on many targets it is placed into a special
-subsection of the text section so all cold functions appear close together,
-improving code locality of non-cold parts of program. The paths leading
-to calls of cold functions within code are marked as unlikely by the branch
-prediction mechanism. It is thus useful to mark functions used to handle
-unlikely conditions, such as @code{perror}, as cold to improve optimization
-of hot functions that do call marked functions in rare occasions.
-
-When profile feedback is available, via @option{-fprofile-use}, cold functions
-are automatically detected and this attribute is ignored.
-
-@item const
-@cindex @code{const} function attribute
-@cindex functions that have no side effects
-Calls to functions whose return value is not affected by changes to
-the observable state of the program and that have no observable effects
-on such state other than to return a value may lend themselves to
-optimizations such as common subexpression elimination. Declaring such
-functions with the @code{const} attribute allows GCC to avoid emitting
-some calls in repeated invocations of the function with the same argument
-values.
-
-For example,
-
-@smallexample
-int square (int) __attribute__ ((const));
-@end smallexample
-
-@noindent
-tells GCC that subsequent calls to function @code{square} with the same
-argument value can be replaced by the result of the first call regardless
-of the statements in between.
-
-The @code{const} attribute prohibits a function from reading objects
-that affect its return value between successive invocations. However,
-functions declared with the attribute can safely read objects that do
-not change their return value, such as non-volatile constants.
-
-The @code{const} attribute imposes greater restrictions on a function's
-definition than the similar @code{pure} attribute. Declaring the same
-function with both the @code{const} and the @code{pure} attribute is
-diagnosed. Because a const function cannot have any observable side
-effects it does not make sense for it to return @code{void}. Declaring
-such a function is diagnosed.
-
-@cindex pointer arguments
-Note that a function that has pointer arguments and examines the data
-pointed to must @emph{not} be declared @code{const} if the pointed-to
-data might change between successive invocations of the function. In
-general, since a function cannot distinguish data that might change
-from data that cannot, const functions should never take pointer or,
-in C++, reference arguments. Likewise, a function that calls a non-const
-function usually must not be const itself.
-
-@item constructor
-@itemx destructor
-@itemx constructor (@var{priority})
-@itemx destructor (@var{priority})
-@cindex @code{constructor} function attribute
-@cindex @code{destructor} function attribute
-The @code{constructor} attribute causes the function to be called
-automatically before execution enters @code{main ()}. Similarly, the
-@code{destructor} attribute causes the function to be called
-automatically after @code{main ()} completes or @code{exit ()} is
-called. Functions with these attributes are useful for
-initializing data that is used implicitly during the execution of
-the program.
-
-On some targets the attributes also accept an integer argument to
-specify a priority to control the order in which constructor and
-destructor functions are run. A constructor
-with a smaller priority number runs before a constructor with a larger
-priority number; the opposite relationship holds for destructors. Note
-that priorities 0-100 are reserved. So, if you have a constructor that
-allocates a resource and a destructor that deallocates the same
-resource, both functions typically have the same priority. The
-priorities for constructor and destructor functions are the same as
-those specified for namespace-scope C++ objects (@pxref{C++ Attributes}).
-However, at present, the order in which constructors for C++ objects
-with static storage duration and functions decorated with attribute
-@code{constructor} are invoked is unspecified. In mixed declarations,
-attribute @code{init_priority} can be used to impose a specific ordering.
-
-Using the argument forms of the @code{constructor} and @code{destructor}
-attributes on targets where the feature is not supported is rejected with
-an error.
-
-@item copy
-@itemx copy (@var{function})
-@cindex @code{copy} function attribute
-The @code{copy} attribute applies the set of attributes with which
-@var{function} has been declared to the declaration of the function
-to which the attribute is applied. The attribute is designed for
-libraries that define aliases or function resolvers that are expected
-to specify the same set of attributes as their targets. The @code{copy}
-attribute can be used with functions, variables, or types. However,
-the kind of symbol to which the attribute is applied (either function
-or variable) must match the kind of symbol to which the argument refers.
-The @code{copy} attribute copies only syntactic and semantic attributes
-but not attributes that affect a symbol's linkage or visibility such as
-@code{alias}, @code{visibility}, or @code{weak}. The @code{deprecated}
-and @code{target_clones} attribute are also not copied.
-@xref{Common Type Attributes}.
-@xref{Common Variable Attributes}.
-
-For example, the @var{StrongAlias} macro below makes use of the @code{alias}
-and @code{copy} attributes to define an alias named @var{alloc} for function
-@var{allocate} declared with attributes @var{alloc_size}, @var{malloc}, and
-@var{nothrow}. Thanks to the @code{__typeof__} operator the alias has
-the same type as the target function. As a result of the @code{copy}
-attribute the alias also shares the same attributes as the target.
-
-@smallexample
-#define StrongAlias(TargetFunc, AliasDecl) \
- extern __typeof__ (TargetFunc) AliasDecl \
- __attribute__ ((alias (#TargetFunc), copy (TargetFunc)));
-
-extern __attribute__ ((alloc_size (1), malloc, nothrow))
- void* allocate (size_t);
-StrongAlias (allocate, alloc);
-@end smallexample
-
-@item deprecated
-@itemx deprecated (@var{msg})
-@cindex @code{deprecated} function attribute
-The @code{deprecated} attribute results in a warning if the function
-is used anywhere in the source file. This is useful when identifying
-functions that are expected to be removed in a future version of a
-program. The warning also includes the location of the declaration
-of the deprecated function, to enable users to easily find further
-information about why the function is deprecated, or what they should
-do instead. Note that the warnings only occurs for uses:
-
-@smallexample
-int old_fn () __attribute__ ((deprecated));
-int old_fn ();
-int (*fn_ptr)() = old_fn;
-@end smallexample
-
-@noindent
-results in a warning on line 3 but not line 2. The optional @var{msg}
-argument, which must be a string, is printed in the warning if
-present.
-
-The @code{deprecated} attribute can also be used for variables and
-types (@pxref{Variable Attributes}, @pxref{Type Attributes}.)
-
-The message attached to the attribute is affected by the setting of
-the @option{-fmessage-length} option.
-
-@item unavailable
-@itemx unavailable (@var{msg})
-@cindex @code{unavailable} function attribute
-The @code{unavailable} attribute results in an error if the function
-is used anywhere in the source file. This is useful when identifying
-functions that have been removed from a particular variation of an
-interface. Other than emitting an error rather than a warning, the
-@code{unavailable} attribute behaves in the same manner as
-@code{deprecated}.
-
-The @code{unavailable} attribute can also be used for variables and
-types (@pxref{Variable Attributes}, @pxref{Type Attributes}.)
-
-@item error ("@var{message}")
-@itemx warning ("@var{message}")
-@cindex @code{error} function attribute
-@cindex @code{warning} function attribute
-If the @code{error} or @code{warning} attribute
-is used on a function declaration and a call to such a function
-is not eliminated through dead code elimination or other optimizations,
-an error or warning (respectively) that includes @var{message} is diagnosed.
-This is useful
-for compile-time checking, especially together with @code{__builtin_constant_p}
-and inline functions where checking the inline function arguments is not
-possible through @code{extern char [(condition) ? 1 : -1];} tricks.
-
-While it is possible to leave the function undefined and thus invoke
-a link failure (to define the function with
-a message in @code{.gnu.warning*} section),
-when using these attributes the problem is diagnosed
-earlier and with exact location of the call even in presence of inline
-functions or when not emitting debugging information.
-
-@item externally_visible
-@cindex @code{externally_visible} function attribute
-This attribute, attached to a global variable or function, nullifies
-the effect of the @option{-fwhole-program} command-line option, so the
-object remains visible outside the current compilation unit.
-
-If @option{-fwhole-program} is used together with @option{-flto} and
-@command{gold} is used as the linker plugin,
-@code{externally_visible} attributes are automatically added to functions
-(not variable yet due to a current @command{gold} issue)
-that are accessed outside of LTO objects according to resolution file
-produced by @command{gold}.
-For other linkers that cannot generate resolution file,
-explicit @code{externally_visible} attributes are still necessary.
-
-@item fd_arg
-@itemx fd_arg (@var{N})
-@cindex @code{fd_arg} function attribute
-The @code{fd_arg} attribute may be applied to a function that takes an open
-file descriptor at referenced argument @var{N}.
-
-It indicates that the passed filedescriptor must not have been closed.
-Therefore, when the analyzer is enabled with @option{-fanalyzer}, the
-analyzer may emit a @option{-Wanalyzer-fd-use-after-close} diagnostic
-if it detects a code path in which a function with this attribute is
-called with a closed file descriptor.
-
-The attribute also indicates that the file descriptor must have been checked for
-validity before usage. Therefore, analyzer may emit
-@option{-Wanalyzer-fd-use-without-check} diagnostic if it detects a code path in
-which a function with this attribute is called with a file descriptor that has
-not been checked for validity.
-
-@item fd_arg_read
-@itemx fd_arg_read (@var{N})
-@cindex @code{fd_arg_read} function attribute
-The @code{fd_arg_read} is identical to @code{fd_arg}, but with the additional
-requirement that it might read from the file descriptor, and thus, the file
-descriptor must not have been opened as write-only.
-
-The analyzer may emit a @option{-Wanalyzer-access-mode-mismatch}
-diagnostic if it detects a code path in which a function with this
-attribute is called on a file descriptor opened with @code{O_WRONLY}.
-
-@item fd_arg_write
-@itemx fd_arg_write (@var{N})
-@cindex @code{fd_arg_write} function attribute
-The @code{fd_arg_write} is identical to @code{fd_arg_read} except that the
-analyzer may emit a @option{-Wanalyzer-access-mode-mismatch} diagnostic if
-it detects a code path in which a function with this attribute is called on a
-file descriptor opened with @code{O_RDONLY}.
-
-@item flatten
-@cindex @code{flatten} function attribute
-Generally, inlining into a function is limited. For a function marked with
-this attribute, every call inside this function is inlined, if possible.
-Functions declared with attribute @code{noinline} and similar are not
-inlined. Whether the function itself is considered for inlining depends
-on its size and the current inlining parameters.
-
-@item format (@var{archetype}, @var{string-index}, @var{first-to-check})
-@cindex @code{format} function attribute
-@cindex functions with @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style arguments
-@opindex Wformat
-The @code{format} attribute specifies that a function takes @code{printf},
-@code{scanf}, @code{strftime} or @code{strfmon} style arguments that
-should be type-checked against a format string. For example, the
-declaration:
-
-@smallexample
-extern int
-my_printf (void *my_object, const char *my_format, ...)
- __attribute__ ((format (printf, 2, 3)));
-@end smallexample
-
-@noindent
-causes the compiler to check the arguments in calls to @code{my_printf}
-for consistency with the @code{printf} style format string argument
-@code{my_format}.
-
-The parameter @var{archetype} determines how the format string is
-interpreted, and should be @code{printf}, @code{scanf}, @code{strftime},
-@code{gnu_printf}, @code{gnu_scanf}, @code{gnu_strftime} or
-@code{strfmon}. (You can also use @code{__printf__},
-@code{__scanf__}, @code{__strftime__} or @code{__strfmon__}.) On
-MinGW targets, @code{ms_printf}, @code{ms_scanf}, and
-@code{ms_strftime} are also present.
-@var{archetype} values such as @code{printf} refer to the formats accepted
-by the system's C runtime library,
-while values prefixed with @samp{gnu_} always refer
-to the formats accepted by the GNU C Library. On Microsoft Windows
-targets, values prefixed with @samp{ms_} refer to the formats accepted by the
-@file{msvcrt.dll} library.
-The parameter @var{string-index}
-specifies which argument is the format string argument (starting
-from 1), while @var{first-to-check} is the number of the first
-argument to check against the format string. For functions
-where the arguments are not available to be checked (such as
-@code{vprintf}), specify the third parameter as zero. In this case the
-compiler only checks the format string for consistency. For
-@code{strftime} formats, the third parameter is required to be zero.
-Since non-static C++ methods have an implicit @code{this} argument, the
-arguments of such methods should be counted from two, not one, when
-giving values for @var{string-index} and @var{first-to-check}.
-
-In the example above, the format string (@code{my_format}) is the second
-argument of the function @code{my_print}, and the arguments to check
-start with the third argument, so the correct parameters for the format
-attribute are 2 and 3.
-
-@opindex ffreestanding
-@opindex fno-builtin
-The @code{format} attribute allows you to identify your own functions
-that take format strings as arguments, so that GCC can check the
-calls to these functions for errors. The compiler always (unless
-@option{-ffreestanding} or @option{-fno-builtin} is used) checks formats
-for the standard library functions @code{printf}, @code{fprintf},
-@code{sprintf}, @code{scanf}, @code{fscanf}, @code{sscanf}, @code{strftime},
-@code{vprintf}, @code{vfprintf} and @code{vsprintf} whenever such
-warnings are requested (using @option{-Wformat}), so there is no need to
-modify the header file @file{stdio.h}. In C99 mode, the functions
-@code{snprintf}, @code{vsnprintf}, @code{vscanf}, @code{vfscanf} and
-@code{vsscanf} are also checked. Except in strictly conforming C
-standard modes, the X/Open function @code{strfmon} is also checked as
-are @code{printf_unlocked} and @code{fprintf_unlocked}.
-@xref{C Dialect Options,,Options Controlling C Dialect}.
-
-For Objective-C dialects, @code{NSString} (or @code{__NSString__}) is
-recognized in the same context. Declarations including these format attributes
-are parsed for correct syntax, however the result of checking of such format
-strings is not yet defined, and is not carried out by this version of the
-compiler.
-
-The target may also provide additional types of format checks.
-@xref{Target Format Checks,,Format Checks Specific to Particular
-Target Machines}.
-
-@item format_arg (@var{string-index})
-@cindex @code{format_arg} function attribute
-@opindex Wformat-nonliteral
-The @code{format_arg} attribute specifies that a function takes one or
-more format strings for a @code{printf}, @code{scanf}, @code{strftime} or
-@code{strfmon} style function and modifies it (for example, to translate
-it into another language), so the result can be passed to a
-@code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style
-function (with the remaining arguments to the format function the same
-as they would have been for the unmodified string). Multiple
-@code{format_arg} attributes may be applied to the same function, each
-designating a distinct parameter as a format string. For example, the
-declaration:
-
-@smallexample
-extern char *
-my_dgettext (char *my_domain, const char *my_format)
- __attribute__ ((format_arg (2)));
-@end smallexample
-
-@noindent
-causes the compiler to check the arguments in calls to a @code{printf},
-@code{scanf}, @code{strftime} or @code{strfmon} type function, whose
-format string argument is a call to the @code{my_dgettext} function, for
-consistency with the format string argument @code{my_format}. If the
-@code{format_arg} attribute had not been specified, all the compiler
-could tell in such calls to format functions would be that the format
-string argument is not constant; this would generate a warning when
-@option{-Wformat-nonliteral} is used, but the calls could not be checked
-without the attribute.
-
-In calls to a function declared with more than one @code{format_arg}
-attribute, each with a distinct argument value, the corresponding
-actual function arguments are checked against all format strings
-designated by the attributes. This capability is designed to support
-the GNU @code{ngettext} family of functions.
-
-The parameter @var{string-index} specifies which argument is the format
-string argument (starting from one). Since non-static C++ methods have
-an implicit @code{this} argument, the arguments of such methods should
-be counted from two.
-
-The @code{format_arg} attribute allows you to identify your own
-functions that modify format strings, so that GCC can check the
-calls to @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon}
-type function whose operands are a call to one of your own function.
-The compiler always treats @code{gettext}, @code{dgettext}, and
-@code{dcgettext} in this manner except when strict ISO C support is
-requested by @option{-ansi} or an appropriate @option{-std} option, or
-@option{-ffreestanding} or @option{-fno-builtin}
-is used. @xref{C Dialect Options,,Options
-Controlling C Dialect}.
-
-For Objective-C dialects, the @code{format-arg} attribute may refer to an
-@code{NSString} reference for compatibility with the @code{format} attribute
-above.
-
-The target may also allow additional types in @code{format-arg} attributes.
-@xref{Target Format Checks,,Format Checks Specific to Particular
-Target Machines}.
-
-@item gnu_inline
-@cindex @code{gnu_inline} function attribute
-This attribute should be used with a function that is also declared
-with the @code{inline} keyword. It directs GCC to treat the function
-as if it were defined in gnu90 mode even when compiling in C99 or
-gnu99 mode.
-
-If the function is declared @code{extern}, then this definition of the
-function is used only for inlining. In no case is the function
-compiled as a standalone function, not even if you take its address
-explicitly. Such an address becomes an external reference, as if you
-had only declared the function, and had not defined it. This has
-almost the effect of a macro. The way to use this is to put a
-function definition in a header file with this attribute, and put
-another copy of the function, without @code{extern}, in a library
-file. The definition in the header file causes most calls to the
-function to be inlined. If any uses of the function remain, they
-refer to the single copy in the library. Note that the two
-definitions of the functions need not be precisely the same, although
-if they do not have the same effect your program may behave oddly.
-
-In C, if the function is neither @code{extern} nor @code{static}, then
-the function is compiled as a standalone function, as well as being
-inlined where possible.
-
-This is how GCC traditionally handled functions declared
-@code{inline}. Since ISO C99 specifies a different semantics for
-@code{inline}, this function attribute is provided as a transition
-measure and as a useful feature in its own right. This attribute is
-available in GCC 4.1.3 and later. It is available if either of the
-preprocessor macros @code{__GNUC_GNU_INLINE__} or
-@code{__GNUC_STDC_INLINE__} are defined. @xref{Inline,,An Inline
-Function is As Fast As a Macro}.
-
-In C++, this attribute does not depend on @code{extern} in any way,
-but it still requires the @code{inline} keyword to enable its special
-behavior.
-
-@item hot
-@cindex @code{hot} function attribute
-The @code{hot} attribute on a function is used to inform the compiler that
-the function is a hot spot of the compiled program. The function is
-optimized more aggressively and on many targets it is placed into a special
-subsection of the text section so all hot functions appear close together,
-improving locality.
-
-When profile feedback is available, via @option{-fprofile-use}, hot functions
-are automatically detected and this attribute is ignored.
-
-@item ifunc ("@var{resolver}")
-@cindex @code{ifunc} function attribute
-@cindex indirect functions
-@cindex functions that are dynamically resolved
-The @code{ifunc} attribute is used to mark a function as an indirect
-function using the STT_GNU_IFUNC symbol type extension to the ELF
-standard. This allows the resolution of the symbol value to be
-determined dynamically at load time, and an optimized version of the
-routine to be selected for the particular processor or other system
-characteristics determined then. To use this attribute, first define
-the implementation functions available, and a resolver function that
-returns a pointer to the selected implementation function. The
-implementation functions' declarations must match the API of the
-function being implemented. The resolver should be declared to
-be a function taking no arguments and returning a pointer to
-a function of the same type as the implementation. For example:
-
-@smallexample
-void *my_memcpy (void *dst, const void *src, size_t len)
-@{
- @dots{}
- return dst;
-@}
-
-static void * (*resolve_memcpy (void))(void *, const void *, size_t)
-@{
- return my_memcpy; // we will just always select this routine
-@}
-@end smallexample
-
-@noindent
-The exported header file declaring the function the user calls would
-contain:
-
-@smallexample
-extern void *memcpy (void *, const void *, size_t);
-@end smallexample
-
-@noindent
-allowing the user to call @code{memcpy} as a regular function, unaware of
-the actual implementation. Finally, the indirect function needs to be
-defined in the same translation unit as the resolver function:
-
-@smallexample
-void *memcpy (void *, const void *, size_t)
- __attribute__ ((ifunc ("resolve_memcpy")));
-@end smallexample
-
-In C++, the @code{ifunc} attribute takes a string that is the mangled name
-of the resolver function. A C++ resolver for a non-static member function
-of class @code{C} should be declared to return a pointer to a non-member
-function taking pointer to @code{C} as the first argument, followed by
-the same arguments as of the implementation function. G++ checks
-the signatures of the two functions and issues
-a @option{-Wattribute-alias} warning for mismatches. To suppress a warning
-for the necessary cast from a pointer to the implementation member function
-to the type of the corresponding non-member function use
-the @option{-Wno-pmf-conversions} option. For example:
-
-@smallexample
-class S
-@{
-private:
- int debug_impl (int);
- int optimized_impl (int);
-
- typedef int Func (S*, int);
-
- static Func* resolver ();
-public:
-
- int interface (int);
-@};
-
-int S::debug_impl (int) @{ /* @r{@dots{}} */ @}
-int S::optimized_impl (int) @{ /* @r{@dots{}} */ @}
-
-S::Func* S::resolver ()
-@{
- int (S::*pimpl) (int)
- = getenv ("DEBUG") ? &S::debug_impl : &S::optimized_impl;
-
- // Cast triggers -Wno-pmf-conversions.
- return reinterpret_cast<Func*>(pimpl);
-@}
-
-int S::interface (int) __attribute__ ((ifunc ("_ZN1S8resolverEv")));
-@end smallexample
-
-Indirect functions cannot be weak. Binutils version 2.20.1 or higher
-and GNU C Library version 2.11.1 are required to use this feature.
-
-@item interrupt
-@itemx interrupt_handler
-Many GCC back ends support attributes to indicate that a function is
-an interrupt handler, which tells the compiler to generate function
-entry and exit sequences that differ from those from regular
-functions. The exact syntax and behavior are target-specific;
-refer to the following subsections for details.
-
-@item leaf
-@cindex @code{leaf} function attribute
-Calls to external functions with this attribute must return to the
-current compilation unit only by return or by exception handling. In
-particular, a leaf function is not allowed to invoke callback functions
-passed to it from the current compilation unit, directly call functions
-exported by the unit, or @code{longjmp} into the unit. Leaf functions
-might still call functions from other compilation units and thus they
-are not necessarily leaf in the sense that they contain no function
-calls at all.
-
-The attribute is intended for library functions to improve dataflow
-analysis. The compiler takes the hint that any data not escaping the
-current compilation unit cannot be used or modified by the leaf
-function. For example, the @code{sin} function is a leaf function, but
-@code{qsort} is not.
-
-Note that leaf functions might indirectly run a signal handler defined
-in the current compilation unit that uses static variables. Similarly,
-when lazy symbol resolution is in effect, leaf functions might invoke
-indirect functions whose resolver function or implementation function is
-defined in the current compilation unit and uses static variables. There
-is no standard-compliant way to write such a signal handler, resolver
-function, or implementation function, and the best that you can do is to
-remove the @code{leaf} attribute or mark all such static variables
-@code{volatile}. Lastly, for ELF-based systems that support symbol
-interposition, care should be taken that functions defined in the
-current compilation unit do not unexpectedly interpose other symbols
-based on the defined standards mode and defined feature test macros;
-otherwise an inadvertent callback would be added.
-
-The attribute has no effect on functions defined within the current
-compilation unit. This is to allow easy merging of multiple compilation
-units into one, for example, by using the link-time optimization. For
-this reason the attribute is not allowed on types to annotate indirect
-calls.
-
-@item malloc
-@item malloc (@var{deallocator})
-@item malloc (@var{deallocator}, @var{ptr-index})
-@cindex @code{malloc} function attribute
-@cindex functions that behave like malloc
-Attribute @code{malloc} indicates that a function is @code{malloc}-like,
-i.e., that the pointer @var{P} returned by the function cannot alias any
-other pointer valid when the function returns, and moreover no
-pointers to valid objects occur in any storage addressed by @var{P}. In
-addition, the GCC predicts that a function with the attribute returns
-non-null in most cases.
-
-Independently, the form of the attribute with one or two arguments
-associates @code{deallocator} as a suitable deallocation function for
-pointers returned from the @code{malloc}-like function. @var{ptr-index}
-denotes the positional argument to which when the pointer is passed in
-calls to @code{deallocator} has the effect of deallocating it.
-
-Using the attribute with no arguments is designed to improve optimization
-by relying on the aliasing property it implies. Functions like @code{malloc}
-and @code{calloc} have this property because they return a pointer to
-uninitialized or zeroed-out, newly obtained storage. However, functions
-like @code{realloc} do not have this property, as they may return pointers
-to storage containing pointers to existing objects. Additionally, since
-all such functions are assumed to return null only infrequently, callers
-can be optimized based on that assumption.
-
-Associating a function with a @var{deallocator} helps detect calls to
-mismatched allocation and deallocation functions and diagnose them under
-the control of options such as @option{-Wmismatched-dealloc}. It also
-makes it possible to diagnose attempts to deallocate objects that were not
-allocated dynamically, by @option{-Wfree-nonheap-object}. To indicate
-that an allocation function both satisifies the nonaliasing property and
-has a deallocator associated with it, both the plain form of the attribute
-and the one with the @var{deallocator} argument must be used. The same
-function can be both an allocator and a deallocator. Since inlining one
-of the associated functions but not the other could result in apparent
-mismatches, this form of attribute @code{malloc} is not accepted on inline
-functions. For the same reason, using the attribute prevents both
-the allocation and deallocation functions from being expanded inline.
-
-For example, besides stating that the functions return pointers that do
-not alias any others, the following declarations make @code{fclose}
-a suitable deallocator for pointers returned from all functions except
-@code{popen}, and @code{pclose} as the only suitable deallocator for
-pointers returned from @code{popen}. The deallocator functions must
-be declared before they can be referenced in the attribute.
-
-@smallexample
-int fclose (FILE*);
-int pclose (FILE*);
-
-__attribute__ ((malloc, malloc (fclose, 1)))
- FILE* fdopen (int, const char*);
-__attribute__ ((malloc, malloc (fclose, 1)))
- FILE* fopen (const char*, const char*);
-__attribute__ ((malloc, malloc (fclose, 1)))
- FILE* fmemopen(void *, size_t, const char *);
-__attribute__ ((malloc, malloc (pclose, 1)))
- FILE* popen (const char*, const char*);
-__attribute__ ((malloc, malloc (fclose, 1)))
- FILE* tmpfile (void);
-@end smallexample
-
-The warnings guarded by @option{-fanalyzer} respect allocation and
-deallocation pairs marked with the @code{malloc}. In particular:
-
-@itemize @bullet
-
-@item
-The analyzer will emit a @option{-Wanalyzer-mismatching-deallocation}
-diagnostic if there is an execution path in which the result of an
-allocation call is passed to a different deallocator.
-
-@item
-The analyzer will emit a @option{-Wanalyzer-double-free}
-diagnostic if there is an execution path in which a value is passed
-more than once to a deallocation call.
-
-@item
-The analyzer will consider the possibility that an allocation function
-could fail and return NULL. It will emit
-@option{-Wanalyzer-possible-null-dereference} and
-@option{-Wanalyzer-possible-null-argument} diagnostics if there are
-execution paths in which an unchecked result of an allocation call is
-dereferenced or passed to a function requiring a non-null argument.
-If the allocator always returns non-null, use
-@code{__attribute__ ((returns_nonnull))} to suppress these warnings.
-For example:
-@smallexample
-char *xstrdup (const char *)
- __attribute__((malloc (free), returns_nonnull));
-@end smallexample
-
-@item
-The analyzer will emit a @option{-Wanalyzer-use-after-free}
-diagnostic if there is an execution path in which the memory passed
-by pointer to a deallocation call is used after the deallocation.
-
-@item
-The analyzer will emit a @option{-Wanalyzer-malloc-leak} diagnostic if
-there is an execution path in which the result of an allocation call
-is leaked (without being passed to the deallocation function).
-
-@item
-The analyzer will emit a @option{-Wanalyzer-free-of-non-heap} diagnostic
-if a deallocation function is used on a global or on-stack variable.
-
-@end itemize
-
-The analyzer assumes that deallocators can gracefully handle the @code{NULL}
-pointer. If this is not the case, the deallocator can be marked with
-@code{__attribute__((nonnull))} so that @option{-fanalyzer} can emit
-a @option{-Wanalyzer-possible-null-argument} diagnostic for code paths
-in which the deallocator is called with NULL.
-
-@item no_icf
-@cindex @code{no_icf} function attribute
-This function attribute prevents a functions from being merged with another
-semantically equivalent function.
-
-@item no_instrument_function
-@cindex @code{no_instrument_function} function attribute
-@opindex finstrument-functions
-@opindex p
-@opindex pg
-If any of @option{-finstrument-functions}, @option{-p}, or @option{-pg} are
-given, profiling function calls are
-generated at entry and exit of most user-compiled functions.
-Functions with this attribute are not so instrumented.
-
-@item no_profile_instrument_function
-@cindex @code{no_profile_instrument_function} function attribute
-The @code{no_profile_instrument_function} attribute on functions is used
-to inform the compiler that it should not process any profile feedback based
-optimization code instrumentation.
-
-@item no_reorder
-@cindex @code{no_reorder} function attribute
-Do not reorder functions or variables marked @code{no_reorder}
-against each other or top level assembler statements the executable.
-The actual order in the program will depend on the linker command
-line. Static variables marked like this are also not removed.
-This has a similar effect
-as the @option{-fno-toplevel-reorder} option, but only applies to the
-marked symbols.
-
-@item no_sanitize ("@var{sanitize_option}")
-@cindex @code{no_sanitize} function attribute
-The @code{no_sanitize} attribute on functions is used
-to inform the compiler that it should not do sanitization of any option
-mentioned in @var{sanitize_option}. A list of values acceptable by
-the @option{-fsanitize} option can be provided.
-
-@smallexample
-void __attribute__ ((no_sanitize ("alignment", "object-size")))
-f () @{ /* @r{Do something.} */; @}
-void __attribute__ ((no_sanitize ("alignment,object-size")))
-g () @{ /* @r{Do something.} */; @}
-@end smallexample
-
-@item no_sanitize_address
-@itemx no_address_safety_analysis
-@cindex @code{no_sanitize_address} function attribute
-The @code{no_sanitize_address} attribute on functions is used
-to inform the compiler that it should not instrument memory accesses
-in the function when compiling with the @option{-fsanitize=address} option.
-The @code{no_address_safety_analysis} is a deprecated alias of the
-@code{no_sanitize_address} attribute, new code should use
-@code{no_sanitize_address}.
-
-@item no_sanitize_thread
-@cindex @code{no_sanitize_thread} function attribute
-The @code{no_sanitize_thread} attribute on functions is used
-to inform the compiler that it should not instrument memory accesses
-in the function when compiling with the @option{-fsanitize=thread} option.
-
-@item no_sanitize_undefined
-@cindex @code{no_sanitize_undefined} function attribute
-The @code{no_sanitize_undefined} attribute on functions is used
-to inform the compiler that it should not check for undefined behavior
-in the function when compiling with the @option{-fsanitize=undefined} option.
-
-@item no_sanitize_coverage
-@cindex @code{no_sanitize_coverage} function attribute
-The @code{no_sanitize_coverage} attribute on functions is used
-to inform the compiler that it should not do coverage-guided
-fuzzing code instrumentation (@option{-fsanitize-coverage}).
-
-@item no_split_stack
-@cindex @code{no_split_stack} function attribute
-@opindex fsplit-stack
-If @option{-fsplit-stack} is given, functions have a small
-prologue which decides whether to split the stack. Functions with the
-@code{no_split_stack} attribute do not have that prologue, and thus
-may run with only a small amount of stack space available.
-
-@item no_stack_limit
-@cindex @code{no_stack_limit} function attribute
-This attribute locally overrides the @option{-fstack-limit-register}
-and @option{-fstack-limit-symbol} command-line options; it has the effect
-of disabling stack limit checking in the function it applies to.
-
-@item noclone
-@cindex @code{noclone} function attribute
-This function attribute prevents a function from being considered for
-cloning---a mechanism that produces specialized copies of functions
-and which is (currently) performed by interprocedural constant
-propagation.
-
-@item noinline
-@cindex @code{noinline} function attribute
-This function attribute prevents a function from being considered for
-inlining.
-@c Don't enumerate the optimizations by name here; we try to be
-@c future-compatible with this mechanism.
-If the function does not have side effects, there are optimizations
-other than inlining that cause function calls to be optimized away,
-although the function call is live. To keep such calls from being
-optimized away, put
-@smallexample
-asm ("");
-@end smallexample
-
-@noindent
-(@pxref{Extended Asm}) in the called function, to serve as a special
-side effect.
-
-@item noipa
-@cindex @code{noipa} function attribute
-Disable interprocedural optimizations between the function with this
-attribute and its callers, as if the body of the function is not available
-when optimizing callers and the callers are unavailable when optimizing
-the body. This attribute implies @code{noinline}, @code{noclone} and
-@code{no_icf} attributes. However, this attribute is not equivalent
-to a combination of other attributes, because its purpose is to suppress
-existing and future optimizations employing interprocedural analysis,
-including those that do not have an attribute suitable for disabling
-them individually. This attribute is supported mainly for the purpose
-of testing the compiler.
-
-@item nonnull
-@itemx nonnull (@var{arg-index}, @dots{})
-@cindex @code{nonnull} function attribute
-@cindex functions with non-null pointer arguments
-The @code{nonnull} attribute may be applied to a function that takes at
-least one argument of a pointer type. It indicates that the referenced
-arguments must be non-null pointers. For instance, the declaration:
-
-@smallexample
-extern void *
-my_memcpy (void *dest, const void *src, size_t len)
- __attribute__((nonnull (1, 2)));
-@end smallexample
-
-@noindent
-informs the compiler that, in calls to @code{my_memcpy}, arguments
-@var{dest} and @var{src} must be non-null.
-
-The attribute has an effect both on functions calls and function definitions.
-
-For function calls:
-@itemize @bullet
-@item If the compiler determines that a null pointer is
-passed in an argument slot marked as non-null, and the
-@option{-Wnonnull} option is enabled, a warning is issued.
-@xref{Warning Options}.
-@item The @option{-fisolate-erroneous-paths-attribute} option can be
-specified to have GCC transform calls with null arguments to non-null
-functions into traps. @xref{Optimize Options}.
-@item The compiler may also perform optimizations based on the
-knowledge that certain function arguments cannot be null. These
-optimizations can be disabled by the
-@option{-fno-delete-null-pointer-checks} option. @xref{Optimize Options}.
-@end itemize
-
-For function definitions:
-@itemize @bullet
-@item If the compiler determines that a function parameter that is
-marked with nonnull is compared with null, and
-@option{-Wnonnull-compare} option is enabled, a warning is issued.
-@xref{Warning Options}.
-@item The compiler may also perform optimizations based on the
-knowledge that @code{nonnul} parameters cannot be null. This can
-currently not be disabled other than by removing the nonnull
-attribute.
-@end itemize
-
-If no @var{arg-index} is given to the @code{nonnull} attribute,
-all pointer arguments are marked as non-null. To illustrate, the
-following declaration is equivalent to the previous example:
-
-@smallexample
-extern void *
-my_memcpy (void *dest, const void *src, size_t len)
- __attribute__((nonnull));
-@end smallexample
-
-@item noplt
-@cindex @code{noplt} function attribute
-The @code{noplt} attribute is the counterpart to option @option{-fno-plt}.
-Calls to functions marked with this attribute in position-independent code
-do not use the PLT.
-
-@smallexample
-@group
-/* Externally defined function foo. */
-int foo () __attribute__ ((noplt));
-
-int
-main (/* @r{@dots{}} */)
-@{
- /* @r{@dots{}} */
- foo ();
- /* @r{@dots{}} */
-@}
-@end group
-@end smallexample
-
-The @code{noplt} attribute on function @code{foo}
-tells the compiler to assume that
-the function @code{foo} is externally defined and that the call to
-@code{foo} must avoid the PLT
-in position-independent code.
-
-In position-dependent code, a few targets also convert calls to
-functions that are marked to not use the PLT to use the GOT instead.
-
-@item noreturn
-@cindex @code{noreturn} function attribute
-@cindex functions that never return
-A few standard library functions, such as @code{abort} and @code{exit},
-cannot return. GCC knows this automatically. Some programs define
-their own functions that never return. You can declare them
-@code{noreturn} to tell the compiler this fact. For example,
-
-@smallexample
-@group
-void fatal () __attribute__ ((noreturn));
-
-void
-fatal (/* @r{@dots{}} */)
-@{
- /* @r{@dots{}} */ /* @r{Print error message.} */ /* @r{@dots{}} */
- exit (1);
-@}
-@end group
-@end smallexample
-
-The @code{noreturn} keyword tells the compiler to assume that
-@code{fatal} cannot return. It can then optimize without regard to what
-would happen if @code{fatal} ever did return. This makes slightly
-better code. More importantly, it helps avoid spurious warnings of
-uninitialized variables.
-
-The @code{noreturn} keyword does not affect the exceptional path when that
-applies: a @code{noreturn}-marked function may still return to the caller
-by throwing an exception or calling @code{longjmp}.
-
-In order to preserve backtraces, GCC will never turn calls to
-@code{noreturn} functions into tail calls.
-
-Do not assume that registers saved by the calling function are
-restored before calling the @code{noreturn} function.
-
-It does not make sense for a @code{noreturn} function to have a return
-type other than @code{void}.
-
-@item nothrow
-@cindex @code{nothrow} function attribute
-The @code{nothrow} attribute is used to inform the compiler that a
-function cannot throw an exception. For example, most functions in
-the standard C library can be guaranteed not to throw an exception
-with the notable exceptions of @code{qsort} and @code{bsearch} that
-take function pointer arguments.
-
-@item optimize (@var{level}, @dots{})
-@item optimize (@var{string}, @dots{})
-@cindex @code{optimize} function attribute
-The @code{optimize} attribute is used to specify that a function is to
-be compiled with different optimization options than specified on the
-command line. The optimize attribute arguments of a function behave
-behave as if appended to the command-line.
-
-Valid arguments are constant non-negative integers and
-strings. Each numeric argument specifies an optimization @var{level}.
-Each @var{string} argument consists of one or more comma-separated
-substrings. Each substring that begins with the letter @code{O} refers
-to an optimization option such as @option{-O0} or @option{-Os}. Other
-substrings are taken as suffixes to the @code{-f} prefix jointly
-forming the name of an optimization option. @xref{Optimize Options}.
-
-@samp{#pragma GCC optimize} can be used to set optimization options
-for more than one function. @xref{Function Specific Option Pragmas},
-for details about the pragma.
-
-Providing multiple strings as arguments separated by commas to specify
-multiple options is equivalent to separating the option suffixes with
-a comma (@samp{,}) within a single string. Spaces are not permitted
-within the strings.
-
-Not every optimization option that starts with the @var{-f} prefix
-specified by the attribute necessarily has an effect on the function.
-The @code{optimize} attribute should be used for debugging purposes only.
-It is not suitable in production code.
-
-@item patchable_function_entry
-@cindex @code{patchable_function_entry} function attribute
-@cindex extra NOP instructions at the function entry point
-In case the target's text segment can be made writable at run time by
-any means, padding the function entry with a number of NOPs can be
-used to provide a universal tool for instrumentation.
-
-The @code{patchable_function_entry} function attribute can be used to
-change the number of NOPs to any desired value. The two-value syntax
-is the same as for the command-line switch
-@option{-fpatchable-function-entry=N,M}, generating @var{N} NOPs, with
-the function entry point before the @var{M}th NOP instruction.
-@var{M} defaults to 0 if omitted e.g.@: function entry point is before
-the first NOP.
-
-If patchable function entries are enabled globally using the command-line
-option @option{-fpatchable-function-entry=N,M}, then you must disable
-instrumentation on all functions that are part of the instrumentation
-framework with the attribute @code{patchable_function_entry (0)}
-to prevent recursion.
-
-@item pure
-@cindex @code{pure} function attribute
-@cindex functions that have no side effects
-
-Calls to functions that have no observable effects on the state of
-the program other than to return a value may lend themselves to optimizations
-such as common subexpression elimination. Declaring such functions with
-the @code{pure} attribute allows GCC to avoid emitting some calls in repeated
-invocations of the function with the same argument values.
-
-The @code{pure} attribute prohibits a function from modifying the state
-of the program that is observable by means other than inspecting
-the function's return value. However, functions declared with the @code{pure}
-attribute can safely read any non-volatile objects, and modify the value of
-objects in a way that does not affect their return value or the observable
-state of the program.
-
-For example,
-
-@smallexample
-int hash (char *) __attribute__ ((pure));
-@end smallexample
-
-@noindent
-tells GCC that subsequent calls to the function @code{hash} with the same
-string can be replaced by the result of the first call provided the state
-of the program observable by @code{hash}, including the contents of the array
-itself, does not change in between. Even though @code{hash} takes a non-const
-pointer argument it must not modify the array it points to, or any other object
-whose value the rest of the program may depend on. However, the caller may
-safely change the contents of the array between successive calls to
-the function (doing so disables the optimization). The restriction also
-applies to member objects referenced by the @code{this} pointer in C++
-non-static member functions.
-
-Some common examples of pure functions are @code{strlen} or @code{memcmp}.
-Interesting non-pure functions are functions with infinite loops or those
-depending on volatile memory or other system resource, that may change between
-consecutive calls (such as the standard C @code{feof} function in
-a multithreading environment).
-
-The @code{pure} attribute imposes similar but looser restrictions on
-a function's definition than the @code{const} attribute: @code{pure}
-allows the function to read any non-volatile memory, even if it changes
-in between successive invocations of the function. Declaring the same
-function with both the @code{pure} and the @code{const} attribute is
-diagnosed. Because a pure function cannot have any observable side
-effects it does not make sense for such a function to return @code{void}.
-Declaring such a function is diagnosed.
-
-@item returns_nonnull
-@cindex @code{returns_nonnull} function attribute
-The @code{returns_nonnull} attribute specifies that the function
-return value should be a non-null pointer. For instance, the declaration:
-
-@smallexample
-extern void *
-mymalloc (size_t len) __attribute__((returns_nonnull));
-@end smallexample
-
-@noindent
-lets the compiler optimize callers based on the knowledge
-that the return value will never be null.
-
-@item returns_twice
-@cindex @code{returns_twice} function attribute
-@cindex functions that return more than once
-The @code{returns_twice} attribute tells the compiler that a function may
-return more than one time. The compiler ensures that all registers
-are dead before calling such a function and emits a warning about
-the variables that may be clobbered after the second return from the
-function. Examples of such functions are @code{setjmp} and @code{vfork}.
-The @code{longjmp}-like counterpart of such function, if any, might need
-to be marked with the @code{noreturn} attribute.
-
-@item section ("@var{section-name}")
-@cindex @code{section} function attribute
-@cindex functions in arbitrary sections
-Normally, the compiler places the code it generates in the @code{text} section.
-Sometimes, however, you need additional sections, or you need certain
-particular functions to appear in special sections. The @code{section}
-attribute specifies that a function lives in a particular section.
-For example, the declaration:
-
-@smallexample
-extern void foobar (void) __attribute__ ((section ("bar")));
-@end smallexample
-
-@noindent
-puts the function @code{foobar} in the @code{bar} section.
-
-Some file formats do not support arbitrary sections so the @code{section}
-attribute is not available on all platforms.
-If you need to map the entire contents of a module to a particular
-section, consider using the facilities of the linker instead.
-
-@item sentinel
-@itemx sentinel (@var{position})
-@cindex @code{sentinel} function attribute
-This function attribute indicates that an argument in a call to the function
-is expected to be an explicit @code{NULL}. The attribute is only valid on
-variadic functions. By default, the sentinel is expected to be the last
-argument of the function call. If the optional @var{position} argument
-is specified to the attribute, the sentinel must be located at
-@var{position} counting backwards from the end of the argument list.
-
-@smallexample
-__attribute__ ((sentinel))
-is equivalent to
-__attribute__ ((sentinel(0)))
-@end smallexample
-
-The attribute is automatically set with a position of 0 for the built-in
-functions @code{execl} and @code{execlp}. The built-in function
-@code{execle} has the attribute set with a position of 1.
-
-A valid @code{NULL} in this context is defined as zero with any object
-pointer type. If your system defines the @code{NULL} macro with
-an integer type then you need to add an explicit cast. During
-installation GCC replaces the system @code{<stddef.h>} header with
-a copy that redefines NULL appropriately.
-
-The warnings for missing or incorrect sentinels are enabled with
-@option{-Wformat}.
-
-@item simd
-@itemx simd("@var{mask}")
-@cindex @code{simd} function attribute
-This attribute enables creation of one or more function versions that
-can process multiple arguments using SIMD instructions from a
-single invocation. Specifying this attribute allows compiler to
-assume that such versions are available at link time (provided
-in the same or another translation unit). Generated versions are
-target-dependent and described in the corresponding Vector ABI document. For
-x86_64 target this document can be found
-@w{@uref{https://sourceware.org/glibc/wiki/libmvec?action=AttachFile&do=view&target=VectorABI.txt,here}}.
-
-The optional argument @var{mask} may have the value
-@code{notinbranch} or @code{inbranch},
-and instructs the compiler to generate non-masked or masked
-clones correspondingly. By default, all clones are generated.
-
-If the attribute is specified and @code{#pragma omp declare simd} is
-present on a declaration and the @option{-fopenmp} or @option{-fopenmp-simd}
-switch is specified, then the attribute is ignored.
-
-@item stack_protect
-@cindex @code{stack_protect} function attribute
-This attribute adds stack protection code to the function if
-flags @option{-fstack-protector}, @option{-fstack-protector-strong}
-or @option{-fstack-protector-explicit} are set.
-
-@item no_stack_protector
-@cindex @code{no_stack_protector} function attribute
-This attribute prevents stack protection code for the function.
-
-@item target (@var{string}, @dots{})
-@cindex @code{target} function attribute
-Multiple target back ends implement the @code{target} attribute
-to specify that a function is to
-be compiled with different target options than specified on the
-command line. The original target command-line options are ignored.
-One or more strings can be provided as arguments.
-Each string consists of one or more comma-separated suffixes to
-the @code{-m} prefix jointly forming the name of a machine-dependent
-option. @xref{Submodel Options,,Machine-Dependent Options}.
-
-The @code{target} attribute can be used for instance to have a function
-compiled with a different ISA (instruction set architecture) than the
-default. @samp{#pragma GCC target} can be used to specify target-specific
-options for more than one function. @xref{Function Specific Option Pragmas},
-for details about the pragma.
-
-For instance, on an x86, you could declare one function with the
-@code{target("sse4.1,arch=core2")} attribute and another with
-@code{target("sse4a,arch=amdfam10")}. This is equivalent to
-compiling the first function with @option{-msse4.1} and
-@option{-march=core2} options, and the second function with
-@option{-msse4a} and @option{-march=amdfam10} options. It is up to you
-to make sure that a function is only invoked on a machine that
-supports the particular ISA it is compiled for (for example by using
-@code{cpuid} on x86 to determine what feature bits and architecture
-family are used).
-
-@smallexample
-int core2_func (void) __attribute__ ((__target__ ("arch=core2")));
-int sse3_func (void) __attribute__ ((__target__ ("sse3")));
-@end smallexample
-
-Providing multiple strings as arguments separated by commas to specify
-multiple options is equivalent to separating the option suffixes with
-a comma (@samp{,}) within a single string. Spaces are not permitted
-within the strings.
-
-The options supported are specific to each target; refer to @ref{x86
-Function Attributes}, @ref{PowerPC Function Attributes},
-@ref{ARM Function Attributes}, @ref{AArch64 Function Attributes},
-@ref{Nios II Function Attributes}, and @ref{S/390 Function Attributes}
-for details.
-
-@item symver ("@var{name2}@@@var{nodename}")
-@cindex @code{symver} function attribute
-On ELF targets this attribute creates a symbol version. The @var{name2} part
-of the parameter is the actual name of the symbol by which it will be
-externally referenced. The @code{nodename} portion should be the name of a
-node specified in the version script supplied to the linker when building a
-shared library. Versioned symbol must be defined and must be exported with
-default visibility.
-
-@smallexample
-__attribute__ ((__symver__ ("foo@@VERS_1"))) int
-foo_v1 (void)
-@{
-@}
-@end smallexample
-
-Will produce a @code{.symver foo_v1, foo@@VERS_1} directive in the assembler
-output.
-
-One can also define multiple version for a given symbol
-(starting from binutils 2.35).
-
-@smallexample
-__attribute__ ((__symver__ ("foo@@VERS_2"), __symver__ ("foo@@VERS_3")))
-int symver_foo_v1 (void)
-@{
-@}
-@end smallexample
-
-This example creates a symbol name @code{symver_foo_v1}
-which will be version @code{VERS_2} and @code{VERS_3} of @code{foo}.
-
-If you have an older release of binutils, then symbol alias needs to
-be used:
-
-@smallexample
-__attribute__ ((__symver__ ("foo@@VERS_2")))
-int foo_v1 (void)
-@{
- return 0;
-@}
-
-__attribute__ ((__symver__ ("foo@@VERS_3")))
-__attribute__ ((alias ("foo_v1")))
-int symver_foo_v1 (void);
-@end smallexample
-
-Finally if the parameter is @code{"@var{name2}@@@@@var{nodename}"} then in
-addition to creating a symbol version (as if
-@code{"@var{name2}@@@var{nodename}"} was used) the version will be also used
-to resolve @var{name2} by the linker.
-
-@item tainted_args
-@cindex @code{tainted_args} function attribute
-The @code{tainted_args} attribute is used to specify that a function is called
-in a way that requires sanitization of its arguments, such as a system
-call in an operating system kernel. Such a function can be considered part
-of the ``attack surface'' of the program. The attribute can be used both
-on function declarations, and on field declarations containing function
-pointers. In the latter case, any function used as an initializer of
-such a callback field will be treated as being called with tainted
-arguments.
-
-The analyzer will pay particular attention to such functions when both
-@option{-fanalyzer} and @option{-fanalyzer-checker=taint} are supplied,
-potentially issuing warnings guarded by
-@option{-Wanalyzer-tainted-allocation-size},
-@option{-Wanalyzer-tainted-array-index},
-@option{-Wanalyzer-tainted-divisor},
-@option{-Wanalyzer-tainted-offset},
-and @option{-Wanalyzer-tainted-size}.
-
-@item target_clones (@var{options})
-@cindex @code{target_clones} function attribute
-The @code{target_clones} attribute is used to specify that a function
-be cloned into multiple versions compiled with different target options
-than specified on the command line. The supported options and restrictions
-are the same as for @code{target} attribute.
-
-For instance, on an x86, you could compile a function with
-@code{target_clones("sse4.1,avx")}. GCC creates two function clones,
-one compiled with @option{-msse4.1} and another with @option{-mavx}.
-
-On a PowerPC, you can compile a function with
-@code{target_clones("cpu=power9,default")}. GCC will create two
-function clones, one compiled with @option{-mcpu=power9} and another
-with the default options. GCC must be configured to use GLIBC 2.23 or
-newer in order to use the @code{target_clones} attribute.
-
-It also creates a resolver function (see
-the @code{ifunc} attribute above) that dynamically selects a clone
-suitable for current architecture. The resolver is created only if there
-is a usage of a function with @code{target_clones} attribute.
-
-Note that any subsequent call of a function without @code{target_clone}
-from a @code{target_clone} caller will not lead to copying
-(target clone) of the called function.
-If you want to enforce such behaviour,
-we recommend declaring the calling function with the @code{flatten} attribute?
-
-@item unused
-@cindex @code{unused} function attribute
-This attribute, attached to a function, means that the function is meant
-to be possibly unused. GCC does not produce a warning for this
-function.
-
-@item used
-@cindex @code{used} function attribute
-This attribute, attached to a function, means that code must be emitted
-for the function even if it appears that the function is not referenced.
-This is useful, for example, when the function is referenced only in
-inline assembly.
-
-When applied to a member function of a C++ class template, the
-attribute also means that the function is instantiated if the
-class itself is instantiated.
-
-@item retain
-@cindex @code{retain} function attribute
-For ELF targets that support the GNU or FreeBSD OSABIs, this attribute
-will save the function from linker garbage collection. To support
-this behavior, functions that have not been placed in specific sections
-(e.g. by the @code{section} attribute, or the @code{-ffunction-sections}
-option), will be placed in new, unique sections.
-
-This additional functionality requires Binutils version 2.36 or later.
-
-@item visibility ("@var{visibility_type}")
-@cindex @code{visibility} function attribute
-This attribute affects the linkage of the declaration to which it is attached.
-It can be applied to variables (@pxref{Common Variable Attributes}) and types
-(@pxref{Common Type Attributes}) as well as functions.
-
-There are four supported @var{visibility_type} values: default,
-hidden, protected or internal visibility.
-
-@smallexample
-void __attribute__ ((visibility ("protected")))
-f () @{ /* @r{Do something.} */; @}
-int i __attribute__ ((visibility ("hidden")));
-@end smallexample
-
-The possible values of @var{visibility_type} correspond to the
-visibility settings in the ELF gABI.
-
-@table @code
-@c keep this list of visibilities in alphabetical order.
-
-@item default
-Default visibility is the normal case for the object file format.
-This value is available for the visibility attribute to override other
-options that may change the assumed visibility of entities.
-
-On ELF, default visibility means that the declaration is visible to other
-modules and, in shared libraries, means that the declared entity may be
-overridden.
-
-On Darwin, default visibility means that the declaration is visible to
-other modules.
-
-Default visibility corresponds to ``external linkage'' in the language.
-
-@item hidden
-Hidden visibility indicates that the entity declared has a new
-form of linkage, which we call ``hidden linkage''. Two
-declarations of an object with hidden linkage refer to the same object
-if they are in the same shared object.
-
-@item internal
-Internal visibility is like hidden visibility, but with additional
-processor specific semantics. Unless otherwise specified by the
-psABI, GCC defines internal visibility to mean that a function is
-@emph{never} called from another module. Compare this with hidden
-functions which, while they cannot be referenced directly by other
-modules, can be referenced indirectly via function pointers. By
-indicating that a function cannot be called from outside the module,
-GCC may for instance omit the load of a PIC register since it is known
-that the calling function loaded the correct value.
-
-@item protected
-Protected visibility is like default visibility except that it
-indicates that references within the defining module bind to the
-definition in that module. That is, the declared entity cannot be
-overridden by another module.
-
-@end table
-
-All visibilities are supported on many, but not all, ELF targets
-(supported when the assembler supports the @samp{.visibility}
-pseudo-op). Default visibility is supported everywhere. Hidden
-visibility is supported on Darwin targets.
-
-The visibility attribute should be applied only to declarations that
-would otherwise have external linkage. The attribute should be applied
-consistently, so that the same entity should not be declared with
-different settings of the attribute.
-
-In C++, the visibility attribute applies to types as well as functions
-and objects, because in C++ types have linkage. A class must not have
-greater visibility than its non-static data member types and bases,
-and class members default to the visibility of their class. Also, a
-declaration without explicit visibility is limited to the visibility
-of its type.
-
-In C++, you can mark member functions and static member variables of a
-class with the visibility attribute. This is useful if you know a
-particular method or static member variable should only be used from
-one shared object; then you can mark it hidden while the rest of the
-class has default visibility. Care must be taken to avoid breaking
-the One Definition Rule; for example, it is usually not useful to mark
-an inline method as hidden without marking the whole class as hidden.
-
-A C++ namespace declaration can also have the visibility attribute.
-
-@smallexample
-namespace nspace1 __attribute__ ((visibility ("protected")))
-@{ /* @r{Do something.} */; @}
-@end smallexample
-
-This attribute applies only to the particular namespace body, not to
-other definitions of the same namespace; it is equivalent to using
-@samp{#pragma GCC visibility} before and after the namespace
-definition (@pxref{Visibility Pragmas}).
-
-In C++, if a template argument has limited visibility, this
-restriction is implicitly propagated to the template instantiation.
-Otherwise, template instantiations and specializations default to the
-visibility of their template.
-
-If both the template and enclosing class have explicit visibility, the
-visibility from the template is used.
-
-@item warn_unused_result
-@cindex @code{warn_unused_result} function attribute
-The @code{warn_unused_result} attribute causes a warning to be emitted
-if a caller of the function with this attribute does not use its
-return value. This is useful for functions where not checking
-the result is either a security problem or always a bug, such as
-@code{realloc}.
-
-@smallexample
-int fn () __attribute__ ((warn_unused_result));
-int foo ()
-@{
- if (fn () < 0) return -1;
- fn ();
- return 0;
-@}
-@end smallexample
-
-@noindent
-results in warning on line 5.
-
-@item weak
-@cindex @code{weak} function attribute
-The @code{weak} attribute causes a declaration of an external symbol
-to be emitted as a weak symbol rather than a global. This is primarily
-useful in defining library functions that can be overridden in user code,
-though it can also be used with non-function declarations. The overriding
-symbol must have the same type as the weak symbol. In addition, if it
-designates a variable it must also have the same size and alignment as
-the weak symbol. Weak symbols are supported for ELF targets, and also
-for a.out targets when using the GNU assembler and linker.
-
-@item weakref
-@itemx weakref ("@var{target}")
-@cindex @code{weakref} function attribute
-The @code{weakref} attribute marks a declaration as a weak reference.
-Without arguments, it should be accompanied by an @code{alias} attribute
-naming the target symbol. Alternatively, @var{target} may be given as
-an argument to @code{weakref} itself, naming the target definition of
-the alias. The @var{target} must have the same type as the declaration.
-In addition, if it designates a variable it must also have the same size
-and alignment as the declaration. In either form of the declaration
-@code{weakref} implicitly marks the declared symbol as @code{weak}. Without
-a @var{target} given as an argument to @code{weakref} or to @code{alias},
-@code{weakref} is equivalent to @code{weak} (in that case the declaration
-may be @code{extern}).
-
-@smallexample
-/* Given the declaration: */
-extern int y (void);
-
-/* the following... */
-static int x (void) __attribute__ ((weakref ("y")));
-
-/* is equivalent to... */
-static int x (void) __attribute__ ((weakref, alias ("y")));
-
-/* or, alternatively, to... */
-static int x (void) __attribute__ ((weakref));
-static int x (void) __attribute__ ((alias ("y")));
-@end smallexample
-
-A weak reference is an alias that does not by itself require a
-definition to be given for the target symbol. If the target symbol is
-only referenced through weak references, then it becomes a @code{weak}
-undefined symbol. If it is directly referenced, however, then such
-strong references prevail, and a definition is required for the
-symbol, not necessarily in the same translation unit.
-
-The effect is equivalent to moving all references to the alias to a
-separate translation unit, renaming the alias to the aliased symbol,
-declaring it as weak, compiling the two separate translation units and
-performing a link with relocatable output (i.e.@: @code{ld -r}) on them.
-
-A declaration to which @code{weakref} is attached and that is associated
-with a named @code{target} must be @code{static}.
-
-@item zero_call_used_regs ("@var{choice}")
-@cindex @code{zero_call_used_regs} function attribute
-
-The @code{zero_call_used_regs} attribute causes the compiler to zero
-a subset of all call-used registers@footnote{A ``call-used'' register
-is a register whose contents can be changed by a function call;
-therefore, a caller cannot assume that the register has the same contents
-on return from the function as it had before calling the function. Such
-registers are also called ``call-clobbered'', ``caller-saved'', or
-``volatile''.} at function return.
-This is used to increase program security by either mitigating
-Return-Oriented Programming (ROP) attacks or preventing information leakage
-through registers.
-
-In order to satisfy users with different security needs and control the
-run-time overhead at the same time, the @var{choice} parameter provides a
-flexible way to choose the subset of the call-used registers to be zeroed.
-The three basic values of @var{choice} are:
-
-@itemize @bullet
-@item
-@samp{skip} doesn't zero any call-used registers.
-
-@item
-@samp{used} only zeros call-used registers that are used in the function.
-A ``used'' register is one whose content has been set or referenced in
-the function.
-
-@item
-@samp{all} zeros all call-used registers.
-@end itemize
-
-In addition to these three basic choices, it is possible to modify
-@samp{used} or @samp{all} as follows:
-
-@itemize @bullet
-@item
-Adding @samp{-gpr} restricts the zeroing to general-purpose registers.
-
-@item
-Adding @samp{-arg} restricts the zeroing to registers that can sometimes
-be used to pass function arguments. This includes all argument registers
-defined by the platform's calling conversion, regardless of whether the
-function uses those registers for function arguments or not.
-@end itemize
-
-The modifiers can be used individually or together. If they are used
-together, they must appear in the order above.
-
-The full list of @var{choice}s is therefore:
-
-@table @code
-@item skip
-doesn't zero any call-used register.
-
-@item used
-only zeros call-used registers that are used in the function.
-
-@item used-gpr
-only zeros call-used general purpose registers that are used in the function.
-
-@item used-arg
-only zeros call-used registers that are used in the function and pass arguments.
-
-@item used-gpr-arg
-only zeros call-used general purpose registers that are used in the function
-and pass arguments.
-
-@item all
-zeros all call-used registers.
-
-@item all-gpr
-zeros all call-used general purpose registers.
-
-@item all-arg
-zeros all call-used registers that pass arguments.
-
-@item all-gpr-arg
-zeros all call-used general purpose registers that pass
-arguments.
-@end table
-
-Of this list, @samp{used-arg}, @samp{used-gpr-arg}, @samp{all-arg},
-and @samp{all-gpr-arg} are mainly used for ROP mitigation.
-
-The default for the attribute is controlled by @option{-fzero-call-used-regs}.
-@end table
-
-@c This is the end of the target-independent attribute table
-
-@node AArch64 Function Attributes
-@subsection AArch64 Function Attributes
-
-The following target-specific function attributes are available for the
-AArch64 target. For the most part, these options mirror the behavior of
-similar command-line options (@pxref{AArch64 Options}), but on a
-per-function basis.
-
-@table @code
-@item general-regs-only
-@cindex @code{general-regs-only} function attribute, AArch64
-Indicates that no floating-point or Advanced SIMD registers should be
-used when generating code for this function. If the function explicitly
-uses floating-point code, then the compiler gives an error. This is
-the same behavior as that of the command-line option
-@option{-mgeneral-regs-only}.
-
-@item fix-cortex-a53-835769
-@cindex @code{fix-cortex-a53-835769} function attribute, AArch64
-Indicates that the workaround for the Cortex-A53 erratum 835769 should be
-applied to this function. To explicitly disable the workaround for this
-function specify the negated form: @code{no-fix-cortex-a53-835769}.
-This corresponds to the behavior of the command line options
-@option{-mfix-cortex-a53-835769} and @option{-mno-fix-cortex-a53-835769}.
-
-@item cmodel=
-@cindex @code{cmodel=} function attribute, AArch64
-Indicates that code should be generated for a particular code model for
-this function. The behavior and permissible arguments are the same as
-for the command line option @option{-mcmodel=}.
-
-@item strict-align
-@itemx no-strict-align
-@cindex @code{strict-align} function attribute, AArch64
-@code{strict-align} indicates that the compiler should not assume that unaligned
-memory references are handled by the system. To allow the compiler to assume
-that aligned memory references are handled by the system, the inverse attribute
-@code{no-strict-align} can be specified. The behavior is same as for the
-command-line option @option{-mstrict-align} and @option{-mno-strict-align}.
-
-@item omit-leaf-frame-pointer
-@cindex @code{omit-leaf-frame-pointer} function attribute, AArch64
-Indicates that the frame pointer should be omitted for a leaf function call.
-To keep the frame pointer, the inverse attribute
-@code{no-omit-leaf-frame-pointer} can be specified. These attributes have
-the same behavior as the command-line options @option{-momit-leaf-frame-pointer}
-and @option{-mno-omit-leaf-frame-pointer}.
-
-@item tls-dialect=
-@cindex @code{tls-dialect=} function attribute, AArch64
-Specifies the TLS dialect to use for this function. The behavior and
-permissible arguments are the same as for the command-line option
-@option{-mtls-dialect=}.
-
-@item arch=
-@cindex @code{arch=} function attribute, AArch64
-Specifies the architecture version and architectural extensions to use
-for this function. The behavior and permissible arguments are the same as
-for the @option{-march=} command-line option.
-
-@item tune=
-@cindex @code{tune=} function attribute, AArch64
-Specifies the core for which to tune the performance of this function.
-The behavior and permissible arguments are the same as for the @option{-mtune=}
-command-line option.
-
-@item cpu=
-@cindex @code{cpu=} function attribute, AArch64
-Specifies the core for which to tune the performance of this function and also
-whose architectural features to use. The behavior and valid arguments are the
-same as for the @option{-mcpu=} command-line option.
-
-@item sign-return-address
-@cindex @code{sign-return-address} function attribute, AArch64
-Select the function scope on which return address signing will be applied. The
-behavior and permissible arguments are the same as for the command-line option
-@option{-msign-return-address=}. The default value is @code{none}. This
-attribute is deprecated. The @code{branch-protection} attribute should
-be used instead.
-
-@item branch-protection
-@cindex @code{branch-protection} function attribute, AArch64
-Select the function scope on which branch protection will be applied. The
-behavior and permissible arguments are the same as for the command-line option
-@option{-mbranch-protection=}. The default value is @code{none}.
-
-@item outline-atomics
-@cindex @code{outline-atomics} function attribute, AArch64
-Enable or disable calls to out-of-line helpers to implement atomic operations.
-This corresponds to the behavior of the command line options
-@option{-moutline-atomics} and @option{-mno-outline-atomics}.
-
-@end table
-
-The above target attributes can be specified as follows:
-
-@smallexample
-__attribute__((target("@var{attr-string}")))
-int
-f (int a)
-@{
- return a + 5;
-@}
-@end smallexample
-
-where @code{@var{attr-string}} is one of the attribute strings specified above.
-
-Additionally, the architectural extension string may be specified on its
-own. This can be used to turn on and off particular architectural extensions
-without having to specify a particular architecture version or core. Example:
-
-@smallexample
-__attribute__((target("+crc+nocrypto")))
-int
-foo (int a)
-@{
- return a + 5;
-@}
-@end smallexample
-
-In this example @code{target("+crc+nocrypto")} enables the @code{crc}
-extension and disables the @code{crypto} extension for the function @code{foo}
-without modifying an existing @option{-march=} or @option{-mcpu} option.
-
-Multiple target function attributes can be specified by separating them with
-a comma. For example:
-@smallexample
-__attribute__((target("arch=armv8-a+crc+crypto,tune=cortex-a53")))
-int
-foo (int a)
-@{
- return a + 5;
-@}
-@end smallexample
-
-is valid and compiles function @code{foo} for ARMv8-A with @code{crc}
-and @code{crypto} extensions and tunes it for @code{cortex-a53}.
-
-@subsubsection Inlining rules
-Specifying target attributes on individual functions or performing link-time
-optimization across translation units compiled with different target options
-can affect function inlining rules:
-
-In particular, a caller function can inline a callee function only if the
-architectural features available to the callee are a subset of the features
-available to the caller.
-For example: A function @code{foo} compiled with @option{-march=armv8-a+crc},
-or tagged with the equivalent @code{arch=armv8-a+crc} attribute,
-can inline a function @code{bar} compiled with @option{-march=armv8-a+nocrc}
-because the all the architectural features that function @code{bar} requires
-are available to function @code{foo}. Conversely, function @code{bar} cannot
-inline function @code{foo}.
-
-Additionally inlining a function compiled with @option{-mstrict-align} into a
-function compiled without @code{-mstrict-align} is not allowed.
-However, inlining a function compiled without @option{-mstrict-align} into a
-function compiled with @option{-mstrict-align} is allowed.
-
-Note that CPU tuning options and attributes such as the @option{-mcpu=},
-@option{-mtune=} do not inhibit inlining unless the CPU specified by the
-@option{-mcpu=} option or the @code{cpu=} attribute conflicts with the
-architectural feature rules specified above.
-
-@node AMD GCN Function Attributes
-@subsection AMD GCN Function Attributes
-
-These function attributes are supported by the AMD GCN back end:
-
-@table @code
-@item amdgpu_hsa_kernel
-@cindex @code{amdgpu_hsa_kernel} function attribute, AMD GCN
-This attribute indicates that the corresponding function should be compiled as
-a kernel function, that is an entry point that can be invoked from the host
-via the HSA runtime library. By default functions are only callable only from
-other GCN functions.
-
-This attribute is implicitly applied to any function named @code{main}, using
-default parameters.
-
-Kernel functions may return an integer value, which will be written to a
-conventional place within the HSA "kernargs" region.
-
-The attribute parameters configure what values are passed into the kernel
-function by the GPU drivers, via the initial register state. Some values are
-used by the compiler, and therefore forced on. Enabling other options may
-break assumptions in the compiler and/or run-time libraries.
-
-@table @code
-@item private_segment_buffer
-Set @code{enable_sgpr_private_segment_buffer} flag. Always on (required to
-locate the stack).
-
-@item dispatch_ptr
-Set @code{enable_sgpr_dispatch_ptr} flag. Always on (required to locate the
-launch dimensions).
-
-@item queue_ptr
-Set @code{enable_sgpr_queue_ptr} flag. Always on (required to convert address
-spaces).
-
-@item kernarg_segment_ptr
-Set @code{enable_sgpr_kernarg_segment_ptr} flag. Always on (required to
-locate the kernel arguments, "kernargs").
-
-@item dispatch_id
-Set @code{enable_sgpr_dispatch_id} flag.
-
-@item flat_scratch_init
-Set @code{enable_sgpr_flat_scratch_init} flag.
-
-@item private_segment_size
-Set @code{enable_sgpr_private_segment_size} flag.
-
-@item grid_workgroup_count_X
-Set @code{enable_sgpr_grid_workgroup_count_x} flag. Always on (required to
-use OpenACC/OpenMP).
-
-@item grid_workgroup_count_Y
-Set @code{enable_sgpr_grid_workgroup_count_y} flag.
-
-@item grid_workgroup_count_Z
-Set @code{enable_sgpr_grid_workgroup_count_z} flag.
-
-@item workgroup_id_X
-Set @code{enable_sgpr_workgroup_id_x} flag.
-
-@item workgroup_id_Y
-Set @code{enable_sgpr_workgroup_id_y} flag.
-
-@item workgroup_id_Z
-Set @code{enable_sgpr_workgroup_id_z} flag.
-
-@item workgroup_info
-Set @code{enable_sgpr_workgroup_info} flag.
-
-@item private_segment_wave_offset
-Set @code{enable_sgpr_private_segment_wave_byte_offset} flag. Always on
-(required to locate the stack).
-
-@item work_item_id_X
-Set @code{enable_vgpr_workitem_id} parameter. Always on (can't be disabled).
-
-@item work_item_id_Y
-Set @code{enable_vgpr_workitem_id} parameter. Always on (required to enable
-vectorization.)
-
-@item work_item_id_Z
-Set @code{enable_vgpr_workitem_id} parameter. Always on (required to use
-OpenACC/OpenMP).
-
-@end table
-@end table
-
-@node ARC Function Attributes
-@subsection ARC Function Attributes
-
-These function attributes are supported by the ARC back end:
-
-@table @code
-@item interrupt
-@cindex @code{interrupt} function attribute, ARC
-Use this attribute to indicate
-that the specified function is an interrupt handler. The compiler generates
-function entry and exit sequences suitable for use in an interrupt handler
-when this attribute is present.
-
-On the ARC, you must specify the kind of interrupt to be handled
-in a parameter to the interrupt attribute like this:
-
-@smallexample
-void f () __attribute__ ((interrupt ("ilink1")));
-@end smallexample
-
-Permissible values for this parameter are: @w{@code{ilink1}} and
-@w{@code{ilink2}} for ARCv1 architecture, and @w{@code{ilink}} and
-@w{@code{firq}} for ARCv2 architecture.
-
-@item long_call
-@itemx medium_call
-@itemx short_call
-@cindex @code{long_call} function attribute, ARC
-@cindex @code{medium_call} function attribute, ARC
-@cindex @code{short_call} function attribute, ARC
-@cindex indirect calls, ARC
-These attributes specify how a particular function is called.
-These attributes override the
-@option{-mlong-calls} and @option{-mmedium-calls} (@pxref{ARC Options})
-command-line switches and @code{#pragma long_calls} settings.
-
-For ARC, a function marked with the @code{long_call} attribute is
-always called using register-indirect jump-and-link instructions,
-thereby enabling the called function to be placed anywhere within the
-32-bit address space. A function marked with the @code{medium_call}
-attribute will always be close enough to be called with an unconditional
-branch-and-link instruction, which has a 25-bit offset from
-the call site. A function marked with the @code{short_call}
-attribute will always be close enough to be called with a conditional
-branch-and-link instruction, which has a 21-bit offset from
-the call site.
-
-@item jli_always
-@cindex @code{jli_always} function attribute, ARC
-Forces a particular function to be called using @code{jli}
-instruction. The @code{jli} instruction makes use of a table stored
-into @code{.jlitab} section, which holds the location of the functions
-which are addressed using this instruction.
-
-@item jli_fixed
-@cindex @code{jli_fixed} function attribute, ARC
-Identical like the above one, but the location of the function in the
-@code{jli} table is known and given as an attribute parameter.
-
-@item secure_call
-@cindex @code{secure_call} function attribute, ARC
-This attribute allows one to mark secure-code functions that are
-callable from normal mode. The location of the secure call function
-into the @code{sjli} table needs to be passed as argument.
-
-@item naked
-@cindex @code{naked} function attribute, ARC
-This attribute allows the compiler to construct the requisite function
-declaration, while allowing the body of the function to be assembly
-code. The specified function will not have prologue/epilogue
-sequences generated by the compiler. Only basic @code{asm} statements
-can safely be included in naked functions (@pxref{Basic Asm}). While
-using extended @code{asm} or a mixture of basic @code{asm} and C code
-may appear to work, they cannot be depended upon to work reliably and
-are not supported.
-
-@end table
-
-@node ARM Function Attributes
-@subsection ARM Function Attributes
-
-These function attributes are supported for ARM targets:
-
-@table @code
-
-@item general-regs-only
-@cindex @code{general-regs-only} function attribute, ARM
-Indicates that no floating-point or Advanced SIMD registers should be
-used when generating code for this function. If the function explicitly
-uses floating-point code, then the compiler gives an error. This is
-the same behavior as that of the command-line option
-@option{-mgeneral-regs-only}.
-
-@item interrupt
-@cindex @code{interrupt} function attribute, ARM
-Use this attribute to indicate
-that the specified function is an interrupt handler. The compiler generates
-function entry and exit sequences suitable for use in an interrupt handler
-when this attribute is present.
-
-You can specify the kind of interrupt to be handled by
-adding an optional parameter to the interrupt attribute like this:
-
-@smallexample
-void f () __attribute__ ((interrupt ("IRQ")));
-@end smallexample
-
-@noindent
-Permissible values for this parameter are: @code{IRQ}, @code{FIQ},
-@code{SWI}, @code{ABORT} and @code{UNDEF}.
-
-On ARMv7-M the interrupt type is ignored, and the attribute means the function
-may be called with a word-aligned stack pointer.
-
-@item isr
-@cindex @code{isr} function attribute, ARM
-Use this attribute on ARM to write Interrupt Service Routines. This is an
-alias to the @code{interrupt} attribute above.
-
-@item long_call
-@itemx short_call
-@cindex @code{long_call} function attribute, ARM
-@cindex @code{short_call} function attribute, ARM
-@cindex indirect calls, ARM
-These attributes specify how a particular function is called.
-These attributes override the
-@option{-mlong-calls} (@pxref{ARM Options})
-command-line switch and @code{#pragma long_calls} settings. For ARM, the
-@code{long_call} attribute indicates that the function might be far
-away from the call site and require a different (more expensive)
-calling sequence. The @code{short_call} attribute always places
-the offset to the function from the call site into the @samp{BL}
-instruction directly.
-
-@item naked
-@cindex @code{naked} function attribute, ARM
-This attribute allows the compiler to construct the
-requisite function declaration, while allowing the body of the
-function to be assembly code. The specified function will not have
-prologue/epilogue sequences generated by the compiler. Only basic
-@code{asm} statements can safely be included in naked functions
-(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
-basic @code{asm} and C code may appear to work, they cannot be
-depended upon to work reliably and are not supported.
-
-@item pcs
-@cindex @code{pcs} function attribute, ARM
-
-The @code{pcs} attribute can be used to control the calling convention
-used for a function on ARM. The attribute takes an argument that specifies
-the calling convention to use.
-
-When compiling using the AAPCS ABI (or a variant of it) then valid
-values for the argument are @code{"aapcs"} and @code{"aapcs-vfp"}. In
-order to use a variant other than @code{"aapcs"} then the compiler must
-be permitted to use the appropriate co-processor registers (i.e., the
-VFP registers must be available in order to use @code{"aapcs-vfp"}).
-For example,
-
-@smallexample
-/* Argument passed in r0, and result returned in r0+r1. */
-double f2d (float) __attribute__((pcs("aapcs")));
-@end smallexample
-
-Variadic functions always use the @code{"aapcs"} calling convention and
-the compiler rejects attempts to specify an alternative.
-
-@item target (@var{options})
-@cindex @code{target} function attribute
-As discussed in @ref{Common Function Attributes}, this attribute
-allows specification of target-specific compilation options.
-
-On ARM, the following options are allowed:
-
-@table @samp
-@item thumb
-@cindex @code{target("thumb")} function attribute, ARM
-Force code generation in the Thumb (T16/T32) ISA, depending on the
-architecture level.
-
-@item arm
-@cindex @code{target("arm")} function attribute, ARM
-Force code generation in the ARM (A32) ISA.
-
-Functions from different modes can be inlined in the caller's mode.
-
-@item fpu=
-@cindex @code{target("fpu=")} function attribute, ARM
-Specifies the fpu for which to tune the performance of this function.
-The behavior and permissible arguments are the same as for the @option{-mfpu=}
-command-line option.
-
-@item arch=
-@cindex @code{arch=} function attribute, ARM
-Specifies the architecture version and architectural extensions to use
-for this function. The behavior and permissible arguments are the same as
-for the @option{-march=} command-line option.
-
-The above target attributes can be specified as follows:
-
-@smallexample
-__attribute__((target("arch=armv8-a+crc")))
-int
-f (int a)
-@{
- return a + 5;
-@}
-@end smallexample
-
-Additionally, the architectural extension string may be specified on its
-own. This can be used to turn on and off particular architectural extensions
-without having to specify a particular architecture version or core. Example:
-
-@smallexample
-__attribute__((target("+crc+nocrypto")))
-int
-foo (int a)
-@{
- return a + 5;
-@}
-@end smallexample
-
-In this example @code{target("+crc+nocrypto")} enables the @code{crc}
-extension and disables the @code{crypto} extension for the function @code{foo}
-without modifying an existing @option{-march=} or @option{-mcpu} option.
-
-@end table
-
-@end table
-
-@node AVR Function Attributes
-@subsection AVR Function Attributes
-
-These function attributes are supported by the AVR back end:
-
-@table @code
-@item interrupt
-@cindex @code{interrupt} function attribute, AVR
-Use this attribute to indicate
-that the specified function is an interrupt handler. The compiler generates
-function entry and exit sequences suitable for use in an interrupt handler
-when this attribute is present.
-
-On the AVR, the hardware globally disables interrupts when an
-interrupt is executed. The first instruction of an interrupt handler
-declared with this attribute is a @code{SEI} instruction to
-re-enable interrupts. See also the @code{signal} function attribute
-that does not insert a @code{SEI} instruction. If both @code{signal} and
-@code{interrupt} are specified for the same function, @code{signal}
-is silently ignored.
-
-@item naked
-@cindex @code{naked} function attribute, AVR
-This attribute allows the compiler to construct the
-requisite function declaration, while allowing the body of the
-function to be assembly code. The specified function will not have
-prologue/epilogue sequences generated by the compiler. Only basic
-@code{asm} statements can safely be included in naked functions
-(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
-basic @code{asm} and C code may appear to work, they cannot be
-depended upon to work reliably and are not supported.
-
-@item no_gccisr
-@cindex @code{no_gccisr} function attribute, AVR
-Do not use @code{__gcc_isr} pseudo instructions in a function with
-the @code{interrupt} or @code{signal} attribute aka. interrupt
-service routine (ISR).
-Use this attribute if the preamble of the ISR prologue should always read
-@example
-push __zero_reg__
-push __tmp_reg__
-in __tmp_reg__, __SREG__
-push __tmp_reg__
-clr __zero_reg__
-@end example
-and accordingly for the postamble of the epilogue --- no matter whether
-the mentioned registers are actually used in the ISR or not.
-Situations where you might want to use this attribute include:
-@itemize @bullet
-@item
-Code that (effectively) clobbers bits of @code{SREG} other than the
-@code{I}-flag by writing to the memory location of @code{SREG}.
-@item
-Code that uses inline assembler to jump to a different function which
-expects (parts of) the prologue code as outlined above to be present.
-@end itemize
-To disable @code{__gcc_isr} generation for the whole compilation unit,
-there is option @option{-mno-gas-isr-prologues}, @pxref{AVR Options}.
-
-@item OS_main
-@itemx OS_task
-@cindex @code{OS_main} function attribute, AVR
-@cindex @code{OS_task} function attribute, AVR
-On AVR, functions with the @code{OS_main} or @code{OS_task} attribute
-do not save/restore any call-saved register in their prologue/epilogue.
-
-The @code{OS_main} attribute can be used when there @emph{is
-guarantee} that interrupts are disabled at the time when the function
-is entered. This saves resources when the stack pointer has to be
-changed to set up a frame for local variables.
-
-The @code{OS_task} attribute can be used when there is @emph{no
-guarantee} that interrupts are disabled at that time when the function
-is entered like for, e@.g@. task functions in a multi-threading operating
-system. In that case, changing the stack pointer register is
-guarded by save/clear/restore of the global interrupt enable flag.
-
-The differences to the @code{naked} function attribute are:
-@itemize @bullet
-@item @code{naked} functions do not have a return instruction whereas
-@code{OS_main} and @code{OS_task} functions have a @code{RET} or
-@code{RETI} return instruction.
-@item @code{naked} functions do not set up a frame for local variables
-or a frame pointer whereas @code{OS_main} and @code{OS_task} do this
-as needed.
-@end itemize
-
-@item signal
-@cindex @code{signal} function attribute, AVR
-Use this attribute on the AVR to indicate that the specified
-function is an interrupt handler. The compiler generates function
-entry and exit sequences suitable for use in an interrupt handler when this
-attribute is present.
-
-See also the @code{interrupt} function attribute.
-
-The AVR hardware globally disables interrupts when an interrupt is executed.
-Interrupt handler functions defined with the @code{signal} attribute
-do not re-enable interrupts. It is save to enable interrupts in a
-@code{signal} handler. This ``save'' only applies to the code
-generated by the compiler and not to the IRQ layout of the
-application which is responsibility of the application.
-
-If both @code{signal} and @code{interrupt} are specified for the same
-function, @code{signal} is silently ignored.
-@end table
-
-@node Blackfin Function Attributes
-@subsection Blackfin Function Attributes
-
-These function attributes are supported by the Blackfin back end:
-
-@table @code
-
-@item exception_handler
-@cindex @code{exception_handler} function attribute
-@cindex exception handler functions, Blackfin
-Use this attribute on the Blackfin to indicate that the specified function
-is an exception handler. The compiler generates function entry and
-exit sequences suitable for use in an exception handler when this
-attribute is present.
-
-@item interrupt_handler
-@cindex @code{interrupt_handler} function attribute, Blackfin
-Use this attribute to
-indicate that the specified function is an interrupt handler. The compiler
-generates function entry and exit sequences suitable for use in an
-interrupt handler when this attribute is present.
-
-@item kspisusp
-@cindex @code{kspisusp} function attribute, Blackfin
-@cindex User stack pointer in interrupts on the Blackfin
-When used together with @code{interrupt_handler}, @code{exception_handler}
-or @code{nmi_handler}, code is generated to load the stack pointer
-from the USP register in the function prologue.
-
-@item l1_text
-@cindex @code{l1_text} function attribute, Blackfin
-This attribute specifies a function to be placed into L1 Instruction
-SRAM@. The function is put into a specific section named @code{.l1.text}.
-With @option{-mfdpic}, function calls with a such function as the callee
-or caller uses inlined PLT.
-
-@item l2
-@cindex @code{l2} function attribute, Blackfin
-This attribute specifies a function to be placed into L2
-SRAM. The function is put into a specific section named
-@code{.l2.text}. With @option{-mfdpic}, callers of such functions use
-an inlined PLT.
-
-@item longcall
-@itemx shortcall
-@cindex indirect calls, Blackfin
-@cindex @code{longcall} function attribute, Blackfin
-@cindex @code{shortcall} function attribute, Blackfin
-The @code{longcall} attribute
-indicates that the function might be far away from the call site and
-require a different (more expensive) calling sequence. The
-@code{shortcall} attribute indicates that the function is always close
-enough for the shorter calling sequence to be used. These attributes
-override the @option{-mlongcall} switch.
-
-@item nesting
-@cindex @code{nesting} function attribute, Blackfin
-@cindex Allow nesting in an interrupt handler on the Blackfin processor
-Use this attribute together with @code{interrupt_handler},
-@code{exception_handler} or @code{nmi_handler} to indicate that the function
-entry code should enable nested interrupts or exceptions.
-
-@item nmi_handler
-@cindex @code{nmi_handler} function attribute, Blackfin
-@cindex NMI handler functions on the Blackfin processor
-Use this attribute on the Blackfin to indicate that the specified function
-is an NMI handler. The compiler generates function entry and
-exit sequences suitable for use in an NMI handler when this
-attribute is present.
-
-@item saveall
-@cindex @code{saveall} function attribute, Blackfin
-@cindex save all registers on the Blackfin
-Use this attribute to indicate that
-all registers except the stack pointer should be saved in the prologue
-regardless of whether they are used or not.
-@end table
-
-@node BPF Function Attributes
-@subsection BPF Function Attributes
-
-These function attributes are supported by the BPF back end:
-
-@table @code
-@item kernel_helper
-@cindex @code{kernel helper}, function attribute, BPF
-use this attribute to indicate the specified function declaration is a
-kernel helper. The helper function is passed as an argument to the
-attribute. Example:
-
-@smallexample
-int bpf_probe_read (void *dst, int size, const void *unsafe_ptr)
- __attribute__ ((kernel_helper (4)));
-@end smallexample
-@end table
-
-@node C-SKY Function Attributes
-@subsection C-SKY Function Attributes
-
-These function attributes are supported by the C-SKY back end:
-
-@table @code
-@item interrupt
-@itemx isr
-@cindex @code{interrupt} function attribute, C-SKY
-@cindex @code{isr} function attribute, C-SKY
-Use these attributes to indicate that the specified function
-is an interrupt handler.
-The compiler generates function entry and exit sequences suitable for
-use in an interrupt handler when either of these attributes are present.
-
-Use of these options requires the @option{-mistack} command-line option
-to enable support for the necessary interrupt stack instructions. They
-are ignored with a warning otherwise. @xref{C-SKY Options}.
-
-@item naked
-@cindex @code{naked} function attribute, C-SKY
-This attribute allows the compiler to construct the
-requisite function declaration, while allowing the body of the
-function to be assembly code. The specified function will not have
-prologue/epilogue sequences generated by the compiler. Only basic
-@code{asm} statements can safely be included in naked functions
-(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
-basic @code{asm} and C code may appear to work, they cannot be
-depended upon to work reliably and are not supported.
-@end table
-
-
-@node Epiphany Function Attributes
-@subsection Epiphany Function Attributes
-
-These function attributes are supported by the Epiphany back end:
-
-@table @code
-@item disinterrupt
-@cindex @code{disinterrupt} function attribute, Epiphany
-This attribute causes the compiler to emit
-instructions to disable interrupts for the duration of the given
-function.
-
-@item forwarder_section
-@cindex @code{forwarder_section} function attribute, Epiphany
-This attribute modifies the behavior of an interrupt handler.
-The interrupt handler may be in external memory which cannot be
-reached by a branch instruction, so generate a local memory trampoline
-to transfer control. The single parameter identifies the section where
-the trampoline is placed.
-
-@item interrupt
-@cindex @code{interrupt} function attribute, Epiphany
-Use this attribute to indicate
-that the specified function is an interrupt handler. The compiler generates
-function entry and exit sequences suitable for use in an interrupt handler
-when this attribute is present. It may also generate
-a special section with code to initialize the interrupt vector table.
-
-On Epiphany targets one or more optional parameters can be added like this:
-
-@smallexample
-void __attribute__ ((interrupt ("dma0, dma1"))) universal_dma_handler ();
-@end smallexample
-
-Permissible values for these parameters are: @w{@code{reset}},
-@w{@code{software_exception}}, @w{@code{page_miss}},
-@w{@code{timer0}}, @w{@code{timer1}}, @w{@code{message}},
-@w{@code{dma0}}, @w{@code{dma1}}, @w{@code{wand}} and @w{@code{swi}}.
-Multiple parameters indicate that multiple entries in the interrupt
-vector table should be initialized for this function, i.e.@: for each
-parameter @w{@var{name}}, a jump to the function is emitted in
-the section @w{ivt_entry_@var{name}}. The parameter(s) may be omitted
-entirely, in which case no interrupt vector table entry is provided.
-
-Note that interrupts are enabled inside the function
-unless the @code{disinterrupt} attribute is also specified.
-
-The following examples are all valid uses of these attributes on
-Epiphany targets:
-@smallexample
-void __attribute__ ((interrupt)) universal_handler ();
-void __attribute__ ((interrupt ("dma1"))) dma1_handler ();
-void __attribute__ ((interrupt ("dma0, dma1")))
- universal_dma_handler ();
-void __attribute__ ((interrupt ("timer0"), disinterrupt))
- fast_timer_handler ();
-void __attribute__ ((interrupt ("dma0, dma1"),
- forwarder_section ("tramp")))
- external_dma_handler ();
-@end smallexample
-
-@item long_call
-@itemx short_call
-@cindex @code{long_call} function attribute, Epiphany
-@cindex @code{short_call} function attribute, Epiphany
-@cindex indirect calls, Epiphany
-These attributes specify how a particular function is called.
-These attributes override the
-@option{-mlong-calls} (@pxref{Adapteva Epiphany Options})
-command-line switch and @code{#pragma long_calls} settings.
-@end table
-
-
-@node H8/300 Function Attributes
-@subsection H8/300 Function Attributes
-
-These function attributes are available for H8/300 targets:
-
-@table @code
-@item function_vector
-@cindex @code{function_vector} function attribute, H8/300
-Use this attribute on the H8/300, H8/300H, and H8S to indicate
-that the specified function should be called through the function vector.
-Calling a function through the function vector reduces code size; however,
-the function vector has a limited size (maximum 128 entries on the H8/300
-and 64 entries on the H8/300H and H8S)
-and shares space with the interrupt vector.
-
-@item interrupt_handler
-@cindex @code{interrupt_handler} function attribute, H8/300
-Use this attribute on the H8/300, H8/300H, and H8S to
-indicate that the specified function is an interrupt handler. The compiler
-generates function entry and exit sequences suitable for use in an
-interrupt handler when this attribute is present.
-
-@item saveall
-@cindex @code{saveall} function attribute, H8/300
-@cindex save all registers on the H8/300, H8/300H, and H8S
-Use this attribute on the H8/300, H8/300H, and H8S to indicate that
-all registers except the stack pointer should be saved in the prologue
-regardless of whether they are used or not.
-@end table
-
-@node IA-64 Function Attributes
-@subsection IA-64 Function Attributes
-
-These function attributes are supported on IA-64 targets:
-
-@table @code
-@item syscall_linkage
-@cindex @code{syscall_linkage} function attribute, IA-64
-This attribute is used to modify the IA-64 calling convention by marking
-all input registers as live at all function exits. This makes it possible
-to restart a system call after an interrupt without having to save/restore
-the input registers. This also prevents kernel data from leaking into
-application code.
-
-@item version_id
-@cindex @code{version_id} function attribute, IA-64
-This IA-64 HP-UX attribute, attached to a global variable or function, renames a
-symbol to contain a version string, thus allowing for function level
-versioning. HP-UX system header files may use function level versioning
-for some system calls.
-
-@smallexample
-extern int foo () __attribute__((version_id ("20040821")));
-@end smallexample
-
-@noindent
-Calls to @code{foo} are mapped to calls to @code{foo@{20040821@}}.
-@end table
-
-@node M32C Function Attributes
-@subsection M32C Function Attributes
-
-These function attributes are supported by the M32C back end:
-
-@table @code
-@item bank_switch
-@cindex @code{bank_switch} function attribute, M32C
-When added to an interrupt handler with the M32C port, causes the
-prologue and epilogue to use bank switching to preserve the registers
-rather than saving them on the stack.
-
-@item fast_interrupt
-@cindex @code{fast_interrupt} function attribute, M32C
-Use this attribute on the M32C port to indicate that the specified
-function is a fast interrupt handler. This is just like the
-@code{interrupt} attribute, except that @code{freit} is used to return
-instead of @code{reit}.
-
-@item function_vector
-@cindex @code{function_vector} function attribute, M16C/M32C
-On M16C/M32C targets, the @code{function_vector} attribute declares a
-special page subroutine call function. Use of this attribute reduces
-the code size by 2 bytes for each call generated to the
-subroutine. The argument to the attribute is the vector number entry
-from the special page vector table which contains the 16 low-order
-bits of the subroutine's entry address. Each vector table has special
-page number (18 to 255) that is used in @code{jsrs} instructions.
-Jump addresses of the routines are generated by adding 0x0F0000 (in
-case of M16C targets) or 0xFF0000 (in case of M32C targets), to the
-2-byte addresses set in the vector table. Therefore you need to ensure
-that all the special page vector routines should get mapped within the
-address range 0x0F0000 to 0x0FFFFF (for M16C) and 0xFF0000 to 0xFFFFFF
-(for M32C).
-
-In the following example 2 bytes are saved for each call to
-function @code{foo}.
-
-@smallexample
-void foo (void) __attribute__((function_vector(0x18)));
-void foo (void)
-@{
-@}
-
-void bar (void)
-@{
- foo();
-@}
-@end smallexample
-
-If functions are defined in one file and are called in another file,
-then be sure to write this declaration in both files.
-
-This attribute is ignored for R8C target.
-
-@item interrupt
-@cindex @code{interrupt} function attribute, M32C
-Use this attribute to indicate
-that the specified function is an interrupt handler. The compiler generates
-function entry and exit sequences suitable for use in an interrupt handler
-when this attribute is present.
-@end table
-
-@node M32R/D Function Attributes
-@subsection M32R/D Function Attributes
-
-These function attributes are supported by the M32R/D back end:
-
-@table @code
-@item interrupt
-@cindex @code{interrupt} function attribute, M32R/D
-Use this attribute to indicate
-that the specified function is an interrupt handler. The compiler generates
-function entry and exit sequences suitable for use in an interrupt handler
-when this attribute is present.
-
-@item model (@var{model-name})
-@cindex @code{model} function attribute, M32R/D
-@cindex function addressability on the M32R/D
-
-On the M32R/D, use this attribute to set the addressability of an
-object, and of the code generated for a function. The identifier
-@var{model-name} is one of @code{small}, @code{medium}, or
-@code{large}, representing each of the code models.
-
-Small model objects live in the lower 16MB of memory (so that their
-addresses can be loaded with the @code{ld24} instruction), and are
-callable with the @code{bl} instruction.
-
-Medium model objects may live anywhere in the 32-bit address space (the
-compiler generates @code{seth/add3} instructions to load their addresses),
-and are callable with the @code{bl} instruction.
-
-Large model objects may live anywhere in the 32-bit address space (the
-compiler generates @code{seth/add3} instructions to load their addresses),
-and may not be reachable with the @code{bl} instruction (the compiler
-generates the much slower @code{seth/add3/jl} instruction sequence).
-@end table
-
-@node m68k Function Attributes
-@subsection m68k Function Attributes
-
-These function attributes are supported by the m68k back end:
-
-@table @code
-@item interrupt
-@itemx interrupt_handler
-@cindex @code{interrupt} function attribute, m68k
-@cindex @code{interrupt_handler} function attribute, m68k
-Use this attribute to
-indicate that the specified function is an interrupt handler. The compiler
-generates function entry and exit sequences suitable for use in an
-interrupt handler when this attribute is present. Either name may be used.
-
-@item interrupt_thread
-@cindex @code{interrupt_thread} function attribute, fido
-Use this attribute on fido, a subarchitecture of the m68k, to indicate
-that the specified function is an interrupt handler that is designed
-to run as a thread. The compiler omits generate prologue/epilogue
-sequences and replaces the return instruction with a @code{sleep}
-instruction. This attribute is available only on fido.
-@end table
-
-@node MCORE Function Attributes
-@subsection MCORE Function Attributes
-
-These function attributes are supported by the MCORE back end:
-
-@table @code
-@item naked
-@cindex @code{naked} function attribute, MCORE
-This attribute allows the compiler to construct the
-requisite function declaration, while allowing the body of the
-function to be assembly code. The specified function will not have
-prologue/epilogue sequences generated by the compiler. Only basic
-@code{asm} statements can safely be included in naked functions
-(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
-basic @code{asm} and C code may appear to work, they cannot be
-depended upon to work reliably and are not supported.
-@end table
-
-@node MeP Function Attributes
-@subsection MeP Function Attributes
-
-These function attributes are supported by the MeP back end:
-
-@table @code
-@item disinterrupt
-@cindex @code{disinterrupt} function attribute, MeP
-On MeP targets, this attribute causes the compiler to emit
-instructions to disable interrupts for the duration of the given
-function.
-
-@item interrupt
-@cindex @code{interrupt} function attribute, MeP
-Use this attribute to indicate
-that the specified function is an interrupt handler. The compiler generates
-function entry and exit sequences suitable for use in an interrupt handler
-when this attribute is present.
-
-@item near
-@cindex @code{near} function attribute, MeP
-This attribute causes the compiler to assume the called
-function is close enough to use the normal calling convention,
-overriding the @option{-mtf} command-line option.
-
-@item far
-@cindex @code{far} function attribute, MeP
-On MeP targets this causes the compiler to use a calling convention
-that assumes the called function is too far away for the built-in
-addressing modes.
-
-@item vliw
-@cindex @code{vliw} function attribute, MeP
-The @code{vliw} attribute tells the compiler to emit
-instructions in VLIW mode instead of core mode. Note that this
-attribute is not allowed unless a VLIW coprocessor has been configured
-and enabled through command-line options.
-@end table
-
-@node MicroBlaze Function Attributes
-@subsection MicroBlaze Function Attributes
-
-These function attributes are supported on MicroBlaze targets:
-
-@table @code
-@item save_volatiles
-@cindex @code{save_volatiles} function attribute, MicroBlaze
-Use this attribute to indicate that the function is
-an interrupt handler. All volatile registers (in addition to non-volatile
-registers) are saved in the function prologue. If the function is a leaf
-function, only volatiles used by the function are saved. A normal function
-return is generated instead of a return from interrupt.
-
-@item break_handler
-@cindex @code{break_handler} function attribute, MicroBlaze
-@cindex break handler functions
-Use this attribute to indicate that
-the specified function is a break handler. The compiler generates function
-entry and exit sequences suitable for use in an break handler when this
-attribute is present. The return from @code{break_handler} is done through
-the @code{rtbd} instead of @code{rtsd}.
-
-@smallexample
-void f () __attribute__ ((break_handler));
-@end smallexample
-
-@item interrupt_handler
-@itemx fast_interrupt
-@cindex @code{interrupt_handler} function attribute, MicroBlaze
-@cindex @code{fast_interrupt} function attribute, MicroBlaze
-These attributes indicate that the specified function is an interrupt
-handler. Use the @code{fast_interrupt} attribute to indicate handlers
-used in low-latency interrupt mode, and @code{interrupt_handler} for
-interrupts that do not use low-latency handlers. In both cases, GCC
-emits appropriate prologue code and generates a return from the handler
-using @code{rtid} instead of @code{rtsd}.
-@end table
-
-@node Microsoft Windows Function Attributes
-@subsection Microsoft Windows Function Attributes
-
-The following attributes are available on Microsoft Windows and Symbian OS
-targets.
-
-@table @code
-@item dllexport
-@cindex @code{dllexport} function attribute
-@cindex @code{__declspec(dllexport)}
-On Microsoft Windows targets and Symbian OS targets the
-@code{dllexport} attribute causes the compiler to provide a global
-pointer to a pointer in a DLL, so that it can be referenced with the
-@code{dllimport} attribute. On Microsoft Windows targets, the pointer
-name is formed by combining @code{_imp__} and the function or variable
-name.
-
-You can use @code{__declspec(dllexport)} as a synonym for
-@code{__attribute__ ((dllexport))} for compatibility with other
-compilers.
-
-On systems that support the @code{visibility} attribute, this
-attribute also implies ``default'' visibility. It is an error to
-explicitly specify any other visibility.
-
-GCC's default behavior is to emit all inline functions with the
-@code{dllexport} attribute. Since this can cause object file-size bloat,
-you can use @option{-fno-keep-inline-dllexport}, which tells GCC to
-ignore the attribute for inlined functions unless the
-@option{-fkeep-inline-functions} flag is used instead.
-
-The attribute is ignored for undefined symbols.
-
-When applied to C++ classes, the attribute marks defined non-inlined
-member functions and static data members as exports. Static consts
-initialized in-class are not marked unless they are also defined
-out-of-class.
-
-For Microsoft Windows targets there are alternative methods for
-including the symbol in the DLL's export table such as using a
-@file{.def} file with an @code{EXPORTS} section or, with GNU ld, using
-the @option{--export-all} linker flag.
-
-@item dllimport
-@cindex @code{dllimport} function attribute
-@cindex @code{__declspec(dllimport)}
-On Microsoft Windows and Symbian OS targets, the @code{dllimport}
-attribute causes the compiler to reference a function or variable via
-a global pointer to a pointer that is set up by the DLL exporting the
-symbol. The attribute implies @code{extern}. On Microsoft Windows
-targets, the pointer name is formed by combining @code{_imp__} and the
-function or variable name.
-
-You can use @code{__declspec(dllimport)} as a synonym for
-@code{__attribute__ ((dllimport))} for compatibility with other
-compilers.
-
-On systems that support the @code{visibility} attribute, this
-attribute also implies ``default'' visibility. It is an error to
-explicitly specify any other visibility.
-
-Currently, the attribute is ignored for inlined functions. If the
-attribute is applied to a symbol @emph{definition}, an error is reported.
-If a symbol previously declared @code{dllimport} is later defined, the
-attribute is ignored in subsequent references, and a warning is emitted.
-The attribute is also overridden by a subsequent declaration as
-@code{dllexport}.
-
-When applied to C++ classes, the attribute marks non-inlined
-member functions and static data members as imports. However, the
-attribute is ignored for virtual methods to allow creation of vtables
-using thunks.
-
-On the SH Symbian OS target the @code{dllimport} attribute also has
-another affect---it can cause the vtable and run-time type information
-for a class to be exported. This happens when the class has a
-dllimported constructor or a non-inline, non-pure virtual function
-and, for either of those two conditions, the class also has an inline
-constructor or destructor and has a key function that is defined in
-the current translation unit.
-
-For Microsoft Windows targets the use of the @code{dllimport}
-attribute on functions is not necessary, but provides a small
-performance benefit by eliminating a thunk in the DLL@. The use of the
-@code{dllimport} attribute on imported variables can be avoided by passing the
-@option{--enable-auto-import} switch to the GNU linker. As with
-functions, using the attribute for a variable eliminates a thunk in
-the DLL@.
-
-One drawback to using this attribute is that a pointer to a
-@emph{variable} marked as @code{dllimport} cannot be used as a constant
-address. However, a pointer to a @emph{function} with the
-@code{dllimport} attribute can be used as a constant initializer; in
-this case, the address of a stub function in the import lib is
-referenced. On Microsoft Windows targets, the attribute can be disabled
-for functions by setting the @option{-mnop-fun-dllimport} flag.
-@end table
-
-@node MIPS Function Attributes
-@subsection MIPS Function Attributes
-
-These function attributes are supported by the MIPS back end:
-
-@table @code
-@item interrupt
-@cindex @code{interrupt} function attribute, MIPS
-Use this attribute to indicate that the specified function is an interrupt
-handler. The compiler generates function entry and exit sequences suitable
-for use in an interrupt handler when this attribute is present.
-An optional argument is supported for the interrupt attribute which allows
-the interrupt mode to be described. By default GCC assumes the external
-interrupt controller (EIC) mode is in use, this can be explicitly set using
-@code{eic}. When interrupts are non-masked then the requested Interrupt
-Priority Level (IPL) is copied to the current IPL which has the effect of only
-enabling higher priority interrupts. To use vectored interrupt mode use
-the argument @code{vector=[sw0|sw1|hw0|hw1|hw2|hw3|hw4|hw5]}, this will change
-the behavior of the non-masked interrupt support and GCC will arrange to mask
-all interrupts from sw0 up to and including the specified interrupt vector.
-
-You can use the following attributes to modify the behavior
-of an interrupt handler:
-@table @code
-@item use_shadow_register_set
-@cindex @code{use_shadow_register_set} function attribute, MIPS
-Assume that the handler uses a shadow register set, instead of
-the main general-purpose registers. An optional argument @code{intstack} is
-supported to indicate that the shadow register set contains a valid stack
-pointer.
-
-@item keep_interrupts_masked
-@cindex @code{keep_interrupts_masked} function attribute, MIPS
-Keep interrupts masked for the whole function. Without this attribute,
-GCC tries to reenable interrupts for as much of the function as it can.
-
-@item use_debug_exception_return
-@cindex @code{use_debug_exception_return} function attribute, MIPS
-Return using the @code{deret} instruction. Interrupt handlers that don't
-have this attribute return using @code{eret} instead.
-@end table
-
-You can use any combination of these attributes, as shown below:
-@smallexample
-void __attribute__ ((interrupt)) v0 ();
-void __attribute__ ((interrupt, use_shadow_register_set)) v1 ();
-void __attribute__ ((interrupt, keep_interrupts_masked)) v2 ();
-void __attribute__ ((interrupt, use_debug_exception_return)) v3 ();
-void __attribute__ ((interrupt, use_shadow_register_set,
- keep_interrupts_masked)) v4 ();
-void __attribute__ ((interrupt, use_shadow_register_set,
- use_debug_exception_return)) v5 ();
-void __attribute__ ((interrupt, keep_interrupts_masked,
- use_debug_exception_return)) v6 ();
-void __attribute__ ((interrupt, use_shadow_register_set,
- keep_interrupts_masked,
- use_debug_exception_return)) v7 ();
-void __attribute__ ((interrupt("eic"))) v8 ();
-void __attribute__ ((interrupt("vector=hw3"))) v9 ();
-@end smallexample
-
-@item long_call
-@itemx short_call
-@itemx near
-@itemx far
-@cindex indirect calls, MIPS
-@cindex @code{long_call} function attribute, MIPS
-@cindex @code{short_call} function attribute, MIPS
-@cindex @code{near} function attribute, MIPS
-@cindex @code{far} function attribute, MIPS
-These attributes specify how a particular function is called on MIPS@.
-The attributes override the @option{-mlong-calls} (@pxref{MIPS Options})
-command-line switch. The @code{long_call} and @code{far} attributes are
-synonyms, and cause the compiler to always call
-the function by first loading its address into a register, and then using
-the contents of that register. The @code{short_call} and @code{near}
-attributes are synonyms, and have the opposite
-effect; they specify that non-PIC calls should be made using the more
-efficient @code{jal} instruction.
-
-@item mips16
-@itemx nomips16
-@cindex @code{mips16} function attribute, MIPS
-@cindex @code{nomips16} function attribute, MIPS
-
-On MIPS targets, you can use the @code{mips16} and @code{nomips16}
-function attributes to locally select or turn off MIPS16 code generation.
-A function with the @code{mips16} attribute is emitted as MIPS16 code,
-while MIPS16 code generation is disabled for functions with the
-@code{nomips16} attribute. These attributes override the
-@option{-mips16} and @option{-mno-mips16} options on the command line
-(@pxref{MIPS Options}).
-
-When compiling files containing mixed MIPS16 and non-MIPS16 code, the
-preprocessor symbol @code{__mips16} reflects the setting on the command line,
-not that within individual functions. Mixed MIPS16 and non-MIPS16 code
-may interact badly with some GCC extensions such as @code{__builtin_apply}
-(@pxref{Constructing Calls}).
-
-@item micromips, MIPS
-@itemx nomicromips, MIPS
-@cindex @code{micromips} function attribute
-@cindex @code{nomicromips} function attribute
-
-On MIPS targets, you can use the @code{micromips} and @code{nomicromips}
-function attributes to locally select or turn off microMIPS code generation.
-A function with the @code{micromips} attribute is emitted as microMIPS code,
-while microMIPS code generation is disabled for functions with the
-@code{nomicromips} attribute. These attributes override the
-@option{-mmicromips} and @option{-mno-micromips} options on the command line
-(@pxref{MIPS Options}).
-
-When compiling files containing mixed microMIPS and non-microMIPS code, the
-preprocessor symbol @code{__mips_micromips} reflects the setting on the
-command line,
-not that within individual functions. Mixed microMIPS and non-microMIPS code
-may interact badly with some GCC extensions such as @code{__builtin_apply}
-(@pxref{Constructing Calls}).
-
-@item nocompression
-@cindex @code{nocompression} function attribute, MIPS
-On MIPS targets, you can use the @code{nocompression} function attribute
-to locally turn off MIPS16 and microMIPS code generation. This attribute
-overrides the @option{-mips16} and @option{-mmicromips} options on the
-command line (@pxref{MIPS Options}).
-@end table
-
-@node MSP430 Function Attributes
-@subsection MSP430 Function Attributes
-
-These function attributes are supported by the MSP430 back end:
-
-@table @code
-@item critical
-@cindex @code{critical} function attribute, MSP430
-Critical functions disable interrupts upon entry and restore the
-previous interrupt state upon exit. Critical functions cannot also
-have the @code{naked}, @code{reentrant} or @code{interrupt} attributes.
-
-The MSP430 hardware ensures that interrupts are disabled on entry to
-@code{interrupt} functions, and restores the previous interrupt state
-on exit. The @code{critical} attribute is therefore redundant on
-@code{interrupt} functions.
-
-@item interrupt
-@cindex @code{interrupt} function attribute, MSP430
-Use this attribute to indicate
-that the specified function is an interrupt handler. The compiler generates
-function entry and exit sequences suitable for use in an interrupt handler
-when this attribute is present.
-
-You can provide an argument to the interrupt
-attribute which specifies a name or number. If the argument is a
-number it indicates the slot in the interrupt vector table (0 - 31) to
-which this handler should be assigned. If the argument is a name it
-is treated as a symbolic name for the vector slot. These names should
-match up with appropriate entries in the linker script. By default
-the names @code{watchdog} for vector 26, @code{nmi} for vector 30 and
-@code{reset} for vector 31 are recognized.
-
-@item naked
-@cindex @code{naked} function attribute, MSP430
-This attribute allows the compiler to construct the
-requisite function declaration, while allowing the body of the
-function to be assembly code. The specified function will not have
-prologue/epilogue sequences generated by the compiler. Only basic
-@code{asm} statements can safely be included in naked functions
-(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
-basic @code{asm} and C code may appear to work, they cannot be
-depended upon to work reliably and are not supported.
-
-@item reentrant
-@cindex @code{reentrant} function attribute, MSP430
-Reentrant functions disable interrupts upon entry and enable them
-upon exit. Reentrant functions cannot also have the @code{naked}
-or @code{critical} attributes. They can have the @code{interrupt}
-attribute.
-
-@item wakeup
-@cindex @code{wakeup} function attribute, MSP430
-This attribute only applies to interrupt functions. It is silently
-ignored if applied to a non-interrupt function. A wakeup interrupt
-function will rouse the processor from any low-power state that it
-might be in when the function exits.
-
-@item lower
-@itemx upper
-@itemx either
-@cindex @code{lower} function attribute, MSP430
-@cindex @code{upper} function attribute, MSP430
-@cindex @code{either} function attribute, MSP430
-On the MSP430 target these attributes can be used to specify whether
-the function or variable should be placed into low memory, high
-memory, or the placement should be left to the linker to decide. The
-attributes are only significant if compiling for the MSP430X
-architecture in the large memory model.
-
-The attributes work in conjunction with a linker script that has been
-augmented to specify where to place sections with a @code{.lower} and
-a @code{.upper} prefix. So, for example, as well as placing the
-@code{.data} section, the script also specifies the placement of a
-@code{.lower.data} and a @code{.upper.data} section. The intention
-is that @code{lower} sections are placed into a small but easier to
-access memory region and the upper sections are placed into a larger, but
-slower to access, region.
-
-The @code{either} attribute is special. It tells the linker to place
-the object into the corresponding @code{lower} section if there is
-room for it. If there is insufficient room then the object is placed
-into the corresponding @code{upper} section instead. Note that the
-placement algorithm is not very sophisticated. It does not attempt to
-find an optimal packing of the @code{lower} sections. It just makes
-one pass over the objects and does the best that it can. Using the
-@option{-ffunction-sections} and @option{-fdata-sections} command-line
-options can help the packing, however, since they produce smaller,
-easier to pack regions.
-@end table
-
-@node NDS32 Function Attributes
-@subsection NDS32 Function Attributes
-
-These function attributes are supported by the NDS32 back end:
-
-@table @code
-@item exception
-@cindex @code{exception} function attribute
-@cindex exception handler functions, NDS32
-Use this attribute on the NDS32 target to indicate that the specified function
-is an exception handler. The compiler will generate corresponding sections
-for use in an exception handler.
-
-@item interrupt
-@cindex @code{interrupt} function attribute, NDS32
-On NDS32 target, this attribute indicates that the specified function
-is an interrupt handler. The compiler generates corresponding sections
-for use in an interrupt handler. You can use the following attributes
-to modify the behavior:
-@table @code
-@item nested
-@cindex @code{nested} function attribute, NDS32
-This interrupt service routine is interruptible.
-@item not_nested
-@cindex @code{not_nested} function attribute, NDS32
-This interrupt service routine is not interruptible.
-@item nested_ready
-@cindex @code{nested_ready} function attribute, NDS32
-This interrupt service routine is interruptible after @code{PSW.GIE}
-(global interrupt enable) is set. This allows interrupt service routine to
-finish some short critical code before enabling interrupts.
-@item save_all
-@cindex @code{save_all} function attribute, NDS32
-The system will help save all registers into stack before entering
-interrupt handler.
-@item partial_save
-@cindex @code{partial_save} function attribute, NDS32
-The system will help save caller registers into stack before entering
-interrupt handler.
-@end table
-
-@item naked
-@cindex @code{naked} function attribute, NDS32
-This attribute allows the compiler to construct the
-requisite function declaration, while allowing the body of the
-function to be assembly code. The specified function will not have
-prologue/epilogue sequences generated by the compiler. Only basic
-@code{asm} statements can safely be included in naked functions
-(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
-basic @code{asm} and C code may appear to work, they cannot be
-depended upon to work reliably and are not supported.
-
-@item reset
-@cindex @code{reset} function attribute, NDS32
-@cindex reset handler functions
-Use this attribute on the NDS32 target to indicate that the specified function
-is a reset handler. The compiler will generate corresponding sections
-for use in a reset handler. You can use the following attributes
-to provide extra exception handling:
-@table @code
-@item nmi
-@cindex @code{nmi} function attribute, NDS32
-Provide a user-defined function to handle NMI exception.
-@item warm
-@cindex @code{warm} function attribute, NDS32
-Provide a user-defined function to handle warm reset exception.
-@end table
-@end table
-
-@node Nios II Function Attributes
-@subsection Nios II Function Attributes
-
-These function attributes are supported by the Nios II back end:
-
-@table @code
-@item target (@var{options})
-@cindex @code{target} function attribute
-As discussed in @ref{Common Function Attributes}, this attribute
-allows specification of target-specific compilation options.
-
-When compiling for Nios II, the following options are allowed:
-
-@table @samp
-@item custom-@var{insn}=@var{N}
-@itemx no-custom-@var{insn}
-@cindex @code{target("custom-@var{insn}=@var{N}")} function attribute, Nios II
-@cindex @code{target("no-custom-@var{insn}")} function attribute, Nios II
-Each @samp{custom-@var{insn}=@var{N}} attribute locally enables use of a
-custom instruction with encoding @var{N} when generating code that uses
-@var{insn}. Similarly, @samp{no-custom-@var{insn}} locally inhibits use of
-the custom instruction @var{insn}.
-These target attributes correspond to the
-@option{-mcustom-@var{insn}=@var{N}} and @option{-mno-custom-@var{insn}}
-command-line options, and support the same set of @var{insn} keywords.
-@xref{Nios II Options}, for more information.
-
-@item custom-fpu-cfg=@var{name}
-@cindex @code{target("custom-fpu-cfg=@var{name}")} function attribute, Nios II
-This attribute corresponds to the @option{-mcustom-fpu-cfg=@var{name}}
-command-line option, to select a predefined set of custom instructions
-named @var{name}.
-@xref{Nios II Options}, for more information.
-@end table
-@end table
-
-@node Nvidia PTX Function Attributes
-@subsection Nvidia PTX Function Attributes
-
-These function attributes are supported by the Nvidia PTX back end:
-
-@table @code
-@item kernel
-@cindex @code{kernel} attribute, Nvidia PTX
-This attribute indicates that the corresponding function should be compiled
-as a kernel function, which can be invoked from the host via the CUDA RT
-library.
-By default functions are only callable only from other PTX functions.
-
-Kernel functions must have @code{void} return type.
-@end table
-
-@node PowerPC Function Attributes
-@subsection PowerPC Function Attributes
-
-These function attributes are supported by the PowerPC back end:
-
-@table @code
-@item longcall
-@itemx shortcall
-@cindex indirect calls, PowerPC
-@cindex @code{longcall} function attribute, PowerPC
-@cindex @code{shortcall} function attribute, PowerPC
-The @code{longcall} attribute
-indicates that the function might be far away from the call site and
-require a different (more expensive) calling sequence. The
-@code{shortcall} attribute indicates that the function is always close
-enough for the shorter calling sequence to be used. These attributes
-override both the @option{-mlongcall} switch and
-the @code{#pragma longcall} setting.
-
-@xref{RS/6000 and PowerPC Options}, for more information on whether long
-calls are necessary.
-
-@item target (@var{options})
-@cindex @code{target} function attribute
-As discussed in @ref{Common Function Attributes}, this attribute
-allows specification of target-specific compilation options.
-
-On the PowerPC, the following options are allowed:
-
-@table @samp
-@item altivec
-@itemx no-altivec
-@cindex @code{target("altivec")} function attribute, PowerPC
-Generate code that uses (does not use) AltiVec instructions. In
-32-bit code, you cannot enable AltiVec instructions unless
-@option{-mabi=altivec} is used on the command line.
-
-@item cmpb
-@itemx no-cmpb
-@cindex @code{target("cmpb")} function attribute, PowerPC
-Generate code that uses (does not use) the compare bytes instruction
-implemented on the POWER6 processor and other processors that support
-the PowerPC V2.05 architecture.
-
-@item dlmzb
-@itemx no-dlmzb
-@cindex @code{target("dlmzb")} function attribute, PowerPC
-Generate code that uses (does not use) the string-search @samp{dlmzb}
-instruction on the IBM 405, 440, 464 and 476 processors. This instruction is
-generated by default when targeting those processors.
-
-@item fprnd
-@itemx no-fprnd
-@cindex @code{target("fprnd")} function attribute, PowerPC
-Generate code that uses (does not use) the FP round to integer
-instructions implemented on the POWER5+ processor and other processors
-that support the PowerPC V2.03 architecture.
-
-@item hard-dfp
-@itemx no-hard-dfp
-@cindex @code{target("hard-dfp")} function attribute, PowerPC
-Generate code that uses (does not use) the decimal floating-point
-instructions implemented on some POWER processors.
-
-@item isel
-@itemx no-isel
-@cindex @code{target("isel")} function attribute, PowerPC
-Generate code that uses (does not use) ISEL instruction.
-
-@item mfcrf
-@itemx no-mfcrf
-@cindex @code{target("mfcrf")} function attribute, PowerPC
-Generate code that uses (does not use) the move from condition
-register field instruction implemented on the POWER4 processor and
-other processors that support the PowerPC V2.01 architecture.
-
-@item mulhw
-@itemx no-mulhw
-@cindex @code{target("mulhw")} function attribute, PowerPC
-Generate code that uses (does not use) the half-word multiply and
-multiply-accumulate instructions on the IBM 405, 440, 464 and 476 processors.
-These instructions are generated by default when targeting those
-processors.
-
-@item multiple
-@itemx no-multiple
-@cindex @code{target("multiple")} function attribute, PowerPC
-Generate code that uses (does not use) the load multiple word
-instructions and the store multiple word instructions.
-
-@item update
-@itemx no-update
-@cindex @code{target("update")} function attribute, PowerPC
-Generate code that uses (does not use) the load or store instructions
-that update the base register to the address of the calculated memory
-location.
-
-@item popcntb
-@itemx no-popcntb
-@cindex @code{target("popcntb")} function attribute, PowerPC
-Generate code that uses (does not use) the popcount and double-precision
-FP reciprocal estimate instruction implemented on the POWER5
-processor and other processors that support the PowerPC V2.02
-architecture.
-
-@item popcntd
-@itemx no-popcntd
-@cindex @code{target("popcntd")} function attribute, PowerPC
-Generate code that uses (does not use) the popcount instruction
-implemented on the POWER7 processor and other processors that support
-the PowerPC V2.06 architecture.
-
-@item powerpc-gfxopt
-@itemx no-powerpc-gfxopt
-@cindex @code{target("powerpc-gfxopt")} function attribute, PowerPC
-Generate code that uses (does not use) the optional PowerPC
-architecture instructions in the Graphics group, including
-floating-point select.
-
-@item powerpc-gpopt
-@itemx no-powerpc-gpopt
-@cindex @code{target("powerpc-gpopt")} function attribute, PowerPC
-Generate code that uses (does not use) the optional PowerPC
-architecture instructions in the General Purpose group, including
-floating-point square root.
-
-@item recip-precision
-@itemx no-recip-precision
-@cindex @code{target("recip-precision")} function attribute, PowerPC
-Assume (do not assume) that the reciprocal estimate instructions
-provide higher-precision estimates than is mandated by the PowerPC
-ABI.
-
-@item string
-@itemx no-string
-@cindex @code{target("string")} function attribute, PowerPC
-Generate code that uses (does not use) the load string instructions
-and the store string word instructions to save multiple registers and
-do small block moves.
-
-@item vsx
-@itemx no-vsx
-@cindex @code{target("vsx")} function attribute, PowerPC
-Generate code that uses (does not use) vector/scalar (VSX)
-instructions, and also enable the use of built-in functions that allow
-more direct access to the VSX instruction set. In 32-bit code, you
-cannot enable VSX or AltiVec instructions unless
-@option{-mabi=altivec} is used on the command line.
-
-@item friz
-@itemx no-friz
-@cindex @code{target("friz")} function attribute, PowerPC
-Generate (do not generate) the @code{friz} instruction when the
-@option{-funsafe-math-optimizations} option is used to optimize
-rounding a floating-point value to 64-bit integer and back to floating
-point. The @code{friz} instruction does not return the same value if
-the floating-point number is too large to fit in an integer.
-
-@item avoid-indexed-addresses
-@itemx no-avoid-indexed-addresses
-@cindex @code{target("avoid-indexed-addresses")} function attribute, PowerPC
-Generate code that tries to avoid (not avoid) the use of indexed load
-or store instructions.
-
-@item paired
-@itemx no-paired
-@cindex @code{target("paired")} function attribute, PowerPC
-Generate code that uses (does not use) the generation of PAIRED simd
-instructions.
-
-@item longcall
-@itemx no-longcall
-@cindex @code{target("longcall")} function attribute, PowerPC
-Generate code that assumes (does not assume) that all calls are far
-away so that a longer more expensive calling sequence is required.
-
-@item cpu=@var{CPU}
-@cindex @code{target("cpu=@var{CPU}")} function attribute, PowerPC
-Specify the architecture to generate code for when compiling the
-function. If you select the @code{target("cpu=power7")} attribute when
-generating 32-bit code, VSX and AltiVec instructions are not generated
-unless you use the @option{-mabi=altivec} option on the command line.
-
-@item tune=@var{TUNE}
-@cindex @code{target("tune=@var{TUNE}")} function attribute, PowerPC
-Specify the architecture to tune for when compiling the function. If
-you do not specify the @code{target("tune=@var{TUNE}")} attribute and
-you do specify the @code{target("cpu=@var{CPU}")} attribute,
-compilation tunes for the @var{CPU} architecture, and not the
-default tuning specified on the command line.
-@end table
-
-On the PowerPC, the inliner does not inline a
-function that has different target options than the caller, unless the
-callee has a subset of the target options of the caller.
-@end table
-
-@node RISC-V Function Attributes
-@subsection RISC-V Function Attributes
-
-These function attributes are supported by the RISC-V back end:
-
-@table @code
-@item naked
-@cindex @code{naked} function attribute, RISC-V
-This attribute allows the compiler to construct the
-requisite function declaration, while allowing the body of the
-function to be assembly code. The specified function will not have
-prologue/epilogue sequences generated by the compiler. Only basic
-@code{asm} statements can safely be included in naked functions
-(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
-basic @code{asm} and C code may appear to work, they cannot be
-depended upon to work reliably and are not supported.
-
-@item interrupt
-@cindex @code{interrupt} function attribute, RISC-V
-Use this attribute to indicate that the specified function is an interrupt
-handler. The compiler generates function entry and exit sequences suitable
-for use in an interrupt handler when this attribute is present.
-
-You can specify the kind of interrupt to be handled by adding an optional
-parameter to the interrupt attribute like this:
-
-@smallexample
-void f (void) __attribute__ ((interrupt ("user")));
-@end smallexample
-
-Permissible values for this parameter are @code{user}, @code{supervisor},
-and @code{machine}. If there is no parameter, then it defaults to
-@code{machine}.
-@end table
-
-@node RL78 Function Attributes
-@subsection RL78 Function Attributes
-
-These function attributes are supported by the RL78 back end:
-
-@table @code
-@item interrupt
-@itemx brk_interrupt
-@cindex @code{interrupt} function attribute, RL78
-@cindex @code{brk_interrupt} function attribute, RL78
-These attributes indicate
-that the specified function is an interrupt handler. The compiler generates
-function entry and exit sequences suitable for use in an interrupt handler
-when this attribute is present.
-
-Use @code{brk_interrupt} instead of @code{interrupt} for
-handlers intended to be used with the @code{BRK} opcode (i.e.@: those
-that must end with @code{RETB} instead of @code{RETI}).
-
-@item naked
-@cindex @code{naked} function attribute, RL78
-This attribute allows the compiler to construct the
-requisite function declaration, while allowing the body of the
-function to be assembly code. The specified function will not have
-prologue/epilogue sequences generated by the compiler. Only basic
-@code{asm} statements can safely be included in naked functions
-(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
-basic @code{asm} and C code may appear to work, they cannot be
-depended upon to work reliably and are not supported.
-@end table
-
-@node RX Function Attributes
-@subsection RX Function Attributes
-
-These function attributes are supported by the RX back end:
-
-@table @code
-@item fast_interrupt
-@cindex @code{fast_interrupt} function attribute, RX
-Use this attribute on the RX port to indicate that the specified
-function is a fast interrupt handler. This is just like the
-@code{interrupt} attribute, except that @code{freit} is used to return
-instead of @code{reit}.
-
-@item interrupt
-@cindex @code{interrupt} function attribute, RX
-Use this attribute to indicate
-that the specified function is an interrupt handler. The compiler generates
-function entry and exit sequences suitable for use in an interrupt handler
-when this attribute is present.
-
-On RX and RL78 targets, you may specify one or more vector numbers as arguments
-to the attribute, as well as naming an alternate table name.
-Parameters are handled sequentially, so one handler can be assigned to
-multiple entries in multiple tables. One may also pass the magic
-string @code{"$default"} which causes the function to be used for any
-unfilled slots in the current table.
-
-This example shows a simple assignment of a function to one vector in
-the default table (note that preprocessor macros may be used for
-chip-specific symbolic vector names):
-@smallexample
-void __attribute__ ((interrupt (5))) txd1_handler ();
-@end smallexample
-
-This example assigns a function to two slots in the default table
-(using preprocessor macros defined elsewhere) and makes it the default
-for the @code{dct} table:
-@smallexample
-void __attribute__ ((interrupt (RXD1_VECT,RXD2_VECT,"dct","$default")))
- txd1_handler ();
-@end smallexample
-
-@item naked
-@cindex @code{naked} function attribute, RX
-This attribute allows the compiler to construct the
-requisite function declaration, while allowing the body of the
-function to be assembly code. The specified function will not have
-prologue/epilogue sequences generated by the compiler. Only basic
-@code{asm} statements can safely be included in naked functions
-(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
-basic @code{asm} and C code may appear to work, they cannot be
-depended upon to work reliably and are not supported.
-
-@item vector
-@cindex @code{vector} function attribute, RX
-This RX attribute is similar to the @code{interrupt} attribute, including its
-parameters, but does not make the function an interrupt-handler type
-function (i.e.@: it retains the normal C function calling ABI). See the
-@code{interrupt} attribute for a description of its arguments.
-@end table
-
-@node S/390 Function Attributes
-@subsection S/390 Function Attributes
-
-These function attributes are supported on the S/390:
-
-@table @code
-@item hotpatch (@var{halfwords-before-function-label},@var{halfwords-after-function-label})
-@cindex @code{hotpatch} function attribute, S/390
-
-On S/390 System z targets, you can use this function attribute to
-make GCC generate a ``hot-patching'' function prologue. If the
-@option{-mhotpatch=} command-line option is used at the same time,
-the @code{hotpatch} attribute takes precedence. The first of the
-two arguments specifies the number of halfwords to be added before
-the function label. A second argument can be used to specify the
-number of halfwords to be added after the function label. For
-both arguments the maximum allowed value is 1000000.
-
-If both arguments are zero, hotpatching is disabled.
-
-@item target (@var{options})
-@cindex @code{target} function attribute
-As discussed in @ref{Common Function Attributes}, this attribute
-allows specification of target-specific compilation options.
-
-On S/390, the following options are supported:
-
-@table @samp
-@item arch=
-@item tune=
-@item stack-guard=
-@item stack-size=
-@item branch-cost=
-@item warn-framesize=
-@item backchain
-@itemx no-backchain
-@item hard-dfp
-@itemx no-hard-dfp
-@item hard-float
-@itemx soft-float
-@item htm
-@itemx no-htm
-@item vx
-@itemx no-vx
-@item packed-stack
-@itemx no-packed-stack
-@item small-exec
-@itemx no-small-exec
-@item mvcle
-@itemx no-mvcle
-@item warn-dynamicstack
-@itemx no-warn-dynamicstack
-@end table
-
-The options work exactly like the S/390 specific command line
-options (without the prefix @option{-m}) except that they do not
-change any feature macros. For example,
-
-@smallexample
-@code{target("no-vx")}
-@end smallexample
-
-does not undefine the @code{__VEC__} macro.
-@end table
-
-@node SH Function Attributes
-@subsection SH Function Attributes
-
-These function attributes are supported on the SH family of processors:
-
-@table @code
-@item function_vector
-@cindex @code{function_vector} function attribute, SH
-@cindex calling functions through the function vector on SH2A
-On SH2A targets, this attribute declares a function to be called using the
-TBR relative addressing mode. The argument to this attribute is the entry
-number of the same function in a vector table containing all the TBR
-relative addressable functions. For correct operation the TBR must be setup
-accordingly to point to the start of the vector table before any functions with
-this attribute are invoked. Usually a good place to do the initialization is
-the startup routine. The TBR relative vector table can have at max 256 function
-entries. The jumps to these functions are generated using a SH2A specific,
-non delayed branch instruction JSR/N @@(disp8,TBR). You must use GAS and GLD
-from GNU binutils version 2.7 or later for this attribute to work correctly.
-
-In an application, for a function being called once, this attribute
-saves at least 8 bytes of code; and if other successive calls are being
-made to the same function, it saves 2 bytes of code per each of these
-calls.
-
-@item interrupt_handler
-@cindex @code{interrupt_handler} function attribute, SH
-Use this attribute to
-indicate that the specified function is an interrupt handler. The compiler
-generates function entry and exit sequences suitable for use in an
-interrupt handler when this attribute is present.
-
-@item nosave_low_regs
-@cindex @code{nosave_low_regs} function attribute, SH
-Use this attribute on SH targets to indicate that an @code{interrupt_handler}
-function should not save and restore registers R0..R7. This can be used on SH3*
-and SH4* targets that have a second R0..R7 register bank for non-reentrant
-interrupt handlers.
-
-@item renesas
-@cindex @code{renesas} function attribute, SH
-On SH targets this attribute specifies that the function or struct follows the
-Renesas ABI.
-
-@item resbank
-@cindex @code{resbank} function attribute, SH
-On the SH2A target, this attribute enables the high-speed register
-saving and restoration using a register bank for @code{interrupt_handler}
-routines. Saving to the bank is performed automatically after the CPU
-accepts an interrupt that uses a register bank.
-
-The nineteen 32-bit registers comprising general register R0 to R14,
-control register GBR, and system registers MACH, MACL, and PR and the
-vector table address offset are saved into a register bank. Register
-banks are stacked in first-in last-out (FILO) sequence. Restoration
-from the bank is executed by issuing a RESBANK instruction.
-
-@item sp_switch
-@cindex @code{sp_switch} function attribute, SH
-Use this attribute on the SH to indicate an @code{interrupt_handler}
-function should switch to an alternate stack. It expects a string
-argument that names a global variable holding the address of the
-alternate stack.
-
-@smallexample
-void *alt_stack;
-void f () __attribute__ ((interrupt_handler,
- sp_switch ("alt_stack")));
-@end smallexample
-
-@item trap_exit
-@cindex @code{trap_exit} function attribute, SH
-Use this attribute on the SH for an @code{interrupt_handler} to return using
-@code{trapa} instead of @code{rte}. This attribute expects an integer
-argument specifying the trap number to be used.
-
-@item trapa_handler
-@cindex @code{trapa_handler} function attribute, SH
-On SH targets this function attribute is similar to @code{interrupt_handler}
-but it does not save and restore all registers.
-@end table
-
-@node Symbian OS Function Attributes
-@subsection Symbian OS Function Attributes
-
-@xref{Microsoft Windows Function Attributes}, for discussion of the
-@code{dllexport} and @code{dllimport} attributes.
-
-@node V850 Function Attributes
-@subsection V850 Function Attributes
-
-The V850 back end supports these function attributes:
-
-@table @code
-@item interrupt
-@itemx interrupt_handler
-@cindex @code{interrupt} function attribute, V850
-@cindex @code{interrupt_handler} function attribute, V850
-Use these attributes to indicate
-that the specified function is an interrupt handler. The compiler generates
-function entry and exit sequences suitable for use in an interrupt handler
-when either attribute is present.
-@end table
-
-@node Visium Function Attributes
-@subsection Visium Function Attributes
-
-These function attributes are supported by the Visium back end:
-
-@table @code
-@item interrupt
-@cindex @code{interrupt} function attribute, Visium
-Use this attribute to indicate
-that the specified function is an interrupt handler. The compiler generates
-function entry and exit sequences suitable for use in an interrupt handler
-when this attribute is present.
-@end table
-
-@node x86 Function Attributes
-@subsection x86 Function Attributes
-
-These function attributes are supported by the x86 back end:
-
-@table @code
-@item cdecl
-@cindex @code{cdecl} function attribute, x86-32
-@cindex functions that pop the argument stack on x86-32
-@opindex mrtd
-On the x86-32 targets, the @code{cdecl} attribute causes the compiler to
-assume that the calling function pops off the stack space used to
-pass arguments. This is
-useful to override the effects of the @option{-mrtd} switch.
-
-@item fastcall
-@cindex @code{fastcall} function attribute, x86-32
-@cindex functions that pop the argument stack on x86-32
-On x86-32 targets, the @code{fastcall} attribute causes the compiler to
-pass the first argument (if of integral type) in the register ECX and
-the second argument (if of integral type) in the register EDX@. Subsequent
-and other typed arguments are passed on the stack. The called function
-pops the arguments off the stack. If the number of arguments is variable all
-arguments are pushed on the stack.
-
-@item thiscall
-@cindex @code{thiscall} function attribute, x86-32
-@cindex functions that pop the argument stack on x86-32
-On x86-32 targets, the @code{thiscall} attribute causes the compiler to
-pass the first argument (if of integral type) in the register ECX.
-Subsequent and other typed arguments are passed on the stack. The called
-function pops the arguments off the stack.
-If the number of arguments is variable all arguments are pushed on the
-stack.
-The @code{thiscall} attribute is intended for C++ non-static member functions.
-As a GCC extension, this calling convention can be used for C functions
-and for static member methods.
-
-@item ms_abi
-@itemx sysv_abi
-@cindex @code{ms_abi} function attribute, x86
-@cindex @code{sysv_abi} function attribute, x86
-
-On 32-bit and 64-bit x86 targets, you can use an ABI attribute
-to indicate which calling convention should be used for a function. The
-@code{ms_abi} attribute tells the compiler to use the Microsoft ABI,
-while the @code{sysv_abi} attribute tells the compiler to use the System V
-ELF ABI, which is used on GNU/Linux and other systems. The default is to use
-the Microsoft ABI when targeting Windows. On all other systems, the default
-is the System V ELF ABI.
-
-Note, the @code{ms_abi} attribute for Microsoft Windows 64-bit targets currently
-requires the @option{-maccumulate-outgoing-args} option.
-
-@item callee_pop_aggregate_return (@var{number})
-@cindex @code{callee_pop_aggregate_return} function attribute, x86
-
-On x86-32 targets, you can use this attribute to control how
-aggregates are returned in memory. If the caller is responsible for
-popping the hidden pointer together with the rest of the arguments, specify
-@var{number} equal to zero. If callee is responsible for popping the
-hidden pointer, specify @var{number} equal to one.
-
-The default x86-32 ABI assumes that the callee pops the
-stack for hidden pointer. However, on x86-32 Microsoft Windows targets,
-the compiler assumes that the
-caller pops the stack for hidden pointer.
-
-@item ms_hook_prologue
-@cindex @code{ms_hook_prologue} function attribute, x86
-
-On 32-bit and 64-bit x86 targets, you can use
-this function attribute to make GCC generate the ``hot-patching'' function
-prologue used in Win32 API functions in Microsoft Windows XP Service Pack 2
-and newer.
-
-@item naked
-@cindex @code{naked} function attribute, x86
-This attribute allows the compiler to construct the
-requisite function declaration, while allowing the body of the
-function to be assembly code. The specified function will not have
-prologue/epilogue sequences generated by the compiler. Only basic
-@code{asm} statements can safely be included in naked functions
-(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
-basic @code{asm} and C code may appear to work, they cannot be
-depended upon to work reliably and are not supported.
-
-@item regparm (@var{number})
-@cindex @code{regparm} function attribute, x86
-@cindex functions that are passed arguments in registers on x86-32
-On x86-32 targets, the @code{regparm} attribute causes the compiler to
-pass arguments number one to @var{number} if they are of integral type
-in registers EAX, EDX, and ECX instead of on the stack. Functions that
-take a variable number of arguments continue to be passed all of their
-arguments on the stack.
-
-Beware that on some ELF systems this attribute is unsuitable for
-global functions in shared libraries with lazy binding (which is the
-default). Lazy binding sends the first call via resolving code in
-the loader, which might assume EAX, EDX and ECX can be clobbered, as
-per the standard calling conventions. Solaris 8 is affected by this.
-Systems with the GNU C Library version 2.1 or higher
-and FreeBSD are believed to be
-safe since the loaders there save EAX, EDX and ECX. (Lazy binding can be
-disabled with the linker or the loader if desired, to avoid the
-problem.)
-
-@item sseregparm
-@cindex @code{sseregparm} function attribute, x86
-On x86-32 targets with SSE support, the @code{sseregparm} attribute
-causes the compiler to pass up to 3 floating-point arguments in
-SSE registers instead of on the stack. Functions that take a
-variable number of arguments continue to pass all of their
-floating-point arguments on the stack.
-
-@item force_align_arg_pointer
-@cindex @code{force_align_arg_pointer} function attribute, x86
-On x86 targets, the @code{force_align_arg_pointer} attribute may be
-applied to individual function definitions, generating an alternate
-prologue and epilogue that realigns the run-time stack if necessary.
-This supports mixing legacy codes that run with a 4-byte aligned stack
-with modern codes that keep a 16-byte stack for SSE compatibility.
-
-@item stdcall
-@cindex @code{stdcall} function attribute, x86-32
-@cindex functions that pop the argument stack on x86-32
-On x86-32 targets, the @code{stdcall} attribute causes the compiler to
-assume that the called function pops off the stack space used to
-pass arguments, unless it takes a variable number of arguments.
-
-@item no_caller_saved_registers
-@cindex @code{no_caller_saved_registers} function attribute, x86
-Use this attribute to indicate that the specified function has no
-caller-saved registers. That is, all registers are callee-saved. For
-example, this attribute can be used for a function called from an
-interrupt handler. The compiler generates proper function entry and
-exit sequences to save and restore any modified registers, except for
-the EFLAGS register. Since GCC doesn't preserve SSE, MMX nor x87
-states, the GCC option @option{-mgeneral-regs-only} should be used to
-compile functions with @code{no_caller_saved_registers} attribute.
-
-@item interrupt
-@cindex @code{interrupt} function attribute, x86
-Use this attribute to indicate that the specified function is an
-interrupt handler or an exception handler (depending on parameters passed
-to the function, explained further). The compiler generates function
-entry and exit sequences suitable for use in an interrupt handler when
-this attribute is present. The @code{IRET} instruction, instead of the
-@code{RET} instruction, is used to return from interrupt handlers. All
-registers, except for the EFLAGS register which is restored by the
-@code{IRET} instruction, are preserved by the compiler. Since GCC
-doesn't preserve SSE, MMX nor x87 states, the GCC option
-@option{-mgeneral-regs-only} should be used to compile interrupt and
-exception handlers.
-
-Any interruptible-without-stack-switch code must be compiled with
-@option{-mno-red-zone} since interrupt handlers can and will, because
-of the hardware design, touch the red zone.
-
-An interrupt handler must be declared with a mandatory pointer
-argument:
-
-@smallexample
-struct interrupt_frame;
-
-__attribute__ ((interrupt))
-void
-f (struct interrupt_frame *frame)
-@{
-@}
-@end smallexample
-
-@noindent
-and you must define @code{struct interrupt_frame} as described in the
-processor's manual.
-
-Exception handlers differ from interrupt handlers because the system
-pushes an error code on the stack. An exception handler declaration is
-similar to that for an interrupt handler, but with a different mandatory
-function signature. The compiler arranges to pop the error code off the
-stack before the @code{IRET} instruction.
-
-@smallexample
-#ifdef __x86_64__
-typedef unsigned long long int uword_t;
-#else
-typedef unsigned int uword_t;
-#endif
-
-struct interrupt_frame;
-
-__attribute__ ((interrupt))
-void
-f (struct interrupt_frame *frame, uword_t error_code)
-@{
- ...
-@}
-@end smallexample
-
-Exception handlers should only be used for exceptions that push an error
-code; you should use an interrupt handler in other cases. The system
-will crash if the wrong kind of handler is used.
-
-@item target (@var{options})
-@cindex @code{target} function attribute
-As discussed in @ref{Common Function Attributes}, this attribute
-allows specification of target-specific compilation options.
-
-On the x86, the following options are allowed:
-@table @samp
-@item 3dnow
-@itemx no-3dnow
-@cindex @code{target("3dnow")} function attribute, x86
-Enable/disable the generation of the 3DNow!@: instructions.
-
-@item 3dnowa
-@itemx no-3dnowa
-@cindex @code{target("3dnowa")} function attribute, x86
-Enable/disable the generation of the enhanced 3DNow!@: instructions.
-
-@item abm
-@itemx no-abm
-@cindex @code{target("abm")} function attribute, x86
-Enable/disable the generation of the advanced bit instructions.
-
-@item adx
-@itemx no-adx
-@cindex @code{target("adx")} function attribute, x86
-Enable/disable the generation of the ADX instructions.
-
-@item aes
-@itemx no-aes
-@cindex @code{target("aes")} function attribute, x86
-Enable/disable the generation of the AES instructions.
-
-@item avx
-@itemx no-avx
-@cindex @code{target("avx")} function attribute, x86
-Enable/disable the generation of the AVX instructions.
-
-@item avx2
-@itemx no-avx2
-@cindex @code{target("avx2")} function attribute, x86
-Enable/disable the generation of the AVX2 instructions.
-
-@item avx5124fmaps
-@itemx no-avx5124fmaps
-@cindex @code{target("avx5124fmaps")} function attribute, x86
-Enable/disable the generation of the AVX5124FMAPS instructions.
-
-@item avx5124vnniw
-@itemx no-avx5124vnniw
-@cindex @code{target("avx5124vnniw")} function attribute, x86
-Enable/disable the generation of the AVX5124VNNIW instructions.
-
-@item avx512bitalg
-@itemx no-avx512bitalg
-@cindex @code{target("avx512bitalg")} function attribute, x86
-Enable/disable the generation of the AVX512BITALG instructions.
-
-@item avx512bw
-@itemx no-avx512bw
-@cindex @code{target("avx512bw")} function attribute, x86
-Enable/disable the generation of the AVX512BW instructions.
-
-@item avx512cd
-@itemx no-avx512cd
-@cindex @code{target("avx512cd")} function attribute, x86
-Enable/disable the generation of the AVX512CD instructions.
-
-@item avx512dq
-@itemx no-avx512dq
-@cindex @code{target("avx512dq")} function attribute, x86
-Enable/disable the generation of the AVX512DQ instructions.
-
-@item avx512er
-@itemx no-avx512er
-@cindex @code{target("avx512er")} function attribute, x86
-Enable/disable the generation of the AVX512ER instructions.
-
-@item avx512f
-@itemx no-avx512f
-@cindex @code{target("avx512f")} function attribute, x86
-Enable/disable the generation of the AVX512F instructions.
-
-@item avx512ifma
-@itemx no-avx512ifma
-@cindex @code{target("avx512ifma")} function attribute, x86
-Enable/disable the generation of the AVX512IFMA instructions.
-
-@item avx512pf
-@itemx no-avx512pf
-@cindex @code{target("avx512pf")} function attribute, x86
-Enable/disable the generation of the AVX512PF instructions.
-
-@item avx512vbmi
-@itemx no-avx512vbmi
-@cindex @code{target("avx512vbmi")} function attribute, x86
-Enable/disable the generation of the AVX512VBMI instructions.
-
-@item avx512vbmi2
-@itemx no-avx512vbmi2
-@cindex @code{target("avx512vbmi2")} function attribute, x86
-Enable/disable the generation of the AVX512VBMI2 instructions.
-
-@item avx512vl
-@itemx no-avx512vl
-@cindex @code{target("avx512vl")} function attribute, x86
-Enable/disable the generation of the AVX512VL instructions.
-
-@item avx512vnni
-@itemx no-avx512vnni
-@cindex @code{target("avx512vnni")} function attribute, x86
-Enable/disable the generation of the AVX512VNNI instructions.
-
-@item avx512vpopcntdq
-@itemx no-avx512vpopcntdq
-@cindex @code{target("avx512vpopcntdq")} function attribute, x86
-Enable/disable the generation of the AVX512VPOPCNTDQ instructions.
-
-@item bmi
-@itemx no-bmi
-@cindex @code{target("bmi")} function attribute, x86
-Enable/disable the generation of the BMI instructions.
-
-@item bmi2
-@itemx no-bmi2
-@cindex @code{target("bmi2")} function attribute, x86
-Enable/disable the generation of the BMI2 instructions.
-
-@item cldemote
-@itemx no-cldemote
-@cindex @code{target("cldemote")} function attribute, x86
-Enable/disable the generation of the CLDEMOTE instructions.
-
-@item clflushopt
-@itemx no-clflushopt
-@cindex @code{target("clflushopt")} function attribute, x86
-Enable/disable the generation of the CLFLUSHOPT instructions.
-
-@item clwb
-@itemx no-clwb
-@cindex @code{target("clwb")} function attribute, x86
-Enable/disable the generation of the CLWB instructions.
-
-@item clzero
-@itemx no-clzero
-@cindex @code{target("clzero")} function attribute, x86
-Enable/disable the generation of the CLZERO instructions.
-
-@item crc32
-@itemx no-crc32
-@cindex @code{target("crc32")} function attribute, x86
-Enable/disable the generation of the CRC32 instructions.
-
-@item cx16
-@itemx no-cx16
-@cindex @code{target("cx16")} function attribute, x86
-Enable/disable the generation of the CMPXCHG16B instructions.
-
-@item default
-@cindex @code{target("default")} function attribute, x86
-@xref{Function Multiversioning}, where it is used to specify the
-default function version.
-
-@item f16c
-@itemx no-f16c
-@cindex @code{target("f16c")} function attribute, x86
-Enable/disable the generation of the F16C instructions.
-
-@item fma
-@itemx no-fma
-@cindex @code{target("fma")} function attribute, x86
-Enable/disable the generation of the FMA instructions.
-
-@item fma4
-@itemx no-fma4
-@cindex @code{target("fma4")} function attribute, x86
-Enable/disable the generation of the FMA4 instructions.
-
-@item fsgsbase
-@itemx no-fsgsbase
-@cindex @code{target("fsgsbase")} function attribute, x86
-Enable/disable the generation of the FSGSBASE instructions.
-
-@item fxsr
-@itemx no-fxsr
-@cindex @code{target("fxsr")} function attribute, x86
-Enable/disable the generation of the FXSR instructions.
-
-@item gfni
-@itemx no-gfni
-@cindex @code{target("gfni")} function attribute, x86
-Enable/disable the generation of the GFNI instructions.
-
-@item hle
-@itemx no-hle
-@cindex @code{target("hle")} function attribute, x86
-Enable/disable the generation of the HLE instruction prefixes.
-
-@item lwp
-@itemx no-lwp
-@cindex @code{target("lwp")} function attribute, x86
-Enable/disable the generation of the LWP instructions.
-
-@item lzcnt
-@itemx no-lzcnt
-@cindex @code{target("lzcnt")} function attribute, x86
-Enable/disable the generation of the LZCNT instructions.
-
-@item mmx
-@itemx no-mmx
-@cindex @code{target("mmx")} function attribute, x86
-Enable/disable the generation of the MMX instructions.
-
-@item movbe
-@itemx no-movbe
-@cindex @code{target("movbe")} function attribute, x86
-Enable/disable the generation of the MOVBE instructions.
-
-@item movdir64b
-@itemx no-movdir64b
-@cindex @code{target("movdir64b")} function attribute, x86
-Enable/disable the generation of the MOVDIR64B instructions.
-
-@item movdiri
-@itemx no-movdiri
-@cindex @code{target("movdiri")} function attribute, x86
-Enable/disable the generation of the MOVDIRI instructions.
-
-@item mwait
-@itemx no-mwait
-@cindex @code{target("mwait")} function attribute, x86
-Enable/disable the generation of the MWAIT and MONITOR instructions.
-
-@item mwaitx
-@itemx no-mwaitx
-@cindex @code{target("mwaitx")} function attribute, x86
-Enable/disable the generation of the MWAITX instructions.
-
-@item pclmul
-@itemx no-pclmul
-@cindex @code{target("pclmul")} function attribute, x86
-Enable/disable the generation of the PCLMUL instructions.
-
-@item pconfig
-@itemx no-pconfig
-@cindex @code{target("pconfig")} function attribute, x86
-Enable/disable the generation of the PCONFIG instructions.
-
-@item pku
-@itemx no-pku
-@cindex @code{target("pku")} function attribute, x86
-Enable/disable the generation of the PKU instructions.
-
-@item popcnt
-@itemx no-popcnt
-@cindex @code{target("popcnt")} function attribute, x86
-Enable/disable the generation of the POPCNT instruction.
-
-@item prefetchwt1
-@itemx no-prefetchwt1
-@cindex @code{target("prefetchwt1")} function attribute, x86
-Enable/disable the generation of the PREFETCHWT1 instructions.
-
-@item prfchw
-@itemx no-prfchw
-@cindex @code{target("prfchw")} function attribute, x86
-Enable/disable the generation of the PREFETCHW instruction.
-
-@item ptwrite
-@itemx no-ptwrite
-@cindex @code{target("ptwrite")} function attribute, x86
-Enable/disable the generation of the PTWRITE instructions.
-
-@item rdpid
-@itemx no-rdpid
-@cindex @code{target("rdpid")} function attribute, x86
-Enable/disable the generation of the RDPID instructions.
-
-@item rdrnd
-@itemx no-rdrnd
-@cindex @code{target("rdrnd")} function attribute, x86
-Enable/disable the generation of the RDRND instructions.
-
-@item rdseed
-@itemx no-rdseed
-@cindex @code{target("rdseed")} function attribute, x86
-Enable/disable the generation of the RDSEED instructions.
-
-@item rtm
-@itemx no-rtm
-@cindex @code{target("rtm")} function attribute, x86
-Enable/disable the generation of the RTM instructions.
-
-@item sahf
-@itemx no-sahf
-@cindex @code{target("sahf")} function attribute, x86
-Enable/disable the generation of the SAHF instructions.
-
-@item sgx
-@itemx no-sgx
-@cindex @code{target("sgx")} function attribute, x86
-Enable/disable the generation of the SGX instructions.
-
-@item sha
-@itemx no-sha
-@cindex @code{target("sha")} function attribute, x86
-Enable/disable the generation of the SHA instructions.
-
-@item shstk
-@itemx no-shstk
-@cindex @code{target("shstk")} function attribute, x86
-Enable/disable the shadow stack built-in functions from CET.
-
-@item sse
-@itemx no-sse
-@cindex @code{target("sse")} function attribute, x86
-Enable/disable the generation of the SSE instructions.
-
-@item sse2
-@itemx no-sse2
-@cindex @code{target("sse2")} function attribute, x86
-Enable/disable the generation of the SSE2 instructions.
-
-@item sse3
-@itemx no-sse3
-@cindex @code{target("sse3")} function attribute, x86
-Enable/disable the generation of the SSE3 instructions.
-
-@item sse4
-@itemx no-sse4
-@cindex @code{target("sse4")} function attribute, x86
-Enable/disable the generation of the SSE4 instructions (both SSE4.1
-and SSE4.2).
-
-@item sse4.1
-@itemx no-sse4.1
-@cindex @code{target("sse4.1")} function attribute, x86
-Enable/disable the generation of the SSE4.1 instructions.
-
-@item sse4.2
-@itemx no-sse4.2
-@cindex @code{target("sse4.2")} function attribute, x86
-Enable/disable the generation of the SSE4.2 instructions.
-
-@item sse4a
-@itemx no-sse4a
-@cindex @code{target("sse4a")} function attribute, x86
-Enable/disable the generation of the SSE4A instructions.
-
-@item ssse3
-@itemx no-ssse3
-@cindex @code{target("ssse3")} function attribute, x86
-Enable/disable the generation of the SSSE3 instructions.
-
-@item tbm
-@itemx no-tbm
-@cindex @code{target("tbm")} function attribute, x86
-Enable/disable the generation of the TBM instructions.
-
-@item vaes
-@itemx no-vaes
-@cindex @code{target("vaes")} function attribute, x86
-Enable/disable the generation of the VAES instructions.
-
-@item vpclmulqdq
-@itemx no-vpclmulqdq
-@cindex @code{target("vpclmulqdq")} function attribute, x86
-Enable/disable the generation of the VPCLMULQDQ instructions.
-
-@item waitpkg
-@itemx no-waitpkg
-@cindex @code{target("waitpkg")} function attribute, x86
-Enable/disable the generation of the WAITPKG instructions.
-
-@item wbnoinvd
-@itemx no-wbnoinvd
-@cindex @code{target("wbnoinvd")} function attribute, x86
-Enable/disable the generation of the WBNOINVD instructions.
-
-@item xop
-@itemx no-xop
-@cindex @code{target("xop")} function attribute, x86
-Enable/disable the generation of the XOP instructions.
-
-@item xsave
-@itemx no-xsave
-@cindex @code{target("xsave")} function attribute, x86
-Enable/disable the generation of the XSAVE instructions.
-
-@item xsavec
-@itemx no-xsavec
-@cindex @code{target("xsavec")} function attribute, x86
-Enable/disable the generation of the XSAVEC instructions.
-
-@item xsaveopt
-@itemx no-xsaveopt
-@cindex @code{target("xsaveopt")} function attribute, x86
-Enable/disable the generation of the XSAVEOPT instructions.
-
-@item xsaves
-@itemx no-xsaves
-@cindex @code{target("xsaves")} function attribute, x86
-Enable/disable the generation of the XSAVES instructions.
-
-@item amx-tile
-@itemx no-amx-tile
-@cindex @code{target("amx-tile")} function attribute, x86
-Enable/disable the generation of the AMX-TILE instructions.
-
-@item amx-int8
-@itemx no-amx-int8
-@cindex @code{target("amx-int8")} function attribute, x86
-Enable/disable the generation of the AMX-INT8 instructions.
-
-@item amx-bf16
-@itemx no-amx-bf16
-@cindex @code{target("amx-bf16")} function attribute, x86
-Enable/disable the generation of the AMX-BF16 instructions.
-
-@item uintr
-@itemx no-uintr
-@cindex @code{target("uintr")} function attribute, x86
-Enable/disable the generation of the UINTR instructions.
-
-@item hreset
-@itemx no-hreset
-@cindex @code{target("hreset")} function attribute, x86
-Enable/disable the generation of the HRESET instruction.
-
-@item kl
-@itemx no-kl
-@cindex @code{target("kl")} function attribute, x86
-Enable/disable the generation of the KEYLOCKER instructions.
-
-@item widekl
-@itemx no-widekl
-@cindex @code{target("widekl")} function attribute, x86
-Enable/disable the generation of the WIDEKL instructions.
-
-@item avxvnni
-@itemx no-avxvnni
-@cindex @code{target("avxvnni")} function attribute, x86
-Enable/disable the generation of the AVXVNNI instructions.
-
-@item avxifma
-@itemx no-avxifma
-@cindex @code{target("avxifma")} function attribute, x86
-Enable/disable the generation of the AVXIFMA instructions.
-
-@item avxvnniint8
-@itemx no-avxvnniint8
-@cindex @code{target("avxvnniint8")} function attribute, x86
-Enable/disable the generation of the AVXVNNIINT8 instructions.
-
-@item avxneconvert
-@itemx no-avxneconvert
-@cindex @code{target("avxneconvert")} function attribute, x86
-Enable/disable the generation of the AVXNECONVERT instructions.
-
-@item cmpccxadd
-@itemx no-cmpccxadd
-@cindex @code{target("cmpccxadd")} function attribute, x86
-Enable/disable the generation of the CMPccXADD instructions.
-
-@item amx-fp16
-@itemx no-amx-fp16
-@cindex @code{target("amx-fp16")} function attribute, x86
-Enable/disable the generation of the AMX-FP16 instructions.
-
-@item prefetchi
-@itemx no-prefetchi
-@cindex @code{target("prefetchi")} function attribute, x86
-Enable/disable the generation of the PREFETCHI instructions.
-
-@item raoint
-@itemx no-raoint
-@cindex @code{target("raoint")} function attribute, x86
-Enable/disable the generation of the RAOINT instructions.
-
-@item cld
-@itemx no-cld
-@cindex @code{target("cld")} function attribute, x86
-Enable/disable the generation of the CLD before string moves.
-
-@item fancy-math-387
-@itemx no-fancy-math-387
-@cindex @code{target("fancy-math-387")} function attribute, x86
-Enable/disable the generation of the @code{sin}, @code{cos}, and
-@code{sqrt} instructions on the 387 floating-point unit.
-
-@item ieee-fp
-@itemx no-ieee-fp
-@cindex @code{target("ieee-fp")} function attribute, x86
-Enable/disable the generation of floating point that depends on IEEE arithmetic.
-
-@item inline-all-stringops
-@itemx no-inline-all-stringops
-@cindex @code{target("inline-all-stringops")} function attribute, x86
-Enable/disable inlining of string operations.
-
-@item inline-stringops-dynamically
-@itemx no-inline-stringops-dynamically
-@cindex @code{target("inline-stringops-dynamically")} function attribute, x86
-Enable/disable the generation of the inline code to do small string
-operations and calling the library routines for large operations.
-
-@item align-stringops
-@itemx no-align-stringops
-@cindex @code{target("align-stringops")} function attribute, x86
-Do/do not align destination of inlined string operations.
-
-@item recip
-@itemx no-recip
-@cindex @code{target("recip")} function attribute, x86
-Enable/disable the generation of RCPSS, RCPPS, RSQRTSS and RSQRTPS
-instructions followed an additional Newton-Raphson step instead of
-doing a floating-point division.
-
-@item general-regs-only
-@cindex @code{target("general-regs-only")} function attribute, x86
-Generate code which uses only the general registers.
-
-@item arch=@var{ARCH}
-@cindex @code{target("arch=@var{ARCH}")} function attribute, x86
-Specify the architecture to generate code for in compiling the function.
-
-@item tune=@var{TUNE}
-@cindex @code{target("tune=@var{TUNE}")} function attribute, x86
-Specify the architecture to tune for in compiling the function.
-
-@item fpmath=@var{FPMATH}
-@cindex @code{target("fpmath=@var{FPMATH}")} function attribute, x86
-Specify which floating-point unit to use. You must specify the
-@code{target("fpmath=sse,387")} option as
-@code{target("fpmath=sse+387")} because the comma would separate
-different options.
-
-@item prefer-vector-width=@var{OPT}
-@cindex @code{prefer-vector-width} function attribute, x86
-On x86 targets, the @code{prefer-vector-width} attribute informs the
-compiler to use @var{OPT}-bit vector width in instructions
-instead of the default on the selected platform.
-
-Valid @var{OPT} values are:
-
-@table @samp
-@item none
-No extra limitations applied to GCC other than defined by the selected platform.
-
-@item 128
-Prefer 128-bit vector width for instructions.
-
-@item 256
-Prefer 256-bit vector width for instructions.
-
-@item 512
-Prefer 512-bit vector width for instructions.
-@end table
-
-On the x86, the inliner does not inline a
-function that has different target options than the caller, unless the
-callee has a subset of the target options of the caller. For example
-a function declared with @code{target("sse3")} can inline a function
-with @code{target("sse2")}, since @code{-msse3} implies @code{-msse2}.
-@end table
-
-@item indirect_branch("@var{choice}")
-@cindex @code{indirect_branch} function attribute, x86
-On x86 targets, the @code{indirect_branch} attribute causes the compiler
-to convert indirect call and jump with @var{choice}. @samp{keep}
-keeps indirect call and jump unmodified. @samp{thunk} converts indirect
-call and jump to call and return thunk. @samp{thunk-inline} converts
-indirect call and jump to inlined call and return thunk.
-@samp{thunk-extern} converts indirect call and jump to external call
-and return thunk provided in a separate object file.
-
-@item function_return("@var{choice}")
-@cindex @code{function_return} function attribute, x86
-On x86 targets, the @code{function_return} attribute causes the compiler
-to convert function return with @var{choice}. @samp{keep} keeps function
-return unmodified. @samp{thunk} converts function return to call and
-return thunk. @samp{thunk-inline} converts function return to inlined
-call and return thunk. @samp{thunk-extern} converts function return to
-external call and return thunk provided in a separate object file.
-
-@item nocf_check
-@cindex @code{nocf_check} function attribute
-The @code{nocf_check} attribute on a function is used to inform the
-compiler that the function's prologue should not be instrumented when
-compiled with the @option{-fcf-protection=branch} option. The
-compiler assumes that the function's address is a valid target for a
-control-flow transfer.
-
-The @code{nocf_check} attribute on a type of pointer to function is
-used to inform the compiler that a call through the pointer should
-not be instrumented when compiled with the
-@option{-fcf-protection=branch} option. The compiler assumes
-that the function's address from the pointer is a valid target for
-a control-flow transfer. A direct function call through a function
-name is assumed to be a safe call thus direct calls are not
-instrumented by the compiler.
-
-The @code{nocf_check} attribute is applied to an object's type.
-In case of assignment of a function address or a function pointer to
-another pointer, the attribute is not carried over from the right-hand
-object's type; the type of left-hand object stays unchanged. The
-compiler checks for @code{nocf_check} attribute mismatch and reports
-a warning in case of mismatch.
-
-@smallexample
-@{
-int foo (void) __attribute__(nocf_check);
-void (*foo1)(void) __attribute__(nocf_check);
-void (*foo2)(void);
-
-/* foo's address is assumed to be valid. */
-int
-foo (void)
-
- /* This call site is not checked for control-flow
- validity. */
- (*foo1)();
-
- /* A warning is issued about attribute mismatch. */
- foo1 = foo2;
-
- /* This call site is still not checked. */
- (*foo1)();
-
- /* This call site is checked. */
- (*foo2)();
-
- /* A warning is issued about attribute mismatch. */
- foo2 = foo1;
-
- /* This call site is still checked. */
- (*foo2)();
-
- return 0;
-@}
-@end smallexample
-
-@item cf_check
-@cindex @code{cf_check} function attribute, x86
-
-The @code{cf_check} attribute on a function is used to inform the
-compiler that ENDBR instruction should be placed at the function
-entry when @option{-fcf-protection=branch} is enabled.
-
-@item indirect_return
-@cindex @code{indirect_return} function attribute, x86
-
-The @code{indirect_return} attribute can be applied to a function,
-as well as variable or type of function pointer to inform the
-compiler that the function may return via indirect branch.
-
-@item fentry_name("@var{name}")
-@cindex @code{fentry_name} function attribute, x86
-On x86 targets, the @code{fentry_name} attribute sets the function to
-call on function entry when function instrumentation is enabled
-with @option{-pg -mfentry}. When @var{name} is nop then a 5 byte
-nop sequence is generated.
-
-@item fentry_section("@var{name}")
-@cindex @code{fentry_section} function attribute, x86
-On x86 targets, the @code{fentry_section} attribute sets the name
-of the section to record function entry instrumentation calls in when
-enabled with @option{-pg -mrecord-mcount}
-
-@item nodirect_extern_access
-@cindex @code{nodirect_extern_access} function attribute
-@opindex mno-direct-extern-access
-This attribute, attached to a global variable or function, is the
-counterpart to option @option{-mno-direct-extern-access}.
-
-@end table
-
-@node Xstormy16 Function Attributes
-@subsection Xstormy16 Function Attributes
-
-These function attributes are supported by the Xstormy16 back end:
-
-@table @code
-@item interrupt
-@cindex @code{interrupt} function attribute, Xstormy16
-Use this attribute to indicate
-that the specified function is an interrupt handler. The compiler generates
-function entry and exit sequences suitable for use in an interrupt handler
-when this attribute is present.
-@end table
-
-@node Variable Attributes
-@section Specifying Attributes of Variables
-@cindex attribute of variables
-@cindex variable attributes
-
-The keyword @code{__attribute__} allows you to specify special properties
-of variables, function parameters, or structure, union, and, in C++, class
-members. This @code{__attribute__} keyword is followed by an attribute
-specification enclosed in double parentheses. Some attributes are currently
-defined generically for variables. Other attributes are defined for
-variables on particular target systems. Other attributes are available
-for functions (@pxref{Function Attributes}), labels (@pxref{Label Attributes}),
-enumerators (@pxref{Enumerator Attributes}), statements
-(@pxref{Statement Attributes}), and for types (@pxref{Type Attributes}).
-Other front ends might define more attributes
-(@pxref{C++ Extensions,,Extensions to the C++ Language}).
-
-@xref{Attribute Syntax}, for details of the exact syntax for using
-attributes.
-
-@menu
-* Common Variable Attributes::
-* ARC Variable Attributes::
-* AVR Variable Attributes::
-* Blackfin Variable Attributes::
-* H8/300 Variable Attributes::
-* IA-64 Variable Attributes::
-* LoongArch Variable Attributes::
-* M32R/D Variable Attributes::
-* MeP Variable Attributes::
-* Microsoft Windows Variable Attributes::
-* MSP430 Variable Attributes::
-* Nvidia PTX Variable Attributes::
-* PowerPC Variable Attributes::
-* RL78 Variable Attributes::
-* V850 Variable Attributes::
-* x86 Variable Attributes::
-* Xstormy16 Variable Attributes::
-@end menu
-
-@node Common Variable Attributes
-@subsection Common Variable Attributes
-
-The following attributes are supported on most targets.
-
-@table @code
-
-@item alias ("@var{target}")
-@cindex @code{alias} variable attribute
-The @code{alias} variable attribute causes the declaration to be emitted
-as an alias for another symbol known as an @dfn{alias target}. Except
-for top-level qualifiers the alias target must have the same type as
-the alias. For instance, the following
-
-@smallexample
-int var_target;
-extern int __attribute__ ((alias ("var_target"))) var_alias;
-@end smallexample
-
-@noindent
-defines @code{var_alias} to be an alias for the @code{var_target} variable.
-
-It is an error if the alias target is not defined in the same translation
-unit as the alias.
-
-Note that in the absence of the attribute GCC assumes that distinct
-declarations with external linkage denote distinct objects. Using both
-the alias and the alias target to access the same object is undefined
-in a translation unit without a declaration of the alias with the attribute.
-
-This attribute requires assembler and object file support, and may not be
-available on all targets.
-
-@cindex @code{aligned} variable attribute
-@item aligned
-@itemx aligned (@var{alignment})
-The @code{aligned} attribute specifies a minimum alignment for the variable
-or structure field, measured in bytes. When specified, @var{alignment} must
-be an integer constant power of 2. Specifying no @var{alignment} argument
-implies the maximum alignment for the target, which is often, but by no
-means always, 8 or 16 bytes.
-
-For example, the declaration:
-
-@smallexample
-int x __attribute__ ((aligned (16))) = 0;
-@end smallexample
-
-@noindent
-causes the compiler to allocate the global variable @code{x} on a
-16-byte boundary. On a 68040, this could be used in conjunction with
-an @code{asm} expression to access the @code{move16} instruction which
-requires 16-byte aligned operands.
-
-You can also specify the alignment of structure fields. For example, to
-create a double-word aligned @code{int} pair, you could write:
-
-@smallexample
-struct foo @{ int x[2] __attribute__ ((aligned (8))); @};
-@end smallexample
-
-@noindent
-This is an alternative to creating a union with a @code{double} member,
-which forces the union to be double-word aligned.
-
-As in the preceding examples, you can explicitly specify the alignment
-(in bytes) that you wish the compiler to use for a given variable or
-structure field. Alternatively, you can leave out the alignment factor
-and just ask the compiler to align a variable or field to the
-default alignment for the target architecture you are compiling for.
-The default alignment is sufficient for all scalar types, but may not be
-enough for all vector types on a target that supports vector operations.
-The default alignment is fixed for a particular target ABI.
-
-GCC also provides a target specific macro @code{__BIGGEST_ALIGNMENT__},
-which is the largest alignment ever used for any data type on the
-target machine you are compiling for. For example, you could write:
-
-@smallexample
-short array[3] __attribute__ ((aligned (__BIGGEST_ALIGNMENT__)));
-@end smallexample
-
-The compiler automatically sets the alignment for the declared
-variable or field to @code{__BIGGEST_ALIGNMENT__}. Doing this can
-often make copy operations more efficient, because the compiler can
-use whatever instructions copy the biggest chunks of memory when
-performing copies to or from the variables or fields that you have
-aligned this way. Note that the value of @code{__BIGGEST_ALIGNMENT__}
-may change depending on command-line options.
-
-When used on a struct, or struct member, the @code{aligned} attribute can
-only increase the alignment; in order to decrease it, the @code{packed}
-attribute must be specified as well. When used as part of a typedef, the
-@code{aligned} attribute can both increase and decrease alignment, and
-specifying the @code{packed} attribute generates a warning.
-
-Note that the effectiveness of @code{aligned} attributes for static
-variables may be limited by inherent limitations in the system linker
-and/or object file format. On some systems, the linker is
-only able to arrange for variables to be aligned up to a certain maximum
-alignment. (For some linkers, the maximum supported alignment may
-be very very small.) If your linker is only able to align variables
-up to a maximum of 8-byte alignment, then specifying @code{aligned(16)}
-in an @code{__attribute__} still only provides you with 8-byte
-alignment. See your linker documentation for further information.
-
-Stack variables are not affected by linker restrictions; GCC can properly
-align them on any target.
-
-The @code{aligned} attribute can also be used for functions
-(@pxref{Common Function Attributes}.)
-
-@cindex @code{warn_if_not_aligned} variable attribute
-@item warn_if_not_aligned (@var{alignment})
-This attribute specifies a threshold for the structure field, measured
-in bytes. If the structure field is aligned below the threshold, a
-warning will be issued. For example, the declaration:
-
-@smallexample
-struct foo
-@{
- int i1;
- int i2;
- unsigned long long x __attribute__ ((warn_if_not_aligned (16)));
-@};
-@end smallexample
-
-@noindent
-causes the compiler to issue an warning on @code{struct foo}, like
-@samp{warning: alignment 8 of 'struct foo' is less than 16}.
-The compiler also issues a warning, like @samp{warning: 'x' offset
-8 in 'struct foo' isn't aligned to 16}, when the structure field has
-the misaligned offset:
-
-@smallexample
-struct __attribute__ ((aligned (16))) foo
-@{
- int i1;
- int i2;
- unsigned long long x __attribute__ ((warn_if_not_aligned (16)));
-@};
-@end smallexample
-
-This warning can be disabled by @option{-Wno-if-not-aligned}.
-The @code{warn_if_not_aligned} attribute can also be used for types
-(@pxref{Common Type Attributes}.)
-
-@cindex @code{strict_flex_array} variable attribute
-@item strict_flex_array (@var{level})
-The @code{strict_flex_array} attribute should be attached to the trailing
-array field of a structure. It controls when to treat the trailing array
-field of a structure as a flexible array member for the purposes of accessing
-the elements of such an array.
-@var{level} must be an integer betwen 0 to 3.
-
-@var{level}=0 is the least strict level, all trailing arrays of structures
-are treated as flexible array members. @var{level}=3 is the strictest level,
-only when the trailing array is declared as a flexible array member per C99
-standard onwards (@samp{[]}), it is treated as a flexible array member.
-
-There are two more levels in between 0 and 3, which are provided to support
-older codes that use GCC zero-length array extension (@samp{[0]}) or one-element
-array as flexible array members (@samp{[1]}):
-When @var{level} is 1, the trailing array is treated as a flexible array member
-when it is declared as either @samp{[]}, @samp{[0]}, or @samp{[1]};
-When @var{level} is 2, the trailing array is treated as a flexible array member
-when it is declared as either @samp{[]}, or @samp{[0]}.
-
-This attribute can be used with or without the @option{-fstrict-flex-arrays}.
-When both the attribute and the option present at the same time, the level of
-the strictness for the specific trailing array field is determined by the
-attribute.
-
-@item alloc_size (@var{position})
-@itemx alloc_size (@var{position-1}, @var{position-2})
-@cindex @code{alloc_size} variable attribute
-The @code{alloc_size} variable attribute may be applied to the declaration
-of a pointer to a function that returns a pointer and takes at least one
-argument of an integer type. It indicates that the returned pointer points
-to an object whose size is given by the function argument at @var{position},
-or by the product of the arguments at @var{position-1} and @var{position-2}.
-Meaningful sizes are positive values less than @code{PTRDIFF_MAX}. Other
-sizes are diagnosed when detected. GCC uses this information to improve
-the results of @code{__builtin_object_size}.
-
-For instance, the following declarations
-
-@smallexample
-typedef __attribute__ ((alloc_size (1, 2))) void*
- (*calloc_ptr) (size_t, size_t);
-typedef __attribute__ ((alloc_size (1))) void*
- (*malloc_ptr) (size_t);
-@end smallexample
-
-@noindent
-specify that @code{calloc_ptr} is a pointer of a function that, like
-the standard C function @code{calloc}, returns an object whose size
-is given by the product of arguments 1 and 2, and similarly, that
-@code{malloc_ptr}, like the standard C function @code{malloc},
-returns an object whose size is given by argument 1 to the function.
-
-@item cleanup (@var{cleanup_function})
-@cindex @code{cleanup} variable attribute
-The @code{cleanup} attribute runs a function when the variable goes
-out of scope. This attribute can only be applied to auto function
-scope variables; it may not be applied to parameters or variables
-with static storage duration. The function must take one parameter,
-a pointer to a type compatible with the variable. The return value
-of the function (if any) is ignored.
-
-If @option{-fexceptions} is enabled, then @var{cleanup_function}
-is run during the stack unwinding that happens during the
-processing of the exception. Note that the @code{cleanup} attribute
-does not allow the exception to be caught, only to perform an action.
-It is undefined what happens if @var{cleanup_function} does not
-return normally.
-
-@item common
-@itemx nocommon
-@cindex @code{common} variable attribute
-@cindex @code{nocommon} variable attribute
-@opindex fcommon
-@opindex fno-common
-The @code{common} attribute requests GCC to place a variable in
-``common'' storage. The @code{nocommon} attribute requests the
-opposite---to allocate space for it directly.
-
-These attributes override the default chosen by the
-@option{-fno-common} and @option{-fcommon} flags respectively.
-
-@item copy
-@itemx copy (@var{variable})
-@cindex @code{copy} variable attribute
-The @code{copy} attribute applies the set of attributes with which
-@var{variable} has been declared to the declaration of the variable
-to which the attribute is applied. The attribute is designed for
-libraries that define aliases that are expected to specify the same
-set of attributes as the aliased symbols. The @code{copy} attribute
-can be used with variables, functions or types. However, the kind
-of symbol to which the attribute is applied (either varible or
-function) must match the kind of symbol to which the argument refers.
-The @code{copy} attribute copies only syntactic and semantic attributes
-but not attributes that affect a symbol's linkage or visibility such as
-@code{alias}, @code{visibility}, or @code{weak}. The @code{deprecated}
-attribute is also not copied. @xref{Common Function Attributes}.
-@xref{Common Type Attributes}.
-
-@item deprecated
-@itemx deprecated (@var{msg})
-@cindex @code{deprecated} variable attribute
-The @code{deprecated} attribute results in a warning if the variable
-is used anywhere in the source file. This is useful when identifying
-variables that are expected to be removed in a future version of a
-program. The warning also includes the location of the declaration
-of the deprecated variable, to enable users to easily find further
-information about why the variable is deprecated, or what they should
-do instead. Note that the warning only occurs for uses:
-
-@smallexample
-extern int old_var __attribute__ ((deprecated));
-extern int old_var;
-int new_fn () @{ return old_var; @}
-@end smallexample
-
-@noindent
-results in a warning on line 3 but not line 2. The optional @var{msg}
-argument, which must be a string, is printed in the warning if
-present.
-
-The @code{deprecated} attribute can also be used for functions and
-types (@pxref{Common Function Attributes},
-@pxref{Common Type Attributes}).
-
-The message attached to the attribute is affected by the setting of
-the @option{-fmessage-length} option.
-
-@item unavailable
-@itemx unavailable (@var{msg})
-@cindex @code{unavailable} variable attribute
-The @code{unavailable} attribute indicates that the variable so marked
-is not available, if it is used anywhere in the source file. It behaves
-in the same manner as the @code{deprecated} attribute except that the
-compiler will emit an error rather than a warning.
-
-It is expected that items marked as @code{deprecated} will eventually be
-withdrawn from interfaces, and then become unavailable. This attribute
-allows for marking them appropriately.
-
-The @code{unavailable} attribute can also be used for functions and
-types (@pxref{Common Function Attributes},
-@pxref{Common Type Attributes}).
-
-@item mode (@var{mode})
-@cindex @code{mode} variable attribute
-This attribute specifies the data type for the declaration---whichever
-type corresponds to the mode @var{mode}. This in effect lets you
-request an integer or floating-point type according to its width.
-
-@xref{Machine Modes,,, gccint, GNU Compiler Collection (GCC) Internals},
-for a list of the possible keywords for @var{mode}.
-You may also specify a mode of @code{byte} or @code{__byte__} to
-indicate the mode corresponding to a one-byte integer, @code{word} or
-@code{__word__} for the mode of a one-word integer, and @code{pointer}
-or @code{__pointer__} for the mode used to represent pointers.
-
-@item nonstring
-@cindex @code{nonstring} variable attribute
-The @code{nonstring} variable attribute specifies that an object or member
-declaration with type array of @code{char}, @code{signed char}, or
-@code{unsigned char}, or pointer to such a type is intended to store
-character arrays that do not necessarily contain a terminating @code{NUL}.
-This is useful in detecting uses of such arrays or pointers with functions
-that expect @code{NUL}-terminated strings, and to avoid warnings when such
-an array or pointer is used as an argument to a bounded string manipulation
-function such as @code{strncpy}. For example, without the attribute, GCC
-will issue a warning for the @code{strncpy} call below because it may
-truncate the copy without appending the terminating @code{NUL} character.
-Using the attribute makes it possible to suppress the warning. However,
-when the array is declared with the attribute the call to @code{strlen} is
-diagnosed because when the array doesn't contain a @code{NUL}-terminated
-string the call is undefined. To copy, compare, of search non-string
-character arrays use the @code{memcpy}, @code{memcmp}, @code{memchr},
-and other functions that operate on arrays of bytes. In addition,
-calling @code{strnlen} and @code{strndup} with such arrays is safe
-provided a suitable bound is specified, and not diagnosed.
-
-@smallexample
-struct Data
-@{
- char name [32] __attribute__ ((nonstring));
-@};
-
-int f (struct Data *pd, const char *s)
-@{
- strncpy (pd->name, s, sizeof pd->name);
- @dots{}
- return strlen (pd->name); // unsafe, gets a warning
-@}
-@end smallexample
-
-@item packed
-@cindex @code{packed} variable attribute
-The @code{packed} attribute specifies that a structure member should have
-the smallest possible alignment---one bit for a bit-field and one byte
-otherwise, unless a larger value is specified with the @code{aligned}
-attribute. The attribute does not apply to non-member objects.
-
-For example in the structure below, the member array @code{x} is packed
-so that it immediately follows @code{a} with no intervening padding:
-
-@smallexample
-struct foo
-@{
- char a;
- int x[2] __attribute__ ((packed));
-@};
-@end smallexample
-
-@emph{Note:} The 4.1, 4.2 and 4.3 series of GCC ignore the
-@code{packed} attribute on bit-fields of type @code{char}. This has
-been fixed in GCC 4.4 but the change can lead to differences in the
-structure layout. See the documentation of
-@option{-Wpacked-bitfield-compat} for more information.
-
-@item section ("@var{section-name}")
-@cindex @code{section} variable attribute
-Normally, the compiler places the objects it generates in sections like
-@code{data} and @code{bss}. Sometimes, however, you need additional sections,
-or you need certain particular variables to appear in special sections,
-for example to map to special hardware. The @code{section}
-attribute specifies that a variable (or function) lives in a particular
-section. For example, this small program uses several specific section names:
-
-@smallexample
-struct duart a __attribute__ ((section ("DUART_A"))) = @{ 0 @};
-struct duart b __attribute__ ((section ("DUART_B"))) = @{ 0 @};
-char stack[10000] __attribute__ ((section ("STACK"))) = @{ 0 @};
-int init_data __attribute__ ((section ("INITDATA")));
-
-main()
-@{
- /* @r{Initialize stack pointer} */
- init_sp (stack + sizeof (stack));
-
- /* @r{Initialize initialized data} */
- memcpy (&init_data, &data, &edata - &data);
-
- /* @r{Turn on the serial ports} */
- init_duart (&a);
- init_duart (&b);
-@}
-@end smallexample
-
-@noindent
-Use the @code{section} attribute with
-@emph{global} variables and not @emph{local} variables,
-as shown in the example.
-
-You may use the @code{section} attribute with initialized or
-uninitialized global variables but the linker requires
-each object be defined once, with the exception that uninitialized
-variables tentatively go in the @code{common} (or @code{bss}) section
-and can be multiply ``defined''. Using the @code{section} attribute
-changes what section the variable goes into and may cause the
-linker to issue an error if an uninitialized variable has multiple
-definitions. You can force a variable to be initialized with the
-@option{-fno-common} flag or the @code{nocommon} attribute.
-
-Some file formats do not support arbitrary sections so the @code{section}
-attribute is not available on all platforms.
-If you need to map the entire contents of a module to a particular
-section, consider using the facilities of the linker instead.
-
-@item tls_model ("@var{tls_model}")
-@cindex @code{tls_model} variable attribute
-The @code{tls_model} attribute sets thread-local storage model
-(@pxref{Thread-Local}) of a particular @code{__thread} variable,
-overriding @option{-ftls-model=} command-line switch on a per-variable
-basis.
-The @var{tls_model} argument should be one of @code{global-dynamic},
-@code{local-dynamic}, @code{initial-exec} or @code{local-exec}.
-
-Not all targets support this attribute.
-
-@item unused
-@cindex @code{unused} variable attribute
-This attribute, attached to a variable or structure field, means that
-the variable or field is meant to be possibly unused. GCC does not
-produce a warning for this variable or field.
-
-@item used
-@cindex @code{used} variable attribute
-This attribute, attached to a variable with static storage, means that
-the variable must be emitted even if it appears that the variable is not
-referenced.
-
-When applied to a static data member of a C++ class template, the
-attribute also means that the member is instantiated if the
-class itself is instantiated.
-
-@item retain
-@cindex @code{retain} variable attribute
-For ELF targets that support the GNU or FreeBSD OSABIs, this attribute
-will save the variable from linker garbage collection. To support
-this behavior, variables that have not been placed in specific sections
-(e.g. by the @code{section} attribute, or the @code{-fdata-sections} option),
-will be placed in new, unique sections.
-
-This additional functionality requires Binutils version 2.36 or later.
-
-@item uninitialized
-@cindex @code{uninitialized} variable attribute
-This attribute, attached to a variable with automatic storage, means that
-the variable should not be automatically initialized by the compiler when
-the option @code{-ftrivial-auto-var-init} presents.
-
-With the option @code{-ftrivial-auto-var-init}, all the automatic variables
-that do not have explicit initializers will be initialized by the compiler.
-These additional compiler initializations might incur run-time overhead,
-sometimes dramatically. This attribute can be used to mark some variables
-to be excluded from such automatical initialization in order to reduce runtime
-overhead.
-
-This attribute has no effect when the option @code{-ftrivial-auto-var-init}
-does not present.
-
-@item vector_size (@var{bytes})
-@cindex @code{vector_size} variable attribute
-This attribute specifies the vector size for the type of the declared
-variable, measured in bytes. The type to which it applies is known as
-the @dfn{base type}. The @var{bytes} argument must be a positive
-power-of-two multiple of the base type size. For example, the declaration:
-
-@smallexample
-int foo __attribute__ ((vector_size (16)));
-@end smallexample
-
-@noindent
-causes the compiler to set the mode for @code{foo}, to be 16 bytes,
-divided into @code{int} sized units. Assuming a 32-bit @code{int},
-@code{foo}'s type is a vector of four units of four bytes each, and
-the corresponding mode of @code{foo} is @code{V4SI}.
-@xref{Vector Extensions}, for details of manipulating vector variables.
-
-This attribute is only applicable to integral and floating scalars,
-although arrays, pointers, and function return values are allowed in
-conjunction with this construct.
-
-Aggregates with this attribute are invalid, even if they are of the same
-size as a corresponding scalar. For example, the declaration:
-
-@smallexample
-struct S @{ int a; @};
-struct S __attribute__ ((vector_size (16))) foo;
-@end smallexample
-
-@noindent
-is invalid even if the size of the structure is the same as the size of
-the @code{int}.
-
-@item visibility ("@var{visibility_type}")
-@cindex @code{visibility} variable attribute
-This attribute affects the linkage of the declaration to which it is attached.
-The @code{visibility} attribute is described in
-@ref{Common Function Attributes}.
-
-@item weak
-@cindex @code{weak} variable attribute
-The @code{weak} attribute is described in
-@ref{Common Function Attributes}.
-
-@item noinit
-@cindex @code{noinit} variable attribute
-Any data with the @code{noinit} attribute will not be initialized by
-the C runtime startup code, or the program loader. Not initializing
-data in this way can reduce program startup times.
-
-This attribute is specific to ELF targets and relies on the linker
-script to place sections with the @code{.noinit} prefix in the right
-location.
-
-@item persistent
-@cindex @code{persistent} variable attribute
-Any data with the @code{persistent} attribute will not be initialized by
-the C runtime startup code, but will be initialized by the program
-loader. This enables the value of the variable to @samp{persist}
-between processor resets.
-
-This attribute is specific to ELF targets and relies on the linker
-script to place the sections with the @code{.persistent} prefix in the
-right location. Specifically, some type of non-volatile, writeable
-memory is required.
-
-@item objc_nullability (@var{nullability kind}) @r{(Objective-C and Objective-C++ only)}
-@cindex @code{objc_nullability} variable attribute
-This attribute applies to pointer variables only. It allows marking the
-pointer with one of four possible values describing the conditions under
-which the pointer might have a @code{nil} value. In most cases, the
-attribute is intended to be an internal representation for property and
-method nullability (specified by language keywords); it is not recommended
-to use it directly.
-
-When @var{nullability kind} is @code{"unspecified"} or @code{0}, nothing is
-known about the conditions in which the pointer might be @code{nil}. Making
-this state specific serves to avoid false positives in diagnostics.
-
-When @var{nullability kind} is @code{"nonnull"} or @code{1}, the pointer has
-no meaning if it is @code{nil} and thus the compiler is free to emit
-diagnostics if it can be determined that the value will be @code{nil}.
-
-When @var{nullability kind} is @code{"nullable"} or @code{2}, the pointer might
-be @code{nil} and carry meaning as such.
-
-When @var{nullability kind} is @code{"resettable"} or @code{3} (used only in
-the context of property attribute lists) this describes the case in which a
-property setter may take the value @code{nil} (which perhaps causes the
-property to be reset in some manner to a default) but for which the property
-getter will never validly return @code{nil}.
-
-@end table
-
-@node ARC Variable Attributes
-@subsection ARC Variable Attributes
-
-@table @code
-@item aux
-@cindex @code{aux} variable attribute, ARC
-The @code{aux} attribute is used to directly access the ARC's
-auxiliary register space from C. The auxilirary register number is
-given via attribute argument.
-
-@end table
-
-@node AVR Variable Attributes
-@subsection AVR Variable Attributes
-
-@table @code
-@item progmem
-@cindex @code{progmem} variable attribute, AVR
-The @code{progmem} attribute is used on the AVR to place read-only
-data in the non-volatile program memory (flash). The @code{progmem}
-attribute accomplishes this by putting respective variables into a
-section whose name starts with @code{.progmem}.
-
-This attribute works similar to the @code{section} attribute
-but adds additional checking.
-
-@table @asis
-@item @bullet{} Ordinary AVR cores with 32 general purpose registers:
-@code{progmem} affects the location
-of the data but not how this data is accessed.
-In order to read data located with the @code{progmem} attribute
-(inline) assembler must be used.
-@smallexample
-/* Use custom macros from @w{@uref{http://nongnu.org/avr-libc/user-manual/,AVR-LibC}} */
-#include <avr/pgmspace.h>
-
-/* Locate var in flash memory */
-const int var[2] PROGMEM = @{ 1, 2 @};
-
-int read_var (int i)
-@{
- /* Access var[] by accessor macro from avr/pgmspace.h */
- return (int) pgm_read_word (& var[i]);
-@}
-@end smallexample
-
-AVR is a Harvard architecture processor and data and read-only data
-normally resides in the data memory (RAM).
-
-See also the @ref{AVR Named Address Spaces} section for
-an alternate way to locate and access data in flash memory.
-
-@item @bullet{} AVR cores with flash memory visible in the RAM address range:
-On such devices, there is no need for attribute @code{progmem} or
-@ref{AVR Named Address Spaces,,@code{__flash}} qualifier at all.
-Just use standard C / C++. The compiler will generate @code{LD*}
-instructions. As flash memory is visible in the RAM address range,
-and the default linker script does @emph{not} locate @code{.rodata} in
-RAM, no special features are needed in order not to waste RAM for
-read-only data or to read from flash. You might even get slightly better
-performance by
-avoiding @code{progmem} and @code{__flash}. This applies to devices from
-families @code{avrtiny} and @code{avrxmega3}, see @ref{AVR Options} for
-an overview.
-
-@item @bullet{} Reduced AVR Tiny cores like ATtiny40:
-The compiler adds @code{0x4000}
-to the addresses of objects and declarations in @code{progmem} and locates
-the objects in flash memory, namely in section @code{.progmem.data}.
-The offset is needed because the flash memory is visible in the RAM
-address space starting at address @code{0x4000}.
-
-Data in @code{progmem} can be accessed by means of ordinary C@tie{}code,
-no special functions or macros are needed.
-
-@smallexample
-/* var is located in flash memory */
-extern const int var[2] __attribute__((progmem));
-
-int read_var (int i)
-@{
- return var[i];
-@}
-@end smallexample
-
-Please notice that on these devices, there is no need for @code{progmem}
-at all.
-
-@end table
-
-@item io
-@itemx io (@var{addr})
-@cindex @code{io} variable attribute, AVR
-Variables with the @code{io} attribute are used to address
-memory-mapped peripherals in the io address range.
-If an address is specified, the variable
-is assigned that address, and the value is interpreted as an
-address in the data address space.
-Example:
-
-@smallexample
-volatile int porta __attribute__((io (0x22)));
-@end smallexample
-
-The address specified in the address in the data address range.
-
-Otherwise, the variable it is not assigned an address, but the
-compiler will still use in/out instructions where applicable,
-assuming some other module assigns an address in the io address range.
-Example:
-
-@smallexample
-extern volatile int porta __attribute__((io));
-@end smallexample
-
-@item io_low
-@itemx io_low (@var{addr})
-@cindex @code{io_low} variable attribute, AVR
-This is like the @code{io} attribute, but additionally it informs the
-compiler that the object lies in the lower half of the I/O area,
-allowing the use of @code{cbi}, @code{sbi}, @code{sbic} and @code{sbis}
-instructions.
-
-@item address
-@itemx address (@var{addr})
-@cindex @code{address} variable attribute, AVR
-Variables with the @code{address} attribute are used to address
-memory-mapped peripherals that may lie outside the io address range.
-
-@smallexample
-volatile int porta __attribute__((address (0x600)));
-@end smallexample
-
-@item absdata
-@cindex @code{absdata} variable attribute, AVR
-Variables in static storage and with the @code{absdata} attribute can
-be accessed by the @code{LDS} and @code{STS} instructions which take
-absolute addresses.
-
-@itemize @bullet
-@item
-This attribute is only supported for the reduced AVR Tiny core
-like ATtiny40.
-
-@item
-You must make sure that respective data is located in the
-address range @code{0x40}@dots{}@code{0xbf} accessible by
-@code{LDS} and @code{STS}. One way to achieve this as an
-appropriate linker description file.
-
-@item
-If the location does not fit the address range of @code{LDS}
-and @code{STS}, there is currently (Binutils 2.26) just an unspecific
-warning like
-@quotation
-@code{module.cc:(.text+0x1c): warning: internal error: out of range error}
-@end quotation
-
-@end itemize
-
-See also the @option{-mabsdata} @ref{AVR Options,command-line option}.
-
-@end table
-
-@node Blackfin Variable Attributes
-@subsection Blackfin Variable Attributes
-
-Three attributes are currently defined for the Blackfin.
-
-@table @code
-@item l1_data
-@itemx l1_data_A
-@itemx l1_data_B
-@cindex @code{l1_data} variable attribute, Blackfin
-@cindex @code{l1_data_A} variable attribute, Blackfin
-@cindex @code{l1_data_B} variable attribute, Blackfin
-Use these attributes on the Blackfin to place the variable into L1 Data SRAM.
-Variables with @code{l1_data} attribute are put into the specific section
-named @code{.l1.data}. Those with @code{l1_data_A} attribute are put into
-the specific section named @code{.l1.data.A}. Those with @code{l1_data_B}
-attribute are put into the specific section named @code{.l1.data.B}.
-
-@item l2
-@cindex @code{l2} variable attribute, Blackfin
-Use this attribute on the Blackfin to place the variable into L2 SRAM.
-Variables with @code{l2} attribute are put into the specific section
-named @code{.l2.data}.
-@end table
-
-@node H8/300 Variable Attributes
-@subsection H8/300 Variable Attributes
-
-These variable attributes are available for H8/300 targets:
-
-@table @code
-@item eightbit_data
-@cindex @code{eightbit_data} variable attribute, H8/300
-@cindex eight-bit data on the H8/300, H8/300H, and H8S
-Use this attribute on the H8/300, H8/300H, and H8S to indicate that the specified
-variable should be placed into the eight-bit data section.
-The compiler generates more efficient code for certain operations
-on data in the eight-bit data area. Note the eight-bit data area is limited to
-256 bytes of data.
-
-You must use GAS and GLD from GNU binutils version 2.7 or later for
-this attribute to work correctly.
-
-@item tiny_data
-@cindex @code{tiny_data} variable attribute, H8/300
-@cindex tiny data section on the H8/300H and H8S
-Use this attribute on the H8/300H and H8S to indicate that the specified
-variable should be placed into the tiny data section.
-The compiler generates more efficient code for loads and stores
-on data in the tiny data section. Note the tiny data area is limited to
-slightly under 32KB of data.
-
-@end table
-
-@node IA-64 Variable Attributes
-@subsection IA-64 Variable Attributes
-
-The IA-64 back end supports the following variable attribute:
-
-@table @code
-@item model (@var{model-name})
-@cindex @code{model} variable attribute, IA-64
-
-On IA-64, use this attribute to set the addressability of an object.
-At present, the only supported identifier for @var{model-name} is
-@code{small}, indicating addressability via ``small'' (22-bit)
-addresses (so that their addresses can be loaded with the @code{addl}
-instruction). Caveat: such addressing is by definition not position
-independent and hence this attribute must not be used for objects
-defined by shared libraries.
-
-@end table
-
-@node LoongArch Variable Attributes
-@subsection LoongArch Variable Attributes
-
-One attribute is currently defined for the LoongArch.
-
-@table @code
-@item model("@var{name}")
-@cindex @code{model} variable attribute, LoongArch
-Use this attribute on the LoongArch to use a different code model for
-addressing this variable, than the code model specified by the global
-@option{-mcmodel} option. This attribute is mostly useful if a
-@code{section} attribute and/or a linker script will locate this object
-specially. Currently the only supported values of @var{name} are
-@code{normal} and @code{extreme}.
-@end table
-
-@node M32R/D Variable Attributes
-@subsection M32R/D Variable Attributes
-
-One attribute is currently defined for the M32R/D@.
-
-@table @code
-@item model (@var{model-name})
-@cindex @code{model-name} variable attribute, M32R/D
-@cindex variable addressability on the M32R/D
-Use this attribute on the M32R/D to set the addressability of an object.
-The identifier @var{model-name} is one of @code{small}, @code{medium},
-or @code{large}, representing each of the code models.
-
-Small model objects live in the lower 16MB of memory (so that their
-addresses can be loaded with the @code{ld24} instruction).
-
-Medium and large model objects may live anywhere in the 32-bit address space
-(the compiler generates @code{seth/add3} instructions to load their
-addresses).
-@end table
-
-@node MeP Variable Attributes
-@subsection MeP Variable Attributes
-
-The MeP target has a number of addressing modes and busses. The
-@code{near} space spans the standard memory space's first 16 megabytes
-(24 bits). The @code{far} space spans the entire 32-bit memory space.
-The @code{based} space is a 128-byte region in the memory space that
-is addressed relative to the @code{$tp} register. The @code{tiny}
-space is a 65536-byte region relative to the @code{$gp} register. In
-addition to these memory regions, the MeP target has a separate 16-bit
-control bus which is specified with @code{cb} attributes.
-
-@table @code
-
-@item based
-@cindex @code{based} variable attribute, MeP
-Any variable with the @code{based} attribute is assigned to the
-@code{.based} section, and is accessed with relative to the
-@code{$tp} register.
-
-@item tiny
-@cindex @code{tiny} variable attribute, MeP
-Likewise, the @code{tiny} attribute assigned variables to the
-@code{.tiny} section, relative to the @code{$gp} register.
-
-@item near
-@cindex @code{near} variable attribute, MeP
-Variables with the @code{near} attribute are assumed to have addresses
-that fit in a 24-bit addressing mode. This is the default for large
-variables (@code{-mtiny=4} is the default) but this attribute can
-override @code{-mtiny=} for small variables, or override @code{-ml}.
-
-@item far
-@cindex @code{far} variable attribute, MeP
-Variables with the @code{far} attribute are addressed using a full
-32-bit address. Since this covers the entire memory space, this
-allows modules to make no assumptions about where variables might be
-stored.
-
-@item io
-@cindex @code{io} variable attribute, MeP
-@itemx io (@var{addr})
-Variables with the @code{io} attribute are used to address
-memory-mapped peripherals. If an address is specified, the variable
-is assigned that address, else it is not assigned an address (it is
-assumed some other module assigns an address). Example:
-
-@smallexample
-int timer_count __attribute__((io(0x123)));
-@end smallexample
-
-@item cb
-@itemx cb (@var{addr})
-@cindex @code{cb} variable attribute, MeP
-Variables with the @code{cb} attribute are used to access the control
-bus, using special instructions. @code{addr} indicates the control bus
-address. Example:
-
-@smallexample
-int cpu_clock __attribute__((cb(0x123)));
-@end smallexample
-
-@end table
-
-@node Microsoft Windows Variable Attributes
-@subsection Microsoft Windows Variable Attributes
-
-You can use these attributes on Microsoft Windows targets.
-@ref{x86 Variable Attributes} for additional Windows compatibility
-attributes available on all x86 targets.
-
-@table @code
-@item dllimport
-@itemx dllexport
-@cindex @code{dllimport} variable attribute
-@cindex @code{dllexport} variable attribute
-The @code{dllimport} and @code{dllexport} attributes are described in
-@ref{Microsoft Windows Function Attributes}.
-
-@item selectany
-@cindex @code{selectany} variable attribute
-The @code{selectany} attribute causes an initialized global variable to
-have link-once semantics. When multiple definitions of the variable are
-encountered by the linker, the first is selected and the remainder are
-discarded. Following usage by the Microsoft compiler, the linker is told
-@emph{not} to warn about size or content differences of the multiple
-definitions.
-
-Although the primary usage of this attribute is for POD types, the
-attribute can also be applied to global C++ objects that are initialized
-by a constructor. In this case, the static initialization and destruction
-code for the object is emitted in each translation defining the object,
-but the calls to the constructor and destructor are protected by a
-link-once guard variable.
-
-The @code{selectany} attribute is only available on Microsoft Windows
-targets. You can use @code{__declspec (selectany)} as a synonym for
-@code{__attribute__ ((selectany))} for compatibility with other
-compilers.
-
-@item shared
-@cindex @code{shared} variable attribute
-On Microsoft Windows, in addition to putting variable definitions in a named
-section, the section can also be shared among all running copies of an
-executable or DLL@. For example, this small program defines shared data
-by putting it in a named section @code{shared} and marking the section
-shareable:
-
-@smallexample
-int foo __attribute__((section ("shared"), shared)) = 0;
-
-int
-main()
-@{
- /* @r{Read and write foo. All running
- copies see the same value.} */
- return 0;
-@}
-@end smallexample
-
-@noindent
-You may only use the @code{shared} attribute along with @code{section}
-attribute with a fully-initialized global definition because of the way
-linkers work. See @code{section} attribute for more information.
-
-The @code{shared} attribute is only available on Microsoft Windows@.
-
-@end table
-
-@node MSP430 Variable Attributes
-@subsection MSP430 Variable Attributes
-
-@table @code
-@item upper
-@itemx either
-@cindex @code{upper} variable attribute, MSP430
-@cindex @code{either} variable attribute, MSP430
-These attributes are the same as the MSP430 function attributes of the
-same name (@pxref{MSP430 Function Attributes}).
-
-@item lower
-@cindex @code{lower} variable attribute, MSP430
-This option behaves mostly the same as the MSP430 function attribute of the
-same name (@pxref{MSP430 Function Attributes}), but it has some additional
-functionality.
-
-If @option{-mdata-region=}@{@code{upper,either,none}@} has been passed, or
-the @code{section} attribute is applied to a variable, the compiler will
-generate 430X instructions to handle it. This is because the compiler has
-to assume that the variable could get placed in the upper memory region
-(above address 0xFFFF). Marking the variable with the @code{lower} attribute
-informs the compiler that the variable will be placed in lower memory so it
-is safe to use 430 instructions to handle it.
-
-In the case of the @code{section} attribute, the section name given
-will be used, and the @code{.lower} prefix will not be added.
-
-@end table
-
-@node Nvidia PTX Variable Attributes
-@subsection Nvidia PTX Variable Attributes
-
-These variable attributes are supported by the Nvidia PTX back end:
-
-@table @code
-@item shared
-@cindex @code{shared} attribute, Nvidia PTX
-Use this attribute to place a variable in the @code{.shared} memory space.
-This memory space is private to each cooperative thread array; only threads
-within one thread block refer to the same instance of the variable.
-The runtime does not initialize variables in this memory space.
-@end table
-
-@node PowerPC Variable Attributes
-@subsection PowerPC Variable Attributes
-
-Three attributes currently are defined for PowerPC configurations:
-@code{altivec}, @code{ms_struct} and @code{gcc_struct}.
-
-@cindex @code{ms_struct} variable attribute, PowerPC
-@cindex @code{gcc_struct} variable attribute, PowerPC
-For full documentation of the struct attributes please see the
-documentation in @ref{x86 Variable Attributes}.
-
-@cindex @code{altivec} variable attribute, PowerPC
-For documentation of @code{altivec} attribute please see the
-documentation in @ref{PowerPC Type Attributes}.
-
-@node RL78 Variable Attributes
-@subsection RL78 Variable Attributes
-
-@cindex @code{saddr} variable attribute, RL78
-The RL78 back end supports the @code{saddr} variable attribute. This
-specifies placement of the corresponding variable in the SADDR area,
-which can be accessed more efficiently than the default memory region.
-
-@node V850 Variable Attributes
-@subsection V850 Variable Attributes
-
-These variable attributes are supported by the V850 back end:
-
-@table @code
-
-@item sda
-@cindex @code{sda} variable attribute, V850
-Use this attribute to explicitly place a variable in the small data area,
-which can hold up to 64 kilobytes.
-
-@item tda
-@cindex @code{tda} variable attribute, V850
-Use this attribute to explicitly place a variable in the tiny data area,
-which can hold up to 256 bytes in total.
-
-@item zda
-@cindex @code{zda} variable attribute, V850
-Use this attribute to explicitly place a variable in the first 32 kilobytes
-of memory.
-@end table
-
-@node x86 Variable Attributes
-@subsection x86 Variable Attributes
-
-Two attributes are currently defined for x86 configurations:
-@code{ms_struct} and @code{gcc_struct}.
-
-@table @code
-@item ms_struct
-@itemx gcc_struct
-@cindex @code{ms_struct} variable attribute, x86
-@cindex @code{gcc_struct} variable attribute, x86
-
-If @code{packed} is used on a structure, or if bit-fields are used,
-it may be that the Microsoft ABI lays out the structure differently
-than the way GCC normally does. Particularly when moving packed
-data between functions compiled with GCC and the native Microsoft compiler
-(either via function call or as data in a file), it may be necessary to access
-either format.
-
-The @code{ms_struct} and @code{gcc_struct} attributes correspond
-to the @option{-mms-bitfields} and @option{-mno-ms-bitfields}
-command-line options, respectively;
-see @ref{x86 Options}, for details of how structure layout is affected.
-@xref{x86 Type Attributes}, for information about the corresponding
-attributes on types.
-
-@end table
-
-@node Xstormy16 Variable Attributes
-@subsection Xstormy16 Variable Attributes
-
-One attribute is currently defined for xstormy16 configurations:
-@code{below100}.
-
-@table @code
-@item below100
-@cindex @code{below100} variable attribute, Xstormy16
-
-If a variable has the @code{below100} attribute (@code{BELOW100} is
-allowed also), GCC places the variable in the first 0x100 bytes of
-memory and use special opcodes to access it. Such variables are
-placed in either the @code{.bss_below100} section or the
-@code{.data_below100} section.
-
-@end table
-
-@node Type Attributes
-@section Specifying Attributes of Types
-@cindex attribute of types
-@cindex type attributes
-
-The keyword @code{__attribute__} allows you to specify various special
-properties of types. Some type attributes apply only to structure and
-union types, and in C++, also class types, while others can apply to
-any type defined via a @code{typedef} declaration. Unless otherwise
-specified, the same restrictions and effects apply to attributes regardless
-of whether a type is a trivial structure or a C++ class with user-defined
-constructors, destructors, or a copy assignment.
-
-Other attributes are defined for functions (@pxref{Function Attributes}),
-labels (@pxref{Label Attributes}), enumerators (@pxref{Enumerator
-Attributes}), statements (@pxref{Statement Attributes}), and for variables
-(@pxref{Variable Attributes}).
-
-The @code{__attribute__} keyword is followed by an attribute specification
-enclosed in double parentheses.
-
-You may specify type attributes in an enum, struct or union type
-declaration or definition by placing them immediately after the
-@code{struct}, @code{union} or @code{enum} keyword. You can also place
-them just past the closing curly brace of the definition, but this is less
-preferred because logically the type should be fully defined at
-the closing brace.
-
-You can also include type attributes in a @code{typedef} declaration.
-@xref{Attribute Syntax}, for details of the exact syntax for using
-attributes.
-
-@menu
-* Common Type Attributes::
-* ARC Type Attributes::
-* ARM Type Attributes::
-* BPF Type Attributes::
-* MeP Type Attributes::
-* PowerPC Type Attributes::
-* x86 Type Attributes::
-@end menu
-
-@node Common Type Attributes
-@subsection Common Type Attributes
-
-The following type attributes are supported on most targets.
-
-@table @code
-@cindex @code{aligned} type attribute
-@item aligned
-@itemx aligned (@var{alignment})
-The @code{aligned} attribute specifies a minimum alignment (in bytes) for
-variables of the specified type. When specified, @var{alignment} must be
-a power of 2. Specifying no @var{alignment} argument implies the maximum
-alignment for the target, which is often, but by no means always, 8 or 16
-bytes. For example, the declarations:
-
-@smallexample
-struct __attribute__ ((aligned (8))) S @{ short f[3]; @};
-typedef int more_aligned_int __attribute__ ((aligned (8)));
-@end smallexample
-
-@noindent
-force the compiler to ensure (as far as it can) that each variable whose
-type is @code{struct S} or @code{more_aligned_int} is allocated and
-aligned @emph{at least} on a 8-byte boundary. On a SPARC, having all
-variables of type @code{struct S} aligned to 8-byte boundaries allows
-the compiler to use the @code{ldd} and @code{std} (doubleword load and
-store) instructions when copying one variable of type @code{struct S} to
-another, thus improving run-time efficiency.
-
-Note that the alignment of any given @code{struct} or @code{union} type
-is required by the ISO C standard to be at least a perfect multiple of
-the lowest common multiple of the alignments of all of the members of
-the @code{struct} or @code{union} in question. This means that you @emph{can}
-effectively adjust the alignment of a @code{struct} or @code{union}
-type by attaching an @code{aligned} attribute to any one of the members
-of such a type, but the notation illustrated in the example above is a
-more obvious, intuitive, and readable way to request the compiler to
-adjust the alignment of an entire @code{struct} or @code{union} type.
-
-As in the preceding example, you can explicitly specify the alignment
-(in bytes) that you wish the compiler to use for a given @code{struct}
-or @code{union} type. Alternatively, you can leave out the alignment factor
-and just ask the compiler to align a type to the maximum
-useful alignment for the target machine you are compiling for. For
-example, you could write:
-
-@smallexample
-struct __attribute__ ((aligned)) S @{ short f[3]; @};
-@end smallexample
-
-Whenever you leave out the alignment factor in an @code{aligned}
-attribute specification, the compiler automatically sets the alignment
-for the type to the largest alignment that is ever used for any data
-type on the target machine you are compiling for. Doing this can often
-make copy operations more efficient, because the compiler can use
-whatever instructions copy the biggest chunks of memory when performing
-copies to or from the variables that have types that you have aligned
-this way.
-
-In the example above, if the size of each @code{short} is 2 bytes, then
-the size of the entire @code{struct S} type is 6 bytes. The smallest
-power of two that is greater than or equal to that is 8, so the
-compiler sets the alignment for the entire @code{struct S} type to 8
-bytes.
-
-Note that although you can ask the compiler to select a time-efficient
-alignment for a given type and then declare only individual stand-alone
-objects of that type, the compiler's ability to select a time-efficient
-alignment is primarily useful only when you plan to create arrays of
-variables having the relevant (efficiently aligned) type. If you
-declare or use arrays of variables of an efficiently-aligned type, then
-it is likely that your program also does pointer arithmetic (or
-subscripting, which amounts to the same thing) on pointers to the
-relevant type, and the code that the compiler generates for these
-pointer arithmetic operations is often more efficient for
-efficiently-aligned types than for other types.
-
-Note that the effectiveness of @code{aligned} attributes may be limited
-by inherent limitations in your linker. On many systems, the linker is
-only able to arrange for variables to be aligned up to a certain maximum
-alignment. (For some linkers, the maximum supported alignment may
-be very very small.) If your linker is only able to align variables
-up to a maximum of 8-byte alignment, then specifying @code{aligned (16)}
-in an @code{__attribute__} still only provides you with 8-byte
-alignment. See your linker documentation for further information.
-
-When used on a struct, or struct member, the @code{aligned} attribute can
-only increase the alignment; in order to decrease it, the @code{packed}
-attribute must be specified as well. When used as part of a typedef, the
-@code{aligned} attribute can both increase and decrease alignment, and
-specifying the @code{packed} attribute generates a warning.
-
-@cindex @code{warn_if_not_aligned} type attribute
-@item warn_if_not_aligned (@var{alignment})
-This attribute specifies a threshold for the structure field, measured
-in bytes. If the structure field is aligned below the threshold, a
-warning will be issued. For example, the declaration:
-
-@smallexample
-typedef unsigned long long __u64
- __attribute__((aligned (4), warn_if_not_aligned (8)));
-
-struct foo
-@{
- int i1;
- int i2;
- __u64 x;
-@};
-@end smallexample
-
-@noindent
-causes the compiler to issue an warning on @code{struct foo}, like
-@samp{warning: alignment 4 of 'struct foo' is less than 8}.
-It is used to define @code{struct foo} in such a way that
-@code{struct foo} has the same layout and the structure field @code{x}
-has the same alignment when @code{__u64} is aligned at either 4 or
-8 bytes. Align @code{struct foo} to 8 bytes:
-
-@smallexample
-struct __attribute__ ((aligned (8))) foo
-@{
- int i1;
- int i2;
- __u64 x;
-@};
-@end smallexample
-
-@noindent
-silences the warning. The compiler also issues a warning, like
-@samp{warning: 'x' offset 12 in 'struct foo' isn't aligned to 8},
-when the structure field has the misaligned offset:
-
-@smallexample
-struct __attribute__ ((aligned (8))) foo
-@{
- int i1;
- int i2;
- int i3;
- __u64 x;
-@};
-@end smallexample
-
-This warning can be disabled by @option{-Wno-if-not-aligned}.
-
-@item alloc_size (@var{position})
-@itemx alloc_size (@var{position-1}, @var{position-2})
-@cindex @code{alloc_size} type attribute
-The @code{alloc_size} type attribute may be applied to the definition
-of a type of a function that returns a pointer and takes at least one
-argument of an integer type. It indicates that the returned pointer
-points to an object whose size is given by the function argument at
-@var{position-1}, or by the product of the arguments at @var{position-1}
-and @var{position-2}. Meaningful sizes are positive values less than
-@code{PTRDIFF_MAX}. Other sizes are disagnosed when detected. GCC uses
-this information to improve the results of @code{__builtin_object_size}.
-
-For instance, the following declarations
-
-@smallexample
-typedef __attribute__ ((alloc_size (1, 2))) void*
- calloc_type (size_t, size_t);
-typedef __attribute__ ((alloc_size (1))) void*
- malloc_type (size_t);
-@end smallexample
-
-@noindent
-specify that @code{calloc_type} is a type of a function that, like
-the standard C function @code{calloc}, returns an object whose size
-is given by the product of arguments 1 and 2, and that
-@code{malloc_type}, like the standard C function @code{malloc},
-returns an object whose size is given by argument 1 to the function.
-
-@item copy
-@itemx copy (@var{expression})
-@cindex @code{copy} type attribute
-The @code{copy} attribute applies the set of attributes with which
-the type of the @var{expression} has been declared to the declaration
-of the type to which the attribute is applied. The attribute is
-designed for libraries that define aliases that are expected to
-specify the same set of attributes as the aliased symbols.
-The @code{copy} attribute can be used with types, variables, or
-functions. However, the kind of symbol to which the attribute is
-applied (either varible or function) must match the kind of symbol
-to which the argument refers.
-The @code{copy} attribute copies only syntactic and semantic attributes
-but not attributes that affect a symbol's linkage or visibility such as
-@code{alias}, @code{visibility}, or @code{weak}. The @code{deprecated}
-attribute is also not copied. @xref{Common Function Attributes}.
-@xref{Common Variable Attributes}.
-
-For example, suppose @code{struct A} below is defined in some third
-party library header to have the alignment requirement @code{N} and
-to force a warning whenever a variable of the type is not so aligned
-due to attribute @code{packed}. Specifying the @code{copy} attribute
-on the definition on the unrelated @code{struct B} has the effect of
-copying all relevant attributes from the type referenced by the pointer
-expression to @code{struct B}.
-
-@smallexample
-struct __attribute__ ((aligned (N), warn_if_not_aligned (N)))
-A @{ /* @r{@dots{}} */ @};
-struct __attribute__ ((copy ( (struct A *)0)) B @{ /* @r{@dots{}} */ @};
-@end smallexample
-
-@item deprecated
-@itemx deprecated (@var{msg})
-@cindex @code{deprecated} type attribute
-The @code{deprecated} attribute results in a warning if the type
-is used anywhere in the source file. This is useful when identifying
-types that are expected to be removed in a future version of a program.
-If possible, the warning also includes the location of the declaration
-of the deprecated type, to enable users to easily find further
-information about why the type is deprecated, or what they should do
-instead. Note that the warnings only occur for uses and then only
-if the type is being applied to an identifier that itself is not being
-declared as deprecated.
-
-@smallexample
-typedef int T1 __attribute__ ((deprecated));
-T1 x;
-typedef T1 T2;
-T2 y;
-typedef T1 T3 __attribute__ ((deprecated));
-T3 z __attribute__ ((deprecated));
-@end smallexample
-
-@noindent
-results in a warning on line 2 and 3 but not lines 4, 5, or 6. No
-warning is issued for line 4 because T2 is not explicitly
-deprecated. Line 5 has no warning because T3 is explicitly
-deprecated. Similarly for line 6. The optional @var{msg}
-argument, which must be a string, is printed in the warning if
-present. Control characters in the string will be replaced with
-escape sequences, and if the @option{-fmessage-length} option is set
-to 0 (its default value) then any newline characters will be ignored.
-
-The @code{deprecated} attribute can also be used for functions and
-variables (@pxref{Function Attributes}, @pxref{Variable Attributes}.)
-
-The message attached to the attribute is affected by the setting of
-the @option{-fmessage-length} option.
-
-@item unavailable
-@itemx unavailable (@var{msg})
-@cindex @code{unavailable} type attribute
-The @code{unavailable} attribute behaves in the same manner as the
-@code{deprecated} one, but emits an error rather than a warning. It is
-used to indicate that a (perhaps previously @code{deprecated}) type is
-no longer usable.
-
-The @code{unavailable} attribute can also be used for functions and
-variables (@pxref{Function Attributes}, @pxref{Variable Attributes}.)
-
-@item designated_init
-@cindex @code{designated_init} type attribute
-This attribute may only be applied to structure types. It indicates
-that any initialization of an object of this type must use designated
-initializers rather than positional initializers. The intent of this
-attribute is to allow the programmer to indicate that a structure's
-layout may change, and that therefore relying on positional
-initialization will result in future breakage.
-
-GCC emits warnings based on this attribute by default; use
-@option{-Wno-designated-init} to suppress them.
-
-@item may_alias
-@cindex @code{may_alias} type attribute
-Accesses through pointers to types with this attribute are not subject
-to type-based alias analysis, but are instead assumed to be able to alias
-any other type of objects.
-In the context of section 6.5 paragraph 7 of the C99 standard,
-an lvalue expression
-dereferencing such a pointer is treated like having a character type.
-See @option{-fstrict-aliasing} for more information on aliasing issues.
-This extension exists to support some vector APIs, in which pointers to
-one vector type are permitted to alias pointers to a different vector type.
-
-Note that an object of a type with this attribute does not have any
-special semantics.
-
-Example of use:
-
-@smallexample
-typedef short __attribute__ ((__may_alias__)) short_a;
-
-int
-main (void)
-@{
- int a = 0x12345678;
- short_a *b = (short_a *) &a;
-
- b[1] = 0;
-
- if (a == 0x12345678)
- abort();
-
- exit(0);
-@}
-@end smallexample
-
-@noindent
-If you replaced @code{short_a} with @code{short} in the variable
-declaration, the above program would abort when compiled with
-@option{-fstrict-aliasing}, which is on by default at @option{-O2} or
-above.
-
-@item mode (@var{mode})
-@cindex @code{mode} type attribute
-This attribute specifies the data type for the declaration---whichever
-type corresponds to the mode @var{mode}. This in effect lets you
-request an integer or floating-point type according to its width.
-
-@xref{Machine Modes,,, gccint, GNU Compiler Collection (GCC) Internals},
-for a list of the possible keywords for @var{mode}.
-You may also specify a mode of @code{byte} or @code{__byte__} to
-indicate the mode corresponding to a one-byte integer, @code{word} or
-@code{__word__} for the mode of a one-word integer, and @code{pointer}
-or @code{__pointer__} for the mode used to represent pointers.
-
-@item packed
-@cindex @code{packed} type attribute
-This attribute, attached to a @code{struct}, @code{union}, or C++ @code{class}
-type definition, specifies that each of its members (other than zero-width
-bit-fields) is placed to minimize the memory required. This is equivalent
-to specifying the @code{packed} attribute on each of the members.
-
-@opindex fshort-enums
-When attached to an @code{enum} definition, the @code{packed} attribute
-indicates that the smallest integral type should be used.
-Specifying the @option{-fshort-enums} flag on the command line
-is equivalent to specifying the @code{packed}
-attribute on all @code{enum} definitions.
-
-In the following example @code{struct my_packed_struct}'s members are
-packed closely together, but the internal layout of its @code{s} member
-is not packed---to do that, @code{struct my_unpacked_struct} needs to
-be packed too.
-
-@smallexample
-struct my_unpacked_struct
- @{
- char c;
- int i;
- @};
-
-struct __attribute__ ((__packed__)) my_packed_struct
- @{
- char c;
- int i;
- struct my_unpacked_struct s;
- @};
-@end smallexample
-
-You may only specify the @code{packed} attribute on the definition
-of an @code{enum}, @code{struct}, @code{union}, or @code{class},
-not on a @code{typedef} that does not also define the enumerated type,
-structure, union, or class.
-
-@item scalar_storage_order ("@var{endianness}")
-@cindex @code{scalar_storage_order} type attribute
-When attached to a @code{union} or a @code{struct}, this attribute sets
-the storage order, aka endianness, of the scalar fields of the type, as
-well as the array fields whose component is scalar. The supported
-endiannesses are @code{big-endian} and @code{little-endian}. The attribute
-has no effects on fields which are themselves a @code{union}, a @code{struct}
-or an array whose component is a @code{union} or a @code{struct}, and it is
-possible for these fields to have a different scalar storage order than the
-enclosing type.
-
-Note that neither pointer nor vector fields are considered scalar fields in
-this context, so the attribute has no effects on these fields.
-
-This attribute is supported only for targets that use a uniform default
-scalar storage order (fortunately, most of them), i.e.@: targets that store
-the scalars either all in big-endian or all in little-endian.
-
-Additional restrictions are enforced for types with the reverse scalar
-storage order with regard to the scalar storage order of the target:
-
-@itemize
-@item Taking the address of a scalar field of a @code{union} or a
-@code{struct} with reverse scalar storage order is not permitted and yields
-an error.
-@item Taking the address of an array field, whose component is scalar, of
-a @code{union} or a @code{struct} with reverse scalar storage order is
-permitted but yields a warning, unless @option{-Wno-scalar-storage-order}
-is specified.
-@item Taking the address of a @code{union} or a @code{struct} with reverse
-scalar storage order is permitted.
-@end itemize
-
-These restrictions exist because the storage order attribute is lost when
-the address of a scalar or the address of an array with scalar component is
-taken, so storing indirectly through this address generally does not work.
-The second case is nevertheless allowed to be able to perform a block copy
-from or to the array.
-
-Moreover, the use of type punning or aliasing to toggle the storage order
-is not supported; that is to say, if a given scalar object can be accessed
-through distinct types that assign a different storage order to it, then the
-behavior is undefined.
-
-@item transparent_union
-@cindex @code{transparent_union} type attribute
-
-This attribute, attached to a @code{union} type definition, indicates
-that any function parameter having that union type causes calls to that
-function to be treated in a special way.
-
-First, the argument corresponding to a transparent union type can be of
-any type in the union; no cast is required. Also, if the union contains
-a pointer type, the corresponding argument can be a null pointer
-constant or a void pointer expression; and if the union contains a void
-pointer type, the corresponding argument can be any pointer expression.
-If the union member type is a pointer, qualifiers like @code{const} on
-the referenced type must be respected, just as with normal pointer
-conversions.
-
-Second, the argument is passed to the function using the calling
-conventions of the first member of the transparent union, not the calling
-conventions of the union itself. All members of the union must have the
-same machine representation; this is necessary for this argument passing
-to work properly.
-
-Transparent unions are designed for library functions that have multiple
-interfaces for compatibility reasons. For example, suppose the
-@code{wait} function must accept either a value of type @code{int *} to
-comply with POSIX, or a value of type @code{union wait *} to comply with
-the 4.1BSD interface. If @code{wait}'s parameter were @code{void *},
-@code{wait} would accept both kinds of arguments, but it would also
-accept any other pointer type and this would make argument type checking
-less useful. Instead, @code{<sys/wait.h>} might define the interface
-as follows:
-
-@smallexample
-typedef union __attribute__ ((__transparent_union__))
- @{
- int *__ip;
- union wait *__up;
- @} wait_status_ptr_t;
-
-pid_t wait (wait_status_ptr_t);
-@end smallexample
-
-@noindent
-This interface allows either @code{int *} or @code{union wait *}
-arguments to be passed, using the @code{int *} calling convention.
-The program can call @code{wait} with arguments of either type:
-
-@smallexample
-int w1 () @{ int w; return wait (&w); @}
-int w2 () @{ union wait w; return wait (&w); @}
-@end smallexample
-
-@noindent
-With this interface, @code{wait}'s implementation might look like this:
-
-@smallexample
-pid_t wait (wait_status_ptr_t p)
-@{
- return waitpid (-1, p.__ip, 0);
-@}
-@end smallexample
-
-@item unused
-@cindex @code{unused} type attribute
-When attached to a type (including a @code{union} or a @code{struct}),
-this attribute means that variables of that type are meant to appear
-possibly unused. GCC does not produce a warning for any variables of
-that type, even if the variable appears to do nothing. This is often
-the case with lock or thread classes, which are usually defined and then
-not referenced, but contain constructors and destructors that have
-nontrivial bookkeeping functions.
-
-@item vector_size (@var{bytes})
-@cindex @code{vector_size} type attribute
-This attribute specifies the vector size for the type, measured in bytes.
-The type to which it applies is known as the @dfn{base type}. The @var{bytes}
-argument must be a positive power-of-two multiple of the base type size. For
-example, the following declarations:
-
-@smallexample
-typedef __attribute__ ((vector_size (32))) int int_vec32_t ;
-typedef __attribute__ ((vector_size (32))) int* int_vec32_ptr_t;
-typedef __attribute__ ((vector_size (32))) int int_vec32_arr3_t[3];
-@end smallexample
-
-@noindent
-define @code{int_vec32_t} to be a 32-byte vector type composed of @code{int}
-sized units. With @code{int} having a size of 4 bytes, the type defines
-a vector of eight units, four bytes each. The mode of variables of type
-@code{int_vec32_t} is @code{V8SI}. @code{int_vec32_ptr_t} is then defined
-to be a pointer to such a vector type, and @code{int_vec32_arr3_t} to be
-an array of three such vectors. @xref{Vector Extensions}, for details of
-manipulating objects of vector types.
-
-This attribute is only applicable to integral and floating scalar types.
-In function declarations the attribute applies to the function return
-type.
-
-For example, the following:
-@smallexample
-__attribute__ ((vector_size (16))) float get_flt_vec16 (void);
-@end smallexample
-declares @code{get_flt_vec16} to be a function returning a 16-byte vector
-with the base type @code{float}.
-
-@item visibility
-@cindex @code{visibility} type attribute
-In C++, attribute visibility (@pxref{Function Attributes}) can also be
-applied to class, struct, union and enum types. Unlike other type
-attributes, the attribute must appear between the initial keyword and
-the name of the type; it cannot appear after the body of the type.
-
-Note that the type visibility is applied to vague linkage entities
-associated with the class (vtable, typeinfo node, etc.). In
-particular, if a class is thrown as an exception in one shared object
-and caught in another, the class must have default visibility.
-Otherwise the two shared objects are unable to use the same
-typeinfo node and exception handling will break.
-
-@item objc_root_class @r{(Objective-C and Objective-C++ only)}
-@cindex @code{objc_root_class} type attribute
-This attribute marks a class as being a root class, and thus allows
-the compiler to elide any warnings about a missing superclass and to
-make additional checks for mandatory methods as needed.
-
-@end table
-
-To specify multiple attributes, separate them by commas within the
-double parentheses: for example, @samp{__attribute__ ((aligned (16),
-packed))}.
-
-@node ARC Type Attributes
-@subsection ARC Type Attributes
-
-@cindex @code{uncached} type attribute, ARC
-Declaring objects with @code{uncached} allows you to exclude
-data-cache participation in load and store operations on those objects
-without involving the additional semantic implications of
-@code{volatile}. The @code{.di} instruction suffix is used for all
-loads and stores of data declared @code{uncached}.
-
-@node ARM Type Attributes
-@subsection ARM Type Attributes
-
-@cindex @code{notshared} type attribute, ARM
-On those ARM targets that support @code{dllimport} (such as Symbian
-OS), you can use the @code{notshared} attribute to indicate that the
-virtual table and other similar data for a class should not be
-exported from a DLL@. For example:
-
-@smallexample
-class __declspec(notshared) C @{
-public:
- __declspec(dllimport) C();
- virtual void f();
-@}
-
-__declspec(dllexport)
-C::C() @{@}
-@end smallexample
-
-@noindent
-In this code, @code{C::C} is exported from the current DLL, but the
-virtual table for @code{C} is not exported. (You can use
-@code{__attribute__} instead of @code{__declspec} if you prefer, but
-most Symbian OS code uses @code{__declspec}.)
-
-@node BPF Type Attributes
-@subsection BPF Type Attributes
-
-@cindex @code{preserve_access_index} type attribute, BPF
-BPF Compile Once - Run Everywhere (CO-RE) support. When attached to a
-@code{struct} or @code{union} type definition, indicates that CO-RE
-relocation information should be generated for any access to a variable
-of that type. The behavior is equivalent to the programmer manually
-wrapping every such access with @code{__builtin_preserve_access_index}.
-
-
-@node MeP Type Attributes
-@subsection MeP Type Attributes
-
-@cindex @code{based} type attribute, MeP
-@cindex @code{tiny} type attribute, MeP
-@cindex @code{near} type attribute, MeP
-@cindex @code{far} type attribute, MeP
-Many of the MeP variable attributes may be applied to types as well.
-Specifically, the @code{based}, @code{tiny}, @code{near}, and
-@code{far} attributes may be applied to either. The @code{io} and
-@code{cb} attributes may not be applied to types.
-
-@node PowerPC Type Attributes
-@subsection PowerPC Type Attributes
-
-Three attributes currently are defined for PowerPC configurations:
-@code{altivec}, @code{ms_struct} and @code{gcc_struct}.
-
-@cindex @code{ms_struct} type attribute, PowerPC
-@cindex @code{gcc_struct} type attribute, PowerPC
-For full documentation of the @code{ms_struct} and @code{gcc_struct}
-attributes please see the documentation in @ref{x86 Type Attributes}.
-
-@cindex @code{altivec} type attribute, PowerPC
-The @code{altivec} attribute allows one to declare AltiVec vector data
-types supported by the AltiVec Programming Interface Manual. The
-attribute requires an argument to specify one of three vector types:
-@code{vector__}, @code{pixel__} (always followed by unsigned short),
-and @code{bool__} (always followed by unsigned).
-
-@smallexample
-__attribute__((altivec(vector__)))
-__attribute__((altivec(pixel__))) unsigned short
-__attribute__((altivec(bool__))) unsigned
-@end smallexample
-
-These attributes mainly are intended to support the @code{__vector},
-@code{__pixel}, and @code{__bool} AltiVec keywords.
-
-@node x86 Type Attributes
-@subsection x86 Type Attributes
-
-Two attributes are currently defined for x86 configurations:
-@code{ms_struct} and @code{gcc_struct}.
-
-@table @code
-
-@item ms_struct
-@itemx gcc_struct
-@cindex @code{ms_struct} type attribute, x86
-@cindex @code{gcc_struct} type attribute, x86
-
-If @code{packed} is used on a structure, or if bit-fields are used
-it may be that the Microsoft ABI packs them differently
-than GCC normally packs them. Particularly when moving packed
-data between functions compiled with GCC and the native Microsoft compiler
-(either via function call or as data in a file), it may be necessary to access
-either format.
-
-The @code{ms_struct} and @code{gcc_struct} attributes correspond
-to the @option{-mms-bitfields} and @option{-mno-ms-bitfields}
-command-line options, respectively;
-see @ref{x86 Options}, for details of how structure layout is affected.
-@xref{x86 Variable Attributes}, for information about the corresponding
-attributes on variables.
-
-@end table
-
-@node Label Attributes
-@section Label Attributes
-@cindex Label Attributes
-
-GCC allows attributes to be set on C labels. @xref{Attribute Syntax}, for
-details of the exact syntax for using attributes. Other attributes are
-available for functions (@pxref{Function Attributes}), variables
-(@pxref{Variable Attributes}), enumerators (@pxref{Enumerator Attributes}),
-statements (@pxref{Statement Attributes}), and for types
-(@pxref{Type Attributes}). A label attribute followed
-by a declaration appertains to the label and not the declaration.
-
-This example uses the @code{cold} label attribute to indicate the
-@code{ErrorHandling} branch is unlikely to be taken and that the
-@code{ErrorHandling} label is unused:
-
-@smallexample
-
- asm goto ("some asm" : : : : NoError);
-
-/* This branch (the fall-through from the asm) is less commonly used */
-ErrorHandling:
- __attribute__((cold, unused)); /* Semi-colon is required here */
- printf("error\n");
- return 0;
-
-NoError:
- printf("no error\n");
- return 1;
-@end smallexample
-
-@table @code
-@item unused
-@cindex @code{unused} label attribute
-This feature is intended for program-generated code that may contain
-unused labels, but which is compiled with @option{-Wall}. It is
-not normally appropriate to use in it human-written code, though it
-could be useful in cases where the code that jumps to the label is
-contained within an @code{#ifdef} conditional.
-
-@item hot
-@cindex @code{hot} label attribute
-The @code{hot} attribute on a label is used to inform the compiler that
-the path following the label is more likely than paths that are not so
-annotated. This attribute is used in cases where @code{__builtin_expect}
-cannot be used, for instance with computed goto or @code{asm goto}.
-
-@item cold
-@cindex @code{cold} label attribute
-The @code{cold} attribute on labels is used to inform the compiler that
-the path following the label is unlikely to be executed. This attribute
-is used in cases where @code{__builtin_expect} cannot be used, for instance
-with computed goto or @code{asm goto}.
-
-@end table
-
-@node Enumerator Attributes
-@section Enumerator Attributes
-@cindex Enumerator Attributes
-
-GCC allows attributes to be set on enumerators. @xref{Attribute Syntax}, for
-details of the exact syntax for using attributes. Other attributes are
-available for functions (@pxref{Function Attributes}), variables
-(@pxref{Variable Attributes}), labels (@pxref{Label Attributes}), statements
-(@pxref{Statement Attributes}), and for types (@pxref{Type Attributes}).
-
-This example uses the @code{deprecated} enumerator attribute to indicate the
-@code{oldval} enumerator is deprecated:
-
-@smallexample
-enum E @{
- oldval __attribute__((deprecated)),
- newval
-@};
-
-int
-fn (void)
-@{
- return oldval;
-@}
-@end smallexample
-
-@table @code
-@item deprecated
-@cindex @code{deprecated} enumerator attribute
-The @code{deprecated} attribute results in a warning if the enumerator
-is used anywhere in the source file. This is useful when identifying
-enumerators that are expected to be removed in a future version of a
-program. The warning also includes the location of the declaration
-of the deprecated enumerator, to enable users to easily find further
-information about why the enumerator is deprecated, or what they should
-do instead. Note that the warnings only occurs for uses.
-
-@item unavailable
-@cindex @code{unavailable} enumerator attribute
-The @code{unavailable} attribute results in an error if the enumerator
-is used anywhere in the source file. In other respects it behaves in the
-same manner as the @code{deprecated} attribute.
-
-@end table
-
-@node Statement Attributes
-@section Statement Attributes
-@cindex Statement Attributes
-
-GCC allows attributes to be set on null statements. @xref{Attribute Syntax},
-for details of the exact syntax for using attributes. Other attributes are
-available for functions (@pxref{Function Attributes}), variables
-(@pxref{Variable Attributes}), labels (@pxref{Label Attributes}), enumerators
-(@pxref{Enumerator Attributes}), and for types (@pxref{Type Attributes}).
-
-@table @code
-@item fallthrough
-@cindex @code{fallthrough} statement attribute
-The @code{fallthrough} attribute with a null statement serves as a
-fallthrough statement. It hints to the compiler that a statement
-that falls through to another case label, or user-defined label
-in a switch statement is intentional and thus the
-@option{-Wimplicit-fallthrough} warning must not trigger. The
-fallthrough attribute may appear at most once in each attribute
-list, and may not be mixed with other attributes. It can only
-be used in a switch statement (the compiler will issue an error
-otherwise), after a preceding statement and before a logically
-succeeding case label, or user-defined label.
-
-This example uses the @code{fallthrough} statement attribute to indicate that
-the @option{-Wimplicit-fallthrough} warning should not be emitted:
-
-@smallexample
-switch (cond)
- @{
- case 1:
- bar (1);
- __attribute__((fallthrough));
- case 2:
- @dots{}
- @}
-@end smallexample
-
-@item assume
-@cindex @code{assume} statement attribute
-The @code{assume} attribute with a null statement serves as portable
-assumption. It should have a single argument, a conditional expression,
-which is not evaluated. If the argument would evaluate to true
-at the point where it appears, it has no effect, otherwise there
-is undefined behavior. This is a GNU variant of the ISO C++23
-standard @code{assume} attribute, but it can be used in any version of
-both C and C++.
-
-@smallexample
-int
-foo (int x, int y)
-@{
- __attribute__((assume(x == 42)));
- __attribute__((assume(++y == 43)));
- return x + y;
-@}
-@end smallexample
-
-@code{y} is not actually incremented and the compiler can but does not
-have to optimize it to just @code{return 42 + 42;}.
-
-@end table
-
-@node Attribute Syntax
-@section Attribute Syntax
-@cindex attribute syntax
-
-This section describes the syntax with which @code{__attribute__} may be
-used, and the constructs to which attribute specifiers bind, for the C
-language. Some details may vary for C++ and Objective-C@. Because of
-infelicities in the grammar for attributes, some forms described here
-may not be successfully parsed in all cases.
-
-There are some problems with the semantics of attributes in C++. For
-example, there are no manglings for attributes, although they may affect
-code generation, so problems may arise when attributed types are used in
-conjunction with templates or overloading. Similarly, @code{typeid}
-does not distinguish between types with different attributes. Support
-for attributes in C++ may be restricted in future to attributes on
-declarations only, but not on nested declarators.
-
-@xref{Function Attributes}, for details of the semantics of attributes
-applying to functions. @xref{Variable Attributes}, for details of the
-semantics of attributes applying to variables. @xref{Type Attributes},
-for details of the semantics of attributes applying to structure, union
-and enumerated types.
-@xref{Label Attributes}, for details of the semantics of attributes
-applying to labels.
-@xref{Enumerator Attributes}, for details of the semantics of attributes
-applying to enumerators.
-@xref{Statement Attributes}, for details of the semantics of attributes
-applying to statements.
-
-An @dfn{attribute specifier} is of the form
-@code{__attribute__ ((@var{attribute-list}))}. An @dfn{attribute list}
-is a possibly empty comma-separated sequence of @dfn{attributes}, where
-each attribute is one of the following:
-
-@itemize @bullet
-@item
-Empty. Empty attributes are ignored.
-
-@item
-An attribute name
-(which may be an identifier such as @code{unused}, or a reserved
-word such as @code{const}).
-
-@item
-An attribute name followed by a parenthesized list of
-parameters for the attribute.
-These parameters take one of the following forms:
-
-@itemize @bullet
-@item
-An identifier. For example, @code{mode} attributes use this form.
-
-@item
-An identifier followed by a comma and a non-empty comma-separated list
-of expressions. For example, @code{format} attributes use this form.
-
-@item
-A possibly empty comma-separated list of expressions. For example,
-@code{format_arg} attributes use this form with the list being a single
-integer constant expression, and @code{alias} attributes use this form
-with the list being a single string constant.
-@end itemize
-@end itemize
-
-An @dfn{attribute specifier list} is a sequence of one or more attribute
-specifiers, not separated by any other tokens.
-
-You may optionally specify attribute names with @samp{__}
-preceding and following the name.
-This allows you to use them in header files without
-being concerned about a possible macro of the same name. For example,
-you may use the attribute name @code{__noreturn__} instead of @code{noreturn}.
-
-
-@subsubheading Label Attributes
-
-In GNU C, an attribute specifier list may appear after the colon following a
-label, other than a @code{case} or @code{default} label. GNU C++ only permits
-attributes on labels if the attribute specifier is immediately
-followed by a semicolon (i.e., the label applies to an empty
-statement). If the semicolon is missing, C++ label attributes are
-ambiguous, as it is permissible for a declaration, which could begin
-with an attribute list, to be labelled in C++. Declarations cannot be
-labelled in C90 or C99, so the ambiguity does not arise there.
-
-@subsubheading Enumerator Attributes
-
-In GNU C, an attribute specifier list may appear as part of an enumerator.
-The attribute goes after the enumeration constant, before @code{=}, if
-present. The optional attribute in the enumerator appertains to the
-enumeration constant. It is not possible to place the attribute after
-the constant expression, if present.
-
-@subsubheading Statement Attributes
-In GNU C, an attribute specifier list may appear as part of a null
-statement. The attribute goes before the semicolon.
-
-@subsubheading Type Attributes
-
-An attribute specifier list may appear as part of a @code{struct},
-@code{union} or @code{enum} specifier. It may go either immediately
-after the @code{struct}, @code{union} or @code{enum} keyword, or after
-the closing brace. The former syntax is preferred.
-Where attribute specifiers follow the closing brace, they are considered
-to relate to the structure, union or enumerated type defined, not to any
-enclosing declaration the type specifier appears in, and the type
-defined is not complete until after the attribute specifiers.
-@c Otherwise, there would be the following problems: a shift/reduce
-@c conflict between attributes binding the struct/union/enum and
-@c binding to the list of specifiers/qualifiers; and "aligned"
-@c attributes could use sizeof for the structure, but the size could be
-@c changed later by "packed" attributes.
-
-
-@subsubheading All other attributes
-
-Otherwise, an attribute specifier appears as part of a declaration,
-counting declarations of unnamed parameters and type names, and relates
-to that declaration (which may be nested in another declaration, for
-example in the case of a parameter declaration), or to a particular declarator
-within a declaration. Where an
-attribute specifier is applied to a parameter declared as a function or
-an array, it should apply to the function or array rather than the
-pointer to which the parameter is implicitly converted, but this is not
-yet correctly implemented.
-
-Any list of specifiers and qualifiers at the start of a declaration may
-contain attribute specifiers, whether or not such a list may in that
-context contain storage class specifiers. (Some attributes, however,
-are essentially in the nature of storage class specifiers, and only make
-sense where storage class specifiers may be used; for example,
-@code{section}.) There is one necessary limitation to this syntax: the
-first old-style parameter declaration in a function definition cannot
-begin with an attribute specifier, because such an attribute applies to
-the function instead by syntax described below (which, however, is not
-yet implemented in this case). In some other cases, attribute
-specifiers are permitted by this grammar but not yet supported by the
-compiler. All attribute specifiers in this place relate to the
-declaration as a whole. In the obsolescent usage where a type of
-@code{int} is implied by the absence of type specifiers, such a list of
-specifiers and qualifiers may be an attribute specifier list with no
-other specifiers or qualifiers.
-
-At present, the first parameter in a function prototype must have some
-type specifier that is not an attribute specifier; this resolves an
-ambiguity in the interpretation of @code{void f(int
-(__attribute__((foo)) x))}, but is subject to change. At present, if
-the parentheses of a function declarator contain only attributes then
-those attributes are ignored, rather than yielding an error or warning
-or implying a single parameter of type int, but this is subject to
-change.
-
-An attribute specifier list may appear immediately before a declarator
-(other than the first) in a comma-separated list of declarators in a
-declaration of more than one identifier using a single list of
-specifiers and qualifiers. Such attribute specifiers apply
-only to the identifier before whose declarator they appear. For
-example, in
-
-@smallexample
-__attribute__((noreturn)) void d0 (void),
- __attribute__((format(printf, 1, 2))) d1 (const char *, ...),
- d2 (void);
-@end smallexample
-
-@noindent
-the @code{noreturn} attribute applies to all the functions
-declared; the @code{format} attribute only applies to @code{d1}.
-
-An attribute specifier list may appear immediately before the comma,
-@code{=} or semicolon terminating the declaration of an identifier other
-than a function definition. Such attribute specifiers apply
-to the declared object or function. Where an
-assembler name for an object or function is specified (@pxref{Asm
-Labels}), the attribute must follow the @code{asm}
-specification.
-
-An attribute specifier list may, in future, be permitted to appear after
-the declarator in a function definition (before any old-style parameter
-declarations or the function body).
-
-Attribute specifiers may be mixed with type qualifiers appearing inside
-the @code{[]} of a parameter array declarator, in the C99 construct by
-which such qualifiers are applied to the pointer to which the array is
-implicitly converted. Such attribute specifiers apply to the pointer,
-not to the array, but at present this is not implemented and they are
-ignored.
-
-An attribute specifier list may appear at the start of a nested
-declarator. At present, there are some limitations in this usage: the
-attributes correctly apply to the declarator, but for most individual
-attributes the semantics this implies are not implemented.
-When attribute specifiers follow the @code{*} of a pointer
-declarator, they may be mixed with any type qualifiers present.
-The following describes the formal semantics of this syntax. It makes the
-most sense if you are familiar with the formal specification of
-declarators in the ISO C standard.
-
-Consider (as in C99 subclause 6.7.5 paragraph 4) a declaration @code{T
-D1}, where @code{T} contains declaration specifiers that specify a type
-@var{Type} (such as @code{int}) and @code{D1} is a declarator that
-contains an identifier @var{ident}. The type specified for @var{ident}
-for derived declarators whose type does not include an attribute
-specifier is as in the ISO C standard.
-
-If @code{D1} has the form @code{( @var{attribute-specifier-list} D )},
-and the declaration @code{T D} specifies the type
-``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then
-@code{T D1} specifies the type ``@var{derived-declarator-type-list}
-@var{attribute-specifier-list} @var{Type}'' for @var{ident}.
-
-If @code{D1} has the form @code{*
-@var{type-qualifier-and-attribute-specifier-list} D}, and the
-declaration @code{T D} specifies the type
-``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then
-@code{T D1} specifies the type ``@var{derived-declarator-type-list}
-@var{type-qualifier-and-attribute-specifier-list} pointer to @var{Type}'' for
-@var{ident}.
-
-For example,
-
-@smallexample
-void (__attribute__((noreturn)) ****f) (void);
-@end smallexample
-
-@noindent
-specifies the type ``pointer to pointer to pointer to pointer to
-non-returning function returning @code{void}''. As another example,
-
-@smallexample
-char *__attribute__((aligned(8))) *f;
-@end smallexample
-
-@noindent
-specifies the type ``pointer to 8-byte-aligned pointer to @code{char}''.
-Note again that this does not work with most attributes; for example,
-the usage of @samp{aligned} and @samp{noreturn} attributes given above
-is not yet supported.
-
-For compatibility with existing code written for compiler versions that
-did not implement attributes on nested declarators, some laxity is
-allowed in the placing of attributes. If an attribute that only applies
-to types is applied to a declaration, it is treated as applying to
-the type of that declaration. If an attribute that only applies to
-declarations is applied to the type of a declaration, it is treated
-as applying to that declaration; and, for compatibility with code
-placing the attributes immediately before the identifier declared, such
-an attribute applied to a function return type is treated as
-applying to the function type, and such an attribute applied to an array
-element type is treated as applying to the array type. If an
-attribute that only applies to function types is applied to a
-pointer-to-function type, it is treated as applying to the pointer
-target type; if such an attribute is applied to a function return type
-that is not a pointer-to-function type, it is treated as applying
-to the function type.
-
-@node Function Prototypes
-@section Prototypes and Old-Style Function Definitions
-@cindex function prototype declarations
-@cindex old-style function definitions
-@cindex promotion of formal parameters
-
-GNU C extends ISO C to allow a function prototype to override a later
-old-style non-prototype definition. Consider the following example:
-
-@smallexample
-/* @r{Use prototypes unless the compiler is old-fashioned.} */
-#ifdef __STDC__
-#define P(x) x
-#else
-#define P(x) ()
-#endif
-
-/* @r{Prototype function declaration.} */
-int isroot P((uid_t));
-
-/* @r{Old-style function definition.} */
-int
-isroot (x) /* @r{??? lossage here ???} */
- uid_t x;
-@{
- return x == 0;
-@}
-@end smallexample
-
-Suppose the type @code{uid_t} happens to be @code{short}. ISO C does
-not allow this example, because subword arguments in old-style
-non-prototype definitions are promoted. Therefore in this example the
-function definition's argument is really an @code{int}, which does not
-match the prototype argument type of @code{short}.
-
-This restriction of ISO C makes it hard to write code that is portable
-to traditional C compilers, because the programmer does not know
-whether the @code{uid_t} type is @code{short}, @code{int}, or
-@code{long}. Therefore, in cases like these GNU C allows a prototype
-to override a later old-style definition. More precisely, in GNU C, a
-function prototype argument type overrides the argument type specified
-by a later old-style definition if the former type is the same as the
-latter type before promotion. Thus in GNU C the above example is
-equivalent to the following:
-
-@smallexample
-int isroot (uid_t);
-
-int
-isroot (uid_t x)
-@{
- return x == 0;
-@}
-@end smallexample
-
-@noindent
-GNU C++ does not support old-style function definitions, so this
-extension is irrelevant.
-
-@node C++ Comments
-@section C++ Style Comments
-@cindex @code{//}
-@cindex C++ comments
-@cindex comments, C++ style
-
-In GNU C, you may use C++ style comments, which start with @samp{//} and
-continue until the end of the line. Many other C implementations allow
-such comments, and they are included in the 1999 C standard. However,
-C++ style comments are not recognized if you specify an @option{-std}
-option specifying a version of ISO C before C99, or @option{-ansi}
-(equivalent to @option{-std=c90}).
-
-@node Dollar Signs
-@section Dollar Signs in Identifier Names
-@cindex $
-@cindex dollar signs in identifier names
-@cindex identifier names, dollar signs in
-
-In GNU C, you may normally use dollar signs in identifier names.
-This is because many traditional C implementations allow such identifiers.
-However, dollar signs in identifiers are not supported on a few target
-machines, typically because the target assembler does not allow them.
-
-@node Character Escapes
-@section The Character @key{ESC} in Constants
-
-You can use the sequence @samp{\e} in a string or character constant to
-stand for the ASCII character @key{ESC}.
-
-@node Alignment
-@section Determining the Alignment of Functions, Types or Variables
-@cindex alignment
-@cindex type alignment
-@cindex variable alignment
-
-The keyword @code{__alignof__} determines the alignment requirement of
-a function, object, or a type, or the minimum alignment usually required
-by a type. Its syntax is just like @code{sizeof} and C11 @code{_Alignof}.
-
-For example, if the target machine requires a @code{double} value to be
-aligned on an 8-byte boundary, then @code{__alignof__ (double)} is 8.
-This is true on many RISC machines. On more traditional machine
-designs, @code{__alignof__ (double)} is 4 or even 2.
-
-Some machines never actually require alignment; they allow references to any
-data type even at an odd address. For these machines, @code{__alignof__}
-reports the smallest alignment that GCC gives the data type, usually as
-mandated by the target ABI.
-
-If the operand of @code{__alignof__} is an lvalue rather than a type,
-its value is the required alignment for its type, taking into account
-any minimum alignment specified by attribute @code{aligned}
-(@pxref{Common Variable Attributes}). For example, after this
-declaration:
-
-@smallexample
-struct foo @{ int x; char y; @} foo1;
-@end smallexample
-
-@noindent
-the value of @code{__alignof__ (foo1.y)} is 1, even though its actual
-alignment is probably 2 or 4, the same as @code{__alignof__ (int)}.
-It is an error to ask for the alignment of an incomplete type other
-than @code{void}.
-
-If the operand of the @code{__alignof__} expression is a function,
-the expression evaluates to the alignment of the function which may
-be specified by attribute @code{aligned} (@pxref{Common Function Attributes}).
-
-@node Inline
-@section An Inline Function is As Fast As a Macro
-@cindex inline functions
-@cindex integrating function code
-@cindex open coding
-@cindex macros, inline alternative
-
-By declaring a function inline, you can direct GCC to make
-calls to that function faster. One way GCC can achieve this is to
-integrate that function's code into the code for its callers. This
-makes execution faster by eliminating the function-call overhead; in
-addition, if any of the actual argument values are constant, their
-known values may permit simplifications at compile time so that not
-all of the inline function's code needs to be included. The effect on
-code size is less predictable; object code may be larger or smaller
-with function inlining, depending on the particular case. You can
-also direct GCC to try to integrate all ``simple enough'' functions
-into their callers with the option @option{-finline-functions}.
-
-GCC implements three different semantics of declaring a function
-inline. One is available with @option{-std=gnu89} or
-@option{-fgnu89-inline} or when @code{gnu_inline} attribute is present
-on all inline declarations, another when
-@option{-std=c99},
-@option{-std=gnu99} or an option for a later C version is used
-(without @option{-fgnu89-inline}), and the third
-is used when compiling C++.
-
-To declare a function inline, use the @code{inline} keyword in its
-declaration, like this:
-
-@smallexample
-static inline int
-inc (int *a)
-@{
- return (*a)++;
-@}
-@end smallexample
-
-If you are writing a header file to be included in ISO C90 programs, write
-@code{__inline__} instead of @code{inline}. @xref{Alternate Keywords}.
-
-The three types of inlining behave similarly in two important cases:
-when the @code{inline} keyword is used on a @code{static} function,
-like the example above, and when a function is first declared without
-using the @code{inline} keyword and then is defined with
-@code{inline}, like this:
-
-@smallexample
-extern int inc (int *a);
-inline int
-inc (int *a)
-@{
- return (*a)++;
-@}
-@end smallexample
-
-In both of these common cases, the program behaves the same as if you
-had not used the @code{inline} keyword, except for its speed.
-
-@cindex inline functions, omission of
-@opindex fkeep-inline-functions
-When a function is both inline and @code{static}, if all calls to the
-function are integrated into the caller, and the function's address is
-never used, then the function's own assembler code is never referenced.
-In this case, GCC does not actually output assembler code for the
-function, unless you specify the option @option{-fkeep-inline-functions}.
-If there is a nonintegrated call, then the function is compiled to
-assembler code as usual. The function must also be compiled as usual if
-the program refers to its address, because that cannot be inlined.
-
-@opindex Winline
-Note that certain usages in a function definition can make it unsuitable
-for inline substitution. Among these usages are: variadic functions,
-use of @code{alloca}, use of computed goto (@pxref{Labels as Values}),
-use of nonlocal goto, use of nested functions, use of @code{setjmp}, use
-of @code{__builtin_longjmp} and use of @code{__builtin_return} or
-@code{__builtin_apply_args}. Using @option{-Winline} warns when a
-function marked @code{inline} could not be substituted, and gives the
-reason for the failure.
-
-@cindex automatic @code{inline} for C++ member fns
-@cindex @code{inline} automatic for C++ member fns
-@cindex member fns, automatically @code{inline}
-@cindex C++ member fns, automatically @code{inline}
-@opindex fno-default-inline
-As required by ISO C++, GCC considers member functions defined within
-the body of a class to be marked inline even if they are
-not explicitly declared with the @code{inline} keyword. You can
-override this with @option{-fno-default-inline}; @pxref{C++ Dialect
-Options,,Options Controlling C++ Dialect}.
-
-GCC does not inline any functions when not optimizing unless you specify
-the @samp{always_inline} attribute for the function, like this:
-
-@smallexample
-/* @r{Prototype.} */
-inline void foo (const char) __attribute__((always_inline));
-@end smallexample
-
-The remainder of this section is specific to GNU C90 inlining.
-
-@cindex non-static inline function
-When an inline function is not @code{static}, then the compiler must assume
-that there may be calls from other source files; since a global symbol can
-be defined only once in any program, the function must not be defined in
-the other source files, so the calls therein cannot be integrated.
-Therefore, a non-@code{static} inline function is always compiled on its
-own in the usual fashion.
-
-If you specify both @code{inline} and @code{extern} in the function
-definition, then the definition is used only for inlining. In no case
-is the function compiled on its own, not even if you refer to its
-address explicitly. Such an address becomes an external reference, as
-if you had only declared the function, and had not defined it.
-
-This combination of @code{inline} and @code{extern} has almost the
-effect of a macro. The way to use it is to put a function definition in
-a header file with these keywords, and put another copy of the
-definition (lacking @code{inline} and @code{extern}) in a library file.
-The definition in the header file causes most calls to the function
-to be inlined. If any uses of the function remain, they refer to
-the single copy in the library.
-
-@node Volatiles
-@section When is a Volatile Object Accessed?
-@cindex accessing volatiles
-@cindex volatile read
-@cindex volatile write
-@cindex volatile access
-
-C has the concept of volatile objects. These are normally accessed by
-pointers and used for accessing hardware or inter-thread
-communication. The standard encourages compilers to refrain from
-optimizations concerning accesses to volatile objects, but leaves it
-implementation defined as to what constitutes a volatile access. The
-minimum requirement is that at a sequence point all previous accesses
-to volatile objects have stabilized and no subsequent accesses have
-occurred. Thus an implementation is free to reorder and combine
-volatile accesses that occur between sequence points, but cannot do
-so for accesses across a sequence point. The use of volatile does
-not allow you to violate the restriction on updating objects multiple
-times between two sequence points.
-
-Accesses to non-volatile objects are not ordered with respect to
-volatile accesses. You cannot use a volatile object as a memory
-barrier to order a sequence of writes to non-volatile memory. For
-instance:
-
-@smallexample
-int *ptr = @var{something};
-volatile int vobj;
-*ptr = @var{something};
-vobj = 1;
-@end smallexample
-
-@noindent
-Unless @var{*ptr} and @var{vobj} can be aliased, it is not guaranteed
-that the write to @var{*ptr} occurs by the time the update
-of @var{vobj} happens. If you need this guarantee, you must use
-a stronger memory barrier such as:
-
-@smallexample
-int *ptr = @var{something};
-volatile int vobj;
-*ptr = @var{something};
-asm volatile ("" : : : "memory");
-vobj = 1;
-@end smallexample
-
-A scalar volatile object is read when it is accessed in a void context:
-
-@smallexample
-volatile int *src = @var{somevalue};
-*src;
-@end smallexample
-
-Such expressions are rvalues, and GCC implements this as a
-read of the volatile object being pointed to.
-
-Assignments are also expressions and have an rvalue. However when
-assigning to a scalar volatile, the volatile object is not reread,
-regardless of whether the assignment expression's rvalue is used or
-not. If the assignment's rvalue is used, the value is that assigned
-to the volatile object. For instance, there is no read of @var{vobj}
-in all the following cases:
-
-@smallexample
-int obj;
-volatile int vobj;
-vobj = @var{something};
-obj = vobj = @var{something};
-obj ? vobj = @var{onething} : vobj = @var{anotherthing};
-obj = (@var{something}, vobj = @var{anotherthing});
-@end smallexample
-
-If you need to read the volatile object after an assignment has
-occurred, you must use a separate expression with an intervening
-sequence point.
-
-As bit-fields are not individually addressable, volatile bit-fields may
-be implicitly read when written to, or when adjacent bit-fields are
-accessed. Bit-field operations may be optimized such that adjacent
-bit-fields are only partially accessed, if they straddle a storage unit
-boundary. For these reasons it is unwise to use volatile bit-fields to
-access hardware.
-
-@node Using Assembly Language with C
-@section How to Use Inline Assembly Language in C Code
-@cindex @code{asm} keyword
-@cindex assembly language in C
-@cindex inline assembly language
-@cindex mixing assembly language and C
-
-The @code{asm} keyword allows you to embed assembler instructions
-within C code. GCC provides two forms of inline @code{asm}
-statements. A @dfn{basic @code{asm}} statement is one with no
-operands (@pxref{Basic Asm}), while an @dfn{extended @code{asm}}
-statement (@pxref{Extended Asm}) includes one or more operands.
-The extended form is preferred for mixing C and assembly language
-within a function, but to include assembly language at
-top level you must use basic @code{asm}.
-
-You can also use the @code{asm} keyword to override the assembler name
-for a C symbol, or to place a C variable in a specific register.
-
-@menu
-* Basic Asm:: Inline assembler without operands.
-* Extended Asm:: Inline assembler with operands.
-* Constraints:: Constraints for @code{asm} operands
-* Asm Labels:: Specifying the assembler name to use for a C symbol.
-* Explicit Register Variables:: Defining variables residing in specified
- registers.
-* Size of an asm:: How GCC calculates the size of an @code{asm} block.
-@end menu
-
-@node Basic Asm
-@subsection Basic Asm --- Assembler Instructions Without Operands
-@cindex basic @code{asm}
-@cindex assembly language in C, basic
-
-A basic @code{asm} statement has the following syntax:
-
-@example
-asm @var{asm-qualifiers} ( @var{AssemblerInstructions} )
-@end example
-
-For the C language, the @code{asm} keyword is a GNU extension.
-When writing C code that can be compiled with @option{-ansi} and the
-@option{-std} options that select C dialects without GNU extensions, use
-@code{__asm__} instead of @code{asm} (@pxref{Alternate Keywords}). For
-the C++ language, @code{asm} is a standard keyword, but @code{__asm__}
-can be used for code compiled with @option{-fno-asm}.
-
-@subsubheading Qualifiers
-@table @code
-@item volatile
-The optional @code{volatile} qualifier has no effect.
-All basic @code{asm} blocks are implicitly volatile.
-
-@item inline
-If you use the @code{inline} qualifier, then for inlining purposes the size
-of the @code{asm} statement is taken as the smallest size possible (@pxref{Size
-of an asm}).
-@end table
-
-@subsubheading Parameters
-@table @var
-
-@item AssemblerInstructions
-This is a literal string that specifies the assembler code. The string can
-contain any instructions recognized by the assembler, including directives.
-GCC does not parse the assembler instructions themselves and
-does not know what they mean or even whether they are valid assembler input.
-
-You may place multiple assembler instructions together in a single @code{asm}
-string, separated by the characters normally used in assembly code for the
-system. A combination that works in most places is a newline to break the
-line, plus a tab character (written as @samp{\n\t}).
-Some assemblers allow semicolons as a line separator. However,
-note that some assembler dialects use semicolons to start a comment.
-@end table
-
-@subsubheading Remarks
-Using extended @code{asm} (@pxref{Extended Asm}) typically produces
-smaller, safer, and more efficient code, and in most cases it is a
-better solution than basic @code{asm}. However, there are two
-situations where only basic @code{asm} can be used:
-
-@itemize @bullet
-@item
-Extended @code{asm} statements have to be inside a C
-function, so to write inline assembly language at file scope (``top-level''),
-outside of C functions, you must use basic @code{asm}.
-You can use this technique to emit assembler directives,
-define assembly language macros that can be invoked elsewhere in the file,
-or write entire functions in assembly language.
-Basic @code{asm} statements outside of functions may not use any
-qualifiers.
-
-@item
-Functions declared
-with the @code{naked} attribute also require basic @code{asm}
-(@pxref{Function Attributes}).
-@end itemize
-
-Safely accessing C data and calling functions from basic @code{asm} is more
-complex than it may appear. To access C data, it is better to use extended
-@code{asm}.
-
-Do not expect a sequence of @code{asm} statements to remain perfectly
-consecutive after compilation. If certain instructions need to remain
-consecutive in the output, put them in a single multi-instruction @code{asm}
-statement. Note that GCC's optimizers can move @code{asm} statements
-relative to other code, including across jumps.
-
-@code{asm} statements may not perform jumps into other @code{asm} statements.
-GCC does not know about these jumps, and therefore cannot take
-account of them when deciding how to optimize. Jumps from @code{asm} to C
-labels are only supported in extended @code{asm}.
-
-Under certain circumstances, GCC may duplicate (or remove duplicates of) your
-assembly code when optimizing. This can lead to unexpected duplicate
-symbol errors during compilation if your assembly code defines symbols or
-labels.
-
-@strong{Warning:} The C standards do not specify semantics for @code{asm},
-making it a potential source of incompatibilities between compilers. These
-incompatibilities may not produce compiler warnings/errors.
-
-GCC does not parse basic @code{asm}'s @var{AssemblerInstructions}, which
-means there is no way to communicate to the compiler what is happening
-inside them. GCC has no visibility of symbols in the @code{asm} and may
-discard them as unreferenced. It also does not know about side effects of
-the assembler code, such as modifications to memory or registers. Unlike
-some compilers, GCC assumes that no changes to general purpose registers
-occur. This assumption may change in a future release.
-
-To avoid complications from future changes to the semantics and the
-compatibility issues between compilers, consider replacing basic @code{asm}
-with extended @code{asm}. See
-@uref{https://gcc.gnu.org/wiki/ConvertBasicAsmToExtended, How to convert
-from basic asm to extended asm} for information about how to perform this
-conversion.
-
-The compiler copies the assembler instructions in a basic @code{asm}
-verbatim to the assembly language output file, without
-processing dialects or any of the @samp{%} operators that are available with
-extended @code{asm}. This results in minor differences between basic
-@code{asm} strings and extended @code{asm} templates. For example, to refer to
-registers you might use @samp{%eax} in basic @code{asm} and
-@samp{%%eax} in extended @code{asm}.
-
-On targets such as x86 that support multiple assembler dialects,
-all basic @code{asm} blocks use the assembler dialect specified by the
-@option{-masm} command-line option (@pxref{x86 Options}).
-Basic @code{asm} provides no
-mechanism to provide different assembler strings for different dialects.
-
-For basic @code{asm} with non-empty assembler string GCC assumes
-the assembler block does not change any general purpose registers,
-but it may read or write any globally accessible variable.
-
-Here is an example of basic @code{asm} for i386:
-
-@example
-/* Note that this code will not compile with -masm=intel */
-#define DebugBreak() asm("int $3")
-@end example
-
-@node Extended Asm
-@subsection Extended Asm - Assembler Instructions with C Expression Operands
-@cindex extended @code{asm}
-@cindex assembly language in C, extended
-
-With extended @code{asm} you can read and write C variables from
-assembler and perform jumps from assembler code to C labels.
-Extended @code{asm} syntax uses colons (@samp{:}) to delimit
-the operand parameters after the assembler template:
-
-@example
-asm @var{asm-qualifiers} ( @var{AssemblerTemplate}
- : @var{OutputOperands}
- @r{[} : @var{InputOperands}
- @r{[} : @var{Clobbers} @r{]} @r{]})
-
-asm @var{asm-qualifiers} ( @var{AssemblerTemplate}
- : @var{OutputOperands}
- : @var{InputOperands}
- : @var{Clobbers}
- : @var{GotoLabels})
-@end example
-where in the last form, @var{asm-qualifiers} contains @code{goto} (and in the
-first form, not).
-
-The @code{asm} keyword is a GNU extension.
-When writing code that can be compiled with @option{-ansi} and the
-various @option{-std} options, use @code{__asm__} instead of
-@code{asm} (@pxref{Alternate Keywords}).
-
-@subsubheading Qualifiers
-@table @code
-
-@item volatile
-The typical use of extended @code{asm} statements is to manipulate input
-values to produce output values. However, your @code{asm} statements may
-also produce side effects. If so, you may need to use the @code{volatile}
-qualifier to disable certain optimizations. @xref{Volatile}.
-
-@item inline
-If you use the @code{inline} qualifier, then for inlining purposes the size
-of the @code{asm} statement is taken as the smallest size possible
-(@pxref{Size of an asm}).
-
-@item goto
-This qualifier informs the compiler that the @code{asm} statement may
-perform a jump to one of the labels listed in the @var{GotoLabels}.
-@xref{GotoLabels}.
-@end table
-
-@subsubheading Parameters
-@table @var
-@item AssemblerTemplate
-This is a literal string that is the template for the assembler code. It is a
-combination of fixed text and tokens that refer to the input, output,
-and goto parameters. @xref{AssemblerTemplate}.
-
-@item OutputOperands
-A comma-separated list of the C variables modified by the instructions in the
-@var{AssemblerTemplate}. An empty list is permitted. @xref{OutputOperands}.
-
-@item InputOperands
-A comma-separated list of C expressions read by the instructions in the
-@var{AssemblerTemplate}. An empty list is permitted. @xref{InputOperands}.
-
-@item Clobbers
-A comma-separated list of registers or other values changed by the
-@var{AssemblerTemplate}, beyond those listed as outputs.
-An empty list is permitted. @xref{Clobbers and Scratch Registers}.
-
-@item GotoLabels
-When you are using the @code{goto} form of @code{asm}, this section contains
-the list of all C labels to which the code in the
-@var{AssemblerTemplate} may jump.
-@xref{GotoLabels}.
-
-@code{asm} statements may not perform jumps into other @code{asm} statements,
-only to the listed @var{GotoLabels}.
-GCC's optimizers do not know about other jumps; therefore they cannot take
-account of them when deciding how to optimize.
-@end table
-
-The total number of input + output + goto operands is limited to 30.
-
-@subsubheading Remarks
-The @code{asm} statement allows you to include assembly instructions directly
-within C code. This may help you to maximize performance in time-sensitive
-code or to access assembly instructions that are not readily available to C
-programs.
-
-Note that extended @code{asm} statements must be inside a function. Only
-basic @code{asm} may be outside functions (@pxref{Basic Asm}).
-Functions declared with the @code{naked} attribute also require basic
-@code{asm} (@pxref{Function Attributes}).
-
-While the uses of @code{asm} are many and varied, it may help to think of an
-@code{asm} statement as a series of low-level instructions that convert input
-parameters to output parameters. So a simple (if not particularly useful)
-example for i386 using @code{asm} might look like this:
-
-@example
-int src = 1;
-int dst;
-
-asm ("mov %1, %0\n\t"
- "add $1, %0"
- : "=r" (dst)
- : "r" (src));
-
-printf("%d\n", dst);
-@end example
-
-This code copies @code{src} to @code{dst} and add 1 to @code{dst}.
-
-@anchor{Volatile}
-@subsubsection Volatile
-@cindex volatile @code{asm}
-@cindex @code{asm} volatile
-
-GCC's optimizers sometimes discard @code{asm} statements if they determine
-there is no need for the output variables. Also, the optimizers may move
-code out of loops if they believe that the code will always return the same
-result (i.e.@: none of its input values change between calls). Using the
-@code{volatile} qualifier disables these optimizations. @code{asm} statements
-that have no output operands and @code{asm goto} statements,
-are implicitly volatile.
-
-This i386 code demonstrates a case that does not use (or require) the
-@code{volatile} qualifier. If it is performing assertion checking, this code
-uses @code{asm} to perform the validation. Otherwise, @code{dwRes} is
-unreferenced by any code. As a result, the optimizers can discard the
-@code{asm} statement, which in turn removes the need for the entire
-@code{DoCheck} routine. By omitting the @code{volatile} qualifier when it
-isn't needed you allow the optimizers to produce the most efficient code
-possible.
-
-@example
-void DoCheck(uint32_t dwSomeValue)
-@{
- uint32_t dwRes;
-
- // Assumes dwSomeValue is not zero.
- asm ("bsfl %1,%0"
- : "=r" (dwRes)
- : "r" (dwSomeValue)
- : "cc");
-
- assert(dwRes > 3);
-@}
-@end example
-
-The next example shows a case where the optimizers can recognize that the input
-(@code{dwSomeValue}) never changes during the execution of the function and can
-therefore move the @code{asm} outside the loop to produce more efficient code.
-Again, using the @code{volatile} qualifier disables this type of optimization.
-
-@example
-void do_print(uint32_t dwSomeValue)
-@{
- uint32_t dwRes;
-
- for (uint32_t x=0; x < 5; x++)
- @{
- // Assumes dwSomeValue is not zero.
- asm ("bsfl %1,%0"
- : "=r" (dwRes)
- : "r" (dwSomeValue)
- : "cc");
-
- printf("%u: %u %u\n", x, dwSomeValue, dwRes);
- @}
-@}
-@end example
-
-The following example demonstrates a case where you need to use the
-@code{volatile} qualifier.
-It uses the x86 @code{rdtsc} instruction, which reads
-the computer's time-stamp counter. Without the @code{volatile} qualifier,
-the optimizers might assume that the @code{asm} block will always return the
-same value and therefore optimize away the second call.
-
-@example
-uint64_t msr;
-
-asm volatile ( "rdtsc\n\t" // Returns the time in EDX:EAX.
- "shl $32, %%rdx\n\t" // Shift the upper bits left.
- "or %%rdx, %0" // 'Or' in the lower bits.
- : "=a" (msr)
- :
- : "rdx");
-
-printf("msr: %llx\n", msr);
-
-// Do other work...
-
-// Reprint the timestamp
-asm volatile ( "rdtsc\n\t" // Returns the time in EDX:EAX.
- "shl $32, %%rdx\n\t" // Shift the upper bits left.
- "or %%rdx, %0" // 'Or' in the lower bits.
- : "=a" (msr)
- :
- : "rdx");
-
-printf("msr: %llx\n", msr);
-@end example
-
-GCC's optimizers do not treat this code like the non-volatile code in the
-earlier examples. They do not move it out of loops or omit it on the
-assumption that the result from a previous call is still valid.
-
-Note that the compiler can move even @code{volatile asm} instructions relative
-to other code, including across jump instructions. For example, on many
-targets there is a system register that controls the rounding mode of
-floating-point operations. Setting it with a @code{volatile asm} statement,
-as in the following PowerPC example, does not work reliably.
-
-@example
-asm volatile("mtfsf 255, %0" : : "f" (fpenv));
-sum = x + y;
-@end example
-
-The compiler may move the addition back before the @code{volatile asm}
-statement. To make it work as expected, add an artificial dependency to
-the @code{asm} by referencing a variable in the subsequent code, for
-example:
-
-@example
-asm volatile ("mtfsf 255,%1" : "=X" (sum) : "f" (fpenv));
-sum = x + y;
-@end example
-
-Under certain circumstances, GCC may duplicate (or remove duplicates of) your
-assembly code when optimizing. This can lead to unexpected duplicate symbol
-errors during compilation if your @code{asm} code defines symbols or labels.
-Using @samp{%=}
-(@pxref{AssemblerTemplate}) may help resolve this problem.
-
-@anchor{AssemblerTemplate}
-@subsubsection Assembler Template
-@cindex @code{asm} assembler template
-
-An assembler template is a literal string containing assembler instructions.
-The compiler replaces tokens in the template that refer
-to inputs, outputs, and goto labels,
-and then outputs the resulting string to the assembler. The
-string can contain any instructions recognized by the assembler, including
-directives. GCC does not parse the assembler instructions
-themselves and does not know what they mean or even whether they are valid
-assembler input. However, it does count the statements
-(@pxref{Size of an asm}).
-
-You may place multiple assembler instructions together in a single @code{asm}
-string, separated by the characters normally used in assembly code for the
-system. A combination that works in most places is a newline to break the
-line, plus a tab character to move to the instruction field (written as
-@samp{\n\t}).
-Some assemblers allow semicolons as a line separator. However, note
-that some assembler dialects use semicolons to start a comment.
-
-Do not expect a sequence of @code{asm} statements to remain perfectly
-consecutive after compilation, even when you are using the @code{volatile}
-qualifier. If certain instructions need to remain consecutive in the output,
-put them in a single multi-instruction @code{asm} statement.
-
-Accessing data from C programs without using input/output operands (such as
-by using global symbols directly from the assembler template) may not work as
-expected. Similarly, calling functions directly from an assembler template
-requires a detailed understanding of the target assembler and ABI.
-
-Since GCC does not parse the assembler template,
-it has no visibility of any
-symbols it references. This may result in GCC discarding those symbols as
-unreferenced unless they are also listed as input, output, or goto operands.
-
-@subsubheading Special format strings
-
-In addition to the tokens described by the input, output, and goto operands,
-these tokens have special meanings in the assembler template:
-
-@table @samp
-@item %%
-Outputs a single @samp{%} into the assembler code.
-
-@item %=
-Outputs a number that is unique to each instance of the @code{asm}
-statement in the entire compilation. This option is useful when creating local
-labels and referring to them multiple times in a single template that
-generates multiple assembler instructions.
-
-@item %@{
-@itemx %|
-@itemx %@}
-Outputs @samp{@{}, @samp{|}, and @samp{@}} characters (respectively)
-into the assembler code. When unescaped, these characters have special
-meaning to indicate multiple assembler dialects, as described below.
-@end table
-
-@subsubheading Multiple assembler dialects in @code{asm} templates
-
-On targets such as x86, GCC supports multiple assembler dialects.
-The @option{-masm} option controls which dialect GCC uses as its
-default for inline assembler. The target-specific documentation for the
-@option{-masm} option contains the list of supported dialects, as well as the
-default dialect if the option is not specified. This information may be
-important to understand, since assembler code that works correctly when
-compiled using one dialect will likely fail if compiled using another.
-@xref{x86 Options}.
-
-If your code needs to support multiple assembler dialects (for example, if
-you are writing public headers that need to support a variety of compilation
-options), use constructs of this form:
-
-@example
-@{ dialect0 | dialect1 | dialect2... @}
-@end example
-
-This construct outputs @code{dialect0}
-when using dialect #0 to compile the code,
-@code{dialect1} for dialect #1, etc. If there are fewer alternatives within the
-braces than the number of dialects the compiler supports, the construct
-outputs nothing.
-
-For example, if an x86 compiler supports two dialects
-(@samp{att}, @samp{intel}), an
-assembler template such as this:
-
-@example
-"bt@{l %[Offset],%[Base] | %[Base],%[Offset]@}; jc %l2"
-@end example
-
-@noindent
-is equivalent to one of
-
-@example
-"btl %[Offset],%[Base] ; jc %l2" @r{/* att dialect */}
-"bt %[Base],%[Offset]; jc %l2" @r{/* intel dialect */}
-@end example
-
-Using that same compiler, this code:
-
-@example
-"xchg@{l@}\t@{%%@}ebx, %1"
-@end example
-
-@noindent
-corresponds to either
-
-@example
-"xchgl\t%%ebx, %1" @r{/* att dialect */}
-"xchg\tebx, %1" @r{/* intel dialect */}
-@end example
-
-There is no support for nesting dialect alternatives.
-
-@anchor{OutputOperands}
-@subsubsection Output Operands
-@cindex @code{asm} output operands
-
-An @code{asm} statement has zero or more output operands indicating the names
-of C variables modified by the assembler code.
-
-In this i386 example, @code{old} (referred to in the template string as
-@code{%0}) and @code{*Base} (as @code{%1}) are outputs and @code{Offset}
-(@code{%2}) is an input:
-
-@example
-bool old;
-
-__asm__ ("btsl %2,%1\n\t" // Turn on zero-based bit #Offset in Base.
- "sbb %0,%0" // Use the CF to calculate old.
- : "=r" (old), "+rm" (*Base)
- : "Ir" (Offset)
- : "cc");
-
-return old;
-@end example
-
-Operands are separated by commas. Each operand has this format:
-
-@example
-@r{[} [@var{asmSymbolicName}] @r{]} @var{constraint} (@var{cvariablename})
-@end example
-
-@table @var
-@item asmSymbolicName
-Specifies a symbolic name for the operand.
-Reference the name in the assembler template
-by enclosing it in square brackets
-(i.e.@: @samp{%[Value]}). The scope of the name is the @code{asm} statement
-that contains the definition. Any valid C variable name is acceptable,
-including names already defined in the surrounding code. No two operands
-within the same @code{asm} statement can use the same symbolic name.
-
-When not using an @var{asmSymbolicName}, use the (zero-based) position
-of the operand
-in the list of operands in the assembler template. For example if there are
-three output operands, use @samp{%0} in the template to refer to the first,
-@samp{%1} for the second, and @samp{%2} for the third.
-
-@item constraint
-A string constant specifying constraints on the placement of the operand;
-@xref{Constraints}, for details.
-
-Output constraints must begin with either @samp{=} (a variable overwriting an
-existing value) or @samp{+} (when reading and writing). When using
-@samp{=}, do not assume the location contains the existing value
-on entry to the @code{asm}, except
-when the operand is tied to an input; @pxref{InputOperands,,Input Operands}.
-
-After the prefix, there must be one or more additional constraints
-(@pxref{Constraints}) that describe where the value resides. Common
-constraints include @samp{r} for register and @samp{m} for memory.
-When you list more than one possible location (for example, @code{"=rm"}),
-the compiler chooses the most efficient one based on the current context.
-If you list as many alternates as the @code{asm} statement allows, you permit
-the optimizers to produce the best possible code.
-If you must use a specific register, but your Machine Constraints do not
-provide sufficient control to select the specific register you want,
-local register variables may provide a solution (@pxref{Local Register
-Variables}).
-
-@item cvariablename
-Specifies a C lvalue expression to hold the output, typically a variable name.
-The enclosing parentheses are a required part of the syntax.
-
-@end table
-
-When the compiler selects the registers to use to
-represent the output operands, it does not use any of the clobbered registers
-(@pxref{Clobbers and Scratch Registers}).
-
-Output operand expressions must be lvalues. The compiler cannot check whether
-the operands have data types that are reasonable for the instruction being
-executed. For output expressions that are not directly addressable (for
-example a bit-field), the constraint must allow a register. In that case, GCC
-uses the register as the output of the @code{asm}, and then stores that
-register into the output.
-
-Operands using the @samp{+} constraint modifier count as two operands
-(that is, both as input and output) towards the total maximum of 30 operands
-per @code{asm} statement.
-
-Use the @samp{&} constraint modifier (@pxref{Modifiers}) on all output
-operands that must not overlap an input. Otherwise,
-GCC may allocate the output operand in the same register as an unrelated
-input operand, on the assumption that the assembler code consumes its
-inputs before producing outputs. This assumption may be false if the assembler
-code actually consists of more than one instruction.
-
-The same problem can occur if one output parameter (@var{a}) allows a register
-constraint and another output parameter (@var{b}) allows a memory constraint.
-The code generated by GCC to access the memory address in @var{b} can contain
-registers which @emph{might} be shared by @var{a}, and GCC considers those
-registers to be inputs to the asm. As above, GCC assumes that such input
-registers are consumed before any outputs are written. This assumption may
-result in incorrect behavior if the @code{asm} statement writes to @var{a}
-before using
-@var{b}. Combining the @samp{&} modifier with the register constraint on @var{a}
-ensures that modifying @var{a} does not affect the address referenced by
-@var{b}. Otherwise, the location of @var{b}
-is undefined if @var{a} is modified before using @var{b}.
-
-@code{asm} supports operand modifiers on operands (for example @samp{%k2}
-instead of simply @samp{%2}). Typically these qualifiers are hardware
-dependent. The list of supported modifiers for x86 is found at
-@ref{x86Operandmodifiers,x86 Operand modifiers}.
-
-If the C code that follows the @code{asm} makes no use of any of the output
-operands, use @code{volatile} for the @code{asm} statement to prevent the
-optimizers from discarding the @code{asm} statement as unneeded
-(see @ref{Volatile}).
-
-This code makes no use of the optional @var{asmSymbolicName}. Therefore it
-references the first output operand as @code{%0} (were there a second, it
-would be @code{%1}, etc). The number of the first input operand is one greater
-than that of the last output operand. In this i386 example, that makes
-@code{Mask} referenced as @code{%1}:
-
-@example
-uint32_t Mask = 1234;
-uint32_t Index;
-
- asm ("bsfl %1, %0"
- : "=r" (Index)
- : "r" (Mask)
- : "cc");
-@end example
-
-That code overwrites the variable @code{Index} (@samp{=}),
-placing the value in a register (@samp{r}).
-Using the generic @samp{r} constraint instead of a constraint for a specific
-register allows the compiler to pick the register to use, which can result
-in more efficient code. This may not be possible if an assembler instruction
-requires a specific register.
-
-The following i386 example uses the @var{asmSymbolicName} syntax.
-It produces the
-same result as the code above, but some may consider it more readable or more
-maintainable since reordering index numbers is not necessary when adding or
-removing operands. The names @code{aIndex} and @code{aMask}
-are only used in this example to emphasize which
-names get used where.
-It is acceptable to reuse the names @code{Index} and @code{Mask}.
-
-@example
-uint32_t Mask = 1234;
-uint32_t Index;
-
- asm ("bsfl %[aMask], %[aIndex]"
- : [aIndex] "=r" (Index)
- : [aMask] "r" (Mask)
- : "cc");
-@end example
-
-Here are some more examples of output operands.
-
-@example
-uint32_t c = 1;
-uint32_t d;
-uint32_t *e = &c;
-
-asm ("mov %[e], %[d]"
- : [d] "=rm" (d)
- : [e] "rm" (*e));
-@end example
-
-Here, @code{d} may either be in a register or in memory. Since the compiler
-might already have the current value of the @code{uint32_t} location
-pointed to by @code{e}
-in a register, you can enable it to choose the best location
-for @code{d} by specifying both constraints.
-
-@anchor{FlagOutputOperands}
-@subsubsection Flag Output Operands
-@cindex @code{asm} flag output operands
-
-Some targets have a special register that holds the ``flags'' for the
-result of an operation or comparison. Normally, the contents of that
-register are either unmodifed by the asm, or the @code{asm} statement is
-considered to clobber the contents.
-
-On some targets, a special form of output operand exists by which
-conditions in the flags register may be outputs of the asm. The set of
-conditions supported are target specific, but the general rule is that
-the output variable must be a scalar integer, and the value is boolean.
-When supported, the target defines the preprocessor symbol
-@code{__GCC_ASM_FLAG_OUTPUTS__}.
-
-Because of the special nature of the flag output operands, the constraint
-may not include alternatives.
-
-Most often, the target has only one flags register, and thus is an implied
-operand of many instructions. In this case, the operand should not be
-referenced within the assembler template via @code{%0} etc, as there's
-no corresponding text in the assembly language.
-
-@table @asis
-@item ARM
-@itemx AArch64
-The flag output constraints for the ARM family are of the form
-@samp{=@@cc@var{cond}} where @var{cond} is one of the standard
-conditions defined in the ARM ARM for @code{ConditionHolds}.
-
-@table @code
-@item eq
-Z flag set, or equal
-@item ne
-Z flag clear or not equal
-@item cs
-@itemx hs
-C flag set or unsigned greater than equal
-@item cc
-@itemx lo
-C flag clear or unsigned less than
-@item mi
-N flag set or ``minus''
-@item pl
-N flag clear or ``plus''
-@item vs
-V flag set or signed overflow
-@item vc
-V flag clear
-@item hi
-unsigned greater than
-@item ls
-unsigned less than equal
-@item ge
-signed greater than equal
-@item lt
-signed less than
-@item gt
-signed greater than
-@item le
-signed less than equal
-@end table
-
-The flag output constraints are not supported in thumb1 mode.
-
-@item x86 family
-The flag output constraints for the x86 family are of the form
-@samp{=@@cc@var{cond}} where @var{cond} is one of the standard
-conditions defined in the ISA manual for @code{j@var{cc}} or
-@code{set@var{cc}}.
-
-@table @code
-@item a
-``above'' or unsigned greater than
-@item ae
-``above or equal'' or unsigned greater than or equal
-@item b
-``below'' or unsigned less than
-@item be
-``below or equal'' or unsigned less than or equal
-@item c
-carry flag set
-@item e
-@itemx z
-``equal'' or zero flag set
-@item g
-signed greater than
-@item ge
-signed greater than or equal
-@item l
-signed less than
-@item le
-signed less than or equal
-@item o
-overflow flag set
-@item p
-parity flag set
-@item s
-sign flag set
-@item na
-@itemx nae
-@itemx nb
-@itemx nbe
-@itemx nc
-@itemx ne
-@itemx ng
-@itemx nge
-@itemx nl
-@itemx nle
-@itemx no
-@itemx np
-@itemx ns
-@itemx nz
-``not'' @var{flag}, or inverted versions of those above
-@end table
-
-@end table
-
-@anchor{InputOperands}
-@subsubsection Input Operands
-@cindex @code{asm} input operands
-@cindex @code{asm} expressions
-
-Input operands make values from C variables and expressions available to the
-assembly code.
-
-Operands are separated by commas. Each operand has this format:
-
-@example
-@r{[} [@var{asmSymbolicName}] @r{]} @var{constraint} (@var{cexpression})
-@end example
-
-@table @var
-@item asmSymbolicName
-Specifies a symbolic name for the operand.
-Reference the name in the assembler template
-by enclosing it in square brackets
-(i.e.@: @samp{%[Value]}). The scope of the name is the @code{asm} statement
-that contains the definition. Any valid C variable name is acceptable,
-including names already defined in the surrounding code. No two operands
-within the same @code{asm} statement can use the same symbolic name.
-
-When not using an @var{asmSymbolicName}, use the (zero-based) position
-of the operand
-in the list of operands in the assembler template. For example if there are
-two output operands and three inputs,
-use @samp{%2} in the template to refer to the first input operand,
-@samp{%3} for the second, and @samp{%4} for the third.
-
-@item constraint
-A string constant specifying constraints on the placement of the operand;
-@xref{Constraints}, for details.
-
-Input constraint strings may not begin with either @samp{=} or @samp{+}.
-When you list more than one possible location (for example, @samp{"irm"}),
-the compiler chooses the most efficient one based on the current context.
-If you must use a specific register, but your Machine Constraints do not
-provide sufficient control to select the specific register you want,
-local register variables may provide a solution (@pxref{Local Register
-Variables}).
-
-Input constraints can also be digits (for example, @code{"0"}). This indicates
-that the specified input must be in the same place as the output constraint
-at the (zero-based) index in the output constraint list.
-When using @var{asmSymbolicName} syntax for the output operands,
-you may use these names (enclosed in brackets @samp{[]}) instead of digits.
-
-@item cexpression
-This is the C variable or expression being passed to the @code{asm} statement
-as input. The enclosing parentheses are a required part of the syntax.
-
-@end table
-
-When the compiler selects the registers to use to represent the input
-operands, it does not use any of the clobbered registers
-(@pxref{Clobbers and Scratch Registers}).
-
-If there are no output operands but there are input operands, place two
-consecutive colons where the output operands would go:
-
-@example
-__asm__ ("some instructions"
- : /* No outputs. */
- : "r" (Offset / 8));
-@end example
-
-@strong{Warning:} Do @emph{not} modify the contents of input-only operands
-(except for inputs tied to outputs). The compiler assumes that on exit from
-the @code{asm} statement these operands contain the same values as they
-had before executing the statement.
-It is @emph{not} possible to use clobbers
-to inform the compiler that the values in these inputs are changing. One
-common work-around is to tie the changing input variable to an output variable
-that never gets used. Note, however, that if the code that follows the
-@code{asm} statement makes no use of any of the output operands, the GCC
-optimizers may discard the @code{asm} statement as unneeded
-(see @ref{Volatile}).
-
-@code{asm} supports operand modifiers on operands (for example @samp{%k2}
-instead of simply @samp{%2}). Typically these qualifiers are hardware
-dependent. The list of supported modifiers for x86 is found at
-@ref{x86Operandmodifiers,x86 Operand modifiers}.
-
-In this example using the fictitious @code{combine} instruction, the
-constraint @code{"0"} for input operand 1 says that it must occupy the same
-location as output operand 0. Only input operands may use numbers in
-constraints, and they must each refer to an output operand. Only a number (or
-the symbolic assembler name) in the constraint can guarantee that one operand
-is in the same place as another. The mere fact that @code{foo} is the value of
-both operands is not enough to guarantee that they are in the same place in
-the generated assembler code.
-
-@example
-asm ("combine %2, %0"
- : "=r" (foo)
- : "0" (foo), "g" (bar));
-@end example
-
-Here is an example using symbolic names.
-
-@example
-asm ("cmoveq %1, %2, %[result]"
- : [result] "=r"(result)
- : "r" (test), "r" (new), "[result]" (old));
-@end example
-
-@anchor{Clobbers and Scratch Registers}
-@subsubsection Clobbers and Scratch Registers
-@cindex @code{asm} clobbers
-@cindex @code{asm} scratch registers
-
-While the compiler is aware of changes to entries listed in the output
-operands, the inline @code{asm} code may modify more than just the outputs. For
-example, calculations may require additional registers, or the processor may
-overwrite a register as a side effect of a particular assembler instruction.
-In order to inform the compiler of these changes, list them in the clobber
-list. Clobber list items are either register names or the special clobbers
-(listed below). Each clobber list item is a string constant
-enclosed in double quotes and separated by commas.
-
-Clobber descriptions may not in any way overlap with an input or output
-operand. For example, you may not have an operand describing a register class
-with one member when listing that register in the clobber list. Variables
-declared to live in specific registers (@pxref{Explicit Register
-Variables}) and used
-as @code{asm} input or output operands must have no part mentioned in the
-clobber description. In particular, there is no way to specify that input
-operands get modified without also specifying them as output operands.
-
-When the compiler selects which registers to use to represent input and output
-operands, it does not use any of the clobbered registers. As a result,
-clobbered registers are available for any use in the assembler code.
-
-Another restriction is that the clobber list should not contain the
-stack pointer register. This is because the compiler requires the
-value of the stack pointer to be the same after an @code{asm}
-statement as it was on entry to the statement. However, previous
-versions of GCC did not enforce this rule and allowed the stack
-pointer to appear in the list, with unclear semantics. This behavior
-is deprecated and listing the stack pointer may become an error in
-future versions of GCC@.
-
-Here is a realistic example for the VAX showing the use of clobbered
-registers:
-
-@example
-asm volatile ("movc3 %0, %1, %2"
- : /* No outputs. */
- : "g" (from), "g" (to), "g" (count)
- : "r0", "r1", "r2", "r3", "r4", "r5", "memory");
-@end example
-
-Also, there are two special clobber arguments:
-
-@table @code
-@item "cc"
-The @code{"cc"} clobber indicates that the assembler code modifies the flags
-register. On some machines, GCC represents the condition codes as a specific
-hardware register; @code{"cc"} serves to name this register.
-On other machines, condition code handling is different,
-and specifying @code{"cc"} has no effect. But
-it is valid no matter what the target.
-
-@item "memory"
-The @code{"memory"} clobber tells the compiler that the assembly code
-performs memory
-reads or writes to items other than those listed in the input and output
-operands (for example, accessing the memory pointed to by one of the input
-parameters). To ensure memory contains correct values, GCC may need to flush
-specific register values to memory before executing the @code{asm}. Further,
-the compiler does not assume that any values read from memory before an
-@code{asm} remain unchanged after that @code{asm}; it reloads them as
-needed.
-Using the @code{"memory"} clobber effectively forms a read/write
-memory barrier for the compiler.
-
-Note that this clobber does not prevent the @emph{processor} from doing
-speculative reads past the @code{asm} statement. To prevent that, you need
-processor-specific fence instructions.
-
-@end table
-
-Flushing registers to memory has performance implications and may be
-an issue for time-sensitive code. You can provide better information
-to GCC to avoid this, as shown in the following examples. At a
-minimum, aliasing rules allow GCC to know what memory @emph{doesn't}
-need to be flushed.
-
-Here is a fictitious sum of squares instruction, that takes two
-pointers to floating point values in memory and produces a floating
-point register output.
-Notice that @code{x}, and @code{y} both appear twice in the @code{asm}
-parameters, once to specify memory accessed, and once to specify a
-base register used by the @code{asm}. You won't normally be wasting a
-register by doing this as GCC can use the same register for both
-purposes. However, it would be foolish to use both @code{%1} and
-@code{%3} for @code{x} in this @code{asm} and expect them to be the
-same. In fact, @code{%3} may well not be a register. It might be a
-symbolic memory reference to the object pointed to by @code{x}.
-
-@smallexample
-asm ("sumsq %0, %1, %2"
- : "+f" (result)
- : "r" (x), "r" (y), "m" (*x), "m" (*y));
-@end smallexample
-
-Here is a fictitious @code{*z++ = *x++ * *y++} instruction.
-Notice that the @code{x}, @code{y} and @code{z} pointer registers
-must be specified as input/output because the @code{asm} modifies
-them.
-
-@smallexample
-asm ("vecmul %0, %1, %2"
- : "+r" (z), "+r" (x), "+r" (y), "=m" (*z)
- : "m" (*x), "m" (*y));
-@end smallexample
-
-An x86 example where the string memory argument is of unknown length.
-
-@smallexample
-asm("repne scasb"
- : "=c" (count), "+D" (p)
- : "m" (*(const char (*)[]) p), "0" (-1), "a" (0));
-@end smallexample
-
-If you know the above will only be reading a ten byte array then you
-could instead use a memory input like:
-@code{"m" (*(const char (*)[10]) p)}.
-
-Here is an example of a PowerPC vector scale implemented in assembly,
-complete with vector and condition code clobbers, and some initialized
-offset registers that are unchanged by the @code{asm}.
-
-@smallexample
-void
-dscal (size_t n, double *x, double alpha)
-@{
- asm ("/* lots of asm here */"
- : "+m" (*(double (*)[n]) x), "+&r" (n), "+b" (x)
- : "d" (alpha), "b" (32), "b" (48), "b" (64),
- "b" (80), "b" (96), "b" (112)
- : "cr0",
- "vs32","vs33","vs34","vs35","vs36","vs37","vs38","vs39",
- "vs40","vs41","vs42","vs43","vs44","vs45","vs46","vs47");
-@}
-@end smallexample
-
-Rather than allocating fixed registers via clobbers to provide scratch
-registers for an @code{asm} statement, an alternative is to define a
-variable and make it an early-clobber output as with @code{a2} and
-@code{a3} in the example below. This gives the compiler register
-allocator more freedom. You can also define a variable and make it an
-output tied to an input as with @code{a0} and @code{a1}, tied
-respectively to @code{ap} and @code{lda}. Of course, with tied
-outputs your @code{asm} can't use the input value after modifying the
-output register since they are one and the same register. What's
-more, if you omit the early-clobber on the output, it is possible that
-GCC might allocate the same register to another of the inputs if GCC
-could prove they had the same value on entry to the @code{asm}. This
-is why @code{a1} has an early-clobber. Its tied input, @code{lda}
-might conceivably be known to have the value 16 and without an
-early-clobber share the same register as @code{%11}. On the other
-hand, @code{ap} can't be the same as any of the other inputs, so an
-early-clobber on @code{a0} is not needed. It is also not desirable in
-this case. An early-clobber on @code{a0} would cause GCC to allocate
-a separate register for the @code{"m" (*(const double (*)[]) ap)}
-input. Note that tying an input to an output is the way to set up an
-initialized temporary register modified by an @code{asm} statement.
-An input not tied to an output is assumed by GCC to be unchanged, for
-example @code{"b" (16)} below sets up @code{%11} to 16, and GCC might
-use that register in following code if the value 16 happened to be
-needed. You can even use a normal @code{asm} output for a scratch if
-all inputs that might share the same register are consumed before the
-scratch is used. The VSX registers clobbered by the @code{asm}
-statement could have used this technique except for GCC's limit on the
-number of @code{asm} parameters.
-
-@smallexample
-static void
-dgemv_kernel_4x4 (long n, const double *ap, long lda,
- const double *x, double *y, double alpha)
-@{
- double *a0;
- double *a1;
- double *a2;
- double *a3;
-
- __asm__
- (
- /* lots of asm here */
- "#n=%1 ap=%8=%12 lda=%13 x=%7=%10 y=%0=%2 alpha=%9 o16=%11\n"
- "#a0=%3 a1=%4 a2=%5 a3=%6"
- :
- "+m" (*(double (*)[n]) y),
- "+&r" (n), // 1
- "+b" (y), // 2
- "=b" (a0), // 3
- "=&b" (a1), // 4
- "=&b" (a2), // 5
- "=&b" (a3) // 6
- :
- "m" (*(const double (*)[n]) x),
- "m" (*(const double (*)[]) ap),
- "d" (alpha), // 9
- "r" (x), // 10
- "b" (16), // 11
- "3" (ap), // 12
- "4" (lda) // 13
- :
- "cr0",
- "vs32","vs33","vs34","vs35","vs36","vs37",
- "vs40","vs41","vs42","vs43","vs44","vs45","vs46","vs47"
- );
-@}
-@end smallexample
-
-@anchor{GotoLabels}
-@subsubsection Goto Labels
-@cindex @code{asm} goto labels
-
-@code{asm goto} allows assembly code to jump to one or more C labels. The
-@var{GotoLabels} section in an @code{asm goto} statement contains
-a comma-separated
-list of all C labels to which the assembler code may jump. GCC assumes that
-@code{asm} execution falls through to the next statement (if this is not the
-case, consider using the @code{__builtin_unreachable} intrinsic after the
-@code{asm} statement). Optimization of @code{asm goto} may be improved by
-using the @code{hot} and @code{cold} label attributes (@pxref{Label
-Attributes}).
-
-If the assembler code does modify anything, use the @code{"memory"} clobber
-to force the
-optimizers to flush all register values to memory and reload them if
-necessary after the @code{asm} statement.
-
-Also note that an @code{asm goto} statement is always implicitly
-considered volatile.
-
-Be careful when you set output operands inside @code{asm goto} only on
-some possible control flow paths. If you don't set up the output on
-given path and never use it on this path, it is okay. Otherwise, you
-should use @samp{+} constraint modifier meaning that the operand is
-input and output one. With this modifier you will have the correct
-values on all possible paths from the @code{asm goto}.
-
-To reference a label in the assembler template, prefix it with
-@samp{%l} (lowercase @samp{L}) followed by its (zero-based) position
-in @var{GotoLabels} plus the number of input and output operands.
-Output operand with constraint modifier @samp{+} is counted as two
-operands because it is considered as one output and one input operand.
-For example, if the @code{asm} has three inputs, one output operand
-with constraint modifier @samp{+} and one output operand with
-constraint modifier @samp{=} and references two labels, refer to the
-first label as @samp{%l6} and the second as @samp{%l7}).
-
-Alternately, you can reference labels using the actual C label name
-enclosed in brackets. For example, to reference a label named
-@code{carry}, you can use @samp{%l[carry]}. The label must still be
-listed in the @var{GotoLabels} section when using this approach. It
-is better to use the named references for labels as in this case you
-can avoid counting input and output operands and special treatment of
-output operands with constraint modifier @samp{+}.
-
-Here is an example of @code{asm goto} for i386:
-
-@example
-asm goto (
- "btl %1, %0\n\t"
- "jc %l2"
- : /* No outputs. */
- : "r" (p1), "r" (p2)
- : "cc"
- : carry);
-
-return 0;
-
-carry:
-return 1;
-@end example
-
-The following example shows an @code{asm goto} that uses a memory clobber.
-
-@example
-int frob(int x)
-@{
- int y;
- asm goto ("frob %%r5, %1; jc %l[error]; mov (%2), %%r5"
- : /* No outputs. */
- : "r"(x), "r"(&y)
- : "r5", "memory"
- : error);
- return y;
-error:
- return -1;
-@}
-@end example
-
-The following example shows an @code{asm goto} that uses an output.
-
-@example
-int foo(int count)
-@{
- asm goto ("dec %0; jb %l[stop]"
- : "+r" (count)
- :
- :
- : stop);
- return count;
-stop:
- return 0;
-@}
-@end example
-
-The following artificial example shows an @code{asm goto} that sets
-up an output only on one path inside the @code{asm goto}. Usage of
-constraint modifier @code{=} instead of @code{+} would be wrong as
-@code{factor} is used on all paths from the @code{asm goto}.
-
-@example
-int foo(int inp)
-@{
- int factor = 0;
- asm goto ("cmp %1, 10; jb %l[lab]; mov 2, %0"
- : "+r" (factor)
- : "r" (inp)
- :
- : lab);
-lab:
- return inp * factor; /* return 2 * inp or 0 if inp < 10 */
-@}
-@end example
-
-@anchor{x86Operandmodifiers}
-@subsubsection x86 Operand Modifiers
-
-References to input, output, and goto operands in the assembler template
-of extended @code{asm} statements can use
-modifiers to affect the way the operands are formatted in
-the code output to the assembler. For example, the
-following code uses the @samp{h} and @samp{b} modifiers for x86:
-
-@example
-uint16_t num;
-asm volatile ("xchg %h0, %b0" : "+a" (num) );
-@end example
-
-@noindent
-These modifiers generate this assembler code:
-
-@example
-xchg %ah, %al
-@end example
-
-The rest of this discussion uses the following code for illustrative purposes.
-
-@example
-int main()
-@{
- int iInt = 1;
-
-top:
-
- asm volatile goto ("some assembler instructions here"
- : /* No outputs. */
- : "q" (iInt), "X" (sizeof(unsigned char) + 1), "i" (42)
- : /* No clobbers. */
- : top);
-@}
-@end example
-
-With no modifiers, this is what the output from the operands would be
-for the @samp{att} and @samp{intel} dialects of assembler:
-
-@multitable {Operand} {$.L2} {OFFSET FLAT:.L2}
-@headitem Operand @tab @samp{att} @tab @samp{intel}
-@item @code{%0}
-@tab @code{%eax}
-@tab @code{eax}
-@item @code{%1}
-@tab @code{$2}
-@tab @code{2}
-@item @code{%3}
-@tab @code{$.L3}
-@tab @code{OFFSET FLAT:.L3}
-@item @code{%4}
-@tab @code{$8}
-@tab @code{8}
-@item @code{%5}
-@tab @code{%xmm0}
-@tab @code{xmm0}
-@item @code{%7}
-@tab @code{$0}
-@tab @code{0}
-@end multitable
-
-The table below shows the list of supported modifiers and their effects.
-
-@multitable {Modifier} {Print the opcode suffix for the size of th} {Operand} {@samp{att}} {@samp{intel}}
-@headitem Modifier @tab Description @tab Operand @tab @samp{att} @tab @samp{intel}
-@item @code{A}
-@tab Print an absolute memory reference.
-@tab @code{%A0}
-@tab @code{*%rax}
-@tab @code{rax}
-@item @code{b}
-@tab Print the QImode name of the register.
-@tab @code{%b0}
-@tab @code{%al}
-@tab @code{al}
-@item @code{B}
-@tab print the opcode suffix of b.
-@tab @code{%B0}
-@tab @code{b}
-@tab
-@item @code{c}
-@tab Require a constant operand and print the constant expression with no punctuation.
-@tab @code{%c1}
-@tab @code{2}
-@tab @code{2}
-@item @code{d}
-@tab print duplicated register operand for AVX instruction.
-@tab @code{%d5}
-@tab @code{%xmm0, %xmm0}
-@tab @code{xmm0, xmm0}
-@item @code{E}
-@tab Print the address in Double Integer (DImode) mode (8 bytes) when the target is 64-bit.
-Otherwise mode is unspecified (VOIDmode).
-@tab @code{%E1}
-@tab @code{%(rax)}
-@tab @code{[rax]}
-@item @code{g}
-@tab Print the V16SFmode name of the register.
-@tab @code{%g0}
-@tab @code{%zmm0}
-@tab @code{zmm0}
-@item @code{h}
-@tab Print the QImode name for a ``high'' register.
-@tab @code{%h0}
-@tab @code{%ah}
-@tab @code{ah}
-@item @code{H}
-@tab Add 8 bytes to an offsettable memory reference. Useful when accessing the
-high 8 bytes of SSE values. For a memref in (%rax), it generates
-@tab @code{%H0}
-@tab @code{8(%rax)}
-@tab @code{8[rax]}
-@item @code{k}
-@tab Print the SImode name of the register.
-@tab @code{%k0}
-@tab @code{%eax}
-@tab @code{eax}
-@item @code{l}
-@tab Print the label name with no punctuation.
-@tab @code{%l3}
-@tab @code{.L3}
-@tab @code{.L3}
-@item @code{L}
-@tab print the opcode suffix of l.
-@tab @code{%L0}
-@tab @code{l}
-@tab
-@item @code{N}
-@tab print maskz.
-@tab @code{%N7}
-@tab @code{@{z@}}
-@tab @code{@{z@}}
-@item @code{p}
-@tab Print raw symbol name (without syntax-specific prefixes).
-@tab @code{%p2}
-@tab @code{42}
-@tab @code{42}
-@item @code{P}
-@tab If used for a function, print the PLT suffix and generate PIC code.
-For example, emit @code{foo@@PLT} instead of 'foo' for the function
-foo(). If used for a constant, drop all syntax-specific prefixes and
-issue the bare constant. See @code{p} above.
-@item @code{q}
-@tab Print the DImode name of the register.
-@tab @code{%q0}
-@tab @code{%rax}
-@tab @code{rax}
-@item @code{Q}
-@tab print the opcode suffix of q.
-@tab @code{%Q0}
-@tab @code{q}
-@tab
-@item @code{R}
-@tab print embedded rounding and sae.
-@tab @code{%R4}
-@tab @code{@{rn-sae@}, }
-@tab @code{, @{rn-sae@}}
-@item @code{r}
-@tab print only sae.
-@tab @code{%r4}
-@tab @code{@{sae@}, }
-@tab @code{, @{sae@}}
-@item @code{s}
-@tab print a shift double count, followed by the assemblers argument
-delimiterprint the opcode suffix of s.
-@tab @code{%s1}
-@tab @code{$2, }
-@tab @code{2, }
-@item @code{S}
-@tab print the opcode suffix of s.
-@tab @code{%S0}
-@tab @code{s}
-@tab
-@item @code{t}
-@tab print the V8SFmode name of the register.
-@tab @code{%t5}
-@tab @code{%ymm0}
-@tab @code{ymm0}
-@item @code{T}
-@tab print the opcode suffix of t.
-@tab @code{%T0}
-@tab @code{t}
-@tab
-@item @code{V}
-@tab print naked full integer register name without %.
-@tab @code{%V0}
-@tab @code{eax}
-@tab @code{eax}
-@item @code{w}
-@tab Print the HImode name of the register.
-@tab @code{%w0}
-@tab @code{%ax}
-@tab @code{ax}
-@item @code{W}
-@tab print the opcode suffix of w.
-@tab @code{%W0}
-@tab @code{w}
-@tab
-@item @code{x}
-@tab print the V4SFmode name of the register.
-@tab @code{%x5}
-@tab @code{%xmm0}
-@tab @code{xmm0}
-@item @code{y}
-@tab print "st(0)" instead of "st" as a register.
-@tab @code{%y6}
-@tab @code{%st(0)}
-@tab @code{st(0)}
-@item @code{z}
-@tab Print the opcode suffix for the size of the current integer operand (one of @code{b}/@code{w}/@code{l}/@code{q}).
-@tab @code{%z0}
-@tab @code{l}
-@tab
-@item @code{Z}
-@tab Like @code{z}, with special suffixes for x87 instructions.
-@end multitable
-
-
-@anchor{x86floatingpointasmoperands}
-@subsubsection x86 Floating-Point @code{asm} Operands
-
-On x86 targets, there are several rules on the usage of stack-like registers
-in the operands of an @code{asm}. These rules apply only to the operands
-that are stack-like registers:
-
-@enumerate
-@item
-Given a set of input registers that die in an @code{asm}, it is
-necessary to know which are implicitly popped by the @code{asm}, and
-which must be explicitly popped by GCC@.
-
-An input register that is implicitly popped by the @code{asm} must be
-explicitly clobbered, unless it is constrained to match an
-output operand.
-
-@item
-For any input register that is implicitly popped by an @code{asm}, it is
-necessary to know how to adjust the stack to compensate for the pop.
-If any non-popped input is closer to the top of the reg-stack than
-the implicitly popped register, it would not be possible to know what the
-stack looked like---it's not clear how the rest of the stack ``slides
-up''.
-
-All implicitly popped input registers must be closer to the top of
-the reg-stack than any input that is not implicitly popped.
-
-It is possible that if an input dies in an @code{asm}, the compiler might
-use the input register for an output reload. Consider this example:
-
-@smallexample
-asm ("foo" : "=t" (a) : "f" (b));
-@end smallexample
-
-@noindent
-This code says that input @code{b} is not popped by the @code{asm}, and that
-the @code{asm} pushes a result onto the reg-stack, i.e., the stack is one
-deeper after the @code{asm} than it was before. But, it is possible that
-reload may think that it can use the same register for both the input and
-the output.
-
-To prevent this from happening,
-if any input operand uses the @samp{f} constraint, all output register
-constraints must use the @samp{&} early-clobber modifier.
-
-The example above is correctly written as:
-
-@smallexample
-asm ("foo" : "=&t" (a) : "f" (b));
-@end smallexample
-
-@item
-Some operands need to be in particular places on the stack. All
-output operands fall in this category---GCC has no other way to
-know which registers the outputs appear in unless you indicate
-this in the constraints.
-
-Output operands must specifically indicate which register an output
-appears in after an @code{asm}. @samp{=f} is not allowed: the operand
-constraints must select a class with a single register.
-
-@item
-Output operands may not be ``inserted'' between existing stack registers.
-Since no 387 opcode uses a read/write operand, all output operands
-are dead before the @code{asm}, and are pushed by the @code{asm}.
-It makes no sense to push anywhere but the top of the reg-stack.
-
-Output operands must start at the top of the reg-stack: output
-operands may not ``skip'' a register.
-
-@item
-Some @code{asm} statements may need extra stack space for internal
-calculations. This can be guaranteed by clobbering stack registers
-unrelated to the inputs and outputs.
-
-@end enumerate
-
-This @code{asm}
-takes one input, which is internally popped, and produces two outputs.
-
-@smallexample
-asm ("fsincos" : "=t" (cos), "=u" (sin) : "0" (inp));
-@end smallexample
-
-@noindent
-This @code{asm} takes two inputs, which are popped by the @code{fyl2xp1} opcode,
-and replaces them with one output. The @code{st(1)} clobber is necessary
-for the compiler to know that @code{fyl2xp1} pops both inputs.
-
-@smallexample
-asm ("fyl2xp1" : "=t" (result) : "0" (x), "u" (y) : "st(1)");
-@end smallexample
-
-@anchor{msp430Operandmodifiers}
-@subsubsection MSP430 Operand Modifiers
-
-The list below describes the supported modifiers and their effects for MSP430.
-
-@multitable @columnfractions .10 .90
-@headitem Modifier @tab Description
-@item @code{A} @tab Select low 16-bits of the constant/register/memory operand.
-@item @code{B} @tab Select high 16-bits of the constant/register/memory
-operand.
-@item @code{C} @tab Select bits 32-47 of the constant/register/memory operand.
-@item @code{D} @tab Select bits 48-63 of the constant/register/memory operand.
-@item @code{H} @tab Equivalent to @code{B} (for backwards compatibility).
-@item @code{I} @tab Print the inverse (logical @code{NOT}) of the constant
-value.
-@item @code{J} @tab Print an integer without a @code{#} prefix.
-@item @code{L} @tab Equivalent to @code{A} (for backwards compatibility).
-@item @code{O} @tab Offset of the current frame from the top of the stack.
-@item @code{Q} @tab Use the @code{A} instruction postfix.
-@item @code{R} @tab Inverse of condition code, for unsigned comparisons.
-@item @code{W} @tab Subtract 16 from the constant value.
-@item @code{X} @tab Use the @code{X} instruction postfix.
-@item @code{Y} @tab Subtract 4 from the constant value.
-@item @code{Z} @tab Subtract 1 from the constant value.
-@item @code{b} @tab Append @code{.B}, @code{.W} or @code{.A} to the
-instruction, depending on the mode.
-@item @code{d} @tab Offset 1 byte of a memory reference or constant value.
-@item @code{e} @tab Offset 3 bytes of a memory reference or constant value.
-@item @code{f} @tab Offset 5 bytes of a memory reference or constant value.
-@item @code{g} @tab Offset 7 bytes of a memory reference or constant value.
-@item @code{p} @tab Print the value of 2, raised to the power of the given
-constant. Used to select the specified bit position.
-@item @code{r} @tab Inverse of condition code, for signed comparisons.
-@item @code{x} @tab Equivialent to @code{X}, but only for pointers.
-@end multitable
-
-@lowersections
-@include md.texi
-@raisesections
-
-@node Asm Labels
-@subsection Controlling Names Used in Assembler Code
-@cindex assembler names for identifiers
-@cindex names used in assembler code
-@cindex identifiers, names in assembler code
-
-You can specify the name to be used in the assembler code for a C
-function or variable by writing the @code{asm} (or @code{__asm__})
-keyword after the declarator.
-It is up to you to make sure that the assembler names you choose do not
-conflict with any other assembler symbols, or reference registers.
-
-@subsubheading Assembler names for data
-
-This sample shows how to specify the assembler name for data:
-
-@smallexample
-int foo asm ("myfoo") = 2;
-@end smallexample
-
-@noindent
-This specifies that the name to be used for the variable @code{foo} in
-the assembler code should be @samp{myfoo} rather than the usual
-@samp{_foo}.
-
-On systems where an underscore is normally prepended to the name of a C
-variable, this feature allows you to define names for the
-linker that do not start with an underscore.
-
-GCC does not support using this feature with a non-static local variable
-since such variables do not have assembler names. If you are
-trying to put the variable in a particular register, see
-@ref{Explicit Register Variables}.
-
-@subsubheading Assembler names for functions
-
-To specify the assembler name for functions, write a declaration for the
-function before its definition and put @code{asm} there, like this:
-
-@smallexample
-int func (int x, int y) asm ("MYFUNC");
-
-int func (int x, int y)
-@{
- /* @r{@dots{}} */
-@end smallexample
-
-@noindent
-This specifies that the name to be used for the function @code{func} in
-the assembler code should be @code{MYFUNC}.
-
-@node Explicit Register Variables
-@subsection Variables in Specified Registers
-@anchor{Explicit Reg Vars}
-@cindex explicit register variables
-@cindex variables in specified registers
-@cindex specified registers
-
-GNU C allows you to associate specific hardware registers with C
-variables. In almost all cases, allowing the compiler to assign
-registers produces the best code. However under certain unusual
-circumstances, more precise control over the variable storage is
-required.
-
-Both global and local variables can be associated with a register. The
-consequences of performing this association are very different between
-the two, as explained in the sections below.
-
-@menu
-* Global Register Variables:: Variables declared at global scope.
-* Local Register Variables:: Variables declared within a function.
-@end menu
-
-@node Global Register Variables
-@subsubsection Defining Global Register Variables
-@anchor{Global Reg Vars}
-@cindex global register variables
-@cindex registers, global variables in
-@cindex registers, global allocation
-
-You can define a global register variable and associate it with a specified
-register like this:
-
-@smallexample
-register int *foo asm ("r12");
-@end smallexample
-
-@noindent
-Here @code{r12} is the name of the register that should be used. Note that
-this is the same syntax used for defining local register variables, but for
-a global variable the declaration appears outside a function. The
-@code{register} keyword is required, and cannot be combined with
-@code{static}. The register name must be a valid register name for the
-target platform.
-
-Do not use type qualifiers such as @code{const} and @code{volatile}, as
-the outcome may be contrary to expectations. In particular, using the
-@code{volatile} qualifier does not fully prevent the compiler from
-optimizing accesses to the register.
-
-Registers are a scarce resource on most systems and allowing the
-compiler to manage their usage usually results in the best code. However,
-under special circumstances it can make sense to reserve some globally.
-For example this may be useful in programs such as programming language
-interpreters that have a couple of global variables that are accessed
-very often.
-
-After defining a global register variable, for the current compilation
-unit:
-
-@itemize @bullet
-@item If the register is a call-saved register, call ABI is affected:
-the register will not be restored in function epilogue sequences after
-the variable has been assigned. Therefore, functions cannot safely
-return to callers that assume standard ABI.
-@item Conversely, if the register is a call-clobbered register, making
-calls to functions that use standard ABI may lose contents of the variable.
-Such calls may be created by the compiler even if none are evident in
-the original program, for example when libgcc functions are used to
-make up for unavailable instructions.
-@item Accesses to the variable may be optimized as usual and the register
-remains available for allocation and use in any computations, provided that
-observable values of the variable are not affected.
-@item If the variable is referenced in inline assembly, the type of access
-must be provided to the compiler via constraints (@pxref{Constraints}).
-Accesses from basic asms are not supported.
-@end itemize
-
-Note that these points @emph{only} apply to code that is compiled with the
-definition. The behavior of code that is merely linked in (for example
-code from libraries) is not affected.
-
-If you want to recompile source files that do not actually use your global
-register variable so they do not use the specified register for any other
-purpose, you need not actually add the global register declaration to
-their source code. It suffices to specify the compiler option
-@option{-ffixed-@var{reg}} (@pxref{Code Gen Options}) to reserve the
-register.
-
-@subsubheading Declaring the variable
-
-Global register variables cannot have initial values, because an
-executable file has no means to supply initial contents for a register.
-
-When selecting a register, choose one that is normally saved and
-restored by function calls on your machine. This ensures that code
-which is unaware of this reservation (such as library routines) will
-restore it before returning.
-
-On machines with register windows, be sure to choose a global
-register that is not affected magically by the function call mechanism.
-
-@subsubheading Using the variable
-
-@cindex @code{qsort}, and global register variables
-When calling routines that are not aware of the reservation, be
-cautious if those routines call back into code which uses them. As an
-example, if you call the system library version of @code{qsort}, it may
-clobber your registers during execution, but (if you have selected
-appropriate registers) it will restore them before returning. However
-it will @emph{not} restore them before calling @code{qsort}'s comparison
-function. As a result, global values will not reliably be available to
-the comparison function unless the @code{qsort} function itself is rebuilt.
-
-Similarly, it is not safe to access the global register variables from signal
-handlers or from more than one thread of control. Unless you recompile
-them specially for the task at hand, the system library routines may
-temporarily use the register for other things. Furthermore, since the register
-is not reserved exclusively for the variable, accessing it from handlers of
-asynchronous signals may observe unrelated temporary values residing in the
-register.
-
-@cindex register variable after @code{longjmp}
-@cindex global register after @code{longjmp}
-@cindex value after @code{longjmp}
-@findex longjmp
-@findex setjmp
-On most machines, @code{longjmp} restores to each global register
-variable the value it had at the time of the @code{setjmp}. On some
-machines, however, @code{longjmp} does not change the value of global
-register variables. To be portable, the function that called @code{setjmp}
-should make other arrangements to save the values of the global register
-variables, and to restore them in a @code{longjmp}. This way, the same
-thing happens regardless of what @code{longjmp} does.
-
-@node Local Register Variables
-@subsubsection Specifying Registers for Local Variables
-@anchor{Local Reg Vars}
-@cindex local variables, specifying registers
-@cindex specifying registers for local variables
-@cindex registers for local variables
-
-You can define a local register variable and associate it with a specified
-register like this:
-
-@smallexample
-register int *foo asm ("r12");
-@end smallexample
-
-@noindent
-Here @code{r12} is the name of the register that should be used. Note
-that this is the same syntax used for defining global register variables,
-but for a local variable the declaration appears within a function. The
-@code{register} keyword is required, and cannot be combined with
-@code{static}. The register name must be a valid register name for the
-target platform.
-
-Do not use type qualifiers such as @code{const} and @code{volatile}, as
-the outcome may be contrary to expectations. In particular, when the
-@code{const} qualifier is used, the compiler may substitute the
-variable with its initializer in @code{asm} statements, which may cause
-the corresponding operand to appear in a different register.
-
-As with global register variables, it is recommended that you choose
-a register that is normally saved and restored by function calls on your
-machine, so that calls to library routines will not clobber it.
-
-The only supported use for this feature is to specify registers
-for input and output operands when calling Extended @code{asm}
-(@pxref{Extended Asm}). This may be necessary if the constraints for a
-particular machine don't provide sufficient control to select the desired
-register. To force an operand into a register, create a local variable
-and specify the register name after the variable's declaration. Then use
-the local variable for the @code{asm} operand and specify any constraint
-letter that matches the register:
-
-@smallexample
-register int *p1 asm ("r0") = @dots{};
-register int *p2 asm ("r1") = @dots{};
-register int *result asm ("r0");
-asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2));
-@end smallexample
-
-@emph{Warning:} In the above example, be aware that a register (for example
-@code{r0}) can be call-clobbered by subsequent code, including function
-calls and library calls for arithmetic operators on other variables (for
-example the initialization of @code{p2}). In this case, use temporary
-variables for expressions between the register assignments:
-
-@smallexample
-int t1 = @dots{};
-register int *p1 asm ("r0") = @dots{};
-register int *p2 asm ("r1") = t1;
-register int *result asm ("r0");
-asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2));
-@end smallexample
-
-Defining a register variable does not reserve the register. Other than
-when invoking the Extended @code{asm}, the contents of the specified
-register are not guaranteed. For this reason, the following uses
-are explicitly @emph{not} supported. If they appear to work, it is only
-happenstance, and may stop working as intended due to (seemingly)
-unrelated changes in surrounding code, or even minor changes in the
-optimization of a future version of gcc:
-
-@itemize @bullet
-@item Passing parameters to or from Basic @code{asm}
-@item Passing parameters to or from Extended @code{asm} without using input
-or output operands.
-@item Passing parameters to or from routines written in assembler (or
-other languages) using non-standard calling conventions.
-@end itemize
-
-Some developers use Local Register Variables in an attempt to improve
-gcc's allocation of registers, especially in large functions. In this
-case the register name is essentially a hint to the register allocator.
-While in some instances this can generate better code, improvements are
-subject to the whims of the allocator/optimizers. Since there are no
-guarantees that your improvements won't be lost, this usage of Local
-Register Variables is discouraged.
-
-On the MIPS platform, there is related use for local register variables
-with slightly different characteristics (@pxref{MIPS Coprocessors,,
-Defining coprocessor specifics for MIPS targets, gccint,
-GNU Compiler Collection (GCC) Internals}).
-
-@node Size of an asm
-@subsection Size of an @code{asm}
-
-Some targets require that GCC track the size of each instruction used
-in order to generate correct code. Because the final length of the
-code produced by an @code{asm} statement is only known by the
-assembler, GCC must make an estimate as to how big it will be. It
-does this by counting the number of instructions in the pattern of the
-@code{asm} and multiplying that by the length of the longest
-instruction supported by that processor. (When working out the number
-of instructions, it assumes that any occurrence of a newline or of
-whatever statement separator character is supported by the assembler ---
-typically @samp{;} --- indicates the end of an instruction.)
-
-Normally, GCC's estimate is adequate to ensure that correct
-code is generated, but it is possible to confuse the compiler if you use
-pseudo instructions or assembler macros that expand into multiple real
-instructions, or if you use assembler directives that expand to more
-space in the object file than is needed for a single instruction.
-If this happens then the assembler may produce a diagnostic saying that
-a label is unreachable.
-
-@cindex @code{asm inline}
-This size is also used for inlining decisions. If you use @code{asm inline}
-instead of just @code{asm}, then for inlining purposes the size of the asm
-is taken as the minimum size, ignoring how many instructions GCC thinks it is.
-
-@node Alternate Keywords
-@section Alternate Keywords
-@cindex alternate keywords
-@cindex keywords, alternate
-
-@option{-ansi} and the various @option{-std} options disable certain
-keywords. This causes trouble when you want to use GNU C extensions, or
-a general-purpose header file that should be usable by all programs,
-including ISO C programs. The keywords @code{asm}, @code{typeof} and
-@code{inline} are not available in programs compiled with
-@option{-ansi} or @option{-std} (although @code{inline} can be used in a
-program compiled with @option{-std=c99} or a later standard). The
-ISO C99 keyword
-@code{restrict} is only available when @option{-std=gnu99} (which will
-eventually be the default) or @option{-std=c99} (or the equivalent
-@option{-std=iso9899:1999}), or an option for a later standard
-version, is used.
-
-The way to solve these problems is to put @samp{__} at the beginning and
-end of each problematical keyword. For example, use @code{__asm__}
-instead of @code{asm}, and @code{__inline__} instead of @code{inline}.
-
-Other C compilers won't accept these alternative keywords; if you want to
-compile with another compiler, you can define the alternate keywords as
-macros to replace them with the customary keywords. It looks like this:
-
-@smallexample
-#ifndef __GNUC__
-#define __asm__ asm
-#endif
-@end smallexample
-
-@findex __extension__
-@opindex pedantic
-@option{-pedantic} and other options cause warnings for many GNU C extensions.
-You can
-prevent such warnings within one expression by writing
-@code{__extension__} before the expression. @code{__extension__} has no
-effect aside from this.
-
-@node Incomplete Enums
-@section Incomplete @code{enum} Types
-
-You can define an @code{enum} tag without specifying its possible values.
-This results in an incomplete type, much like what you get if you write
-@code{struct foo} without describing the elements. A later declaration
-that does specify the possible values completes the type.
-
-You cannot allocate variables or storage using the type while it is
-incomplete. However, you can work with pointers to that type.
-
-This extension may not be very useful, but it makes the handling of
-@code{enum} more consistent with the way @code{struct} and @code{union}
-are handled.
-
-This extension is not supported by GNU C++.
-
-@node Function Names
-@section Function Names as Strings
-@cindex @code{__func__} identifier
-@cindex @code{__FUNCTION__} identifier
-@cindex @code{__PRETTY_FUNCTION__} identifier
-
-GCC provides three magic constants that hold the name of the current
-function as a string. In C++11 and later modes, all three are treated
-as constant expressions and can be used in @code{constexpr} constexts.
-The first of these constants is @code{__func__}, which is part of
-the C99 standard:
-
-The identifier @code{__func__} is implicitly declared by the translator
-as if, immediately following the opening brace of each function
-definition, the declaration
-
-@smallexample
-static const char __func__[] = "function-name";
-@end smallexample
-
-@noindent
-appeared, where function-name is the name of the lexically-enclosing
-function. This name is the unadorned name of the function. As an
-extension, at file (or, in C++, namespace scope), @code{__func__}
-evaluates to the empty string.
-
-@code{__FUNCTION__} is another name for @code{__func__}, provided for
-backward compatibility with old versions of GCC.
-
-In C, @code{__PRETTY_FUNCTION__} is yet another name for
-@code{__func__}, except that at file scope (or, in C++, namespace scope),
-it evaluates to the string @code{"top level"}. In addition, in C++,
-@code{__PRETTY_FUNCTION__} contains the signature of the function as
-well as its bare name. For example, this program:
-
-@smallexample
-extern "C" int printf (const char *, ...);
-
-class a @{
- public:
- void sub (int i)
- @{
- printf ("__FUNCTION__ = %s\n", __FUNCTION__);
- printf ("__PRETTY_FUNCTION__ = %s\n", __PRETTY_FUNCTION__);
- @}
-@};
-
-int
-main (void)
-@{
- a ax;
- ax.sub (0);
- return 0;
-@}
-@end smallexample
-
-@noindent
-gives this output:
-
-@smallexample
-__FUNCTION__ = sub
-__PRETTY_FUNCTION__ = void a::sub(int)
-@end smallexample
-
-These identifiers are variables, not preprocessor macros, and may not
-be used to initialize @code{char} arrays or be concatenated with string
-literals.
-
-@node Return Address
-@section Getting the Return or Frame Address of a Function
-
-These functions may be used to get information about the callers of a
-function.
-
-@deftypefn {Built-in Function} {void *} __builtin_return_address (unsigned int @var{level})
-This function returns the return address of the current function, or of
-one of its callers. The @var{level} argument is number of frames to
-scan up the call stack. A value of @code{0} yields the return address
-of the current function, a value of @code{1} yields the return address
-of the caller of the current function, and so forth. When inlining
-the expected behavior is that the function returns the address of
-the function that is returned to. To work around this behavior use
-the @code{noinline} function attribute.
-
-The @var{level} argument must be a constant integer.
-
-On some machines it may be impossible to determine the return address of
-any function other than the current one; in such cases, or when the top
-of the stack has been reached, this function returns an unspecified
-value. In addition, @code{__builtin_frame_address} may be used
-to determine if the top of the stack has been reached.
-
-Additional post-processing of the returned value may be needed, see
-@code{__builtin_extract_return_addr}.
-
-The stored representation of the return address in memory may be different
-from the address returned by @code{__builtin_return_address}. For example,
-on AArch64 the stored address may be mangled with return address signing
-whereas the address returned by @code{__builtin_return_address} is not.
-
-Calling this function with a nonzero argument can have unpredictable
-effects, including crashing the calling program. As a result, calls
-that are considered unsafe are diagnosed when the @option{-Wframe-address}
-option is in effect. Such calls should only be made in debugging
-situations.
-
-On targets where code addresses are representable as @code{void *},
-@smallexample
-void *addr = __builtin_extract_return_addr (__builtin_return_address (0));
-@end smallexample
-gives the code address where the current function would return. For example,
-such an address may be used with @code{dladdr} or other interfaces that work
-with code addresses.
-@end deftypefn
-
-@deftypefn {Built-in Function} {void *} __builtin_extract_return_addr (void *@var{addr})
-The address as returned by @code{__builtin_return_address} may have to be fed
-through this function to get the actual encoded address. For example, on the
-31-bit S/390 platform the highest bit has to be masked out, or on SPARC
-platforms an offset has to be added for the true next instruction to be
-executed.
-
-If no fixup is needed, this function simply passes through @var{addr}.
-@end deftypefn
-
-@deftypefn {Built-in Function} {void *} __builtin_frob_return_addr (void *@var{addr})
-This function does the reverse of @code{__builtin_extract_return_addr}.
-@end deftypefn
-
-@deftypefn {Built-in Function} {void *} __builtin_frame_address (unsigned int @var{level})
-This function is similar to @code{__builtin_return_address}, but it
-returns the address of the function frame rather than the return address
-of the function. Calling @code{__builtin_frame_address} with a value of
-@code{0} yields the frame address of the current function, a value of
-@code{1} yields the frame address of the caller of the current function,
-and so forth.
-
-The frame is the area on the stack that holds local variables and saved
-registers. The frame address is normally the address of the first word
-pushed on to the stack by the function. However, the exact definition
-depends upon the processor and the calling convention. If the processor
-has a dedicated frame pointer register, and the function has a frame,
-then @code{__builtin_frame_address} returns the value of the frame
-pointer register.
-
-On some machines it may be impossible to determine the frame address of
-any function other than the current one; in such cases, or when the top
-of the stack has been reached, this function returns @code{0} if
-the first frame pointer is properly initialized by the startup code.
-
-Calling this function with a nonzero argument can have unpredictable
-effects, including crashing the calling program. As a result, calls
-that are considered unsafe are diagnosed when the @option{-Wframe-address}
-option is in effect. Such calls should only be made in debugging
-situations.
-@end deftypefn
-
-@node Vector Extensions
-@section Using Vector Instructions through Built-in Functions
-
-On some targets, the instruction set contains SIMD vector instructions which
-operate on multiple values contained in one large register at the same time.
-For example, on the x86 the MMX, 3DNow!@: and SSE extensions can be used
-this way.
-
-The first step in using these extensions is to provide the necessary data
-types. This should be done using an appropriate @code{typedef}:
-
-@smallexample
-typedef int v4si __attribute__ ((vector_size (16)));
-@end smallexample
-
-@noindent
-The @code{int} type specifies the @dfn{base type}, while the attribute specifies
-the vector size for the variable, measured in bytes. For example, the
-declaration above causes the compiler to set the mode for the @code{v4si}
-type to be 16 bytes wide and divided into @code{int} sized units. For
-a 32-bit @code{int} this means a vector of 4 units of 4 bytes, and the
-corresponding mode of @code{foo} is @acronym{V4SI}.
-
-The @code{vector_size} attribute is only applicable to integral and
-floating scalars, although arrays, pointers, and function return values
-are allowed in conjunction with this construct. Only sizes that are
-positive power-of-two multiples of the base type size are currently allowed.
-
-All the basic integer types can be used as base types, both as signed
-and as unsigned: @code{char}, @code{short}, @code{int}, @code{long},
-@code{long long}. In addition, @code{float} and @code{double} can be
-used to build floating-point vector types.
-
-Specifying a combination that is not valid for the current architecture
-causes GCC to synthesize the instructions using a narrower mode.
-For example, if you specify a variable of type @code{V4SI} and your
-architecture does not allow for this specific SIMD type, GCC
-produces code that uses 4 @code{SIs}.
-
-The types defined in this manner can be used with a subset of normal C
-operations. Currently, GCC allows using the following operators
-on these types: @code{+, -, *, /, unary minus, ^, |, &, ~, %}@.
-
-The operations behave like C++ @code{valarrays}. Addition is defined as
-the addition of the corresponding elements of the operands. For
-example, in the code below, each of the 4 elements in @var{a} is
-added to the corresponding 4 elements in @var{b} and the resulting
-vector is stored in @var{c}.
-
-@smallexample
-typedef int v4si __attribute__ ((vector_size (16)));
-
-v4si a, b, c;
-
-c = a + b;
-@end smallexample
-
-Subtraction, multiplication, division, and the logical operations
-operate in a similar manner. Likewise, the result of using the unary
-minus or complement operators on a vector type is a vector whose
-elements are the negative or complemented values of the corresponding
-elements in the operand.
-
-It is possible to use shifting operators @code{<<}, @code{>>} on
-integer-type vectors. The operation is defined as following: @code{@{a0,
-a1, @dots{}, an@} >> @{b0, b1, @dots{}, bn@} == @{a0 >> b0, a1 >> b1,
-@dots{}, an >> bn@}}@. Vector operands must have the same number of
-elements.
-
-For convenience, it is allowed to use a binary vector operation
-where one operand is a scalar. In that case the compiler transforms
-the scalar operand into a vector where each element is the scalar from
-the operation. The transformation happens only if the scalar could be
-safely converted to the vector-element type.
-Consider the following code.
-
-@smallexample
-typedef int v4si __attribute__ ((vector_size (16)));
-
-v4si a, b, c;
-long l;
-
-a = b + 1; /* a = b + @{1,1,1,1@}; */
-a = 2 * b; /* a = @{2,2,2,2@} * b; */
-
-a = l + a; /* Error, cannot convert long to int. */
-@end smallexample
-
-Vectors can be subscripted as if the vector were an array with
-the same number of elements and base type. Out of bound accesses
-invoke undefined behavior at run time. Warnings for out of bound
-accesses for vector subscription can be enabled with
-@option{-Warray-bounds}.
-
-Vector comparison is supported with standard comparison
-operators: @code{==, !=, <, <=, >, >=}. Comparison operands can be
-vector expressions of integer-type or real-type. Comparison between
-integer-type vectors and real-type vectors are not supported. The
-result of the comparison is a vector of the same width and number of
-elements as the comparison operands with a signed integral element
-type.
-
-Vectors are compared element-wise producing 0 when comparison is false
-and -1 (constant of the appropriate type where all bits are set)
-otherwise. Consider the following example.
-
-@smallexample
-typedef int v4si __attribute__ ((vector_size (16)));
-
-v4si a = @{1,2,3,4@};
-v4si b = @{3,2,1,4@};
-v4si c;
-
-c = a > b; /* The result would be @{0, 0,-1, 0@} */
-c = a == b; /* The result would be @{0,-1, 0,-1@} */
-@end smallexample
-
-In C++, the ternary operator @code{?:} is available. @code{a?b:c}, where
-@code{b} and @code{c} are vectors of the same type and @code{a} is an
-integer vector with the same number of elements of the same size as @code{b}
-and @code{c}, computes all three arguments and creates a vector
-@code{@{a[0]?b[0]:c[0], a[1]?b[1]:c[1], @dots{}@}}. Note that unlike in
-OpenCL, @code{a} is thus interpreted as @code{a != 0} and not @code{a < 0}.
-As in the case of binary operations, this syntax is also accepted when
-one of @code{b} or @code{c} is a scalar that is then transformed into a
-vector. If both @code{b} and @code{c} are scalars and the type of
-@code{true?b:c} has the same size as the element type of @code{a}, then
-@code{b} and @code{c} are converted to a vector type whose elements have
-this type and with the same number of elements as @code{a}.
-
-In C++, the logic operators @code{!, &&, ||} are available for vectors.
-@code{!v} is equivalent to @code{v == 0}, @code{a && b} is equivalent to
-@code{a!=0 & b!=0} and @code{a || b} is equivalent to @code{a!=0 | b!=0}.
-For mixed operations between a scalar @code{s} and a vector @code{v},
-@code{s && v} is equivalent to @code{s?v!=0:0} (the evaluation is
-short-circuit) and @code{v && s} is equivalent to @code{v!=0 & (s?-1:0)}.
-
-@findex __builtin_shuffle
-Vector shuffling is available using functions
-@code{__builtin_shuffle (vec, mask)} and
-@code{__builtin_shuffle (vec0, vec1, mask)}.
-Both functions construct a permutation of elements from one or two
-vectors and return a vector of the same type as the input vector(s).
-The @var{mask} is an integral vector with the same width (@var{W})
-and element count (@var{N}) as the output vector.
-
-The elements of the input vectors are numbered in memory ordering of
-@var{vec0} beginning at 0 and @var{vec1} beginning at @var{N}. The
-elements of @var{mask} are considered modulo @var{N} in the single-operand
-case and modulo @math{2*@var{N}} in the two-operand case.
-
-Consider the following example,
-
-@smallexample
-typedef int v4si __attribute__ ((vector_size (16)));
-
-v4si a = @{1,2,3,4@};
-v4si b = @{5,6,7,8@};
-v4si mask1 = @{0,1,1,3@};
-v4si mask2 = @{0,4,2,5@};
-v4si res;
-
-res = __builtin_shuffle (a, mask1); /* res is @{1,2,2,4@} */
-res = __builtin_shuffle (a, b, mask2); /* res is @{1,5,3,6@} */
-@end smallexample
-
-Note that @code{__builtin_shuffle} is intentionally semantically
-compatible with the OpenCL @code{shuffle} and @code{shuffle2} functions.
-
-You can declare variables and use them in function calls and returns, as
-well as in assignments and some casts. You can specify a vector type as
-a return type for a function. Vector types can also be used as function
-arguments. It is possible to cast from one vector type to another,
-provided they are of the same size (in fact, you can also cast vectors
-to and from other datatypes of the same size).
-
-You cannot operate between vectors of different lengths or different
-signedness without a cast.
-
-@findex __builtin_shufflevector
-Vector shuffling is available using the
-@code{__builtin_shufflevector (vec1, vec2, index...)}
-function. @var{vec1} and @var{vec2} must be expressions with
-vector type with a compatible element type. The result of
-@code{__builtin_shufflevector} is a vector with the same element type
-as @var{vec1} and @var{vec2} but that has an element count equal to
-the number of indices specified.
-
-The @var{index} arguments are a list of integers that specify the
-elements indices of the first two vectors that should be extracted and
-returned in a new vector. These element indices are numbered sequentially
-starting with the first vector, continuing into the second vector.
-An index of -1 can be used to indicate that the corresponding element in
-the returned vector is a don't care and can be freely chosen to optimized
-the generated code sequence performing the shuffle operation.
-
-Consider the following example,
-@smallexample
-typedef int v4si __attribute__ ((vector_size (16)));
-typedef int v8si __attribute__ ((vector_size (32)));
-
-v8si a = @{1,-2,3,-4,5,-6,7,-8@};
-v4si b = __builtin_shufflevector (a, a, 0, 2, 4, 6); /* b is @{1,3,5,7@} */
-v4si c = @{-2,-4,-6,-8@};
-v8si d = __builtin_shufflevector (c, b, 4, 0, 5, 1, 6, 2, 7, 3); /* d is a */
-@end smallexample
-
-@findex __builtin_convertvector
-Vector conversion is available using the
-@code{__builtin_convertvector (vec, vectype)}
-function. @var{vec} must be an expression with integral or floating
-vector type and @var{vectype} an integral or floating vector type with the
-same number of elements. The result has @var{vectype} type and value of
-a C cast of every element of @var{vec} to the element type of @var{vectype}.
-
-Consider the following example,
-@smallexample
-typedef int v4si __attribute__ ((vector_size (16)));
-typedef float v4sf __attribute__ ((vector_size (16)));
-typedef double v4df __attribute__ ((vector_size (32)));
-typedef unsigned long long v4di __attribute__ ((vector_size (32)));
-
-v4si a = @{1,-2,3,-4@};
-v4sf b = @{1.5f,-2.5f,3.f,7.f@};
-v4di c = @{1ULL,5ULL,0ULL,10ULL@};
-v4sf d = __builtin_convertvector (a, v4sf); /* d is @{1.f,-2.f,3.f,-4.f@} */
-/* Equivalent of:
- v4sf d = @{ (float)a[0], (float)a[1], (float)a[2], (float)a[3] @}; */
-v4df e = __builtin_convertvector (a, v4df); /* e is @{1.,-2.,3.,-4.@} */
-v4df f = __builtin_convertvector (b, v4df); /* f is @{1.5,-2.5,3.,7.@} */
-v4si g = __builtin_convertvector (f, v4si); /* g is @{1,-2,3,7@} */
-v4si h = __builtin_convertvector (c, v4si); /* h is @{1,5,0,10@} */
-@end smallexample
-
-@cindex vector types, using with x86 intrinsics
-Sometimes it is desirable to write code using a mix of generic vector
-operations (for clarity) and machine-specific vector intrinsics (to
-access vector instructions that are not exposed via generic built-ins).
-On x86, intrinsic functions for integer vectors typically use the same
-vector type @code{__m128i} irrespective of how they interpret the vector,
-making it necessary to cast their arguments and return values from/to
-other vector types. In C, you can make use of a @code{union} type:
-@c In C++ such type punning via a union is not allowed by the language
-@smallexample
-#include <immintrin.h>
-
-typedef unsigned char u8x16 __attribute__ ((vector_size (16)));
-typedef unsigned int u32x4 __attribute__ ((vector_size (16)));
-
-typedef union @{
- __m128i mm;
- u8x16 u8;
- u32x4 u32;
-@} v128;
-@end smallexample
-
-@noindent
-for variables that can be used with both built-in operators and x86
-intrinsics:
-
-@smallexample
-v128 x, y = @{ 0 @};
-memcpy (&x, ptr, sizeof x);
-y.u8 += 0x80;
-x.mm = _mm_adds_epu8 (x.mm, y.mm);
-x.u32 &= 0xffffff;
-
-/* Instead of a variable, a compound literal may be used to pass the
- return value of an intrinsic call to a function expecting the union: */
-v128 foo (v128);
-x = foo ((v128) @{_mm_adds_epu8 (x.mm, y.mm)@});
-@c This could be done implicitly with __attribute__((transparent_union)),
-@c but GCC does not accept it for unions of vector types (PR 88955).
-@end smallexample
-
-@node Offsetof
-@section Support for @code{offsetof}
-@findex __builtin_offsetof
-
-GCC implements for both C and C++ a syntactic extension to implement
-the @code{offsetof} macro.
-
-@smallexample
-primary:
- "__builtin_offsetof" "(" @code{typename} "," offsetof_member_designator ")"
-
-offsetof_member_designator:
- @code{identifier}
- | offsetof_member_designator "." @code{identifier}
- | offsetof_member_designator "[" @code{expr} "]"
-@end smallexample
-
-This extension is sufficient such that
-
-@smallexample
-#define offsetof(@var{type}, @var{member}) __builtin_offsetof (@var{type}, @var{member})
-@end smallexample
-
-@noindent
-is a suitable definition of the @code{offsetof} macro. In C++, @var{type}
-may be dependent. In either case, @var{member} may consist of a single
-identifier, or a sequence of member accesses and array references.
-
-@node __sync Builtins
-@section Legacy @code{__sync} Built-in Functions for Atomic Memory Access
-
-The following built-in functions
-are intended to be compatible with those described
-in the @cite{Intel Itanium Processor-specific Application Binary Interface},
-section 7.4. As such, they depart from normal GCC practice by not using
-the @samp{__builtin_} prefix and also by being overloaded so that they
-work on multiple types.
-
-The definition given in the Intel documentation allows only for the use of
-the types @code{int}, @code{long}, @code{long long} or their unsigned
-counterparts. GCC allows any scalar type that is 1, 2, 4 or 8 bytes in
-size other than the C type @code{_Bool} or the C++ type @code{bool}.
-Operations on pointer arguments are performed as if the operands were
-of the @code{uintptr_t} type. That is, they are not scaled by the size
-of the type to which the pointer points.
-
-These functions are implemented in terms of the @samp{__atomic}
-builtins (@pxref{__atomic Builtins}). They should not be used for new
-code which should use the @samp{__atomic} builtins instead.
-
-Not all operations are supported by all target processors. If a particular
-operation cannot be implemented on the target processor, a warning is
-generated and a call to an external function is generated. The external
-function carries the same name as the built-in version,
-with an additional suffix
-@samp{_@var{n}} where @var{n} is the size of the data type.
-
-@c ??? Should we have a mechanism to suppress this warning? This is almost
-@c useful for implementing the operation under the control of an external
-@c mutex.
-
-In most cases, these built-in functions are considered a @dfn{full barrier}.
-That is,
-no memory operand is moved across the operation, either forward or
-backward. Further, instructions are issued as necessary to prevent the
-processor from speculating loads across the operation and from queuing stores
-after the operation.
-
-All of the routines are described in the Intel documentation to take
-``an optional list of variables protected by the memory barrier''. It's
-not clear what is meant by that; it could mean that @emph{only} the
-listed variables are protected, or it could mean a list of additional
-variables to be protected. The list is ignored by GCC which treats it as
-empty. GCC interprets an empty list as meaning that all globally
-accessible variables should be protected.
-
-@table @code
-@item @var{type} __sync_fetch_and_add (@var{type} *ptr, @var{type} value, ...)
-@itemx @var{type} __sync_fetch_and_sub (@var{type} *ptr, @var{type} value, ...)
-@itemx @var{type} __sync_fetch_and_or (@var{type} *ptr, @var{type} value, ...)
-@itemx @var{type} __sync_fetch_and_and (@var{type} *ptr, @var{type} value, ...)
-@itemx @var{type} __sync_fetch_and_xor (@var{type} *ptr, @var{type} value, ...)
-@itemx @var{type} __sync_fetch_and_nand (@var{type} *ptr, @var{type} value, ...)
-@findex __sync_fetch_and_add
-@findex __sync_fetch_and_sub
-@findex __sync_fetch_and_or
-@findex __sync_fetch_and_and
-@findex __sync_fetch_and_xor
-@findex __sync_fetch_and_nand
-These built-in functions perform the operation suggested by the name, and
-returns the value that had previously been in memory. That is, operations
-on integer operands have the following semantics. Operations on pointer
-arguments are performed as if the operands were of the @code{uintptr_t}
-type. That is, they are not scaled by the size of the type to which
-the pointer points.
-
-@smallexample
-@{ tmp = *ptr; *ptr @var{op}= value; return tmp; @}
-@{ tmp = *ptr; *ptr = ~(tmp & value); return tmp; @} // nand
-@end smallexample
-
-The object pointed to by the first argument must be of integer or pointer
-type. It must not be a boolean type.
-
-@emph{Note:} GCC 4.4 and later implement @code{__sync_fetch_and_nand}
-as @code{*ptr = ~(tmp & value)} instead of @code{*ptr = ~tmp & value}.
-
-@item @var{type} __sync_add_and_fetch (@var{type} *ptr, @var{type} value, ...)
-@itemx @var{type} __sync_sub_and_fetch (@var{type} *ptr, @var{type} value, ...)
-@itemx @var{type} __sync_or_and_fetch (@var{type} *ptr, @var{type} value, ...)
-@itemx @var{type} __sync_and_and_fetch (@var{type} *ptr, @var{type} value, ...)
-@itemx @var{type} __sync_xor_and_fetch (@var{type} *ptr, @var{type} value, ...)
-@itemx @var{type} __sync_nand_and_fetch (@var{type} *ptr, @var{type} value, ...)
-@findex __sync_add_and_fetch
-@findex __sync_sub_and_fetch
-@findex __sync_or_and_fetch
-@findex __sync_and_and_fetch
-@findex __sync_xor_and_fetch
-@findex __sync_nand_and_fetch
-These built-in functions perform the operation suggested by the name, and
-return the new value. That is, operations on integer operands have
-the following semantics. Operations on pointer operands are performed as
-if the operand's type were @code{uintptr_t}.
-
-@smallexample
-@{ *ptr @var{op}= value; return *ptr; @}
-@{ *ptr = ~(*ptr & value); return *ptr; @} // nand
-@end smallexample
-
-The same constraints on arguments apply as for the corresponding
-@code{__sync_op_and_fetch} built-in functions.
-
-@emph{Note:} GCC 4.4 and later implement @code{__sync_nand_and_fetch}
-as @code{*ptr = ~(*ptr & value)} instead of
-@code{*ptr = ~*ptr & value}.
-
-@item bool __sync_bool_compare_and_swap (@var{type} *ptr, @var{type} oldval, @var{type} newval, ...)
-@itemx @var{type} __sync_val_compare_and_swap (@var{type} *ptr, @var{type} oldval, @var{type} newval, ...)
-@findex __sync_bool_compare_and_swap
-@findex __sync_val_compare_and_swap
-These built-in functions perform an atomic compare and swap.
-That is, if the current
-value of @code{*@var{ptr}} is @var{oldval}, then write @var{newval} into
-@code{*@var{ptr}}.
-
-The ``bool'' version returns @code{true} if the comparison is successful and
-@var{newval} is written. The ``val'' version returns the contents
-of @code{*@var{ptr}} before the operation.
-
-@item __sync_synchronize (...)
-@findex __sync_synchronize
-This built-in function issues a full memory barrier.
-
-@item @var{type} __sync_lock_test_and_set (@var{type} *ptr, @var{type} value, ...)
-@findex __sync_lock_test_and_set
-This built-in function, as described by Intel, is not a traditional test-and-set
-operation, but rather an atomic exchange operation. It writes @var{value}
-into @code{*@var{ptr}}, and returns the previous contents of
-@code{*@var{ptr}}.
-
-Many targets have only minimal support for such locks, and do not support
-a full exchange operation. In this case, a target may support reduced
-functionality here by which the @emph{only} valid value to store is the
-immediate constant 1. The exact value actually stored in @code{*@var{ptr}}
-is implementation defined.
-
-This built-in function is not a full barrier,
-but rather an @dfn{acquire barrier}.
-This means that references after the operation cannot move to (or be
-speculated to) before the operation, but previous memory stores may not
-be globally visible yet, and previous memory loads may not yet be
-satisfied.
-
-@item void __sync_lock_release (@var{type} *ptr, ...)
-@findex __sync_lock_release
-This built-in function releases the lock acquired by
-@code{__sync_lock_test_and_set}.
-Normally this means writing the constant 0 to @code{*@var{ptr}}.
-
-This built-in function is not a full barrier,
-but rather a @dfn{release barrier}.
-This means that all previous memory stores are globally visible, and all
-previous memory loads have been satisfied, but following memory reads
-are not prevented from being speculated to before the barrier.
-@end table
-
-@node __atomic Builtins
-@section Built-in Functions for Memory Model Aware Atomic Operations
-
-The following built-in functions approximately match the requirements
-for the C++11 memory model. They are all
-identified by being prefixed with @samp{__atomic} and most are
-overloaded so that they work with multiple types.
-
-These functions are intended to replace the legacy @samp{__sync}
-builtins. The main difference is that the memory order that is requested
-is a parameter to the functions. New code should always use the
-@samp{__atomic} builtins rather than the @samp{__sync} builtins.
-
-Note that the @samp{__atomic} builtins assume that programs will
-conform to the C++11 memory model. In particular, they assume
-that programs are free of data races. See the C++11 standard for
-detailed requirements.
-
-The @samp{__atomic} builtins can be used with any integral scalar or
-pointer type that is 1, 2, 4, or 8 bytes in length. 16-byte integral
-types are also allowed if @samp{__int128} (@pxref{__int128}) is
-supported by the architecture.
-
-The four non-arithmetic functions (load, store, exchange, and
-compare_exchange) all have a generic version as well. This generic
-version works on any data type. It uses the lock-free built-in function
-if the specific data type size makes that possible; otherwise, an
-external call is left to be resolved at run time. This external call is
-the same format with the addition of a @samp{size_t} parameter inserted
-as the first parameter indicating the size of the object being pointed to.
-All objects must be the same size.
-
-There are 6 different memory orders that can be specified. These map
-to the C++11 memory orders with the same names, see the C++11 standard
-or the @uref{https://gcc.gnu.org/wiki/Atomic/GCCMM/AtomicSync,GCC wiki
-on atomic synchronization} for detailed definitions. Individual
-targets may also support additional memory orders for use on specific
-architectures. Refer to the target documentation for details of
-these.
-
-An atomic operation can both constrain code motion and
-be mapped to hardware instructions for synchronization between threads
-(e.g., a fence). To which extent this happens is controlled by the
-memory orders, which are listed here in approximately ascending order of
-strength. The description of each memory order is only meant to roughly
-illustrate the effects and is not a specification; see the C++11
-memory model for precise semantics.
-
-@table @code
-@item __ATOMIC_RELAXED
-Implies no inter-thread ordering constraints.
-@item __ATOMIC_CONSUME
-This is currently implemented using the stronger @code{__ATOMIC_ACQUIRE}
-memory order because of a deficiency in C++11's semantics for
-@code{memory_order_consume}.
-@item __ATOMIC_ACQUIRE
-Creates an inter-thread happens-before constraint from the release (or
-stronger) semantic store to this acquire load. Can prevent hoisting
-of code to before the operation.
-@item __ATOMIC_RELEASE
-Creates an inter-thread happens-before constraint to acquire (or stronger)
-semantic loads that read from this release store. Can prevent sinking
-of code to after the operation.
-@item __ATOMIC_ACQ_REL
-Combines the effects of both @code{__ATOMIC_ACQUIRE} and
-@code{__ATOMIC_RELEASE}.
-@item __ATOMIC_SEQ_CST
-Enforces total ordering with all other @code{__ATOMIC_SEQ_CST} operations.
-@end table
-
-Note that in the C++11 memory model, @emph{fences} (e.g.,
-@samp{__atomic_thread_fence}) take effect in combination with other
-atomic operations on specific memory locations (e.g., atomic loads);
-operations on specific memory locations do not necessarily affect other
-operations in the same way.
-
-Target architectures are encouraged to provide their own patterns for
-each of the atomic built-in functions. If no target is provided, the original
-non-memory model set of @samp{__sync} atomic built-in functions are
-used, along with any required synchronization fences surrounding it in
-order to achieve the proper behavior. Execution in this case is subject
-to the same restrictions as those built-in functions.
-
-If there is no pattern or mechanism to provide a lock-free instruction
-sequence, a call is made to an external routine with the same parameters
-to be resolved at run time.
-
-When implementing patterns for these built-in functions, the memory order
-parameter can be ignored as long as the pattern implements the most
-restrictive @code{__ATOMIC_SEQ_CST} memory order. Any of the other memory
-orders execute correctly with this memory order but they may not execute as
-efficiently as they could with a more appropriate implementation of the
-relaxed requirements.
-
-Note that the C++11 standard allows for the memory order parameter to be
-determined at run time rather than at compile time. These built-in
-functions map any run-time value to @code{__ATOMIC_SEQ_CST} rather
-than invoke a runtime library call or inline a switch statement. This is
-standard compliant, safe, and the simplest approach for now.
-
-The memory order parameter is a signed int, but only the lower 16 bits are
-reserved for the memory order. The remainder of the signed int is reserved
-for target use and should be 0. Use of the predefined atomic values
-ensures proper usage.
-
-@deftypefn {Built-in Function} @var{type} __atomic_load_n (@var{type} *ptr, int memorder)
-This built-in function implements an atomic load operation. It returns the
-contents of @code{*@var{ptr}}.
-
-The valid memory order variants are
-@code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, @code{__ATOMIC_ACQUIRE},
-and @code{__ATOMIC_CONSUME}.
-
-@end deftypefn
-
-@deftypefn {Built-in Function} void __atomic_load (@var{type} *ptr, @var{type} *ret, int memorder)
-This is the generic version of an atomic load. It returns the
-contents of @code{*@var{ptr}} in @code{*@var{ret}}.
-
-@end deftypefn
-
-@deftypefn {Built-in Function} void __atomic_store_n (@var{type} *ptr, @var{type} val, int memorder)
-This built-in function implements an atomic store operation. It writes
-@code{@var{val}} into @code{*@var{ptr}}.
-
-The valid memory order variants are
-@code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, and @code{__ATOMIC_RELEASE}.
-
-@end deftypefn
-
-@deftypefn {Built-in Function} void __atomic_store (@var{type} *ptr, @var{type} *val, int memorder)
-This is the generic version of an atomic store. It stores the value
-of @code{*@var{val}} into @code{*@var{ptr}}.
-
-@end deftypefn
-
-@deftypefn {Built-in Function} @var{type} __atomic_exchange_n (@var{type} *ptr, @var{type} val, int memorder)
-This built-in function implements an atomic exchange operation. It writes
-@var{val} into @code{*@var{ptr}}, and returns the previous contents of
-@code{*@var{ptr}}.
-
-All memory order variants are valid.
-
-@end deftypefn
-
-@deftypefn {Built-in Function} void __atomic_exchange (@var{type} *ptr, @var{type} *val, @var{type} *ret, int memorder)
-This is the generic version of an atomic exchange. It stores the
-contents of @code{*@var{val}} into @code{*@var{ptr}}. The original value
-of @code{*@var{ptr}} is copied into @code{*@var{ret}}.
-
-@end deftypefn
-
-@deftypefn {Built-in Function} bool __atomic_compare_exchange_n (@var{type} *ptr, @var{type} *expected, @var{type} desired, bool weak, int success_memorder, int failure_memorder)
-This built-in function implements an atomic compare and exchange operation.
-This compares the contents of @code{*@var{ptr}} with the contents of
-@code{*@var{expected}}. If equal, the operation is a @emph{read-modify-write}
-operation that writes @var{desired} into @code{*@var{ptr}}. If they are not
-equal, the operation is a @emph{read} and the current contents of
-@code{*@var{ptr}} are written into @code{*@var{expected}}. @var{weak} is @code{true}
-for weak compare_exchange, which may fail spuriously, and @code{false} for
-the strong variation, which never fails spuriously. Many targets
-only offer the strong variation and ignore the parameter. When in doubt, use
-the strong variation.
-
-If @var{desired} is written into @code{*@var{ptr}} then @code{true} is returned
-and memory is affected according to the
-memory order specified by @var{success_memorder}. There are no
-restrictions on what memory order can be used here.
-
-Otherwise, @code{false} is returned and memory is affected according
-to @var{failure_memorder}. This memory order cannot be
-@code{__ATOMIC_RELEASE} nor @code{__ATOMIC_ACQ_REL}. It also cannot be a
-stronger order than that specified by @var{success_memorder}.
-
-@end deftypefn
-
-@deftypefn {Built-in Function} bool __atomic_compare_exchange (@var{type} *ptr, @var{type} *expected, @var{type} *desired, bool weak, int success_memorder, int failure_memorder)
-This built-in function implements the generic version of
-@code{__atomic_compare_exchange}. The function is virtually identical to
-@code{__atomic_compare_exchange_n}, except the desired value is also a
-pointer.
-
-@end deftypefn
-
-@deftypefn {Built-in Function} @var{type} __atomic_add_fetch (@var{type} *ptr, @var{type} val, int memorder)
-@deftypefnx {Built-in Function} @var{type} __atomic_sub_fetch (@var{type} *ptr, @var{type} val, int memorder)
-@deftypefnx {Built-in Function} @var{type} __atomic_and_fetch (@var{type} *ptr, @var{type} val, int memorder)
-@deftypefnx {Built-in Function} @var{type} __atomic_xor_fetch (@var{type} *ptr, @var{type} val, int memorder)
-@deftypefnx {Built-in Function} @var{type} __atomic_or_fetch (@var{type} *ptr, @var{type} val, int memorder)
-@deftypefnx {Built-in Function} @var{type} __atomic_nand_fetch (@var{type} *ptr, @var{type} val, int memorder)
-These built-in functions perform the operation suggested by the name, and
-return the result of the operation. Operations on pointer arguments are
-performed as if the operands were of the @code{uintptr_t} type. That is,
-they are not scaled by the size of the type to which the pointer points.
-
-@smallexample
-@{ *ptr @var{op}= val; return *ptr; @}
-@{ *ptr = ~(*ptr & val); return *ptr; @} // nand
-@end smallexample
-
-The object pointed to by the first argument must be of integer or pointer
-type. It must not be a boolean type. All memory orders are valid.
-
-@end deftypefn
-
-@deftypefn {Built-in Function} @var{type} __atomic_fetch_add (@var{type} *ptr, @var{type} val, int memorder)
-@deftypefnx {Built-in Function} @var{type} __atomic_fetch_sub (@var{type} *ptr, @var{type} val, int memorder)
-@deftypefnx {Built-in Function} @var{type} __atomic_fetch_and (@var{type} *ptr, @var{type} val, int memorder)
-@deftypefnx {Built-in Function} @var{type} __atomic_fetch_xor (@var{type} *ptr, @var{type} val, int memorder)
-@deftypefnx {Built-in Function} @var{type} __atomic_fetch_or (@var{type} *ptr, @var{type} val, int memorder)
-@deftypefnx {Built-in Function} @var{type} __atomic_fetch_nand (@var{type} *ptr, @var{type} val, int memorder)
-These built-in functions perform the operation suggested by the name, and
-return the value that had previously been in @code{*@var{ptr}}. Operations
-on pointer arguments are performed as if the operands were of
-the @code{uintptr_t} type. That is, they are not scaled by the size of
-the type to which the pointer points.
-
-@smallexample
-@{ tmp = *ptr; *ptr @var{op}= val; return tmp; @}
-@{ tmp = *ptr; *ptr = ~(*ptr & val); return tmp; @} // nand
-@end smallexample
-
-The same constraints on arguments apply as for the corresponding
-@code{__atomic_op_fetch} built-in functions. All memory orders are valid.
-
-@end deftypefn
-
-@deftypefn {Built-in Function} bool __atomic_test_and_set (void *ptr, int memorder)
-
-This built-in function performs an atomic test-and-set operation on
-the byte at @code{*@var{ptr}}. The byte is set to some implementation
-defined nonzero ``set'' value and the return value is @code{true} if and only
-if the previous contents were ``set''.
-It should be only used for operands of type @code{bool} or @code{char}. For
-other types only part of the value may be set.
-
-All memory orders are valid.
-
-@end deftypefn
-
-@deftypefn {Built-in Function} void __atomic_clear (bool *ptr, int memorder)
-
-This built-in function performs an atomic clear operation on
-@code{*@var{ptr}}. After the operation, @code{*@var{ptr}} contains 0.
-It should be only used for operands of type @code{bool} or @code{char} and
-in conjunction with @code{__atomic_test_and_set}.
-For other types it may only clear partially. If the type is not @code{bool}
-prefer using @code{__atomic_store}.
-
-The valid memory order variants are
-@code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, and
-@code{__ATOMIC_RELEASE}.
-
-@end deftypefn
-
-@deftypefn {Built-in Function} void __atomic_thread_fence (int memorder)
-
-This built-in function acts as a synchronization fence between threads
-based on the specified memory order.
-
-All memory orders are valid.
-
-@end deftypefn
-
-@deftypefn {Built-in Function} void __atomic_signal_fence (int memorder)
-
-This built-in function acts as a synchronization fence between a thread
-and signal handlers based in the same thread.
-
-All memory orders are valid.
-
-@end deftypefn
-
-@deftypefn {Built-in Function} bool __atomic_always_lock_free (size_t size, void *ptr)
-
-This built-in function returns @code{true} if objects of @var{size} bytes always
-generate lock-free atomic instructions for the target architecture.
-@var{size} must resolve to a compile-time constant and the result also
-resolves to a compile-time constant.
-
-@var{ptr} is an optional pointer to the object that may be used to determine
-alignment. A value of 0 indicates typical alignment should be used. The
-compiler may also ignore this parameter.
-
-@smallexample
-if (__atomic_always_lock_free (sizeof (long long), 0))
-@end smallexample
-
-@end deftypefn
-
-@deftypefn {Built-in Function} bool __atomic_is_lock_free (size_t size, void *ptr)
-
-This built-in function returns @code{true} if objects of @var{size} bytes always
-generate lock-free atomic instructions for the target architecture. If
-the built-in function is not known to be lock-free, a call is made to a
-runtime routine named @code{__atomic_is_lock_free}.
-
-@var{ptr} is an optional pointer to the object that may be used to determine
-alignment. A value of 0 indicates typical alignment should be used. The
-compiler may also ignore this parameter.
-@end deftypefn
-
-@node Integer Overflow Builtins
-@section Built-in Functions to Perform Arithmetic with Overflow Checking
-
-The following built-in functions allow performing simple arithmetic operations
-together with checking whether the operations overflowed.
-
-@deftypefn {Built-in Function} bool __builtin_add_overflow (@var{type1} a, @var{type2} b, @var{type3} *res)
-@deftypefnx {Built-in Function} bool __builtin_sadd_overflow (int a, int b, int *res)
-@deftypefnx {Built-in Function} bool __builtin_saddl_overflow (long int a, long int b, long int *res)
-@deftypefnx {Built-in Function} bool __builtin_saddll_overflow (long long int a, long long int b, long long int *res)
-@deftypefnx {Built-in Function} bool __builtin_uadd_overflow (unsigned int a, unsigned int b, unsigned int *res)
-@deftypefnx {Built-in Function} bool __builtin_uaddl_overflow (unsigned long int a, unsigned long int b, unsigned long int *res)
-@deftypefnx {Built-in Function} bool __builtin_uaddll_overflow (unsigned long long int a, unsigned long long int b, unsigned long long int *res)
-
-These built-in functions promote the first two operands into infinite precision signed
-type and perform addition on those promoted operands. The result is then
-cast to the type the third pointer argument points to and stored there.
-If the stored result is equal to the infinite precision result, the built-in
-functions return @code{false}, otherwise they return @code{true}. As the addition is
-performed in infinite signed precision, these built-in functions have fully defined
-behavior for all argument values.
-
-The first built-in function allows arbitrary integral types for operands and
-the result type must be pointer to some integral type other than enumerated or
-boolean type, the rest of the built-in functions have explicit integer types.
-
-The compiler will attempt to use hardware instructions to implement
-these built-in functions where possible, like conditional jump on overflow
-after addition, conditional jump on carry etc.
-
-@end deftypefn
-
-@deftypefn {Built-in Function} bool __builtin_sub_overflow (@var{type1} a, @var{type2} b, @var{type3} *res)
-@deftypefnx {Built-in Function} bool __builtin_ssub_overflow (int a, int b, int *res)
-@deftypefnx {Built-in Function} bool __builtin_ssubl_overflow (long int a, long int b, long int *res)
-@deftypefnx {Built-in Function} bool __builtin_ssubll_overflow (long long int a, long long int b, long long int *res)
-@deftypefnx {Built-in Function} bool __builtin_usub_overflow (unsigned int a, unsigned int b, unsigned int *res)
-@deftypefnx {Built-in Function} bool __builtin_usubl_overflow (unsigned long int a, unsigned long int b, unsigned long int *res)
-@deftypefnx {Built-in Function} bool __builtin_usubll_overflow (unsigned long long int a, unsigned long long int b, unsigned long long int *res)
-
-These built-in functions are similar to the add overflow checking built-in
-functions above, except they perform subtraction, subtract the second argument
-from the first one, instead of addition.
-
-@end deftypefn
-
-@deftypefn {Built-in Function} bool __builtin_mul_overflow (@var{type1} a, @var{type2} b, @var{type3} *res)
-@deftypefnx {Built-in Function} bool __builtin_smul_overflow (int a, int b, int *res)
-@deftypefnx {Built-in Function} bool __builtin_smull_overflow (long int a, long int b, long int *res)
-@deftypefnx {Built-in Function} bool __builtin_smulll_overflow (long long int a, long long int b, long long int *res)
-@deftypefnx {Built-in Function} bool __builtin_umul_overflow (unsigned int a, unsigned int b, unsigned int *res)
-@deftypefnx {Built-in Function} bool __builtin_umull_overflow (unsigned long int a, unsigned long int b, unsigned long int *res)
-@deftypefnx {Built-in Function} bool __builtin_umulll_overflow (unsigned long long int a, unsigned long long int b, unsigned long long int *res)
-
-These built-in functions are similar to the add overflow checking built-in
-functions above, except they perform multiplication, instead of addition.
-
-@end deftypefn
-
-The following built-in functions allow checking if simple arithmetic operation
-would overflow.
-
-@deftypefn {Built-in Function} bool __builtin_add_overflow_p (@var{type1} a, @var{type2} b, @var{type3} c)
-@deftypefnx {Built-in Function} bool __builtin_sub_overflow_p (@var{type1} a, @var{type2} b, @var{type3} c)
-@deftypefnx {Built-in Function} bool __builtin_mul_overflow_p (@var{type1} a, @var{type2} b, @var{type3} c)
-
-These built-in functions are similar to @code{__builtin_add_overflow},
-@code{__builtin_sub_overflow}, or @code{__builtin_mul_overflow}, except that
-they don't store the result of the arithmetic operation anywhere and the
-last argument is not a pointer, but some expression with integral type other
-than enumerated or boolean type.
-
-The built-in functions promote the first two operands into infinite precision signed type
-and perform addition on those promoted operands. The result is then
-cast to the type of the third argument. If the cast result is equal to the infinite
-precision result, the built-in functions return @code{false}, otherwise they return @code{true}.
-The value of the third argument is ignored, just the side effects in the third argument
-are evaluated, and no integral argument promotions are performed on the last argument.
-If the third argument is a bit-field, the type used for the result cast has the
-precision and signedness of the given bit-field, rather than precision and signedness
-of the underlying type.
-
-For example, the following macro can be used to portably check, at
-compile-time, whether or not adding two constant integers will overflow,
-and perform the addition only when it is known to be safe and not to trigger
-a @option{-Woverflow} warning.
-
-@smallexample
-#define INT_ADD_OVERFLOW_P(a, b) \
- __builtin_add_overflow_p (a, b, (__typeof__ ((a) + (b))) 0)
-
-enum @{
- A = INT_MAX, B = 3,
- C = INT_ADD_OVERFLOW_P (A, B) ? 0 : A + B,
- D = __builtin_add_overflow_p (1, SCHAR_MAX, (signed char) 0)
-@};
-@end smallexample
-
-The compiler will attempt to use hardware instructions to implement
-these built-in functions where possible, like conditional jump on overflow
-after addition, conditional jump on carry etc.
-
-@end deftypefn
-
-@node x86 specific memory model extensions for transactional memory
-@section x86-Specific Memory Model Extensions for Transactional Memory
-
-The x86 architecture supports additional memory ordering flags
-to mark critical sections for hardware lock elision.
-These must be specified in addition to an existing memory order to
-atomic intrinsics.
-
-@table @code
-@item __ATOMIC_HLE_ACQUIRE
-Start lock elision on a lock variable.
-Memory order must be @code{__ATOMIC_ACQUIRE} or stronger.
-@item __ATOMIC_HLE_RELEASE
-End lock elision on a lock variable.
-Memory order must be @code{__ATOMIC_RELEASE} or stronger.
-@end table
-
-When a lock acquire fails, it is required for good performance to abort
-the transaction quickly. This can be done with a @code{_mm_pause}.
-
-@smallexample
-#include <immintrin.h> // For _mm_pause
-
-int lockvar;
-
-/* Acquire lock with lock elision */
-while (__atomic_exchange_n(&lockvar, 1, __ATOMIC_ACQUIRE|__ATOMIC_HLE_ACQUIRE))
- _mm_pause(); /* Abort failed transaction */
-...
-/* Free lock with lock elision */
-__atomic_store_n(&lockvar, 0, __ATOMIC_RELEASE|__ATOMIC_HLE_RELEASE);
-@end smallexample
-
-@node Object Size Checking
-@section Object Size Checking Built-in Functions
-@findex __builtin_object_size
-@findex __builtin_dynamic_object_size
-@findex __builtin___memcpy_chk
-@findex __builtin___mempcpy_chk
-@findex __builtin___memmove_chk
-@findex __builtin___memset_chk
-@findex __builtin___strcpy_chk
-@findex __builtin___stpcpy_chk
-@findex __builtin___strncpy_chk
-@findex __builtin___strcat_chk
-@findex __builtin___strncat_chk
-@findex __builtin___sprintf_chk
-@findex __builtin___snprintf_chk
-@findex __builtin___vsprintf_chk
-@findex __builtin___vsnprintf_chk
-@findex __builtin___printf_chk
-@findex __builtin___vprintf_chk
-@findex __builtin___fprintf_chk
-@findex __builtin___vfprintf_chk
-
-GCC implements a limited buffer overflow protection mechanism that can
-prevent some buffer overflow attacks by determining the sizes of objects
-into which data is about to be written and preventing the writes when
-the size isn't sufficient. The built-in functions described below yield
-the best results when used together and when optimization is enabled.
-For example, to detect object sizes across function boundaries or to
-follow pointer assignments through non-trivial control flow they rely
-on various optimization passes enabled with @option{-O2}. However, to
-a limited extent, they can be used without optimization as well.
-
-@deftypefn {Built-in Function} {size_t} __builtin_object_size (const void * @var{ptr}, int @var{type})
-is a built-in construct that returns a constant number of bytes from
-@var{ptr} to the end of the object @var{ptr} pointer points to
-(if known at compile time). To determine the sizes of dynamically allocated
-objects the function relies on the allocation functions called to obtain
-the storage to be declared with the @code{alloc_size} attribute (@pxref{Common
-Function Attributes}). @code{__builtin_object_size} never evaluates
-its arguments for side effects. If there are any side effects in them, it
-returns @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0}
-for @var{type} 2 or 3. If there are multiple objects @var{ptr} can
-point to and all of them are known at compile time, the returned number
-is the maximum of remaining byte counts in those objects if @var{type} & 2 is
-0 and minimum if nonzero. If it is not possible to determine which objects
-@var{ptr} points to at compile time, @code{__builtin_object_size} should
-return @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0}
-for @var{type} 2 or 3.
-
-@var{type} is an integer constant from 0 to 3. If the least significant
-bit is clear, objects are whole variables, if it is set, a closest
-surrounding subobject is considered the object a pointer points to.
-The second bit determines if maximum or minimum of remaining bytes
-is computed.
-
-@smallexample
-struct V @{ char buf1[10]; int b; char buf2[10]; @} var;
-char *p = &var.buf1[1], *q = &var.b;
-
-/* Here the object p points to is var. */
-assert (__builtin_object_size (p, 0) == sizeof (var) - 1);
-/* The subobject p points to is var.buf1. */
-assert (__builtin_object_size (p, 1) == sizeof (var.buf1) - 1);
-/* The object q points to is var. */
-assert (__builtin_object_size (q, 0)
- == (char *) (&var + 1) - (char *) &var.b);
-/* The subobject q points to is var.b. */
-assert (__builtin_object_size (q, 1) == sizeof (var.b));
-@end smallexample
-@end deftypefn
-
-@deftypefn {Built-in Function} {size_t} __builtin_dynamic_object_size (const void * @var{ptr}, int @var{type})
-is similar to @code{__builtin_object_size} in that it returns a number of bytes
-from @var{ptr} to the end of the object @var{ptr} pointer points to, except
-that the size returned may not be a constant. This results in successful
-evaluation of object size estimates in a wider range of use cases and can be
-more precise than @code{__builtin_object_size}, but it incurs a performance
-penalty since it may add a runtime overhead on size computation. Semantics of
-@var{type} as well as return values in case it is not possible to determine
-which objects @var{ptr} points to at compile time are the same as in the case
-of @code{__builtin_object_size}.
-@end deftypefn
-
-There are built-in functions added for many common string operation
-functions, e.g., for @code{memcpy} @code{__builtin___memcpy_chk}
-built-in is provided. This built-in has an additional last argument,
-which is the number of bytes remaining in the object the @var{dest}
-argument points to or @code{(size_t) -1} if the size is not known.
-
-The built-in functions are optimized into the normal string functions
-like @code{memcpy} if the last argument is @code{(size_t) -1} or if
-it is known at compile time that the destination object will not
-be overflowed. If the compiler can determine at compile time that the
-object will always be overflowed, it issues a warning.
-
-The intended use can be e.g.@:
-
-@smallexample
-#undef memcpy
-#define bos0(dest) __builtin_object_size (dest, 0)
-#define memcpy(dest, src, n) \
- __builtin___memcpy_chk (dest, src, n, bos0 (dest))
-
-char *volatile p;
-char buf[10];
-/* It is unknown what object p points to, so this is optimized
- into plain memcpy - no checking is possible. */
-memcpy (p, "abcde", n);
-/* Destination is known and length too. It is known at compile
- time there will be no overflow. */
-memcpy (&buf[5], "abcde", 5);
-/* Destination is known, but the length is not known at compile time.
- This will result in __memcpy_chk call that can check for overflow
- at run time. */
-memcpy (&buf[5], "abcde", n);
-/* Destination is known and it is known at compile time there will
- be overflow. There will be a warning and __memcpy_chk call that
- will abort the program at run time. */
-memcpy (&buf[6], "abcde", 5);
-@end smallexample
-
-Such built-in functions are provided for @code{memcpy}, @code{mempcpy},
-@code{memmove}, @code{memset}, @code{strcpy}, @code{stpcpy}, @code{strncpy},
-@code{strcat} and @code{strncat}.
-
-There are also checking built-in functions for formatted output functions.
-@smallexample
-int __builtin___sprintf_chk (char *s, int flag, size_t os, const char *fmt, ...);
-int __builtin___snprintf_chk (char *s, size_t maxlen, int flag, size_t os,
- const char *fmt, ...);
-int __builtin___vsprintf_chk (char *s, int flag, size_t os, const char *fmt,
- va_list ap);
-int __builtin___vsnprintf_chk (char *s, size_t maxlen, int flag, size_t os,
- const char *fmt, va_list ap);
-@end smallexample
-
-The added @var{flag} argument is passed unchanged to @code{__sprintf_chk}
-etc.@: functions and can contain implementation specific flags on what
-additional security measures the checking function might take, such as
-handling @code{%n} differently.
-
-The @var{os} argument is the object size @var{s} points to, like in the
-other built-in functions. There is a small difference in the behavior
-though, if @var{os} is @code{(size_t) -1}, the built-in functions are
-optimized into the non-checking functions only if @var{flag} is 0, otherwise
-the checking function is called with @var{os} argument set to
-@code{(size_t) -1}.
-
-In addition to this, there are checking built-in functions
-@code{__builtin___printf_chk}, @code{__builtin___vprintf_chk},
-@code{__builtin___fprintf_chk} and @code{__builtin___vfprintf_chk}.
-These have just one additional argument, @var{flag}, right before
-format string @var{fmt}. If the compiler is able to optimize them to
-@code{fputc} etc.@: functions, it does, otherwise the checking function
-is called and the @var{flag} argument passed to it.
-
-@node Other Builtins
-@section Other Built-in Functions Provided by GCC
-@cindex built-in functions
-@findex __builtin_alloca
-@findex __builtin_alloca_with_align
-@findex __builtin_alloca_with_align_and_max
-@findex __builtin_call_with_static_chain
-@findex __builtin_extend_pointer
-@findex __builtin_fpclassify
-@findex __builtin_has_attribute
-@findex __builtin_isfinite
-@findex __builtin_isnormal
-@findex __builtin_isgreater
-@findex __builtin_isgreaterequal
-@findex __builtin_isinf_sign
-@findex __builtin_isless
-@findex __builtin_islessequal
-@findex __builtin_islessgreater
-@findex __builtin_issignaling
-@findex __builtin_isunordered
-@findex __builtin_object_size
-@findex __builtin_powi
-@findex __builtin_powif
-@findex __builtin_powil
-@findex __builtin_speculation_safe_value
-@findex _Exit
-@findex _exit
-@findex abort
-@findex abs
-@findex acos
-@findex acosf
-@findex acosh
-@findex acoshf
-@findex acoshl
-@findex acosl
-@findex alloca
-@findex asin
-@findex asinf
-@findex asinh
-@findex asinhf
-@findex asinhl
-@findex asinl
-@findex atan
-@findex atan2
-@findex atan2f
-@findex atan2l
-@findex atanf
-@findex atanh
-@findex atanhf
-@findex atanhl
-@findex atanl
-@findex bcmp
-@findex bzero
-@findex cabs
-@findex cabsf
-@findex cabsl
-@findex cacos
-@findex cacosf
-@findex cacosh
-@findex cacoshf
-@findex cacoshl
-@findex cacosl
-@findex calloc
-@findex carg
-@findex cargf
-@findex cargl
-@findex casin
-@findex casinf
-@findex casinh
-@findex casinhf
-@findex casinhl
-@findex casinl
-@findex catan
-@findex catanf
-@findex catanh
-@findex catanhf
-@findex catanhl
-@findex catanl
-@findex cbrt
-@findex cbrtf
-@findex cbrtl
-@findex ccos
-@findex ccosf
-@findex ccosh
-@findex ccoshf
-@findex ccoshl
-@findex ccosl
-@findex ceil
-@findex ceilf
-@findex ceill
-@findex cexp
-@findex cexpf
-@findex cexpl
-@findex cimag
-@findex cimagf
-@findex cimagl
-@findex clog
-@findex clogf
-@findex clogl
-@findex clog10
-@findex clog10f
-@findex clog10l
-@findex conj
-@findex conjf
-@findex conjl
-@findex copysign
-@findex copysignf
-@findex copysignl
-@findex cos
-@findex cosf
-@findex cosh
-@findex coshf
-@findex coshl
-@findex cosl
-@findex cpow
-@findex cpowf
-@findex cpowl
-@findex cproj
-@findex cprojf
-@findex cprojl
-@findex creal
-@findex crealf
-@findex creall
-@findex csin
-@findex csinf
-@findex csinh
-@findex csinhf
-@findex csinhl
-@findex csinl
-@findex csqrt
-@findex csqrtf
-@findex csqrtl
-@findex ctan
-@findex ctanf
-@findex ctanh
-@findex ctanhf
-@findex ctanhl
-@findex ctanl
-@findex dcgettext
-@findex dgettext
-@findex drem
-@findex dremf
-@findex dreml
-@findex erf
-@findex erfc
-@findex erfcf
-@findex erfcl
-@findex erff
-@findex erfl
-@findex exit
-@findex exp
-@findex exp10
-@findex exp10f
-@findex exp10l
-@findex exp2
-@findex exp2f
-@findex exp2l
-@findex expf
-@findex expl
-@findex expm1
-@findex expm1f
-@findex expm1l
-@findex fabs
-@findex fabsf
-@findex fabsl
-@findex fdim
-@findex fdimf
-@findex fdiml
-@findex ffs
-@findex floor
-@findex floorf
-@findex floorl
-@findex fma
-@findex fmaf
-@findex fmal
-@findex fmax
-@findex fmaxf
-@findex fmaxl
-@findex fmin
-@findex fminf
-@findex fminl
-@findex fmod
-@findex fmodf
-@findex fmodl
-@findex fprintf
-@findex fprintf_unlocked
-@findex fputs
-@findex fputs_unlocked
-@findex free
-@findex frexp
-@findex frexpf
-@findex frexpl
-@findex fscanf
-@findex gamma
-@findex gammaf
-@findex gammal
-@findex gamma_r
-@findex gammaf_r
-@findex gammal_r
-@findex gettext
-@findex hypot
-@findex hypotf
-@findex hypotl
-@findex ilogb
-@findex ilogbf
-@findex ilogbl
-@findex imaxabs
-@findex index
-@findex isalnum
-@findex isalpha
-@findex isascii
-@findex isblank
-@findex iscntrl
-@findex isdigit
-@findex isgraph
-@findex islower
-@findex isprint
-@findex ispunct
-@findex isspace
-@findex isupper
-@findex iswalnum
-@findex iswalpha
-@findex iswblank
-@findex iswcntrl
-@findex iswdigit
-@findex iswgraph
-@findex iswlower
-@findex iswprint
-@findex iswpunct
-@findex iswspace
-@findex iswupper
-@findex iswxdigit
-@findex isxdigit
-@findex j0
-@findex j0f
-@findex j0l
-@findex j1
-@findex j1f
-@findex j1l
-@findex jn
-@findex jnf
-@findex jnl
-@findex labs
-@findex ldexp
-@findex ldexpf
-@findex ldexpl
-@findex lgamma
-@findex lgammaf
-@findex lgammal
-@findex lgamma_r
-@findex lgammaf_r
-@findex lgammal_r
-@findex llabs
-@findex llrint
-@findex llrintf
-@findex llrintl
-@findex llround
-@findex llroundf
-@findex llroundl
-@findex log
-@findex log10
-@findex log10f
-@findex log10l
-@findex log1p
-@findex log1pf
-@findex log1pl
-@findex log2
-@findex log2f
-@findex log2l
-@findex logb
-@findex logbf
-@findex logbl
-@findex logf
-@findex logl
-@findex lrint
-@findex lrintf
-@findex lrintl
-@findex lround
-@findex lroundf
-@findex lroundl
-@findex malloc
-@findex memchr
-@findex memcmp
-@findex memcpy
-@findex mempcpy
-@findex memset
-@findex modf
-@findex modff
-@findex modfl
-@findex nearbyint
-@findex nearbyintf
-@findex nearbyintl
-@findex nextafter
-@findex nextafterf
-@findex nextafterl
-@findex nexttoward
-@findex nexttowardf
-@findex nexttowardl
-@findex pow
-@findex pow10
-@findex pow10f
-@findex pow10l
-@findex powf
-@findex powl
-@findex printf
-@findex printf_unlocked
-@findex putchar
-@findex puts
-@findex realloc
-@findex remainder
-@findex remainderf
-@findex remainderl
-@findex remquo
-@findex remquof
-@findex remquol
-@findex rindex
-@findex rint
-@findex rintf
-@findex rintl
-@findex round
-@findex roundf
-@findex roundl
-@findex scalb
-@findex scalbf
-@findex scalbl
-@findex scalbln
-@findex scalblnf
-@findex scalblnf
-@findex scalbn
-@findex scalbnf
-@findex scanfnl
-@findex signbit
-@findex signbitf
-@findex signbitl
-@findex signbitd32
-@findex signbitd64
-@findex signbitd128
-@findex significand
-@findex significandf
-@findex significandl
-@findex sin
-@findex sincos
-@findex sincosf
-@findex sincosl
-@findex sinf
-@findex sinh
-@findex sinhf
-@findex sinhl
-@findex sinl
-@findex snprintf
-@findex sprintf
-@findex sqrt
-@findex sqrtf
-@findex sqrtl
-@findex sscanf
-@findex stpcpy
-@findex stpncpy
-@findex strcasecmp
-@findex strcat
-@findex strchr
-@findex strcmp
-@findex strcpy
-@findex strcspn
-@findex strdup
-@findex strfmon
-@findex strftime
-@findex strlen
-@findex strncasecmp
-@findex strncat
-@findex strncmp
-@findex strncpy
-@findex strndup
-@findex strnlen
-@findex strpbrk
-@findex strrchr
-@findex strspn
-@findex strstr
-@findex tan
-@findex tanf
-@findex tanh
-@findex tanhf
-@findex tanhl
-@findex tanl
-@findex tgamma
-@findex tgammaf
-@findex tgammal
-@findex toascii
-@findex tolower
-@findex toupper
-@findex towlower
-@findex towupper
-@findex trunc
-@findex truncf
-@findex truncl
-@findex vfprintf
-@findex vfscanf
-@findex vprintf
-@findex vscanf
-@findex vsnprintf
-@findex vsprintf
-@findex vsscanf
-@findex y0
-@findex y0f
-@findex y0l
-@findex y1
-@findex y1f
-@findex y1l
-@findex yn
-@findex ynf
-@findex ynl
-
-GCC provides a large number of built-in functions other than the ones
-mentioned above. Some of these are for internal use in the processing
-of exceptions or variable-length argument lists and are not
-documented here because they may change from time to time; we do not
-recommend general use of these functions.
-
-The remaining functions are provided for optimization purposes.
-
-With the exception of built-ins that have library equivalents such as
-the standard C library functions discussed below, or that expand to
-library calls, GCC built-in functions are always expanded inline and
-thus do not have corresponding entry points and their address cannot
-be obtained. Attempting to use them in an expression other than
-a function call results in a compile-time error.
-
-@opindex fno-builtin
-GCC includes built-in versions of many of the functions in the standard
-C library. These functions come in two forms: one whose names start with
-the @code{__builtin_} prefix, and the other without. Both forms have the
-same type (including prototype), the same address (when their address is
-taken), and the same meaning as the C library functions even if you specify
-the @option{-fno-builtin} option @pxref{C Dialect Options}). Many of these
-functions are only optimized in certain cases; if they are not optimized in
-a particular case, a call to the library function is emitted.
-
-@opindex ansi
-@opindex std
-Outside strict ISO C mode (@option{-ansi}, @option{-std=c90},
-@option{-std=c99} or @option{-std=c11}), the functions
-@code{_exit}, @code{alloca}, @code{bcmp}, @code{bzero},
-@code{dcgettext}, @code{dgettext}, @code{dremf}, @code{dreml},
-@code{drem}, @code{exp10f}, @code{exp10l}, @code{exp10}, @code{ffsll},
-@code{ffsl}, @code{ffs}, @code{fprintf_unlocked},
-@code{fputs_unlocked}, @code{gammaf}, @code{gammal}, @code{gamma},
-@code{gammaf_r}, @code{gammal_r}, @code{gamma_r}, @code{gettext},
-@code{index}, @code{isascii}, @code{j0f}, @code{j0l}, @code{j0},
-@code{j1f}, @code{j1l}, @code{j1}, @code{jnf}, @code{jnl}, @code{jn},
-@code{lgammaf_r}, @code{lgammal_r}, @code{lgamma_r}, @code{mempcpy},
-@code{pow10f}, @code{pow10l}, @code{pow10}, @code{printf_unlocked},
-@code{rindex}, @code{roundeven}, @code{roundevenf}, @code{roundevenl},
-@code{scalbf}, @code{scalbl}, @code{scalb},
-@code{signbit}, @code{signbitf}, @code{signbitl}, @code{signbitd32},
-@code{signbitd64}, @code{signbitd128}, @code{significandf},
-@code{significandl}, @code{significand}, @code{sincosf},
-@code{sincosl}, @code{sincos}, @code{stpcpy}, @code{stpncpy},
-@code{strcasecmp}, @code{strdup}, @code{strfmon}, @code{strncasecmp},
-@code{strndup}, @code{strnlen}, @code{toascii}, @code{y0f}, @code{y0l},
-@code{y0}, @code{y1f}, @code{y1l}, @code{y1}, @code{ynf}, @code{ynl} and
-@code{yn}
-may be handled as built-in functions.
-All these functions have corresponding versions
-prefixed with @code{__builtin_}, which may be used even in strict C90
-mode.
-
-The ISO C99 functions
-@code{_Exit}, @code{acoshf}, @code{acoshl}, @code{acosh}, @code{asinhf},
-@code{asinhl}, @code{asinh}, @code{atanhf}, @code{atanhl}, @code{atanh},
-@code{cabsf}, @code{cabsl}, @code{cabs}, @code{cacosf}, @code{cacoshf},
-@code{cacoshl}, @code{cacosh}, @code{cacosl}, @code{cacos},
-@code{cargf}, @code{cargl}, @code{carg}, @code{casinf}, @code{casinhf},
-@code{casinhl}, @code{casinh}, @code{casinl}, @code{casin},
-@code{catanf}, @code{catanhf}, @code{catanhl}, @code{catanh},
-@code{catanl}, @code{catan}, @code{cbrtf}, @code{cbrtl}, @code{cbrt},
-@code{ccosf}, @code{ccoshf}, @code{ccoshl}, @code{ccosh}, @code{ccosl},
-@code{ccos}, @code{cexpf}, @code{cexpl}, @code{cexp}, @code{cimagf},
-@code{cimagl}, @code{cimag}, @code{clogf}, @code{clogl}, @code{clog},
-@code{conjf}, @code{conjl}, @code{conj}, @code{copysignf}, @code{copysignl},
-@code{copysign}, @code{cpowf}, @code{cpowl}, @code{cpow}, @code{cprojf},
-@code{cprojl}, @code{cproj}, @code{crealf}, @code{creall}, @code{creal},
-@code{csinf}, @code{csinhf}, @code{csinhl}, @code{csinh}, @code{csinl},
-@code{csin}, @code{csqrtf}, @code{csqrtl}, @code{csqrt}, @code{ctanf},
-@code{ctanhf}, @code{ctanhl}, @code{ctanh}, @code{ctanl}, @code{ctan},
-@code{erfcf}, @code{erfcl}, @code{erfc}, @code{erff}, @code{erfl},
-@code{erf}, @code{exp2f}, @code{exp2l}, @code{exp2}, @code{expm1f},
-@code{expm1l}, @code{expm1}, @code{fdimf}, @code{fdiml}, @code{fdim},
-@code{fmaf}, @code{fmal}, @code{fmaxf}, @code{fmaxl}, @code{fmax},
-@code{fma}, @code{fminf}, @code{fminl}, @code{fmin}, @code{hypotf},
-@code{hypotl}, @code{hypot}, @code{ilogbf}, @code{ilogbl}, @code{ilogb},
-@code{imaxabs}, @code{isblank}, @code{iswblank}, @code{lgammaf},
-@code{lgammal}, @code{lgamma}, @code{llabs}, @code{llrintf}, @code{llrintl},
-@code{llrint}, @code{llroundf}, @code{llroundl}, @code{llround},
-@code{log1pf}, @code{log1pl}, @code{log1p}, @code{log2f}, @code{log2l},
-@code{log2}, @code{logbf}, @code{logbl}, @code{logb}, @code{lrintf},
-@code{lrintl}, @code{lrint}, @code{lroundf}, @code{lroundl},
-@code{lround}, @code{nearbyintf}, @code{nearbyintl}, @code{nearbyint},
-@code{nextafterf}, @code{nextafterl}, @code{nextafter},
-@code{nexttowardf}, @code{nexttowardl}, @code{nexttoward},
-@code{remainderf}, @code{remainderl}, @code{remainder}, @code{remquof},
-@code{remquol}, @code{remquo}, @code{rintf}, @code{rintl}, @code{rint},
-@code{roundf}, @code{roundl}, @code{round}, @code{scalblnf},
-@code{scalblnl}, @code{scalbln}, @code{scalbnf}, @code{scalbnl},
-@code{scalbn}, @code{snprintf}, @code{tgammaf}, @code{tgammal},
-@code{tgamma}, @code{truncf}, @code{truncl}, @code{trunc},
-@code{vfscanf}, @code{vscanf}, @code{vsnprintf} and @code{vsscanf}
-are handled as built-in functions
-except in strict ISO C90 mode (@option{-ansi} or @option{-std=c90}).
-
-There are also built-in versions of the ISO C99 functions
-@code{acosf}, @code{acosl}, @code{asinf}, @code{asinl}, @code{atan2f},
-@code{atan2l}, @code{atanf}, @code{atanl}, @code{ceilf}, @code{ceill},
-@code{cosf}, @code{coshf}, @code{coshl}, @code{cosl}, @code{expf},
-@code{expl}, @code{fabsf}, @code{fabsl}, @code{floorf}, @code{floorl},
-@code{fmodf}, @code{fmodl}, @code{frexpf}, @code{frexpl}, @code{ldexpf},
-@code{ldexpl}, @code{log10f}, @code{log10l}, @code{logf}, @code{logl},
-@code{modfl}, @code{modff}, @code{powf}, @code{powl}, @code{sinf},
-@code{sinhf}, @code{sinhl}, @code{sinl}, @code{sqrtf}, @code{sqrtl},
-@code{tanf}, @code{tanhf}, @code{tanhl} and @code{tanl}
-that are recognized in any mode since ISO C90 reserves these names for
-the purpose to which ISO C99 puts them. All these functions have
-corresponding versions prefixed with @code{__builtin_}.
-
-There are also built-in functions @code{__builtin_fabsf@var{n}},
-@code{__builtin_fabsf@var{n}x}, @code{__builtin_copysignf@var{n}} and
-@code{__builtin_copysignf@var{n}x}, corresponding to the TS 18661-3
-functions @code{fabsf@var{n}}, @code{fabsf@var{n}x},
-@code{copysignf@var{n}} and @code{copysignf@var{n}x}, for supported
-types @code{_Float@var{n}} and @code{_Float@var{n}x}.
-
-There are also GNU extension functions @code{clog10}, @code{clog10f} and
-@code{clog10l} which names are reserved by ISO C99 for future use.
-All these functions have versions prefixed with @code{__builtin_}.
-
-The ISO C94 functions
-@code{iswalnum}, @code{iswalpha}, @code{iswcntrl}, @code{iswdigit},
-@code{iswgraph}, @code{iswlower}, @code{iswprint}, @code{iswpunct},
-@code{iswspace}, @code{iswupper}, @code{iswxdigit}, @code{towlower} and
-@code{towupper}
-are handled as built-in functions
-except in strict ISO C90 mode (@option{-ansi} or @option{-std=c90}).
-
-The ISO C90 functions
-@code{abort}, @code{abs}, @code{acos}, @code{asin}, @code{atan2},
-@code{atan}, @code{calloc}, @code{ceil}, @code{cosh}, @code{cos},
-@code{exit}, @code{exp}, @code{fabs}, @code{floor}, @code{fmod},
-@code{fprintf}, @code{fputs}, @code{free}, @code{frexp}, @code{fscanf},
-@code{isalnum}, @code{isalpha}, @code{iscntrl}, @code{isdigit},
-@code{isgraph}, @code{islower}, @code{isprint}, @code{ispunct},
-@code{isspace}, @code{isupper}, @code{isxdigit}, @code{tolower},
-@code{toupper}, @code{labs}, @code{ldexp}, @code{log10}, @code{log},
-@code{malloc}, @code{memchr}, @code{memcmp}, @code{memcpy},
-@code{memset}, @code{modf}, @code{pow}, @code{printf}, @code{putchar},
-@code{puts}, @code{realloc}, @code{scanf}, @code{sinh}, @code{sin},
-@code{snprintf}, @code{sprintf}, @code{sqrt}, @code{sscanf}, @code{strcat},
-@code{strchr}, @code{strcmp}, @code{strcpy}, @code{strcspn},
-@code{strlen}, @code{strncat}, @code{strncmp}, @code{strncpy},
-@code{strpbrk}, @code{strrchr}, @code{strspn}, @code{strstr},
-@code{tanh}, @code{tan}, @code{vfprintf}, @code{vprintf} and @code{vsprintf}
-are all recognized as built-in functions unless
-@option{-fno-builtin} is specified (or @option{-fno-builtin-@var{function}}
-is specified for an individual function). All of these functions have
-corresponding versions prefixed with @code{__builtin_}.
-
-GCC provides built-in versions of the ISO C99 floating-point comparison
-macros that avoid raising exceptions for unordered operands. They have
-the same names as the standard macros ( @code{isgreater},
-@code{isgreaterequal}, @code{isless}, @code{islessequal},
-@code{islessgreater}, and @code{isunordered}) , with @code{__builtin_}
-prefixed. We intend for a library implementor to be able to simply
-@code{#define} each standard macro to its built-in equivalent.
-In the same fashion, GCC provides @code{fpclassify}, @code{isfinite},
-@code{isinf_sign}, @code{isnormal} and @code{signbit} built-ins used with
-@code{__builtin_} prefixed. The @code{isinf} and @code{isnan}
-built-in functions appear both with and without the @code{__builtin_} prefix.
-With @code{-ffinite-math-only} option the @code{isinf} and @code{isnan}
-built-in functions will always return 0.
-
-GCC provides built-in versions of the ISO C99 floating-point rounding and
-exceptions handling functions @code{fegetround}, @code{feclearexcept} and
-@code{feraiseexcept}. They may not be available for all targets, and because
-they need close interaction with libc internal values, they may not be available
-for all target libcs, but in all cases they will gracefully fallback to libc
-calls. These built-in functions appear both with and without the
-@code{__builtin_} prefix.
-
-@deftypefn {Built-in Function} void *__builtin_alloca (size_t size)
-The @code{__builtin_alloca} function must be called at block scope.
-The function allocates an object @var{size} bytes large on the stack
-of the calling function. The object is aligned on the default stack
-alignment boundary for the target determined by the
-@code{__BIGGEST_ALIGNMENT__} macro. The @code{__builtin_alloca}
-function returns a pointer to the first byte of the allocated object.
-The lifetime of the allocated object ends just before the calling
-function returns to its caller. This is so even when
-@code{__builtin_alloca} is called within a nested block.
-
-For example, the following function allocates eight objects of @code{n}
-bytes each on the stack, storing a pointer to each in consecutive elements
-of the array @code{a}. It then passes the array to function @code{g}
-which can safely use the storage pointed to by each of the array elements.
-
-@smallexample
-void f (unsigned n)
-@{
- void *a [8];
- for (int i = 0; i != 8; ++i)
- a [i] = __builtin_alloca (n);
-
- g (a, n); // @r{safe}
-@}
-@end smallexample
-
-Since the @code{__builtin_alloca} function doesn't validate its argument
-it is the responsibility of its caller to make sure the argument doesn't
-cause it to exceed the stack size limit.
-The @code{__builtin_alloca} function is provided to make it possible to
-allocate on the stack arrays of bytes with an upper bound that may be
-computed at run time. Since C99 Variable Length Arrays offer
-similar functionality under a portable, more convenient, and safer
-interface they are recommended instead, in both C99 and C++ programs
-where GCC provides them as an extension.
-@xref{Variable Length}, for details.
-
-@end deftypefn
-
-@deftypefn {Built-in Function} void *__builtin_alloca_with_align (size_t size, size_t alignment)
-The @code{__builtin_alloca_with_align} function must be called at block
-scope. The function allocates an object @var{size} bytes large on
-the stack of the calling function. The allocated object is aligned on
-the boundary specified by the argument @var{alignment} whose unit is given
-in bits (not bytes). The @var{size} argument must be positive and not
-exceed the stack size limit. The @var{alignment} argument must be a constant
-integer expression that evaluates to a power of 2 greater than or equal to
-@code{CHAR_BIT} and less than some unspecified maximum. Invocations
-with other values are rejected with an error indicating the valid bounds.
-The function returns a pointer to the first byte of the allocated object.
-The lifetime of the allocated object ends at the end of the block in which
-the function was called. The allocated storage is released no later than
-just before the calling function returns to its caller, but may be released
-at the end of the block in which the function was called.
-
-For example, in the following function the call to @code{g} is unsafe
-because when @code{overalign} is non-zero, the space allocated by
-@code{__builtin_alloca_with_align} may have been released at the end
-of the @code{if} statement in which it was called.
-
-@smallexample
-void f (unsigned n, bool overalign)
-@{
- void *p;
- if (overalign)
- p = __builtin_alloca_with_align (n, 64 /* bits */);
- else
- p = __builtin_alloc (n);
-
- g (p, n); // @r{unsafe}
-@}
-@end smallexample
-
-Since the @code{__builtin_alloca_with_align} function doesn't validate its
-@var{size} argument it is the responsibility of its caller to make sure
-the argument doesn't cause it to exceed the stack size limit.
-The @code{__builtin_alloca_with_align} function is provided to make
-it possible to allocate on the stack overaligned arrays of bytes with
-an upper bound that may be computed at run time. Since C99
-Variable Length Arrays offer the same functionality under
-a portable, more convenient, and safer interface they are recommended
-instead, in both C99 and C++ programs where GCC provides them as
-an extension. @xref{Variable Length}, for details.
-
-@end deftypefn
-
-@deftypefn {Built-in Function} void *__builtin_alloca_with_align_and_max (size_t size, size_t alignment, size_t max_size)
-Similar to @code{__builtin_alloca_with_align} but takes an extra argument
-specifying an upper bound for @var{size} in case its value cannot be computed
-at compile time, for use by @option{-fstack-usage}, @option{-Wstack-usage}
-and @option{-Walloca-larger-than}. @var{max_size} must be a constant integer
-expression, it has no effect on code generation and no attempt is made to
-check its compatibility with @var{size}.
-
-@end deftypefn
-
-@deftypefn {Built-in Function} bool __builtin_has_attribute (@var{type-or-expression}, @var{attribute})
-The @code{__builtin_has_attribute} function evaluates to an integer constant
-expression equal to @code{true} if the symbol or type referenced by
-the @var{type-or-expression} argument has been declared with
-the @var{attribute} referenced by the second argument. For
-an @var{type-or-expression} argument that does not reference a symbol,
-since attributes do not apply to expressions the built-in consider
-the type of the argument. Neither argument is evaluated.
-The @var{type-or-expression} argument is subject to the same
-restrictions as the argument to @code{typeof} (@pxref{Typeof}). The
-@var{attribute} argument is an attribute name optionally followed by
-a comma-separated list of arguments enclosed in parentheses. Both forms
-of attribute names---with and without double leading and trailing
-underscores---are recognized. @xref{Attribute Syntax}, for details.
-When no attribute arguments are specified for an attribute that expects
-one or more arguments the function returns @code{true} if
-@var{type-or-expression} has been declared with the attribute regardless
-of the attribute argument values. Arguments provided for an attribute
-that expects some are validated and matched up to the provided number.
-The function returns @code{true} if all provided arguments match. For
-example, the first call to the function below evaluates to @code{true}
-because @code{x} is declared with the @code{aligned} attribute but
-the second call evaluates to @code{false} because @code{x} is declared
-@code{aligned (8)} and not @code{aligned (4)}.
-
-@smallexample
-__attribute__ ((aligned (8))) int x;
-_Static_assert (__builtin_has_attribute (x, aligned), "aligned");
-_Static_assert (!__builtin_has_attribute (x, aligned (4)), "aligned (4)");
-@end smallexample
-
-Due to a limitation the @code{__builtin_has_attribute} function returns
-@code{false} for the @code{mode} attribute even if the type or variable
-referenced by the @var{type-or-expression} argument was declared with one.
-The function is also not supported with labels, and in C with enumerators.
-
-Note that unlike the @code{__has_attribute} preprocessor operator which
-is suitable for use in @code{#if} preprocessing directives
-@code{__builtin_has_attribute} is an intrinsic function that is not
-recognized in such contexts.
-
-@end deftypefn
-
-@deftypefn {Built-in Function} @var{type} __builtin_speculation_safe_value (@var{type} val, @var{type} failval)
-
-This built-in function can be used to help mitigate against unsafe
-speculative execution. @var{type} may be any integral type or any
-pointer type.
-
-@enumerate
-@item
-If the CPU is not speculatively executing the code, then @var{val}
-is returned.
-@item
-If the CPU is executing speculatively then either:
-@itemize
-@item
-The function may cause execution to pause until it is known that the
-code is no-longer being executed speculatively (in which case
-@var{val} can be returned, as above); or
-@item
-The function may use target-dependent speculation tracking state to cause
-@var{failval} to be returned when it is known that speculative
-execution has incorrectly predicted a conditional branch operation.
-@end itemize
-@end enumerate
-
-The second argument, @var{failval}, is optional and defaults to zero
-if omitted.
-
-GCC defines the preprocessor macro
-@code{__HAVE_BUILTIN_SPECULATION_SAFE_VALUE} for targets that have been
-updated to support this builtin.
-
-The built-in function can be used where a variable appears to be used in a
-safe way, but the CPU, due to speculative execution may temporarily ignore
-the bounds checks. Consider, for example, the following function:
-
-@smallexample
-int array[500];
-int f (unsigned untrusted_index)
-@{
- if (untrusted_index < 500)
- return array[untrusted_index];
- return 0;
-@}
-@end smallexample
-
-If the function is called repeatedly with @code{untrusted_index} less
-than the limit of 500, then a branch predictor will learn that the
-block of code that returns a value stored in @code{array} will be
-executed. If the function is subsequently called with an
-out-of-range value it will still try to execute that block of code
-first until the CPU determines that the prediction was incorrect
-(the CPU will unwind any incorrect operations at that point).
-However, depending on how the result of the function is used, it might be
-possible to leave traces in the cache that can reveal what was stored
-at the out-of-bounds location. The built-in function can be used to
-provide some protection against leaking data in this way by changing
-the code to:
-
-@smallexample
-int array[500];
-int f (unsigned untrusted_index)
-@{
- if (untrusted_index < 500)
- return array[__builtin_speculation_safe_value (untrusted_index)];
- return 0;
-@}
-@end smallexample
-
-The built-in function will either cause execution to stall until the
-conditional branch has been fully resolved, or it may permit
-speculative execution to continue, but using 0 instead of
-@code{untrusted_value} if that exceeds the limit.
-
-If accessing any memory location is potentially unsafe when speculative
-execution is incorrect, then the code can be rewritten as
-
-@smallexample
-int array[500];
-int f (unsigned untrusted_index)
-@{
- if (untrusted_index < 500)
- return *__builtin_speculation_safe_value (&array[untrusted_index], NULL);
- return 0;
-@}
-@end smallexample
-
-which will cause a @code{NULL} pointer to be used for the unsafe case.
-
-@end deftypefn
-
-@deftypefn {Built-in Function} int __builtin_types_compatible_p (@var{type1}, @var{type2})
-
-You can use the built-in function @code{__builtin_types_compatible_p} to
-determine whether two types are the same.
-
-This built-in function returns 1 if the unqualified versions of the
-types @var{type1} and @var{type2} (which are types, not expressions) are
-compatible, 0 otherwise. The result of this built-in function can be
-used in integer constant expressions.
-
-This built-in function ignores top level qualifiers (e.g., @code{const},
-@code{volatile}). For example, @code{int} is equivalent to @code{const
-int}.
-
-The type @code{int[]} and @code{int[5]} are compatible. On the other
-hand, @code{int} and @code{char *} are not compatible, even if the size
-of their types, on the particular architecture are the same. Also, the
-amount of pointer indirection is taken into account when determining
-similarity. Consequently, @code{short *} is not similar to
-@code{short **}. Furthermore, two types that are typedefed are
-considered compatible if their underlying types are compatible.
-
-An @code{enum} type is not considered to be compatible with another
-@code{enum} type even if both are compatible with the same integer
-type; this is what the C standard specifies.
-For example, @code{enum @{foo, bar@}} is not similar to
-@code{enum @{hot, dog@}}.
-
-You typically use this function in code whose execution varies
-depending on the arguments' types. For example:
-
-@smallexample
-#define foo(x) \
- (@{ \
- typeof (x) tmp = (x); \
- if (__builtin_types_compatible_p (typeof (x), long double)) \
- tmp = foo_long_double (tmp); \
- else if (__builtin_types_compatible_p (typeof (x), double)) \
- tmp = foo_double (tmp); \
- else if (__builtin_types_compatible_p (typeof (x), float)) \
- tmp = foo_float (tmp); \
- else \
- abort (); \
- tmp; \
- @})
-@end smallexample
-
-@emph{Note:} This construct is only available for C@.
-
-@end deftypefn
-
-@deftypefn {Built-in Function} @var{type} __builtin_call_with_static_chain (@var{call_exp}, @var{pointer_exp})
-
-The @var{call_exp} expression must be a function call, and the
-@var{pointer_exp} expression must be a pointer. The @var{pointer_exp}
-is passed to the function call in the target's static chain location.
-The result of builtin is the result of the function call.
-
-@emph{Note:} This builtin is only available for C@.
-This builtin can be used to call Go closures from C.
-
-@end deftypefn
-
-@deftypefn {Built-in Function} @var{type} __builtin_choose_expr (@var{const_exp}, @var{exp1}, @var{exp2})
-
-You can use the built-in function @code{__builtin_choose_expr} to
-evaluate code depending on the value of a constant expression. This
-built-in function returns @var{exp1} if @var{const_exp}, which is an
-integer constant expression, is nonzero. Otherwise it returns @var{exp2}.
-
-This built-in function is analogous to the @samp{? :} operator in C,
-except that the expression returned has its type unaltered by promotion
-rules. Also, the built-in function does not evaluate the expression
-that is not chosen. For example, if @var{const_exp} evaluates to @code{true},
-@var{exp2} is not evaluated even if it has side effects.
-
-This built-in function can return an lvalue if the chosen argument is an
-lvalue.
-
-If @var{exp1} is returned, the return type is the same as @var{exp1}'s
-type. Similarly, if @var{exp2} is returned, its return type is the same
-as @var{exp2}.
-
-Example:
-
-@smallexample
-#define foo(x) \
- __builtin_choose_expr ( \
- __builtin_types_compatible_p (typeof (x), double), \
- foo_double (x), \
- __builtin_choose_expr ( \
- __builtin_types_compatible_p (typeof (x), float), \
- foo_float (x), \
- /* @r{The void expression results in a compile-time error} \
- @r{when assigning the result to something.} */ \
- (void)0))
-@end smallexample
-
-@emph{Note:} This construct is only available for C@. Furthermore, the
-unused expression (@var{exp1} or @var{exp2} depending on the value of
-@var{const_exp}) may still generate syntax errors. This may change in
-future revisions.
-
-@end deftypefn
-
-@deftypefn {Built-in Function} @var{type} __builtin_tgmath (@var{functions}, @var{arguments})
-
-The built-in function @code{__builtin_tgmath}, available only for C
-and Objective-C, calls a function determined according to the rules of
-@code{<tgmath.h>} macros. It is intended to be used in
-implementations of that header, so that expansions of macros from that
-header only expand each of their arguments once, to avoid problems
-when calls to such macros are nested inside the arguments of other
-calls to such macros; in addition, it results in better diagnostics
-for invalid calls to @code{<tgmath.h>} macros than implementations
-using other GNU C language features. For example, the @code{pow}
-type-generic macro might be defined as:
-
-@smallexample
-#define pow(a, b) __builtin_tgmath (powf, pow, powl, \
- cpowf, cpow, cpowl, a, b)
-@end smallexample
-
-The arguments to @code{__builtin_tgmath} are at least two pointers to
-functions, followed by the arguments to the type-generic macro (which
-will be passed as arguments to the selected function). All the
-pointers to functions must be pointers to prototyped functions, none
-of which may have variable arguments, and all of which must have the
-same number of parameters; the number of parameters of the first
-function determines how many arguments to @code{__builtin_tgmath} are
-interpreted as function pointers, and how many as the arguments to the
-called function.
-
-The types of the specified functions must all be different, but
-related to each other in the same way as a set of functions that may
-be selected between by a macro in @code{<tgmath.h>}. This means that
-the functions are parameterized by a floating-point type @var{t},
-different for each such function. The function return types may all
-be the same type, or they may be @var{t} for each function, or they
-may be the real type corresponding to @var{t} for each function (if
-some of the types @var{t} are complex). Likewise, for each parameter
-position, the type of the parameter in that position may always be the
-same type, or may be @var{t} for each function (this case must apply
-for at least one parameter position), or may be the real type
-corresponding to @var{t} for each function.
-
-The standard rules for @code{<tgmath.h>} macros are used to find a
-common type @var{u} from the types of the arguments for parameters
-whose types vary between the functions; complex integer types (a GNU
-extension) are treated like @code{_Complex double} for this purpose
-(or @code{_Complex _Float64} if all the function return types are the
-same @code{_Float@var{n}} or @code{_Float@var{n}x} type).
-If the function return types vary, or are all the same integer type,
-the function called is the one for which @var{t} is @var{u}, and it is
-an error if there is no such function. If the function return types
-are all the same floating-point type, the type-generic macro is taken
-to be one of those from TS 18661 that rounds the result to a narrower
-type; if there is a function for which @var{t} is @var{u}, it is
-called, and otherwise the first function, if any, for which @var{t}
-has at least the range and precision of @var{u} is called, and it is
-an error if there is no such function.
-
-@end deftypefn
-
-@deftypefn {Built-in Function} int __builtin_constant_p (@var{exp})
-You can use the built-in function @code{__builtin_constant_p} to
-determine if a value is known to be constant at compile time and hence
-that GCC can perform constant-folding on expressions involving that
-value. The argument of the function is the value to test. The function
-returns the integer 1 if the argument is known to be a compile-time
-constant and 0 if it is not known to be a compile-time constant. A
-return of 0 does not indicate that the value is @emph{not} a constant,
-but merely that GCC cannot prove it is a constant with the specified
-value of the @option{-O} option.
-
-You typically use this function in an embedded application where
-memory is a critical resource. If you have some complex calculation,
-you may want it to be folded if it involves constants, but need to call
-a function if it does not. For example:
-
-@smallexample
-#define Scale_Value(X) \
- (__builtin_constant_p (X) \
- ? ((X) * SCALE + OFFSET) : Scale (X))
-@end smallexample
-
-You may use this built-in function in either a macro or an inline
-function. However, if you use it in an inlined function and pass an
-argument of the function as the argument to the built-in, GCC
-never returns 1 when you call the inline function with a string constant
-or compound literal (@pxref{Compound Literals}) and does not return 1
-when you pass a constant numeric value to the inline function unless you
-specify the @option{-O} option.
-
-You may also use @code{__builtin_constant_p} in initializers for static
-data. For instance, you can write
-
-@smallexample
-static const int table[] = @{
- __builtin_constant_p (EXPRESSION) ? (EXPRESSION) : -1,
- /* @r{@dots{}} */
-@};
-@end smallexample
-
-@noindent
-This is an acceptable initializer even if @var{EXPRESSION} is not a
-constant expression, including the case where
-@code{__builtin_constant_p} returns 1 because @var{EXPRESSION} can be
-folded to a constant but @var{EXPRESSION} contains operands that are
-not otherwise permitted in a static initializer (for example,
-@code{0 && foo ()}). GCC must be more conservative about evaluating the
-built-in in this case, because it has no opportunity to perform
-optimization.
-@end deftypefn
-
-@deftypefn {Built-in Function} bool __builtin_is_constant_evaluated (void)
-The @code{__builtin_is_constant_evaluated} function is available only
-in C++. The built-in is intended to be used by implementations of
-the @code{std::is_constant_evaluated} C++ function. Programs should make
-use of the latter function rather than invoking the built-in directly.
-
-The main use case of the built-in is to determine whether a @code{constexpr}
-function is being called in a @code{constexpr} context. A call to
-the function evaluates to a core constant expression with the value
-@code{true} if and only if it occurs within the evaluation of an expression
-or conversion that is manifestly constant-evaluated as defined in the C++
-standard. Manifestly constant-evaluated contexts include constant-expressions,
-the conditions of @code{constexpr if} statements, constraint-expressions, and
-initializers of variables usable in constant expressions. For more details
-refer to the latest revision of the C++ standard.
-@end deftypefn
-
-@deftypefn {Built-in Function} void __builtin_clear_padding (@var{ptr})
-The built-in function @code{__builtin_clear_padding} function clears
-padding bits inside of the object representation of object pointed by
-@var{ptr}, which has to be a pointer. The value representation of the
-object is not affected. The type of the object is assumed to be the type
-the pointer points to. Inside of a union, the only cleared bits are
-bits that are padding bits for all the union members.
-
-This built-in-function is useful if the padding bits of an object might
-have intederminate values and the object representation needs to be
-bitwise compared to some other object, for example for atomic operations.
-
-For C++, @var{ptr} argument type should be pointer to trivially-copyable
-type, unless the argument is address of a variable or parameter, because
-otherwise it isn't known if the type isn't just a base class whose padding
-bits are reused or laid out differently in a derived class.
-@end deftypefn
-
-@deftypefn {Built-in Function} @var{type} __builtin_bit_cast (@var{type}, @var{arg})
-The @code{__builtin_bit_cast} function is available only
-in C++. The built-in is intended to be used by implementations of
-the @code{std::bit_cast} C++ template function. Programs should make
-use of the latter function rather than invoking the built-in directly.
-
-This built-in function allows reinterpreting the bits of the @var{arg}
-argument as if it had type @var{type}. @var{type} and the type of the
-@var{arg} argument need to be trivially copyable types with the same size.
-When manifestly constant-evaluated, it performs extra diagnostics required
-for @code{std::bit_cast} and returns a constant expression if @var{arg}
-is a constant expression. For more details
-refer to the latest revision of the C++ standard.
-@end deftypefn
-
-@deftypefn {Built-in Function} long __builtin_expect (long @var{exp}, long @var{c})
-@opindex fprofile-arcs
-You may use @code{__builtin_expect} to provide the compiler with
-branch prediction information. In general, you should prefer to
-use actual profile feedback for this (@option{-fprofile-arcs}), as
-programmers are notoriously bad at predicting how their programs
-actually perform. However, there are applications in which this
-data is hard to collect.
-
-The return value is the value of @var{exp}, which should be an integral
-expression. The semantics of the built-in are that it is expected that
-@var{exp} == @var{c}. For example:
-
-@smallexample
-if (__builtin_expect (x, 0))
- foo ();
-@end smallexample
-
-@noindent
-indicates that we do not expect to call @code{foo}, since
-we expect @code{x} to be zero. Since you are limited to integral
-expressions for @var{exp}, you should use constructions such as
-
-@smallexample
-if (__builtin_expect (ptr != NULL, 1))
- foo (*ptr);
-@end smallexample
-
-@noindent
-when testing pointer or floating-point values.
-
-For the purposes of branch prediction optimizations, the probability that
-a @code{__builtin_expect} expression is @code{true} is controlled by GCC's
-@code{builtin-expect-probability} parameter, which defaults to 90%.
-
-You can also use @code{__builtin_expect_with_probability} to explicitly
-assign a probability value to individual expressions. If the built-in
-is used in a loop construct, the provided probability will influence
-the expected number of iterations made by loop optimizations.
-@end deftypefn
-
-@deftypefn {Built-in Function} long __builtin_expect_with_probability
-(long @var{exp}, long @var{c}, double @var{probability})
-
-This function has the same semantics as @code{__builtin_expect},
-but the caller provides the expected probability that @var{exp} == @var{c}.
-The last argument, @var{probability}, is a floating-point value in the
-range 0.0 to 1.0, inclusive. The @var{probability} argument must be
-constant floating-point expression.
-@end deftypefn
-
-@deftypefn {Built-in Function} void __builtin_trap (void)
-This function causes the program to exit abnormally. GCC implements
-this function by using a target-dependent mechanism (such as
-intentionally executing an illegal instruction) or by calling
-@code{abort}. The mechanism used may vary from release to release so
-you should not rely on any particular implementation.
-@end deftypefn
-
-@deftypefn {Built-in Function} void __builtin_unreachable (void)
-If control flow reaches the point of the @code{__builtin_unreachable},
-the program is undefined. It is useful in situations where the
-compiler cannot deduce the unreachability of the code.
-
-One such case is immediately following an @code{asm} statement that
-either never terminates, or one that transfers control elsewhere
-and never returns. In this example, without the
-@code{__builtin_unreachable}, GCC issues a warning that control
-reaches the end of a non-void function. It also generates code
-to return after the @code{asm}.
-
-@smallexample
-int f (int c, int v)
-@{
- if (c)
- @{
- return v;
- @}
- else
- @{
- asm("jmp error_handler");
- __builtin_unreachable ();
- @}
-@}
-@end smallexample
-
-@noindent
-Because the @code{asm} statement unconditionally transfers control out
-of the function, control never reaches the end of the function
-body. The @code{__builtin_unreachable} is in fact unreachable and
-communicates this fact to the compiler.
-
-Another use for @code{__builtin_unreachable} is following a call a
-function that never returns but that is not declared
-@code{__attribute__((noreturn))}, as in this example:
-
-@smallexample
-void function_that_never_returns (void);
-
-int g (int c)
-@{
- if (c)
- @{
- return 1;
- @}
- else
- @{
- function_that_never_returns ();
- __builtin_unreachable ();
- @}
-@}
-@end smallexample
-
-@end deftypefn
-
-@deftypefn {Built-in Function} @var{type} __builtin_assoc_barrier (@var{type} @var{expr})
-This built-in inhibits re-association of the floating-point expression
-@var{expr} with expressions consuming the return value of the built-in. The
-expression @var{expr} itself can be reordered, and the whole expression
-@var{expr} can be reordered with operands after the barrier. The barrier is
-only relevant when @code{-fassociative-math} is active, since otherwise
-floating-point is not treated as associative.
-
-@smallexample
-float x0 = a + b - b;
-float x1 = __builtin_assoc_barrier(a + b) - b;
-@end smallexample
-
-@noindent
-means that, with @code{-fassociative-math}, @code{x0} can be optimized to
-@code{x0 = a} but @code{x1} cannot.
-@end deftypefn
-
-@deftypefn {Built-in Function} {void *} __builtin_assume_aligned (const void *@var{exp}, size_t @var{align}, ...)
-This function returns its first argument, and allows the compiler
-to assume that the returned pointer is at least @var{align} bytes
-aligned. This built-in can have either two or three arguments,
-if it has three, the third argument should have integer type, and
-if it is nonzero means misalignment offset. For example:
-
-@smallexample
-void *x = __builtin_assume_aligned (arg, 16);
-@end smallexample
-
-@noindent
-means that the compiler can assume @code{x}, set to @code{arg}, is at least
-16-byte aligned, while:
-
-@smallexample
-void *x = __builtin_assume_aligned (arg, 32, 8);
-@end smallexample
-
-@noindent
-means that the compiler can assume for @code{x}, set to @code{arg}, that
-@code{(char *) x - 8} is 32-byte aligned.
-@end deftypefn
-
-@deftypefn {Built-in Function} int __builtin_LINE ()
-This function is the equivalent of the preprocessor @code{__LINE__}
-macro and returns a constant integer expression that evaluates to
-the line number of the invocation of the built-in. When used as a C++
-default argument for a function @var{F}, it returns the line number
-of the call to @var{F}.
-@end deftypefn
-
-@deftypefn {Built-in Function} {const char *} __builtin_FUNCTION ()
-This function is the equivalent of the @code{__FUNCTION__} symbol
-and returns an address constant pointing to the name of the function
-from which the built-in was invoked, or the empty string if
-the invocation is not at function scope. When used as a C++ default
-argument for a function @var{F}, it returns the name of @var{F}'s
-caller or the empty string if the call was not made at function
-scope.
-@end deftypefn
-
-@deftypefn {Built-in Function} {const char *} __builtin_FILE ()
-This function is the equivalent of the preprocessor @code{__FILE__}
-macro and returns an address constant pointing to the file name
-containing the invocation of the built-in, or the empty string if
-the invocation is not at function scope. When used as a C++ default
-argument for a function @var{F}, it returns the file name of the call
-to @var{F} or the empty string if the call was not made at function
-scope.
-
-For example, in the following, each call to function @code{foo} will
-print a line similar to @code{"file.c:123: foo: message"} with the name
-of the file and the line number of the @code{printf} call, the name of
-the function @code{foo}, followed by the word @code{message}.
-
-@smallexample
-const char*
-function (const char *func = __builtin_FUNCTION ())
-@{
- return func;
-@}
-
-void foo (void)
-@{
- printf ("%s:%i: %s: message\n", file (), line (), function ());
-@}
-@end smallexample
-
-@end deftypefn
-
-@deftypefn {Built-in Function} void __builtin___clear_cache (void *@var{begin}, void *@var{end})
-This function is used to flush the processor's instruction cache for
-the region of memory between @var{begin} inclusive and @var{end}
-exclusive. Some targets require that the instruction cache be
-flushed, after modifying memory containing code, in order to obtain
-deterministic behavior.
-
-If the target does not require instruction cache flushes,
-@code{__builtin___clear_cache} has no effect. Otherwise either
-instructions are emitted in-line to clear the instruction cache or a
-call to the @code{__clear_cache} function in libgcc is made.
-@end deftypefn
-
-@deftypefn {Built-in Function} void __builtin_prefetch (const void *@var{addr}, ...)
-This function is used to minimize cache-miss latency by moving data into
-a cache before it is accessed.
-You can insert calls to @code{__builtin_prefetch} into code for which
-you know addresses of data in memory that is likely to be accessed soon.
-If the target supports them, data prefetch instructions are generated.
-If the prefetch is done early enough before the access then the data will
-be in the cache by the time it is accessed.
-
-The value of @var{addr} is the address of the memory to prefetch.
-There are two optional arguments, @var{rw} and @var{locality}.
-The value of @var{rw} is a compile-time constant one or zero; one
-means that the prefetch is preparing for a write to the memory address
-and zero, the default, means that the prefetch is preparing for a read.
-The value @var{locality} must be a compile-time constant integer between
-zero and three. A value of zero means that the data has no temporal
-locality, so it need not be left in the cache after the access. A value
-of three means that the data has a high degree of temporal locality and
-should be left in all levels of cache possible. Values of one and two
-mean, respectively, a low or moderate degree of temporal locality. The
-default is three.
-
-@smallexample
-for (i = 0; i < n; i++)
- @{
- a[i] = a[i] + b[i];
- __builtin_prefetch (&a[i+j], 1, 1);
- __builtin_prefetch (&b[i+j], 0, 1);
- /* @r{@dots{}} */
- @}
-@end smallexample
-
-Data prefetch does not generate faults if @var{addr} is invalid, but
-the address expression itself must be valid. For example, a prefetch
-of @code{p->next} does not fault if @code{p->next} is not a valid
-address, but evaluation faults if @code{p} is not a valid address.
-
-If the target does not support data prefetch, the address expression
-is evaluated if it includes side effects but no other code is generated
-and GCC does not issue a warning.
-@end deftypefn
-
-@deftypefn {Built-in Function}{size_t} __builtin_object_size (const void * @var{ptr}, int @var{type})
-Returns the size of an object pointed to by @var{ptr}. @xref{Object Size
-Checking}, for a detailed description of the function.
-@end deftypefn
-
-@deftypefn {Built-in Function} double __builtin_huge_val (void)
-Returns a positive infinity, if supported by the floating-point format,
-else @code{DBL_MAX}. This function is suitable for implementing the
-ISO C macro @code{HUGE_VAL}.
-@end deftypefn
-
-@deftypefn {Built-in Function} float __builtin_huge_valf (void)
-Similar to @code{__builtin_huge_val}, except the return type is @code{float}.
-@end deftypefn
-
-@deftypefn {Built-in Function} {long double} __builtin_huge_vall (void)
-Similar to @code{__builtin_huge_val}, except the return
-type is @code{long double}.
-@end deftypefn
-
-@deftypefn {Built-in Function} _Float@var{n} __builtin_huge_valf@var{n} (void)
-Similar to @code{__builtin_huge_val}, except the return type is
-@code{_Float@var{n}}.
-@end deftypefn
-
-@deftypefn {Built-in Function} _Float@var{n}x __builtin_huge_valf@var{n}x (void)
-Similar to @code{__builtin_huge_val}, except the return type is
-@code{_Float@var{n}x}.
-@end deftypefn
-
-@deftypefn {Built-in Function} int __builtin_fpclassify (int, int, int, int, int, ...)
-This built-in implements the C99 fpclassify functionality. The first
-five int arguments should be the target library's notion of the
-possible FP classes and are used for return values. They must be
-constant values and they must appear in this order: @code{FP_NAN},
-@code{FP_INFINITE}, @code{FP_NORMAL}, @code{FP_SUBNORMAL} and
-@code{FP_ZERO}. The ellipsis is for exactly one floating-point value
-to classify. GCC treats the last argument as type-generic, which
-means it does not do default promotion from float to double.
-@end deftypefn
-
-@deftypefn {Built-in Function} double __builtin_inf (void)
-Similar to @code{__builtin_huge_val}, except a warning is generated
-if the target floating-point format does not support infinities.
-@end deftypefn
-
-@deftypefn {Built-in Function} _Decimal32 __builtin_infd32 (void)
-Similar to @code{__builtin_inf}, except the return type is @code{_Decimal32}.
-@end deftypefn
-
-@deftypefn {Built-in Function} _Decimal64 __builtin_infd64 (void)
-Similar to @code{__builtin_inf}, except the return type is @code{_Decimal64}.
-@end deftypefn
-
-@deftypefn {Built-in Function} _Decimal128 __builtin_infd128 (void)
-Similar to @code{__builtin_inf}, except the return type is @code{_Decimal128}.
-@end deftypefn
-
-@deftypefn {Built-in Function} float __builtin_inff (void)
-Similar to @code{__builtin_inf}, except the return type is @code{float}.
-This function is suitable for implementing the ISO C99 macro @code{INFINITY}.
-@end deftypefn
-
-@deftypefn {Built-in Function} {long double} __builtin_infl (void)
-Similar to @code{__builtin_inf}, except the return
-type is @code{long double}.
-@end deftypefn
-
-@deftypefn {Built-in Function} _Float@var{n} __builtin_inff@var{n} (void)
-Similar to @code{__builtin_inf}, except the return
-type is @code{_Float@var{n}}.
-@end deftypefn
-
-@deftypefn {Built-in Function} _Float@var{n} __builtin_inff@var{n}x (void)
-Similar to @code{__builtin_inf}, except the return
-type is @code{_Float@var{n}x}.
-@end deftypefn
-
-@deftypefn {Built-in Function} int __builtin_isinf_sign (...)
-Similar to @code{isinf}, except the return value is -1 for
-an argument of @code{-Inf} and 1 for an argument of @code{+Inf}.
-Note while the parameter list is an
-ellipsis, this function only accepts exactly one floating-point
-argument. GCC treats this parameter as type-generic, which means it
-does not do default promotion from float to double.
-@end deftypefn
-
-@deftypefn {Built-in Function} double __builtin_nan (const char *str)
-This is an implementation of the ISO C99 function @code{nan}.
-
-Since ISO C99 defines this function in terms of @code{strtod}, which we
-do not implement, a description of the parsing is in order. The string
-is parsed as by @code{strtol}; that is, the base is recognized by
-leading @samp{0} or @samp{0x} prefixes. The number parsed is placed
-in the significand such that the least significant bit of the number
-is at the least significant bit of the significand. The number is
-truncated to fit the significand field provided. The significand is
-forced to be a quiet NaN@.
-
-This function, if given a string literal all of which would have been
-consumed by @code{strtol}, is evaluated early enough that it is considered a
-compile-time constant.
-@end deftypefn
-
-@deftypefn {Built-in Function} _Decimal32 __builtin_nand32 (const char *str)
-Similar to @code{__builtin_nan}, except the return type is @code{_Decimal32}.
-@end deftypefn
-
-@deftypefn {Built-in Function} _Decimal64 __builtin_nand64 (const char *str)
-Similar to @code{__builtin_nan}, except the return type is @code{_Decimal64}.
-@end deftypefn
-
-@deftypefn {Built-in Function} _Decimal128 __builtin_nand128 (const char *str)
-Similar to @code{__builtin_nan}, except the return type is @code{_Decimal128}.
-@end deftypefn
-
-@deftypefn {Built-in Function} float __builtin_nanf (const char *str)
-Similar to @code{__builtin_nan}, except the return type is @code{float}.
-@end deftypefn
-
-@deftypefn {Built-in Function} {long double} __builtin_nanl (const char *str)
-Similar to @code{__builtin_nan}, except the return type is @code{long double}.
-@end deftypefn
-
-@deftypefn {Built-in Function} _Float@var{n} __builtin_nanf@var{n} (const char *str)
-Similar to @code{__builtin_nan}, except the return type is
-@code{_Float@var{n}}.
-@end deftypefn
-
-@deftypefn {Built-in Function} _Float@var{n}x __builtin_nanf@var{n}x (const char *str)
-Similar to @code{__builtin_nan}, except the return type is
-@code{_Float@var{n}x}.
-@end deftypefn
-
-@deftypefn {Built-in Function} double __builtin_nans (const char *str)
-Similar to @code{__builtin_nan}, except the significand is forced
-to be a signaling NaN@. The @code{nans} function is proposed by
-@uref{http://www.open-std.org/jtc1/sc22/wg14/www/docs/n965.htm,,WG14 N965}.
-@end deftypefn
-
-@deftypefn {Built-in Function} _Decimal32 __builtin_nansd32 (const char *str)
-Similar to @code{__builtin_nans}, except the return type is @code{_Decimal32}.
-@end deftypefn
-
-@deftypefn {Built-in Function} _Decimal64 __builtin_nansd64 (const char *str)
-Similar to @code{__builtin_nans}, except the return type is @code{_Decimal64}.
-@end deftypefn
-
-@deftypefn {Built-in Function} _Decimal128 __builtin_nansd128 (const char *str)
-Similar to @code{__builtin_nans}, except the return type is @code{_Decimal128}.
-@end deftypefn
-
-@deftypefn {Built-in Function} float __builtin_nansf (const char *str)
-Similar to @code{__builtin_nans}, except the return type is @code{float}.
-@end deftypefn
-
-@deftypefn {Built-in Function} {long double} __builtin_nansl (const char *str)
-Similar to @code{__builtin_nans}, except the return type is @code{long double}.
-@end deftypefn
-
-@deftypefn {Built-in Function} _Float@var{n} __builtin_nansf@var{n} (const char *str)
-Similar to @code{__builtin_nans}, except the return type is
-@code{_Float@var{n}}.
-@end deftypefn
-
-@deftypefn {Built-in Function} _Float@var{n}x __builtin_nansf@var{n}x (const char *str)
-Similar to @code{__builtin_nans}, except the return type is
-@code{_Float@var{n}x}.
-@end deftypefn
-
-@deftypefn {Built-in Function} int __builtin_issignaling (...)
-Return non-zero if the argument is a signaling NaN and zero otherwise.
-Note while the parameter list is an
-ellipsis, this function only accepts exactly one floating-point
-argument. GCC treats this parameter as type-generic, which means it
-does not do default promotion from float to double.
-This built-in function can work even without the non-default
-@code{-fsignaling-nans} option, although if a signaling NaN is computed,
-stored or passed as argument to some function other than this built-in
-in the current translation unit, it is safer to use @code{-fsignaling-nans}.
-With @code{-ffinite-math-only} option this built-in function will always
-return 0.
-@end deftypefn
-
-@deftypefn {Built-in Function} int __builtin_ffs (int x)
-Returns one plus the index of the least significant 1-bit of @var{x}, or
-if @var{x} is zero, returns zero.
-@end deftypefn
-
-@deftypefn {Built-in Function} int __builtin_clz (unsigned int x)
-Returns the number of leading 0-bits in @var{x}, starting at the most
-significant bit position. If @var{x} is 0, the result is undefined.
-@end deftypefn
-
-@deftypefn {Built-in Function} int __builtin_ctz (unsigned int x)
-Returns the number of trailing 0-bits in @var{x}, starting at the least
-significant bit position. If @var{x} is 0, the result is undefined.
-@end deftypefn
-
-@deftypefn {Built-in Function} int __builtin_clrsb (int x)
-Returns the number of leading redundant sign bits in @var{x}, i.e.@: the
-number of bits following the most significant bit that are identical
-to it. There are no special cases for 0 or other values.
-@end deftypefn
-
-@deftypefn {Built-in Function} int __builtin_popcount (unsigned int x)
-Returns the number of 1-bits in @var{x}.
-@end deftypefn
-
-@deftypefn {Built-in Function} int __builtin_parity (unsigned int x)
-Returns the parity of @var{x}, i.e.@: the number of 1-bits in @var{x}
-modulo 2.
-@end deftypefn
-
-@deftypefn {Built-in Function} int __builtin_ffsl (long)
-Similar to @code{__builtin_ffs}, except the argument type is
-@code{long}.
-@end deftypefn
-
-@deftypefn {Built-in Function} int __builtin_clzl (unsigned long)
-Similar to @code{__builtin_clz}, except the argument type is
-@code{unsigned long}.
-@end deftypefn
-
-@deftypefn {Built-in Function} int __builtin_ctzl (unsigned long)
-Similar to @code{__builtin_ctz}, except the argument type is
-@code{unsigned long}.
-@end deftypefn
-
-@deftypefn {Built-in Function} int __builtin_clrsbl (long)
-Similar to @code{__builtin_clrsb}, except the argument type is
-@code{long}.
-@end deftypefn
-
-@deftypefn {Built-in Function} int __builtin_popcountl (unsigned long)
-Similar to @code{__builtin_popcount}, except the argument type is
-@code{unsigned long}.
-@end deftypefn
-
-@deftypefn {Built-in Function} int __builtin_parityl (unsigned long)
-Similar to @code{__builtin_parity}, except the argument type is
-@code{unsigned long}.
-@end deftypefn
-
-@deftypefn {Built-in Function} int __builtin_ffsll (long long)
-Similar to @code{__builtin_ffs}, except the argument type is
-@code{long long}.
-@end deftypefn
-
-@deftypefn {Built-in Function} int __builtin_clzll (unsigned long long)
-Similar to @code{__builtin_clz}, except the argument type is
-@code{unsigned long long}.
-@end deftypefn
-
-@deftypefn {Built-in Function} int __builtin_ctzll (unsigned long long)
-Similar to @code{__builtin_ctz}, except the argument type is
-@code{unsigned long long}.
-@end deftypefn
-
-@deftypefn {Built-in Function} int __builtin_clrsbll (long long)
-Similar to @code{__builtin_clrsb}, except the argument type is
-@code{long long}.
-@end deftypefn
-
-@deftypefn {Built-in Function} int __builtin_popcountll (unsigned long long)
-Similar to @code{__builtin_popcount}, except the argument type is
-@code{unsigned long long}.
-@end deftypefn
-
-@deftypefn {Built-in Function} int __builtin_parityll (unsigned long long)
-Similar to @code{__builtin_parity}, except the argument type is
-@code{unsigned long long}.
-@end deftypefn
-
-@deftypefn {Built-in Function} double __builtin_powi (double, int)
-Returns the first argument raised to the power of the second. Unlike the
-@code{pow} function no guarantees about precision and rounding are made.
-@end deftypefn
-
-@deftypefn {Built-in Function} float __builtin_powif (float, int)
-Similar to @code{__builtin_powi}, except the argument and return types
-are @code{float}.
-@end deftypefn
-
-@deftypefn {Built-in Function} {long double} __builtin_powil (long double, int)
-Similar to @code{__builtin_powi}, except the argument and return types
-are @code{long double}.
-@end deftypefn
-
-@deftypefn {Built-in Function} uint16_t __builtin_bswap16 (uint16_t x)
-Returns @var{x} with the order of the bytes reversed; for example,
-@code{0xaabb} becomes @code{0xbbaa}. Byte here always means
-exactly 8 bits.
-@end deftypefn
-
-@deftypefn {Built-in Function} uint32_t __builtin_bswap32 (uint32_t x)
-Similar to @code{__builtin_bswap16}, except the argument and return types
-are 32-bit.
-@end deftypefn
-
-@deftypefn {Built-in Function} uint64_t __builtin_bswap64 (uint64_t x)
-Similar to @code{__builtin_bswap32}, except the argument and return types
-are 64-bit.
-@end deftypefn
-
-@deftypefn {Built-in Function} uint128_t __builtin_bswap128 (uint128_t x)
-Similar to @code{__builtin_bswap64}, except the argument and return types
-are 128-bit. Only supported on targets when 128-bit types are supported.
-@end deftypefn
-
-
-@deftypefn {Built-in Function} Pmode __builtin_extend_pointer (void * x)
-On targets where the user visible pointer size is smaller than the size
-of an actual hardware address this function returns the extended user
-pointer. Targets where this is true included ILP32 mode on x86_64 or
-Aarch64. This function is mainly useful when writing inline assembly
-code.
-@end deftypefn
-
-@deftypefn {Built-in Function} int __builtin_goacc_parlevel_id (int x)
-Returns the openacc gang, worker or vector id depending on whether @var{x} is
-0, 1 or 2.
-@end deftypefn
-
-@deftypefn {Built-in Function} int __builtin_goacc_parlevel_size (int x)
-Returns the openacc gang, worker or vector size depending on whether @var{x} is
-0, 1 or 2.
-@end deftypefn
-
-@node Target Builtins
-@section Built-in Functions Specific to Particular Target Machines
-
-On some target machines, GCC supports many built-in functions specific
-to those machines. Generally these generate calls to specific machine
-instructions, but allow the compiler to schedule those calls.
-
-@menu
-* AArch64 Built-in Functions::
-* Alpha Built-in Functions::
-* Altera Nios II Built-in Functions::
-* ARC Built-in Functions::
-* ARC SIMD Built-in Functions::
-* ARM iWMMXt Built-in Functions::
-* ARM C Language Extensions (ACLE)::
-* ARM Floating Point Status and Control Intrinsics::
-* ARM ARMv8-M Security Extensions::
-* AVR Built-in Functions::
-* Blackfin Built-in Functions::
-* BPF Built-in Functions::
-* FR-V Built-in Functions::
-* MIPS DSP Built-in Functions::
-* MIPS Paired-Single Support::
-* MIPS Loongson Built-in Functions::
-* MIPS SIMD Architecture (MSA) Support::
-* Other MIPS Built-in Functions::
-* MSP430 Built-in Functions::
-* NDS32 Built-in Functions::
-* picoChip Built-in Functions::
-* Basic PowerPC Built-in Functions::
-* PowerPC AltiVec/VSX Built-in Functions::
-* PowerPC Hardware Transactional Memory Built-in Functions::
-* PowerPC Atomic Memory Operation Functions::
-* PowerPC Matrix-Multiply Assist Built-in Functions::
-* PRU Built-in Functions::
-* RISC-V Built-in Functions::
-* RX Built-in Functions::
-* S/390 System z Built-in Functions::
-* SH Built-in Functions::
-* SPARC VIS Built-in Functions::
-* TI C6X Built-in Functions::
-* x86 Built-in Functions::
-* x86 transactional memory intrinsics::
-* x86 control-flow protection intrinsics::
-@end menu
-
-@node AArch64 Built-in Functions
-@subsection AArch64 Built-in Functions
-
-These built-in functions are available for the AArch64 family of
-processors.
-@smallexample
-unsigned int __builtin_aarch64_get_fpcr ();
-void __builtin_aarch64_set_fpcr (unsigned int);
-unsigned int __builtin_aarch64_get_fpsr ();
-void __builtin_aarch64_set_fpsr (unsigned int);
-
-unsigned long long __builtin_aarch64_get_fpcr64 ();
-void __builtin_aarch64_set_fpcr64 (unsigned long long);
-unsigned long long __builtin_aarch64_get_fpsr64 ();
-void __builtin_aarch64_set_fpsr64 (unsigned long long);
-@end smallexample
-
-@node Alpha Built-in Functions
-@subsection Alpha Built-in Functions
-
-These built-in functions are available for the Alpha family of
-processors, depending on the command-line switches used.
-
-The following built-in functions are always available. They
-all generate the machine instruction that is part of the name.
-
-@smallexample
-long __builtin_alpha_implver (void);
-long __builtin_alpha_rpcc (void);
-long __builtin_alpha_amask (long);
-long __builtin_alpha_cmpbge (long, long);
-long __builtin_alpha_extbl (long, long);
-long __builtin_alpha_extwl (long, long);
-long __builtin_alpha_extll (long, long);
-long __builtin_alpha_extql (long, long);
-long __builtin_alpha_extwh (long, long);
-long __builtin_alpha_extlh (long, long);
-long __builtin_alpha_extqh (long, long);
-long __builtin_alpha_insbl (long, long);
-long __builtin_alpha_inswl (long, long);
-long __builtin_alpha_insll (long, long);
-long __builtin_alpha_insql (long, long);
-long __builtin_alpha_inswh (long, long);
-long __builtin_alpha_inslh (long, long);
-long __builtin_alpha_insqh (long, long);
-long __builtin_alpha_mskbl (long, long);
-long __builtin_alpha_mskwl (long, long);
-long __builtin_alpha_mskll (long, long);
-long __builtin_alpha_mskql (long, long);
-long __builtin_alpha_mskwh (long, long);
-long __builtin_alpha_msklh (long, long);
-long __builtin_alpha_mskqh (long, long);
-long __builtin_alpha_umulh (long, long);
-long __builtin_alpha_zap (long, long);
-long __builtin_alpha_zapnot (long, long);
-@end smallexample
-
-The following built-in functions are always with @option{-mmax}
-or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{pca56} or
-later. They all generate the machine instruction that is part
-of the name.
-
-@smallexample
-long __builtin_alpha_pklb (long);
-long __builtin_alpha_pkwb (long);
-long __builtin_alpha_unpkbl (long);
-long __builtin_alpha_unpkbw (long);
-long __builtin_alpha_minub8 (long, long);
-long __builtin_alpha_minsb8 (long, long);
-long __builtin_alpha_minuw4 (long, long);
-long __builtin_alpha_minsw4 (long, long);
-long __builtin_alpha_maxub8 (long, long);
-long __builtin_alpha_maxsb8 (long, long);
-long __builtin_alpha_maxuw4 (long, long);
-long __builtin_alpha_maxsw4 (long, long);
-long __builtin_alpha_perr (long, long);
-@end smallexample
-
-The following built-in functions are always with @option{-mcix}
-or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{ev67} or
-later. They all generate the machine instruction that is part
-of the name.
-
-@smallexample
-long __builtin_alpha_cttz (long);
-long __builtin_alpha_ctlz (long);
-long __builtin_alpha_ctpop (long);
-@end smallexample
-
-The following built-in functions are available on systems that use the OSF/1
-PALcode. Normally they invoke the @code{rduniq} and @code{wruniq}
-PAL calls, but when invoked with @option{-mtls-kernel}, they invoke
-@code{rdval} and @code{wrval}.
-
-@smallexample
-void *__builtin_thread_pointer (void);
-void __builtin_set_thread_pointer (void *);
-@end smallexample
-
-@node Altera Nios II Built-in Functions
-@subsection Altera Nios II Built-in Functions
-
-These built-in functions are available for the Altera Nios II
-family of processors.
-
-The following built-in functions are always available. They
-all generate the machine instruction that is part of the name.
-
-@example
-int __builtin_ldbio (volatile const void *);
-int __builtin_ldbuio (volatile const void *);
-int __builtin_ldhio (volatile const void *);
-int __builtin_ldhuio (volatile const void *);
-int __builtin_ldwio (volatile const void *);
-void __builtin_stbio (volatile void *, int);
-void __builtin_sthio (volatile void *, int);
-void __builtin_stwio (volatile void *, int);
-void __builtin_sync (void);
-int __builtin_rdctl (int);
-int __builtin_rdprs (int, int);
-void __builtin_wrctl (int, int);
-void __builtin_flushd (volatile void *);
-void __builtin_flushda (volatile void *);
-int __builtin_wrpie (int);
-void __builtin_eni (int);
-int __builtin_ldex (volatile const void *);
-int __builtin_stex (volatile void *, int);
-int __builtin_ldsex (volatile const void *);
-int __builtin_stsex (volatile void *, int);
-@end example
-
-The following built-in functions are always available. They
-all generate a Nios II Custom Instruction. The name of the
-function represents the types that the function takes and
-returns. The letter before the @code{n} is the return type
-or void if absent. The @code{n} represents the first parameter
-to all the custom instructions, the custom instruction number.
-The two letters after the @code{n} represent the up to two
-parameters to the function.
-
-The letters represent the following data types:
-@table @code
-@item <no letter>
-@code{void} for return type and no parameter for parameter types.
-
-@item i
-@code{int} for return type and parameter type
-
-@item f
-@code{float} for return type and parameter type
-
-@item p
-@code{void *} for return type and parameter type
-
-@end table
-
-And the function names are:
-@example
-void __builtin_custom_n (void);
-void __builtin_custom_ni (int);
-void __builtin_custom_nf (float);
-void __builtin_custom_np (void *);
-void __builtin_custom_nii (int, int);
-void __builtin_custom_nif (int, float);
-void __builtin_custom_nip (int, void *);
-void __builtin_custom_nfi (float, int);
-void __builtin_custom_nff (float, float);
-void __builtin_custom_nfp (float, void *);
-void __builtin_custom_npi (void *, int);
-void __builtin_custom_npf (void *, float);
-void __builtin_custom_npp (void *, void *);
-int __builtin_custom_in (void);
-int __builtin_custom_ini (int);
-int __builtin_custom_inf (float);
-int __builtin_custom_inp (void *);
-int __builtin_custom_inii (int, int);
-int __builtin_custom_inif (int, float);
-int __builtin_custom_inip (int, void *);
-int __builtin_custom_infi (float, int);
-int __builtin_custom_inff (float, float);
-int __builtin_custom_infp (float, void *);
-int __builtin_custom_inpi (void *, int);
-int __builtin_custom_inpf (void *, float);
-int __builtin_custom_inpp (void *, void *);
-float __builtin_custom_fn (void);
-float __builtin_custom_fni (int);
-float __builtin_custom_fnf (float);
-float __builtin_custom_fnp (void *);
-float __builtin_custom_fnii (int, int);
-float __builtin_custom_fnif (int, float);
-float __builtin_custom_fnip (int, void *);
-float __builtin_custom_fnfi (float, int);
-float __builtin_custom_fnff (float, float);
-float __builtin_custom_fnfp (float, void *);
-float __builtin_custom_fnpi (void *, int);
-float __builtin_custom_fnpf (void *, float);
-float __builtin_custom_fnpp (void *, void *);
-void * __builtin_custom_pn (void);
-void * __builtin_custom_pni (int);
-void * __builtin_custom_pnf (float);
-void * __builtin_custom_pnp (void *);
-void * __builtin_custom_pnii (int, int);
-void * __builtin_custom_pnif (int, float);
-void * __builtin_custom_pnip (int, void *);
-void * __builtin_custom_pnfi (float, int);
-void * __builtin_custom_pnff (float, float);
-void * __builtin_custom_pnfp (float, void *);
-void * __builtin_custom_pnpi (void *, int);
-void * __builtin_custom_pnpf (void *, float);
-void * __builtin_custom_pnpp (void *, void *);
-@end example
-
-@node ARC Built-in Functions
-@subsection ARC Built-in Functions
-
-The following built-in functions are provided for ARC targets. The
-built-ins generate the corresponding assembly instructions. In the
-examples given below, the generated code often requires an operand or
-result to be in a register. Where necessary further code will be
-generated to ensure this is true, but for brevity this is not
-described in each case.
-
-@emph{Note:} Using a built-in to generate an instruction not supported
-by a target may cause problems. At present the compiler is not
-guaranteed to detect such misuse, and as a result an internal compiler
-error may be generated.
-
-@deftypefn {Built-in Function} int __builtin_arc_aligned (void *@var{val}, int @var{alignval})
-Return 1 if @var{val} is known to have the byte alignment given
-by @var{alignval}, otherwise return 0.
-Note that this is different from
-@smallexample
-__alignof__(*(char *)@var{val}) >= alignval
-@end smallexample
-because __alignof__ sees only the type of the dereference, whereas
-__builtin_arc_align uses alignment information from the pointer
-as well as from the pointed-to type.
-The information available will depend on optimization level.
-@end deftypefn
-
-@deftypefn {Built-in Function} void __builtin_arc_brk (void)
-Generates
-@example
-brk
-@end example
-@end deftypefn
-
-@deftypefn {Built-in Function} {unsigned int} __builtin_arc_core_read (unsigned int @var{regno})
-The operand is the number of a register to be read. Generates:
-@example
-mov @var{dest}, r@var{regno}
-@end example
-where the value in @var{dest} will be the result returned from the
-built-in.
-@end deftypefn
-
-@deftypefn {Built-in Function} void __builtin_arc_core_write (unsigned int @var{regno}, unsigned int @var{val})
-The first operand is the number of a register to be written, the
-second operand is a compile time constant to write into that
-register. Generates:
-@example
-mov r@var{regno}, @var{val}
-@end example
-@end deftypefn
-
-@deftypefn {Built-in Function} int __builtin_arc_divaw (int @var{a}, int @var{b})
-Only available if either @option{-mcpu=ARC700} or @option{-meA} is set.
-Generates:
-@example
-divaw @var{dest}, @var{a}, @var{b}
-@end example
-where the value in @var{dest} will be the result returned from the
-built-in.
-@end deftypefn
-
-@deftypefn {Built-in Function} void __builtin_arc_flag (unsigned int @var{a})
-Generates
-@example
-flag @var{a}
-@end example
-@end deftypefn
-
-@deftypefn {Built-in Function} {unsigned int} __builtin_arc_lr (unsigned int @var{auxr})
-The operand, @var{auxv}, is the address of an auxiliary register and
-must be a compile time constant. Generates:
-@example
-lr @var{dest}, [@var{auxr}]
-@end example
-Where the value in @var{dest} will be the result returned from the
-built-in.
-@end deftypefn
-
-@deftypefn {Built-in Function} void __builtin_arc_mul64 (int @var{a}, int @var{b})
-Only available with @option{-mmul64}. Generates:
-@example
-mul64 @var{a}, @var{b}
-@end example
-@end deftypefn
-
-@deftypefn {Built-in Function} void __builtin_arc_mulu64 (unsigned int @var{a}, unsigned int @var{b})
-Only available with @option{-mmul64}. Generates:
-@example
-mulu64 @var{a}, @var{b}
-@end example
-@end deftypefn
-
-@deftypefn {Built-in Function} void __builtin_arc_nop (void)
-Generates:
-@example
-nop
-@end example
-@end deftypefn
-
-@deftypefn {Built-in Function} int __builtin_arc_norm (int @var{src})
-Only valid if the @samp{norm} instruction is available through the
-@option{-mnorm} option or by default with @option{-mcpu=ARC700}.
-Generates:
-@example
-norm @var{dest}, @var{src}
-@end example
-Where the value in @var{dest} will be the result returned from the
-built-in.
-@end deftypefn
-
-@deftypefn {Built-in Function} {short int} __builtin_arc_normw (short int @var{src})
-Only valid if the @samp{normw} instruction is available through the
-@option{-mnorm} option or by default with @option{-mcpu=ARC700}.
-Generates:
-@example
-normw @var{dest}, @var{src}
-@end example
-Where the value in @var{dest} will be the result returned from the
-built-in.
-@end deftypefn
-
-@deftypefn {Built-in Function} void __builtin_arc_rtie (void)
-Generates:
-@example
-rtie
-@end example
-@end deftypefn
-
-@deftypefn {Built-in Function} void __builtin_arc_sleep (int @var{a}
-Generates:
-@example
-sleep @var{a}
-@end example
-@end deftypefn
-
-@deftypefn {Built-in Function} void __builtin_arc_sr (unsigned int @var{val}, unsigned int @var{auxr})
-The first argument, @var{val}, is a compile time constant to be
-written to the register, the second argument, @var{auxr}, is the
-address of an auxiliary register. Generates:
-@example
-sr @var{val}, [@var{auxr}]
-@end example
-@end deftypefn
-
-@deftypefn {Built-in Function} int __builtin_arc_swap (int @var{src})
-Only valid with @option{-mswap}. Generates:
-@example
-swap @var{dest}, @var{src}
-@end example
-Where the value in @var{dest} will be the result returned from the
-built-in.
-@end deftypefn
-
-@deftypefn {Built-in Function} void __builtin_arc_swi (void)
-Generates:
-@example
-swi
-@end example
-@end deftypefn
-
-@deftypefn {Built-in Function} void __builtin_arc_sync (void)
-Only available with @option{-mcpu=ARC700}. Generates:
-@example
-sync
-@end example
-@end deftypefn
-
-@deftypefn {Built-in Function} void __builtin_arc_trap_s (unsigned int @var{c})
-Only available with @option{-mcpu=ARC700}. Generates:
-@example
-trap_s @var{c}
-@end example
-@end deftypefn
-
-@deftypefn {Built-in Function} void __builtin_arc_unimp_s (void)
-Only available with @option{-mcpu=ARC700}. Generates:
-@example
-unimp_s
-@end example
-@end deftypefn
-
-The instructions generated by the following builtins are not
-considered as candidates for scheduling. They are not moved around by
-the compiler during scheduling, and thus can be expected to appear
-where they are put in the C code:
-@example
-__builtin_arc_brk()
-__builtin_arc_core_read()
-__builtin_arc_core_write()
-__builtin_arc_flag()
-__builtin_arc_lr()
-__builtin_arc_sleep()
-__builtin_arc_sr()
-__builtin_arc_swi()
-@end example
-
-@node ARC SIMD Built-in Functions
-@subsection ARC SIMD Built-in Functions
-
-SIMD builtins provided by the compiler can be used to generate the
-vector instructions. This section describes the available builtins
-and their usage in programs. With the @option{-msimd} option, the
-compiler provides 128-bit vector types, which can be specified using
-the @code{vector_size} attribute. The header file @file{arc-simd.h}
-can be included to use the following predefined types:
-@example
-typedef int __v4si __attribute__((vector_size(16)));
-typedef short __v8hi __attribute__((vector_size(16)));
-@end example
-
-These types can be used to define 128-bit variables. The built-in
-functions listed in the following section can be used on these
-variables to generate the vector operations.
-
-For all builtins, @code{__builtin_arc_@var{someinsn}}, the header file
-@file{arc-simd.h} also provides equivalent macros called
-@code{_@var{someinsn}} that can be used for programming ease and
-improved readability. The following macros for DMA control are also
-provided:
-@example
-#define _setup_dma_in_channel_reg _vdiwr
-#define _setup_dma_out_channel_reg _vdowr
-@end example
-
-The following is a complete list of all the SIMD built-ins provided
-for ARC, grouped by calling signature.
-
-The following take two @code{__v8hi} arguments and return a
-@code{__v8hi} result:
-@example
-__v8hi __builtin_arc_vaddaw (__v8hi, __v8hi);
-__v8hi __builtin_arc_vaddw (__v8hi, __v8hi);
-__v8hi __builtin_arc_vand (__v8hi, __v8hi);
-__v8hi __builtin_arc_vandaw (__v8hi, __v8hi);
-__v8hi __builtin_arc_vavb (__v8hi, __v8hi);
-__v8hi __builtin_arc_vavrb (__v8hi, __v8hi);
-__v8hi __builtin_arc_vbic (__v8hi, __v8hi);
-__v8hi __builtin_arc_vbicaw (__v8hi, __v8hi);
-__v8hi __builtin_arc_vdifaw (__v8hi, __v8hi);
-__v8hi __builtin_arc_vdifw (__v8hi, __v8hi);
-__v8hi __builtin_arc_veqw (__v8hi, __v8hi);
-__v8hi __builtin_arc_vh264f (__v8hi, __v8hi);
-__v8hi __builtin_arc_vh264ft (__v8hi, __v8hi);
-__v8hi __builtin_arc_vh264fw (__v8hi, __v8hi);
-__v8hi __builtin_arc_vlew (__v8hi, __v8hi);
-__v8hi __builtin_arc_vltw (__v8hi, __v8hi);
-__v8hi __builtin_arc_vmaxaw (__v8hi, __v8hi);
-__v8hi __builtin_arc_vmaxw (__v8hi, __v8hi);
-__v8hi __builtin_arc_vminaw (__v8hi, __v8hi);
-__v8hi __builtin_arc_vminw (__v8hi, __v8hi);
-__v8hi __builtin_arc_vmr1aw (__v8hi, __v8hi);
-__v8hi __builtin_arc_vmr1w (__v8hi, __v8hi);
-__v8hi __builtin_arc_vmr2aw (__v8hi, __v8hi);
-__v8hi __builtin_arc_vmr2w (__v8hi, __v8hi);
-__v8hi __builtin_arc_vmr3aw (__v8hi, __v8hi);
-__v8hi __builtin_arc_vmr3w (__v8hi, __v8hi);
-__v8hi __builtin_arc_vmr4aw (__v8hi, __v8hi);
-__v8hi __builtin_arc_vmr4w (__v8hi, __v8hi);
-__v8hi __builtin_arc_vmr5aw (__v8hi, __v8hi);
-__v8hi __builtin_arc_vmr5w (__v8hi, __v8hi);
-__v8hi __builtin_arc_vmr6aw (__v8hi, __v8hi);
-__v8hi __builtin_arc_vmr6w (__v8hi, __v8hi);
-__v8hi __builtin_arc_vmr7aw (__v8hi, __v8hi);
-__v8hi __builtin_arc_vmr7w (__v8hi, __v8hi);
-__v8hi __builtin_arc_vmrb (__v8hi, __v8hi);
-__v8hi __builtin_arc_vmulaw (__v8hi, __v8hi);
-__v8hi __builtin_arc_vmulfaw (__v8hi, __v8hi);
-__v8hi __builtin_arc_vmulfw (__v8hi, __v8hi);
-__v8hi __builtin_arc_vmulw (__v8hi, __v8hi);
-__v8hi __builtin_arc_vnew (__v8hi, __v8hi);
-__v8hi __builtin_arc_vor (__v8hi, __v8hi);
-__v8hi __builtin_arc_vsubaw (__v8hi, __v8hi);
-__v8hi __builtin_arc_vsubw (__v8hi, __v8hi);
-__v8hi __builtin_arc_vsummw (__v8hi, __v8hi);
-__v8hi __builtin_arc_vvc1f (__v8hi, __v8hi);
-__v8hi __builtin_arc_vvc1ft (__v8hi, __v8hi);
-__v8hi __builtin_arc_vxor (__v8hi, __v8hi);
-__v8hi __builtin_arc_vxoraw (__v8hi, __v8hi);
-@end example
-
-The following take one @code{__v8hi} and one @code{int} argument and return a
-@code{__v8hi} result:
-
-@example
-__v8hi __builtin_arc_vbaddw (__v8hi, int);
-__v8hi __builtin_arc_vbmaxw (__v8hi, int);
-__v8hi __builtin_arc_vbminw (__v8hi, int);
-__v8hi __builtin_arc_vbmulaw (__v8hi, int);
-__v8hi __builtin_arc_vbmulfw (__v8hi, int);
-__v8hi __builtin_arc_vbmulw (__v8hi, int);
-__v8hi __builtin_arc_vbrsubw (__v8hi, int);
-__v8hi __builtin_arc_vbsubw (__v8hi, int);
-@end example
-
-The following take one @code{__v8hi} argument and one @code{int} argument which
-must be a 3-bit compile time constant indicating a register number
-I0-I7. They return a @code{__v8hi} result.
-@example
-__v8hi __builtin_arc_vasrw (__v8hi, const int);
-__v8hi __builtin_arc_vsr8 (__v8hi, const int);
-__v8hi __builtin_arc_vsr8aw (__v8hi, const int);
-@end example
-
-The following take one @code{__v8hi} argument and one @code{int}
-argument which must be a 6-bit compile time constant. They return a
-@code{__v8hi} result.
-@example
-__v8hi __builtin_arc_vasrpwbi (__v8hi, const int);
-__v8hi __builtin_arc_vasrrpwbi (__v8hi, const int);
-__v8hi __builtin_arc_vasrrwi (__v8hi, const int);
-__v8hi __builtin_arc_vasrsrwi (__v8hi, const int);
-__v8hi __builtin_arc_vasrwi (__v8hi, const int);
-__v8hi __builtin_arc_vsr8awi (__v8hi, const int);
-__v8hi __builtin_arc_vsr8i (__v8hi, const int);
-@end example
-
-The following take one @code{__v8hi} argument and one @code{int} argument which
-must be a 8-bit compile time constant. They return a @code{__v8hi}
-result.
-@example
-__v8hi __builtin_arc_vd6tapf (__v8hi, const int);
-__v8hi __builtin_arc_vmvaw (__v8hi, const int);
-__v8hi __builtin_arc_vmvw (__v8hi, const int);
-__v8hi __builtin_arc_vmvzw (__v8hi, const int);
-@end example
-
-The following take two @code{int} arguments, the second of which which
-must be a 8-bit compile time constant. They return a @code{__v8hi}
-result:
-@example
-__v8hi __builtin_arc_vmovaw (int, const int);
-__v8hi __builtin_arc_vmovw (int, const int);
-__v8hi __builtin_arc_vmovzw (int, const int);
-@end example
-
-The following take a single @code{__v8hi} argument and return a
-@code{__v8hi} result:
-@example
-__v8hi __builtin_arc_vabsaw (__v8hi);
-__v8hi __builtin_arc_vabsw (__v8hi);
-__v8hi __builtin_arc_vaddsuw (__v8hi);
-__v8hi __builtin_arc_vexch1 (__v8hi);
-__v8hi __builtin_arc_vexch2 (__v8hi);
-__v8hi __builtin_arc_vexch4 (__v8hi);
-__v8hi __builtin_arc_vsignw (__v8hi);
-__v8hi __builtin_arc_vupbaw (__v8hi);
-__v8hi __builtin_arc_vupbw (__v8hi);
-__v8hi __builtin_arc_vupsbaw (__v8hi);
-__v8hi __builtin_arc_vupsbw (__v8hi);
-@end example
-
-The following take two @code{int} arguments and return no result:
-@example
-void __builtin_arc_vdirun (int, int);
-void __builtin_arc_vdorun (int, int);
-@end example
-
-The following take two @code{int} arguments and return no result. The
-first argument must a 3-bit compile time constant indicating one of
-the DR0-DR7 DMA setup channels:
-@example
-void __builtin_arc_vdiwr (const int, int);
-void __builtin_arc_vdowr (const int, int);
-@end example
-
-The following take an @code{int} argument and return no result:
-@example
-void __builtin_arc_vendrec (int);
-void __builtin_arc_vrec (int);
-void __builtin_arc_vrecrun (int);
-void __builtin_arc_vrun (int);
-@end example
-
-The following take a @code{__v8hi} argument and two @code{int}
-arguments and return a @code{__v8hi} result. The second argument must
-be a 3-bit compile time constants, indicating one the registers I0-I7,
-and the third argument must be an 8-bit compile time constant.
-
-@emph{Note:} Although the equivalent hardware instructions do not take
-an SIMD register as an operand, these builtins overwrite the relevant
-bits of the @code{__v8hi} register provided as the first argument with
-the value loaded from the @code{[Ib, u8]} location in the SDM.
-
-@example
-__v8hi __builtin_arc_vld32 (__v8hi, const int, const int);
-__v8hi __builtin_arc_vld32wh (__v8hi, const int, const int);
-__v8hi __builtin_arc_vld32wl (__v8hi, const int, const int);
-__v8hi __builtin_arc_vld64 (__v8hi, const int, const int);
-@end example
-
-The following take two @code{int} arguments and return a @code{__v8hi}
-result. The first argument must be a 3-bit compile time constants,
-indicating one the registers I0-I7, and the second argument must be an
-8-bit compile time constant.
-
-@example
-__v8hi __builtin_arc_vld128 (const int, const int);
-__v8hi __builtin_arc_vld64w (const int, const int);
-@end example
-
-The following take a @code{__v8hi} argument and two @code{int}
-arguments and return no result. The second argument must be a 3-bit
-compile time constants, indicating one the registers I0-I7, and the
-third argument must be an 8-bit compile time constant.
-
-@example
-void __builtin_arc_vst128 (__v8hi, const int, const int);
-void __builtin_arc_vst64 (__v8hi, const int, const int);
-@end example
-
-The following take a @code{__v8hi} argument and three @code{int}
-arguments and return no result. The second argument must be a 3-bit
-compile-time constant, identifying the 16-bit sub-register to be
-stored, the third argument must be a 3-bit compile time constants,
-indicating one the registers I0-I7, and the fourth argument must be an
-8-bit compile time constant.
-
-@example
-void __builtin_arc_vst16_n (__v8hi, const int, const int, const int);
-void __builtin_arc_vst32_n (__v8hi, const int, const int, const int);
-@end example
-
-@node ARM iWMMXt Built-in Functions
-@subsection ARM iWMMXt Built-in Functions
-
-These built-in functions are available for the ARM family of
-processors when the @option{-mcpu=iwmmxt} switch is used:
-
-@smallexample
-typedef int v2si __attribute__ ((vector_size (8)));
-typedef short v4hi __attribute__ ((vector_size (8)));
-typedef char v8qi __attribute__ ((vector_size (8)));
-
-int __builtin_arm_getwcgr0 (void);
-void __builtin_arm_setwcgr0 (int);
-int __builtin_arm_getwcgr1 (void);
-void __builtin_arm_setwcgr1 (int);
-int __builtin_arm_getwcgr2 (void);
-void __builtin_arm_setwcgr2 (int);
-int __builtin_arm_getwcgr3 (void);
-void __builtin_arm_setwcgr3 (int);
-int __builtin_arm_textrmsb (v8qi, int);
-int __builtin_arm_textrmsh (v4hi, int);
-int __builtin_arm_textrmsw (v2si, int);
-int __builtin_arm_textrmub (v8qi, int);
-int __builtin_arm_textrmuh (v4hi, int);
-int __builtin_arm_textrmuw (v2si, int);
-v8qi __builtin_arm_tinsrb (v8qi, int, int);
-v4hi __builtin_arm_tinsrh (v4hi, int, int);
-v2si __builtin_arm_tinsrw (v2si, int, int);
-long long __builtin_arm_tmia (long long, int, int);
-long long __builtin_arm_tmiabb (long long, int, int);
-long long __builtin_arm_tmiabt (long long, int, int);
-long long __builtin_arm_tmiaph (long long, int, int);
-long long __builtin_arm_tmiatb (long long, int, int);
-long long __builtin_arm_tmiatt (long long, int, int);
-int __builtin_arm_tmovmskb (v8qi);
-int __builtin_arm_tmovmskh (v4hi);
-int __builtin_arm_tmovmskw (v2si);
-long long __builtin_arm_waccb (v8qi);
-long long __builtin_arm_wacch (v4hi);
-long long __builtin_arm_waccw (v2si);
-v8qi __builtin_arm_waddb (v8qi, v8qi);
-v8qi __builtin_arm_waddbss (v8qi, v8qi);
-v8qi __builtin_arm_waddbus (v8qi, v8qi);
-v4hi __builtin_arm_waddh (v4hi, v4hi);
-v4hi __builtin_arm_waddhss (v4hi, v4hi);
-v4hi __builtin_arm_waddhus (v4hi, v4hi);
-v2si __builtin_arm_waddw (v2si, v2si);
-v2si __builtin_arm_waddwss (v2si, v2si);
-v2si __builtin_arm_waddwus (v2si, v2si);
-v8qi __builtin_arm_walign (v8qi, v8qi, int);
-long long __builtin_arm_wand(long long, long long);
-long long __builtin_arm_wandn (long long, long long);
-v8qi __builtin_arm_wavg2b (v8qi, v8qi);
-v8qi __builtin_arm_wavg2br (v8qi, v8qi);
-v4hi __builtin_arm_wavg2h (v4hi, v4hi);
-v4hi __builtin_arm_wavg2hr (v4hi, v4hi);
-v8qi __builtin_arm_wcmpeqb (v8qi, v8qi);
-v4hi __builtin_arm_wcmpeqh (v4hi, v4hi);
-v2si __builtin_arm_wcmpeqw (v2si, v2si);
-v8qi __builtin_arm_wcmpgtsb (v8qi, v8qi);
-v4hi __builtin_arm_wcmpgtsh (v4hi, v4hi);
-v2si __builtin_arm_wcmpgtsw (v2si, v2si);
-v8qi __builtin_arm_wcmpgtub (v8qi, v8qi);
-v4hi __builtin_arm_wcmpgtuh (v4hi, v4hi);
-v2si __builtin_arm_wcmpgtuw (v2si, v2si);
-long long __builtin_arm_wmacs (long long, v4hi, v4hi);
-long long __builtin_arm_wmacsz (v4hi, v4hi);
-long long __builtin_arm_wmacu (long long, v4hi, v4hi);
-long long __builtin_arm_wmacuz (v4hi, v4hi);
-v4hi __builtin_arm_wmadds (v4hi, v4hi);
-v4hi __builtin_arm_wmaddu (v4hi, v4hi);
-v8qi __builtin_arm_wmaxsb (v8qi, v8qi);
-v4hi __builtin_arm_wmaxsh (v4hi, v4hi);
-v2si __builtin_arm_wmaxsw (v2si, v2si);
-v8qi __builtin_arm_wmaxub (v8qi, v8qi);
-v4hi __builtin_arm_wmaxuh (v4hi, v4hi);
-v2si __builtin_arm_wmaxuw (v2si, v2si);
-v8qi __builtin_arm_wminsb (v8qi, v8qi);
-v4hi __builtin_arm_wminsh (v4hi, v4hi);
-v2si __builtin_arm_wminsw (v2si, v2si);
-v8qi __builtin_arm_wminub (v8qi, v8qi);
-v4hi __builtin_arm_wminuh (v4hi, v4hi);
-v2si __builtin_arm_wminuw (v2si, v2si);
-v4hi __builtin_arm_wmulsm (v4hi, v4hi);
-v4hi __builtin_arm_wmulul (v4hi, v4hi);
-v4hi __builtin_arm_wmulum (v4hi, v4hi);
-long long __builtin_arm_wor (long long, long long);
-v2si __builtin_arm_wpackdss (long long, long long);
-v2si __builtin_arm_wpackdus (long long, long long);
-v8qi __builtin_arm_wpackhss (v4hi, v4hi);
-v8qi __builtin_arm_wpackhus (v4hi, v4hi);
-v4hi __builtin_arm_wpackwss (v2si, v2si);
-v4hi __builtin_arm_wpackwus (v2si, v2si);
-long long __builtin_arm_wrord (long long, long long);
-long long __builtin_arm_wrordi (long long, int);
-v4hi __builtin_arm_wrorh (v4hi, long long);
-v4hi __builtin_arm_wrorhi (v4hi, int);
-v2si __builtin_arm_wrorw (v2si, long long);
-v2si __builtin_arm_wrorwi (v2si, int);
-v2si __builtin_arm_wsadb (v2si, v8qi, v8qi);
-v2si __builtin_arm_wsadbz (v8qi, v8qi);
-v2si __builtin_arm_wsadh (v2si, v4hi, v4hi);
-v2si __builtin_arm_wsadhz (v4hi, v4hi);
-v4hi __builtin_arm_wshufh (v4hi, int);
-long long __builtin_arm_wslld (long long, long long);
-long long __builtin_arm_wslldi (long long, int);
-v4hi __builtin_arm_wsllh (v4hi, long long);
-v4hi __builtin_arm_wsllhi (v4hi, int);
-v2si __builtin_arm_wsllw (v2si, long long);
-v2si __builtin_arm_wsllwi (v2si, int);
-long long __builtin_arm_wsrad (long long, long long);
-long long __builtin_arm_wsradi (long long, int);
-v4hi __builtin_arm_wsrah (v4hi, long long);
-v4hi __builtin_arm_wsrahi (v4hi, int);
-v2si __builtin_arm_wsraw (v2si, long long);
-v2si __builtin_arm_wsrawi (v2si, int);
-long long __builtin_arm_wsrld (long long, long long);
-long long __builtin_arm_wsrldi (long long, int);
-v4hi __builtin_arm_wsrlh (v4hi, long long);
-v4hi __builtin_arm_wsrlhi (v4hi, int);
-v2si __builtin_arm_wsrlw (v2si, long long);
-v2si __builtin_arm_wsrlwi (v2si, int);
-v8qi __builtin_arm_wsubb (v8qi, v8qi);
-v8qi __builtin_arm_wsubbss (v8qi, v8qi);
-v8qi __builtin_arm_wsubbus (v8qi, v8qi);
-v4hi __builtin_arm_wsubh (v4hi, v4hi);
-v4hi __builtin_arm_wsubhss (v4hi, v4hi);
-v4hi __builtin_arm_wsubhus (v4hi, v4hi);
-v2si __builtin_arm_wsubw (v2si, v2si);
-v2si __builtin_arm_wsubwss (v2si, v2si);
-v2si __builtin_arm_wsubwus (v2si, v2si);
-v4hi __builtin_arm_wunpckehsb (v8qi);
-v2si __builtin_arm_wunpckehsh (v4hi);
-long long __builtin_arm_wunpckehsw (v2si);
-v4hi __builtin_arm_wunpckehub (v8qi);
-v2si __builtin_arm_wunpckehuh (v4hi);
-long long __builtin_arm_wunpckehuw (v2si);
-v4hi __builtin_arm_wunpckelsb (v8qi);
-v2si __builtin_arm_wunpckelsh (v4hi);
-long long __builtin_arm_wunpckelsw (v2si);
-v4hi __builtin_arm_wunpckelub (v8qi);
-v2si __builtin_arm_wunpckeluh (v4hi);
-long long __builtin_arm_wunpckeluw (v2si);
-v8qi __builtin_arm_wunpckihb (v8qi, v8qi);
-v4hi __builtin_arm_wunpckihh (v4hi, v4hi);
-v2si __builtin_arm_wunpckihw (v2si, v2si);
-v8qi __builtin_arm_wunpckilb (v8qi, v8qi);
-v4hi __builtin_arm_wunpckilh (v4hi, v4hi);
-v2si __builtin_arm_wunpckilw (v2si, v2si);
-long long __builtin_arm_wxor (long long, long long);
-long long __builtin_arm_wzero ();
-@end smallexample
-
-
-@node ARM C Language Extensions (ACLE)
-@subsection ARM C Language Extensions (ACLE)
-
-GCC implements extensions for C as described in the ARM C Language
-Extensions (ACLE) specification, which can be found at
-@uref{https://developer.arm.com/documentation/ihi0053/latest/}.
-
-As a part of ACLE, GCC implements extensions for Advanced SIMD as described in
-the ARM C Language Extensions Specification. The complete list of Advanced SIMD
-intrinsics can be found at
-@uref{https://developer.arm.com/documentation/ihi0073/latest/}.
-The built-in intrinsics for the Advanced SIMD extension are available when
-NEON is enabled.
-
-Currently, ARM and AArch64 back ends do not support ACLE 2.0 fully. Both
-back ends support CRC32 intrinsics and the ARM back end supports the
-Coprocessor intrinsics, all from @file{arm_acle.h}. The ARM back end's 16-bit
-floating-point Advanced SIMD intrinsics currently comply to ACLE v1.1.
-AArch64's back end does not have support for 16-bit floating point Advanced SIMD
-intrinsics yet.
-
-See @ref{ARM Options} and @ref{AArch64 Options} for more information on the
-availability of extensions.
-
-@node ARM Floating Point Status and Control Intrinsics
-@subsection ARM Floating Point Status and Control Intrinsics
-
-These built-in functions are available for the ARM family of
-processors with floating-point unit.
-
-@smallexample
-unsigned int __builtin_arm_get_fpscr ();
-void __builtin_arm_set_fpscr (unsigned int);
-@end smallexample
-
-@node ARM ARMv8-M Security Extensions
-@subsection ARM ARMv8-M Security Extensions
-
-GCC implements the ARMv8-M Security Extensions as described in the ARMv8-M
-Security Extensions: Requirements on Development Tools Engineering
-Specification, which can be found at
-@uref{https://developer.arm.com/documentation/ecm0359818/latest/}.
-
-As part of the Security Extensions GCC implements two new function attributes:
-@code{cmse_nonsecure_entry} and @code{cmse_nonsecure_call}.
-
-As part of the Security Extensions GCC implements the intrinsics below. FPTR
-is used here to mean any function pointer type.
-
-@smallexample
-cmse_address_info_t cmse_TT (void *);
-cmse_address_info_t cmse_TT_fptr (FPTR);
-cmse_address_info_t cmse_TTT (void *);
-cmse_address_info_t cmse_TTT_fptr (FPTR);
-cmse_address_info_t cmse_TTA (void *);
-cmse_address_info_t cmse_TTA_fptr (FPTR);
-cmse_address_info_t cmse_TTAT (void *);
-cmse_address_info_t cmse_TTAT_fptr (FPTR);
-void * cmse_check_address_range (void *, size_t, int);
-typeof(p) cmse_nsfptr_create (FPTR p);
-intptr_t cmse_is_nsfptr (FPTR);
-int cmse_nonsecure_caller (void);
-@end smallexample
-
-@node AVR Built-in Functions
-@subsection AVR Built-in Functions
-
-For each built-in function for AVR, there is an equally named,
-uppercase built-in macro defined. That way users can easily query if
-or if not a specific built-in is implemented or not. For example, if
-@code{__builtin_avr_nop} is available the macro
-@code{__BUILTIN_AVR_NOP} is defined to @code{1} and undefined otherwise.
-
-@table @code
-
-@item void __builtin_avr_nop (void)
-@itemx void __builtin_avr_sei (void)
-@itemx void __builtin_avr_cli (void)
-@itemx void __builtin_avr_sleep (void)
-@itemx void __builtin_avr_wdr (void)
-@itemx unsigned char __builtin_avr_swap (unsigned char)
-@itemx unsigned int __builtin_avr_fmul (unsigned char, unsigned char)
-@itemx int __builtin_avr_fmuls (char, char)
-@itemx int __builtin_avr_fmulsu (char, unsigned char)
-These built-in functions map to the respective machine
-instruction, i.e.@: @code{nop}, @code{sei}, @code{cli}, @code{sleep},
-@code{wdr}, @code{swap}, @code{fmul}, @code{fmuls}
-resp. @code{fmulsu}. The three @code{fmul*} built-ins are implemented
-as library call if no hardware multiplier is available.
-
-@item void __builtin_avr_delay_cycles (unsigned long ticks)
-Delay execution for @var{ticks} cycles. Note that this
-built-in does not take into account the effect of interrupts that
-might increase delay time. @var{ticks} must be a compile-time
-integer constant; delays with a variable number of cycles are not supported.
-
-@item char __builtin_avr_flash_segment (const __memx void*)
-This built-in takes a byte address to the 24-bit
-@ref{AVR Named Address Spaces,address space} @code{__memx} and returns
-the number of the flash segment (the 64 KiB chunk) where the address
-points to. Counting starts at @code{0}.
-If the address does not point to flash memory, return @code{-1}.
-
-@item uint8_t __builtin_avr_insert_bits (uint32_t map, uint8_t bits, uint8_t val)
-Insert bits from @var{bits} into @var{val} and return the resulting
-value. The nibbles of @var{map} determine how the insertion is
-performed: Let @var{X} be the @var{n}-th nibble of @var{map}
-@enumerate
-@item If @var{X} is @code{0xf},
-then the @var{n}-th bit of @var{val} is returned unaltered.
-
-@item If X is in the range 0@dots{}7,
-then the @var{n}-th result bit is set to the @var{X}-th bit of @var{bits}
-
-@item If X is in the range 8@dots{}@code{0xe},
-then the @var{n}-th result bit is undefined.
-@end enumerate
-
-@noindent
-One typical use case for this built-in is adjusting input and
-output values to non-contiguous port layouts. Some examples:
-
-@smallexample
-// same as val, bits is unused
-__builtin_avr_insert_bits (0xffffffff, bits, val);
-@end smallexample
-
-@smallexample
-// same as bits, val is unused
-__builtin_avr_insert_bits (0x76543210, bits, val);
-@end smallexample
-
-@smallexample
-// same as rotating bits by 4
-__builtin_avr_insert_bits (0x32107654, bits, 0);
-@end smallexample
-
-@smallexample
-// high nibble of result is the high nibble of val
-// low nibble of result is the low nibble of bits
-__builtin_avr_insert_bits (0xffff3210, bits, val);
-@end smallexample
-
-@smallexample
-// reverse the bit order of bits
-__builtin_avr_insert_bits (0x01234567, bits, 0);
-@end smallexample
-
-@item void __builtin_avr_nops (unsigned count)
-Insert @var{count} @code{NOP} instructions.
-The number of instructions must be a compile-time integer constant.
-
-@end table
-
-@noindent
-There are many more AVR-specific built-in functions that are used to
-implement the ISO/IEC TR 18037 ``Embedded C'' fixed-point functions of
-section 7.18a.6. You don't need to use these built-ins directly.
-Instead, use the declarations as supplied by the @code{stdfix.h} header
-with GNU-C99:
-
-@smallexample
-#include <stdfix.h>
-
-// Re-interpret the bit representation of unsigned 16-bit
-// integer @var{uval} as Q-format 0.16 value.
-unsigned fract get_bits (uint_ur_t uval)
-@{
- return urbits (uval);
-@}
-@end smallexample
-
-@node Blackfin Built-in Functions
-@subsection Blackfin Built-in Functions
-
-Currently, there are two Blackfin-specific built-in functions. These are
-used for generating @code{CSYNC} and @code{SSYNC} machine insns without
-using inline assembly; by using these built-in functions the compiler can
-automatically add workarounds for hardware errata involving these
-instructions. These functions are named as follows:
-
-@smallexample
-void __builtin_bfin_csync (void);
-void __builtin_bfin_ssync (void);
-@end smallexample
-
-@node BPF Built-in Functions
-@subsection BPF Built-in Functions
-
-The following built-in functions are available for eBPF targets.
-
-@deftypefn {Built-in Function} unsigned long long __builtin_bpf_load_byte (unsigned long long @var{offset})
-Load a byte from the @code{struct sk_buff} packet data pointed by the register @code{%r6} and return it.
-@end deftypefn
-
-@deftypefn {Built-in Function} unsigned long long __builtin_bpf_load_half (unsigned long long @var{offset})
-Load 16-bits from the @code{struct sk_buff} packet data pointed by the register @code{%r6} and return it.
-@end deftypefn
-
-@deftypefn {Built-in Function} unsigned long long __builtin_bpf_load_word (unsigned long long @var{offset})
-Load 32-bits from the @code{struct sk_buff} packet data pointed by the register @code{%r6} and return it.
-@end deftypefn
-
-@deftypefn {Built-in Function} void * __builtin_preserve_access_index (@var{expr})
-BPF Compile Once-Run Everywhere (CO-RE) support. Instruct GCC to generate CO-RE relocation records for any accesses to aggregate data structures (struct, union, array types) in @var{expr}. This builtin is otherwise transparent, the return value is whatever @var{expr} evaluates to. It is also overloaded: @var{expr} may be of any type (not necessarily a pointer), the return type is the same. Has no effect if @code{-mco-re} is not in effect (either specified or implied).
-@end deftypefn
-
-@deftypefn {Built-in Function} unsigned int __builtin_preserve_field_info (@var{expr}, unsigned int @var{kind})
-BPF Compile Once-Run Everywhere (CO-RE) support. This builtin is used to
-extract information to aid in struct/union relocations. @var{expr} is
-an access to a field of a struct or union. Depending on @var{kind}, different
-information is returned to the program. A CO-RE relocation for the access in
-@var{expr} with kind @var{kind} is recorded if @code{-mco-re} is in effect.
-
-The following values are supported for @var{kind}:
-@table @var
-@item FIELD_BYTE_OFFSET = 0
-The returned value is the offset, in bytes, of the field from the
-beginning of the containing structure. For bitfields, the byte offset
-of the containing word.
-
-@item FIELD_BYTE_SIZE = 1
-The returned value is the size, in bytes, of the field. For bitfields,
-the size in bytes of the containing word.
-
-@item FIELD_EXISTENCE = 2
-The returned value is 1 if the field exists, 0 otherwise. Always 1 at
-compile time.
-
-@item FIELD_SIGNEDNESS = 3
-The returned value is 1 if the field is signed, 0 otherwise.
-
-@item FIELD_LSHIFT_U64 = 4
-@itemx FIELD_RSHIFT_U64 = 5
-The returned value is the number of bits of left- or right-shifting
-respectively needed in order to recover the original value of the field,
-after it has been loaded by a read of FIELD_BYTE_SIZE bytes into an
-unsigned 64-bit value. Primarily useful for reading bitfield values
-from structures which may change between kernel versions.
-
-@end table
-
-Note that the return value is a constant which is known at
-compile-time. If the field has a variable offset then
-FIELD_BYTE_OFFSET, FIELD_LSHIFT_U64 and FIELD_RSHIFT_U64 are not
-supported. Similarly, if the field has a variable size then
-FIELD_BYTE_SIZE, FIELD_LSHIFT_U64 and FIELD_RSHIFT_U64 are not
-supported.
-
-For example, __builtin_preserve_field_info can be used to reliably
-extract bitfield values from a structure which may change between
-kernel versions:
-
-@example
-struct S
-@{
- short a;
- int x:7;
- int y:5;
-@};
-
-int
-read_y (struct S *arg)
-@{
- unsigned long long val;
- unsigned int offset = __builtin_preserve_field_info (arg->y, FIELD_BYTE_OFFSET);
- unsigned int size = __builtin_presrve_field_info (arg->y, FIELD_BYTE_SIZE);
-
- /* Read size bytes from arg + offset into val. */
- bpf_probe_read (&val, size, arg + offset);
-
- val <<= __builtin_preserve_field_info (arg->y, FIELD_LSHIFT_U64);
-
- if (__builtin_preserve_field_info (arg->y, FIELD_SIGNEDNESS))
- val = ((long long) val >> __builtin_preserve_field_info (arg->y, FIELD_RSHIFT_U64));
- else
- val >>= __builtin_preserve_field_info (arg->y, FIELD_RSHIFT_U64);
-
- return val;
-@}
-
-@end example
-@end deftypefn
-
-@node FR-V Built-in Functions
-@subsection FR-V Built-in Functions
-
-GCC provides many FR-V-specific built-in functions. In general,
-these functions are intended to be compatible with those described
-by @cite{FR-V Family, Softune C/C++ Compiler Manual (V6), Fujitsu
-Semiconductor}. The two exceptions are @code{__MDUNPACKH} and
-@code{__MBTOHE}, the GCC forms of which pass 128-bit values by
-pointer rather than by value.
-
-Most of the functions are named after specific FR-V instructions.
-Such functions are said to be ``directly mapped'' and are summarized
-here in tabular form.
-
-@menu
-* Argument Types::
-* Directly-mapped Integer Functions::
-* Directly-mapped Media Functions::
-* Raw read/write Functions::
-* Other Built-in Functions::
-@end menu
-
-@node Argument Types
-@subsubsection Argument Types
-
-The arguments to the built-in functions can be divided into three groups:
-register numbers, compile-time constants and run-time values. In order
-to make this classification clear at a glance, the arguments and return
-values are given the following pseudo types:
-
-@multitable @columnfractions .20 .30 .15 .35
-@headitem Pseudo type @tab Real C type @tab Constant? @tab Description
-@item @code{uh} @tab @code{unsigned short} @tab No @tab an unsigned halfword
-@item @code{uw1} @tab @code{unsigned int} @tab No @tab an unsigned word
-@item @code{sw1} @tab @code{int} @tab No @tab a signed word
-@item @code{uw2} @tab @code{unsigned long long} @tab No
-@tab an unsigned doubleword
-@item @code{sw2} @tab @code{long long} @tab No @tab a signed doubleword
-@item @code{const} @tab @code{int} @tab Yes @tab an integer constant
-@item @code{acc} @tab @code{int} @tab Yes @tab an ACC register number
-@item @code{iacc} @tab @code{int} @tab Yes @tab an IACC register number
-@end multitable
-
-These pseudo types are not defined by GCC, they are simply a notational
-convenience used in this manual.
-
-Arguments of type @code{uh}, @code{uw1}, @code{sw1}, @code{uw2}
-and @code{sw2} are evaluated at run time. They correspond to
-register operands in the underlying FR-V instructions.
-
-@code{const} arguments represent immediate operands in the underlying
-FR-V instructions. They must be compile-time constants.
-
-@code{acc} arguments are evaluated at compile time and specify the number
-of an accumulator register. For example, an @code{acc} argument of 2
-selects the ACC2 register.
-
-@code{iacc} arguments are similar to @code{acc} arguments but specify the
-number of an IACC register. See @pxref{Other Built-in Functions}
-for more details.
-
-@node Directly-mapped Integer Functions
-@subsubsection Directly-Mapped Integer Functions
-
-The functions listed below map directly to FR-V I-type instructions.
-
-@multitable @columnfractions .45 .32 .23
-@headitem Function prototype @tab Example usage @tab Assembly output
-@item @code{sw1 __ADDSS (sw1, sw1)}
-@tab @code{@var{c} = __ADDSS (@var{a}, @var{b})}
-@tab @code{ADDSS @var{a},@var{b},@var{c}}
-@item @code{sw1 __SCAN (sw1, sw1)}
-@tab @code{@var{c} = __SCAN (@var{a}, @var{b})}
-@tab @code{SCAN @var{a},@var{b},@var{c}}
-@item @code{sw1 __SCUTSS (sw1)}
-@tab @code{@var{b} = __SCUTSS (@var{a})}
-@tab @code{SCUTSS @var{a},@var{b}}
-@item @code{sw1 __SLASS (sw1, sw1)}
-@tab @code{@var{c} = __SLASS (@var{a}, @var{b})}
-@tab @code{SLASS @var{a},@var{b},@var{c}}
-@item @code{void __SMASS (sw1, sw1)}
-@tab @code{__SMASS (@var{a}, @var{b})}
-@tab @code{SMASS @var{a},@var{b}}
-@item @code{void __SMSSS (sw1, sw1)}
-@tab @code{__SMSSS (@var{a}, @var{b})}
-@tab @code{SMSSS @var{a},@var{b}}
-@item @code{void __SMU (sw1, sw1)}
-@tab @code{__SMU (@var{a}, @var{b})}
-@tab @code{SMU @var{a},@var{b}}
-@item @code{sw2 __SMUL (sw1, sw1)}
-@tab @code{@var{c} = __SMUL (@var{a}, @var{b})}
-@tab @code{SMUL @var{a},@var{b},@var{c}}
-@item @code{sw1 __SUBSS (sw1, sw1)}
-@tab @code{@var{c} = __SUBSS (@var{a}, @var{b})}
-@tab @code{SUBSS @var{a},@var{b},@var{c}}
-@item @code{uw2 __UMUL (uw1, uw1)}
-@tab @code{@var{c} = __UMUL (@var{a}, @var{b})}
-@tab @code{UMUL @var{a},@var{b},@var{c}}
-@end multitable
-
-@node Directly-mapped Media Functions
-@subsubsection Directly-Mapped Media Functions
-
-The functions listed below map directly to FR-V M-type instructions.
-
-@multitable @columnfractions .45 .32 .23
-@headitem Function prototype @tab Example usage @tab Assembly output
-@item @code{uw1 __MABSHS (sw1)}
-@tab @code{@var{b} = __MABSHS (@var{a})}
-@tab @code{MABSHS @var{a},@var{b}}
-@item @code{void __MADDACCS (acc, acc)}
-@tab @code{__MADDACCS (@var{b}, @var{a})}
-@tab @code{MADDACCS @var{a},@var{b}}
-@item @code{sw1 __MADDHSS (sw1, sw1)}
-@tab @code{@var{c} = __MADDHSS (@var{a}, @var{b})}
-@tab @code{MADDHSS @var{a},@var{b},@var{c}}
-@item @code{uw1 __MADDHUS (uw1, uw1)}
-@tab @code{@var{c} = __MADDHUS (@var{a}, @var{b})}
-@tab @code{MADDHUS @var{a},@var{b},@var{c}}
-@item @code{uw1 __MAND (uw1, uw1)}
-@tab @code{@var{c} = __MAND (@var{a}, @var{b})}
-@tab @code{MAND @var{a},@var{b},@var{c}}
-@item @code{void __MASACCS (acc, acc)}
-@tab @code{__MASACCS (@var{b}, @var{a})}
-@tab @code{MASACCS @var{a},@var{b}}
-@item @code{uw1 __MAVEH (uw1, uw1)}
-@tab @code{@var{c} = __MAVEH (@var{a}, @var{b})}
-@tab @code{MAVEH @var{a},@var{b},@var{c}}
-@item @code{uw2 __MBTOH (uw1)}
-@tab @code{@var{b} = __MBTOH (@var{a})}
-@tab @code{MBTOH @var{a},@var{b}}
-@item @code{void __MBTOHE (uw1 *, uw1)}
-@tab @code{__MBTOHE (&@var{b}, @var{a})}
-@tab @code{MBTOHE @var{a},@var{b}}
-@item @code{void __MCLRACC (acc)}
-@tab @code{__MCLRACC (@var{a})}
-@tab @code{MCLRACC @var{a}}
-@item @code{void __MCLRACCA (void)}
-@tab @code{__MCLRACCA ()}
-@tab @code{MCLRACCA}
-@item @code{uw1 __Mcop1 (uw1, uw1)}
-@tab @code{@var{c} = __Mcop1 (@var{a}, @var{b})}
-@tab @code{Mcop1 @var{a},@var{b},@var{c}}
-@item @code{uw1 __Mcop2 (uw1, uw1)}
-@tab @code{@var{c} = __Mcop2 (@var{a}, @var{b})}
-@tab @code{Mcop2 @var{a},@var{b},@var{c}}
-@item @code{uw1 __MCPLHI (uw2, const)}
-@tab @code{@var{c} = __MCPLHI (@var{a}, @var{b})}
-@tab @code{MCPLHI @var{a},#@var{b},@var{c}}
-@item @code{uw1 __MCPLI (uw2, const)}
-@tab @code{@var{c} = __MCPLI (@var{a}, @var{b})}
-@tab @code{MCPLI @var{a},#@var{b},@var{c}}
-@item @code{void __MCPXIS (acc, sw1, sw1)}
-@tab @code{__MCPXIS (@var{c}, @var{a}, @var{b})}
-@tab @code{MCPXIS @var{a},@var{b},@var{c}}
-@item @code{void __MCPXIU (acc, uw1, uw1)}
-@tab @code{__MCPXIU (@var{c}, @var{a}, @var{b})}
-@tab @code{MCPXIU @var{a},@var{b},@var{c}}
-@item @code{void __MCPXRS (acc, sw1, sw1)}
-@tab @code{__MCPXRS (@var{c}, @var{a}, @var{b})}
-@tab @code{MCPXRS @var{a},@var{b},@var{c}}
-@item @code{void __MCPXRU (acc, uw1, uw1)}
-@tab @code{__MCPXRU (@var{c}, @var{a}, @var{b})}
-@tab @code{MCPXRU @var{a},@var{b},@var{c}}
-@item @code{uw1 __MCUT (acc, uw1)}
-@tab @code{@var{c} = __MCUT (@var{a}, @var{b})}
-@tab @code{MCUT @var{a},@var{b},@var{c}}
-@item @code{uw1 __MCUTSS (acc, sw1)}
-@tab @code{@var{c} = __MCUTSS (@var{a}, @var{b})}
-@tab @code{MCUTSS @var{a},@var{b},@var{c}}
-@item @code{void __MDADDACCS (acc, acc)}
-@tab @code{__MDADDACCS (@var{b}, @var{a})}
-@tab @code{MDADDACCS @var{a},@var{b}}
-@item @code{void __MDASACCS (acc, acc)}
-@tab @code{__MDASACCS (@var{b}, @var{a})}
-@tab @code{MDASACCS @var{a},@var{b}}
-@item @code{uw2 __MDCUTSSI (acc, const)}
-@tab @code{@var{c} = __MDCUTSSI (@var{a}, @var{b})}
-@tab @code{MDCUTSSI @var{a},#@var{b},@var{c}}
-@item @code{uw2 __MDPACKH (uw2, uw2)}
-@tab @code{@var{c} = __MDPACKH (@var{a}, @var{b})}
-@tab @code{MDPACKH @var{a},@var{b},@var{c}}
-@item @code{uw2 __MDROTLI (uw2, const)}
-@tab @code{@var{c} = __MDROTLI (@var{a}, @var{b})}
-@tab @code{MDROTLI @var{a},#@var{b},@var{c}}
-@item @code{void __MDSUBACCS (acc, acc)}
-@tab @code{__MDSUBACCS (@var{b}, @var{a})}
-@tab @code{MDSUBACCS @var{a},@var{b}}
-@item @code{void __MDUNPACKH (uw1 *, uw2)}
-@tab @code{__MDUNPACKH (&@var{b}, @var{a})}
-@tab @code{MDUNPACKH @var{a},@var{b}}
-@item @code{uw2 __MEXPDHD (uw1, const)}
-@tab @code{@var{c} = __MEXPDHD (@var{a}, @var{b})}
-@tab @code{MEXPDHD @var{a},#@var{b},@var{c}}
-@item @code{uw1 __MEXPDHW (uw1, const)}
-@tab @code{@var{c} = __MEXPDHW (@var{a}, @var{b})}
-@tab @code{MEXPDHW @var{a},#@var{b},@var{c}}
-@item @code{uw1 __MHDSETH (uw1, const)}
-@tab @code{@var{c} = __MHDSETH (@var{a}, @var{b})}
-@tab @code{MHDSETH @var{a},#@var{b},@var{c}}
-@item @code{sw1 __MHDSETS (const)}
-@tab @code{@var{b} = __MHDSETS (@var{a})}
-@tab @code{MHDSETS #@var{a},@var{b}}
-@item @code{uw1 __MHSETHIH (uw1, const)}
-@tab @code{@var{b} = __MHSETHIH (@var{b}, @var{a})}
-@tab @code{MHSETHIH #@var{a},@var{b}}
-@item @code{sw1 __MHSETHIS (sw1, const)}
-@tab @code{@var{b} = __MHSETHIS (@var{b}, @var{a})}
-@tab @code{MHSETHIS #@var{a},@var{b}}
-@item @code{uw1 __MHSETLOH (uw1, const)}
-@tab @code{@var{b} = __MHSETLOH (@var{b}, @var{a})}
-@tab @code{MHSETLOH #@var{a},@var{b}}
-@item @code{sw1 __MHSETLOS (sw1, const)}
-@tab @code{@var{b} = __MHSETLOS (@var{b}, @var{a})}
-@tab @code{MHSETLOS #@var{a},@var{b}}
-@item @code{uw1 __MHTOB (uw2)}
-@tab @code{@var{b} = __MHTOB (@var{a})}
-@tab @code{MHTOB @var{a},@var{b}}
-@item @code{void __MMACHS (acc, sw1, sw1)}
-@tab @code{__MMACHS (@var{c}, @var{a}, @var{b})}
-@tab @code{MMACHS @var{a},@var{b},@var{c}}
-@item @code{void __MMACHU (acc, uw1, uw1)}
-@tab @code{__MMACHU (@var{c}, @var{a}, @var{b})}
-@tab @code{MMACHU @var{a},@var{b},@var{c}}
-@item @code{void __MMRDHS (acc, sw1, sw1)}
-@tab @code{__MMRDHS (@var{c}, @var{a}, @var{b})}
-@tab @code{MMRDHS @var{a},@var{b},@var{c}}
-@item @code{void __MMRDHU (acc, uw1, uw1)}
-@tab @code{__MMRDHU (@var{c}, @var{a}, @var{b})}
-@tab @code{MMRDHU @var{a},@var{b},@var{c}}
-@item @code{void __MMULHS (acc, sw1, sw1)}
-@tab @code{__MMULHS (@var{c}, @var{a}, @var{b})}
-@tab @code{MMULHS @var{a},@var{b},@var{c}}
-@item @code{void __MMULHU (acc, uw1, uw1)}
-@tab @code{__MMULHU (@var{c}, @var{a}, @var{b})}
-@tab @code{MMULHU @var{a},@var{b},@var{c}}
-@item @code{void __MMULXHS (acc, sw1, sw1)}
-@tab @code{__MMULXHS (@var{c}, @var{a}, @var{b})}
-@tab @code{MMULXHS @var{a},@var{b},@var{c}}
-@item @code{void __MMULXHU (acc, uw1, uw1)}
-@tab @code{__MMULXHU (@var{c}, @var{a}, @var{b})}
-@tab @code{MMULXHU @var{a},@var{b},@var{c}}
-@item @code{uw1 __MNOT (uw1)}
-@tab @code{@var{b} = __MNOT (@var{a})}
-@tab @code{MNOT @var{a},@var{b}}
-@item @code{uw1 __MOR (uw1, uw1)}
-@tab @code{@var{c} = __MOR (@var{a}, @var{b})}
-@tab @code{MOR @var{a},@var{b},@var{c}}
-@item @code{uw1 __MPACKH (uh, uh)}
-@tab @code{@var{c} = __MPACKH (@var{a}, @var{b})}
-@tab @code{MPACKH @var{a},@var{b},@var{c}}
-@item @code{sw2 __MQADDHSS (sw2, sw2)}
-@tab @code{@var{c} = __MQADDHSS (@var{a}, @var{b})}
-@tab @code{MQADDHSS @var{a},@var{b},@var{c}}
-@item @code{uw2 __MQADDHUS (uw2, uw2)}
-@tab @code{@var{c} = __MQADDHUS (@var{a}, @var{b})}
-@tab @code{MQADDHUS @var{a},@var{b},@var{c}}
-@item @code{void __MQCPXIS (acc, sw2, sw2)}
-@tab @code{__MQCPXIS (@var{c}, @var{a}, @var{b})}
-@tab @code{MQCPXIS @var{a},@var{b},@var{c}}
-@item @code{void __MQCPXIU (acc, uw2, uw2)}
-@tab @code{__MQCPXIU (@var{c}, @var{a}, @var{b})}
-@tab @code{MQCPXIU @var{a},@var{b},@var{c}}
-@item @code{void __MQCPXRS (acc, sw2, sw2)}
-@tab @code{__MQCPXRS (@var{c}, @var{a}, @var{b})}
-@tab @code{MQCPXRS @var{a},@var{b},@var{c}}
-@item @code{void __MQCPXRU (acc, uw2, uw2)}
-@tab @code{__MQCPXRU (@var{c}, @var{a}, @var{b})}
-@tab @code{MQCPXRU @var{a},@var{b},@var{c}}
-@item @code{sw2 __MQLCLRHS (sw2, sw2)}
-@tab @code{@var{c} = __MQLCLRHS (@var{a}, @var{b})}
-@tab @code{MQLCLRHS @var{a},@var{b},@var{c}}
-@item @code{sw2 __MQLMTHS (sw2, sw2)}
-@tab @code{@var{c} = __MQLMTHS (@var{a}, @var{b})}
-@tab @code{MQLMTHS @var{a},@var{b},@var{c}}
-@item @code{void __MQMACHS (acc, sw2, sw2)}
-@tab @code{__MQMACHS (@var{c}, @var{a}, @var{b})}
-@tab @code{MQMACHS @var{a},@var{b},@var{c}}
-@item @code{void __MQMACHU (acc, uw2, uw2)}
-@tab @code{__MQMACHU (@var{c}, @var{a}, @var{b})}
-@tab @code{MQMACHU @var{a},@var{b},@var{c}}
-@item @code{void __MQMACXHS (acc, sw2, sw2)}
-@tab @code{__MQMACXHS (@var{c}, @var{a}, @var{b})}
-@tab @code{MQMACXHS @var{a},@var{b},@var{c}}
-@item @code{void __MQMULHS (acc, sw2, sw2)}
-@tab @code{__MQMULHS (@var{c}, @var{a}, @var{b})}
-@tab @code{MQMULHS @var{a},@var{b},@var{c}}
-@item @code{void __MQMULHU (acc, uw2, uw2)}
-@tab @code{__MQMULHU (@var{c}, @var{a}, @var{b})}
-@tab @code{MQMULHU @var{a},@var{b},@var{c}}
-@item @code{void __MQMULXHS (acc, sw2, sw2)}
-@tab @code{__MQMULXHS (@var{c}, @var{a}, @var{b})}
-@tab @code{MQMULXHS @var{a},@var{b},@var{c}}
-@item @code{void __MQMULXHU (acc, uw2, uw2)}
-@tab @code{__MQMULXHU (@var{c}, @var{a}, @var{b})}
-@tab @code{MQMULXHU @var{a},@var{b},@var{c}}
-@item @code{sw2 __MQSATHS (sw2, sw2)}
-@tab @code{@var{c} = __MQSATHS (@var{a}, @var{b})}
-@tab @code{MQSATHS @var{a},@var{b},@var{c}}
-@item @code{uw2 __MQSLLHI (uw2, int)}
-@tab @code{@var{c} = __MQSLLHI (@var{a}, @var{b})}
-@tab @code{MQSLLHI @var{a},@var{b},@var{c}}
-@item @code{sw2 __MQSRAHI (sw2, int)}
-@tab @code{@var{c} = __MQSRAHI (@var{a}, @var{b})}
-@tab @code{MQSRAHI @var{a},@var{b},@var{c}}
-@item @code{sw2 __MQSUBHSS (sw2, sw2)}
-@tab @code{@var{c} = __MQSUBHSS (@var{a}, @var{b})}
-@tab @code{MQSUBHSS @var{a},@var{b},@var{c}}
-@item @code{uw2 __MQSUBHUS (uw2, uw2)}
-@tab @code{@var{c} = __MQSUBHUS (@var{a}, @var{b})}
-@tab @code{MQSUBHUS @var{a},@var{b},@var{c}}
-@item @code{void __MQXMACHS (acc, sw2, sw2)}
-@tab @code{__MQXMACHS (@var{c}, @var{a}, @var{b})}
-@tab @code{MQXMACHS @var{a},@var{b},@var{c}}
-@item @code{void __MQXMACXHS (acc, sw2, sw2)}
-@tab @code{__MQXMACXHS (@var{c}, @var{a}, @var{b})}
-@tab @code{MQXMACXHS @var{a},@var{b},@var{c}}
-@item @code{uw1 __MRDACC (acc)}
-@tab @code{@var{b} = __MRDACC (@var{a})}
-@tab @code{MRDACC @var{a},@var{b}}
-@item @code{uw1 __MRDACCG (acc)}
-@tab @code{@var{b} = __MRDACCG (@var{a})}
-@tab @code{MRDACCG @var{a},@var{b}}
-@item @code{uw1 __MROTLI (uw1, const)}
-@tab @code{@var{c} = __MROTLI (@var{a}, @var{b})}
-@tab @code{MROTLI @var{a},#@var{b},@var{c}}
-@item @code{uw1 __MROTRI (uw1, const)}
-@tab @code{@var{c} = __MROTRI (@var{a}, @var{b})}
-@tab @code{MROTRI @var{a},#@var{b},@var{c}}
-@item @code{sw1 __MSATHS (sw1, sw1)}
-@tab @code{@var{c} = __MSATHS (@var{a}, @var{b})}
-@tab @code{MSATHS @var{a},@var{b},@var{c}}
-@item @code{uw1 __MSATHU (uw1, uw1)}
-@tab @code{@var{c} = __MSATHU (@var{a}, @var{b})}
-@tab @code{MSATHU @var{a},@var{b},@var{c}}
-@item @code{uw1 __MSLLHI (uw1, const)}
-@tab @code{@var{c} = __MSLLHI (@var{a}, @var{b})}
-@tab @code{MSLLHI @var{a},#@var{b},@var{c}}
-@item @code{sw1 __MSRAHI (sw1, const)}
-@tab @code{@var{c} = __MSRAHI (@var{a}, @var{b})}
-@tab @code{MSRAHI @var{a},#@var{b},@var{c}}
-@item @code{uw1 __MSRLHI (uw1, const)}
-@tab @code{@var{c} = __MSRLHI (@var{a}, @var{b})}
-@tab @code{MSRLHI @var{a},#@var{b},@var{c}}
-@item @code{void __MSUBACCS (acc, acc)}
-@tab @code{__MSUBACCS (@var{b}, @var{a})}
-@tab @code{MSUBACCS @var{a},@var{b}}
-@item @code{sw1 __MSUBHSS (sw1, sw1)}
-@tab @code{@var{c} = __MSUBHSS (@var{a}, @var{b})}
-@tab @code{MSUBHSS @var{a},@var{b},@var{c}}
-@item @code{uw1 __MSUBHUS (uw1, uw1)}
-@tab @code{@var{c} = __MSUBHUS (@var{a}, @var{b})}
-@tab @code{MSUBHUS @var{a},@var{b},@var{c}}
-@item @code{void __MTRAP (void)}
-@tab @code{__MTRAP ()}
-@tab @code{MTRAP}
-@item @code{uw2 __MUNPACKH (uw1)}
-@tab @code{@var{b} = __MUNPACKH (@var{a})}
-@tab @code{MUNPACKH @var{a},@var{b}}
-@item @code{uw1 __MWCUT (uw2, uw1)}
-@tab @code{@var{c} = __MWCUT (@var{a}, @var{b})}
-@tab @code{MWCUT @var{a},@var{b},@var{c}}
-@item @code{void __MWTACC (acc, uw1)}
-@tab @code{__MWTACC (@var{b}, @var{a})}
-@tab @code{MWTACC @var{a},@var{b}}
-@item @code{void __MWTACCG (acc, uw1)}
-@tab @code{__MWTACCG (@var{b}, @var{a})}
-@tab @code{MWTACCG @var{a},@var{b}}
-@item @code{uw1 __MXOR (uw1, uw1)}
-@tab @code{@var{c} = __MXOR (@var{a}, @var{b})}
-@tab @code{MXOR @var{a},@var{b},@var{c}}
-@end multitable
-
-@node Raw read/write Functions
-@subsubsection Raw Read/Write Functions
-
-This sections describes built-in functions related to read and write
-instructions to access memory. These functions generate
-@code{membar} instructions to flush the I/O load and stores where
-appropriate, as described in Fujitsu's manual described above.
-
-@table @code
-
-@item unsigned char __builtin_read8 (void *@var{data})
-@item unsigned short __builtin_read16 (void *@var{data})
-@item unsigned long __builtin_read32 (void *@var{data})
-@item unsigned long long __builtin_read64 (void *@var{data})
-
-@item void __builtin_write8 (void *@var{data}, unsigned char @var{datum})
-@item void __builtin_write16 (void *@var{data}, unsigned short @var{datum})
-@item void __builtin_write32 (void *@var{data}, unsigned long @var{datum})
-@item void __builtin_write64 (void *@var{data}, unsigned long long @var{datum})
-@end table
-
-@node Other Built-in Functions
-@subsubsection Other Built-in Functions
-
-This section describes built-in functions that are not named after
-a specific FR-V instruction.
-
-@table @code
-@item sw2 __IACCreadll (iacc @var{reg})
-Return the full 64-bit value of IACC0@. The @var{reg} argument is reserved
-for future expansion and must be 0.
-
-@item sw1 __IACCreadl (iacc @var{reg})
-Return the value of IACC0H if @var{reg} is 0 and IACC0L if @var{reg} is 1.
-Other values of @var{reg} are rejected as invalid.
-
-@item void __IACCsetll (iacc @var{reg}, sw2 @var{x})
-Set the full 64-bit value of IACC0 to @var{x}. The @var{reg} argument
-is reserved for future expansion and must be 0.
-
-@item void __IACCsetl (iacc @var{reg}, sw1 @var{x})
-Set IACC0H to @var{x} if @var{reg} is 0 and IACC0L to @var{x} if @var{reg}
-is 1. Other values of @var{reg} are rejected as invalid.
-
-@item void __data_prefetch0 (const void *@var{x})
-Use the @code{dcpl} instruction to load the contents of address @var{x}
-into the data cache.
-
-@item void __data_prefetch (const void *@var{x})
-Use the @code{nldub} instruction to load the contents of address @var{x}
-into the data cache. The instruction is issued in slot I1@.
-@end table
-
-@node MIPS DSP Built-in Functions
-@subsection MIPS DSP Built-in Functions
-
-The MIPS DSP Application-Specific Extension (ASE) includes new
-instructions that are designed to improve the performance of DSP and
-media applications. It provides instructions that operate on packed
-8-bit/16-bit integer data, Q7, Q15 and Q31 fractional data.
-
-GCC supports MIPS DSP operations using both the generic
-vector extensions (@pxref{Vector Extensions}) and a collection of
-MIPS-specific built-in functions. Both kinds of support are
-enabled by the @option{-mdsp} command-line option.
-
-Revision 2 of the ASE was introduced in the second half of 2006.
-This revision adds extra instructions to the original ASE, but is
-otherwise backwards-compatible with it. You can select revision 2
-using the command-line option @option{-mdspr2}; this option implies
-@option{-mdsp}.
-
-The SCOUNT and POS bits of the DSP control register are global. The
-WRDSP, EXTPDP, EXTPDPV and MTHLIP instructions modify the SCOUNT and
-POS bits. During optimization, the compiler does not delete these
-instructions and it does not delete calls to functions containing
-these instructions.
-
-At present, GCC only provides support for operations on 32-bit
-vectors. The vector type associated with 8-bit integer data is
-usually called @code{v4i8}, the vector type associated with Q7
-is usually called @code{v4q7}, the vector type associated with 16-bit
-integer data is usually called @code{v2i16}, and the vector type
-associated with Q15 is usually called @code{v2q15}. They can be
-defined in C as follows:
-
-@smallexample
-typedef signed char v4i8 __attribute__ ((vector_size(4)));
-typedef signed char v4q7 __attribute__ ((vector_size(4)));
-typedef short v2i16 __attribute__ ((vector_size(4)));
-typedef short v2q15 __attribute__ ((vector_size(4)));
-@end smallexample
-
-@code{v4i8}, @code{v4q7}, @code{v2i16} and @code{v2q15} values are
-initialized in the same way as aggregates. For example:
-
-@smallexample
-v4i8 a = @{1, 2, 3, 4@};
-v4i8 b;
-b = (v4i8) @{5, 6, 7, 8@};
-
-v2q15 c = @{0x0fcb, 0x3a75@};
-v2q15 d;
-d = (v2q15) @{0.1234 * 0x1.0p15, 0.4567 * 0x1.0p15@};
-@end smallexample
-
-@emph{Note:} The CPU's endianness determines the order in which values
-are packed. On little-endian targets, the first value is the least
-significant and the last value is the most significant. The opposite
-order applies to big-endian targets. For example, the code above
-sets the lowest byte of @code{a} to @code{1} on little-endian targets
-and @code{4} on big-endian targets.
-
-@emph{Note:} Q7, Q15 and Q31 values must be initialized with their integer
-representation. As shown in this example, the integer representation
-of a Q7 value can be obtained by multiplying the fractional value by
-@code{0x1.0p7}. The equivalent for Q15 values is to multiply by
-@code{0x1.0p15}. The equivalent for Q31 values is to multiply by
-@code{0x1.0p31}.
-
-The table below lists the @code{v4i8} and @code{v2q15} operations for which
-hardware support exists. @code{a} and @code{b} are @code{v4i8} values,
-and @code{c} and @code{d} are @code{v2q15} values.
-
-@multitable @columnfractions .50 .50
-@headitem C code @tab MIPS instruction
-@item @code{a + b} @tab @code{addu.qb}
-@item @code{c + d} @tab @code{addq.ph}
-@item @code{a - b} @tab @code{subu.qb}
-@item @code{c - d} @tab @code{subq.ph}
-@end multitable
-
-The table below lists the @code{v2i16} operation for which
-hardware support exists for the DSP ASE REV 2. @code{e} and @code{f} are
-@code{v2i16} values.
-
-@multitable @columnfractions .50 .50
-@headitem C code @tab MIPS instruction
-@item @code{e * f} @tab @code{mul.ph}
-@end multitable
-
-It is easier to describe the DSP built-in functions if we first define
-the following types:
-
-@smallexample
-typedef int q31;
-typedef int i32;
-typedef unsigned int ui32;
-typedef long long a64;
-@end smallexample
-
-@code{q31} and @code{i32} are actually the same as @code{int}, but we
-use @code{q31} to indicate a Q31 fractional value and @code{i32} to
-indicate a 32-bit integer value. Similarly, @code{a64} is the same as
-@code{long long}, but we use @code{a64} to indicate values that are
-placed in one of the four DSP accumulators (@code{$ac0},
-@code{$ac1}, @code{$ac2} or @code{$ac3}).
-
-Also, some built-in functions prefer or require immediate numbers as
-parameters, because the corresponding DSP instructions accept both immediate
-numbers and register operands, or accept immediate numbers only. The
-immediate parameters are listed as follows.
-
-@smallexample
-imm0_3: 0 to 3.
-imm0_7: 0 to 7.
-imm0_15: 0 to 15.
-imm0_31: 0 to 31.
-imm0_63: 0 to 63.
-imm0_255: 0 to 255.
-imm_n32_31: -32 to 31.
-imm_n512_511: -512 to 511.
-@end smallexample
-
-The following built-in functions map directly to a particular MIPS DSP
-instruction. Please refer to the architecture specification
-for details on what each instruction does.
-
-@smallexample
-v2q15 __builtin_mips_addq_ph (v2q15, v2q15);
-v2q15 __builtin_mips_addq_s_ph (v2q15, v2q15);
-q31 __builtin_mips_addq_s_w (q31, q31);
-v4i8 __builtin_mips_addu_qb (v4i8, v4i8);
-v4i8 __builtin_mips_addu_s_qb (v4i8, v4i8);
-v2q15 __builtin_mips_subq_ph (v2q15, v2q15);
-v2q15 __builtin_mips_subq_s_ph (v2q15, v2q15);
-q31 __builtin_mips_subq_s_w (q31, q31);
-v4i8 __builtin_mips_subu_qb (v4i8, v4i8);
-v4i8 __builtin_mips_subu_s_qb (v4i8, v4i8);
-i32 __builtin_mips_addsc (i32, i32);
-i32 __builtin_mips_addwc (i32, i32);
-i32 __builtin_mips_modsub (i32, i32);
-i32 __builtin_mips_raddu_w_qb (v4i8);
-v2q15 __builtin_mips_absq_s_ph (v2q15);
-q31 __builtin_mips_absq_s_w (q31);
-v4i8 __builtin_mips_precrq_qb_ph (v2q15, v2q15);
-v2q15 __builtin_mips_precrq_ph_w (q31, q31);
-v2q15 __builtin_mips_precrq_rs_ph_w (q31, q31);
-v4i8 __builtin_mips_precrqu_s_qb_ph (v2q15, v2q15);
-q31 __builtin_mips_preceq_w_phl (v2q15);
-q31 __builtin_mips_preceq_w_phr (v2q15);
-v2q15 __builtin_mips_precequ_ph_qbl (v4i8);
-v2q15 __builtin_mips_precequ_ph_qbr (v4i8);
-v2q15 __builtin_mips_precequ_ph_qbla (v4i8);
-v2q15 __builtin_mips_precequ_ph_qbra (v4i8);
-v2q15 __builtin_mips_preceu_ph_qbl (v4i8);
-v2q15 __builtin_mips_preceu_ph_qbr (v4i8);
-v2q15 __builtin_mips_preceu_ph_qbla (v4i8);
-v2q15 __builtin_mips_preceu_ph_qbra (v4i8);
-v4i8 __builtin_mips_shll_qb (v4i8, imm0_7);
-v4i8 __builtin_mips_shll_qb (v4i8, i32);
-v2q15 __builtin_mips_shll_ph (v2q15, imm0_15);
-v2q15 __builtin_mips_shll_ph (v2q15, i32);
-v2q15 __builtin_mips_shll_s_ph (v2q15, imm0_15);
-v2q15 __builtin_mips_shll_s_ph (v2q15, i32);
-q31 __builtin_mips_shll_s_w (q31, imm0_31);
-q31 __builtin_mips_shll_s_w (q31, i32);
-v4i8 __builtin_mips_shrl_qb (v4i8, imm0_7);
-v4i8 __builtin_mips_shrl_qb (v4i8, i32);
-v2q15 __builtin_mips_shra_ph (v2q15, imm0_15);
-v2q15 __builtin_mips_shra_ph (v2q15, i32);
-v2q15 __builtin_mips_shra_r_ph (v2q15, imm0_15);
-v2q15 __builtin_mips_shra_r_ph (v2q15, i32);
-q31 __builtin_mips_shra_r_w (q31, imm0_31);
-q31 __builtin_mips_shra_r_w (q31, i32);
-v2q15 __builtin_mips_muleu_s_ph_qbl (v4i8, v2q15);
-v2q15 __builtin_mips_muleu_s_ph_qbr (v4i8, v2q15);
-v2q15 __builtin_mips_mulq_rs_ph (v2q15, v2q15);
-q31 __builtin_mips_muleq_s_w_phl (v2q15, v2q15);
-q31 __builtin_mips_muleq_s_w_phr (v2q15, v2q15);
-a64 __builtin_mips_dpau_h_qbl (a64, v4i8, v4i8);
-a64 __builtin_mips_dpau_h_qbr (a64, v4i8, v4i8);
-a64 __builtin_mips_dpsu_h_qbl (a64, v4i8, v4i8);
-a64 __builtin_mips_dpsu_h_qbr (a64, v4i8, v4i8);
-a64 __builtin_mips_dpaq_s_w_ph (a64, v2q15, v2q15);
-a64 __builtin_mips_dpaq_sa_l_w (a64, q31, q31);
-a64 __builtin_mips_dpsq_s_w_ph (a64, v2q15, v2q15);
-a64 __builtin_mips_dpsq_sa_l_w (a64, q31, q31);
-a64 __builtin_mips_mulsaq_s_w_ph (a64, v2q15, v2q15);
-a64 __builtin_mips_maq_s_w_phl (a64, v2q15, v2q15);
-a64 __builtin_mips_maq_s_w_phr (a64, v2q15, v2q15);
-a64 __builtin_mips_maq_sa_w_phl (a64, v2q15, v2q15);
-a64 __builtin_mips_maq_sa_w_phr (a64, v2q15, v2q15);
-i32 __builtin_mips_bitrev (i32);
-i32 __builtin_mips_insv (i32, i32);
-v4i8 __builtin_mips_repl_qb (imm0_255);
-v4i8 __builtin_mips_repl_qb (i32);
-v2q15 __builtin_mips_repl_ph (imm_n512_511);
-v2q15 __builtin_mips_repl_ph (i32);
-void __builtin_mips_cmpu_eq_qb (v4i8, v4i8);
-void __builtin_mips_cmpu_lt_qb (v4i8, v4i8);
-void __builtin_mips_cmpu_le_qb (v4i8, v4i8);
-i32 __builtin_mips_cmpgu_eq_qb (v4i8, v4i8);
-i32 __builtin_mips_cmpgu_lt_qb (v4i8, v4i8);
-i32 __builtin_mips_cmpgu_le_qb (v4i8, v4i8);
-void __builtin_mips_cmp_eq_ph (v2q15, v2q15);
-void __builtin_mips_cmp_lt_ph (v2q15, v2q15);
-void __builtin_mips_cmp_le_ph (v2q15, v2q15);
-v4i8 __builtin_mips_pick_qb (v4i8, v4i8);
-v2q15 __builtin_mips_pick_ph (v2q15, v2q15);
-v2q15 __builtin_mips_packrl_ph (v2q15, v2q15);
-i32 __builtin_mips_extr_w (a64, imm0_31);
-i32 __builtin_mips_extr_w (a64, i32);
-i32 __builtin_mips_extr_r_w (a64, imm0_31);
-i32 __builtin_mips_extr_s_h (a64, i32);
-i32 __builtin_mips_extr_rs_w (a64, imm0_31);
-i32 __builtin_mips_extr_rs_w (a64, i32);
-i32 __builtin_mips_extr_s_h (a64, imm0_31);
-i32 __builtin_mips_extr_r_w (a64, i32);
-i32 __builtin_mips_extp (a64, imm0_31);
-i32 __builtin_mips_extp (a64, i32);
-i32 __builtin_mips_extpdp (a64, imm0_31);
-i32 __builtin_mips_extpdp (a64, i32);
-a64 __builtin_mips_shilo (a64, imm_n32_31);
-a64 __builtin_mips_shilo (a64, i32);
-a64 __builtin_mips_mthlip (a64, i32);
-void __builtin_mips_wrdsp (i32, imm0_63);
-i32 __builtin_mips_rddsp (imm0_63);
-i32 __builtin_mips_lbux (void *, i32);
-i32 __builtin_mips_lhx (void *, i32);
-i32 __builtin_mips_lwx (void *, i32);
-a64 __builtin_mips_ldx (void *, i32); /* MIPS64 only */
-i32 __builtin_mips_bposge32 (void);
-a64 __builtin_mips_madd (a64, i32, i32);
-a64 __builtin_mips_maddu (a64, ui32, ui32);
-a64 __builtin_mips_msub (a64, i32, i32);
-a64 __builtin_mips_msubu (a64, ui32, ui32);
-a64 __builtin_mips_mult (i32, i32);
-a64 __builtin_mips_multu (ui32, ui32);
-@end smallexample
-
-The following built-in functions map directly to a particular MIPS DSP REV 2
-instruction. Please refer to the architecture specification
-for details on what each instruction does.
-
-@smallexample
-v4q7 __builtin_mips_absq_s_qb (v4q7);
-v2i16 __builtin_mips_addu_ph (v2i16, v2i16);
-v2i16 __builtin_mips_addu_s_ph (v2i16, v2i16);
-v4i8 __builtin_mips_adduh_qb (v4i8, v4i8);
-v4i8 __builtin_mips_adduh_r_qb (v4i8, v4i8);
-i32 __builtin_mips_append (i32, i32, imm0_31);
-i32 __builtin_mips_balign (i32, i32, imm0_3);
-i32 __builtin_mips_cmpgdu_eq_qb (v4i8, v4i8);
-i32 __builtin_mips_cmpgdu_lt_qb (v4i8, v4i8);
-i32 __builtin_mips_cmpgdu_le_qb (v4i8, v4i8);
-a64 __builtin_mips_dpa_w_ph (a64, v2i16, v2i16);
-a64 __builtin_mips_dps_w_ph (a64, v2i16, v2i16);
-v2i16 __builtin_mips_mul_ph (v2i16, v2i16);
-v2i16 __builtin_mips_mul_s_ph (v2i16, v2i16);
-q31 __builtin_mips_mulq_rs_w (q31, q31);
-v2q15 __builtin_mips_mulq_s_ph (v2q15, v2q15);
-q31 __builtin_mips_mulq_s_w (q31, q31);
-a64 __builtin_mips_mulsa_w_ph (a64, v2i16, v2i16);
-v4i8 __builtin_mips_precr_qb_ph (v2i16, v2i16);
-v2i16 __builtin_mips_precr_sra_ph_w (i32, i32, imm0_31);
-v2i16 __builtin_mips_precr_sra_r_ph_w (i32, i32, imm0_31);
-i32 __builtin_mips_prepend (i32, i32, imm0_31);
-v4i8 __builtin_mips_shra_qb (v4i8, imm0_7);
-v4i8 __builtin_mips_shra_r_qb (v4i8, imm0_7);
-v4i8 __builtin_mips_shra_qb (v4i8, i32);
-v4i8 __builtin_mips_shra_r_qb (v4i8, i32);
-v2i16 __builtin_mips_shrl_ph (v2i16, imm0_15);
-v2i16 __builtin_mips_shrl_ph (v2i16, i32);
-v2i16 __builtin_mips_subu_ph (v2i16, v2i16);
-v2i16 __builtin_mips_subu_s_ph (v2i16, v2i16);
-v4i8 __builtin_mips_subuh_qb (v4i8, v4i8);
-v4i8 __builtin_mips_subuh_r_qb (v4i8, v4i8);
-v2q15 __builtin_mips_addqh_ph (v2q15, v2q15);
-v2q15 __builtin_mips_addqh_r_ph (v2q15, v2q15);
-q31 __builtin_mips_addqh_w (q31, q31);
-q31 __builtin_mips_addqh_r_w (q31, q31);
-v2q15 __builtin_mips_subqh_ph (v2q15, v2q15);
-v2q15 __builtin_mips_subqh_r_ph (v2q15, v2q15);
-q31 __builtin_mips_subqh_w (q31, q31);
-q31 __builtin_mips_subqh_r_w (q31, q31);
-a64 __builtin_mips_dpax_w_ph (a64, v2i16, v2i16);
-a64 __builtin_mips_dpsx_w_ph (a64, v2i16, v2i16);
-a64 __builtin_mips_dpaqx_s_w_ph (a64, v2q15, v2q15);
-a64 __builtin_mips_dpaqx_sa_w_ph (a64, v2q15, v2q15);
-a64 __builtin_mips_dpsqx_s_w_ph (a64, v2q15, v2q15);
-a64 __builtin_mips_dpsqx_sa_w_ph (a64, v2q15, v2q15);
-@end smallexample
-
-
-@node MIPS Paired-Single Support
-@subsection MIPS Paired-Single Support
-
-The MIPS64 architecture includes a number of instructions that
-operate on pairs of single-precision floating-point values.
-Each pair is packed into a 64-bit floating-point register,
-with one element being designated the ``upper half'' and
-the other being designated the ``lower half''.
-
-GCC supports paired-single operations using both the generic
-vector extensions (@pxref{Vector Extensions}) and a collection of
-MIPS-specific built-in functions. Both kinds of support are
-enabled by the @option{-mpaired-single} command-line option.
-
-The vector type associated with paired-single values is usually
-called @code{v2sf}. It can be defined in C as follows:
-
-@smallexample
-typedef float v2sf __attribute__ ((vector_size (8)));
-@end smallexample
-
-@code{v2sf} values are initialized in the same way as aggregates.
-For example:
-
-@smallexample
-v2sf a = @{1.5, 9.1@};
-v2sf b;
-float e, f;
-b = (v2sf) @{e, f@};
-@end smallexample
-
-@emph{Note:} The CPU's endianness determines which value is stored in
-the upper half of a register and which value is stored in the lower half.
-On little-endian targets, the first value is the lower one and the second
-value is the upper one. The opposite order applies to big-endian targets.
-For example, the code above sets the lower half of @code{a} to
-@code{1.5} on little-endian targets and @code{9.1} on big-endian targets.
-
-@node MIPS Loongson Built-in Functions
-@subsection MIPS Loongson Built-in Functions
-
-GCC provides intrinsics to access the SIMD instructions provided by the
-ST Microelectronics Loongson-2E and -2F processors. These intrinsics,
-available after inclusion of the @code{loongson.h} header file,
-operate on the following 64-bit vector types:
-
-@itemize
-@item @code{uint8x8_t}, a vector of eight unsigned 8-bit integers;
-@item @code{uint16x4_t}, a vector of four unsigned 16-bit integers;
-@item @code{uint32x2_t}, a vector of two unsigned 32-bit integers;
-@item @code{int8x8_t}, a vector of eight signed 8-bit integers;
-@item @code{int16x4_t}, a vector of four signed 16-bit integers;
-@item @code{int32x2_t}, a vector of two signed 32-bit integers.
-@end itemize
-
-The intrinsics provided are listed below; each is named after the
-machine instruction to which it corresponds, with suffixes added as
-appropriate to distinguish intrinsics that expand to the same machine
-instruction yet have different argument types. Refer to the architecture
-documentation for a description of the functionality of each
-instruction.
-
-@smallexample
-int16x4_t packsswh (int32x2_t s, int32x2_t t);
-int8x8_t packsshb (int16x4_t s, int16x4_t t);
-uint8x8_t packushb (uint16x4_t s, uint16x4_t t);
-uint32x2_t paddw_u (uint32x2_t s, uint32x2_t t);
-uint16x4_t paddh_u (uint16x4_t s, uint16x4_t t);
-uint8x8_t paddb_u (uint8x8_t s, uint8x8_t t);
-int32x2_t paddw_s (int32x2_t s, int32x2_t t);
-int16x4_t paddh_s (int16x4_t s, int16x4_t t);
-int8x8_t paddb_s (int8x8_t s, int8x8_t t);
-uint64_t paddd_u (uint64_t s, uint64_t t);
-int64_t paddd_s (int64_t s, int64_t t);
-int16x4_t paddsh (int16x4_t s, int16x4_t t);
-int8x8_t paddsb (int8x8_t s, int8x8_t t);
-uint16x4_t paddush (uint16x4_t s, uint16x4_t t);
-uint8x8_t paddusb (uint8x8_t s, uint8x8_t t);
-uint64_t pandn_ud (uint64_t s, uint64_t t);
-uint32x2_t pandn_uw (uint32x2_t s, uint32x2_t t);
-uint16x4_t pandn_uh (uint16x4_t s, uint16x4_t t);
-uint8x8_t pandn_ub (uint8x8_t s, uint8x8_t t);
-int64_t pandn_sd (int64_t s, int64_t t);
-int32x2_t pandn_sw (int32x2_t s, int32x2_t t);
-int16x4_t pandn_sh (int16x4_t s, int16x4_t t);
-int8x8_t pandn_sb (int8x8_t s, int8x8_t t);
-uint16x4_t pavgh (uint16x4_t s, uint16x4_t t);
-uint8x8_t pavgb (uint8x8_t s, uint8x8_t t);
-uint32x2_t pcmpeqw_u (uint32x2_t s, uint32x2_t t);
-uint16x4_t pcmpeqh_u (uint16x4_t s, uint16x4_t t);
-uint8x8_t pcmpeqb_u (uint8x8_t s, uint8x8_t t);
-int32x2_t pcmpeqw_s (int32x2_t s, int32x2_t t);
-int16x4_t pcmpeqh_s (int16x4_t s, int16x4_t t);
-int8x8_t pcmpeqb_s (int8x8_t s, int8x8_t t);
-uint32x2_t pcmpgtw_u (uint32x2_t s, uint32x2_t t);
-uint16x4_t pcmpgth_u (uint16x4_t s, uint16x4_t t);
-uint8x8_t pcmpgtb_u (uint8x8_t s, uint8x8_t t);
-int32x2_t pcmpgtw_s (int32x2_t s, int32x2_t t);
-int16x4_t pcmpgth_s (int16x4_t s, int16x4_t t);
-int8x8_t pcmpgtb_s (int8x8_t s, int8x8_t t);
-uint16x4_t pextrh_u (uint16x4_t s, int field);
-int16x4_t pextrh_s (int16x4_t s, int field);
-uint16x4_t pinsrh_0_u (uint16x4_t s, uint16x4_t t);
-uint16x4_t pinsrh_1_u (uint16x4_t s, uint16x4_t t);
-uint16x4_t pinsrh_2_u (uint16x4_t s, uint16x4_t t);
-uint16x4_t pinsrh_3_u (uint16x4_t s, uint16x4_t t);
-int16x4_t pinsrh_0_s (int16x4_t s, int16x4_t t);
-int16x4_t pinsrh_1_s (int16x4_t s, int16x4_t t);
-int16x4_t pinsrh_2_s (int16x4_t s, int16x4_t t);
-int16x4_t pinsrh_3_s (int16x4_t s, int16x4_t t);
-int32x2_t pmaddhw (int16x4_t s, int16x4_t t);
-int16x4_t pmaxsh (int16x4_t s, int16x4_t t);
-uint8x8_t pmaxub (uint8x8_t s, uint8x8_t t);
-int16x4_t pminsh (int16x4_t s, int16x4_t t);
-uint8x8_t pminub (uint8x8_t s, uint8x8_t t);
-uint8x8_t pmovmskb_u (uint8x8_t s);
-int8x8_t pmovmskb_s (int8x8_t s);
-uint16x4_t pmulhuh (uint16x4_t s, uint16x4_t t);
-int16x4_t pmulhh (int16x4_t s, int16x4_t t);
-int16x4_t pmullh (int16x4_t s, int16x4_t t);
-int64_t pmuluw (uint32x2_t s, uint32x2_t t);
-uint8x8_t pasubub (uint8x8_t s, uint8x8_t t);
-uint16x4_t biadd (uint8x8_t s);
-uint16x4_t psadbh (uint8x8_t s, uint8x8_t t);
-uint16x4_t pshufh_u (uint16x4_t dest, uint16x4_t s, uint8_t order);
-int16x4_t pshufh_s (int16x4_t dest, int16x4_t s, uint8_t order);
-uint16x4_t psllh_u (uint16x4_t s, uint8_t amount);
-int16x4_t psllh_s (int16x4_t s, uint8_t amount);
-uint32x2_t psllw_u (uint32x2_t s, uint8_t amount);
-int32x2_t psllw_s (int32x2_t s, uint8_t amount);
-uint16x4_t psrlh_u (uint16x4_t s, uint8_t amount);
-int16x4_t psrlh_s (int16x4_t s, uint8_t amount);
-uint32x2_t psrlw_u (uint32x2_t s, uint8_t amount);
-int32x2_t psrlw_s (int32x2_t s, uint8_t amount);
-uint16x4_t psrah_u (uint16x4_t s, uint8_t amount);
-int16x4_t psrah_s (int16x4_t s, uint8_t amount);
-uint32x2_t psraw_u (uint32x2_t s, uint8_t amount);
-int32x2_t psraw_s (int32x2_t s, uint8_t amount);
-uint32x2_t psubw_u (uint32x2_t s, uint32x2_t t);
-uint16x4_t psubh_u (uint16x4_t s, uint16x4_t t);
-uint8x8_t psubb_u (uint8x8_t s, uint8x8_t t);
-int32x2_t psubw_s (int32x2_t s, int32x2_t t);
-int16x4_t psubh_s (int16x4_t s, int16x4_t t);
-int8x8_t psubb_s (int8x8_t s, int8x8_t t);
-uint64_t psubd_u (uint64_t s, uint64_t t);
-int64_t psubd_s (int64_t s, int64_t t);
-int16x4_t psubsh (int16x4_t s, int16x4_t t);
-int8x8_t psubsb (int8x8_t s, int8x8_t t);
-uint16x4_t psubush (uint16x4_t s, uint16x4_t t);
-uint8x8_t psubusb (uint8x8_t s, uint8x8_t t);
-uint32x2_t punpckhwd_u (uint32x2_t s, uint32x2_t t);
-uint16x4_t punpckhhw_u (uint16x4_t s, uint16x4_t t);
-uint8x8_t punpckhbh_u (uint8x8_t s, uint8x8_t t);
-int32x2_t punpckhwd_s (int32x2_t s, int32x2_t t);
-int16x4_t punpckhhw_s (int16x4_t s, int16x4_t t);
-int8x8_t punpckhbh_s (int8x8_t s, int8x8_t t);
-uint32x2_t punpcklwd_u (uint32x2_t s, uint32x2_t t);
-uint16x4_t punpcklhw_u (uint16x4_t s, uint16x4_t t);
-uint8x8_t punpcklbh_u (uint8x8_t s, uint8x8_t t);
-int32x2_t punpcklwd_s (int32x2_t s, int32x2_t t);
-int16x4_t punpcklhw_s (int16x4_t s, int16x4_t t);
-int8x8_t punpcklbh_s (int8x8_t s, int8x8_t t);
-@end smallexample
-
-@menu
-* Paired-Single Arithmetic::
-* Paired-Single Built-in Functions::
-* MIPS-3D Built-in Functions::
-@end menu
-
-@node Paired-Single Arithmetic
-@subsubsection Paired-Single Arithmetic
-
-The table below lists the @code{v2sf} operations for which hardware
-support exists. @code{a}, @code{b} and @code{c} are @code{v2sf}
-values and @code{x} is an integral value.
-
-@multitable @columnfractions .50 .50
-@headitem C code @tab MIPS instruction
-@item @code{a + b} @tab @code{add.ps}
-@item @code{a - b} @tab @code{sub.ps}
-@item @code{-a} @tab @code{neg.ps}
-@item @code{a * b} @tab @code{mul.ps}
-@item @code{a * b + c} @tab @code{madd.ps}
-@item @code{a * b - c} @tab @code{msub.ps}
-@item @code{-(a * b + c)} @tab @code{nmadd.ps}
-@item @code{-(a * b - c)} @tab @code{nmsub.ps}
-@item @code{x ? a : b} @tab @code{movn.ps}/@code{movz.ps}
-@end multitable
-
-Note that the multiply-accumulate instructions can be disabled
-using the command-line option @code{-mno-fused-madd}.
-
-@node Paired-Single Built-in Functions
-@subsubsection Paired-Single Built-in Functions
-
-The following paired-single functions map directly to a particular
-MIPS instruction. Please refer to the architecture specification
-for details on what each instruction does.
-
-@table @code
-@item v2sf __builtin_mips_pll_ps (v2sf, v2sf)
-Pair lower lower (@code{pll.ps}).
-
-@item v2sf __builtin_mips_pul_ps (v2sf, v2sf)
-Pair upper lower (@code{pul.ps}).
-
-@item v2sf __builtin_mips_plu_ps (v2sf, v2sf)
-Pair lower upper (@code{plu.ps}).
-
-@item v2sf __builtin_mips_puu_ps (v2sf, v2sf)
-Pair upper upper (@code{puu.ps}).
-
-@item v2sf __builtin_mips_cvt_ps_s (float, float)
-Convert pair to paired single (@code{cvt.ps.s}).
-
-@item float __builtin_mips_cvt_s_pl (v2sf)
-Convert pair lower to single (@code{cvt.s.pl}).
-
-@item float __builtin_mips_cvt_s_pu (v2sf)
-Convert pair upper to single (@code{cvt.s.pu}).
-
-@item v2sf __builtin_mips_abs_ps (v2sf)
-Absolute value (@code{abs.ps}).
-
-@item v2sf __builtin_mips_alnv_ps (v2sf, v2sf, int)
-Align variable (@code{alnv.ps}).
-
-@emph{Note:} The value of the third parameter must be 0 or 4
-modulo 8, otherwise the result is unpredictable. Please read the
-instruction description for details.
-@end table
-
-The following multi-instruction functions are also available.
-In each case, @var{cond} can be any of the 16 floating-point conditions:
-@code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, @code{ult},
-@code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq}, @code{ngl},
-@code{lt}, @code{nge}, @code{le} or @code{ngt}.
-
-@table @code
-@item v2sf __builtin_mips_movt_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
-@itemx v2sf __builtin_mips_movf_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
-Conditional move based on floating-point comparison (@code{c.@var{cond}.ps},
-@code{movt.ps}/@code{movf.ps}).
-
-The @code{movt} functions return the value @var{x} computed by:
-
-@smallexample
-c.@var{cond}.ps @var{cc},@var{a},@var{b}
-mov.ps @var{x},@var{c}
-movt.ps @var{x},@var{d},@var{cc}
-@end smallexample
-
-The @code{movf} functions are similar but use @code{movf.ps} instead
-of @code{movt.ps}.
-
-@item int __builtin_mips_upper_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
-@itemx int __builtin_mips_lower_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
-Comparison of two paired-single values (@code{c.@var{cond}.ps},
-@code{bc1t}/@code{bc1f}).
-
-These functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps}
-and return either the upper or lower half of the result. For example:
-
-@smallexample
-v2sf a, b;
-if (__builtin_mips_upper_c_eq_ps (a, b))
- upper_halves_are_equal ();
-else
- upper_halves_are_unequal ();
-
-if (__builtin_mips_lower_c_eq_ps (a, b))
- lower_halves_are_equal ();
-else
- lower_halves_are_unequal ();
-@end smallexample
-@end table
-
-@node MIPS-3D Built-in Functions
-@subsubsection MIPS-3D Built-in Functions
-
-The MIPS-3D Application-Specific Extension (ASE) includes additional
-paired-single instructions that are designed to improve the performance
-of 3D graphics operations. Support for these instructions is controlled
-by the @option{-mips3d} command-line option.
-
-The functions listed below map directly to a particular MIPS-3D
-instruction. Please refer to the architecture specification for
-more details on what each instruction does.
-
-@table @code
-@item v2sf __builtin_mips_addr_ps (v2sf, v2sf)
-Reduction add (@code{addr.ps}).
-
-@item v2sf __builtin_mips_mulr_ps (v2sf, v2sf)
-Reduction multiply (@code{mulr.ps}).
-
-@item v2sf __builtin_mips_cvt_pw_ps (v2sf)
-Convert paired single to paired word (@code{cvt.pw.ps}).
-
-@item v2sf __builtin_mips_cvt_ps_pw (v2sf)
-Convert paired word to paired single (@code{cvt.ps.pw}).
-
-@item float __builtin_mips_recip1_s (float)
-@itemx double __builtin_mips_recip1_d (double)
-@itemx v2sf __builtin_mips_recip1_ps (v2sf)
-Reduced-precision reciprocal (sequence step 1) (@code{recip1.@var{fmt}}).
-
-@item float __builtin_mips_recip2_s (float, float)
-@itemx double __builtin_mips_recip2_d (double, double)
-@itemx v2sf __builtin_mips_recip2_ps (v2sf, v2sf)
-Reduced-precision reciprocal (sequence step 2) (@code{recip2.@var{fmt}}).
-
-@item float __builtin_mips_rsqrt1_s (float)
-@itemx double __builtin_mips_rsqrt1_d (double)
-@itemx v2sf __builtin_mips_rsqrt1_ps (v2sf)
-Reduced-precision reciprocal square root (sequence step 1)
-(@code{rsqrt1.@var{fmt}}).
-
-@item float __builtin_mips_rsqrt2_s (float, float)
-@itemx double __builtin_mips_rsqrt2_d (double, double)
-@itemx v2sf __builtin_mips_rsqrt2_ps (v2sf, v2sf)
-Reduced-precision reciprocal square root (sequence step 2)
-(@code{rsqrt2.@var{fmt}}).
-@end table
-
-The following multi-instruction functions are also available.
-In each case, @var{cond} can be any of the 16 floating-point conditions:
-@code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, @code{ult},
-@code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq},
-@code{ngl}, @code{lt}, @code{nge}, @code{le} or @code{ngt}.
-
-@table @code
-@item int __builtin_mips_cabs_@var{cond}_s (float @var{a}, float @var{b})
-@itemx int __builtin_mips_cabs_@var{cond}_d (double @var{a}, double @var{b})
-Absolute comparison of two scalar values (@code{cabs.@var{cond}.@var{fmt}},
-@code{bc1t}/@code{bc1f}).
-
-These functions compare @var{a} and @var{b} using @code{cabs.@var{cond}.s}
-or @code{cabs.@var{cond}.d} and return the result as a boolean value.
-For example:
-
-@smallexample
-float a, b;
-if (__builtin_mips_cabs_eq_s (a, b))
- true ();
-else
- false ();
-@end smallexample
-
-@item int __builtin_mips_upper_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
-@itemx int __builtin_mips_lower_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
-Absolute comparison of two paired-single values (@code{cabs.@var{cond}.ps},
-@code{bc1t}/@code{bc1f}).
-
-These functions compare @var{a} and @var{b} using @code{cabs.@var{cond}.ps}
-and return either the upper or lower half of the result. For example:
-
-@smallexample
-v2sf a, b;
-if (__builtin_mips_upper_cabs_eq_ps (a, b))
- upper_halves_are_equal ();
-else
- upper_halves_are_unequal ();
-
-if (__builtin_mips_lower_cabs_eq_ps (a, b))
- lower_halves_are_equal ();
-else
- lower_halves_are_unequal ();
-@end smallexample
-
-@item v2sf __builtin_mips_movt_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
-@itemx v2sf __builtin_mips_movf_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
-Conditional move based on absolute comparison (@code{cabs.@var{cond}.ps},
-@code{movt.ps}/@code{movf.ps}).
-
-The @code{movt} functions return the value @var{x} computed by:
-
-@smallexample
-cabs.@var{cond}.ps @var{cc},@var{a},@var{b}
-mov.ps @var{x},@var{c}
-movt.ps @var{x},@var{d},@var{cc}
-@end smallexample
-
-The @code{movf} functions are similar but use @code{movf.ps} instead
-of @code{movt.ps}.
-
-@item int __builtin_mips_any_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
-@itemx int __builtin_mips_all_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
-@itemx int __builtin_mips_any_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
-@itemx int __builtin_mips_all_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
-Comparison of two paired-single values
-(@code{c.@var{cond}.ps}/@code{cabs.@var{cond}.ps},
-@code{bc1any2t}/@code{bc1any2f}).
-
-These functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps}
-or @code{cabs.@var{cond}.ps}. The @code{any} forms return @code{true} if either
-result is @code{true} and the @code{all} forms return @code{true} if both results are @code{true}.
-For example:
-
-@smallexample
-v2sf a, b;
-if (__builtin_mips_any_c_eq_ps (a, b))
- one_is_true ();
-else
- both_are_false ();
-
-if (__builtin_mips_all_c_eq_ps (a, b))
- both_are_true ();
-else
- one_is_false ();
-@end smallexample
-
-@item int __builtin_mips_any_c_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
-@itemx int __builtin_mips_all_c_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
-@itemx int __builtin_mips_any_cabs_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
-@itemx int __builtin_mips_all_cabs_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
-Comparison of four paired-single values
-(@code{c.@var{cond}.ps}/@code{cabs.@var{cond}.ps},
-@code{bc1any4t}/@code{bc1any4f}).
-
-These functions use @code{c.@var{cond}.ps} or @code{cabs.@var{cond}.ps}
-to compare @var{a} with @var{b} and to compare @var{c} with @var{d}.
-The @code{any} forms return @code{true} if any of the four results are @code{true}
-and the @code{all} forms return @code{true} if all four results are @code{true}.
-For example:
-
-@smallexample
-v2sf a, b, c, d;
-if (__builtin_mips_any_c_eq_4s (a, b, c, d))
- some_are_true ();
-else
- all_are_false ();
-
-if (__builtin_mips_all_c_eq_4s (a, b, c, d))
- all_are_true ();
-else
- some_are_false ();
-@end smallexample
-@end table
-
-@node MIPS SIMD Architecture (MSA) Support
-@subsection MIPS SIMD Architecture (MSA) Support
-
-@menu
-* MIPS SIMD Architecture Built-in Functions::
-@end menu
-
-GCC provides intrinsics to access the SIMD instructions provided by the
-MSA MIPS SIMD Architecture. The interface is made available by including
-@code{<msa.h>} and using @option{-mmsa -mhard-float -mfp64 -mnan=2008}.
-For each @code{__builtin_msa_*}, there is a shortened name of the intrinsic,
-@code{__msa_*}.
-
-MSA implements 128-bit wide vector registers, operating on 8-, 16-, 32- and
-64-bit integer, 16- and 32-bit fixed-point, or 32- and 64-bit floating point
-data elements. The following vectors typedefs are included in @code{msa.h}:
-@itemize
-@item @code{v16i8}, a vector of sixteen signed 8-bit integers;
-@item @code{v16u8}, a vector of sixteen unsigned 8-bit integers;
-@item @code{v8i16}, a vector of eight signed 16-bit integers;
-@item @code{v8u16}, a vector of eight unsigned 16-bit integers;
-@item @code{v4i32}, a vector of four signed 32-bit integers;
-@item @code{v4u32}, a vector of four unsigned 32-bit integers;
-@item @code{v2i64}, a vector of two signed 64-bit integers;
-@item @code{v2u64}, a vector of two unsigned 64-bit integers;
-@item @code{v4f32}, a vector of four 32-bit floats;
-@item @code{v2f64}, a vector of two 64-bit doubles.
-@end itemize
-
-Instructions and corresponding built-ins may have additional restrictions and/or
-input/output values manipulated:
-@itemize
-@item @code{imm0_1}, an integer literal in range 0 to 1;
-@item @code{imm0_3}, an integer literal in range 0 to 3;
-@item @code{imm0_7}, an integer literal in range 0 to 7;
-@item @code{imm0_15}, an integer literal in range 0 to 15;
-@item @code{imm0_31}, an integer literal in range 0 to 31;
-@item @code{imm0_63}, an integer literal in range 0 to 63;
-@item @code{imm0_255}, an integer literal in range 0 to 255;
-@item @code{imm_n16_15}, an integer literal in range -16 to 15;
-@item @code{imm_n512_511}, an integer literal in range -512 to 511;
-@item @code{imm_n1024_1022}, an integer literal in range -512 to 511 left
-shifted by 1 bit, i.e., -1024, -1022, @dots{}, 1020, 1022;
-@item @code{imm_n2048_2044}, an integer literal in range -512 to 511 left
-shifted by 2 bits, i.e., -2048, -2044, @dots{}, 2040, 2044;
-@item @code{imm_n4096_4088}, an integer literal in range -512 to 511 left
-shifted by 3 bits, i.e., -4096, -4088, @dots{}, 4080, 4088;
-@item @code{imm1_4}, an integer literal in range 1 to 4;
-@item @code{i32, i64, u32, u64, f32, f64}, defined as follows:
-@end itemize
-
-@smallexample
-@{
-typedef int i32;
-#if __LONG_MAX__ == __LONG_LONG_MAX__
-typedef long i64;
-#else
-typedef long long i64;
-#endif
-
-typedef unsigned int u32;
-#if __LONG_MAX__ == __LONG_LONG_MAX__
-typedef unsigned long u64;
-#else
-typedef unsigned long long u64;
-#endif
-
-typedef double f64;
-typedef float f32;
-@}
-@end smallexample
-
-@node MIPS SIMD Architecture Built-in Functions
-@subsubsection MIPS SIMD Architecture Built-in Functions
-
-The intrinsics provided are listed below; each is named after the
-machine instruction.
-
-@smallexample
-v16i8 __builtin_msa_add_a_b (v16i8, v16i8);
-v8i16 __builtin_msa_add_a_h (v8i16, v8i16);
-v4i32 __builtin_msa_add_a_w (v4i32, v4i32);
-v2i64 __builtin_msa_add_a_d (v2i64, v2i64);
-
-v16i8 __builtin_msa_adds_a_b (v16i8, v16i8);
-v8i16 __builtin_msa_adds_a_h (v8i16, v8i16);
-v4i32 __builtin_msa_adds_a_w (v4i32, v4i32);
-v2i64 __builtin_msa_adds_a_d (v2i64, v2i64);
-
-v16i8 __builtin_msa_adds_s_b (v16i8, v16i8);
-v8i16 __builtin_msa_adds_s_h (v8i16, v8i16);
-v4i32 __builtin_msa_adds_s_w (v4i32, v4i32);
-v2i64 __builtin_msa_adds_s_d (v2i64, v2i64);
-
-v16u8 __builtin_msa_adds_u_b (v16u8, v16u8);
-v8u16 __builtin_msa_adds_u_h (v8u16, v8u16);
-v4u32 __builtin_msa_adds_u_w (v4u32, v4u32);
-v2u64 __builtin_msa_adds_u_d (v2u64, v2u64);
-
-v16i8 __builtin_msa_addv_b (v16i8, v16i8);
-v8i16 __builtin_msa_addv_h (v8i16, v8i16);
-v4i32 __builtin_msa_addv_w (v4i32, v4i32);
-v2i64 __builtin_msa_addv_d (v2i64, v2i64);
-
-v16i8 __builtin_msa_addvi_b (v16i8, imm0_31);
-v8i16 __builtin_msa_addvi_h (v8i16, imm0_31);
-v4i32 __builtin_msa_addvi_w (v4i32, imm0_31);
-v2i64 __builtin_msa_addvi_d (v2i64, imm0_31);
-
-v16u8 __builtin_msa_and_v (v16u8, v16u8);
-
-v16u8 __builtin_msa_andi_b (v16u8, imm0_255);
-
-v16i8 __builtin_msa_asub_s_b (v16i8, v16i8);
-v8i16 __builtin_msa_asub_s_h (v8i16, v8i16);
-v4i32 __builtin_msa_asub_s_w (v4i32, v4i32);
-v2i64 __builtin_msa_asub_s_d (v2i64, v2i64);
-
-v16u8 __builtin_msa_asub_u_b (v16u8, v16u8);
-v8u16 __builtin_msa_asub_u_h (v8u16, v8u16);
-v4u32 __builtin_msa_asub_u_w (v4u32, v4u32);
-v2u64 __builtin_msa_asub_u_d (v2u64, v2u64);
-
-v16i8 __builtin_msa_ave_s_b (v16i8, v16i8);
-v8i16 __builtin_msa_ave_s_h (v8i16, v8i16);
-v4i32 __builtin_msa_ave_s_w (v4i32, v4i32);
-v2i64 __builtin_msa_ave_s_d (v2i64, v2i64);
-
-v16u8 __builtin_msa_ave_u_b (v16u8, v16u8);
-v8u16 __builtin_msa_ave_u_h (v8u16, v8u16);
-v4u32 __builtin_msa_ave_u_w (v4u32, v4u32);
-v2u64 __builtin_msa_ave_u_d (v2u64, v2u64);
-
-v16i8 __builtin_msa_aver_s_b (v16i8, v16i8);
-v8i16 __builtin_msa_aver_s_h (v8i16, v8i16);
-v4i32 __builtin_msa_aver_s_w (v4i32, v4i32);
-v2i64 __builtin_msa_aver_s_d (v2i64, v2i64);
-
-v16u8 __builtin_msa_aver_u_b (v16u8, v16u8);
-v8u16 __builtin_msa_aver_u_h (v8u16, v8u16);
-v4u32 __builtin_msa_aver_u_w (v4u32, v4u32);
-v2u64 __builtin_msa_aver_u_d (v2u64, v2u64);
-
-v16u8 __builtin_msa_bclr_b (v16u8, v16u8);
-v8u16 __builtin_msa_bclr_h (v8u16, v8u16);
-v4u32 __builtin_msa_bclr_w (v4u32, v4u32);
-v2u64 __builtin_msa_bclr_d (v2u64, v2u64);
-
-v16u8 __builtin_msa_bclri_b (v16u8, imm0_7);
-v8u16 __builtin_msa_bclri_h (v8u16, imm0_15);
-v4u32 __builtin_msa_bclri_w (v4u32, imm0_31);
-v2u64 __builtin_msa_bclri_d (v2u64, imm0_63);
-
-v16u8 __builtin_msa_binsl_b (v16u8, v16u8, v16u8);
-v8u16 __builtin_msa_binsl_h (v8u16, v8u16, v8u16);
-v4u32 __builtin_msa_binsl_w (v4u32, v4u32, v4u32);
-v2u64 __builtin_msa_binsl_d (v2u64, v2u64, v2u64);
-
-v16u8 __builtin_msa_binsli_b (v16u8, v16u8, imm0_7);
-v8u16 __builtin_msa_binsli_h (v8u16, v8u16, imm0_15);
-v4u32 __builtin_msa_binsli_w (v4u32, v4u32, imm0_31);
-v2u64 __builtin_msa_binsli_d (v2u64, v2u64, imm0_63);
-
-v16u8 __builtin_msa_binsr_b (v16u8, v16u8, v16u8);
-v8u16 __builtin_msa_binsr_h (v8u16, v8u16, v8u16);
-v4u32 __builtin_msa_binsr_w (v4u32, v4u32, v4u32);
-v2u64 __builtin_msa_binsr_d (v2u64, v2u64, v2u64);
-
-v16u8 __builtin_msa_binsri_b (v16u8, v16u8, imm0_7);
-v8u16 __builtin_msa_binsri_h (v8u16, v8u16, imm0_15);
-v4u32 __builtin_msa_binsri_w (v4u32, v4u32, imm0_31);
-v2u64 __builtin_msa_binsri_d (v2u64, v2u64, imm0_63);
-
-v16u8 __builtin_msa_bmnz_v (v16u8, v16u8, v16u8);
-
-v16u8 __builtin_msa_bmnzi_b (v16u8, v16u8, imm0_255);
-
-v16u8 __builtin_msa_bmz_v (v16u8, v16u8, v16u8);
-
-v16u8 __builtin_msa_bmzi_b (v16u8, v16u8, imm0_255);
-
-v16u8 __builtin_msa_bneg_b (v16u8, v16u8);
-v8u16 __builtin_msa_bneg_h (v8u16, v8u16);
-v4u32 __builtin_msa_bneg_w (v4u32, v4u32);
-v2u64 __builtin_msa_bneg_d (v2u64, v2u64);
-
-v16u8 __builtin_msa_bnegi_b (v16u8, imm0_7);
-v8u16 __builtin_msa_bnegi_h (v8u16, imm0_15);
-v4u32 __builtin_msa_bnegi_w (v4u32, imm0_31);
-v2u64 __builtin_msa_bnegi_d (v2u64, imm0_63);
-
-i32 __builtin_msa_bnz_b (v16u8);
-i32 __builtin_msa_bnz_h (v8u16);
-i32 __builtin_msa_bnz_w (v4u32);
-i32 __builtin_msa_bnz_d (v2u64);
-
-i32 __builtin_msa_bnz_v (v16u8);
-
-v16u8 __builtin_msa_bsel_v (v16u8, v16u8, v16u8);
-
-v16u8 __builtin_msa_bseli_b (v16u8, v16u8, imm0_255);
-
-v16u8 __builtin_msa_bset_b (v16u8, v16u8);
-v8u16 __builtin_msa_bset_h (v8u16, v8u16);
-v4u32 __builtin_msa_bset_w (v4u32, v4u32);
-v2u64 __builtin_msa_bset_d (v2u64, v2u64);
-
-v16u8 __builtin_msa_bseti_b (v16u8, imm0_7);
-v8u16 __builtin_msa_bseti_h (v8u16, imm0_15);
-v4u32 __builtin_msa_bseti_w (v4u32, imm0_31);
-v2u64 __builtin_msa_bseti_d (v2u64, imm0_63);
-
-i32 __builtin_msa_bz_b (v16u8);
-i32 __builtin_msa_bz_h (v8u16);
-i32 __builtin_msa_bz_w (v4u32);
-i32 __builtin_msa_bz_d (v2u64);
-
-i32 __builtin_msa_bz_v (v16u8);
-
-v16i8 __builtin_msa_ceq_b (v16i8, v16i8);
-v8i16 __builtin_msa_ceq_h (v8i16, v8i16);
-v4i32 __builtin_msa_ceq_w (v4i32, v4i32);
-v2i64 __builtin_msa_ceq_d (v2i64, v2i64);
-
-v16i8 __builtin_msa_ceqi_b (v16i8, imm_n16_15);
-v8i16 __builtin_msa_ceqi_h (v8i16, imm_n16_15);
-v4i32 __builtin_msa_ceqi_w (v4i32, imm_n16_15);
-v2i64 __builtin_msa_ceqi_d (v2i64, imm_n16_15);
-
-i32 __builtin_msa_cfcmsa (imm0_31);
-
-v16i8 __builtin_msa_cle_s_b (v16i8, v16i8);
-v8i16 __builtin_msa_cle_s_h (v8i16, v8i16);
-v4i32 __builtin_msa_cle_s_w (v4i32, v4i32);
-v2i64 __builtin_msa_cle_s_d (v2i64, v2i64);
-
-v16i8 __builtin_msa_cle_u_b (v16u8, v16u8);
-v8i16 __builtin_msa_cle_u_h (v8u16, v8u16);
-v4i32 __builtin_msa_cle_u_w (v4u32, v4u32);
-v2i64 __builtin_msa_cle_u_d (v2u64, v2u64);
-
-v16i8 __builtin_msa_clei_s_b (v16i8, imm_n16_15);
-v8i16 __builtin_msa_clei_s_h (v8i16, imm_n16_15);
-v4i32 __builtin_msa_clei_s_w (v4i32, imm_n16_15);
-v2i64 __builtin_msa_clei_s_d (v2i64, imm_n16_15);
-
-v16i8 __builtin_msa_clei_u_b (v16u8, imm0_31);
-v8i16 __builtin_msa_clei_u_h (v8u16, imm0_31);
-v4i32 __builtin_msa_clei_u_w (v4u32, imm0_31);
-v2i64 __builtin_msa_clei_u_d (v2u64, imm0_31);
-
-v16i8 __builtin_msa_clt_s_b (v16i8, v16i8);
-v8i16 __builtin_msa_clt_s_h (v8i16, v8i16);
-v4i32 __builtin_msa_clt_s_w (v4i32, v4i32);
-v2i64 __builtin_msa_clt_s_d (v2i64, v2i64);
-
-v16i8 __builtin_msa_clt_u_b (v16u8, v16u8);
-v8i16 __builtin_msa_clt_u_h (v8u16, v8u16);
-v4i32 __builtin_msa_clt_u_w (v4u32, v4u32);
-v2i64 __builtin_msa_clt_u_d (v2u64, v2u64);
-
-v16i8 __builtin_msa_clti_s_b (v16i8, imm_n16_15);
-v8i16 __builtin_msa_clti_s_h (v8i16, imm_n16_15);
-v4i32 __builtin_msa_clti_s_w (v4i32, imm_n16_15);
-v2i64 __builtin_msa_clti_s_d (v2i64, imm_n16_15);
-
-v16i8 __builtin_msa_clti_u_b (v16u8, imm0_31);
-v8i16 __builtin_msa_clti_u_h (v8u16, imm0_31);
-v4i32 __builtin_msa_clti_u_w (v4u32, imm0_31);
-v2i64 __builtin_msa_clti_u_d (v2u64, imm0_31);
-
-i32 __builtin_msa_copy_s_b (v16i8, imm0_15);
-i32 __builtin_msa_copy_s_h (v8i16, imm0_7);
-i32 __builtin_msa_copy_s_w (v4i32, imm0_3);
-i64 __builtin_msa_copy_s_d (v2i64, imm0_1);
-
-u32 __builtin_msa_copy_u_b (v16i8, imm0_15);
-u32 __builtin_msa_copy_u_h (v8i16, imm0_7);
-u32 __builtin_msa_copy_u_w (v4i32, imm0_3);
-u64 __builtin_msa_copy_u_d (v2i64, imm0_1);
-
-void __builtin_msa_ctcmsa (imm0_31, i32);
-
-v16i8 __builtin_msa_div_s_b (v16i8, v16i8);
-v8i16 __builtin_msa_div_s_h (v8i16, v8i16);
-v4i32 __builtin_msa_div_s_w (v4i32, v4i32);
-v2i64 __builtin_msa_div_s_d (v2i64, v2i64);
-
-v16u8 __builtin_msa_div_u_b (v16u8, v16u8);
-v8u16 __builtin_msa_div_u_h (v8u16, v8u16);
-v4u32 __builtin_msa_div_u_w (v4u32, v4u32);
-v2u64 __builtin_msa_div_u_d (v2u64, v2u64);
-
-v8i16 __builtin_msa_dotp_s_h (v16i8, v16i8);
-v4i32 __builtin_msa_dotp_s_w (v8i16, v8i16);
-v2i64 __builtin_msa_dotp_s_d (v4i32, v4i32);
-
-v8u16 __builtin_msa_dotp_u_h (v16u8, v16u8);
-v4u32 __builtin_msa_dotp_u_w (v8u16, v8u16);
-v2u64 __builtin_msa_dotp_u_d (v4u32, v4u32);
-
-v8i16 __builtin_msa_dpadd_s_h (v8i16, v16i8, v16i8);
-v4i32 __builtin_msa_dpadd_s_w (v4i32, v8i16, v8i16);
-v2i64 __builtin_msa_dpadd_s_d (v2i64, v4i32, v4i32);
-
-v8u16 __builtin_msa_dpadd_u_h (v8u16, v16u8, v16u8);
-v4u32 __builtin_msa_dpadd_u_w (v4u32, v8u16, v8u16);
-v2u64 __builtin_msa_dpadd_u_d (v2u64, v4u32, v4u32);
-
-v8i16 __builtin_msa_dpsub_s_h (v8i16, v16i8, v16i8);
-v4i32 __builtin_msa_dpsub_s_w (v4i32, v8i16, v8i16);
-v2i64 __builtin_msa_dpsub_s_d (v2i64, v4i32, v4i32);
-
-v8i16 __builtin_msa_dpsub_u_h (v8i16, v16u8, v16u8);
-v4i32 __builtin_msa_dpsub_u_w (v4i32, v8u16, v8u16);
-v2i64 __builtin_msa_dpsub_u_d (v2i64, v4u32, v4u32);
-
-v4f32 __builtin_msa_fadd_w (v4f32, v4f32);
-v2f64 __builtin_msa_fadd_d (v2f64, v2f64);
-
-v4i32 __builtin_msa_fcaf_w (v4f32, v4f32);
-v2i64 __builtin_msa_fcaf_d (v2f64, v2f64);
-
-v4i32 __builtin_msa_fceq_w (v4f32, v4f32);
-v2i64 __builtin_msa_fceq_d (v2f64, v2f64);
-
-v4i32 __builtin_msa_fclass_w (v4f32);
-v2i64 __builtin_msa_fclass_d (v2f64);
-
-v4i32 __builtin_msa_fcle_w (v4f32, v4f32);
-v2i64 __builtin_msa_fcle_d (v2f64, v2f64);
-
-v4i32 __builtin_msa_fclt_w (v4f32, v4f32);
-v2i64 __builtin_msa_fclt_d (v2f64, v2f64);
-
-v4i32 __builtin_msa_fcne_w (v4f32, v4f32);
-v2i64 __builtin_msa_fcne_d (v2f64, v2f64);
-
-v4i32 __builtin_msa_fcor_w (v4f32, v4f32);
-v2i64 __builtin_msa_fcor_d (v2f64, v2f64);
-
-v4i32 __builtin_msa_fcueq_w (v4f32, v4f32);
-v2i64 __builtin_msa_fcueq_d (v2f64, v2f64);
-
-v4i32 __builtin_msa_fcule_w (v4f32, v4f32);
-v2i64 __builtin_msa_fcule_d (v2f64, v2f64);
-
-v4i32 __builtin_msa_fcult_w (v4f32, v4f32);
-v2i64 __builtin_msa_fcult_d (v2f64, v2f64);
-
-v4i32 __builtin_msa_fcun_w (v4f32, v4f32);
-v2i64 __builtin_msa_fcun_d (v2f64, v2f64);
-
-v4i32 __builtin_msa_fcune_w (v4f32, v4f32);
-v2i64 __builtin_msa_fcune_d (v2f64, v2f64);
-
-v4f32 __builtin_msa_fdiv_w (v4f32, v4f32);
-v2f64 __builtin_msa_fdiv_d (v2f64, v2f64);
-
-v8i16 __builtin_msa_fexdo_h (v4f32, v4f32);
-v4f32 __builtin_msa_fexdo_w (v2f64, v2f64);
-
-v4f32 __builtin_msa_fexp2_w (v4f32, v4i32);
-v2f64 __builtin_msa_fexp2_d (v2f64, v2i64);
-
-v4f32 __builtin_msa_fexupl_w (v8i16);
-v2f64 __builtin_msa_fexupl_d (v4f32);
-
-v4f32 __builtin_msa_fexupr_w (v8i16);
-v2f64 __builtin_msa_fexupr_d (v4f32);
-
-v4f32 __builtin_msa_ffint_s_w (v4i32);
-v2f64 __builtin_msa_ffint_s_d (v2i64);
-
-v4f32 __builtin_msa_ffint_u_w (v4u32);
-v2f64 __builtin_msa_ffint_u_d (v2u64);
-
-v4f32 __builtin_msa_ffql_w (v8i16);
-v2f64 __builtin_msa_ffql_d (v4i32);
-
-v4f32 __builtin_msa_ffqr_w (v8i16);
-v2f64 __builtin_msa_ffqr_d (v4i32);
-
-v16i8 __builtin_msa_fill_b (i32);
-v8i16 __builtin_msa_fill_h (i32);
-v4i32 __builtin_msa_fill_w (i32);
-v2i64 __builtin_msa_fill_d (i64);
-
-v4f32 __builtin_msa_flog2_w (v4f32);
-v2f64 __builtin_msa_flog2_d (v2f64);
-
-v4f32 __builtin_msa_fmadd_w (v4f32, v4f32, v4f32);
-v2f64 __builtin_msa_fmadd_d (v2f64, v2f64, v2f64);
-
-v4f32 __builtin_msa_fmax_w (v4f32, v4f32);
-v2f64 __builtin_msa_fmax_d (v2f64, v2f64);
-
-v4f32 __builtin_msa_fmax_a_w (v4f32, v4f32);
-v2f64 __builtin_msa_fmax_a_d (v2f64, v2f64);
-
-v4f32 __builtin_msa_fmin_w (v4f32, v4f32);
-v2f64 __builtin_msa_fmin_d (v2f64, v2f64);
-
-v4f32 __builtin_msa_fmin_a_w (v4f32, v4f32);
-v2f64 __builtin_msa_fmin_a_d (v2f64, v2f64);
-
-v4f32 __builtin_msa_fmsub_w (v4f32, v4f32, v4f32);
-v2f64 __builtin_msa_fmsub_d (v2f64, v2f64, v2f64);
-
-v4f32 __builtin_msa_fmul_w (v4f32, v4f32);
-v2f64 __builtin_msa_fmul_d (v2f64, v2f64);
-
-v4f32 __builtin_msa_frint_w (v4f32);
-v2f64 __builtin_msa_frint_d (v2f64);
-
-v4f32 __builtin_msa_frcp_w (v4f32);
-v2f64 __builtin_msa_frcp_d (v2f64);
-
-v4f32 __builtin_msa_frsqrt_w (v4f32);
-v2f64 __builtin_msa_frsqrt_d (v2f64);
-
-v4i32 __builtin_msa_fsaf_w (v4f32, v4f32);
-v2i64 __builtin_msa_fsaf_d (v2f64, v2f64);
-
-v4i32 __builtin_msa_fseq_w (v4f32, v4f32);
-v2i64 __builtin_msa_fseq_d (v2f64, v2f64);
-
-v4i32 __builtin_msa_fsle_w (v4f32, v4f32);
-v2i64 __builtin_msa_fsle_d (v2f64, v2f64);
-
-v4i32 __builtin_msa_fslt_w (v4f32, v4f32);
-v2i64 __builtin_msa_fslt_d (v2f64, v2f64);
-
-v4i32 __builtin_msa_fsne_w (v4f32, v4f32);
-v2i64 __builtin_msa_fsne_d (v2f64, v2f64);
-
-v4i32 __builtin_msa_fsor_w (v4f32, v4f32);
-v2i64 __builtin_msa_fsor_d (v2f64, v2f64);
-
-v4f32 __builtin_msa_fsqrt_w (v4f32);
-v2f64 __builtin_msa_fsqrt_d (v2f64);
-
-v4f32 __builtin_msa_fsub_w (v4f32, v4f32);
-v2f64 __builtin_msa_fsub_d (v2f64, v2f64);
-
-v4i32 __builtin_msa_fsueq_w (v4f32, v4f32);
-v2i64 __builtin_msa_fsueq_d (v2f64, v2f64);
-
-v4i32 __builtin_msa_fsule_w (v4f32, v4f32);
-v2i64 __builtin_msa_fsule_d (v2f64, v2f64);
-
-v4i32 __builtin_msa_fsult_w (v4f32, v4f32);
-v2i64 __builtin_msa_fsult_d (v2f64, v2f64);
-
-v4i32 __builtin_msa_fsun_w (v4f32, v4f32);
-v2i64 __builtin_msa_fsun_d (v2f64, v2f64);
-
-v4i32 __builtin_msa_fsune_w (v4f32, v4f32);
-v2i64 __builtin_msa_fsune_d (v2f64, v2f64);
-
-v4i32 __builtin_msa_ftint_s_w (v4f32);
-v2i64 __builtin_msa_ftint_s_d (v2f64);
-
-v4u32 __builtin_msa_ftint_u_w (v4f32);
-v2u64 __builtin_msa_ftint_u_d (v2f64);
-
-v8i16 __builtin_msa_ftq_h (v4f32, v4f32);
-v4i32 __builtin_msa_ftq_w (v2f64, v2f64);
-
-v4i32 __builtin_msa_ftrunc_s_w (v4f32);
-v2i64 __builtin_msa_ftrunc_s_d (v2f64);
-
-v4u32 __builtin_msa_ftrunc_u_w (v4f32);
-v2u64 __builtin_msa_ftrunc_u_d (v2f64);
-
-v8i16 __builtin_msa_hadd_s_h (v16i8, v16i8);
-v4i32 __builtin_msa_hadd_s_w (v8i16, v8i16);
-v2i64 __builtin_msa_hadd_s_d (v4i32, v4i32);
-
-v8u16 __builtin_msa_hadd_u_h (v16u8, v16u8);
-v4u32 __builtin_msa_hadd_u_w (v8u16, v8u16);
-v2u64 __builtin_msa_hadd_u_d (v4u32, v4u32);
-
-v8i16 __builtin_msa_hsub_s_h (v16i8, v16i8);
-v4i32 __builtin_msa_hsub_s_w (v8i16, v8i16);
-v2i64 __builtin_msa_hsub_s_d (v4i32, v4i32);
-
-v8i16 __builtin_msa_hsub_u_h (v16u8, v16u8);
-v4i32 __builtin_msa_hsub_u_w (v8u16, v8u16);
-v2i64 __builtin_msa_hsub_u_d (v4u32, v4u32);
-
-v16i8 __builtin_msa_ilvev_b (v16i8, v16i8);
-v8i16 __builtin_msa_ilvev_h (v8i16, v8i16);
-v4i32 __builtin_msa_ilvev_w (v4i32, v4i32);
-v2i64 __builtin_msa_ilvev_d (v2i64, v2i64);
-
-v16i8 __builtin_msa_ilvl_b (v16i8, v16i8);
-v8i16 __builtin_msa_ilvl_h (v8i16, v8i16);
-v4i32 __builtin_msa_ilvl_w (v4i32, v4i32);
-v2i64 __builtin_msa_ilvl_d (v2i64, v2i64);
-
-v16i8 __builtin_msa_ilvod_b (v16i8, v16i8);
-v8i16 __builtin_msa_ilvod_h (v8i16, v8i16);
-v4i32 __builtin_msa_ilvod_w (v4i32, v4i32);
-v2i64 __builtin_msa_ilvod_d (v2i64, v2i64);
-
-v16i8 __builtin_msa_ilvr_b (v16i8, v16i8);
-v8i16 __builtin_msa_ilvr_h (v8i16, v8i16);
-v4i32 __builtin_msa_ilvr_w (v4i32, v4i32);
-v2i64 __builtin_msa_ilvr_d (v2i64, v2i64);
-
-v16i8 __builtin_msa_insert_b (v16i8, imm0_15, i32);
-v8i16 __builtin_msa_insert_h (v8i16, imm0_7, i32);
-v4i32 __builtin_msa_insert_w (v4i32, imm0_3, i32);
-v2i64 __builtin_msa_insert_d (v2i64, imm0_1, i64);
-
-v16i8 __builtin_msa_insve_b (v16i8, imm0_15, v16i8);
-v8i16 __builtin_msa_insve_h (v8i16, imm0_7, v8i16);
-v4i32 __builtin_msa_insve_w (v4i32, imm0_3, v4i32);
-v2i64 __builtin_msa_insve_d (v2i64, imm0_1, v2i64);
-
-v16i8 __builtin_msa_ld_b (const void *, imm_n512_511);
-v8i16 __builtin_msa_ld_h (const void *, imm_n1024_1022);
-v4i32 __builtin_msa_ld_w (const void *, imm_n2048_2044);
-v2i64 __builtin_msa_ld_d (const void *, imm_n4096_4088);
-
-v16i8 __builtin_msa_ldi_b (imm_n512_511);
-v8i16 __builtin_msa_ldi_h (imm_n512_511);
-v4i32 __builtin_msa_ldi_w (imm_n512_511);
-v2i64 __builtin_msa_ldi_d (imm_n512_511);
-
-v8i16 __builtin_msa_madd_q_h (v8i16, v8i16, v8i16);
-v4i32 __builtin_msa_madd_q_w (v4i32, v4i32, v4i32);
-
-v8i16 __builtin_msa_maddr_q_h (v8i16, v8i16, v8i16);
-v4i32 __builtin_msa_maddr_q_w (v4i32, v4i32, v4i32);
-
-v16i8 __builtin_msa_maddv_b (v16i8, v16i8, v16i8);
-v8i16 __builtin_msa_maddv_h (v8i16, v8i16, v8i16);
-v4i32 __builtin_msa_maddv_w (v4i32, v4i32, v4i32);
-v2i64 __builtin_msa_maddv_d (v2i64, v2i64, v2i64);
-
-v16i8 __builtin_msa_max_a_b (v16i8, v16i8);
-v8i16 __builtin_msa_max_a_h (v8i16, v8i16);
-v4i32 __builtin_msa_max_a_w (v4i32, v4i32);
-v2i64 __builtin_msa_max_a_d (v2i64, v2i64);
-
-v16i8 __builtin_msa_max_s_b (v16i8, v16i8);
-v8i16 __builtin_msa_max_s_h (v8i16, v8i16);
-v4i32 __builtin_msa_max_s_w (v4i32, v4i32);
-v2i64 __builtin_msa_max_s_d (v2i64, v2i64);
-
-v16u8 __builtin_msa_max_u_b (v16u8, v16u8);
-v8u16 __builtin_msa_max_u_h (v8u16, v8u16);
-v4u32 __builtin_msa_max_u_w (v4u32, v4u32);
-v2u64 __builtin_msa_max_u_d (v2u64, v2u64);
-
-v16i8 __builtin_msa_maxi_s_b (v16i8, imm_n16_15);
-v8i16 __builtin_msa_maxi_s_h (v8i16, imm_n16_15);
-v4i32 __builtin_msa_maxi_s_w (v4i32, imm_n16_15);
-v2i64 __builtin_msa_maxi_s_d (v2i64, imm_n16_15);
-
-v16u8 __builtin_msa_maxi_u_b (v16u8, imm0_31);
-v8u16 __builtin_msa_maxi_u_h (v8u16, imm0_31);
-v4u32 __builtin_msa_maxi_u_w (v4u32, imm0_31);
-v2u64 __builtin_msa_maxi_u_d (v2u64, imm0_31);
-
-v16i8 __builtin_msa_min_a_b (v16i8, v16i8);
-v8i16 __builtin_msa_min_a_h (v8i16, v8i16);
-v4i32 __builtin_msa_min_a_w (v4i32, v4i32);
-v2i64 __builtin_msa_min_a_d (v2i64, v2i64);
-
-v16i8 __builtin_msa_min_s_b (v16i8, v16i8);
-v8i16 __builtin_msa_min_s_h (v8i16, v8i16);
-v4i32 __builtin_msa_min_s_w (v4i32, v4i32);
-v2i64 __builtin_msa_min_s_d (v2i64, v2i64);
-
-v16u8 __builtin_msa_min_u_b (v16u8, v16u8);
-v8u16 __builtin_msa_min_u_h (v8u16, v8u16);
-v4u32 __builtin_msa_min_u_w (v4u32, v4u32);
-v2u64 __builtin_msa_min_u_d (v2u64, v2u64);
-
-v16i8 __builtin_msa_mini_s_b (v16i8, imm_n16_15);
-v8i16 __builtin_msa_mini_s_h (v8i16, imm_n16_15);
-v4i32 __builtin_msa_mini_s_w (v4i32, imm_n16_15);
-v2i64 __builtin_msa_mini_s_d (v2i64, imm_n16_15);
-
-v16u8 __builtin_msa_mini_u_b (v16u8, imm0_31);
-v8u16 __builtin_msa_mini_u_h (v8u16, imm0_31);
-v4u32 __builtin_msa_mini_u_w (v4u32, imm0_31);
-v2u64 __builtin_msa_mini_u_d (v2u64, imm0_31);
-
-v16i8 __builtin_msa_mod_s_b (v16i8, v16i8);
-v8i16 __builtin_msa_mod_s_h (v8i16, v8i16);
-v4i32 __builtin_msa_mod_s_w (v4i32, v4i32);
-v2i64 __builtin_msa_mod_s_d (v2i64, v2i64);
-
-v16u8 __builtin_msa_mod_u_b (v16u8, v16u8);
-v8u16 __builtin_msa_mod_u_h (v8u16, v8u16);
-v4u32 __builtin_msa_mod_u_w (v4u32, v4u32);
-v2u64 __builtin_msa_mod_u_d (v2u64, v2u64);
-
-v16i8 __builtin_msa_move_v (v16i8);
-
-v8i16 __builtin_msa_msub_q_h (v8i16, v8i16, v8i16);
-v4i32 __builtin_msa_msub_q_w (v4i32, v4i32, v4i32);
-
-v8i16 __builtin_msa_msubr_q_h (v8i16, v8i16, v8i16);
-v4i32 __builtin_msa_msubr_q_w (v4i32, v4i32, v4i32);
-
-v16i8 __builtin_msa_msubv_b (v16i8, v16i8, v16i8);
-v8i16 __builtin_msa_msubv_h (v8i16, v8i16, v8i16);
-v4i32 __builtin_msa_msubv_w (v4i32, v4i32, v4i32);
-v2i64 __builtin_msa_msubv_d (v2i64, v2i64, v2i64);
-
-v8i16 __builtin_msa_mul_q_h (v8i16, v8i16);
-v4i32 __builtin_msa_mul_q_w (v4i32, v4i32);
-
-v8i16 __builtin_msa_mulr_q_h (v8i16, v8i16);
-v4i32 __builtin_msa_mulr_q_w (v4i32, v4i32);
-
-v16i8 __builtin_msa_mulv_b (v16i8, v16i8);
-v8i16 __builtin_msa_mulv_h (v8i16, v8i16);
-v4i32 __builtin_msa_mulv_w (v4i32, v4i32);
-v2i64 __builtin_msa_mulv_d (v2i64, v2i64);
-
-v16i8 __builtin_msa_nloc_b (v16i8);
-v8i16 __builtin_msa_nloc_h (v8i16);
-v4i32 __builtin_msa_nloc_w (v4i32);
-v2i64 __builtin_msa_nloc_d (v2i64);
-
-v16i8 __builtin_msa_nlzc_b (v16i8);
-v8i16 __builtin_msa_nlzc_h (v8i16);
-v4i32 __builtin_msa_nlzc_w (v4i32);
-v2i64 __builtin_msa_nlzc_d (v2i64);
-
-v16u8 __builtin_msa_nor_v (v16u8, v16u8);
-
-v16u8 __builtin_msa_nori_b (v16u8, imm0_255);
-
-v16u8 __builtin_msa_or_v (v16u8, v16u8);
-
-v16u8 __builtin_msa_ori_b (v16u8, imm0_255);
-
-v16i8 __builtin_msa_pckev_b (v16i8, v16i8);
-v8i16 __builtin_msa_pckev_h (v8i16, v8i16);
-v4i32 __builtin_msa_pckev_w (v4i32, v4i32);
-v2i64 __builtin_msa_pckev_d (v2i64, v2i64);
-
-v16i8 __builtin_msa_pckod_b (v16i8, v16i8);
-v8i16 __builtin_msa_pckod_h (v8i16, v8i16);
-v4i32 __builtin_msa_pckod_w (v4i32, v4i32);
-v2i64 __builtin_msa_pckod_d (v2i64, v2i64);
-
-v16i8 __builtin_msa_pcnt_b (v16i8);
-v8i16 __builtin_msa_pcnt_h (v8i16);
-v4i32 __builtin_msa_pcnt_w (v4i32);
-v2i64 __builtin_msa_pcnt_d (v2i64);
-
-v16i8 __builtin_msa_sat_s_b (v16i8, imm0_7);
-v8i16 __builtin_msa_sat_s_h (v8i16, imm0_15);
-v4i32 __builtin_msa_sat_s_w (v4i32, imm0_31);
-v2i64 __builtin_msa_sat_s_d (v2i64, imm0_63);
-
-v16u8 __builtin_msa_sat_u_b (v16u8, imm0_7);
-v8u16 __builtin_msa_sat_u_h (v8u16, imm0_15);
-v4u32 __builtin_msa_sat_u_w (v4u32, imm0_31);
-v2u64 __builtin_msa_sat_u_d (v2u64, imm0_63);
-
-v16i8 __builtin_msa_shf_b (v16i8, imm0_255);
-v8i16 __builtin_msa_shf_h (v8i16, imm0_255);
-v4i32 __builtin_msa_shf_w (v4i32, imm0_255);
-
-v16i8 __builtin_msa_sld_b (v16i8, v16i8, i32);
-v8i16 __builtin_msa_sld_h (v8i16, v8i16, i32);
-v4i32 __builtin_msa_sld_w (v4i32, v4i32, i32);
-v2i64 __builtin_msa_sld_d (v2i64, v2i64, i32);
-
-v16i8 __builtin_msa_sldi_b (v16i8, v16i8, imm0_15);
-v8i16 __builtin_msa_sldi_h (v8i16, v8i16, imm0_7);
-v4i32 __builtin_msa_sldi_w (v4i32, v4i32, imm0_3);
-v2i64 __builtin_msa_sldi_d (v2i64, v2i64, imm0_1);
-
-v16i8 __builtin_msa_sll_b (v16i8, v16i8);
-v8i16 __builtin_msa_sll_h (v8i16, v8i16);
-v4i32 __builtin_msa_sll_w (v4i32, v4i32);
-v2i64 __builtin_msa_sll_d (v2i64, v2i64);
-
-v16i8 __builtin_msa_slli_b (v16i8, imm0_7);
-v8i16 __builtin_msa_slli_h (v8i16, imm0_15);
-v4i32 __builtin_msa_slli_w (v4i32, imm0_31);
-v2i64 __builtin_msa_slli_d (v2i64, imm0_63);
-
-v16i8 __builtin_msa_splat_b (v16i8, i32);
-v8i16 __builtin_msa_splat_h (v8i16, i32);
-v4i32 __builtin_msa_splat_w (v4i32, i32);
-v2i64 __builtin_msa_splat_d (v2i64, i32);
-
-v16i8 __builtin_msa_splati_b (v16i8, imm0_15);
-v8i16 __builtin_msa_splati_h (v8i16, imm0_7);
-v4i32 __builtin_msa_splati_w (v4i32, imm0_3);
-v2i64 __builtin_msa_splati_d (v2i64, imm0_1);
-
-v16i8 __builtin_msa_sra_b (v16i8, v16i8);
-v8i16 __builtin_msa_sra_h (v8i16, v8i16);
-v4i32 __builtin_msa_sra_w (v4i32, v4i32);
-v2i64 __builtin_msa_sra_d (v2i64, v2i64);
-
-v16i8 __builtin_msa_srai_b (v16i8, imm0_7);
-v8i16 __builtin_msa_srai_h (v8i16, imm0_15);
-v4i32 __builtin_msa_srai_w (v4i32, imm0_31);
-v2i64 __builtin_msa_srai_d (v2i64, imm0_63);
-
-v16i8 __builtin_msa_srar_b (v16i8, v16i8);
-v8i16 __builtin_msa_srar_h (v8i16, v8i16);
-v4i32 __builtin_msa_srar_w (v4i32, v4i32);
-v2i64 __builtin_msa_srar_d (v2i64, v2i64);
-
-v16i8 __builtin_msa_srari_b (v16i8, imm0_7);
-v8i16 __builtin_msa_srari_h (v8i16, imm0_15);
-v4i32 __builtin_msa_srari_w (v4i32, imm0_31);
-v2i64 __builtin_msa_srari_d (v2i64, imm0_63);
-
-v16i8 __builtin_msa_srl_b (v16i8, v16i8);
-v8i16 __builtin_msa_srl_h (v8i16, v8i16);
-v4i32 __builtin_msa_srl_w (v4i32, v4i32);
-v2i64 __builtin_msa_srl_d (v2i64, v2i64);
-
-v16i8 __builtin_msa_srli_b (v16i8, imm0_7);
-v8i16 __builtin_msa_srli_h (v8i16, imm0_15);
-v4i32 __builtin_msa_srli_w (v4i32, imm0_31);
-v2i64 __builtin_msa_srli_d (v2i64, imm0_63);
-
-v16i8 __builtin_msa_srlr_b (v16i8, v16i8);
-v8i16 __builtin_msa_srlr_h (v8i16, v8i16);
-v4i32 __builtin_msa_srlr_w (v4i32, v4i32);
-v2i64 __builtin_msa_srlr_d (v2i64, v2i64);
-
-v16i8 __builtin_msa_srlri_b (v16i8, imm0_7);
-v8i16 __builtin_msa_srlri_h (v8i16, imm0_15);
-v4i32 __builtin_msa_srlri_w (v4i32, imm0_31);
-v2i64 __builtin_msa_srlri_d (v2i64, imm0_63);
-
-void __builtin_msa_st_b (v16i8, void *, imm_n512_511);
-void __builtin_msa_st_h (v8i16, void *, imm_n1024_1022);
-void __builtin_msa_st_w (v4i32, void *, imm_n2048_2044);
-void __builtin_msa_st_d (v2i64, void *, imm_n4096_4088);
-
-v16i8 __builtin_msa_subs_s_b (v16i8, v16i8);
-v8i16 __builtin_msa_subs_s_h (v8i16, v8i16);
-v4i32 __builtin_msa_subs_s_w (v4i32, v4i32);
-v2i64 __builtin_msa_subs_s_d (v2i64, v2i64);
-
-v16u8 __builtin_msa_subs_u_b (v16u8, v16u8);
-v8u16 __builtin_msa_subs_u_h (v8u16, v8u16);
-v4u32 __builtin_msa_subs_u_w (v4u32, v4u32);
-v2u64 __builtin_msa_subs_u_d (v2u64, v2u64);
-
-v16u8 __builtin_msa_subsus_u_b (v16u8, v16i8);
-v8u16 __builtin_msa_subsus_u_h (v8u16, v8i16);
-v4u32 __builtin_msa_subsus_u_w (v4u32, v4i32);
-v2u64 __builtin_msa_subsus_u_d (v2u64, v2i64);
-
-v16i8 __builtin_msa_subsuu_s_b (v16u8, v16u8);
-v8i16 __builtin_msa_subsuu_s_h (v8u16, v8u16);
-v4i32 __builtin_msa_subsuu_s_w (v4u32, v4u32);
-v2i64 __builtin_msa_subsuu_s_d (v2u64, v2u64);
-
-v16i8 __builtin_msa_subv_b (v16i8, v16i8);
-v8i16 __builtin_msa_subv_h (v8i16, v8i16);
-v4i32 __builtin_msa_subv_w (v4i32, v4i32);
-v2i64 __builtin_msa_subv_d (v2i64, v2i64);
-
-v16i8 __builtin_msa_subvi_b (v16i8, imm0_31);
-v8i16 __builtin_msa_subvi_h (v8i16, imm0_31);
-v4i32 __builtin_msa_subvi_w (v4i32, imm0_31);
-v2i64 __builtin_msa_subvi_d (v2i64, imm0_31);
-
-v16i8 __builtin_msa_vshf_b (v16i8, v16i8, v16i8);
-v8i16 __builtin_msa_vshf_h (v8i16, v8i16, v8i16);
-v4i32 __builtin_msa_vshf_w (v4i32, v4i32, v4i32);
-v2i64 __builtin_msa_vshf_d (v2i64, v2i64, v2i64);
-
-v16u8 __builtin_msa_xor_v (v16u8, v16u8);
-
-v16u8 __builtin_msa_xori_b (v16u8, imm0_255);
-@end smallexample
-
-@node Other MIPS Built-in Functions
-@subsection Other MIPS Built-in Functions
-
-GCC provides other MIPS-specific built-in functions:
-
-@table @code
-@item void __builtin_mips_cache (int @var{op}, const volatile void *@var{addr})
-Insert a @samp{cache} instruction with operands @var{op} and @var{addr}.
-GCC defines the preprocessor macro @code{___GCC_HAVE_BUILTIN_MIPS_CACHE}
-when this function is available.
-
-@item unsigned int __builtin_mips_get_fcsr (void)
-@itemx void __builtin_mips_set_fcsr (unsigned int @var{value})
-Get and set the contents of the floating-point control and status register
-(FPU control register 31). These functions are only available in hard-float
-code but can be called in both MIPS16 and non-MIPS16 contexts.
-
-@code{__builtin_mips_set_fcsr} can be used to change any bit of the
-register except the condition codes, which GCC assumes are preserved.
-@end table
-
-@node MSP430 Built-in Functions
-@subsection MSP430 Built-in Functions
-
-GCC provides a couple of special builtin functions to aid in the
-writing of interrupt handlers in C.
-
-@table @code
-@item __bic_SR_register_on_exit (int @var{mask})
-This clears the indicated bits in the saved copy of the status register
-currently residing on the stack. This only works inside interrupt
-handlers and the changes to the status register will only take affect
-once the handler returns.
-
-@item __bis_SR_register_on_exit (int @var{mask})
-This sets the indicated bits in the saved copy of the status register
-currently residing on the stack. This only works inside interrupt
-handlers and the changes to the status register will only take affect
-once the handler returns.
-
-@item __delay_cycles (long long @var{cycles})
-This inserts an instruction sequence that takes exactly @var{cycles}
-cycles (between 0 and about 17E9) to complete. The inserted sequence
-may use jumps, loops, or no-ops, and does not interfere with any other
-instructions. Note that @var{cycles} must be a compile-time constant
-integer - that is, you must pass a number, not a variable that may be
-optimized to a constant later. The number of cycles delayed by this
-builtin is exact.
-@end table
-
-@node NDS32 Built-in Functions
-@subsection NDS32 Built-in Functions
-
-These built-in functions are available for the NDS32 target:
-
-@deftypefn {Built-in Function} void __builtin_nds32_isync (int *@var{addr})
-Insert an ISYNC instruction into the instruction stream where
-@var{addr} is an instruction address for serialization.
-@end deftypefn
-
-@deftypefn {Built-in Function} void __builtin_nds32_isb (void)
-Insert an ISB instruction into the instruction stream.
-@end deftypefn
-
-@deftypefn {Built-in Function} int __builtin_nds32_mfsr (int @var{sr})
-Return the content of a system register which is mapped by @var{sr}.
-@end deftypefn
-
-@deftypefn {Built-in Function} int __builtin_nds32_mfusr (int @var{usr})
-Return the content of a user space register which is mapped by @var{usr}.
-@end deftypefn
-
-@deftypefn {Built-in Function} void __builtin_nds32_mtsr (int @var{value}, int @var{sr})
-Move the @var{value} to a system register which is mapped by @var{sr}.
-@end deftypefn
-
-@deftypefn {Built-in Function} void __builtin_nds32_mtusr (int @var{value}, int @var{usr})
-Move the @var{value} to a user space register which is mapped by @var{usr}.
-@end deftypefn
-
-@deftypefn {Built-in Function} void __builtin_nds32_setgie_en (void)
-Enable global interrupt.
-@end deftypefn
-
-@deftypefn {Built-in Function} void __builtin_nds32_setgie_dis (void)
-Disable global interrupt.
-@end deftypefn
-
-@node picoChip Built-in Functions
-@subsection picoChip Built-in Functions
-
-GCC provides an interface to selected machine instructions from the
-picoChip instruction set.
-
-@table @code
-@item int __builtin_sbc (int @var{value})
-Sign bit count. Return the number of consecutive bits in @var{value}
-that have the same value as the sign bit. The result is the number of
-leading sign bits minus one, giving the number of redundant sign bits in
-@var{value}.
-
-@item int __builtin_byteswap (int @var{value})
-Byte swap. Return the result of swapping the upper and lower bytes of
-@var{value}.
-
-@item int __builtin_brev (int @var{value})
-Bit reversal. Return the result of reversing the bits in
-@var{value}. Bit 15 is swapped with bit 0, bit 14 is swapped with bit 1,
-and so on.
-
-@item int __builtin_adds (int @var{x}, int @var{y})
-Saturating addition. Return the result of adding @var{x} and @var{y},
-storing the value 32767 if the result overflows.
-
-@item int __builtin_subs (int @var{x}, int @var{y})
-Saturating subtraction. Return the result of subtracting @var{y} from
-@var{x}, storing the value @minus{}32768 if the result overflows.
-
-@item void __builtin_halt (void)
-Halt. The processor stops execution. This built-in is useful for
-implementing assertions.
-
-@end table
-
-@node Basic PowerPC Built-in Functions
-@subsection Basic PowerPC Built-in Functions
-
-@menu
-* Basic PowerPC Built-in Functions Available on all Configurations::
-* Basic PowerPC Built-in Functions Available on ISA 2.05::
-* Basic PowerPC Built-in Functions Available on ISA 2.06::
-* Basic PowerPC Built-in Functions Available on ISA 2.07::
-* Basic PowerPC Built-in Functions Available on ISA 3.0::
-* Basic PowerPC Built-in Functions Available on ISA 3.1::
-@end menu
-
-This section describes PowerPC built-in functions that do not require
-the inclusion of any special header files to declare prototypes or
-provide macro definitions. The sections that follow describe
-additional PowerPC built-in functions.
-
-@node Basic PowerPC Built-in Functions Available on all Configurations
-@subsubsection Basic PowerPC Built-in Functions Available on all Configurations
-
-@deftypefn {Built-in Function} void __builtin_cpu_init (void)
-This function is a @code{nop} on the PowerPC platform and is included solely
-to maintain API compatibility with the x86 builtins.
-@end deftypefn
-
-@deftypefn {Built-in Function} int __builtin_cpu_is (const char *@var{cpuname})
-This function returns a value of @code{1} if the run-time CPU is of type
-@var{cpuname} and returns @code{0} otherwise
-
-The @code{__builtin_cpu_is} function requires GLIBC 2.23 or newer
-which exports the hardware capability bits. GCC defines the macro
-@code{__BUILTIN_CPU_SUPPORTS__} if the @code{__builtin_cpu_supports}
-built-in function is fully supported.
-
-If GCC was configured to use a GLIBC before 2.23, the built-in
-function @code{__builtin_cpu_is} always returns a 0 and the compiler
-issues a warning.
-
-The following CPU names can be detected:
-
-@table @samp
-@item power10
-IBM POWER10 Server CPU.
-@item power9
-IBM POWER9 Server CPU.
-@item power8
-IBM POWER8 Server CPU.
-@item power7
-IBM POWER7 Server CPU.
-@item power6x
-IBM POWER6 Server CPU (RAW mode).
-@item power6
-IBM POWER6 Server CPU (Architected mode).
-@item power5+
-IBM POWER5+ Server CPU.
-@item power5
-IBM POWER5 Server CPU.
-@item ppc970
-IBM 970 Server CPU (ie, Apple G5).
-@item power4
-IBM POWER4 Server CPU.
-@item ppca2
-IBM A2 64-bit Embedded CPU
-@item ppc476
-IBM PowerPC 476FP 32-bit Embedded CPU.
-@item ppc464
-IBM PowerPC 464 32-bit Embedded CPU.
-@item ppc440
-PowerPC 440 32-bit Embedded CPU.
-@item ppc405
-PowerPC 405 32-bit Embedded CPU.
-@item ppc-cell-be
-IBM PowerPC Cell Broadband Engine Architecture CPU.
-@end table
-
-Here is an example:
-@smallexample
-#ifdef __BUILTIN_CPU_SUPPORTS__
- if (__builtin_cpu_is ("power8"))
- @{
- do_power8 (); // POWER8 specific implementation.
- @}
- else
-#endif
- @{
- do_generic (); // Generic implementation.
- @}
-@end smallexample
-@end deftypefn
-
-@deftypefn {Built-in Function} int __builtin_cpu_supports (const char *@var{feature})
-This function returns a value of @code{1} if the run-time CPU supports the HWCAP
-feature @var{feature} and returns @code{0} otherwise.
-
-The @code{__builtin_cpu_supports} function requires GLIBC 2.23 or
-newer which exports the hardware capability bits. GCC defines the
-macro @code{__BUILTIN_CPU_SUPPORTS__} if the
-@code{__builtin_cpu_supports} built-in function is fully supported.
-
-If GCC was configured to use a GLIBC before 2.23, the built-in
-function @code{__builtin_cpu_supports} always returns a 0 and the
-compiler issues a warning.
-
-The following features can be
-detected:
-
-@table @samp
-@item 4xxmac
-4xx CPU has a Multiply Accumulator.
-@item altivec
-CPU has a SIMD/Vector Unit.
-@item arch_2_05
-CPU supports ISA 2.05 (eg, POWER6)
-@item arch_2_06
-CPU supports ISA 2.06 (eg, POWER7)
-@item arch_2_07
-CPU supports ISA 2.07 (eg, POWER8)
-@item arch_3_00
-CPU supports ISA 3.0 (eg, POWER9)
-@item arch_3_1
-CPU supports ISA 3.1 (eg, POWER10)
-@item archpmu
-CPU supports the set of compatible performance monitoring events.
-@item booke
-CPU supports the Embedded ISA category.
-@item cellbe
-CPU has a CELL broadband engine.
-@item darn
-CPU supports the @code{darn} (deliver a random number) instruction.
-@item dfp
-CPU has a decimal floating point unit.
-@item dscr
-CPU supports the data stream control register.
-@item ebb
-CPU supports event base branching.
-@item efpdouble
-CPU has a SPE double precision floating point unit.
-@item efpsingle
-CPU has a SPE single precision floating point unit.
-@item fpu
-CPU has a floating point unit.
-@item htm
-CPU has hardware transaction memory instructions.
-@item htm-nosc
-Kernel aborts hardware transactions when a syscall is made.
-@item htm-no-suspend
-CPU supports hardware transaction memory but does not support the
-@code{tsuspend.} instruction.
-@item ic_snoop
-CPU supports icache snooping capabilities.
-@item ieee128
-CPU supports 128-bit IEEE binary floating point instructions.
-@item isel
-CPU supports the integer select instruction.
-@item mma
-CPU supports the matrix-multiply assist instructions.
-@item mmu
-CPU has a memory management unit.
-@item notb
-CPU does not have a timebase (eg, 601 and 403gx).
-@item pa6t
-CPU supports the PA Semi 6T CORE ISA.
-@item power4
-CPU supports ISA 2.00 (eg, POWER4)
-@item power5
-CPU supports ISA 2.02 (eg, POWER5)
-@item power5+
-CPU supports ISA 2.03 (eg, POWER5+)
-@item power6x
-CPU supports ISA 2.05 (eg, POWER6) extended opcodes mffgpr and mftgpr.
-@item ppc32
-CPU supports 32-bit mode execution.
-@item ppc601
-CPU supports the old POWER ISA (eg, 601)
-@item ppc64
-CPU supports 64-bit mode execution.
-@item ppcle
-CPU supports a little-endian mode that uses address swizzling.
-@item scv
-Kernel supports system call vectored.
-@item smt
-CPU support simultaneous multi-threading.
-@item spe
-CPU has a signal processing extension unit.
-@item tar
-CPU supports the target address register.
-@item true_le
-CPU supports true little-endian mode.
-@item ucache
-CPU has unified I/D cache.
-@item vcrypto
-CPU supports the vector cryptography instructions.
-@item vsx
-CPU supports the vector-scalar extension.
-@end table
-
-Here is an example:
-@smallexample
-#ifdef __BUILTIN_CPU_SUPPORTS__
- if (__builtin_cpu_supports ("fpu"))
- @{
- asm("fadd %0,%1,%2" : "=d"(dst) : "d"(src1), "d"(src2));
- @}
- else
-#endif
- @{
- dst = __fadd (src1, src2); // Software FP addition function.
- @}
-@end smallexample
-@end deftypefn
-
-The following built-in functions are also available on all PowerPC
-processors:
-@smallexample
-uint64_t __builtin_ppc_get_timebase ();
-unsigned long __builtin_ppc_mftb ();
-double __builtin_unpack_ibm128 (__ibm128, int);
-__ibm128 __builtin_pack_ibm128 (double, double);
-double __builtin_mffs (void);
-void __builtin_mtfsf (const int, double);
-void __builtin_mtfsb0 (const int);
-void __builtin_mtfsb1 (const int);
-void __builtin_set_fpscr_rn (int);
-@end smallexample
-
-The @code{__builtin_ppc_get_timebase} and @code{__builtin_ppc_mftb}
-functions generate instructions to read the Time Base Register. The
-@code{__builtin_ppc_get_timebase} function may generate multiple
-instructions and always returns the 64 bits of the Time Base Register.
-The @code{__builtin_ppc_mftb} function always generates one instruction and
-returns the Time Base Register value as an unsigned long, throwing away
-the most significant word on 32-bit environments. The @code{__builtin_mffs}
-return the value of the FPSCR register. Note, ISA 3.0 supports the
-@code{__builtin_mffsl()} which permits software to read the control and
-non-sticky status bits in the FSPCR without the higher latency associated with
-accessing the sticky status bits. The @code{__builtin_mtfsf} takes a constant
-8-bit integer field mask and a double precision floating point argument
-and generates the @code{mtfsf} (extended mnemonic) instruction to write new
-values to selected fields of the FPSCR. The
-@code{__builtin_mtfsb0} and @code{__builtin_mtfsb1} take the bit to change
-as an argument. The valid bit range is between 0 and 31. The builtins map to
-the @code{mtfsb0} and @code{mtfsb1} instructions which take the argument and
-add 32. Hence these instructions only modify the FPSCR[32:63] bits by
-changing the specified bit to a zero or one respectively. The
-@code{__builtin_set_fpscr_rn} builtin allows changing both of the floating
-point rounding mode bits. The argument is a 2-bit value. The argument can
-either be a @code{const int} or stored in a variable. The builtin uses
-the ISA 3.0
-instruction @code{mffscrn} if available, otherwise it reads the FPSCR, masks
-the current rounding mode bits out and OR's in the new value.
-
-@node Basic PowerPC Built-in Functions Available on ISA 2.05
-@subsubsection Basic PowerPC Built-in Functions Available on ISA 2.05
-
-The basic built-in functions described in this section are
-available on the PowerPC family of processors starting with ISA 2.05
-or later. Unless specific options are explicitly disabled on the
-command line, specifying option @option{-mcpu=power6} has the effect of
-enabling the @option{-mpowerpc64}, @option{-mpowerpc-gpopt},
-@option{-mpowerpc-gfxopt}, @option{-mmfcrf}, @option{-mpopcntb},
-@option{-mfprnd}, @option{-mcmpb}, @option{-mhard-dfp}, and
-@option{-mrecip-precision} options. Specify the
-@option{-maltivec} option explicitly in
-combination with the above options if desired.
-
-The following functions require option @option{-mcmpb}.
-@smallexample
-unsigned long long __builtin_cmpb (unsigned long long int, unsigned long long int);
-unsigned int __builtin_cmpb (unsigned int, unsigned int);
-@end smallexample
-
-The @code{__builtin_cmpb} function
-performs a byte-wise compare on the contents of its two arguments,
-returning the result of the byte-wise comparison as the returned
-value. For each byte comparison, the corresponding byte of the return
-value holds 0xff if the input bytes are equal and 0 if the input bytes
-are not equal. If either of the arguments to this built-in function
-is wider than 32 bits, the function call expands into the form that
-expects @code{unsigned long long int} arguments
-which is only available on 64-bit targets.
-
-The following built-in functions are available
-when hardware decimal floating point
-(@option{-mhard-dfp}) is available:
-@smallexample
-void __builtin_set_fpscr_drn(int);
-_Decimal64 __builtin_ddedpd (int, _Decimal64);
-_Decimal128 __builtin_ddedpdq (int, _Decimal128);
-_Decimal64 __builtin_denbcd (int, _Decimal64);
-_Decimal128 __builtin_denbcdq (int, _Decimal128);
-_Decimal64 __builtin_diex (long long, _Decimal64);
-_Decimal128 _builtin_diexq (long long, _Decimal128);
-_Decimal64 __builtin_dscli (_Decimal64, int);
-_Decimal128 __builtin_dscliq (_Decimal128, int);
-_Decimal64 __builtin_dscri (_Decimal64, int);
-_Decimal128 __builtin_dscriq (_Decimal128, int);
-long long __builtin_dxex (_Decimal64);
-long long __builtin_dxexq (_Decimal128);
-_Decimal128 __builtin_pack_dec128 (unsigned long long, unsigned long long);
-unsigned long long __builtin_unpack_dec128 (_Decimal128, int);
-
-The @code{__builtin_set_fpscr_drn} builtin allows changing the three decimal
-floating point rounding mode bits. The argument is a 3-bit value. The
-argument can either be a @code{const int} or the value can be stored in
-a variable.
-The builtin uses the ISA 3.0 instruction @code{mffscdrn} if available.
-Otherwise the builtin reads the FPSCR, masks the current decimal rounding
-mode bits out and OR's in the new value.
-
-@end smallexample
-
-The following functions require @option{-mhard-float},
-@option{-mpowerpc-gfxopt}, and @option{-mpopcntb} options.
-
-@smallexample
-double __builtin_recipdiv (double, double);
-float __builtin_recipdivf (float, float);
-double __builtin_rsqrt (double);
-float __builtin_rsqrtf (float);
-@end smallexample
-
-The @code{vec_rsqrt}, @code{__builtin_rsqrt}, and
-@code{__builtin_rsqrtf} functions generate multiple instructions to
-implement the reciprocal sqrt functionality using reciprocal sqrt
-estimate instructions.
-
-The @code{__builtin_recipdiv}, and @code{__builtin_recipdivf}
-functions generate multiple instructions to implement division using
-the reciprocal estimate instructions.
-
-The following functions require @option{-mhard-float} and
-@option{-mmultiple} options.
-
-The @code{__builtin_unpack_longdouble} function takes a
-@code{long double} argument and a compile time constant of 0 or 1. If
-the constant is 0, the first @code{double} within the
-@code{long double} is returned, otherwise the second @code{double}
-is returned. The @code{__builtin_unpack_longdouble} function is only
-available if @code{long double} uses the IBM extended double
-representation.
-
-The @code{__builtin_pack_longdouble} function takes two @code{double}
-arguments and returns a @code{long double} value that combines the two
-arguments. The @code{__builtin_pack_longdouble} function is only
-available if @code{long double} uses the IBM extended double
-representation.
-
-The @code{__builtin_unpack_ibm128} function takes a @code{__ibm128}
-argument and a compile time constant of 0 or 1. If the constant is 0,
-the first @code{double} within the @code{__ibm128} is returned,
-otherwise the second @code{double} is returned.
-
-The @code{__builtin_pack_ibm128} function takes two @code{double}
-arguments and returns a @code{__ibm128} value that combines the two
-arguments.
-
-Additional built-in functions are available for the 64-bit PowerPC
-family of processors, for efficient use of 128-bit floating point
-(@code{__float128}) values.
-
-@node Basic PowerPC Built-in Functions Available on ISA 2.06
-@subsubsection Basic PowerPC Built-in Functions Available on ISA 2.06
-
-The basic built-in functions described in this section are
-available on the PowerPC family of processors starting with ISA 2.05
-or later. Unless specific options are explicitly disabled on the
-command line, specifying option @option{-mcpu=power7} has the effect of
-enabling all the same options as for @option{-mcpu=power6} in
-addition to the @option{-maltivec}, @option{-mpopcntd}, and
-@option{-mvsx} options.
-
-The following basic built-in functions require @option{-mpopcntd}:
-@smallexample
-unsigned int __builtin_addg6s (unsigned int, unsigned int);
-long long __builtin_bpermd (long long, long long);
-unsigned int __builtin_cbcdtd (unsigned int);
-unsigned int __builtin_cdtbcd (unsigned int);
-long long __builtin_divde (long long, long long);
-unsigned long long __builtin_divdeu (unsigned long long, unsigned long long);
-int __builtin_divwe (int, int);
-unsigned int __builtin_divweu (unsigned int, unsigned int);
-vector __int128 __builtin_pack_vector_int128 (long long, long long);
-void __builtin_rs6000_speculation_barrier (void);
-long long __builtin_unpack_vector_int128 (vector __int128, signed char);
-@end smallexample
-
-Of these, the @code{__builtin_divde} and @code{__builtin_divdeu} functions
-require a 64-bit environment.
-
-The following basic built-in functions, which are also supported on
-x86 targets, require @option{-mfloat128}.
-@smallexample
-__float128 __builtin_fabsq (__float128);
-__float128 __builtin_copysignq (__float128, __float128);
-__float128 __builtin_infq (void);
-__float128 __builtin_huge_valq (void);
-__float128 __builtin_nanq (void);
-__float128 __builtin_nansq (void);
-
-__float128 __builtin_sqrtf128 (__float128);
-__float128 __builtin_fmaf128 (__float128, __float128, __float128);
-@end smallexample
-
-@node Basic PowerPC Built-in Functions Available on ISA 2.07
-@subsubsection Basic PowerPC Built-in Functions Available on ISA 2.07
-
-The basic built-in functions described in this section are
-available on the PowerPC family of processors starting with ISA 2.07
-or later. Unless specific options are explicitly disabled on the
-command line, specifying option @option{-mcpu=power8} has the effect of
-enabling all the same options as for @option{-mcpu=power7} in
-addition to the @option{-mpower8-fusion}, @option{-mpower8-vector},
-@option{-mcrypto}, @option{-mhtm}, @option{-mquad-memory}, and
-@option{-mquad-memory-atomic} options.
-
-This section intentionally empty.
-
-@node Basic PowerPC Built-in Functions Available on ISA 3.0
-@subsubsection Basic PowerPC Built-in Functions Available on ISA 3.0
-
-The basic built-in functions described in this section are
-available on the PowerPC family of processors starting with ISA 3.0
-or later. Unless specific options are explicitly disabled on the
-command line, specifying option @option{-mcpu=power9} has the effect of
-enabling all the same options as for @option{-mcpu=power8} in
-addition to the @option{-misel} option.
-
-The following built-in functions are available on Linux 64-bit systems
-that use the ISA 3.0 instruction set (@option{-mcpu=power9}):
-
-@table @code
-@item __float128 __builtin_addf128_round_to_odd (__float128, __float128)
-Perform a 128-bit IEEE floating point add using round to odd as the
-rounding mode.
-@findex __builtin_addf128_round_to_odd
-
-@item __float128 __builtin_subf128_round_to_odd (__float128, __float128)
-Perform a 128-bit IEEE floating point subtract using round to odd as
-the rounding mode.
-@findex __builtin_subf128_round_to_odd
-
-@item __float128 __builtin_mulf128_round_to_odd (__float128, __float128)
-Perform a 128-bit IEEE floating point multiply using round to odd as
-the rounding mode.
-@findex __builtin_mulf128_round_to_odd
-
-@item __float128 __builtin_divf128_round_to_odd (__float128, __float128)
-Perform a 128-bit IEEE floating point divide using round to odd as
-the rounding mode.
-@findex __builtin_divf128_round_to_odd
-
-@item __float128 __builtin_sqrtf128_round_to_odd (__float128)
-Perform a 128-bit IEEE floating point square root using round to odd
-as the rounding mode.
-@findex __builtin_sqrtf128_round_to_odd
-
-@item __float128 __builtin_fmaf128_round_to_odd (__float128, __float128, __float128)
-Perform a 128-bit IEEE floating point fused multiply and add operation
-using round to odd as the rounding mode.
-@findex __builtin_fmaf128_round_to_odd
-
-@item double __builtin_truncf128_round_to_odd (__float128)
-Convert a 128-bit IEEE floating point value to @code{double} using
-round to odd as the rounding mode.
-@findex __builtin_truncf128_round_to_odd
-@end table
-
-The following additional built-in functions are also available for the
-PowerPC family of processors, starting with ISA 3.0 or later:
-@smallexample
-long long __builtin_darn (void);
-long long __builtin_darn_raw (void);
-int __builtin_darn_32 (void);
-@end smallexample
-
-The @code{__builtin_darn} and @code{__builtin_darn_raw}
-functions require a
-64-bit environment supporting ISA 3.0 or later.
-The @code{__builtin_darn} function provides a 64-bit conditioned
-random number. The @code{__builtin_darn_raw} function provides a
-64-bit raw random number. The @code{__builtin_darn_32} function
-provides a 32-bit conditioned random number.
-
-The following additional built-in functions are also available for the
-PowerPC family of processors, starting with ISA 3.0 or later:
-
-@smallexample
-int __builtin_byte_in_set (unsigned char u, unsigned long long set);
-int __builtin_byte_in_range (unsigned char u, unsigned int range);
-int __builtin_byte_in_either_range (unsigned char u, unsigned int ranges);
-
-int __builtin_dfp_dtstsfi_lt (unsigned int comparison, _Decimal64 value);
-int __builtin_dfp_dtstsfi_lt (unsigned int comparison, _Decimal128 value);
-int __builtin_dfp_dtstsfi_lt_dd (unsigned int comparison, _Decimal64 value);
-int __builtin_dfp_dtstsfi_lt_td (unsigned int comparison, _Decimal128 value);
-
-int __builtin_dfp_dtstsfi_gt (unsigned int comparison, _Decimal64 value);
-int __builtin_dfp_dtstsfi_gt (unsigned int comparison, _Decimal128 value);
-int __builtin_dfp_dtstsfi_gt_dd (unsigned int comparison, _Decimal64 value);
-int __builtin_dfp_dtstsfi_gt_td (unsigned int comparison, _Decimal128 value);
-
-int __builtin_dfp_dtstsfi_eq (unsigned int comparison, _Decimal64 value);
-int __builtin_dfp_dtstsfi_eq (unsigned int comparison, _Decimal128 value);
-int __builtin_dfp_dtstsfi_eq_dd (unsigned int comparison, _Decimal64 value);
-int __builtin_dfp_dtstsfi_eq_td (unsigned int comparison, _Decimal128 value);
-
-int __builtin_dfp_dtstsfi_ov (unsigned int comparison, _Decimal64 value);
-int __builtin_dfp_dtstsfi_ov (unsigned int comparison, _Decimal128 value);
-int __builtin_dfp_dtstsfi_ov_dd (unsigned int comparison, _Decimal64 value);
-int __builtin_dfp_dtstsfi_ov_td (unsigned int comparison, _Decimal128 value);
-
-double __builtin_mffsl(void);
-
-@end smallexample
-The @code{__builtin_byte_in_set} function requires a
-64-bit environment supporting ISA 3.0 or later. This function returns
-a non-zero value if and only if its @code{u} argument exactly equals one of
-the eight bytes contained within its 64-bit @code{set} argument.
-
-The @code{__builtin_byte_in_range} and
-@code{__builtin_byte_in_either_range} require an environment
-supporting ISA 3.0 or later. For these two functions, the
-@code{range} argument is encoded as 4 bytes, organized as
-@code{hi_1:lo_1:hi_2:lo_2}.
-The @code{__builtin_byte_in_range} function returns a
-non-zero value if and only if its @code{u} argument is within the
-range bounded between @code{lo_2} and @code{hi_2} inclusive.
-The @code{__builtin_byte_in_either_range} function returns non-zero if
-and only if its @code{u} argument is within either the range bounded
-between @code{lo_1} and @code{hi_1} inclusive or the range bounded
-between @code{lo_2} and @code{hi_2} inclusive.
-
-The @code{__builtin_dfp_dtstsfi_lt} function returns a non-zero value
-if and only if the number of signficant digits of its @code{value} argument
-is less than its @code{comparison} argument. The
-@code{__builtin_dfp_dtstsfi_lt_dd} and
-@code{__builtin_dfp_dtstsfi_lt_td} functions behave similarly, but
-require that the type of the @code{value} argument be
-@code{__Decimal64} and @code{__Decimal128} respectively.
-
-The @code{__builtin_dfp_dtstsfi_gt} function returns a non-zero value
-if and only if the number of signficant digits of its @code{value} argument
-is greater than its @code{comparison} argument. The
-@code{__builtin_dfp_dtstsfi_gt_dd} and
-@code{__builtin_dfp_dtstsfi_gt_td} functions behave similarly, but
-require that the type of the @code{value} argument be
-@code{__Decimal64} and @code{__Decimal128} respectively.
-
-The @code{__builtin_dfp_dtstsfi_eq} function returns a non-zero value
-if and only if the number of signficant digits of its @code{value} argument
-equals its @code{comparison} argument. The
-@code{__builtin_dfp_dtstsfi_eq_dd} and
-@code{__builtin_dfp_dtstsfi_eq_td} functions behave similarly, but
-require that the type of the @code{value} argument be
-@code{__Decimal64} and @code{__Decimal128} respectively.
-
-The @code{__builtin_dfp_dtstsfi_ov} function returns a non-zero value
-if and only if its @code{value} argument has an undefined number of
-significant digits, such as when @code{value} is an encoding of @code{NaN}.
-The @code{__builtin_dfp_dtstsfi_ov_dd} and
-@code{__builtin_dfp_dtstsfi_ov_td} functions behave similarly, but
-require that the type of the @code{value} argument be
-@code{__Decimal64} and @code{__Decimal128} respectively.
-
-The @code{__builtin_mffsl} uses the ISA 3.0 @code{mffsl} instruction to read
-the FPSCR. The instruction is a lower latency version of the @code{mffs}
-instruction. If the @code{mffsl} instruction is not available, then the
-builtin uses the older @code{mffs} instruction to read the FPSCR.
-
-@node Basic PowerPC Built-in Functions Available on ISA 3.1
-@subsubsection Basic PowerPC Built-in Functions Available on ISA 3.1
-
-The basic built-in functions described in this section are
-available on the PowerPC family of processors starting with ISA 3.1.
-Unless specific options are explicitly disabled on the
-command line, specifying option @option{-mcpu=power10} has the effect of
-enabling all the same options as for @option{-mcpu=power9}.
-
-The following built-in functions are available on Linux 64-bit systems
-that use a future architecture instruction set (@option{-mcpu=power10}):
-
-@smallexample
-@exdent unsigned long long
-@exdent __builtin_cfuged (unsigned long long, unsigned long long)
-@end smallexample
-Perform a 64-bit centrifuge operation, as if implemented by the
-@code{cfuged} instruction.
-@findex __builtin_cfuged
-
-@smallexample
-@exdent unsigned long long
-@exdent __builtin_cntlzdm (unsigned long long, unsigned long long)
-@end smallexample
-Perform a 64-bit count leading zeros operation under mask, as if
-implemented by the @code{cntlzdm} instruction.
-@findex __builtin_cntlzdm
-
-@smallexample
-@exdent unsigned long long
-@exdent __builtin_cnttzdm (unsigned long long, unsigned long long)
-@end smallexample
-Perform a 64-bit count trailing zeros operation under mask, as if
-implemented by the @code{cnttzdm} instruction.
-@findex __builtin_cnttzdm
-
-@smallexample
-@exdent unsigned long long
-@exdent __builtin_pdepd (unsigned long long, unsigned long long)
-@end smallexample
-Perform a 64-bit parallel bits deposit operation, as if implemented by the
-@code{pdepd} instruction.
-@findex __builtin_pdepd
-
-@smallexample
-@exdent unsigned long long
-@exdent __builtin_pextd (unsigned long long, unsigned long long)
-@end smallexample
-Perform a 64-bit parallel bits extract operation, as if implemented by the
-@code{pextd} instruction.
-@findex __builtin_pextd
-
-@smallexample
-@exdent vector signed __int128 vsx_xl_sext (signed long long, signed char *)
-
-@exdent vector signed __int128 vsx_xl_sext (signed long long, signed short *)
-
-@exdent vector signed __int128 vsx_xl_sext (signed long long, signed int *)
-
-@exdent vector signed __int128 vsx_xl_sext (signed long long, signed long long *)
-
-@exdent vector unsigned __int128 vsx_xl_zext (signed long long, unsigned char *)
-
-@exdent vector unsigned __int128 vsx_xl_zext (signed long long, unsigned short *)
-
-@exdent vector unsigned __int128 vsx_xl_zext (signed long long, unsigned int *)
-
-@exdent vector unsigned __int128 vsx_xl_zext (signed long long, unsigned long long *)
-@end smallexample
-
-Load (and sign extend) to an __int128 vector, as if implemented by the ISA 3.1
-@code{lxvrbx}, @code{lxvrhx}, @code{lxvrwx}, and @code{lxvrdx} instructions.
-@findex vsx_xl_sext
-@findex vsx_xl_zext
-
-@smallexample
-@exdent void vec_xst_trunc (vector signed __int128, signed long long, signed char *)
-
-@exdent void vec_xst_trunc (vector signed __int128, signed long long, signed short *)
-
-@exdent void vec_xst_trunc (vector signed __int128, signed long long, signed int *)
-
-@exdent void vec_xst_trunc (vector signed __int128, signed long long, signed long long *)
-
-@exdent void vec_xst_trunc (vector unsigned __int128, signed long long, unsigned char *)
-
-@exdent void vec_xst_trunc (vector unsigned __int128, signed long long, unsigned short *)
-
-@exdent void vec_xst_trunc (vector unsigned __int128, signed long long, unsigned int *)
-
-@exdent void vec_xst_trunc (vector unsigned __int128, signed long long, unsigned long long *)
-@end smallexample
-
-Truncate and store the rightmost element of a vector, as if implemented by the
-ISA 3.1 @code{stxvrbx}, @code{stxvrhx}, @code{stxvrwx}, and @code{stxvrdx}
-instructions.
-@findex vec_xst_trunc
-
-@node PowerPC AltiVec/VSX Built-in Functions
-@subsection PowerPC AltiVec/VSX Built-in Functions
-
-GCC provides an interface for the PowerPC family of processors to access
-the AltiVec operations described in Motorola's AltiVec Programming
-Interface Manual. The interface is made available by including
-@code{<altivec.h>} and using @option{-maltivec} and
-@option{-mabi=altivec}. The interface supports the following vector
-types.
-
-@smallexample
-vector unsigned char
-vector signed char
-vector bool char
-
-vector unsigned short
-vector signed short
-vector bool short
-vector pixel
-
-vector unsigned int
-vector signed int
-vector bool int
-vector float
-@end smallexample
-
-GCC's implementation of the high-level language interface available from
-C and C++ code differs from Motorola's documentation in several ways.
-
-@itemize @bullet
-
-@item
-A vector constant is a list of constant expressions within curly braces.
-
-@item
-A vector initializer requires no cast if the vector constant is of the
-same type as the variable it is initializing.
-
-@item
-If @code{signed} or @code{unsigned} is omitted, the signedness of the
-vector type is the default signedness of the base type. The default
-varies depending on the operating system, so a portable program should
-always specify the signedness.
-
-@item
-Compiling with @option{-maltivec} adds keywords @code{__vector},
-@code{vector}, @code{__pixel}, @code{pixel}, @code{__bool} and
-@code{bool}. When compiling ISO C, the context-sensitive substitution
-of the keywords @code{vector}, @code{pixel} and @code{bool} is
-disabled. To use them, you must include @code{<altivec.h>} instead.
-
-@item
-GCC allows using a @code{typedef} name as the type specifier for a
-vector type, but only under the following circumstances:
-
-@itemize @bullet
-
-@item
-When using @code{__vector} instead of @code{vector}; for example,
-
-@smallexample
-typedef signed short int16;
-__vector int16 data;
-@end smallexample
-
-@item
-When using @code{vector} in keyword-and-predefine mode; for example,
-
-@smallexample
-typedef signed short int16;
-vector int16 data;
-@end smallexample
-
-Note that keyword-and-predefine mode is enabled by disabling GNU
-extensions (e.g., by using @code{-std=c11}) and including
-@code{<altivec.h>}.
-@end itemize
-
-@item
-For C, overloaded functions are implemented with macros so the following
-does not work:
-
-@smallexample
- vec_add ((vector signed int)@{1, 2, 3, 4@}, foo);
-@end smallexample
-
-@noindent
-Since @code{vec_add} is a macro, the vector constant in the example
-is treated as four separate arguments. Wrap the entire argument in
-parentheses for this to work.
-@end itemize
-
-@emph{Note:} Only the @code{<altivec.h>} interface is supported.
-Internally, GCC uses built-in functions to achieve the functionality in
-the aforementioned header file, but they are not supported and are
-subject to change without notice.
-
-GCC complies with the Power Vector Intrinsic Programming Reference (PVIPR),
-which may be found at
-@uref{https://openpowerfoundation.org/?resource_lib=power-vector-intrinsic-programming-reference}.
-Chapter 4 of this document fully documents the vector API interfaces
-that must be
-provided by compliant compilers. Programmers should preferentially use
-the interfaces described therein. However, historically GCC has provided
-additional interfaces for access to vector instructions. These are
-briefly described below. Where the PVIPR provides a portable interface,
-other functions in GCC that provide the same capabilities should be
-considered deprecated.
-
-The PVIPR documents the following overloaded functions:
-
-@multitable @columnfractions 0.33 0.33 0.33
-
-@item @code{vec_abs}
-@tab @code{vec_absd}
-@tab @code{vec_abss}
-@item @code{vec_add}
-@tab @code{vec_addc}
-@tab @code{vec_adde}
-@item @code{vec_addec}
-@tab @code{vec_adds}
-@tab @code{vec_all_eq}
-@item @code{vec_all_ge}
-@tab @code{vec_all_gt}
-@tab @code{vec_all_in}
-@item @code{vec_all_le}
-@tab @code{vec_all_lt}
-@tab @code{vec_all_nan}
-@item @code{vec_all_ne}
-@tab @code{vec_all_nge}
-@tab @code{vec_all_ngt}
-@item @code{vec_all_nle}
-@tab @code{vec_all_nlt}
-@tab @code{vec_all_numeric}
-@item @code{vec_and}
-@tab @code{vec_andc}
-@tab @code{vec_any_eq}
-@item @code{vec_any_ge}
-@tab @code{vec_any_gt}
-@tab @code{vec_any_le}
-@item @code{vec_any_lt}
-@tab @code{vec_any_nan}
-@tab @code{vec_any_ne}
-@item @code{vec_any_nge}
-@tab @code{vec_any_ngt}
-@tab @code{vec_any_nle}
-@item @code{vec_any_nlt}
-@tab @code{vec_any_numeric}
-@tab @code{vec_any_out}
-@item @code{vec_avg}
-@tab @code{vec_bperm}
-@tab @code{vec_ceil}
-@item @code{vec_cipher_be}
-@tab @code{vec_cipherlast_be}
-@tab @code{vec_cmpb}
-@item @code{vec_cmpeq}
-@tab @code{vec_cmpge}
-@tab @code{vec_cmpgt}
-@item @code{vec_cmple}
-@tab @code{vec_cmplt}
-@tab @code{vec_cmpne}
-@item @code{vec_cmpnez}
-@tab @code{vec_cntlz}
-@tab @code{vec_cntlz_lsbb}
-@item @code{vec_cnttz}
-@tab @code{vec_cnttz_lsbb}
-@tab @code{vec_cpsgn}
-@item @code{vec_ctf}
-@tab @code{vec_cts}
-@tab @code{vec_ctu}
-@item @code{vec_div}
-@tab @code{vec_double}
-@tab @code{vec_doublee}
-@item @code{vec_doubleh}
-@tab @code{vec_doublel}
-@tab @code{vec_doubleo}
-@item @code{vec_eqv}
-@tab @code{vec_expte}
-@tab @code{vec_extract}
-@item @code{vec_extract_exp}
-@tab @code{vec_extract_fp32_from_shorth}
-@tab @code{vec_extract_fp32_from_shortl}
-@item @code{vec_extract_sig}
-@tab @code{vec_extract_4b}
-@tab @code{vec_first_match_index}
-@item @code{vec_first_match_or_eos_index}
-@tab @code{vec_first_mismatch_index}
-@tab @code{vec_first_mismatch_or_eos_index}
-@item @code{vec_float}
-@tab @code{vec_float2}
-@tab @code{vec_floate}
-@item @code{vec_floato}
-@tab @code{vec_floor}
-@tab @code{vec_gb}
-@item @code{vec_insert}
-@tab @code{vec_insert_exp}
-@tab @code{vec_insert4b}
-@item @code{vec_ld}
-@tab @code{vec_lde}
-@tab @code{vec_ldl}
-@item @code{vec_loge}
-@tab @code{vec_madd}
-@tab @code{vec_madds}
-@item @code{vec_max}
-@tab @code{vec_mergee}
-@tab @code{vec_mergeh}
-@item @code{vec_mergel}
-@tab @code{vec_mergeo}
-@tab @code{vec_mfvscr}
-@item @code{vec_min}
-@tab @code{vec_mradds}
-@tab @code{vec_msub}
-@item @code{vec_msum}
-@tab @code{vec_msums}
-@tab @code{vec_mtvscr}
-@item @code{vec_mul}
-@tab @code{vec_mule}
-@tab @code{vec_mulo}
-@item @code{vec_nabs}
-@tab @code{vec_nand}
-@tab @code{vec_ncipher_be}
-@item @code{vec_ncipherlast_be}
-@tab @code{vec_nearbyint}
-@tab @code{vec_neg}
-@item @code{vec_nmadd}
-@tab @code{vec_nmsub}
-@tab @code{vec_nor}
-@item @code{vec_or}
-@tab @code{vec_orc}
-@tab @code{vec_pack}
-@item @code{vec_pack_to_short_fp32}
-@tab @code{vec_packpx}
-@tab @code{vec_packs}
-@item @code{vec_packsu}
-@tab @code{vec_parity_lsbb}
-@tab @code{vec_perm}
-@item @code{vec_permxor}
-@tab @code{vec_pmsum_be}
-@tab @code{vec_popcnt}
-@item @code{vec_re}
-@tab @code{vec_recipdiv}
-@tab @code{vec_revb}
-@item @code{vec_reve}
-@tab @code{vec_rint}
-@tab @code{vec_rl}
-@item @code{vec_rlmi}
-@tab @code{vec_rlnm}
-@tab @code{vec_round}
-@item @code{vec_rsqrt}
-@tab @code{vec_rsqrte}
-@tab @code{vec_sbox_be}
-@item @code{vec_sel}
-@tab @code{vec_shasigma_be}
-@tab @code{vec_signed}
-@item @code{vec_signed2}
-@tab @code{vec_signede}
-@tab @code{vec_signedo}
-@item @code{vec_sl}
-@tab @code{vec_sld}
-@tab @code{vec_sldw}
-@item @code{vec_sll}
-@tab @code{vec_slo}
-@tab @code{vec_slv}
-@item @code{vec_splat}
-@tab @code{vec_splat_s8}
-@tab @code{vec_splat_s16}
-@item @code{vec_splat_s32}
-@tab @code{vec_splat_u8}
-@tab @code{vec_splat_u16}
-@item @code{vec_splat_u32}
-@tab @code{vec_splats}
-@tab @code{vec_sqrt}
-@item @code{vec_sr}
-@tab @code{vec_sra}
-@tab @code{vec_srl}
-@item @code{vec_sro}
-@tab @code{vec_srv}
-@tab @code{vec_st}
-@item @code{vec_ste}
-@tab @code{vec_stl}
-@tab @code{vec_sub}
-@item @code{vec_subc}
-@tab @code{vec_sube}
-@tab @code{vec_subec}
-@item @code{vec_subs}
-@tab @code{vec_sum2s}
-@tab @code{vec_sum4s}
-@item @code{vec_sums}
-@tab @code{vec_test_data_class}
-@tab @code{vec_trunc}
-@item @code{vec_unpackh}
-@tab @code{vec_unpackl}
-@tab @code{vec_unsigned}
-@item @code{vec_unsigned2}
-@tab @code{vec_unsignede}
-@tab @code{vec_unsignedo}
-@item @code{vec_xl}
-@tab @code{vec_xl_be}
-@tab @code{vec_xl_len}
-@item @code{vec_xl_len_r}
-@tab @code{vec_xor}
-@tab @code{vec_xst}
-@item @code{vec_xst_be}
-@tab @code{vec_xst_len}
-@tab @code{vec_xst_len_r}
-
-@end multitable
-
-@menu
-* PowerPC AltiVec Built-in Functions on ISA 2.05::
-* PowerPC AltiVec Built-in Functions Available on ISA 2.06::
-* PowerPC AltiVec Built-in Functions Available on ISA 2.07::
-* PowerPC AltiVec Built-in Functions Available on ISA 3.0::
-* PowerPC AltiVec Built-in Functions Available on ISA 3.1::
-@end menu
-
-@node PowerPC AltiVec Built-in Functions on ISA 2.05
-@subsubsection PowerPC AltiVec Built-in Functions on ISA 2.05
-
-The following interfaces are supported for the generic and specific
-AltiVec operations and the AltiVec predicates. In cases where there
-is a direct mapping between generic and specific operations, only the
-generic names are shown here, although the specific operations can also
-be used.
-
-Arguments that are documented as @code{const int} require literal
-integral values within the range required for that operation.
-
-Only functions excluded from the PVIPR are listed here.
-
-@smallexample
-void vec_dss (const int);
-
-void vec_dssall (void);
-
-void vec_dst (const vector unsigned char *, int, const int);
-void vec_dst (const vector signed char *, int, const int);
-void vec_dst (const vector bool char *, int, const int);
-void vec_dst (const vector unsigned short *, int, const int);
-void vec_dst (const vector signed short *, int, const int);
-void vec_dst (const vector bool short *, int, const int);
-void vec_dst (const vector pixel *, int, const int);
-void vec_dst (const vector unsigned int *, int, const int);
-void vec_dst (const vector signed int *, int, const int);
-void vec_dst (const vector bool int *, int, const int);
-void vec_dst (const vector float *, int, const int);
-void vec_dst (const unsigned char *, int, const int);
-void vec_dst (const signed char *, int, const int);
-void vec_dst (const unsigned short *, int, const int);
-void vec_dst (const short *, int, const int);
-void vec_dst (const unsigned int *, int, const int);
-void vec_dst (const int *, int, const int);
-void vec_dst (const float *, int, const int);
-
-void vec_dstst (const vector unsigned char *, int, const int);
-void vec_dstst (const vector signed char *, int, const int);
-void vec_dstst (const vector bool char *, int, const int);
-void vec_dstst (const vector unsigned short *, int, const int);
-void vec_dstst (const vector signed short *, int, const int);
-void vec_dstst (const vector bool short *, int, const int);
-void vec_dstst (const vector pixel *, int, const int);
-void vec_dstst (const vector unsigned int *, int, const int);
-void vec_dstst (const vector signed int *, int, const int);
-void vec_dstst (const vector bool int *, int, const int);
-void vec_dstst (const vector float *, int, const int);
-void vec_dstst (const unsigned char *, int, const int);
-void vec_dstst (const signed char *, int, const int);
-void vec_dstst (const unsigned short *, int, const int);
-void vec_dstst (const short *, int, const int);
-void vec_dstst (const unsigned int *, int, const int);
-void vec_dstst (const int *, int, const int);
-void vec_dstst (const unsigned long *, int, const int);
-void vec_dstst (const long *, int, const int);
-void vec_dstst (const float *, int, const int);
-
-void vec_dststt (const vector unsigned char *, int, const int);
-void vec_dststt (const vector signed char *, int, const int);
-void vec_dststt (const vector bool char *, int, const int);
-void vec_dststt (const vector unsigned short *, int, const int);
-void vec_dststt (const vector signed short *, int, const int);
-void vec_dststt (const vector bool short *, int, const int);
-void vec_dststt (const vector pixel *, int, const int);
-void vec_dststt (const vector unsigned int *, int, const int);
-void vec_dststt (const vector signed int *, int, const int);
-void vec_dststt (const vector bool int *, int, const int);
-void vec_dststt (const vector float *, int, const int);
-void vec_dststt (const unsigned char *, int, const int);
-void vec_dststt (const signed char *, int, const int);
-void vec_dststt (const unsigned short *, int, const int);
-void vec_dststt (const short *, int, const int);
-void vec_dststt (const unsigned int *, int, const int);
-void vec_dststt (const int *, int, const int);
-void vec_dststt (const float *, int, const int);
-
-void vec_dstt (const vector unsigned char *, int, const int);
-void vec_dstt (const vector signed char *, int, const int);
-void vec_dstt (const vector bool char *, int, const int);
-void vec_dstt (const vector unsigned short *, int, const int);
-void vec_dstt (const vector signed short *, int, const int);
-void vec_dstt (const vector bool short *, int, const int);
-void vec_dstt (const vector pixel *, int, const int);
-void vec_dstt (const vector unsigned int *, int, const int);
-void vec_dstt (const vector signed int *, int, const int);
-void vec_dstt (const vector bool int *, int, const int);
-void vec_dstt (const vector float *, int, const int);
-void vec_dstt (const unsigned char *, int, const int);
-void vec_dstt (const signed char *, int, const int);
-void vec_dstt (const unsigned short *, int, const int);
-void vec_dstt (const short *, int, const int);
-void vec_dstt (const unsigned int *, int, const int);
-void vec_dstt (const int *, int, const int);
-void vec_dstt (const float *, int, const int);
-
-vector signed char vec_lvebx (int, char *);
-vector unsigned char vec_lvebx (int, unsigned char *);
-
-vector signed short vec_lvehx (int, short *);
-vector unsigned short vec_lvehx (int, unsigned short *);
-
-vector float vec_lvewx (int, float *);
-vector signed int vec_lvewx (int, int *);
-vector unsigned int vec_lvewx (int, unsigned int *);
-
-vector unsigned char vec_lvsl (int, const unsigned char *);
-vector unsigned char vec_lvsl (int, const signed char *);
-vector unsigned char vec_lvsl (int, const unsigned short *);
-vector unsigned char vec_lvsl (int, const short *);
-vector unsigned char vec_lvsl (int, const unsigned int *);
-vector unsigned char vec_lvsl (int, const int *);
-vector unsigned char vec_lvsl (int, const float *);
-
-vector unsigned char vec_lvsr (int, const unsigned char *);
-vector unsigned char vec_lvsr (int, const signed char *);
-vector unsigned char vec_lvsr (int, const unsigned short *);
-vector unsigned char vec_lvsr (int, const short *);
-vector unsigned char vec_lvsr (int, const unsigned int *);
-vector unsigned char vec_lvsr (int, const int *);
-vector unsigned char vec_lvsr (int, const float *);
-
-void vec_stvebx (vector signed char, int, signed char *);
-void vec_stvebx (vector unsigned char, int, unsigned char *);
-void vec_stvebx (vector bool char, int, signed char *);
-void vec_stvebx (vector bool char, int, unsigned char *);
-
-void vec_stvehx (vector signed short, int, short *);
-void vec_stvehx (vector unsigned short, int, unsigned short *);
-void vec_stvehx (vector bool short, int, short *);
-void vec_stvehx (vector bool short, int, unsigned short *);
-
-void vec_stvewx (vector float, int, float *);
-void vec_stvewx (vector signed int, int, int *);
-void vec_stvewx (vector unsigned int, int, unsigned int *);
-void vec_stvewx (vector bool int, int, int *);
-void vec_stvewx (vector bool int, int, unsigned int *);
-
-vector float vec_vaddfp (vector float, vector float);
-
-vector signed char vec_vaddsbs (vector bool char, vector signed char);
-vector signed char vec_vaddsbs (vector signed char, vector bool char);
-vector signed char vec_vaddsbs (vector signed char, vector signed char);
-
-vector signed short vec_vaddshs (vector bool short, vector signed short);
-vector signed short vec_vaddshs (vector signed short, vector bool short);
-vector signed short vec_vaddshs (vector signed short, vector signed short);
-
-vector signed int vec_vaddsws (vector bool int, vector signed int);
-vector signed int vec_vaddsws (vector signed int, vector bool int);
-vector signed int vec_vaddsws (vector signed int, vector signed int);
-
-vector signed char vec_vaddubm (vector bool char, vector signed char);
-vector signed char vec_vaddubm (vector signed char, vector bool char);
-vector signed char vec_vaddubm (vector signed char, vector signed char);
-vector unsigned char vec_vaddubm (vector bool char, vector unsigned char);
-vector unsigned char vec_vaddubm (vector unsigned char, vector bool char);
-vector unsigned char vec_vaddubm (vector unsigned char, vector unsigned char);
-
-vector unsigned char vec_vaddubs (vector bool char, vector unsigned char);
-vector unsigned char vec_vaddubs (vector unsigned char, vector bool char);
-vector unsigned char vec_vaddubs (vector unsigned char, vector unsigned char);
-
-vector signed short vec_vadduhm (vector bool short, vector signed short);
-vector signed short vec_vadduhm (vector signed short, vector bool short);
-vector signed short vec_vadduhm (vector signed short, vector signed short);
-vector unsigned short vec_vadduhm (vector bool short, vector unsigned short);
-vector unsigned short vec_vadduhm (vector unsigned short, vector bool short);
-vector unsigned short vec_vadduhm (vector unsigned short, vector unsigned short);
-
-vector unsigned short vec_vadduhs (vector bool short, vector unsigned short);
-vector unsigned short vec_vadduhs (vector unsigned short, vector bool short);
-vector unsigned short vec_vadduhs (vector unsigned short, vector unsigned short);
-
-vector signed int vec_vadduwm (vector bool int, vector signed int);
-vector signed int vec_vadduwm (vector signed int, vector bool int);
-vector signed int vec_vadduwm (vector signed int, vector signed int);
-vector unsigned int vec_vadduwm (vector bool int, vector unsigned int);
-vector unsigned int vec_vadduwm (vector unsigned int, vector bool int);
-vector unsigned int vec_vadduwm (vector unsigned int, vector unsigned int);
-
-vector unsigned int vec_vadduws (vector bool int, vector unsigned int);
-vector unsigned int vec_vadduws (vector unsigned int, vector bool int);
-vector unsigned int vec_vadduws (vector unsigned int, vector unsigned int);
-
-vector signed char vec_vavgsb (vector signed char, vector signed char);
-
-vector signed short vec_vavgsh (vector signed short, vector signed short);
-
-vector signed int vec_vavgsw (vector signed int, vector signed int);
-
-vector unsigned char vec_vavgub (vector unsigned char, vector unsigned char);
-
-vector unsigned short vec_vavguh (vector unsigned short, vector unsigned short);
-
-vector unsigned int vec_vavguw (vector unsigned int, vector unsigned int);
-
-vector float vec_vcfsx (vector signed int, const int);
-
-vector float vec_vcfux (vector unsigned int, const int);
-
-vector bool int vec_vcmpeqfp (vector float, vector float);
-
-vector bool char vec_vcmpequb (vector signed char, vector signed char);
-vector bool char vec_vcmpequb (vector unsigned char, vector unsigned char);
-
-vector bool short vec_vcmpequh (vector signed short, vector signed short);
-vector bool short vec_vcmpequh (vector unsigned short, vector unsigned short);
-
-vector bool int vec_vcmpequw (vector signed int, vector signed int);
-vector bool int vec_vcmpequw (vector unsigned int, vector unsigned int);
-
-vector bool int vec_vcmpgtfp (vector float, vector float);
-
-vector bool char vec_vcmpgtsb (vector signed char, vector signed char);
-
-vector bool short vec_vcmpgtsh (vector signed short, vector signed short);
-
-vector bool int vec_vcmpgtsw (vector signed int, vector signed int);
-
-vector bool char vec_vcmpgtub (vector unsigned char, vector unsigned char);
-
-vector bool short vec_vcmpgtuh (vector unsigned short, vector unsigned short);
-
-vector bool int vec_vcmpgtuw (vector unsigned int, vector unsigned int);
-
-vector float vec_vmaxfp (vector float, vector float);
-
-vector signed char vec_vmaxsb (vector bool char, vector signed char);
-vector signed char vec_vmaxsb (vector signed char, vector bool char);
-vector signed char vec_vmaxsb (vector signed char, vector signed char);
-
-vector signed short vec_vmaxsh (vector bool short, vector signed short);
-vector signed short vec_vmaxsh (vector signed short, vector bool short);
-vector signed short vec_vmaxsh (vector signed short, vector signed short);
-
-vector signed int vec_vmaxsw (vector bool int, vector signed int);
-vector signed int vec_vmaxsw (vector signed int, vector bool int);
-vector signed int vec_vmaxsw (vector signed int, vector signed int);
-
-vector unsigned char vec_vmaxub (vector bool char, vector unsigned char);
-vector unsigned char vec_vmaxub (vector unsigned char, vector bool char);
-vector unsigned char vec_vmaxub (vector unsigned char, vector unsigned char);
-
-vector unsigned short vec_vmaxuh (vector bool short, vector unsigned short);
-vector unsigned short vec_vmaxuh (vector unsigned short, vector bool short);
-vector unsigned short vec_vmaxuh (vector unsigned short, vector unsigned short);
-
-vector unsigned int vec_vmaxuw (vector bool int, vector unsigned int);
-vector unsigned int vec_vmaxuw (vector unsigned int, vector bool int);
-vector unsigned int vec_vmaxuw (vector unsigned int, vector unsigned int);
-
-vector float vec_vminfp (vector float, vector float);
-
-vector signed char vec_vminsb (vector bool char, vector signed char);
-vector signed char vec_vminsb (vector signed char, vector bool char);
-vector signed char vec_vminsb (vector signed char, vector signed char);
-
-vector signed short vec_vminsh (vector bool short, vector signed short);
-vector signed short vec_vminsh (vector signed short, vector bool short);
-vector signed short vec_vminsh (vector signed short, vector signed short);
-
-vector signed int vec_vminsw (vector bool int, vector signed int);
-vector signed int vec_vminsw (vector signed int, vector bool int);
-vector signed int vec_vminsw (vector signed int, vector signed int);
-
-vector unsigned char vec_vminub (vector bool char, vector unsigned char);
-vector unsigned char vec_vminub (vector unsigned char, vector bool char);
-vector unsigned char vec_vminub (vector unsigned char, vector unsigned char);
-
-vector unsigned short vec_vminuh (vector bool short, vector unsigned short);
-vector unsigned short vec_vminuh (vector unsigned short, vector bool short);
-vector unsigned short vec_vminuh (vector unsigned short, vector unsigned short);
-
-vector unsigned int vec_vminuw (vector bool int, vector unsigned int);
-vector unsigned int vec_vminuw (vector unsigned int, vector bool int);
-vector unsigned int vec_vminuw (vector unsigned int, vector unsigned int);
-
-vector bool char vec_vmrghb (vector bool char, vector bool char);
-vector signed char vec_vmrghb (vector signed char, vector signed char);
-vector unsigned char vec_vmrghb (vector unsigned char, vector unsigned char);
-
-vector bool short vec_vmrghh (vector bool short, vector bool short);
-vector signed short vec_vmrghh (vector signed short, vector signed short);
-vector unsigned short vec_vmrghh (vector unsigned short, vector unsigned short);
-vector pixel vec_vmrghh (vector pixel, vector pixel);
-
-vector float vec_vmrghw (vector float, vector float);
-vector bool int vec_vmrghw (vector bool int, vector bool int);
-vector signed int vec_vmrghw (vector signed int, vector signed int);
-vector unsigned int vec_vmrghw (vector unsigned int, vector unsigned int);
-
-vector bool char vec_vmrglb (vector bool char, vector bool char);
-vector signed char vec_vmrglb (vector signed char, vector signed char);
-vector unsigned char vec_vmrglb (vector unsigned char, vector unsigned char);
-
-vector bool short vec_vmrglh (vector bool short, vector bool short);
-vector signed short vec_vmrglh (vector signed short, vector signed short);
-vector unsigned short vec_vmrglh (vector unsigned short, vector unsigned short);
-vector pixel vec_vmrglh (vector pixel, vector pixel);
-
-vector float vec_vmrglw (vector float, vector float);
-vector signed int vec_vmrglw (vector signed int, vector signed int);
-vector unsigned int vec_vmrglw (vector unsigned int, vector unsigned int);
-vector bool int vec_vmrglw (vector bool int, vector bool int);
-
-vector signed int vec_vmsummbm (vector signed char, vector unsigned char,
- vector signed int);
-
-vector signed int vec_vmsumshm (vector signed short, vector signed short,
- vector signed int);
-
-vector signed int vec_vmsumshs (vector signed short, vector signed short,
- vector signed int);
-
-vector unsigned int vec_vmsumubm (vector unsigned char, vector unsigned char,
- vector unsigned int);
-
-vector unsigned int vec_vmsumuhm (vector unsigned short, vector unsigned short,
- vector unsigned int);
-
-vector unsigned int vec_vmsumuhs (vector unsigned short, vector unsigned short,
- vector unsigned int);
-
-vector signed short vec_vmulesb (vector signed char, vector signed char);
-
-vector signed int vec_vmulesh (vector signed short, vector signed short);
-
-vector unsigned short vec_vmuleub (vector unsigned char, vector unsigned char);
-
-vector unsigned int vec_vmuleuh (vector unsigned short, vector unsigned short);
-
-vector signed short vec_vmulosb (vector signed char, vector signed char);
-
-vector signed int vec_vmulosh (vector signed short, vector signed short);
-
-vector unsigned short vec_vmuloub (vector unsigned char, vector unsigned char);
-
-vector unsigned int vec_vmulouh (vector unsigned short, vector unsigned short);
-
-vector signed char vec_vpkshss (vector signed short, vector signed short);
-
-vector unsigned char vec_vpkshus (vector signed short, vector signed short);
-
-vector signed short vec_vpkswss (vector signed int, vector signed int);
-
-vector unsigned short vec_vpkswus (vector signed int, vector signed int);
-
-vector bool char vec_vpkuhum (vector bool short, vector bool short);
-vector signed char vec_vpkuhum (vector signed short, vector signed short);
-vector unsigned char vec_vpkuhum (vector unsigned short, vector unsigned short);
-
-vector unsigned char vec_vpkuhus (vector unsigned short, vector unsigned short);
-
-vector bool short vec_vpkuwum (vector bool int, vector bool int);
-vector signed short vec_vpkuwum (vector signed int, vector signed int);
-vector unsigned short vec_vpkuwum (vector unsigned int, vector unsigned int);
-
-vector unsigned short vec_vpkuwus (vector unsigned int, vector unsigned int);
-
-vector signed char vec_vrlb (vector signed char, vector unsigned char);
-vector unsigned char vec_vrlb (vector unsigned char, vector unsigned char);
-
-vector signed short vec_vrlh (vector signed short, vector unsigned short);
-vector unsigned short vec_vrlh (vector unsigned short, vector unsigned short);
-
-vector signed int vec_vrlw (vector signed int, vector unsigned int);
-vector unsigned int vec_vrlw (vector unsigned int, vector unsigned int);
-
-vector signed char vec_vslb (vector signed char, vector unsigned char);
-vector unsigned char vec_vslb (vector unsigned char, vector unsigned char);
-
-vector signed short vec_vslh (vector signed short, vector unsigned short);
-vector unsigned short vec_vslh (vector unsigned short, vector unsigned short);
-
-vector signed int vec_vslw (vector signed int, vector unsigned int);
-vector unsigned int vec_vslw (vector unsigned int, vector unsigned int);
-
-vector signed char vec_vspltb (vector signed char, const int);
-vector unsigned char vec_vspltb (vector unsigned char, const int);
-vector bool char vec_vspltb (vector bool char, const int);
-
-vector bool short vec_vsplth (vector bool short, const int);
-vector signed short vec_vsplth (vector signed short, const int);
-vector unsigned short vec_vsplth (vector unsigned short, const int);
-vector pixel vec_vsplth (vector pixel, const int);
-
-vector float vec_vspltw (vector float, const int);
-vector signed int vec_vspltw (vector signed int, const int);
-vector unsigned int vec_vspltw (vector unsigned int, const int);
-vector bool int vec_vspltw (vector bool int, const int);
-
-vector signed char vec_vsrab (vector signed char, vector unsigned char);
-vector unsigned char vec_vsrab (vector unsigned char, vector unsigned char);
-
-vector signed short vec_vsrah (vector signed short, vector unsigned short);
-vector unsigned short vec_vsrah (vector unsigned short, vector unsigned short);
-
-vector signed int vec_vsraw (vector signed int, vector unsigned int);
-vector unsigned int vec_vsraw (vector unsigned int, vector unsigned int);
-
-vector signed char vec_vsrb (vector signed char, vector unsigned char);
-vector unsigned char vec_vsrb (vector unsigned char, vector unsigned char);
-
-vector signed short vec_vsrh (vector signed short, vector unsigned short);
-vector unsigned short vec_vsrh (vector unsigned short, vector unsigned short);
-
-vector signed int vec_vsrw (vector signed int, vector unsigned int);
-vector unsigned int vec_vsrw (vector unsigned int, vector unsigned int);
-
-vector float vec_vsubfp (vector float, vector float);
-
-vector signed char vec_vsubsbs (vector bool char, vector signed char);
-vector signed char vec_vsubsbs (vector signed char, vector bool char);
-vector signed char vec_vsubsbs (vector signed char, vector signed char);
-
-vector signed short vec_vsubshs (vector bool short, vector signed short);
-vector signed short vec_vsubshs (vector signed short, vector bool short);
-vector signed short vec_vsubshs (vector signed short, vector signed short);
-
-vector signed int vec_vsubsws (vector bool int, vector signed int);
-vector signed int vec_vsubsws (vector signed int, vector bool int);
-vector signed int vec_vsubsws (vector signed int, vector signed int);
-
-vector signed char vec_vsububm (vector bool char, vector signed char);
-vector signed char vec_vsububm (vector signed char, vector bool char);
-vector signed char vec_vsububm (vector signed char, vector signed char);
-vector unsigned char vec_vsububm (vector bool char, vector unsigned char);
-vector unsigned char vec_vsububm (vector unsigned char, vector bool char);
-vector unsigned char vec_vsububm (vector unsigned char, vector unsigned char);
-
-vector unsigned char vec_vsububs (vector bool char, vector unsigned char);
-vector unsigned char vec_vsububs (vector unsigned char, vector bool char);
-vector unsigned char vec_vsububs (vector unsigned char, vector unsigned char);
-
-vector signed short vec_vsubuhm (vector bool short, vector signed short);
-vector signed short vec_vsubuhm (vector signed short, vector bool short);
-vector signed short vec_vsubuhm (vector signed short, vector signed short);
-vector unsigned short vec_vsubuhm (vector bool short, vector unsigned short);
-vector unsigned short vec_vsubuhm (vector unsigned short, vector bool short);
-vector unsigned short vec_vsubuhm (vector unsigned short, vector unsigned short);
-
-vector unsigned short vec_vsubuhs (vector bool short, vector unsigned short);
-vector unsigned short vec_vsubuhs (vector unsigned short, vector bool short);
-vector unsigned short vec_vsubuhs (vector unsigned short, vector unsigned short);
-
-vector signed int vec_vsubuwm (vector bool int, vector signed int);
-vector signed int vec_vsubuwm (vector signed int, vector bool int);
-vector signed int vec_vsubuwm (vector signed int, vector signed int);
-vector unsigned int vec_vsubuwm (vector bool int, vector unsigned int);
-vector unsigned int vec_vsubuwm (vector unsigned int, vector bool int);
-vector unsigned int vec_vsubuwm (vector unsigned int, vector unsigned int);
-
-vector unsigned int vec_vsubuws (vector bool int, vector unsigned int);
-vector unsigned int vec_vsubuws (vector unsigned int, vector bool int);
-vector unsigned int vec_vsubuws (vector unsigned int, vector unsigned int);
-
-vector signed int vec_vsum4sbs (vector signed char, vector signed int);
-
-vector signed int vec_vsum4shs (vector signed short, vector signed int);
-
-vector unsigned int vec_vsum4ubs (vector unsigned char, vector unsigned int);
-
-vector unsigned int vec_vupkhpx (vector pixel);
-
-vector bool short vec_vupkhsb (vector bool char);
-vector signed short vec_vupkhsb (vector signed char);
-
-vector bool int vec_vupkhsh (vector bool short);
-vector signed int vec_vupkhsh (vector signed short);
-
-vector unsigned int vec_vupklpx (vector pixel);
-
-vector bool short vec_vupklsb (vector bool char);
-vector signed short vec_vupklsb (vector signed char);
-
-vector bool int vec_vupklsh (vector bool short);
-vector signed int vec_vupklsh (vector signed short);
-@end smallexample
-
-@node PowerPC AltiVec Built-in Functions Available on ISA 2.06
-@subsubsection PowerPC AltiVec Built-in Functions Available on ISA 2.06
-
-The AltiVec built-in functions described in this section are
-available on the PowerPC family of processors starting with ISA 2.06
-or later. These are normally enabled by adding @option{-mvsx} to the
-command line.
-
-When @option{-mvsx} is used, the following additional vector types are
-implemented.
-
-@smallexample
-vector unsigned __int128
-vector signed __int128
-vector unsigned long long int
-vector signed long long int
-vector double
-@end smallexample
-
-The long long types are only implemented for 64-bit code generation.
-
-Only functions excluded from the PVIPR are listed here.
-
-@smallexample
-void vec_dst (const unsigned long *, int, const int);
-void vec_dst (const long *, int, const int);
-
-void vec_dststt (const unsigned long *, int, const int);
-void vec_dststt (const long *, int, const int);
-
-void vec_dstt (const unsigned long *, int, const int);
-void vec_dstt (const long *, int, const int);
-
-vector unsigned char vec_lvsl (int, const unsigned long *);
-vector unsigned char vec_lvsl (int, const long *);
-
-vector unsigned char vec_lvsr (int, const unsigned long *);
-vector unsigned char vec_lvsr (int, const long *);
-
-vector unsigned char vec_lvsl (int, const double *);
-vector unsigned char vec_lvsr (int, const double *);
-
-vector double vec_vsx_ld (int, const vector double *);
-vector double vec_vsx_ld (int, const double *);
-vector float vec_vsx_ld (int, const vector float *);
-vector float vec_vsx_ld (int, const float *);
-vector bool int vec_vsx_ld (int, const vector bool int *);
-vector signed int vec_vsx_ld (int, const vector signed int *);
-vector signed int vec_vsx_ld (int, const int *);
-vector signed int vec_vsx_ld (int, const long *);
-vector unsigned int vec_vsx_ld (int, const vector unsigned int *);
-vector unsigned int vec_vsx_ld (int, const unsigned int *);
-vector unsigned int vec_vsx_ld (int, const unsigned long *);
-vector bool short vec_vsx_ld (int, const vector bool short *);
-vector pixel vec_vsx_ld (int, const vector pixel *);
-vector signed short vec_vsx_ld (int, const vector signed short *);
-vector signed short vec_vsx_ld (int, const short *);
-vector unsigned short vec_vsx_ld (int, const vector unsigned short *);
-vector unsigned short vec_vsx_ld (int, const unsigned short *);
-vector bool char vec_vsx_ld (int, const vector bool char *);
-vector signed char vec_vsx_ld (int, const vector signed char *);
-vector signed char vec_vsx_ld (int, const signed char *);
-vector unsigned char vec_vsx_ld (int, const vector unsigned char *);
-vector unsigned char vec_vsx_ld (int, const unsigned char *);
-
-void vec_vsx_st (vector double, int, vector double *);
-void vec_vsx_st (vector double, int, double *);
-void vec_vsx_st (vector float, int, vector float *);
-void vec_vsx_st (vector float, int, float *);
-void vec_vsx_st (vector signed int, int, vector signed int *);
-void vec_vsx_st (vector signed int, int, int *);
-void vec_vsx_st (vector unsigned int, int, vector unsigned int *);
-void vec_vsx_st (vector unsigned int, int, unsigned int *);
-void vec_vsx_st (vector bool int, int, vector bool int *);
-void vec_vsx_st (vector bool int, int, unsigned int *);
-void vec_vsx_st (vector bool int, int, int *);
-void vec_vsx_st (vector signed short, int, vector signed short *);
-void vec_vsx_st (vector signed short, int, short *);
-void vec_vsx_st (vector unsigned short, int, vector unsigned short *);
-void vec_vsx_st (vector unsigned short, int, unsigned short *);
-void vec_vsx_st (vector bool short, int, vector bool short *);
-void vec_vsx_st (vector bool short, int, unsigned short *);
-void vec_vsx_st (vector pixel, int, vector pixel *);
-void vec_vsx_st (vector pixel, int, unsigned short *);
-void vec_vsx_st (vector pixel, int, short *);
-void vec_vsx_st (vector bool short, int, short *);
-void vec_vsx_st (vector signed char, int, vector signed char *);
-void vec_vsx_st (vector signed char, int, signed char *);
-void vec_vsx_st (vector unsigned char, int, vector unsigned char *);
-void vec_vsx_st (vector unsigned char, int, unsigned char *);
-void vec_vsx_st (vector bool char, int, vector bool char *);
-void vec_vsx_st (vector bool char, int, unsigned char *);
-void vec_vsx_st (vector bool char, int, signed char *);
-
-vector double vec_xxpermdi (vector double, vector double, const int);
-vector float vec_xxpermdi (vector float, vector float, const int);
-vector long long vec_xxpermdi (vector long long, vector long long, const int);
-vector unsigned long long vec_xxpermdi (vector unsigned long long,
- vector unsigned long long, const int);
-vector int vec_xxpermdi (vector int, vector int, const int);
-vector unsigned int vec_xxpermdi (vector unsigned int,
- vector unsigned int, const int);
-vector short vec_xxpermdi (vector short, vector short, const int);
-vector unsigned short vec_xxpermdi (vector unsigned short,
- vector unsigned short, const int);
-vector signed char vec_xxpermdi (vector signed char, vector signed char,
- const int);
-vector unsigned char vec_xxpermdi (vector unsigned char,
- vector unsigned char, const int);
-
-vector double vec_xxsldi (vector double, vector double, int);
-vector float vec_xxsldi (vector float, vector float, int);
-vector long long vec_xxsldi (vector long long, vector long long, int);
-vector unsigned long long vec_xxsldi (vector unsigned long long,
- vector unsigned long long, int);
-vector int vec_xxsldi (vector int, vector int, int);
-vector unsigned int vec_xxsldi (vector unsigned int, vector unsigned int, int);
-vector short vec_xxsldi (vector short, vector short, int);
-vector unsigned short vec_xxsldi (vector unsigned short,
- vector unsigned short, int);
-vector signed char vec_xxsldi (vector signed char, vector signed char, int);
-vector unsigned char vec_xxsldi (vector unsigned char,
- vector unsigned char, int);
-@end smallexample
-
-Note that the @samp{vec_ld} and @samp{vec_st} built-in functions always
-generate the AltiVec @samp{LVX} and @samp{STVX} instructions even
-if the VSX instruction set is available. The @samp{vec_vsx_ld} and
-@samp{vec_vsx_st} built-in functions always generate the VSX @samp{LXVD2X},
-@samp{LXVW4X}, @samp{STXVD2X}, and @samp{STXVW4X} instructions.
-
-@node PowerPC AltiVec Built-in Functions Available on ISA 2.07
-@subsubsection PowerPC AltiVec Built-in Functions Available on ISA 2.07
-
-If the ISA 2.07 additions to the vector/scalar (power8-vector)
-instruction set are available, the following additional functions are
-available for both 32-bit and 64-bit targets. For 64-bit targets, you
-can use @var{vector long} instead of @var{vector long long},
-@var{vector bool long} instead of @var{vector bool long long}, and
-@var{vector unsigned long} instead of @var{vector unsigned long long}.
-
-Only functions excluded from the PVIPR are listed here.
-
-@smallexample
-vector long long vec_vaddudm (vector long long, vector long long);
-vector long long vec_vaddudm (vector bool long long, vector long long);
-vector long long vec_vaddudm (vector long long, vector bool long long);
-vector unsigned long long vec_vaddudm (vector unsigned long long,
- vector unsigned long long);
-vector unsigned long long vec_vaddudm (vector bool unsigned long long,
- vector unsigned long long);
-vector unsigned long long vec_vaddudm (vector unsigned long long,
- vector bool unsigned long long);
-
-vector long long vec_vclz (vector long long);
-vector unsigned long long vec_vclz (vector unsigned long long);
-vector int vec_vclz (vector int);
-vector unsigned int vec_vclz (vector int);
-vector short vec_vclz (vector short);
-vector unsigned short vec_vclz (vector unsigned short);
-vector signed char vec_vclz (vector signed char);
-vector unsigned char vec_vclz (vector unsigned char);
-
-vector signed char vec_vclzb (vector signed char);
-vector unsigned char vec_vclzb (vector unsigned char);
-
-vector long long vec_vclzd (vector long long);
-vector unsigned long long vec_vclzd (vector unsigned long long);
-
-vector short vec_vclzh (vector short);
-vector unsigned short vec_vclzh (vector unsigned short);
-
-vector int vec_vclzw (vector int);
-vector unsigned int vec_vclzw (vector int);
-
-vector signed char vec_vgbbd (vector signed char);
-vector unsigned char vec_vgbbd (vector unsigned char);
-
-vector long long vec_vmaxsd (vector long long, vector long long);
-
-vector unsigned long long vec_vmaxud (vector unsigned long long,
- unsigned vector long long);
-
-vector long long vec_vminsd (vector long long, vector long long);
-
-vector unsigned long long vec_vminud (vector long long, vector long long);
-
-vector int vec_vpksdss (vector long long, vector long long);
-vector unsigned int vec_vpksdss (vector long long, vector long long);
-
-vector unsigned int vec_vpkudus (vector unsigned long long,
- vector unsigned long long);
-
-vector int vec_vpkudum (vector long long, vector long long);
-vector unsigned int vec_vpkudum (vector unsigned long long,
- vector unsigned long long);
-vector bool int vec_vpkudum (vector bool long long, vector bool long long);
-
-vector long long vec_vpopcnt (vector long long);
-vector unsigned long long vec_vpopcnt (vector unsigned long long);
-vector int vec_vpopcnt (vector int);
-vector unsigned int vec_vpopcnt (vector int);
-vector short vec_vpopcnt (vector short);
-vector unsigned short vec_vpopcnt (vector unsigned short);
-vector signed char vec_vpopcnt (vector signed char);
-vector unsigned char vec_vpopcnt (vector unsigned char);
-
-vector signed char vec_vpopcntb (vector signed char);
-vector unsigned char vec_vpopcntb (vector unsigned char);
-
-vector long long vec_vpopcntd (vector long long);
-vector unsigned long long vec_vpopcntd (vector unsigned long long);
-
-vector short vec_vpopcnth (vector short);
-vector unsigned short vec_vpopcnth (vector unsigned short);
-
-vector int vec_vpopcntw (vector int);
-vector unsigned int vec_vpopcntw (vector int);
-
-vector long long vec_vrld (vector long long, vector unsigned long long);
-vector unsigned long long vec_vrld (vector unsigned long long,
- vector unsigned long long);
-
-vector long long vec_vsld (vector long long, vector unsigned long long);
-vector long long vec_vsld (vector unsigned long long,
- vector unsigned long long);
-
-vector long long vec_vsrad (vector long long, vector unsigned long long);
-vector unsigned long long vec_vsrad (vector unsigned long long,
- vector unsigned long long);
-
-vector long long vec_vsrd (vector long long, vector unsigned long long);
-vector unsigned long long char vec_vsrd (vector unsigned long long,
- vector unsigned long long);
-
-vector long long vec_vsubudm (vector long long, vector long long);
-vector long long vec_vsubudm (vector bool long long, vector long long);
-vector long long vec_vsubudm (vector long long, vector bool long long);
-vector unsigned long long vec_vsubudm (vector unsigned long long,
- vector unsigned long long);
-vector unsigned long long vec_vsubudm (vector bool long long,
- vector unsigned long long);
-vector unsigned long long vec_vsubudm (vector unsigned long long,
- vector bool long long);
-
-vector long long vec_vupkhsw (vector int);
-vector unsigned long long vec_vupkhsw (vector unsigned int);
-
-vector long long vec_vupklsw (vector int);
-vector unsigned long long vec_vupklsw (vector int);
-@end smallexample
-
-If the ISA 2.07 additions to the vector/scalar (power8-vector)
-instruction set are available, the following additional functions are
-available for 64-bit targets. New vector types
-(@var{vector __int128} and @var{vector __uint128}) are available
-to hold the @var{__int128} and @var{__uint128} types to use these
-builtins.
-
-The normal vector extract, and set operations work on
-@var{vector __int128} and @var{vector __uint128} types,
-but the index value must be 0.
-
-Only functions excluded from the PVIPR are listed here.
-
-@smallexample
-vector __int128 vec_vaddcuq (vector __int128, vector __int128);
-vector __uint128 vec_vaddcuq (vector __uint128, vector __uint128);
-
-vector __int128 vec_vadduqm (vector __int128, vector __int128);
-vector __uint128 vec_vadduqm (vector __uint128, vector __uint128);
-
-vector __int128 vec_vaddecuq (vector __int128, vector __int128,
- vector __int128);
-vector __uint128 vec_vaddecuq (vector __uint128, vector __uint128,
- vector __uint128);
-
-vector __int128 vec_vaddeuqm (vector __int128, vector __int128,
- vector __int128);
-vector __uint128 vec_vaddeuqm (vector __uint128, vector __uint128,
- vector __uint128);
-
-vector __int128 vec_vsubecuq (vector __int128, vector __int128,
- vector __int128);
-vector __uint128 vec_vsubecuq (vector __uint128, vector __uint128,
- vector __uint128);
-
-vector __int128 vec_vsubeuqm (vector __int128, vector __int128,
- vector __int128);
-vector __uint128 vec_vsubeuqm (vector __uint128, vector __uint128,
- vector __uint128);
-
-vector __int128 vec_vsubcuq (vector __int128, vector __int128);
-vector __uint128 vec_vsubcuq (vector __uint128, vector __uint128);
-
-__int128 vec_vsubuqm (__int128, __int128);
-__uint128 vec_vsubuqm (__uint128, __uint128);
-
-vector __int128 __builtin_bcdadd (vector __int128, vector __int128, const int);
-vector unsigned char __builtin_bcdadd (vector unsigned char, vector unsigned char,
- const int);
-int __builtin_bcdadd_lt (vector __int128, vector __int128, const int);
-int __builtin_bcdadd_lt (vector unsigned char, vector unsigned char, const int);
-int __builtin_bcdadd_eq (vector __int128, vector __int128, const int);
-int __builtin_bcdadd_eq (vector unsigned char, vector unsigned char, const int);
-int __builtin_bcdadd_gt (vector __int128, vector __int128, const int);
-int __builtin_bcdadd_gt (vector unsigned char, vector unsigned char, const int);
-int __builtin_bcdadd_ov (vector __int128, vector __int128, const int);
-int __builtin_bcdadd_ov (vector unsigned char, vector unsigned char, const int);
-
-vector __int128 __builtin_bcdsub (vector __int128, vector __int128, const int);
-vector unsigned char __builtin_bcdsub (vector unsigned char, vector unsigned char,
- const int);
-int __builtin_bcdsub_lt (vector __int128, vector __int128, const int);
-int __builtin_bcdsub_lt (vector unsigned char, vector unsigned char, const int);
-int __builtin_bcdsub_eq (vector __int128, vector __int128, const int);
-int __builtin_bcdsub_eq (vector unsigned char, vector unsigned char, const int);
-int __builtin_bcdsub_gt (vector __int128, vector __int128, const int);
-int __builtin_bcdsub_gt (vector unsigned char, vector unsigned char, const int);
-int __builtin_bcdsub_ov (vector __int128, vector __int128, const int);
-int __builtin_bcdsub_ov (vector unsigned char, vector unsigned char, const int);
-@end smallexample
-
-@node PowerPC AltiVec Built-in Functions Available on ISA 3.0
-@subsubsection PowerPC AltiVec Built-in Functions Available on ISA 3.0
-
-The following additional built-in functions are also available for the
-PowerPC family of processors, starting with ISA 3.0
-(@option{-mcpu=power9}) or later.
-
-Only instructions excluded from the PVIPR are listed here.
-
-@smallexample
-unsigned int scalar_extract_exp (double source);
-unsigned long long int scalar_extract_exp (__ieee128 source);
-
-unsigned long long int scalar_extract_sig (double source);
-unsigned __int128 scalar_extract_sig (__ieee128 source);
-
-double scalar_insert_exp (unsigned long long int significand,
- unsigned long long int exponent);
-double scalar_insert_exp (double significand, unsigned long long int exponent);
-
-ieee_128 scalar_insert_exp (unsigned __int128 significand,
- unsigned long long int exponent);
-ieee_128 scalar_insert_exp (ieee_128 significand, unsigned long long int exponent);
-
-int scalar_cmp_exp_gt (double arg1, double arg2);
-int scalar_cmp_exp_lt (double arg1, double arg2);
-int scalar_cmp_exp_eq (double arg1, double arg2);
-int scalar_cmp_exp_unordered (double arg1, double arg2);
-
-bool scalar_test_data_class (float source, const int condition);
-bool scalar_test_data_class (double source, const int condition);
-bool scalar_test_data_class (__ieee128 source, const int condition);
-
-bool scalar_test_neg (float source);
-bool scalar_test_neg (double source);
-bool scalar_test_neg (__ieee128 source);
-@end smallexample
-
-The @code{scalar_extract_exp} and @code{scalar_extract_sig}
-functions require a 64-bit environment supporting ISA 3.0 or later.
-The @code{scalar_extract_exp} and @code{scalar_extract_sig} built-in
-functions return the significand and the biased exponent value
-respectively of their @code{source} arguments.
-When supplied with a 64-bit @code{source} argument, the
-result returned by @code{scalar_extract_sig} has
-the @code{0x0010000000000000} bit set if the
-function's @code{source} argument is in normalized form.
-Otherwise, this bit is set to 0.
-When supplied with a 128-bit @code{source} argument, the
-@code{0x00010000000000000000000000000000} bit of the result is
-treated similarly.
-Note that the sign of the significand is not represented in the result
-returned from the @code{scalar_extract_sig} function. Use the
-@code{scalar_test_neg} function to test the sign of its @code{double}
-argument.
-
-The @code{scalar_insert_exp}
-functions require a 64-bit environment supporting ISA 3.0 or later.
-When supplied with a 64-bit first argument, the
-@code{scalar_insert_exp} built-in function returns a double-precision
-floating point value that is constructed by assembling the values of its
-@code{significand} and @code{exponent} arguments. The sign of the
-result is copied from the most significant bit of the
-@code{significand} argument. The significand and exponent components
-of the result are composed of the least significant 11 bits of the
-@code{exponent} argument and the least significant 52 bits of the
-@code{significand} argument respectively.
-
-When supplied with a 128-bit first argument, the
-@code{scalar_insert_exp} built-in function returns a quad-precision
-ieee floating point value. The sign bit of the result is copied from
-the most significant bit of the @code{significand} argument.
-The significand and exponent components of the result are composed of
-the least significant 15 bits of the @code{exponent} argument and the
-least significant 112 bits of the @code{significand} argument respectively.
-
-The @code{scalar_cmp_exp_gt}, @code{scalar_cmp_exp_lt},
-@code{scalar_cmp_exp_eq}, and @code{scalar_cmp_exp_unordered} built-in
-functions return a non-zero value if @code{arg1} is greater than, less
-than, equal to, or not comparable to @code{arg2} respectively. The
-arguments are not comparable if one or the other equals NaN (not a
-number).
-
-The @code{scalar_test_data_class} built-in function returns 1
-if any of the condition tests enabled by the value of the
-@code{condition} variable are true, and 0 otherwise. The
-@code{condition} argument must be a compile-time constant integer with
-value not exceeding 127. The
-@code{condition} argument is encoded as a bitmask with each bit
-enabling the testing of a different condition, as characterized by the
-following:
-@smallexample
-0x40 Test for NaN
-0x20 Test for +Infinity
-0x10 Test for -Infinity
-0x08 Test for +Zero
-0x04 Test for -Zero
-0x02 Test for +Denormal
-0x01 Test for -Denormal
-@end smallexample
-
-The @code{scalar_test_neg} built-in function returns 1 if its
-@code{source} argument holds a negative value, 0 otherwise.
-
-The following built-in functions are also available for the PowerPC family
-of processors, starting with ISA 3.0 or later
-(@option{-mcpu=power9}). These string functions are described
-separately in order to group the descriptions closer to the function
-prototypes.
-
-Only functions excluded from the PVIPR are listed here.
-
-@smallexample
-int vec_all_nez (vector signed char, vector signed char);
-int vec_all_nez (vector unsigned char, vector unsigned char);
-int vec_all_nez (vector signed short, vector signed short);
-int vec_all_nez (vector unsigned short, vector unsigned short);
-int vec_all_nez (vector signed int, vector signed int);
-int vec_all_nez (vector unsigned int, vector unsigned int);
-
-int vec_any_eqz (vector signed char, vector signed char);
-int vec_any_eqz (vector unsigned char, vector unsigned char);
-int vec_any_eqz (vector signed short, vector signed short);
-int vec_any_eqz (vector unsigned short, vector unsigned short);
-int vec_any_eqz (vector signed int, vector signed int);
-int vec_any_eqz (vector unsigned int, vector unsigned int);
-
-signed char vec_xlx (unsigned int index, vector signed char data);
-unsigned char vec_xlx (unsigned int index, vector unsigned char data);
-signed short vec_xlx (unsigned int index, vector signed short data);
-unsigned short vec_xlx (unsigned int index, vector unsigned short data);
-signed int vec_xlx (unsigned int index, vector signed int data);
-unsigned int vec_xlx (unsigned int index, vector unsigned int data);
-float vec_xlx (unsigned int index, vector float data);
-
-signed char vec_xrx (unsigned int index, vector signed char data);
-unsigned char vec_xrx (unsigned int index, vector unsigned char data);
-signed short vec_xrx (unsigned int index, vector signed short data);
-unsigned short vec_xrx (unsigned int index, vector unsigned short data);
-signed int vec_xrx (unsigned int index, vector signed int data);
-unsigned int vec_xrx (unsigned int index, vector unsigned int data);
-float vec_xrx (unsigned int index, vector float data);
-@end smallexample
-
-The @code{vec_all_nez}, @code{vec_any_eqz}, and @code{vec_cmpnez}
-perform pairwise comparisons between the elements at the same
-positions within their two vector arguments.
-The @code{vec_all_nez} function returns a
-non-zero value if and only if all pairwise comparisons are not
-equal and no element of either vector argument contains a zero.
-The @code{vec_any_eqz} function returns a
-non-zero value if and only if at least one pairwise comparison is equal
-or if at least one element of either vector argument contains a zero.
-The @code{vec_cmpnez} function returns a vector of the same type as
-its two arguments, within which each element consists of all ones to
-denote that either the corresponding elements of the incoming arguments are
-not equal or that at least one of the corresponding elements contains
-zero. Otherwise, the element of the returned vector contains all zeros.
-
-The @code{vec_xlx} and @code{vec_xrx} functions extract the single
-element selected by the @code{index} argument from the vector
-represented by the @code{data} argument. The @code{index} argument
-always specifies a byte offset, regardless of the size of the vector
-element. With @code{vec_xlx}, @code{index} is the offset of the first
-byte of the element to be extracted. With @code{vec_xrx}, @code{index}
-represents the last byte of the element to be extracted, measured
-from the right end of the vector. In other words, the last byte of
-the element to be extracted is found at position @code{(15 - index)}.
-There is no requirement that @code{index} be a multiple of the vector
-element size. However, if the size of the vector element added to
-@code{index} is greater than 15, the content of the returned value is
-undefined.
-
-The following functions are also available if the ISA 3.0 instruction
-set additions (@option{-mcpu=power9}) are available.
-
-Only functions excluded from the PVIPR are listed here.
-
-@smallexample
-vector long long vec_vctz (vector long long);
-vector unsigned long long vec_vctz (vector unsigned long long);
-vector int vec_vctz (vector int);
-vector unsigned int vec_vctz (vector int);
-vector short vec_vctz (vector short);
-vector unsigned short vec_vctz (vector unsigned short);
-vector signed char vec_vctz (vector signed char);
-vector unsigned char vec_vctz (vector unsigned char);
-
-vector signed char vec_vctzb (vector signed char);
-vector unsigned char vec_vctzb (vector unsigned char);
-
-vector long long vec_vctzd (vector long long);
-vector unsigned long long vec_vctzd (vector unsigned long long);
-
-vector short vec_vctzh (vector short);
-vector unsigned short vec_vctzh (vector unsigned short);
-
-vector int vec_vctzw (vector int);
-vector unsigned int vec_vctzw (vector int);
-
-vector int vec_vprtyb (vector int);
-vector unsigned int vec_vprtyb (vector unsigned int);
-vector long long vec_vprtyb (vector long long);
-vector unsigned long long vec_vprtyb (vector unsigned long long);
-
-vector int vec_vprtybw (vector int);
-vector unsigned int vec_vprtybw (vector unsigned int);
-
-vector long long vec_vprtybd (vector long long);
-vector unsigned long long vec_vprtybd (vector unsigned long long);
-@end smallexample
-
-On 64-bit targets, if the ISA 3.0 additions (@option{-mcpu=power9})
-are available:
-
-@smallexample
-vector long vec_vprtyb (vector long);
-vector unsigned long vec_vprtyb (vector unsigned long);
-vector __int128 vec_vprtyb (vector __int128);
-vector __uint128 vec_vprtyb (vector __uint128);
-
-vector long vec_vprtybd (vector long);
-vector unsigned long vec_vprtybd (vector unsigned long);
-
-vector __int128 vec_vprtybq (vector __int128);
-vector __uint128 vec_vprtybd (vector __uint128);
-@end smallexample
-
-The following built-in functions are available for the PowerPC family
-of processors, starting with ISA 3.0 or later (@option{-mcpu=power9}).
-
-Only functions excluded from the PVIPR are listed here.
-
-@smallexample
-__vector unsigned char
-vec_absdb (__vector unsigned char arg1, __vector unsigned char arg2);
-__vector unsigned short
-vec_absdh (__vector unsigned short arg1, __vector unsigned short arg2);
-__vector unsigned int
-vec_absdw (__vector unsigned int arg1, __vector unsigned int arg2);
-@end smallexample
-
-The @code{vec_absd}, @code{vec_absdb}, @code{vec_absdh}, and
-@code{vec_absdw} built-in functions each computes the absolute
-differences of the pairs of vector elements supplied in its two vector
-arguments, placing the absolute differences into the corresponding
-elements of the vector result.
-
-The following built-in functions are available for the PowerPC family
-of processors, starting with ISA 3.0 or later (@option{-mcpu=power9}):
-@smallexample
-vector unsigned int vec_vrlnm (vector unsigned int, vector unsigned int);
-vector unsigned long long vec_vrlnm (vector unsigned long long,
- vector unsigned long long);
-@end smallexample
-
-The result of @code{vec_vrlnm} is obtained by rotating each element
-of the first argument vector left and ANDing it with a mask. The
-second argument vector contains the mask beginning in bits 11:15,
-the mask end in bits 19:23, and the shift count in bits 27:31,
-of each element.
-
-If the cryptographic instructions are enabled (@option{-mcrypto} or
-@option{-mcpu=power8}), the following builtins are enabled.
-
-Only functions excluded from the PVIPR are listed here.
-
-@smallexample
-vector unsigned long long __builtin_crypto_vsbox (vector unsigned long long);
-
-vector unsigned long long __builtin_crypto_vcipher (vector unsigned long long,
- vector unsigned long long);
-
-vector unsigned long long __builtin_crypto_vcipherlast
- (vector unsigned long long,
- vector unsigned long long);
-
-vector unsigned long long __builtin_crypto_vncipher (vector unsigned long long,
- vector unsigned long long);
-
-vector unsigned long long __builtin_crypto_vncipherlast (vector unsigned long long,
- vector unsigned long long);
-
-vector unsigned char __builtin_crypto_vpermxor (vector unsigned char,
- vector unsigned char,
- vector unsigned char);
-
-vector unsigned short __builtin_crypto_vpermxor (vector unsigned short,
- vector unsigned short,
- vector unsigned short);
-
-vector unsigned int __builtin_crypto_vpermxor (vector unsigned int,
- vector unsigned int,
- vector unsigned int);
-
-vector unsigned long long __builtin_crypto_vpermxor (vector unsigned long long,
- vector unsigned long long,
- vector unsigned long long);
-
-vector unsigned char __builtin_crypto_vpmsumb (vector unsigned char,
- vector unsigned char);
-
-vector unsigned short __builtin_crypto_vpmsumh (vector unsigned short,
- vector unsigned short);
-
-vector unsigned int __builtin_crypto_vpmsumw (vector unsigned int,
- vector unsigned int);
-
-vector unsigned long long __builtin_crypto_vpmsumd (vector unsigned long long,
- vector unsigned long long);
-
-vector unsigned long long __builtin_crypto_vshasigmad (vector unsigned long long,
- int, int);
-
-vector unsigned int __builtin_crypto_vshasigmaw (vector unsigned int, int, int);
-@end smallexample
-
-The second argument to @var{__builtin_crypto_vshasigmad} and
-@var{__builtin_crypto_vshasigmaw} must be a constant
-integer that is 0 or 1. The third argument to these built-in functions
-must be a constant integer in the range of 0 to 15.
-
-The following sign extension builtins are provided:
-
-@smallexample
-vector signed int vec_signexti (vector signed char a);
-vector signed long long vec_signextll (vector signed char a);
-vector signed int vec_signexti (vector signed short a);
-vector signed long long vec_signextll (vector signed short a);
-vector signed long long vec_signextll (vector signed int a);
-vector signed long long vec_signextq (vector signed long long a);
-@end smallexample
-
-Each element of the result is produced by sign-extending the element of the
-input vector that would fall in the least significant portion of the result
-element. For example, a sign-extension of a vector signed char to a vector
-signed long long will sign extend the rightmost byte of each doubleword.
-
-@node PowerPC AltiVec Built-in Functions Available on ISA 3.1
-@subsubsection PowerPC AltiVec Built-in Functions Available on ISA 3.1
-
-The following additional built-in functions are also available for the
-PowerPC family of processors, starting with ISA 3.1 (@option{-mcpu=power10}):
-
-
-@smallexample
-@exdent vector unsigned long long int
-@exdent vec_cfuge (vector unsigned long long int, vector unsigned long long int);
-@end smallexample
-Perform a vector centrifuge operation, as if implemented by the
-@code{vcfuged} instruction.
-@findex vec_cfuge
-
-@smallexample
-@exdent vector unsigned long long int
-@exdent vec_cntlzm (vector unsigned long long int, vector unsigned long long int);
-@end smallexample
-Perform a vector count leading zeros under bit mask operation, as if
-implemented by the @code{vclzdm} instruction.
-@findex vec_cntlzm
-
-@smallexample
-@exdent vector unsigned long long int
-@exdent vec_cnttzm (vector unsigned long long int, vector unsigned long long int);
-@end smallexample
-Perform a vector count trailing zeros under bit mask operation, as if
-implemented by the @code{vctzdm} instruction.
-@findex vec_cnttzm
-
-@smallexample
-@exdent vector signed char
-@exdent vec_clrl (vector signed char a, unsigned int n);
-@exdent vector unsigned char
-@exdent vec_clrl (vector unsigned char a, unsigned int n);
-@end smallexample
-Clear the left-most @code{(16 - n)} bytes of vector argument @code{a}, as if
-implemented by the @code{vclrlb} instruction on a big-endian target
-and by the @code{vclrrb} instruction on a little-endian target. A
-value of @code{n} that is greater than 16 is treated as if it equaled 16.
-@findex vec_clrl
-
-@smallexample
-@exdent vector signed char
-@exdent vec_clrr (vector signed char a, unsigned int n);
-@exdent vector unsigned char
-@exdent vec_clrr (vector unsigned char a, unsigned int n);
-@end smallexample
-Clear the right-most @code{(16 - n)} bytes of vector argument @code{a}, as if
-implemented by the @code{vclrrb} instruction on a big-endian target
-and by the @code{vclrlb} instruction on a little-endian target. A
-value of @code{n} that is greater than 16 is treated as if it equaled 16.
-@findex vec_clrr
-
-@smallexample
-@exdent vector unsigned long long int
-@exdent vec_gnb (vector unsigned __int128, const unsigned char);
-@end smallexample
-Perform a 128-bit vector gather operation, as if implemented by the
-@code{vgnb} instruction. The second argument must be a literal
-integer value between 2 and 7 inclusive.
-@findex vec_gnb
-
-
-Vector Extract
-
-@smallexample
-@exdent vector unsigned long long int
-@exdent vec_extractl (vector unsigned char, vector unsigned char, unsigned int);
-@exdent vector unsigned long long int
-@exdent vec_extractl (vector unsigned short, vector unsigned short, unsigned int);
-@exdent vector unsigned long long int
-@exdent vec_extractl (vector unsigned int, vector unsigned int, unsigned int);
-@exdent vector unsigned long long int
-@exdent vec_extractl (vector unsigned long long, vector unsigned long long, unsigned int);
-@end smallexample
-Extract an element from two concatenated vectors starting at the given byte index
-in natural-endian order, and place it zero-extended in doubleword 1 of the result
-according to natural element order. If the byte index is out of range for the
-data type, the intrinsic will be rejected.
-For little-endian, this output will match the placement by the hardware
-instruction, i.e., dword[0] in RTL notation. For big-endian, an additional
-instruction is needed to move it from the "left" doubleword to the "right" one.
-For little-endian, semantics matching the @code{vextdubvrx},
-@code{vextduhvrx}, @code{vextduwvrx} instruction will be generated, while for
-big-endian, semantics matching the @code{vextdubvlx}, @code{vextduhvlx},
-@code{vextduwvlx} instructions
-will be generated. Note that some fairly anomalous results can be generated if
-the byte index is not aligned on an element boundary for the element being
-extracted. This is a limitation of the bi-endian vector programming model is
-consistent with the limitation on @code{vec_perm}.
-@findex vec_extractl
-
-@smallexample
-@exdent vector unsigned long long int
-@exdent vec_extracth (vector unsigned char, vector unsigned char, unsigned int);
-@exdent vector unsigned long long int
-@exdent vec_extracth (vector unsigned short, vector unsigned short,
-unsigned int);
-@exdent vector unsigned long long int
-@exdent vec_extracth (vector unsigned int, vector unsigned int, unsigned int);
-@exdent vector unsigned long long int
-@exdent vec_extracth (vector unsigned long long, vector unsigned long long,
-unsigned int);
-@end smallexample
-Extract an element from two concatenated vectors starting at the given byte
-index. The index is based on big endian order for a little endian system.
-Similarly, the index is based on little endian order for a big endian system.
-The extraced elements are zero-extended and put in doubleword 1
-according to natural element order. If the byte index is out of range for the
-data type, the intrinsic will be rejected. For little-endian, this output
-will match the placement by the hardware instruction (vextdubvrx, vextduhvrx,
-vextduwvrx, vextddvrx) i.e., dword[0] in RTL
-notation. For big-endian, an additional instruction is needed to move it
-from the "left" doubleword to the "right" one. For little-endian, semantics
-matching the @code{vextdubvlx}, @code{vextduhvlx}, @code{vextduwvlx}
-instructions will be generated, while for big-endian, semantics matching the
-@code{vextdubvrx}, @code{vextduhvrx}, @code{vextduwvrx} instructions will
-be generated. Note that some fairly anomalous
-results can be generated if the byte index is not aligned on the
-element boundary for the element being extracted. This is a
-limitation of the bi-endian vector programming model consistent with the
-limitation on @code{vec_perm}.
-@findex vec_extracth
-@smallexample
-@exdent vector unsigned long long int
-@exdent vec_pdep (vector unsigned long long int, vector unsigned long long int);
-@end smallexample
-Perform a vector parallel bits deposit operation, as if implemented by
-the @code{vpdepd} instruction.
-@findex vec_pdep
-
-Vector Insert
-
-@smallexample
-@exdent vector unsigned char
-@exdent vec_insertl (unsigned char, vector unsigned char, unsigned int);
-@exdent vector unsigned short
-@exdent vec_insertl (unsigned short, vector unsigned short, unsigned int);
-@exdent vector unsigned int
-@exdent vec_insertl (unsigned int, vector unsigned int, unsigned int);
-@exdent vector unsigned long long
-@exdent vec_insertl (unsigned long long, vector unsigned long long,
-unsigned int);
-@exdent vector unsigned char
-@exdent vec_insertl (vector unsigned char, vector unsigned char, unsigned int;
-@exdent vector unsigned short
-@exdent vec_insertl (vector unsigned short, vector unsigned short,
-unsigned int);
-@exdent vector unsigned int
-@exdent vec_insertl (vector unsigned int, vector unsigned int, unsigned int);
-@end smallexample
-
-Let src be the first argument, when the first argument is a scalar, or the
-rightmost element of the left doubleword of the first argument, when the first
-argument is a vector. Insert the source into the destination at the position
-given by the third argument, using natural element order in the second
-argument. The rest of the second argument is unchanged. If the byte
-index is greater than 14 for halfwords, greater than 12 for words, or
-greater than 8 for doublewords the result is undefined. For little-endian,
-the generated code will be semantically equivalent to @code{vins[bhwd]rx}
-instructions. Similarly for big-endian it will be semantically equivalent
-to @code{vins[bhwd]lx}. Note that some fairly anomalous results can be
-generated if the byte index is not aligned on an element boundary for the
-type of element being inserted.
-@findex vec_insertl
-
-@smallexample
-@exdent vector unsigned char
-@exdent vec_inserth (unsigned char, vector unsigned char, unsigned int);
-@exdent vector unsigned short
-@exdent vec_inserth (unsigned short, vector unsigned short, unsigned int);
-@exdent vector unsigned int
-@exdent vec_inserth (unsigned int, vector unsigned int, unsigned int);
-@exdent vector unsigned long long
-@exdent vec_inserth (unsigned long long, vector unsigned long long,
-unsigned int);
-@exdent vector unsigned char
-@exdent vec_inserth (vector unsigned char, vector unsigned char, unsigned int);
-@exdent vector unsigned short
-@exdent vec_inserth (vector unsigned short, vector unsigned short,
-unsigned int);
-@exdent vector unsigned int
-@exdent vec_inserth (vector unsigned int, vector unsigned int, unsigned int);
-@end smallexample
-
-Let src be the first argument, when the first argument is a scalar, or the
-rightmost element of the first argument, when the first argument is a vector.
-Insert src into the second argument at the position identified by the third
-argument, using opposite element order in the second argument, and leaving the
-rest of the second argument unchanged. If the byte index is greater than 14
-for halfwords, 12 for words, or 8 for doublewords, the intrinsic will be
-rejected. Note that the underlying hardware instruction uses the same register
-for the second argument and the result.
-For little-endian, the code generation will be semantically equivalent to
-@code{vins[bhwd]lx}, while for big-endian it will be semantically equivalent to
-@code{vins[bhwd]rx}.
-Note that some fairly anomalous results can be generated if the byte index is
-not aligned on an element boundary for the sort of element being inserted.
-@findex vec_inserth
-
-Vector Replace Element
-@smallexample
-@exdent vector signed int vec_replace_elt (vector signed int, signed int,
-const int);
-@exdent vector unsigned int vec_replace_elt (vector unsigned int,
-unsigned int, const int);
-@exdent vector float vec_replace_elt (vector float, float, const int);
-@exdent vector signed long long vec_replace_elt (vector signed long long,
-signed long long, const int);
-@exdent vector unsigned long long vec_replace_elt (vector unsigned long long,
-unsigned long long, const int);
-@exdent vector double rec_replace_elt (vector double, double, const int);
-@end smallexample
-The third argument (constrained to [0,3]) identifies the natural-endian
-element number of the first argument that will be replaced by the second
-argument to produce the result. The other elements of the first argument will
-remain unchanged in the result.
-
-If it's desirable to insert a word at an unaligned position, use
-vec_replace_unaligned instead.
-
-@findex vec_replace_element
-
-Vector Replace Unaligned
-@smallexample
-@exdent vector unsigned char vec_replace_unaligned (vector unsigned char,
-signed int, const int);
-@exdent vector unsigned char vec_replace_unaligned (vector unsigned char,
-unsigned int, const int);
-@exdent vector unsigned char vec_replace_unaligned (vector unsigned char,
-float, const int);
-@exdent vector unsigned char vec_replace_unaligned (vector unsigned char,
-signed long long, const int);
-@exdent vector unsigned char vec_replace_unaligned (vector unsigned char,
-unsigned long long, const int);
-@exdent vector unsigned char vec_replace_unaligned (vector unsigned char,
-double, const int);
-@end smallexample
-
-The second argument replaces a portion of the first argument to produce the
-result, with the rest of the first argument unchanged in the result. The
-third argument identifies the byte index (using left-to-right, or big-endian
-order) where the high-order byte of the second argument will be placed, with
-the remaining bytes of the second argument placed naturally "to the right"
-of the high-order byte.
-
-The programmer is responsible for understanding the endianness issues involved
-with the first argument and the result.
-@findex vec_replace_unaligned
-
-Vector Shift Left Double Bit Immediate
-@smallexample
-@exdent vector signed char vec_sldb (vector signed char, vector signed char,
-const unsigned int);
-@exdent vector unsigned char vec_sldb (vector unsigned char,
-vector unsigned char, const unsigned int);
-@exdent vector signed short vec_sldb (vector signed short, vector signed short,
-const unsigned int);
-@exdent vector unsigned short vec_sldb (vector unsigned short,
-vector unsigned short, const unsigned int);
-@exdent vector signed int vec_sldb (vector signed int, vector signed int,
-const unsigned int);
-@exdent vector unsigned int vec_sldb (vector unsigned int, vector unsigned int,
-const unsigned int);
-@exdent vector signed long long vec_sldb (vector signed long long,
-vector signed long long, const unsigned int);
-@exdent vector unsigned long long vec_sldb (vector unsigned long long,
-vector unsigned long long, const unsigned int);
-@end smallexample
-
-Shift the combined input vectors left by the amount specified by the low-order
-three bits of the third argument, and return the leftmost remaining 128 bits.
-Code using this instruction must be endian-aware.
-
-@findex vec_sldb
-
-Vector Shift Right Double Bit Immediate
-
-@smallexample
-@exdent vector signed char vec_srdb (vector signed char, vector signed char,
-const unsigned int);
-@exdent vector unsigned char vec_srdb (vector unsigned char, vector unsigned char,
-const unsigned int);
-@exdent vector signed short vec_srdb (vector signed short, vector signed short,
-const unsigned int);
-@exdent vector unsigned short vec_srdb (vector unsigned short, vector unsigned short,
-const unsigned int);
-@exdent vector signed int vec_srdb (vector signed int, vector signed int,
-const unsigned int);
-@exdent vector unsigned int vec_srdb (vector unsigned int, vector unsigned int,
-const unsigned int);
-@exdent vector signed long long vec_srdb (vector signed long long,
-vector signed long long, const unsigned int);
-@exdent vector unsigned long long vec_srdb (vector unsigned long long,
-vector unsigned long long, const unsigned int);
-@end smallexample
-
-Shift the combined input vectors right by the amount specified by the low-order
-three bits of the third argument, and return the remaining 128 bits. Code
-using this built-in must be endian-aware.
-
-@findex vec_srdb
-
-Vector Splat
-
-@smallexample
-@exdent vector signed int vec_splati (const signed int);
-@exdent vector float vec_splati (const float);
-@end smallexample
-
-Splat a 32-bit immediate into a vector of words.
-
-@findex vec_splati
-
-@smallexample
-@exdent vector double vec_splatid (const float);
-@end smallexample
-
-Convert a single precision floating-point value to double-precision and splat
-the result to a vector of double-precision floats.
-
-@findex vec_splatid
-
-@smallexample
-@exdent vector signed int vec_splati_ins (vector signed int,
-const unsigned int, const signed int);
-@exdent vector unsigned int vec_splati_ins (vector unsigned int,
-const unsigned int, const unsigned int);
-@exdent vector float vec_splati_ins (vector float, const unsigned int,
-const float);
-@end smallexample
-
-Argument 2 must be either 0 or 1. Splat the value of argument 3 into the word
-identified by argument 2 of each doubleword of argument 1 and return the
-result. The other words of argument 1 are unchanged.
-
-@findex vec_splati_ins
-
-Vector Blend Variable
-
-@smallexample
-@exdent vector signed char vec_blendv (vector signed char, vector signed char,
-vector unsigned char);
-@exdent vector unsigned char vec_blendv (vector unsigned char,
-vector unsigned char, vector unsigned char);
-@exdent vector signed short vec_blendv (vector signed short,
-vector signed short, vector unsigned short);
-@exdent vector unsigned short vec_blendv (vector unsigned short,
-vector unsigned short, vector unsigned short);
-@exdent vector signed int vec_blendv (vector signed int, vector signed int,
-vector unsigned int);
-@exdent vector unsigned int vec_blendv (vector unsigned int,
-vector unsigned int, vector unsigned int);
-@exdent vector signed long long vec_blendv (vector signed long long,
-vector signed long long, vector unsigned long long);
-@exdent vector unsigned long long vec_blendv (vector unsigned long long,
-vector unsigned long long, vector unsigned long long);
-@exdent vector float vec_blendv (vector float, vector float,
-vector unsigned int);
-@exdent vector double vec_blendv (vector double, vector double,
-vector unsigned long long);
-@end smallexample
-
-Blend the first and second argument vectors according to the sign bits of the
-corresponding elements of the third argument vector. This is similar to the
-@code{vsel} and @code{xxsel} instructions but for bigger elements.
-
-@findex vec_blendv
-
-Vector Permute Extended
-
-@smallexample
-@exdent vector signed char vec_permx (vector signed char, vector signed char,
-vector unsigned char, const int);
-@exdent vector unsigned char vec_permx (vector unsigned char,
-vector unsigned char, vector unsigned char, const int);
-@exdent vector signed short vec_permx (vector signed short,
-vector signed short, vector unsigned char, const int);
-@exdent vector unsigned short vec_permx (vector unsigned short,
-vector unsigned short, vector unsigned char, const int);
-@exdent vector signed int vec_permx (vector signed int, vector signed int,
-vector unsigned char, const int);
-@exdent vector unsigned int vec_permx (vector unsigned int,
-vector unsigned int, vector unsigned char, const int);
-@exdent vector signed long long vec_permx (vector signed long long,
-vector signed long long, vector unsigned char, const int);
-@exdent vector unsigned long long vec_permx (vector unsigned long long,
-vector unsigned long long, vector unsigned char, const int);
-@exdent vector float (vector float, vector float, vector unsigned char,
-const int);
-@exdent vector double (vector double, vector double, vector unsigned char,
-const int);
-@end smallexample
-
-Perform a partial permute of the first two arguments, which form a 32-byte
-section of an emulated vector up to 256 bytes wide, using the partial permute
-control vector in the third argument. The fourth argument (constrained to
-values of 0-7) identifies which 32-byte section of the emulated vector is
-contained in the first two arguments.
-@findex vec_permx
-
-@smallexample
-@exdent vector unsigned long long int
-@exdent vec_pext (vector unsigned long long int, vector unsigned long long int);
-@end smallexample
-Perform a vector parallel bit extract operation, as if implemented by
-the @code{vpextd} instruction.
-@findex vec_pext
-
-@smallexample
-@exdent vector unsigned char vec_stril (vector unsigned char);
-@exdent vector signed char vec_stril (vector signed char);
-@exdent vector unsigned short vec_stril (vector unsigned short);
-@exdent vector signed short vec_stril (vector signed short);
-@end smallexample
-Isolate the left-most non-zero elements of the incoming vector argument,
-replacing all elements to the right of the left-most zero element
-found within the argument with zero. The typical implementation uses
-the @code{vstribl} or @code{vstrihl} instruction on big-endian targets
-and uses the @code{vstribr} or @code{vstrihr} instruction on
-little-endian targets.
-@findex vec_stril
-
-@smallexample
-@exdent int vec_stril_p (vector unsigned char);
-@exdent int vec_stril_p (vector signed char);
-@exdent int short vec_stril_p (vector unsigned short);
-@exdent int vec_stril_p (vector signed short);
-@end smallexample
-Return a non-zero value if and only if the argument contains a zero
-element. The typical implementation uses
-the @code{vstribl.} or @code{vstrihl.} instruction on big-endian targets
-and uses the @code{vstribr.} or @code{vstrihr.} instruction on
-little-endian targets. Choose this built-in to check for presence of
-zero element if the same argument is also passed to @code{vec_stril}.
-@findex vec_stril_p
-
-@smallexample
-@exdent vector unsigned char vec_strir (vector unsigned char);
-@exdent vector signed char vec_strir (vector signed char);
-@exdent vector unsigned short vec_strir (vector unsigned short);
-@exdent vector signed short vec_strir (vector signed short);
-@end smallexample
-Isolate the right-most non-zero elements of the incoming vector argument,
-replacing all elements to the left of the right-most zero element
-found within the argument with zero. The typical implementation uses
-the @code{vstribr} or @code{vstrihr} instruction on big-endian targets
-and uses the @code{vstribl} or @code{vstrihl} instruction on
-little-endian targets.
-@findex vec_strir
-
-@smallexample
-@exdent int vec_strir_p (vector unsigned char);
-@exdent int vec_strir_p (vector signed char);
-@exdent int short vec_strir_p (vector unsigned short);
-@exdent int vec_strir_p (vector signed short);
-@end smallexample
-Return a non-zero value if and only if the argument contains a zero
-element. The typical implementation uses
-the @code{vstribr.} or @code{vstrihr.} instruction on big-endian targets
-and uses the @code{vstribl.} or @code{vstrihl.} instruction on
-little-endian targets. Choose this built-in to check for presence of
-zero element if the same argument is also passed to @code{vec_strir}.
-@findex vec_strir_p
-
-@smallexample
-@exdent vector unsigned char
-@exdent vec_ternarylogic (vector unsigned char, vector unsigned char,
- vector unsigned char, const unsigned int);
-@exdent vector unsigned short
-@exdent vec_ternarylogic (vector unsigned short, vector unsigned short,
- vector unsigned short, const unsigned int);
-@exdent vector unsigned int
-@exdent vec_ternarylogic (vector unsigned int, vector unsigned int,
- vector unsigned int, const unsigned int);
-@exdent vector unsigned long long int
-@exdent vec_ternarylogic (vector unsigned long long int, vector unsigned long long int,
- vector unsigned long long int, const unsigned int);
-@exdent vector unsigned __int128
-@exdent vec_ternarylogic (vector unsigned __int128, vector unsigned __int128,
- vector unsigned __int128, const unsigned int);
-@end smallexample
-Perform a 128-bit vector evaluate operation, as if implemented by the
-@code{xxeval} instruction. The fourth argument must be a literal
-integer value between 0 and 255 inclusive.
-@findex vec_ternarylogic
-
-@smallexample
-@exdent vector unsigned char vec_genpcvm (vector unsigned char, const int);
-@exdent vector unsigned short vec_genpcvm (vector unsigned short, const int);
-@exdent vector unsigned int vec_genpcvm (vector unsigned int, const int);
-@exdent vector unsigned int vec_genpcvm (vector unsigned long long int,
- const int);
-@end smallexample
-
-Vector Integer Multiply/Divide/Modulo
-
-@smallexample
-@exdent vector signed int
-@exdent vec_mulh (vector signed int a, vector signed int b);
-@exdent vector unsigned int
-@exdent vec_mulh (vector unsigned int a, vector unsigned int b);
-@end smallexample
-
-For each integer value @code{i} from 0 to 3, do the following. The integer
-value in word element @code{i} of a is multiplied by the integer value in word
-element @code{i} of b. The high-order 32 bits of the 64-bit product are placed
-into word element @code{i} of the vector returned.
-
-@smallexample
-@exdent vector signed long long
-@exdent vec_mulh (vector signed long long a, vector signed long long b);
-@exdent vector unsigned long long
-@exdent vec_mulh (vector unsigned long long a, vector unsigned long long b);
-@end smallexample
-
-For each integer value @code{i} from 0 to 1, do the following. The integer
-value in doubleword element @code{i} of a is multiplied by the integer value in
-doubleword element @code{i} of b. The high-order 64 bits of the 128-bit product
-are placed into doubleword element @code{i} of the vector returned.
-
-@smallexample
-@exdent vector unsigned long long
-@exdent vec_mul (vector unsigned long long a, vector unsigned long long b);
-@exdent vector signed long long
-@exdent vec_mul (vector signed long long a, vector signed long long b);
-@end smallexample
-
-For each integer value @code{i} from 0 to 1, do the following. The integer
-value in doubleword element @code{i} of a is multiplied by the integer value in
-doubleword element @code{i} of b. The low-order 64 bits of the 128-bit product
-are placed into doubleword element @code{i} of the vector returned.
-
-@smallexample
-@exdent vector signed int
-@exdent vec_div (vector signed int a, vector signed int b);
-@exdent vector unsigned int
-@exdent vec_div (vector unsigned int a, vector unsigned int b);
-@end smallexample
-
-For each integer value @code{i} from 0 to 3, do the following. The integer in
-word element @code{i} of a is divided by the integer in word element @code{i}
-of b. The unique integer quotient is placed into the word element @code{i} of
-the vector returned. If an attempt is made to perform any of the divisions
-<anything> ÷ 0 then the quotient is undefined.
-
-@smallexample
-@exdent vector signed long long
-@exdent vec_div (vector signed long long a, vector signed long long b);
-@exdent vector unsigned long long
-@exdent vec_div (vector unsigned long long a, vector unsigned long long b);
-@end smallexample
-
-For each integer value @code{i} from 0 to 1, do the following. The integer in
-doubleword element @code{i} of a is divided by the integer in doubleword
-element @code{i} of b. The unique integer quotient is placed into the
-doubleword element @code{i} of the vector returned. If an attempt is made to
-perform any of the divisions 0x8000_0000_0000_0000 ÷ -1 or <anything> ÷ 0 then
-the quotient is undefined.
-
-@smallexample
-@exdent vector signed int
-@exdent vec_dive (vector signed int a, vector signed int b);
-@exdent vector unsigned int
-@exdent vec_dive (vector unsigned int a, vector unsigned int b);
-@end smallexample
-
-For each integer value @code{i} from 0 to 3, do the following. The integer in
-word element @code{i} of a is shifted left by 32 bits, then divided by the
-integer in word element @code{i} of b. The unique integer quotient is placed
-into the word element @code{i} of the vector returned. If the quotient cannot
-be represented in 32 bits, or if an attempt is made to perform any of the
-divisions <anything> ÷ 0 then the quotient is undefined.
-
-@smallexample
-@exdent vector signed long long
-@exdent vec_dive (vector signed long long a, vector signed long long b);
-@exdent vector unsigned long long
-@exdent vec_dive (vector unsigned long long a, vector unsigned long long b);
-@end smallexample
-
-For each integer value @code{i} from 0 to 1, do the following. The integer in
-doubleword element @code{i} of a is shifted left by 64 bits, then divided by
-the integer in doubleword element @code{i} of b. The unique integer quotient is
-placed into the doubleword element @code{i} of the vector returned. If the
-quotient cannot be represented in 64 bits, or if an attempt is made to perform
-<anything> ÷ 0 then the quotient is undefined.
-
-@smallexample
-@exdent vector signed int
-@exdent vec_mod (vector signed int a, vector signed int b);
-@exdent vector unsigned int
-@exdent vec_mod (vector unsigned int a, vector unsigned int b);
-@end smallexample
-
-For each integer value @code{i} from 0 to 3, do the following. The integer in
-word element @code{i} of a is divided by the integer in word element @code{i}
-of b. The unique integer remainder is placed into the word element @code{i} of
-the vector returned. If an attempt is made to perform any of the divisions
-0x8000_0000 ÷ -1 or <anything> ÷ 0 then the remainder is undefined.
-
-@smallexample
-@exdent vector signed long long
-@exdent vec_mod (vector signed long long a, vector signed long long b);
-@exdent vector unsigned long long
-@exdent vec_mod (vector unsigned long long a, vector unsigned long long b);
-@end smallexample
-
-For each integer value @code{i} from 0 to 1, do the following. The integer in
-doubleword element @code{i} of a is divided by the integer in doubleword
-element @code{i} of b. The unique integer remainder is placed into the
-doubleword element @code{i} of the vector returned. If an attempt is made to
-perform <anything> ÷ 0 then the remainder is undefined.
-
-Generate PCV from specified Mask size, as if implemented by the
-@code{xxgenpcvbm}, @code{xxgenpcvhm}, @code{xxgenpcvwm} instructions, where
-immediate value is either 0, 1, 2 or 3.
-@findex vec_genpcvm
-
-@smallexample
-@exdent vector unsigned __int128 vec_rl (vector unsigned __int128 A,
- vector unsigned __int128 B);
-@exdent vector signed __int128 vec_rl (vector signed __int128 A,
- vector unsigned __int128 B);
-@end smallexample
-
-Result value: Each element of R is obtained by rotating the corresponding element
-of A left by the number of bits specified by the corresponding element of B.
-
-
-@smallexample
-@exdent vector unsigned __int128 vec_rlmi (vector unsigned __int128,
- vector unsigned __int128,
- vector unsigned __int128);
-@exdent vector signed __int128 vec_rlmi (vector signed __int128,
- vector signed __int128,
- vector unsigned __int128);
-@end smallexample
-
-Returns the result of rotating the first input and inserting it under mask
-into the second input. The first bit in the mask, the last bit in the mask are
-obtained from the two 7-bit fields bits [108:115] and bits [117:123]
-respectively of the second input. The shift is obtained from the third input
-in the 7-bit field [125:131] where all bits counted from zero at the left.
-
-@smallexample
-@exdent vector unsigned __int128 vec_rlnm (vector unsigned __int128,
- vector unsigned __int128,
- vector unsigned __int128);
-@exdent vector signed __int128 vec_rlnm (vector signed __int128,
- vector unsigned __int128,
- vector unsigned __int128);
-@end smallexample
-
-Returns the result of rotating the first input and ANDing it with a mask. The
-first bit in the mask and the last bit in the mask are obtained from the two
-7-bit fields bits [117:123] and bits [125:131] respectively of the second
-input. The shift is obtained from the third input in the 7-bit field bits
-[125:131] where all bits counted from zero at the left.
-
-@smallexample
-@exdent vector unsigned __int128 vec_sl(vector unsigned __int128 A, vector unsigned __int128 B);
-@exdent vector signed __int128 vec_sl(vector signed __int128 A, vector unsigned __int128 B);
-@end smallexample
-
-Result value: Each element of R is obtained by shifting the corresponding element of
-A left by the number of bits specified by the corresponding element of B.
-
-@smallexample
-@exdent vector unsigned __int128 vec_sr(vector unsigned __int128 A, vector unsigned __int128 B);
-@exdent vector signed __int128 vec_sr(vector signed __int128 A, vector unsigned __int128 B);
-@end smallexample
-
-Result value: Each element of R is obtained by shifting the corresponding element of
-A right by the number of bits specified by the corresponding element of B.
-
-@smallexample
-@exdent vector unsigned __int128 vec_sra(vector unsigned __int128 A, vector unsigned __int128 B);
-@exdent vector signed __int128 vec_sra(vector signed __int128 A, vector unsigned __int128 B);
-@end smallexample
-
-Result value: Each element of R is obtained by arithmetic shifting the corresponding
-element of A right by the number of bits specified by the corresponding element of B.
-
-@smallexample
-@exdent vector unsigned __int128 vec_mule (vector unsigned long long,
- vector unsigned long long);
-@exdent vector signed __int128 vec_mule (vector signed long long,
- vector signed long long);
-@end smallexample
-
-Returns a vector containing a 128-bit integer result of multiplying the even
-doubleword elements of the two inputs.
-
-@smallexample
-@exdent vector unsigned __int128 vec_mulo (vector unsigned long long,
- vector unsigned long long);
-@exdent vector signed __int128 vec_mulo (vector signed long long,
- vector signed long long);
-@end smallexample
-
-Returns a vector containing a 128-bit integer result of multiplying the odd
-doubleword elements of the two inputs.
-
-@smallexample
-@exdent vector unsigned __int128 vec_div (vector unsigned __int128,
- vector unsigned __int128);
-@exdent vector signed __int128 vec_div (vector signed __int128,
- vector signed __int128);
-@end smallexample
-
-Returns the result of dividing the first operand by the second operand. An
-attempt to divide any value by zero or to divide the most negative signed
-128-bit integer by negative one results in an undefined value.
-
-@smallexample
-@exdent vector unsigned __int128 vec_dive (vector unsigned __int128,
- vector unsigned __int128);
-@exdent vector signed __int128 vec_dive (vector signed __int128,
- vector signed __int128);
-@end smallexample
-
-The result is produced by shifting the first input left by 128 bits and
-dividing by the second. If an attempt is made to divide by zero or the result
-is larger than 128 bits, the result is undefined.
-
-@smallexample
-@exdent vector unsigned __int128 vec_mod (vector unsigned __int128,
- vector unsigned __int128);
-@exdent vector signed __int128 vec_mod (vector signed __int128,
- vector signed __int128);
-@end smallexample
-
-The result is the modulo result of dividing the first input by the second
-input.
-
-The following builtins perform 128-bit vector comparisons. The
-@code{vec_all_xx}, @code{vec_any_xx}, and @code{vec_cmpxx}, where @code{xx} is
-one of the operations @code{eq, ne, gt, lt, ge, le} perform pairwise
-comparisons between the elements at the same positions within their two vector
-arguments. The @code{vec_all_xx}function returns a non-zero value if and only
-if all pairwise comparisons are true. The @code{vec_any_xx} function returns
-a non-zero value if and only if at least one pairwise comparison is true. The
-@code{vec_cmpxx}function returns a vector of the same type as its two
-arguments, within which each element consists of all ones to denote that
-specified logical comparison of the corresponding elements was true.
-Otherwise, the element of the returned vector contains all zeros.
-
-@smallexample
-vector bool __int128 vec_cmpeq (vector signed __int128, vector signed __int128);
-vector bool __int128 vec_cmpeq (vector unsigned __int128, vector unsigned __int128);
-vector bool __int128 vec_cmpne (vector signed __int128, vector signed __int128);
-vector bool __int128 vec_cmpne (vector unsigned __int128, vector unsigned __int128);
-vector bool __int128 vec_cmpgt (vector signed __int128, vector signed __int128);
-vector bool __int128 vec_cmpgt (vector unsigned __int128, vector unsigned __int128);
-vector bool __int128 vec_cmplt (vector signed __int128, vector signed __int128);
-vector bool __int128 vec_cmplt (vector unsigned __int128, vector unsigned __int128);
-vector bool __int128 vec_cmpge (vector signed __int128, vector signed __int128);
-vector bool __int128 vec_cmpge (vector unsigned __int128, vector unsigned __int128);
-vector bool __int128 vec_cmple (vector signed __int128, vector signed __int128);
-vector bool __int128 vec_cmple (vector unsigned __int128, vector unsigned __int128);
-
-int vec_all_eq (vector signed __int128, vector signed __int128);
-int vec_all_eq (vector unsigned __int128, vector unsigned __int128);
-int vec_all_ne (vector signed __int128, vector signed __int128);
-int vec_all_ne (vector unsigned __int128, vector unsigned __int128);
-int vec_all_gt (vector signed __int128, vector signed __int128);
-int vec_all_gt (vector unsigned __int128, vector unsigned __int128);
-int vec_all_lt (vector signed __int128, vector signed __int128);
-int vec_all_lt (vector unsigned __int128, vector unsigned __int128);
-int vec_all_ge (vector signed __int128, vector signed __int128);
-int vec_all_ge (vector unsigned __int128, vector unsigned __int128);
-int vec_all_le (vector signed __int128, vector signed __int128);
-int vec_all_le (vector unsigned __int128, vector unsigned __int128);
-
-int vec_any_eq (vector signed __int128, vector signed __int128);
-int vec_any_eq (vector unsigned __int128, vector unsigned __int128);
-int vec_any_ne (vector signed __int128, vector signed __int128);
-int vec_any_ne (vector unsigned __int128, vector unsigned __int128);
-int vec_any_gt (vector signed __int128, vector signed __int128);
-int vec_any_gt (vector unsigned __int128, vector unsigned __int128);
-int vec_any_lt (vector signed __int128, vector signed __int128);
-int vec_any_lt (vector unsigned __int128, vector unsigned __int128);
-int vec_any_ge (vector signed __int128, vector signed __int128);
-int vec_any_ge (vector unsigned __int128, vector unsigned __int128);
-int vec_any_le (vector signed __int128, vector signed __int128);
-int vec_any_le (vector unsigned __int128, vector unsigned __int128);
-@end smallexample
-
-
-@node PowerPC Hardware Transactional Memory Built-in Functions
-@subsection PowerPC Hardware Transactional Memory Built-in Functions
-GCC provides two interfaces for accessing the Hardware Transactional
-Memory (HTM) instructions available on some of the PowerPC family
-of processors (eg, POWER8). The two interfaces come in a low level
-interface, consisting of built-in functions specific to PowerPC and a
-higher level interface consisting of inline functions that are common
-between PowerPC and S/390.
-
-@subsubsection PowerPC HTM Low Level Built-in Functions
-
-The following low level built-in functions are available with
-@option{-mhtm} or @option{-mcpu=CPU} where CPU is `power8' or later.
-They all generate the machine instruction that is part of the name.
-
-The HTM builtins (with the exception of @code{__builtin_tbegin}) return
-the full 4-bit condition register value set by their associated hardware
-instruction. The header file @code{htmintrin.h} defines some macros that can
-be used to decipher the return value. The @code{__builtin_tbegin} builtin
-returns a simple @code{true} or @code{false} value depending on whether a transaction was
-successfully started or not. The arguments of the builtins match exactly the
-type and order of the associated hardware instruction's operands, except for
-the @code{__builtin_tcheck} builtin, which does not take any input arguments.
-Refer to the ISA manual for a description of each instruction's operands.
-
-@smallexample
-unsigned int __builtin_tbegin (unsigned int);
-unsigned int __builtin_tend (unsigned int);
-
-unsigned int __builtin_tabort (unsigned int);
-unsigned int __builtin_tabortdc (unsigned int, unsigned int, unsigned int);
-unsigned int __builtin_tabortdci (unsigned int, unsigned int, int);
-unsigned int __builtin_tabortwc (unsigned int, unsigned int, unsigned int);
-unsigned int __builtin_tabortwci (unsigned int, unsigned int, int);
-
-unsigned int __builtin_tcheck (void);
-unsigned int __builtin_treclaim (unsigned int);
-unsigned int __builtin_trechkpt (void);
-unsigned int __builtin_tsr (unsigned int);
-@end smallexample
-
-In addition to the above HTM built-ins, we have added built-ins for
-some common extended mnemonics of the HTM instructions:
-
-@smallexample
-unsigned int __builtin_tendall (void);
-unsigned int __builtin_tresume (void);
-unsigned int __builtin_tsuspend (void);
-@end smallexample
-
-Note that the semantics of the above HTM builtins are required to mimic
-the locking semantics used for critical sections. Builtins that are used
-to create a new transaction or restart a suspended transaction must have
-lock acquisition like semantics while those builtins that end or suspend a
-transaction must have lock release like semantics. Specifically, this must
-mimic lock semantics as specified by C++11, for example: Lock acquisition is
-as-if an execution of __atomic_exchange_n(&globallock,1,__ATOMIC_ACQUIRE)
-that returns 0, and lock release is as-if an execution of
-__atomic_store(&globallock,0,__ATOMIC_RELEASE), with globallock being an
-implicit implementation-defined lock used for all transactions. The HTM
-instructions associated with with the builtins inherently provide the
-correct acquisition and release hardware barriers required. However,
-the compiler must also be prohibited from moving loads and stores across
-the builtins in a way that would violate their semantics. This has been
-accomplished by adding memory barriers to the associated HTM instructions
-(which is a conservative approach to provide acquire and release semantics).
-Earlier versions of the compiler did not treat the HTM instructions as
-memory barriers. A @code{__TM_FENCE__} macro has been added, which can
-be used to determine whether the current compiler treats HTM instructions
-as memory barriers or not. This allows the user to explicitly add memory
-barriers to their code when using an older version of the compiler.
-
-The following set of built-in functions are available to gain access
-to the HTM specific special purpose registers.
-
-@smallexample
-unsigned long __builtin_get_texasr (void);
-unsigned long __builtin_get_texasru (void);
-unsigned long __builtin_get_tfhar (void);
-unsigned long __builtin_get_tfiar (void);
-
-void __builtin_set_texasr (unsigned long);
-void __builtin_set_texasru (unsigned long);
-void __builtin_set_tfhar (unsigned long);
-void __builtin_set_tfiar (unsigned long);
-@end smallexample
-
-Example usage of these low level built-in functions may look like:
-
-@smallexample
-#include <htmintrin.h>
-
-int num_retries = 10;
-
-while (1)
- @{
- if (__builtin_tbegin (0))
- @{
- /* Transaction State Initiated. */
- if (is_locked (lock))
- __builtin_tabort (0);
- ... transaction code...
- __builtin_tend (0);
- break;
- @}
- else
- @{
- /* Transaction State Failed. Use locks if the transaction
- failure is "persistent" or we've tried too many times. */
- if (num_retries-- <= 0
- || _TEXASRU_FAILURE_PERSISTENT (__builtin_get_texasru ()))
- @{
- acquire_lock (lock);
- ... non transactional fallback path...
- release_lock (lock);
- break;
- @}
- @}
- @}
-@end smallexample
-
-One final built-in function has been added that returns the value of
-the 2-bit Transaction State field of the Machine Status Register (MSR)
-as stored in @code{CR0}.
-
-@smallexample
-unsigned long __builtin_ttest (void)
-@end smallexample
-
-This built-in can be used to determine the current transaction state
-using the following code example:
-
-@smallexample
-#include <htmintrin.h>
-
-unsigned char tx_state = _HTM_STATE (__builtin_ttest ());
-
-if (tx_state == _HTM_TRANSACTIONAL)
- @{
- /* Code to use in transactional state. */
- @}
-else if (tx_state == _HTM_NONTRANSACTIONAL)
- @{
- /* Code to use in non-transactional state. */
- @}
-else if (tx_state == _HTM_SUSPENDED)
- @{
- /* Code to use in transaction suspended state. */
- @}
-@end smallexample
-
-@subsubsection PowerPC HTM High Level Inline Functions
-
-The following high level HTM interface is made available by including
-@code{<htmxlintrin.h>} and using @option{-mhtm} or @option{-mcpu=CPU}
-where CPU is `power8' or later. This interface is common between PowerPC
-and S/390, allowing users to write one HTM source implementation that
-can be compiled and executed on either system.
-
-@smallexample
-long __TM_simple_begin (void);
-long __TM_begin (void* const TM_buff);
-long __TM_end (void);
-void __TM_abort (void);
-void __TM_named_abort (unsigned char const code);
-void __TM_resume (void);
-void __TM_suspend (void);
-
-long __TM_is_user_abort (void* const TM_buff);
-long __TM_is_named_user_abort (void* const TM_buff, unsigned char *code);
-long __TM_is_illegal (void* const TM_buff);
-long __TM_is_footprint_exceeded (void* const TM_buff);
-long __TM_nesting_depth (void* const TM_buff);
-long __TM_is_nested_too_deep(void* const TM_buff);
-long __TM_is_conflict(void* const TM_buff);
-long __TM_is_failure_persistent(void* const TM_buff);
-long __TM_failure_address(void* const TM_buff);
-long long __TM_failure_code(void* const TM_buff);
-@end smallexample
-
-Using these common set of HTM inline functions, we can create
-a more portable version of the HTM example in the previous
-section that will work on either PowerPC or S/390:
-
-@smallexample
-#include <htmxlintrin.h>
-
-int num_retries = 10;
-TM_buff_type TM_buff;
-
-while (1)
- @{
- if (__TM_begin (TM_buff) == _HTM_TBEGIN_STARTED)
- @{
- /* Transaction State Initiated. */
- if (is_locked (lock))
- __TM_abort ();
- ... transaction code...
- __TM_end ();
- break;
- @}
- else
- @{
- /* Transaction State Failed. Use locks if the transaction
- failure is "persistent" or we've tried too many times. */
- if (num_retries-- <= 0
- || __TM_is_failure_persistent (TM_buff))
- @{
- acquire_lock (lock);
- ... non transactional fallback path...
- release_lock (lock);
- break;
- @}
- @}
- @}
-@end smallexample
-
-@node PowerPC Atomic Memory Operation Functions
-@subsection PowerPC Atomic Memory Operation Functions
-ISA 3.0 of the PowerPC added new atomic memory operation (amo)
-instructions. GCC provides support for these instructions in 64-bit
-environments. All of the functions are declared in the include file
-@code{amo.h}.
-
-The functions supported are:
-
-@smallexample
-#include <amo.h>
-
-uint32_t amo_lwat_add (uint32_t *, uint32_t);
-uint32_t amo_lwat_xor (uint32_t *, uint32_t);
-uint32_t amo_lwat_ior (uint32_t *, uint32_t);
-uint32_t amo_lwat_and (uint32_t *, uint32_t);
-uint32_t amo_lwat_umax (uint32_t *, uint32_t);
-uint32_t amo_lwat_umin (uint32_t *, uint32_t);
-uint32_t amo_lwat_swap (uint32_t *, uint32_t);
-
-int32_t amo_lwat_sadd (int32_t *, int32_t);
-int32_t amo_lwat_smax (int32_t *, int32_t);
-int32_t amo_lwat_smin (int32_t *, int32_t);
-int32_t amo_lwat_sswap (int32_t *, int32_t);
-
-uint64_t amo_ldat_add (uint64_t *, uint64_t);
-uint64_t amo_ldat_xor (uint64_t *, uint64_t);
-uint64_t amo_ldat_ior (uint64_t *, uint64_t);
-uint64_t amo_ldat_and (uint64_t *, uint64_t);
-uint64_t amo_ldat_umax (uint64_t *, uint64_t);
-uint64_t amo_ldat_umin (uint64_t *, uint64_t);
-uint64_t amo_ldat_swap (uint64_t *, uint64_t);
-
-int64_t amo_ldat_sadd (int64_t *, int64_t);
-int64_t amo_ldat_smax (int64_t *, int64_t);
-int64_t amo_ldat_smin (int64_t *, int64_t);
-int64_t amo_ldat_sswap (int64_t *, int64_t);
-
-void amo_stwat_add (uint32_t *, uint32_t);
-void amo_stwat_xor (uint32_t *, uint32_t);
-void amo_stwat_ior (uint32_t *, uint32_t);
-void amo_stwat_and (uint32_t *, uint32_t);
-void amo_stwat_umax (uint32_t *, uint32_t);
-void amo_stwat_umin (uint32_t *, uint32_t);
-
-void amo_stwat_sadd (int32_t *, int32_t);
-void amo_stwat_smax (int32_t *, int32_t);
-void amo_stwat_smin (int32_t *, int32_t);
-
-void amo_stdat_add (uint64_t *, uint64_t);
-void amo_stdat_xor (uint64_t *, uint64_t);
-void amo_stdat_ior (uint64_t *, uint64_t);
-void amo_stdat_and (uint64_t *, uint64_t);
-void amo_stdat_umax (uint64_t *, uint64_t);
-void amo_stdat_umin (uint64_t *, uint64_t);
-
-void amo_stdat_sadd (int64_t *, int64_t);
-void amo_stdat_smax (int64_t *, int64_t);
-void amo_stdat_smin (int64_t *, int64_t);
-@end smallexample
-
-@node PowerPC Matrix-Multiply Assist Built-in Functions
-@subsection PowerPC Matrix-Multiply Assist Built-in Functions
-ISA 3.1 of the PowerPC added new Matrix-Multiply Assist (MMA) instructions.
-GCC provides support for these instructions through the following built-in
-functions which are enabled with the @code{-mmma} option. The vec_t type
-below is defined to be a normal vector unsigned char type. The uint2, uint4
-and uint8 parameters are 2-bit, 4-bit and 8-bit unsigned integer constants
-respectively. The compiler will verify that they are constants and that
-their values are within range.
-
-The built-in functions supported are:
-
-@smallexample
-void __builtin_mma_xvi4ger8 (__vector_quad *, vec_t, vec_t);
-void __builtin_mma_xvi8ger4 (__vector_quad *, vec_t, vec_t);
-void __builtin_mma_xvi16ger2 (__vector_quad *, vec_t, vec_t);
-void __builtin_mma_xvi16ger2s (__vector_quad *, vec_t, vec_t);
-void __builtin_mma_xvf16ger2 (__vector_quad *, vec_t, vec_t);
-void __builtin_mma_xvbf16ger2 (__vector_quad *, vec_t, vec_t);
-void __builtin_mma_xvf32ger (__vector_quad *, vec_t, vec_t);
-
-void __builtin_mma_xvi4ger8pp (__vector_quad *, vec_t, vec_t);
-void __builtin_mma_xvi8ger4pp (__vector_quad *, vec_t, vec_t);
-void __builtin_mma_xvi8ger4spp(__vector_quad *, vec_t, vec_t);
-void __builtin_mma_xvi16ger2pp (__vector_quad *, vec_t, vec_t);
-void __builtin_mma_xvi16ger2spp (__vector_quad *, vec_t, vec_t);
-void __builtin_mma_xvf16ger2pp (__vector_quad *, vec_t, vec_t);
-void __builtin_mma_xvf16ger2pn (__vector_quad *, vec_t, vec_t);
-void __builtin_mma_xvf16ger2np (__vector_quad *, vec_t, vec_t);
-void __builtin_mma_xvf16ger2nn (__vector_quad *, vec_t, vec_t);
-void __builtin_mma_xvbf16ger2pp (__vector_quad *, vec_t, vec_t);
-void __builtin_mma_xvbf16ger2pn (__vector_quad *, vec_t, vec_t);
-void __builtin_mma_xvbf16ger2np (__vector_quad *, vec_t, vec_t);
-void __builtin_mma_xvbf16ger2nn (__vector_quad *, vec_t, vec_t);
-void __builtin_mma_xvf32gerpp (__vector_quad *, vec_t, vec_t);
-void __builtin_mma_xvf32gerpn (__vector_quad *, vec_t, vec_t);
-void __builtin_mma_xvf32gernp (__vector_quad *, vec_t, vec_t);
-void __builtin_mma_xvf32gernn (__vector_quad *, vec_t, vec_t);
-
-void __builtin_mma_pmxvi4ger8 (__vector_quad *, vec_t, vec_t, uint4, uint4, uint8);
-void __builtin_mma_pmxvi4ger8pp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint8);
-
-void __builtin_mma_pmxvi8ger4 (__vector_quad *, vec_t, vec_t, uint4, uint4, uint4);
-void __builtin_mma_pmxvi8ger4pp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint4);
-void __builtin_mma_pmxvi8ger4spp(__vector_quad *, vec_t, vec_t, uint4, uint4, uint4);
-
-void __builtin_mma_pmxvi16ger2 (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
-void __builtin_mma_pmxvi16ger2s (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
-void __builtin_mma_pmxvf16ger2 (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
-void __builtin_mma_pmxvbf16ger2 (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
-
-void __builtin_mma_pmxvi16ger2pp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
-void __builtin_mma_pmxvi16ger2spp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
-void __builtin_mma_pmxvf16ger2pp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
-void __builtin_mma_pmxvf16ger2pn (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
-void __builtin_mma_pmxvf16ger2np (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
-void __builtin_mma_pmxvf16ger2nn (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
-void __builtin_mma_pmxvbf16ger2pp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
-void __builtin_mma_pmxvbf16ger2pn (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
-void __builtin_mma_pmxvbf16ger2np (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
-void __builtin_mma_pmxvbf16ger2nn (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
-
-void __builtin_mma_pmxvf32ger (__vector_quad *, vec_t, vec_t, uint4, uint4);
-void __builtin_mma_pmxvf32gerpp (__vector_quad *, vec_t, vec_t, uint4, uint4);
-void __builtin_mma_pmxvf32gerpn (__vector_quad *, vec_t, vec_t, uint4, uint4);
-void __builtin_mma_pmxvf32gernp (__vector_quad *, vec_t, vec_t, uint4, uint4);
-void __builtin_mma_pmxvf32gernn (__vector_quad *, vec_t, vec_t, uint4, uint4);
-
-void __builtin_mma_xvf64ger (__vector_quad *, __vector_pair, vec_t);
-void __builtin_mma_xvf64gerpp (__vector_quad *, __vector_pair, vec_t);
-void __builtin_mma_xvf64gerpn (__vector_quad *, __vector_pair, vec_t);
-void __builtin_mma_xvf64gernp (__vector_quad *, __vector_pair, vec_t);
-void __builtin_mma_xvf64gernn (__vector_quad *, __vector_pair, vec_t);
-
-void __builtin_mma_pmxvf64ger (__vector_quad *, __vector_pair, vec_t, uint4, uint2);
-void __builtin_mma_pmxvf64gerpp (__vector_quad *, __vector_pair, vec_t, uint4, uint2);
-void __builtin_mma_pmxvf64gerpn (__vector_quad *, __vector_pair, vec_t, uint4, uint2);
-void __builtin_mma_pmxvf64gernp (__vector_quad *, __vector_pair, vec_t, uint4, uint2);
-void __builtin_mma_pmxvf64gernn (__vector_quad *, __vector_pair, vec_t, uint4, uint2);
-
-void __builtin_mma_xxmtacc (__vector_quad *);
-void __builtin_mma_xxmfacc (__vector_quad *);
-void __builtin_mma_xxsetaccz (__vector_quad *);
-
-void __builtin_mma_build_acc (__vector_quad *, vec_t, vec_t, vec_t, vec_t);
-void __builtin_mma_disassemble_acc (void *, __vector_quad *);
-
-void __builtin_vsx_build_pair (__vector_pair *, vec_t, vec_t);
-void __builtin_vsx_disassemble_pair (void *, __vector_pair *);
-
-vec_t __builtin_vsx_xvcvspbf16 (vec_t);
-vec_t __builtin_vsx_xvcvbf16spn (vec_t);
-
-__vector_pair __builtin_vsx_lxvp (size_t, __vector_pair *);
-void __builtin_vsx_stxvp (__vector_pair, size_t, __vector_pair *);
-@end smallexample
-
-@node PRU Built-in Functions
-@subsection PRU Built-in Functions
-
-GCC provides a couple of special builtin functions to aid in utilizing
-special PRU instructions.
-
-The built-in functions supported are:
-
-@table @code
-@item __delay_cycles (long long @var{cycles})
-This inserts an instruction sequence that takes exactly @var{cycles}
-cycles (between 0 and 0xffffffff) to complete. The inserted sequence
-may use jumps, loops, or no-ops, and does not interfere with any other
-instructions. Note that @var{cycles} must be a compile-time constant
-integer - that is, you must pass a number, not a variable that may be
-optimized to a constant later. The number of cycles delayed by this
-builtin is exact.
-
-@item __halt (void)
-This inserts a HALT instruction to stop processor execution.
-
-@item unsigned int __lmbd (unsigned int @var{wordval}, unsigned int @var{bitval})
-This inserts LMBD instruction to calculate the left-most bit with value
-@var{bitval} in value @var{wordval}. Only the least significant bit
-of @var{bitval} is taken into account.
-@end table
-
-@node RISC-V Built-in Functions
-@subsection RISC-V Built-in Functions
-
-These built-in functions are available for the RISC-V family of
-processors.
-
-@deftypefn {Built-in Function} {void *} __builtin_thread_pointer (void)
-Returns the value that is currently set in the @samp{tp} register.
-@end deftypefn
-
-@node RX Built-in Functions
-@subsection RX Built-in Functions
-GCC supports some of the RX instructions which cannot be expressed in
-the C programming language via the use of built-in functions. The
-following functions are supported:
-
-@deftypefn {Built-in Function} void __builtin_rx_brk (void)
-Generates the @code{brk} machine instruction.
-@end deftypefn
-
-@deftypefn {Built-in Function} void __builtin_rx_clrpsw (int)
-Generates the @code{clrpsw} machine instruction to clear the specified
-bit in the processor status word.
-@end deftypefn
-
-@deftypefn {Built-in Function} void __builtin_rx_int (int)
-Generates the @code{int} machine instruction to generate an interrupt
-with the specified value.
-@end deftypefn
-
-@deftypefn {Built-in Function} void __builtin_rx_machi (int, int)
-Generates the @code{machi} machine instruction to add the result of
-multiplying the top 16 bits of the two arguments into the
-accumulator.
-@end deftypefn
-
-@deftypefn {Built-in Function} void __builtin_rx_maclo (int, int)
-Generates the @code{maclo} machine instruction to add the result of
-multiplying the bottom 16 bits of the two arguments into the
-accumulator.
-@end deftypefn
-
-@deftypefn {Built-in Function} void __builtin_rx_mulhi (int, int)
-Generates the @code{mulhi} machine instruction to place the result of
-multiplying the top 16 bits of the two arguments into the
-accumulator.
-@end deftypefn
-
-@deftypefn {Built-in Function} void __builtin_rx_mullo (int, int)
-Generates the @code{mullo} machine instruction to place the result of
-multiplying the bottom 16 bits of the two arguments into the
-accumulator.
-@end deftypefn
-
-@deftypefn {Built-in Function} int __builtin_rx_mvfachi (void)
-Generates the @code{mvfachi} machine instruction to read the top
-32 bits of the accumulator.
-@end deftypefn
-
-@deftypefn {Built-in Function} int __builtin_rx_mvfacmi (void)
-Generates the @code{mvfacmi} machine instruction to read the middle
-32 bits of the accumulator.
-@end deftypefn
-
-@deftypefn {Built-in Function} int __builtin_rx_mvfc (int)
-Generates the @code{mvfc} machine instruction which reads the control
-register specified in its argument and returns its value.
-@end deftypefn
-
-@deftypefn {Built-in Function} void __builtin_rx_mvtachi (int)
-Generates the @code{mvtachi} machine instruction to set the top
-32 bits of the accumulator.
-@end deftypefn
-
-@deftypefn {Built-in Function} void __builtin_rx_mvtaclo (int)
-Generates the @code{mvtaclo} machine instruction to set the bottom
-32 bits of the accumulator.
-@end deftypefn
-
-@deftypefn {Built-in Function} void __builtin_rx_mvtc (int reg, int val)
-Generates the @code{mvtc} machine instruction which sets control
-register number @code{reg} to @code{val}.
-@end deftypefn
-
-@deftypefn {Built-in Function} void __builtin_rx_mvtipl (int)
-Generates the @code{mvtipl} machine instruction set the interrupt
-priority level.
-@end deftypefn
-
-@deftypefn {Built-in Function} void __builtin_rx_racw (int)
-Generates the @code{racw} machine instruction to round the accumulator
-according to the specified mode.
-@end deftypefn
-
-@deftypefn {Built-in Function} int __builtin_rx_revw (int)
-Generates the @code{revw} machine instruction which swaps the bytes in
-the argument so that bits 0--7 now occupy bits 8--15 and vice versa,
-and also bits 16--23 occupy bits 24--31 and vice versa.
-@end deftypefn
-
-@deftypefn {Built-in Function} void __builtin_rx_rmpa (void)
-Generates the @code{rmpa} machine instruction which initiates a
-repeated multiply and accumulate sequence.
-@end deftypefn
-
-@deftypefn {Built-in Function} void __builtin_rx_round (float)
-Generates the @code{round} machine instruction which returns the
-floating-point argument rounded according to the current rounding mode
-set in the floating-point status word register.
-@end deftypefn
-
-@deftypefn {Built-in Function} int __builtin_rx_sat (int)
-Generates the @code{sat} machine instruction which returns the
-saturated value of the argument.
-@end deftypefn
-
-@deftypefn {Built-in Function} void __builtin_rx_setpsw (int)
-Generates the @code{setpsw} machine instruction to set the specified
-bit in the processor status word.
-@end deftypefn
-
-@deftypefn {Built-in Function} void __builtin_rx_wait (void)
-Generates the @code{wait} machine instruction.
-@end deftypefn
-
-@node S/390 System z Built-in Functions
-@subsection S/390 System z Built-in Functions
-@deftypefn {Built-in Function} int __builtin_tbegin (void*)
-Generates the @code{tbegin} machine instruction starting a
-non-constrained hardware transaction. If the parameter is non-NULL the
-memory area is used to store the transaction diagnostic buffer and
-will be passed as first operand to @code{tbegin}. This buffer can be
-defined using the @code{struct __htm_tdb} C struct defined in
-@code{htmintrin.h} and must reside on a double-word boundary. The
-second tbegin operand is set to @code{0xff0c}. This enables
-save/restore of all GPRs and disables aborts for FPR and AR
-manipulations inside the transaction body. The condition code set by
-the tbegin instruction is returned as integer value. The tbegin
-instruction by definition overwrites the content of all FPRs. The
-compiler will generate code which saves and restores the FPRs. For
-soft-float code it is recommended to used the @code{*_nofloat}
-variant. In order to prevent a TDB from being written it is required
-to pass a constant zero value as parameter. Passing a zero value
-through a variable is not sufficient. Although modifications of
-access registers inside the transaction will not trigger an
-transaction abort it is not supported to actually modify them. Access
-registers do not get saved when entering a transaction. They will have
-undefined state when reaching the abort code.
-@end deftypefn
-
-Macros for the possible return codes of tbegin are defined in the
-@code{htmintrin.h} header file:
-
-@table @code
-@item _HTM_TBEGIN_STARTED
-@code{tbegin} has been executed as part of normal processing. The
-transaction body is supposed to be executed.
-@item _HTM_TBEGIN_INDETERMINATE
-The transaction was aborted due to an indeterminate condition which
-might be persistent.
-@item _HTM_TBEGIN_TRANSIENT
-The transaction aborted due to a transient failure. The transaction
-should be re-executed in that case.
-@item _HTM_TBEGIN_PERSISTENT
-The transaction aborted due to a persistent failure. Re-execution
-under same circumstances will not be productive.
-@end table
-
-@defmac _HTM_FIRST_USER_ABORT_CODE
-The @code{_HTM_FIRST_USER_ABORT_CODE} defined in @code{htmintrin.h}
-specifies the first abort code which can be used for
-@code{__builtin_tabort}. Values below this threshold are reserved for
-machine use.
-@end defmac
-
-@deftp {Data type} {struct __htm_tdb}
-The @code{struct __htm_tdb} defined in @code{htmintrin.h} describes
-the structure of the transaction diagnostic block as specified in the
-Principles of Operation manual chapter 5-91.
-@end deftp
-
-@deftypefn {Built-in Function} int __builtin_tbegin_nofloat (void*)
-Same as @code{__builtin_tbegin} but without FPR saves and restores.
-Using this variant in code making use of FPRs will leave the FPRs in
-undefined state when entering the transaction abort handler code.
-@end deftypefn
-
-@deftypefn {Built-in Function} int __builtin_tbegin_retry (void*, int)
-In addition to @code{__builtin_tbegin} a loop for transient failures
-is generated. If tbegin returns a condition code of 2 the transaction
-will be retried as often as specified in the second argument. The
-perform processor assist instruction is used to tell the CPU about the
-number of fails so far.
-@end deftypefn
-
-@deftypefn {Built-in Function} int __builtin_tbegin_retry_nofloat (void*, int)
-Same as @code{__builtin_tbegin_retry} but without FPR saves and
-restores. Using this variant in code making use of FPRs will leave
-the FPRs in undefined state when entering the transaction abort
-handler code.
-@end deftypefn
-
-@deftypefn {Built-in Function} void __builtin_tbeginc (void)
-Generates the @code{tbeginc} machine instruction starting a constrained
-hardware transaction. The second operand is set to @code{0xff08}.
-@end deftypefn
-
-@deftypefn {Built-in Function} int __builtin_tend (void)
-Generates the @code{tend} machine instruction finishing a transaction
-and making the changes visible to other threads. The condition code
-generated by tend is returned as integer value.
-@end deftypefn
-
-@deftypefn {Built-in Function} void __builtin_tabort (int)
-Generates the @code{tabort} machine instruction with the specified
-abort code. Abort codes from 0 through 255 are reserved and will
-result in an error message.
-@end deftypefn
-
-@deftypefn {Built-in Function} void __builtin_tx_assist (int)
-Generates the @code{ppa rX,rY,1} machine instruction. Where the
-integer parameter is loaded into rX and a value of zero is loaded into
-rY. The integer parameter specifies the number of times the
-transaction repeatedly aborted.
-@end deftypefn
-
-@deftypefn {Built-in Function} int __builtin_tx_nesting_depth (void)
-Generates the @code{etnd} machine instruction. The current nesting
-depth is returned as integer value. For a nesting depth of 0 the code
-is not executed as part of an transaction.
-@end deftypefn
-
-@deftypefn {Built-in Function} void __builtin_non_tx_store (uint64_t *, uint64_t)
-
-Generates the @code{ntstg} machine instruction. The second argument
-is written to the first arguments location. The store operation will
-not be rolled-back in case of an transaction abort.
-@end deftypefn
-
-@node SH Built-in Functions
-@subsection SH Built-in Functions
-The following built-in functions are supported on the SH1, SH2, SH3 and SH4
-families of processors:
-
-@deftypefn {Built-in Function} {void} __builtin_set_thread_pointer (void *@var{ptr})
-Sets the @samp{GBR} register to the specified value @var{ptr}. This is usually
-used by system code that manages threads and execution contexts. The compiler
-normally does not generate code that modifies the contents of @samp{GBR} and
-thus the value is preserved across function calls. Changing the @samp{GBR}
-value in user code must be done with caution, since the compiler might use
-@samp{GBR} in order to access thread local variables.
-
-@end deftypefn
-
-@deftypefn {Built-in Function} {void *} __builtin_thread_pointer (void)
-Returns the value that is currently set in the @samp{GBR} register.
-Memory loads and stores that use the thread pointer as a base address are
-turned into @samp{GBR} based displacement loads and stores, if possible.
-For example:
-@smallexample
-struct my_tcb
-@{
- int a, b, c, d, e;
-@};
-
-int get_tcb_value (void)
-@{
- // Generate @samp{mov.l @@(8,gbr),r0} instruction
- return ((my_tcb*)__builtin_thread_pointer ())->c;
-@}
-
-@end smallexample
-@end deftypefn
-
-@deftypefn {Built-in Function} {unsigned int} __builtin_sh_get_fpscr (void)
-Returns the value that is currently set in the @samp{FPSCR} register.
-@end deftypefn
-
-@deftypefn {Built-in Function} {void} __builtin_sh_set_fpscr (unsigned int @var{val})
-Sets the @samp{FPSCR} register to the specified value @var{val}, while
-preserving the current values of the FR, SZ and PR bits.
-@end deftypefn
-
-@node SPARC VIS Built-in Functions
-@subsection SPARC VIS Built-in Functions
-
-GCC supports SIMD operations on the SPARC using both the generic vector
-extensions (@pxref{Vector Extensions}) as well as built-in functions for
-the SPARC Visual Instruction Set (VIS). When you use the @option{-mvis}
-switch, the VIS extension is exposed as the following built-in functions:
-
-@smallexample
-typedef int v1si __attribute__ ((vector_size (4)));
-typedef int v2si __attribute__ ((vector_size (8)));
-typedef short v4hi __attribute__ ((vector_size (8)));
-typedef short v2hi __attribute__ ((vector_size (4)));
-typedef unsigned char v8qi __attribute__ ((vector_size (8)));
-typedef unsigned char v4qi __attribute__ ((vector_size (4)));
-
-void __builtin_vis_write_gsr (int64_t);
-int64_t __builtin_vis_read_gsr (void);
-
-void * __builtin_vis_alignaddr (void *, long);
-void * __builtin_vis_alignaddrl (void *, long);
-int64_t __builtin_vis_faligndatadi (int64_t, int64_t);
-v2si __builtin_vis_faligndatav2si (v2si, v2si);
-v4hi __builtin_vis_faligndatav4hi (v4si, v4si);
-v8qi __builtin_vis_faligndatav8qi (v8qi, v8qi);
-
-v4hi __builtin_vis_fexpand (v4qi);
-
-v4hi __builtin_vis_fmul8x16 (v4qi, v4hi);
-v4hi __builtin_vis_fmul8x16au (v4qi, v2hi);
-v4hi __builtin_vis_fmul8x16al (v4qi, v2hi);
-v4hi __builtin_vis_fmul8sux16 (v8qi, v4hi);
-v4hi __builtin_vis_fmul8ulx16 (v8qi, v4hi);
-v2si __builtin_vis_fmuld8sux16 (v4qi, v2hi);
-v2si __builtin_vis_fmuld8ulx16 (v4qi, v2hi);
-
-v4qi __builtin_vis_fpack16 (v4hi);
-v8qi __builtin_vis_fpack32 (v2si, v8qi);
-v2hi __builtin_vis_fpackfix (v2si);
-v8qi __builtin_vis_fpmerge (v4qi, v4qi);
-
-int64_t __builtin_vis_pdist (v8qi, v8qi, int64_t);
-
-long __builtin_vis_edge8 (void *, void *);
-long __builtin_vis_edge8l (void *, void *);
-long __builtin_vis_edge16 (void *, void *);
-long __builtin_vis_edge16l (void *, void *);
-long __builtin_vis_edge32 (void *, void *);
-long __builtin_vis_edge32l (void *, void *);
-
-long __builtin_vis_fcmple16 (v4hi, v4hi);
-long __builtin_vis_fcmple32 (v2si, v2si);
-long __builtin_vis_fcmpne16 (v4hi, v4hi);
-long __builtin_vis_fcmpne32 (v2si, v2si);
-long __builtin_vis_fcmpgt16 (v4hi, v4hi);
-long __builtin_vis_fcmpgt32 (v2si, v2si);
-long __builtin_vis_fcmpeq16 (v4hi, v4hi);
-long __builtin_vis_fcmpeq32 (v2si, v2si);
-
-v4hi __builtin_vis_fpadd16 (v4hi, v4hi);
-v2hi __builtin_vis_fpadd16s (v2hi, v2hi);
-v2si __builtin_vis_fpadd32 (v2si, v2si);
-v1si __builtin_vis_fpadd32s (v1si, v1si);
-v4hi __builtin_vis_fpsub16 (v4hi, v4hi);
-v2hi __builtin_vis_fpsub16s (v2hi, v2hi);
-v2si __builtin_vis_fpsub32 (v2si, v2si);
-v1si __builtin_vis_fpsub32s (v1si, v1si);
-
-long __builtin_vis_array8 (long, long);
-long __builtin_vis_array16 (long, long);
-long __builtin_vis_array32 (long, long);
-@end smallexample
-
-When you use the @option{-mvis2} switch, the VIS version 2.0 built-in
-functions also become available:
-
-@smallexample
-long __builtin_vis_bmask (long, long);
-int64_t __builtin_vis_bshuffledi (int64_t, int64_t);
-v2si __builtin_vis_bshufflev2si (v2si, v2si);
-v4hi __builtin_vis_bshufflev2si (v4hi, v4hi);
-v8qi __builtin_vis_bshufflev2si (v8qi, v8qi);
-
-long __builtin_vis_edge8n (void *, void *);
-long __builtin_vis_edge8ln (void *, void *);
-long __builtin_vis_edge16n (void *, void *);
-long __builtin_vis_edge16ln (void *, void *);
-long __builtin_vis_edge32n (void *, void *);
-long __builtin_vis_edge32ln (void *, void *);
-@end smallexample
-
-When you use the @option{-mvis3} switch, the VIS version 3.0 built-in
-functions also become available:
-
-@smallexample
-void __builtin_vis_cmask8 (long);
-void __builtin_vis_cmask16 (long);
-void __builtin_vis_cmask32 (long);
-
-v4hi __builtin_vis_fchksm16 (v4hi, v4hi);
-
-v4hi __builtin_vis_fsll16 (v4hi, v4hi);
-v4hi __builtin_vis_fslas16 (v4hi, v4hi);
-v4hi __builtin_vis_fsrl16 (v4hi, v4hi);
-v4hi __builtin_vis_fsra16 (v4hi, v4hi);
-v2si __builtin_vis_fsll16 (v2si, v2si);
-v2si __builtin_vis_fslas16 (v2si, v2si);
-v2si __builtin_vis_fsrl16 (v2si, v2si);
-v2si __builtin_vis_fsra16 (v2si, v2si);
-
-long __builtin_vis_pdistn (v8qi, v8qi);
-
-v4hi __builtin_vis_fmean16 (v4hi, v4hi);
-
-int64_t __builtin_vis_fpadd64 (int64_t, int64_t);
-int64_t __builtin_vis_fpsub64 (int64_t, int64_t);
-
-v4hi __builtin_vis_fpadds16 (v4hi, v4hi);
-v2hi __builtin_vis_fpadds16s (v2hi, v2hi);
-v4hi __builtin_vis_fpsubs16 (v4hi, v4hi);
-v2hi __builtin_vis_fpsubs16s (v2hi, v2hi);
-v2si __builtin_vis_fpadds32 (v2si, v2si);
-v1si __builtin_vis_fpadds32s (v1si, v1si);
-v2si __builtin_vis_fpsubs32 (v2si, v2si);
-v1si __builtin_vis_fpsubs32s (v1si, v1si);
-
-long __builtin_vis_fucmple8 (v8qi, v8qi);
-long __builtin_vis_fucmpne8 (v8qi, v8qi);
-long __builtin_vis_fucmpgt8 (v8qi, v8qi);
-long __builtin_vis_fucmpeq8 (v8qi, v8qi);
-
-float __builtin_vis_fhadds (float, float);
-double __builtin_vis_fhaddd (double, double);
-float __builtin_vis_fhsubs (float, float);
-double __builtin_vis_fhsubd (double, double);
-float __builtin_vis_fnhadds (float, float);
-double __builtin_vis_fnhaddd (double, double);
-
-int64_t __builtin_vis_umulxhi (int64_t, int64_t);
-int64_t __builtin_vis_xmulx (int64_t, int64_t);
-int64_t __builtin_vis_xmulxhi (int64_t, int64_t);
-@end smallexample
-
-When you use the @option{-mvis4} switch, the VIS version 4.0 built-in
-functions also become available:
-
-@smallexample
-v8qi __builtin_vis_fpadd8 (v8qi, v8qi);
-v8qi __builtin_vis_fpadds8 (v8qi, v8qi);
-v8qi __builtin_vis_fpaddus8 (v8qi, v8qi);
-v4hi __builtin_vis_fpaddus16 (v4hi, v4hi);
-
-v8qi __builtin_vis_fpsub8 (v8qi, v8qi);
-v8qi __builtin_vis_fpsubs8 (v8qi, v8qi);
-v8qi __builtin_vis_fpsubus8 (v8qi, v8qi);
-v4hi __builtin_vis_fpsubus16 (v4hi, v4hi);
-
-long __builtin_vis_fpcmple8 (v8qi, v8qi);
-long __builtin_vis_fpcmpgt8 (v8qi, v8qi);
-long __builtin_vis_fpcmpule16 (v4hi, v4hi);
-long __builtin_vis_fpcmpugt16 (v4hi, v4hi);
-long __builtin_vis_fpcmpule32 (v2si, v2si);
-long __builtin_vis_fpcmpugt32 (v2si, v2si);
-
-v8qi __builtin_vis_fpmax8 (v8qi, v8qi);
-v4hi __builtin_vis_fpmax16 (v4hi, v4hi);
-v2si __builtin_vis_fpmax32 (v2si, v2si);
-
-v8qi __builtin_vis_fpmaxu8 (v8qi, v8qi);
-v4hi __builtin_vis_fpmaxu16 (v4hi, v4hi);
-v2si __builtin_vis_fpmaxu32 (v2si, v2si);
-
-v8qi __builtin_vis_fpmin8 (v8qi, v8qi);
-v4hi __builtin_vis_fpmin16 (v4hi, v4hi);
-v2si __builtin_vis_fpmin32 (v2si, v2si);
-
-v8qi __builtin_vis_fpminu8 (v8qi, v8qi);
-v4hi __builtin_vis_fpminu16 (v4hi, v4hi);
-v2si __builtin_vis_fpminu32 (v2si, v2si);
-@end smallexample
-
-When you use the @option{-mvis4b} switch, the VIS version 4.0B
-built-in functions also become available:
-
-@smallexample
-v8qi __builtin_vis_dictunpack8 (double, int);
-v4hi __builtin_vis_dictunpack16 (double, int);
-v2si __builtin_vis_dictunpack32 (double, int);
-
-long __builtin_vis_fpcmple8shl (v8qi, v8qi, int);
-long __builtin_vis_fpcmpgt8shl (v8qi, v8qi, int);
-long __builtin_vis_fpcmpeq8shl (v8qi, v8qi, int);
-long __builtin_vis_fpcmpne8shl (v8qi, v8qi, int);
-
-long __builtin_vis_fpcmple16shl (v4hi, v4hi, int);
-long __builtin_vis_fpcmpgt16shl (v4hi, v4hi, int);
-long __builtin_vis_fpcmpeq16shl (v4hi, v4hi, int);
-long __builtin_vis_fpcmpne16shl (v4hi, v4hi, int);
-
-long __builtin_vis_fpcmple32shl (v2si, v2si, int);
-long __builtin_vis_fpcmpgt32shl (v2si, v2si, int);
-long __builtin_vis_fpcmpeq32shl (v2si, v2si, int);
-long __builtin_vis_fpcmpne32shl (v2si, v2si, int);
-
-long __builtin_vis_fpcmpule8shl (v8qi, v8qi, int);
-long __builtin_vis_fpcmpugt8shl (v8qi, v8qi, int);
-long __builtin_vis_fpcmpule16shl (v4hi, v4hi, int);
-long __builtin_vis_fpcmpugt16shl (v4hi, v4hi, int);
-long __builtin_vis_fpcmpule32shl (v2si, v2si, int);
-long __builtin_vis_fpcmpugt32shl (v2si, v2si, int);
-
-long __builtin_vis_fpcmpde8shl (v8qi, v8qi, int);
-long __builtin_vis_fpcmpde16shl (v4hi, v4hi, int);
-long __builtin_vis_fpcmpde32shl (v2si, v2si, int);
-
-long __builtin_vis_fpcmpur8shl (v8qi, v8qi, int);
-long __builtin_vis_fpcmpur16shl (v4hi, v4hi, int);
-long __builtin_vis_fpcmpur32shl (v2si, v2si, int);
-@end smallexample
-
-@node TI C6X Built-in Functions
-@subsection TI C6X Built-in Functions
-
-GCC provides intrinsics to access certain instructions of the TI C6X
-processors. These intrinsics, listed below, are available after
-inclusion of the @code{c6x_intrinsics.h} header file. They map directly
-to C6X instructions.
-
-@smallexample
-int _sadd (int, int);
-int _ssub (int, int);
-int _sadd2 (int, int);
-int _ssub2 (int, int);
-long long _mpy2 (int, int);
-long long _smpy2 (int, int);
-int _add4 (int, int);
-int _sub4 (int, int);
-int _saddu4 (int, int);
-
-int _smpy (int, int);
-int _smpyh (int, int);
-int _smpyhl (int, int);
-int _smpylh (int, int);
-
-int _sshl (int, int);
-int _subc (int, int);
-
-int _avg2 (int, int);
-int _avgu4 (int, int);
-
-int _clrr (int, int);
-int _extr (int, int);
-int _extru (int, int);
-int _abs (int);
-int _abs2 (int);
-@end smallexample
-
-@node x86 Built-in Functions
-@subsection x86 Built-in Functions
-
-These built-in functions are available for the x86-32 and x86-64 family
-of computers, depending on the command-line switches used.
-
-If you specify command-line switches such as @option{-msse},
-the compiler could use the extended instruction sets even if the built-ins
-are not used explicitly in the program. For this reason, applications
-that perform run-time CPU detection must compile separate files for each
-supported architecture, using the appropriate flags. In particular,
-the file containing the CPU detection code should be compiled without
-these options.
-
-The following machine modes are available for use with MMX built-in functions
-(@pxref{Vector Extensions}): @code{V2SI} for a vector of two 32-bit integers,
-@code{V4HI} for a vector of four 16-bit integers, and @code{V8QI} for a
-vector of eight 8-bit integers. Some of the built-in functions operate on
-MMX registers as a whole 64-bit entity, these use @code{V1DI} as their mode.
-
-If 3DNow!@: extensions are enabled, @code{V2SF} is used as a mode for a vector
-of two 32-bit floating-point values.
-
-If SSE extensions are enabled, @code{V4SF} is used for a vector of four 32-bit
-floating-point values. Some instructions use a vector of four 32-bit
-integers, these use @code{V4SI}. Finally, some instructions operate on an
-entire vector register, interpreting it as a 128-bit integer, these use mode
-@code{TI}.
-
-The x86-32 and x86-64 family of processors use additional built-in
-functions for efficient use of @code{TF} (@code{__float128}) 128-bit
-floating point and @code{TC} 128-bit complex floating-point values.
-
-The following floating-point built-in functions are always available. All
-of them implement the function that is part of the name.
-
-@smallexample
-__float128 __builtin_fabsq (__float128)
-__float128 __builtin_copysignq (__float128, __float128)
-@end smallexample
-
-The following built-in functions are always available.
-
-@table @code
-@item __float128 __builtin_infq (void)
-Similar to @code{__builtin_inf}, except the return type is @code{__float128}.
-@findex __builtin_infq
-
-@item __float128 __builtin_huge_valq (void)
-Similar to @code{__builtin_huge_val}, except the return type is @code{__float128}.
-@findex __builtin_huge_valq
-
-@item __float128 __builtin_nanq (void)
-Similar to @code{__builtin_nan}, except the return type is @code{__float128}.
-@findex __builtin_nanq
-
-@item __float128 __builtin_nansq (void)
-Similar to @code{__builtin_nans}, except the return type is @code{__float128}.
-@findex __builtin_nansq
-@end table
-
-The following built-in function is always available.
-
-@table @code
-@item void __builtin_ia32_pause (void)
-Generates the @code{pause} machine instruction with a compiler memory
-barrier.
-@end table
-
-The following built-in functions are always available and can be used to
-check the target platform type.
-
-@deftypefn {Built-in Function} void __builtin_cpu_init (void)
-This function runs the CPU detection code to check the type of CPU and the
-features supported. This built-in function needs to be invoked along with the built-in functions
-to check CPU type and features, @code{__builtin_cpu_is} and
-@code{__builtin_cpu_supports}, only when used in a function that is
-executed before any constructors are called. The CPU detection code is
-automatically executed in a very high priority constructor.
-
-For example, this function has to be used in @code{ifunc} resolvers that
-check for CPU type using the built-in functions @code{__builtin_cpu_is}
-and @code{__builtin_cpu_supports}, or in constructors on targets that
-don't support constructor priority.
-@smallexample
-
-static void (*resolve_memcpy (void)) (void)
-@{
- // ifunc resolvers fire before constructors, explicitly call the init
- // function.
- __builtin_cpu_init ();
- if (__builtin_cpu_supports ("ssse3"))
- return ssse3_memcpy; // super fast memcpy with ssse3 instructions.
- else
- return default_memcpy;
-@}
-
-void *memcpy (void *, const void *, size_t)
- __attribute__ ((ifunc ("resolve_memcpy")));
-@end smallexample
-
-@end deftypefn
-
-@deftypefn {Built-in Function} int __builtin_cpu_is (const char *@var{cpuname})
-This function returns a positive integer if the run-time CPU
-is of type @var{cpuname}
-and returns @code{0} otherwise. The following CPU names can be detected:
-
-@table @samp
-@item amd
-AMD CPU.
-
-@item intel
-Intel CPU.
-
-@item atom
-Intel Atom CPU.
-
-@item slm
-Intel Silvermont CPU.
-
-@item core2
-Intel Core 2 CPU.
-
-@item corei7
-Intel Core i7 CPU.
-
-@item nehalem
-Intel Core i7 Nehalem CPU.
-
-@item westmere
-Intel Core i7 Westmere CPU.
-
-@item sandybridge
-Intel Core i7 Sandy Bridge CPU.
-
-@item ivybridge
-Intel Core i7 Ivy Bridge CPU.
-
-@item haswell
-Intel Core i7 Haswell CPU.
-
-@item broadwell
-Intel Core i7 Broadwell CPU.
-
-@item skylake
-Intel Core i7 Skylake CPU.
-
-@item skylake-avx512
-Intel Core i7 Skylake AVX512 CPU.
-
-@item cannonlake
-Intel Core i7 Cannon Lake CPU.
-
-@item icelake-client
-Intel Core i7 Ice Lake Client CPU.
-
-@item icelake-server
-Intel Core i7 Ice Lake Server CPU.
-
-@item cascadelake
-Intel Core i7 Cascadelake CPU.
-
-@item tigerlake
-Intel Core i7 Tigerlake CPU.
-
-@item cooperlake
-Intel Core i7 Cooperlake CPU.
-
-@item sapphirerapids
-Intel Core i7 sapphirerapids CPU.
-
-@item alderlake
-Intel Core i7 Alderlake CPU.
-
-@item rocketlake
-Intel Core i7 Rocketlake CPU.
-
-@item graniterapids
-Intel Core i7 graniterapids CPU.
-
-@item bonnell
-Intel Atom Bonnell CPU.
-
-@item silvermont
-Intel Atom Silvermont CPU.
-
-@item goldmont
-Intel Atom Goldmont CPU.
-
-@item goldmont-plus
-Intel Atom Goldmont Plus CPU.
-
-@item tremont
-Intel Atom Tremont CPU.
-
-@item sierraforest
-Intel Atom Sierra Forest CPU.
-
-@item grandridge
-Intel Atom Grand Ridge CPU.
-
-@item knl
-Intel Knights Landing CPU.
-
-@item knm
-Intel Knights Mill CPU.
-
-@item lujiazui
-ZHAOXIN lujiazui CPU.
-
-@item amdfam10h
-AMD Family 10h CPU.
-
-@item barcelona
-AMD Family 10h Barcelona CPU.
-
-@item shanghai
-AMD Family 10h Shanghai CPU.
-
-@item istanbul
-AMD Family 10h Istanbul CPU.
-
-@item btver1
-AMD Family 14h CPU.
-
-@item amdfam15h
-AMD Family 15h CPU.
-
-@item bdver1
-AMD Family 15h Bulldozer version 1.
-
-@item bdver2
-AMD Family 15h Bulldozer version 2.
-
-@item bdver3
-AMD Family 15h Bulldozer version 3.
-
-@item bdver4
-AMD Family 15h Bulldozer version 4.
-
-@item btver2
-AMD Family 16h CPU.
-
-@item amdfam17h
-AMD Family 17h CPU.
-
-@item znver1
-AMD Family 17h Zen version 1.
-
-@item znver2
-AMD Family 17h Zen version 2.
-
-@item amdfam19h
-AMD Family 19h CPU.
-
-@item znver3
-AMD Family 19h Zen version 3.
-
-@item znver4
-AMD Family 19h Zen version 4.
-
-@item x86-64
-Baseline x86-64 microarchitecture level (as defined in x86-64 psABI).
-
-@item x86-64-v2
-x86-64-v2 microarchitecture level.
-
-@item x86-64-v3
-x86-64-v3 microarchitecture level.
-
-@item x86-64-v4
-x86-64-v4 microarchitecture level.
-@end table
-
-Here is an example:
-@smallexample
-if (__builtin_cpu_is ("corei7"))
- @{
- do_corei7 (); // Core i7 specific implementation.
- @}
-else
- @{
- do_generic (); // Generic implementation.
- @}
-@end smallexample
-@end deftypefn
-
-@deftypefn {Built-in Function} int __builtin_cpu_supports (const char *@var{feature})
-This function returns a positive integer if the run-time CPU
-supports @var{feature}
-and returns @code{0} otherwise. The following features can be detected:
-
-@table @samp
-@item cmov
-CMOV instruction.
-@item mmx
-MMX instructions.
-@item popcnt
-POPCNT instruction.
-@item sse
-SSE instructions.
-@item sse2
-SSE2 instructions.
-@item sse3
-SSE3 instructions.
-@item ssse3
-SSSE3 instructions.
-@item sse4.1
-SSE4.1 instructions.
-@item sse4.2
-SSE4.2 instructions.
-@item avx
-AVX instructions.
-@item avx2
-AVX2 instructions.
-@item sse4a
-SSE4A instructions.
-@item fma4
-FMA4 instructions.
-@item xop
-XOP instructions.
-@item fma
-FMA instructions.
-@item avx512f
-AVX512F instructions.
-@item bmi
-BMI instructions.
-@item bmi2
-BMI2 instructions.
-@item aes
-AES instructions.
-@item pclmul
-PCLMUL instructions.
-@item avx512vl
-AVX512VL instructions.
-@item avx512bw
-AVX512BW instructions.
-@item avx512dq
-AVX512DQ instructions.
-@item avx512cd
-AVX512CD instructions.
-@item avx512er
-AVX512ER instructions.
-@item avx512pf
-AVX512PF instructions.
-@item avx512vbmi
-AVX512VBMI instructions.
-@item avx512ifma
-AVX512IFMA instructions.
-@item avx5124vnniw
-AVX5124VNNIW instructions.
-@item avx5124fmaps
-AVX5124FMAPS instructions.
-@item avx512vpopcntdq
-AVX512VPOPCNTDQ instructions.
-@item avx512vbmi2
-AVX512VBMI2 instructions.
-@item gfni
-GFNI instructions.
-@item vpclmulqdq
-VPCLMULQDQ instructions.
-@item avx512vnni
-AVX512VNNI instructions.
-@item avx512bitalg
-AVX512BITALG instructions.
-@end table
-
-Here is an example:
-@smallexample
-if (__builtin_cpu_supports ("popcnt"))
- @{
- asm("popcnt %1,%0" : "=r"(count) : "rm"(n) : "cc");
- @}
-else
- @{
- count = generic_countbits (n); //generic implementation.
- @}
-@end smallexample
-@end deftypefn
-
-The following built-in functions are made available by @option{-mmmx}.
-All of them generate the machine instruction that is part of the name.
-
-@smallexample
-v8qi __builtin_ia32_paddb (v8qi, v8qi);
-v4hi __builtin_ia32_paddw (v4hi, v4hi);
-v2si __builtin_ia32_paddd (v2si, v2si);
-v8qi __builtin_ia32_psubb (v8qi, v8qi);
-v4hi __builtin_ia32_psubw (v4hi, v4hi);
-v2si __builtin_ia32_psubd (v2si, v2si);
-v8qi __builtin_ia32_paddsb (v8qi, v8qi);
-v4hi __builtin_ia32_paddsw (v4hi, v4hi);
-v8qi __builtin_ia32_psubsb (v8qi, v8qi);
-v4hi __builtin_ia32_psubsw (v4hi, v4hi);
-v8qi __builtin_ia32_paddusb (v8qi, v8qi);
-v4hi __builtin_ia32_paddusw (v4hi, v4hi);
-v8qi __builtin_ia32_psubusb (v8qi, v8qi);
-v4hi __builtin_ia32_psubusw (v4hi, v4hi);
-v4hi __builtin_ia32_pmullw (v4hi, v4hi);
-v4hi __builtin_ia32_pmulhw (v4hi, v4hi);
-di __builtin_ia32_pand (di, di);
-di __builtin_ia32_pandn (di,di);
-di __builtin_ia32_por (di, di);
-di __builtin_ia32_pxor (di, di);
-v8qi __builtin_ia32_pcmpeqb (v8qi, v8qi);
-v4hi __builtin_ia32_pcmpeqw (v4hi, v4hi);
-v2si __builtin_ia32_pcmpeqd (v2si, v2si);
-v8qi __builtin_ia32_pcmpgtb (v8qi, v8qi);
-v4hi __builtin_ia32_pcmpgtw (v4hi, v4hi);
-v2si __builtin_ia32_pcmpgtd (v2si, v2si);
-v8qi __builtin_ia32_punpckhbw (v8qi, v8qi);
-v4hi __builtin_ia32_punpckhwd (v4hi, v4hi);
-v2si __builtin_ia32_punpckhdq (v2si, v2si);
-v8qi __builtin_ia32_punpcklbw (v8qi, v8qi);
-v4hi __builtin_ia32_punpcklwd (v4hi, v4hi);
-v2si __builtin_ia32_punpckldq (v2si, v2si);
-v8qi __builtin_ia32_packsswb (v4hi, v4hi);
-v4hi __builtin_ia32_packssdw (v2si, v2si);
-v8qi __builtin_ia32_packuswb (v4hi, v4hi);
-
-v4hi __builtin_ia32_psllw (v4hi, v4hi);
-v2si __builtin_ia32_pslld (v2si, v2si);
-v1di __builtin_ia32_psllq (v1di, v1di);
-v4hi __builtin_ia32_psrlw (v4hi, v4hi);
-v2si __builtin_ia32_psrld (v2si, v2si);
-v1di __builtin_ia32_psrlq (v1di, v1di);
-v4hi __builtin_ia32_psraw (v4hi, v4hi);
-v2si __builtin_ia32_psrad (v2si, v2si);
-v4hi __builtin_ia32_psllwi (v4hi, int);
-v2si __builtin_ia32_pslldi (v2si, int);
-v1di __builtin_ia32_psllqi (v1di, int);
-v4hi __builtin_ia32_psrlwi (v4hi, int);
-v2si __builtin_ia32_psrldi (v2si, int);
-v1di __builtin_ia32_psrlqi (v1di, int);
-v4hi __builtin_ia32_psrawi (v4hi, int);
-v2si __builtin_ia32_psradi (v2si, int);
-@end smallexample
-
-The following built-in functions are made available either with
-@option{-msse}, or with @option{-m3dnowa}. All of them generate
-the machine instruction that is part of the name.
-
-@smallexample
-v4hi __builtin_ia32_pmulhuw (v4hi, v4hi);
-v8qi __builtin_ia32_pavgb (v8qi, v8qi);
-v4hi __builtin_ia32_pavgw (v4hi, v4hi);
-v1di __builtin_ia32_psadbw (v8qi, v8qi);
-v8qi __builtin_ia32_pmaxub (v8qi, v8qi);
-v4hi __builtin_ia32_pmaxsw (v4hi, v4hi);
-v8qi __builtin_ia32_pminub (v8qi, v8qi);
-v4hi __builtin_ia32_pminsw (v4hi, v4hi);
-int __builtin_ia32_pmovmskb (v8qi);
-void __builtin_ia32_maskmovq (v8qi, v8qi, char *);
-void __builtin_ia32_movntq (di *, di);
-void __builtin_ia32_sfence (void);
-@end smallexample
-
-The following built-in functions are available when @option{-msse} is used.
-All of them generate the machine instruction that is part of the name.
-
-@smallexample
-int __builtin_ia32_comieq (v4sf, v4sf);
-int __builtin_ia32_comineq (v4sf, v4sf);
-int __builtin_ia32_comilt (v4sf, v4sf);
-int __builtin_ia32_comile (v4sf, v4sf);
-int __builtin_ia32_comigt (v4sf, v4sf);
-int __builtin_ia32_comige (v4sf, v4sf);
-int __builtin_ia32_ucomieq (v4sf, v4sf);
-int __builtin_ia32_ucomineq (v4sf, v4sf);
-int __builtin_ia32_ucomilt (v4sf, v4sf);
-int __builtin_ia32_ucomile (v4sf, v4sf);
-int __builtin_ia32_ucomigt (v4sf, v4sf);
-int __builtin_ia32_ucomige (v4sf, v4sf);
-v4sf __builtin_ia32_addps (v4sf, v4sf);
-v4sf __builtin_ia32_subps (v4sf, v4sf);
-v4sf __builtin_ia32_mulps (v4sf, v4sf);
-v4sf __builtin_ia32_divps (v4sf, v4sf);
-v4sf __builtin_ia32_addss (v4sf, v4sf);
-v4sf __builtin_ia32_subss (v4sf, v4sf);
-v4sf __builtin_ia32_mulss (v4sf, v4sf);
-v4sf __builtin_ia32_divss (v4sf, v4sf);
-v4sf __builtin_ia32_cmpeqps (v4sf, v4sf);
-v4sf __builtin_ia32_cmpltps (v4sf, v4sf);
-v4sf __builtin_ia32_cmpleps (v4sf, v4sf);
-v4sf __builtin_ia32_cmpgtps (v4sf, v4sf);
-v4sf __builtin_ia32_cmpgeps (v4sf, v4sf);
-v4sf __builtin_ia32_cmpunordps (v4sf, v4sf);
-v4sf __builtin_ia32_cmpneqps (v4sf, v4sf);
-v4sf __builtin_ia32_cmpnltps (v4sf, v4sf);
-v4sf __builtin_ia32_cmpnleps (v4sf, v4sf);
-v4sf __builtin_ia32_cmpngtps (v4sf, v4sf);
-v4sf __builtin_ia32_cmpngeps (v4sf, v4sf);
-v4sf __builtin_ia32_cmpordps (v4sf, v4sf);
-v4sf __builtin_ia32_cmpeqss (v4sf, v4sf);
-v4sf __builtin_ia32_cmpltss (v4sf, v4sf);
-v4sf __builtin_ia32_cmpless (v4sf, v4sf);
-v4sf __builtin_ia32_cmpunordss (v4sf, v4sf);
-v4sf __builtin_ia32_cmpneqss (v4sf, v4sf);
-v4sf __builtin_ia32_cmpnltss (v4sf, v4sf);
-v4sf __builtin_ia32_cmpnless (v4sf, v4sf);
-v4sf __builtin_ia32_cmpordss (v4sf, v4sf);
-v4sf __builtin_ia32_maxps (v4sf, v4sf);
-v4sf __builtin_ia32_maxss (v4sf, v4sf);
-v4sf __builtin_ia32_minps (v4sf, v4sf);
-v4sf __builtin_ia32_minss (v4sf, v4sf);
-v4sf __builtin_ia32_andps (v4sf, v4sf);
-v4sf __builtin_ia32_andnps (v4sf, v4sf);
-v4sf __builtin_ia32_orps (v4sf, v4sf);
-v4sf __builtin_ia32_xorps (v4sf, v4sf);
-v4sf __builtin_ia32_movss (v4sf, v4sf);
-v4sf __builtin_ia32_movhlps (v4sf, v4sf);
-v4sf __builtin_ia32_movlhps (v4sf, v4sf);
-v4sf __builtin_ia32_unpckhps (v4sf, v4sf);
-v4sf __builtin_ia32_unpcklps (v4sf, v4sf);
-v4sf __builtin_ia32_cvtpi2ps (v4sf, v2si);
-v4sf __builtin_ia32_cvtsi2ss (v4sf, int);
-v2si __builtin_ia32_cvtps2pi (v4sf);
-int __builtin_ia32_cvtss2si (v4sf);
-v2si __builtin_ia32_cvttps2pi (v4sf);
-int __builtin_ia32_cvttss2si (v4sf);
-v4sf __builtin_ia32_rcpps (v4sf);
-v4sf __builtin_ia32_rsqrtps (v4sf);
-v4sf __builtin_ia32_sqrtps (v4sf);
-v4sf __builtin_ia32_rcpss (v4sf);
-v4sf __builtin_ia32_rsqrtss (v4sf);
-v4sf __builtin_ia32_sqrtss (v4sf);
-v4sf __builtin_ia32_shufps (v4sf, v4sf, int);
-void __builtin_ia32_movntps (float *, v4sf);
-int __builtin_ia32_movmskps (v4sf);
-@end smallexample
-
-The following built-in functions are available when @option{-msse} is used.
-
-@table @code
-@item v4sf __builtin_ia32_loadups (float *)
-Generates the @code{movups} machine instruction as a load from memory.
-@item void __builtin_ia32_storeups (float *, v4sf)
-Generates the @code{movups} machine instruction as a store to memory.
-@item v4sf __builtin_ia32_loadss (float *)
-Generates the @code{movss} machine instruction as a load from memory.
-@item v4sf __builtin_ia32_loadhps (v4sf, const v2sf *)
-Generates the @code{movhps} machine instruction as a load from memory.
-@item v4sf __builtin_ia32_loadlps (v4sf, const v2sf *)
-Generates the @code{movlps} machine instruction as a load from memory
-@item void __builtin_ia32_storehps (v2sf *, v4sf)
-Generates the @code{movhps} machine instruction as a store to memory.
-@item void __builtin_ia32_storelps (v2sf *, v4sf)
-Generates the @code{movlps} machine instruction as a store to memory.
-@end table
-
-The following built-in functions are available when @option{-msse2} is used.
-All of them generate the machine instruction that is part of the name.
-
-@smallexample
-int __builtin_ia32_comisdeq (v2df, v2df);
-int __builtin_ia32_comisdlt (v2df, v2df);
-int __builtin_ia32_comisdle (v2df, v2df);
-int __builtin_ia32_comisdgt (v2df, v2df);
-int __builtin_ia32_comisdge (v2df, v2df);
-int __builtin_ia32_comisdneq (v2df, v2df);
-int __builtin_ia32_ucomisdeq (v2df, v2df);
-int __builtin_ia32_ucomisdlt (v2df, v2df);
-int __builtin_ia32_ucomisdle (v2df, v2df);
-int __builtin_ia32_ucomisdgt (v2df, v2df);
-int __builtin_ia32_ucomisdge (v2df, v2df);
-int __builtin_ia32_ucomisdneq (v2df, v2df);
-v2df __builtin_ia32_cmpeqpd (v2df, v2df);
-v2df __builtin_ia32_cmpltpd (v2df, v2df);
-v2df __builtin_ia32_cmplepd (v2df, v2df);
-v2df __builtin_ia32_cmpgtpd (v2df, v2df);
-v2df __builtin_ia32_cmpgepd (v2df, v2df);
-v2df __builtin_ia32_cmpunordpd (v2df, v2df);
-v2df __builtin_ia32_cmpneqpd (v2df, v2df);
-v2df __builtin_ia32_cmpnltpd (v2df, v2df);
-v2df __builtin_ia32_cmpnlepd (v2df, v2df);
-v2df __builtin_ia32_cmpngtpd (v2df, v2df);
-v2df __builtin_ia32_cmpngepd (v2df, v2df);
-v2df __builtin_ia32_cmpordpd (v2df, v2df);
-v2df __builtin_ia32_cmpeqsd (v2df, v2df);
-v2df __builtin_ia32_cmpltsd (v2df, v2df);
-v2df __builtin_ia32_cmplesd (v2df, v2df);
-v2df __builtin_ia32_cmpunordsd (v2df, v2df);
-v2df __builtin_ia32_cmpneqsd (v2df, v2df);
-v2df __builtin_ia32_cmpnltsd (v2df, v2df);
-v2df __builtin_ia32_cmpnlesd (v2df, v2df);
-v2df __builtin_ia32_cmpordsd (v2df, v2df);
-v2di __builtin_ia32_paddq (v2di, v2di);
-v2di __builtin_ia32_psubq (v2di, v2di);
-v2df __builtin_ia32_addpd (v2df, v2df);
-v2df __builtin_ia32_subpd (v2df, v2df);
-v2df __builtin_ia32_mulpd (v2df, v2df);
-v2df __builtin_ia32_divpd (v2df, v2df);
-v2df __builtin_ia32_addsd (v2df, v2df);
-v2df __builtin_ia32_subsd (v2df, v2df);
-v2df __builtin_ia32_mulsd (v2df, v2df);
-v2df __builtin_ia32_divsd (v2df, v2df);
-v2df __builtin_ia32_minpd (v2df, v2df);
-v2df __builtin_ia32_maxpd (v2df, v2df);
-v2df __builtin_ia32_minsd (v2df, v2df);
-v2df __builtin_ia32_maxsd (v2df, v2df);
-v2df __builtin_ia32_andpd (v2df, v2df);
-v2df __builtin_ia32_andnpd (v2df, v2df);
-v2df __builtin_ia32_orpd (v2df, v2df);
-v2df __builtin_ia32_xorpd (v2df, v2df);
-v2df __builtin_ia32_movsd (v2df, v2df);
-v2df __builtin_ia32_unpckhpd (v2df, v2df);
-v2df __builtin_ia32_unpcklpd (v2df, v2df);
-v16qi __builtin_ia32_paddb128 (v16qi, v16qi);
-v8hi __builtin_ia32_paddw128 (v8hi, v8hi);
-v4si __builtin_ia32_paddd128 (v4si, v4si);
-v2di __builtin_ia32_paddq128 (v2di, v2di);
-v16qi __builtin_ia32_psubb128 (v16qi, v16qi);
-v8hi __builtin_ia32_psubw128 (v8hi, v8hi);
-v4si __builtin_ia32_psubd128 (v4si, v4si);
-v2di __builtin_ia32_psubq128 (v2di, v2di);
-v8hi __builtin_ia32_pmullw128 (v8hi, v8hi);
-v8hi __builtin_ia32_pmulhw128 (v8hi, v8hi);
-v2di __builtin_ia32_pand128 (v2di, v2di);
-v2di __builtin_ia32_pandn128 (v2di, v2di);
-v2di __builtin_ia32_por128 (v2di, v2di);
-v2di __builtin_ia32_pxor128 (v2di, v2di);
-v16qi __builtin_ia32_pavgb128 (v16qi, v16qi);
-v8hi __builtin_ia32_pavgw128 (v8hi, v8hi);
-v16qi __builtin_ia32_pcmpeqb128 (v16qi, v16qi);
-v8hi __builtin_ia32_pcmpeqw128 (v8hi, v8hi);
-v4si __builtin_ia32_pcmpeqd128 (v4si, v4si);
-v16qi __builtin_ia32_pcmpgtb128 (v16qi, v16qi);
-v8hi __builtin_ia32_pcmpgtw128 (v8hi, v8hi);
-v4si __builtin_ia32_pcmpgtd128 (v4si, v4si);
-v16qi __builtin_ia32_pmaxub128 (v16qi, v16qi);
-v8hi __builtin_ia32_pmaxsw128 (v8hi, v8hi);
-v16qi __builtin_ia32_pminub128 (v16qi, v16qi);
-v8hi __builtin_ia32_pminsw128 (v8hi, v8hi);
-v16qi __builtin_ia32_punpckhbw128 (v16qi, v16qi);
-v8hi __builtin_ia32_punpckhwd128 (v8hi, v8hi);
-v4si __builtin_ia32_punpckhdq128 (v4si, v4si);
-v2di __builtin_ia32_punpckhqdq128 (v2di, v2di);
-v16qi __builtin_ia32_punpcklbw128 (v16qi, v16qi);
-v8hi __builtin_ia32_punpcklwd128 (v8hi, v8hi);
-v4si __builtin_ia32_punpckldq128 (v4si, v4si);
-v2di __builtin_ia32_punpcklqdq128 (v2di, v2di);
-v16qi __builtin_ia32_packsswb128 (v8hi, v8hi);
-v8hi __builtin_ia32_packssdw128 (v4si, v4si);
-v16qi __builtin_ia32_packuswb128 (v8hi, v8hi);
-v8hi __builtin_ia32_pmulhuw128 (v8hi, v8hi);
-void __builtin_ia32_maskmovdqu (v16qi, v16qi);
-v2df __builtin_ia32_loadupd (double *);
-void __builtin_ia32_storeupd (double *, v2df);
-v2df __builtin_ia32_loadhpd (v2df, double const *);
-v2df __builtin_ia32_loadlpd (v2df, double const *);
-int __builtin_ia32_movmskpd (v2df);
-int __builtin_ia32_pmovmskb128 (v16qi);
-void __builtin_ia32_movnti (int *, int);
-void __builtin_ia32_movnti64 (long long int *, long long int);
-void __builtin_ia32_movntpd (double *, v2df);
-void __builtin_ia32_movntdq (v2df *, v2df);
-v4si __builtin_ia32_pshufd (v4si, int);
-v8hi __builtin_ia32_pshuflw (v8hi, int);
-v8hi __builtin_ia32_pshufhw (v8hi, int);
-v2di __builtin_ia32_psadbw128 (v16qi, v16qi);
-v2df __builtin_ia32_sqrtpd (v2df);
-v2df __builtin_ia32_sqrtsd (v2df);
-v2df __builtin_ia32_shufpd (v2df, v2df, int);
-v2df __builtin_ia32_cvtdq2pd (v4si);
-v4sf __builtin_ia32_cvtdq2ps (v4si);
-v4si __builtin_ia32_cvtpd2dq (v2df);
-v2si __builtin_ia32_cvtpd2pi (v2df);
-v4sf __builtin_ia32_cvtpd2ps (v2df);
-v4si __builtin_ia32_cvttpd2dq (v2df);
-v2si __builtin_ia32_cvttpd2pi (v2df);
-v2df __builtin_ia32_cvtpi2pd (v2si);
-int __builtin_ia32_cvtsd2si (v2df);
-int __builtin_ia32_cvttsd2si (v2df);
-long long __builtin_ia32_cvtsd2si64 (v2df);
-long long __builtin_ia32_cvttsd2si64 (v2df);
-v4si __builtin_ia32_cvtps2dq (v4sf);
-v2df __builtin_ia32_cvtps2pd (v4sf);
-v4si __builtin_ia32_cvttps2dq (v4sf);
-v2df __builtin_ia32_cvtsi2sd (v2df, int);
-v2df __builtin_ia32_cvtsi642sd (v2df, long long);
-v4sf __builtin_ia32_cvtsd2ss (v4sf, v2df);
-v2df __builtin_ia32_cvtss2sd (v2df, v4sf);
-void __builtin_ia32_clflush (const void *);
-void __builtin_ia32_lfence (void);
-void __builtin_ia32_mfence (void);
-v16qi __builtin_ia32_loaddqu (const char *);
-void __builtin_ia32_storedqu (char *, v16qi);
-v1di __builtin_ia32_pmuludq (v2si, v2si);
-v2di __builtin_ia32_pmuludq128 (v4si, v4si);
-v8hi __builtin_ia32_psllw128 (v8hi, v8hi);
-v4si __builtin_ia32_pslld128 (v4si, v4si);
-v2di __builtin_ia32_psllq128 (v2di, v2di);
-v8hi __builtin_ia32_psrlw128 (v8hi, v8hi);
-v4si __builtin_ia32_psrld128 (v4si, v4si);
-v2di __builtin_ia32_psrlq128 (v2di, v2di);
-v8hi __builtin_ia32_psraw128 (v8hi, v8hi);
-v4si __builtin_ia32_psrad128 (v4si, v4si);
-v2di __builtin_ia32_pslldqi128 (v2di, int);
-v8hi __builtin_ia32_psllwi128 (v8hi, int);
-v4si __builtin_ia32_pslldi128 (v4si, int);
-v2di __builtin_ia32_psllqi128 (v2di, int);
-v2di __builtin_ia32_psrldqi128 (v2di, int);
-v8hi __builtin_ia32_psrlwi128 (v8hi, int);
-v4si __builtin_ia32_psrldi128 (v4si, int);
-v2di __builtin_ia32_psrlqi128 (v2di, int);
-v8hi __builtin_ia32_psrawi128 (v8hi, int);
-v4si __builtin_ia32_psradi128 (v4si, int);
-v4si __builtin_ia32_pmaddwd128 (v8hi, v8hi);
-v2di __builtin_ia32_movq128 (v2di);
-@end smallexample
-
-The following built-in functions are available when @option{-msse3} is used.
-All of them generate the machine instruction that is part of the name.
-
-@smallexample
-v2df __builtin_ia32_addsubpd (v2df, v2df);
-v4sf __builtin_ia32_addsubps (v4sf, v4sf);
-v2df __builtin_ia32_haddpd (v2df, v2df);
-v4sf __builtin_ia32_haddps (v4sf, v4sf);
-v2df __builtin_ia32_hsubpd (v2df, v2df);
-v4sf __builtin_ia32_hsubps (v4sf, v4sf);
-v16qi __builtin_ia32_lddqu (char const *);
-void __builtin_ia32_monitor (void *, unsigned int, unsigned int);
-v4sf __builtin_ia32_movshdup (v4sf);
-v4sf __builtin_ia32_movsldup (v4sf);
-void __builtin_ia32_mwait (unsigned int, unsigned int);
-@end smallexample
-
-The following built-in functions are available when @option{-mssse3} is used.
-All of them generate the machine instruction that is part of the name.
-
-@smallexample
-v2si __builtin_ia32_phaddd (v2si, v2si);
-v4hi __builtin_ia32_phaddw (v4hi, v4hi);
-v4hi __builtin_ia32_phaddsw (v4hi, v4hi);
-v2si __builtin_ia32_phsubd (v2si, v2si);
-v4hi __builtin_ia32_phsubw (v4hi, v4hi);
-v4hi __builtin_ia32_phsubsw (v4hi, v4hi);
-v4hi __builtin_ia32_pmaddubsw (v8qi, v8qi);
-v4hi __builtin_ia32_pmulhrsw (v4hi, v4hi);
-v8qi __builtin_ia32_pshufb (v8qi, v8qi);
-v8qi __builtin_ia32_psignb (v8qi, v8qi);
-v2si __builtin_ia32_psignd (v2si, v2si);
-v4hi __builtin_ia32_psignw (v4hi, v4hi);
-v1di __builtin_ia32_palignr (v1di, v1di, int);
-v8qi __builtin_ia32_pabsb (v8qi);
-v2si __builtin_ia32_pabsd (v2si);
-v4hi __builtin_ia32_pabsw (v4hi);
-@end smallexample
-
-The following built-in functions are available when @option{-mssse3} is used.
-All of them generate the machine instruction that is part of the name.
-
-@smallexample
-v4si __builtin_ia32_phaddd128 (v4si, v4si);
-v8hi __builtin_ia32_phaddw128 (v8hi, v8hi);
-v8hi __builtin_ia32_phaddsw128 (v8hi, v8hi);
-v4si __builtin_ia32_phsubd128 (v4si, v4si);
-v8hi __builtin_ia32_phsubw128 (v8hi, v8hi);
-v8hi __builtin_ia32_phsubsw128 (v8hi, v8hi);
-v8hi __builtin_ia32_pmaddubsw128 (v16qi, v16qi);
-v8hi __builtin_ia32_pmulhrsw128 (v8hi, v8hi);
-v16qi __builtin_ia32_pshufb128 (v16qi, v16qi);
-v16qi __builtin_ia32_psignb128 (v16qi, v16qi);
-v4si __builtin_ia32_psignd128 (v4si, v4si);
-v8hi __builtin_ia32_psignw128 (v8hi, v8hi);
-v2di __builtin_ia32_palignr128 (v2di, v2di, int);
-v16qi __builtin_ia32_pabsb128 (v16qi);
-v4si __builtin_ia32_pabsd128 (v4si);
-v8hi __builtin_ia32_pabsw128 (v8hi);
-@end smallexample
-
-The following built-in functions are available when @option{-msse4.1} is
-used. All of them generate the machine instruction that is part of the
-name.
-
-@smallexample
-v2df __builtin_ia32_blendpd (v2df, v2df, const int);
-v4sf __builtin_ia32_blendps (v4sf, v4sf, const int);
-v2df __builtin_ia32_blendvpd (v2df, v2df, v2df);
-v4sf __builtin_ia32_blendvps (v4sf, v4sf, v4sf);
-v2df __builtin_ia32_dppd (v2df, v2df, const int);
-v4sf __builtin_ia32_dpps (v4sf, v4sf, const int);
-v4sf __builtin_ia32_insertps128 (v4sf, v4sf, const int);
-v2di __builtin_ia32_movntdqa (v2di *);
-v16qi __builtin_ia32_mpsadbw128 (v16qi, v16qi, const int);
-v8hi __builtin_ia32_packusdw128 (v4si, v4si);
-v16qi __builtin_ia32_pblendvb128 (v16qi, v16qi, v16qi);
-v8hi __builtin_ia32_pblendw128 (v8hi, v8hi, const int);
-v2di __builtin_ia32_pcmpeqq (v2di, v2di);
-v8hi __builtin_ia32_phminposuw128 (v8hi);
-v16qi __builtin_ia32_pmaxsb128 (v16qi, v16qi);
-v4si __builtin_ia32_pmaxsd128 (v4si, v4si);
-v4si __builtin_ia32_pmaxud128 (v4si, v4si);
-v8hi __builtin_ia32_pmaxuw128 (v8hi, v8hi);
-v16qi __builtin_ia32_pminsb128 (v16qi, v16qi);
-v4si __builtin_ia32_pminsd128 (v4si, v4si);
-v4si __builtin_ia32_pminud128 (v4si, v4si);
-v8hi __builtin_ia32_pminuw128 (v8hi, v8hi);
-v4si __builtin_ia32_pmovsxbd128 (v16qi);
-v2di __builtin_ia32_pmovsxbq128 (v16qi);
-v8hi __builtin_ia32_pmovsxbw128 (v16qi);
-v2di __builtin_ia32_pmovsxdq128 (v4si);
-v4si __builtin_ia32_pmovsxwd128 (v8hi);
-v2di __builtin_ia32_pmovsxwq128 (v8hi);
-v4si __builtin_ia32_pmovzxbd128 (v16qi);
-v2di __builtin_ia32_pmovzxbq128 (v16qi);
-v8hi __builtin_ia32_pmovzxbw128 (v16qi);
-v2di __builtin_ia32_pmovzxdq128 (v4si);
-v4si __builtin_ia32_pmovzxwd128 (v8hi);
-v2di __builtin_ia32_pmovzxwq128 (v8hi);
-v2di __builtin_ia32_pmuldq128 (v4si, v4si);
-v4si __builtin_ia32_pmulld128 (v4si, v4si);
-int __builtin_ia32_ptestc128 (v2di, v2di);
-int __builtin_ia32_ptestnzc128 (v2di, v2di);
-int __builtin_ia32_ptestz128 (v2di, v2di);
-v2df __builtin_ia32_roundpd (v2df, const int);
-v4sf __builtin_ia32_roundps (v4sf, const int);
-v2df __builtin_ia32_roundsd (v2df, v2df, const int);
-v4sf __builtin_ia32_roundss (v4sf, v4sf, const int);
-@end smallexample
-
-The following built-in functions are available when @option{-msse4.1} is
-used.
-
-@table @code
-@item v4sf __builtin_ia32_vec_set_v4sf (v4sf, float, const int)
-Generates the @code{insertps} machine instruction.
-@item int __builtin_ia32_vec_ext_v16qi (v16qi, const int)
-Generates the @code{pextrb} machine instruction.
-@item v16qi __builtin_ia32_vec_set_v16qi (v16qi, int, const int)
-Generates the @code{pinsrb} machine instruction.
-@item v4si __builtin_ia32_vec_set_v4si (v4si, int, const int)
-Generates the @code{pinsrd} machine instruction.
-@item v2di __builtin_ia32_vec_set_v2di (v2di, long long, const int)
-Generates the @code{pinsrq} machine instruction in 64bit mode.
-@end table
-
-The following built-in functions are changed to generate new SSE4.1
-instructions when @option{-msse4.1} is used.
-
-@table @code
-@item float __builtin_ia32_vec_ext_v4sf (v4sf, const int)
-Generates the @code{extractps} machine instruction.
-@item int __builtin_ia32_vec_ext_v4si (v4si, const int)
-Generates the @code{pextrd} machine instruction.
-@item long long __builtin_ia32_vec_ext_v2di (v2di, const int)
-Generates the @code{pextrq} machine instruction in 64bit mode.
-@end table
-
-The following built-in functions are available when @option{-msse4.2} is
-used. All of them generate the machine instruction that is part of the
-name.
-
-@smallexample
-v16qi __builtin_ia32_pcmpestrm128 (v16qi, int, v16qi, int, const int);
-int __builtin_ia32_pcmpestri128 (v16qi, int, v16qi, int, const int);
-int __builtin_ia32_pcmpestria128 (v16qi, int, v16qi, int, const int);
-int __builtin_ia32_pcmpestric128 (v16qi, int, v16qi, int, const int);
-int __builtin_ia32_pcmpestrio128 (v16qi, int, v16qi, int, const int);
-int __builtin_ia32_pcmpestris128 (v16qi, int, v16qi, int, const int);
-int __builtin_ia32_pcmpestriz128 (v16qi, int, v16qi, int, const int);
-v16qi __builtin_ia32_pcmpistrm128 (v16qi, v16qi, const int);
-int __builtin_ia32_pcmpistri128 (v16qi, v16qi, const int);
-int __builtin_ia32_pcmpistria128 (v16qi, v16qi, const int);
-int __builtin_ia32_pcmpistric128 (v16qi, v16qi, const int);
-int __builtin_ia32_pcmpistrio128 (v16qi, v16qi, const int);
-int __builtin_ia32_pcmpistris128 (v16qi, v16qi, const int);
-int __builtin_ia32_pcmpistriz128 (v16qi, v16qi, const int);
-v2di __builtin_ia32_pcmpgtq (v2di, v2di);
-@end smallexample
-
-The following built-in functions are available when @option{-msse4.2} is
-used.
-
-@table @code
-@item unsigned int __builtin_ia32_crc32qi (unsigned int, unsigned char)
-Generates the @code{crc32b} machine instruction.
-@item unsigned int __builtin_ia32_crc32hi (unsigned int, unsigned short)
-Generates the @code{crc32w} machine instruction.
-@item unsigned int __builtin_ia32_crc32si (unsigned int, unsigned int)
-Generates the @code{crc32l} machine instruction.
-@item unsigned long long __builtin_ia32_crc32di (unsigned long long, unsigned long long)
-Generates the @code{crc32q} machine instruction.
-@end table
-
-The following built-in functions are changed to generate new SSE4.2
-instructions when @option{-msse4.2} is used.
-
-@table @code
-@item int __builtin_popcount (unsigned int)
-Generates the @code{popcntl} machine instruction.
-@item int __builtin_popcountl (unsigned long)
-Generates the @code{popcntl} or @code{popcntq} machine instruction,
-depending on the size of @code{unsigned long}.
-@item int __builtin_popcountll (unsigned long long)
-Generates the @code{popcntq} machine instruction.
-@end table
-
-The following built-in functions are available when @option{-mavx} is
-used. All of them generate the machine instruction that is part of the
-name.
-
-@smallexample
-v4df __builtin_ia32_addpd256 (v4df,v4df);
-v8sf __builtin_ia32_addps256 (v8sf,v8sf);
-v4df __builtin_ia32_addsubpd256 (v4df,v4df);
-v8sf __builtin_ia32_addsubps256 (v8sf,v8sf);
-v4df __builtin_ia32_andnpd256 (v4df,v4df);
-v8sf __builtin_ia32_andnps256 (v8sf,v8sf);
-v4df __builtin_ia32_andpd256 (v4df,v4df);
-v8sf __builtin_ia32_andps256 (v8sf,v8sf);
-v4df __builtin_ia32_blendpd256 (v4df,v4df,int);
-v8sf __builtin_ia32_blendps256 (v8sf,v8sf,int);
-v4df __builtin_ia32_blendvpd256 (v4df,v4df,v4df);
-v8sf __builtin_ia32_blendvps256 (v8sf,v8sf,v8sf);
-v2df __builtin_ia32_cmppd (v2df,v2df,int);
-v4df __builtin_ia32_cmppd256 (v4df,v4df,int);
-v4sf __builtin_ia32_cmpps (v4sf,v4sf,int);
-v8sf __builtin_ia32_cmpps256 (v8sf,v8sf,int);
-v2df __builtin_ia32_cmpsd (v2df,v2df,int);
-v4sf __builtin_ia32_cmpss (v4sf,v4sf,int);
-v4df __builtin_ia32_cvtdq2pd256 (v4si);
-v8sf __builtin_ia32_cvtdq2ps256 (v8si);
-v4si __builtin_ia32_cvtpd2dq256 (v4df);
-v4sf __builtin_ia32_cvtpd2ps256 (v4df);
-v8si __builtin_ia32_cvtps2dq256 (v8sf);
-v4df __builtin_ia32_cvtps2pd256 (v4sf);
-v4si __builtin_ia32_cvttpd2dq256 (v4df);
-v8si __builtin_ia32_cvttps2dq256 (v8sf);
-v4df __builtin_ia32_divpd256 (v4df,v4df);
-v8sf __builtin_ia32_divps256 (v8sf,v8sf);
-v8sf __builtin_ia32_dpps256 (v8sf,v8sf,int);
-v4df __builtin_ia32_haddpd256 (v4df,v4df);
-v8sf __builtin_ia32_haddps256 (v8sf,v8sf);
-v4df __builtin_ia32_hsubpd256 (v4df,v4df);
-v8sf __builtin_ia32_hsubps256 (v8sf,v8sf);
-v32qi __builtin_ia32_lddqu256 (pcchar);
-v32qi __builtin_ia32_loaddqu256 (pcchar);
-v4df __builtin_ia32_loadupd256 (pcdouble);
-v8sf __builtin_ia32_loadups256 (pcfloat);
-v2df __builtin_ia32_maskloadpd (pcv2df,v2df);
-v4df __builtin_ia32_maskloadpd256 (pcv4df,v4df);
-v4sf __builtin_ia32_maskloadps (pcv4sf,v4sf);
-v8sf __builtin_ia32_maskloadps256 (pcv8sf,v8sf);
-void __builtin_ia32_maskstorepd (pv2df,v2df,v2df);
-void __builtin_ia32_maskstorepd256 (pv4df,v4df,v4df);
-void __builtin_ia32_maskstoreps (pv4sf,v4sf,v4sf);
-void __builtin_ia32_maskstoreps256 (pv8sf,v8sf,v8sf);
-v4df __builtin_ia32_maxpd256 (v4df,v4df);
-v8sf __builtin_ia32_maxps256 (v8sf,v8sf);
-v4df __builtin_ia32_minpd256 (v4df,v4df);
-v8sf __builtin_ia32_minps256 (v8sf,v8sf);
-v4df __builtin_ia32_movddup256 (v4df);
-int __builtin_ia32_movmskpd256 (v4df);
-int __builtin_ia32_movmskps256 (v8sf);
-v8sf __builtin_ia32_movshdup256 (v8sf);
-v8sf __builtin_ia32_movsldup256 (v8sf);
-v4df __builtin_ia32_mulpd256 (v4df,v4df);
-v8sf __builtin_ia32_mulps256 (v8sf,v8sf);
-v4df __builtin_ia32_orpd256 (v4df,v4df);
-v8sf __builtin_ia32_orps256 (v8sf,v8sf);
-v2df __builtin_ia32_pd_pd256 (v4df);
-v4df __builtin_ia32_pd256_pd (v2df);
-v4sf __builtin_ia32_ps_ps256 (v8sf);
-v8sf __builtin_ia32_ps256_ps (v4sf);
-int __builtin_ia32_ptestc256 (v4di,v4di,ptest);
-int __builtin_ia32_ptestnzc256 (v4di,v4di,ptest);
-int __builtin_ia32_ptestz256 (v4di,v4di,ptest);
-v8sf __builtin_ia32_rcpps256 (v8sf);
-v4df __builtin_ia32_roundpd256 (v4df,int);
-v8sf __builtin_ia32_roundps256 (v8sf,int);
-v8sf __builtin_ia32_rsqrtps_nr256 (v8sf);
-v8sf __builtin_ia32_rsqrtps256 (v8sf);
-v4df __builtin_ia32_shufpd256 (v4df,v4df,int);
-v8sf __builtin_ia32_shufps256 (v8sf,v8sf,int);
-v4si __builtin_ia32_si_si256 (v8si);
-v8si __builtin_ia32_si256_si (v4si);
-v4df __builtin_ia32_sqrtpd256 (v4df);
-v8sf __builtin_ia32_sqrtps_nr256 (v8sf);
-v8sf __builtin_ia32_sqrtps256 (v8sf);
-void __builtin_ia32_storedqu256 (pchar,v32qi);
-void __builtin_ia32_storeupd256 (pdouble,v4df);
-void __builtin_ia32_storeups256 (pfloat,v8sf);
-v4df __builtin_ia32_subpd256 (v4df,v4df);
-v8sf __builtin_ia32_subps256 (v8sf,v8sf);
-v4df __builtin_ia32_unpckhpd256 (v4df,v4df);
-v8sf __builtin_ia32_unpckhps256 (v8sf,v8sf);
-v4df __builtin_ia32_unpcklpd256 (v4df,v4df);
-v8sf __builtin_ia32_unpcklps256 (v8sf,v8sf);
-v4df __builtin_ia32_vbroadcastf128_pd256 (pcv2df);
-v8sf __builtin_ia32_vbroadcastf128_ps256 (pcv4sf);
-v4df __builtin_ia32_vbroadcastsd256 (pcdouble);
-v4sf __builtin_ia32_vbroadcastss (pcfloat);
-v8sf __builtin_ia32_vbroadcastss256 (pcfloat);
-v2df __builtin_ia32_vextractf128_pd256 (v4df,int);
-v4sf __builtin_ia32_vextractf128_ps256 (v8sf,int);
-v4si __builtin_ia32_vextractf128_si256 (v8si,int);
-v4df __builtin_ia32_vinsertf128_pd256 (v4df,v2df,int);
-v8sf __builtin_ia32_vinsertf128_ps256 (v8sf,v4sf,int);
-v8si __builtin_ia32_vinsertf128_si256 (v8si,v4si,int);
-v4df __builtin_ia32_vperm2f128_pd256 (v4df,v4df,int);
-v8sf __builtin_ia32_vperm2f128_ps256 (v8sf,v8sf,int);
-v8si __builtin_ia32_vperm2f128_si256 (v8si,v8si,int);
-v2df __builtin_ia32_vpermil2pd (v2df,v2df,v2di,int);
-v4df __builtin_ia32_vpermil2pd256 (v4df,v4df,v4di,int);
-v4sf __builtin_ia32_vpermil2ps (v4sf,v4sf,v4si,int);
-v8sf __builtin_ia32_vpermil2ps256 (v8sf,v8sf,v8si,int);
-v2df __builtin_ia32_vpermilpd (v2df,int);
-v4df __builtin_ia32_vpermilpd256 (v4df,int);
-v4sf __builtin_ia32_vpermilps (v4sf,int);
-v8sf __builtin_ia32_vpermilps256 (v8sf,int);
-v2df __builtin_ia32_vpermilvarpd (v2df,v2di);
-v4df __builtin_ia32_vpermilvarpd256 (v4df,v4di);
-v4sf __builtin_ia32_vpermilvarps (v4sf,v4si);
-v8sf __builtin_ia32_vpermilvarps256 (v8sf,v8si);
-int __builtin_ia32_vtestcpd (v2df,v2df,ptest);
-int __builtin_ia32_vtestcpd256 (v4df,v4df,ptest);
-int __builtin_ia32_vtestcps (v4sf,v4sf,ptest);
-int __builtin_ia32_vtestcps256 (v8sf,v8sf,ptest);
-int __builtin_ia32_vtestnzcpd (v2df,v2df,ptest);
-int __builtin_ia32_vtestnzcpd256 (v4df,v4df,ptest);
-int __builtin_ia32_vtestnzcps (v4sf,v4sf,ptest);
-int __builtin_ia32_vtestnzcps256 (v8sf,v8sf,ptest);
-int __builtin_ia32_vtestzpd (v2df,v2df,ptest);
-int __builtin_ia32_vtestzpd256 (v4df,v4df,ptest);
-int __builtin_ia32_vtestzps (v4sf,v4sf,ptest);
-int __builtin_ia32_vtestzps256 (v8sf,v8sf,ptest);
-void __builtin_ia32_vzeroall (void);
-void __builtin_ia32_vzeroupper (void);
-v4df __builtin_ia32_xorpd256 (v4df,v4df);
-v8sf __builtin_ia32_xorps256 (v8sf,v8sf);
-@end smallexample
-
-The following built-in functions are available when @option{-mavx2} is
-used. All of them generate the machine instruction that is part of the
-name.
-
-@smallexample
-v32qi __builtin_ia32_mpsadbw256 (v32qi,v32qi,int);
-v32qi __builtin_ia32_pabsb256 (v32qi);
-v16hi __builtin_ia32_pabsw256 (v16hi);
-v8si __builtin_ia32_pabsd256 (v8si);
-v16hi __builtin_ia32_packssdw256 (v8si,v8si);
-v32qi __builtin_ia32_packsswb256 (v16hi,v16hi);
-v16hi __builtin_ia32_packusdw256 (v8si,v8si);
-v32qi __builtin_ia32_packuswb256 (v16hi,v16hi);
-v32qi __builtin_ia32_paddb256 (v32qi,v32qi);
-v16hi __builtin_ia32_paddw256 (v16hi,v16hi);
-v8si __builtin_ia32_paddd256 (v8si,v8si);
-v4di __builtin_ia32_paddq256 (v4di,v4di);
-v32qi __builtin_ia32_paddsb256 (v32qi,v32qi);
-v16hi __builtin_ia32_paddsw256 (v16hi,v16hi);
-v32qi __builtin_ia32_paddusb256 (v32qi,v32qi);
-v16hi __builtin_ia32_paddusw256 (v16hi,v16hi);
-v4di __builtin_ia32_palignr256 (v4di,v4di,int);
-v4di __builtin_ia32_andsi256 (v4di,v4di);
-v4di __builtin_ia32_andnotsi256 (v4di,v4di);
-v32qi __builtin_ia32_pavgb256 (v32qi,v32qi);
-v16hi __builtin_ia32_pavgw256 (v16hi,v16hi);
-v32qi __builtin_ia32_pblendvb256 (v32qi,v32qi,v32qi);
-v16hi __builtin_ia32_pblendw256 (v16hi,v16hi,int);
-v32qi __builtin_ia32_pcmpeqb256 (v32qi,v32qi);
-v16hi __builtin_ia32_pcmpeqw256 (v16hi,v16hi);
-v8si __builtin_ia32_pcmpeqd256 (c8si,v8si);
-v4di __builtin_ia32_pcmpeqq256 (v4di,v4di);
-v32qi __builtin_ia32_pcmpgtb256 (v32qi,v32qi);
-v16hi __builtin_ia32_pcmpgtw256 (16hi,v16hi);
-v8si __builtin_ia32_pcmpgtd256 (v8si,v8si);
-v4di __builtin_ia32_pcmpgtq256 (v4di,v4di);
-v16hi __builtin_ia32_phaddw256 (v16hi,v16hi);
-v8si __builtin_ia32_phaddd256 (v8si,v8si);
-v16hi __builtin_ia32_phaddsw256 (v16hi,v16hi);
-v16hi __builtin_ia32_phsubw256 (v16hi,v16hi);
-v8si __builtin_ia32_phsubd256 (v8si,v8si);
-v16hi __builtin_ia32_phsubsw256 (v16hi,v16hi);
-v32qi __builtin_ia32_pmaddubsw256 (v32qi,v32qi);
-v16hi __builtin_ia32_pmaddwd256 (v16hi,v16hi);
-v32qi __builtin_ia32_pmaxsb256 (v32qi,v32qi);
-v16hi __builtin_ia32_pmaxsw256 (v16hi,v16hi);
-v8si __builtin_ia32_pmaxsd256 (v8si,v8si);
-v32qi __builtin_ia32_pmaxub256 (v32qi,v32qi);
-v16hi __builtin_ia32_pmaxuw256 (v16hi,v16hi);
-v8si __builtin_ia32_pmaxud256 (v8si,v8si);
-v32qi __builtin_ia32_pminsb256 (v32qi,v32qi);
-v16hi __builtin_ia32_pminsw256 (v16hi,v16hi);
-v8si __builtin_ia32_pminsd256 (v8si,v8si);
-v32qi __builtin_ia32_pminub256 (v32qi,v32qi);
-v16hi __builtin_ia32_pminuw256 (v16hi,v16hi);
-v8si __builtin_ia32_pminud256 (v8si,v8si);
-int __builtin_ia32_pmovmskb256 (v32qi);
-v16hi __builtin_ia32_pmovsxbw256 (v16qi);
-v8si __builtin_ia32_pmovsxbd256 (v16qi);
-v4di __builtin_ia32_pmovsxbq256 (v16qi);
-v8si __builtin_ia32_pmovsxwd256 (v8hi);
-v4di __builtin_ia32_pmovsxwq256 (v8hi);
-v4di __builtin_ia32_pmovsxdq256 (v4si);
-v16hi __builtin_ia32_pmovzxbw256 (v16qi);
-v8si __builtin_ia32_pmovzxbd256 (v16qi);
-v4di __builtin_ia32_pmovzxbq256 (v16qi);
-v8si __builtin_ia32_pmovzxwd256 (v8hi);
-v4di __builtin_ia32_pmovzxwq256 (v8hi);
-v4di __builtin_ia32_pmovzxdq256 (v4si);
-v4di __builtin_ia32_pmuldq256 (v8si,v8si);
-v16hi __builtin_ia32_pmulhrsw256 (v16hi, v16hi);
-v16hi __builtin_ia32_pmulhuw256 (v16hi,v16hi);
-v16hi __builtin_ia32_pmulhw256 (v16hi,v16hi);
-v16hi __builtin_ia32_pmullw256 (v16hi,v16hi);
-v8si __builtin_ia32_pmulld256 (v8si,v8si);
-v4di __builtin_ia32_pmuludq256 (v8si,v8si);
-v4di __builtin_ia32_por256 (v4di,v4di);
-v16hi __builtin_ia32_psadbw256 (v32qi,v32qi);
-v32qi __builtin_ia32_pshufb256 (v32qi,v32qi);
-v8si __builtin_ia32_pshufd256 (v8si,int);
-v16hi __builtin_ia32_pshufhw256 (v16hi,int);
-v16hi __builtin_ia32_pshuflw256 (v16hi,int);
-v32qi __builtin_ia32_psignb256 (v32qi,v32qi);
-v16hi __builtin_ia32_psignw256 (v16hi,v16hi);
-v8si __builtin_ia32_psignd256 (v8si,v8si);
-v4di __builtin_ia32_pslldqi256 (v4di,int);
-v16hi __builtin_ia32_psllwi256 (16hi,int);
-v16hi __builtin_ia32_psllw256(v16hi,v8hi);
-v8si __builtin_ia32_pslldi256 (v8si,int);
-v8si __builtin_ia32_pslld256(v8si,v4si);
-v4di __builtin_ia32_psllqi256 (v4di,int);
-v4di __builtin_ia32_psllq256(v4di,v2di);
-v16hi __builtin_ia32_psrawi256 (v16hi,int);
-v16hi __builtin_ia32_psraw256 (v16hi,v8hi);
-v8si __builtin_ia32_psradi256 (v8si,int);
-v8si __builtin_ia32_psrad256 (v8si,v4si);
-v4di __builtin_ia32_psrldqi256 (v4di, int);
-v16hi __builtin_ia32_psrlwi256 (v16hi,int);
-v16hi __builtin_ia32_psrlw256 (v16hi,v8hi);
-v8si __builtin_ia32_psrldi256 (v8si,int);
-v8si __builtin_ia32_psrld256 (v8si,v4si);
-v4di __builtin_ia32_psrlqi256 (v4di,int);
-v4di __builtin_ia32_psrlq256(v4di,v2di);
-v32qi __builtin_ia32_psubb256 (v32qi,v32qi);
-v32hi __builtin_ia32_psubw256 (v16hi,v16hi);
-v8si __builtin_ia32_psubd256 (v8si,v8si);
-v4di __builtin_ia32_psubq256 (v4di,v4di);
-v32qi __builtin_ia32_psubsb256 (v32qi,v32qi);
-v16hi __builtin_ia32_psubsw256 (v16hi,v16hi);
-v32qi __builtin_ia32_psubusb256 (v32qi,v32qi);
-v16hi __builtin_ia32_psubusw256 (v16hi,v16hi);
-v32qi __builtin_ia32_punpckhbw256 (v32qi,v32qi);
-v16hi __builtin_ia32_punpckhwd256 (v16hi,v16hi);
-v8si __builtin_ia32_punpckhdq256 (v8si,v8si);
-v4di __builtin_ia32_punpckhqdq256 (v4di,v4di);
-v32qi __builtin_ia32_punpcklbw256 (v32qi,v32qi);
-v16hi __builtin_ia32_punpcklwd256 (v16hi,v16hi);
-v8si __builtin_ia32_punpckldq256 (v8si,v8si);
-v4di __builtin_ia32_punpcklqdq256 (v4di,v4di);
-v4di __builtin_ia32_pxor256 (v4di,v4di);
-v4di __builtin_ia32_movntdqa256 (pv4di);
-v4sf __builtin_ia32_vbroadcastss_ps (v4sf);
-v8sf __builtin_ia32_vbroadcastss_ps256 (v4sf);
-v4df __builtin_ia32_vbroadcastsd_pd256 (v2df);
-v4di __builtin_ia32_vbroadcastsi256 (v2di);
-v4si __builtin_ia32_pblendd128 (v4si,v4si);
-v8si __builtin_ia32_pblendd256 (v8si,v8si);
-v32qi __builtin_ia32_pbroadcastb256 (v16qi);
-v16hi __builtin_ia32_pbroadcastw256 (v8hi);
-v8si __builtin_ia32_pbroadcastd256 (v4si);
-v4di __builtin_ia32_pbroadcastq256 (v2di);
-v16qi __builtin_ia32_pbroadcastb128 (v16qi);
-v8hi __builtin_ia32_pbroadcastw128 (v8hi);
-v4si __builtin_ia32_pbroadcastd128 (v4si);
-v2di __builtin_ia32_pbroadcastq128 (v2di);
-v8si __builtin_ia32_permvarsi256 (v8si,v8si);
-v4df __builtin_ia32_permdf256 (v4df,int);
-v8sf __builtin_ia32_permvarsf256 (v8sf,v8sf);
-v4di __builtin_ia32_permdi256 (v4di,int);
-v4di __builtin_ia32_permti256 (v4di,v4di,int);
-v4di __builtin_ia32_extract128i256 (v4di,int);
-v4di __builtin_ia32_insert128i256 (v4di,v2di,int);
-v8si __builtin_ia32_maskloadd256 (pcv8si,v8si);
-v4di __builtin_ia32_maskloadq256 (pcv4di,v4di);
-v4si __builtin_ia32_maskloadd (pcv4si,v4si);
-v2di __builtin_ia32_maskloadq (pcv2di,v2di);
-void __builtin_ia32_maskstored256 (pv8si,v8si,v8si);
-void __builtin_ia32_maskstoreq256 (pv4di,v4di,v4di);
-void __builtin_ia32_maskstored (pv4si,v4si,v4si);
-void __builtin_ia32_maskstoreq (pv2di,v2di,v2di);
-v8si __builtin_ia32_psllv8si (v8si,v8si);
-v4si __builtin_ia32_psllv4si (v4si,v4si);
-v4di __builtin_ia32_psllv4di (v4di,v4di);
-v2di __builtin_ia32_psllv2di (v2di,v2di);
-v8si __builtin_ia32_psrav8si (v8si,v8si);
-v4si __builtin_ia32_psrav4si (v4si,v4si);
-v8si __builtin_ia32_psrlv8si (v8si,v8si);
-v4si __builtin_ia32_psrlv4si (v4si,v4si);
-v4di __builtin_ia32_psrlv4di (v4di,v4di);
-v2di __builtin_ia32_psrlv2di (v2di,v2di);
-v2df __builtin_ia32_gathersiv2df (v2df, pcdouble,v4si,v2df,int);
-v4df __builtin_ia32_gathersiv4df (v4df, pcdouble,v4si,v4df,int);
-v2df __builtin_ia32_gatherdiv2df (v2df, pcdouble,v2di,v2df,int);
-v4df __builtin_ia32_gatherdiv4df (v4df, pcdouble,v4di,v4df,int);
-v4sf __builtin_ia32_gathersiv4sf (v4sf, pcfloat,v4si,v4sf,int);
-v8sf __builtin_ia32_gathersiv8sf (v8sf, pcfloat,v8si,v8sf,int);
-v4sf __builtin_ia32_gatherdiv4sf (v4sf, pcfloat,v2di,v4sf,int);
-v4sf __builtin_ia32_gatherdiv4sf256 (v4sf, pcfloat,v4di,v4sf,int);
-v2di __builtin_ia32_gathersiv2di (v2di, pcint64,v4si,v2di,int);
-v4di __builtin_ia32_gathersiv4di (v4di, pcint64,v4si,v4di,int);
-v2di __builtin_ia32_gatherdiv2di (v2di, pcint64,v2di,v2di,int);
-v4di __builtin_ia32_gatherdiv4di (v4di, pcint64,v4di,v4di,int);
-v4si __builtin_ia32_gathersiv4si (v4si, pcint,v4si,v4si,int);
-v8si __builtin_ia32_gathersiv8si (v8si, pcint,v8si,v8si,int);
-v4si __builtin_ia32_gatherdiv4si (v4si, pcint,v2di,v4si,int);
-v4si __builtin_ia32_gatherdiv4si256 (v4si, pcint,v4di,v4si,int);
-@end smallexample
-
-The following built-in functions are available when @option{-maes} is
-used. All of them generate the machine instruction that is part of the
-name.
-
-@smallexample
-v2di __builtin_ia32_aesenc128 (v2di, v2di);
-v2di __builtin_ia32_aesenclast128 (v2di, v2di);
-v2di __builtin_ia32_aesdec128 (v2di, v2di);
-v2di __builtin_ia32_aesdeclast128 (v2di, v2di);
-v2di __builtin_ia32_aeskeygenassist128 (v2di, const int);
-v2di __builtin_ia32_aesimc128 (v2di);
-@end smallexample
-
-The following built-in function is available when @option{-mpclmul} is
-used.
-
-@table @code
-@item v2di __builtin_ia32_pclmulqdq128 (v2di, v2di, const int)
-Generates the @code{pclmulqdq} machine instruction.
-@end table
-
-The following built-in function is available when @option{-mfsgsbase} is
-used. All of them generate the machine instruction that is part of the
-name.
-
-@smallexample
-unsigned int __builtin_ia32_rdfsbase32 (void);
-unsigned long long __builtin_ia32_rdfsbase64 (void);
-unsigned int __builtin_ia32_rdgsbase32 (void);
-unsigned long long __builtin_ia32_rdgsbase64 (void);
-void _writefsbase_u32 (unsigned int);
-void _writefsbase_u64 (unsigned long long);
-void _writegsbase_u32 (unsigned int);
-void _writegsbase_u64 (unsigned long long);
-@end smallexample
-
-The following built-in function is available when @option{-mrdrnd} is
-used. All of them generate the machine instruction that is part of the
-name.
-
-@smallexample
-unsigned int __builtin_ia32_rdrand16_step (unsigned short *);
-unsigned int __builtin_ia32_rdrand32_step (unsigned int *);
-unsigned int __builtin_ia32_rdrand64_step (unsigned long long *);
-@end smallexample
-
-The following built-in function is available when @option{-mptwrite} is
-used. All of them generate the machine instruction that is part of the
-name.
-
-@smallexample
-void __builtin_ia32_ptwrite32 (unsigned);
-void __builtin_ia32_ptwrite64 (unsigned long long);
-@end smallexample
-
-The following built-in functions are available when @option{-msse4a} is used.
-All of them generate the machine instruction that is part of the name.
-
-@smallexample
-void __builtin_ia32_movntsd (double *, v2df);
-void __builtin_ia32_movntss (float *, v4sf);
-v2di __builtin_ia32_extrq (v2di, v16qi);
-v2di __builtin_ia32_extrqi (v2di, const unsigned int, const unsigned int);
-v2di __builtin_ia32_insertq (v2di, v2di);
-v2di __builtin_ia32_insertqi (v2di, v2di, const unsigned int, const unsigned int);
-@end smallexample
-
-The following built-in functions are available when @option{-mxop} is used.
-@smallexample
-v2df __builtin_ia32_vfrczpd (v2df);
-v4sf __builtin_ia32_vfrczps (v4sf);
-v2df __builtin_ia32_vfrczsd (v2df);
-v4sf __builtin_ia32_vfrczss (v4sf);
-v4df __builtin_ia32_vfrczpd256 (v4df);
-v8sf __builtin_ia32_vfrczps256 (v8sf);
-v2di __builtin_ia32_vpcmov (v2di, v2di, v2di);
-v2di __builtin_ia32_vpcmov_v2di (v2di, v2di, v2di);
-v4si __builtin_ia32_vpcmov_v4si (v4si, v4si, v4si);
-v8hi __builtin_ia32_vpcmov_v8hi (v8hi, v8hi, v8hi);
-v16qi __builtin_ia32_vpcmov_v16qi (v16qi, v16qi, v16qi);
-v2df __builtin_ia32_vpcmov_v2df (v2df, v2df, v2df);
-v4sf __builtin_ia32_vpcmov_v4sf (v4sf, v4sf, v4sf);
-v4di __builtin_ia32_vpcmov_v4di256 (v4di, v4di, v4di);
-v8si __builtin_ia32_vpcmov_v8si256 (v8si, v8si, v8si);
-v16hi __builtin_ia32_vpcmov_v16hi256 (v16hi, v16hi, v16hi);
-v32qi __builtin_ia32_vpcmov_v32qi256 (v32qi, v32qi, v32qi);
-v4df __builtin_ia32_vpcmov_v4df256 (v4df, v4df, v4df);
-v8sf __builtin_ia32_vpcmov_v8sf256 (v8sf, v8sf, v8sf);
-v16qi __builtin_ia32_vpcomeqb (v16qi, v16qi);
-v8hi __builtin_ia32_vpcomeqw (v8hi, v8hi);
-v4si __builtin_ia32_vpcomeqd (v4si, v4si);
-v2di __builtin_ia32_vpcomeqq (v2di, v2di);
-v16qi __builtin_ia32_vpcomequb (v16qi, v16qi);
-v4si __builtin_ia32_vpcomequd (v4si, v4si);
-v2di __builtin_ia32_vpcomequq (v2di, v2di);
-v8hi __builtin_ia32_vpcomequw (v8hi, v8hi);
-v8hi __builtin_ia32_vpcomeqw (v8hi, v8hi);
-v16qi __builtin_ia32_vpcomfalseb (v16qi, v16qi);
-v4si __builtin_ia32_vpcomfalsed (v4si, v4si);
-v2di __builtin_ia32_vpcomfalseq (v2di, v2di);
-v16qi __builtin_ia32_vpcomfalseub (v16qi, v16qi);
-v4si __builtin_ia32_vpcomfalseud (v4si, v4si);
-v2di __builtin_ia32_vpcomfalseuq (v2di, v2di);
-v8hi __builtin_ia32_vpcomfalseuw (v8hi, v8hi);
-v8hi __builtin_ia32_vpcomfalsew (v8hi, v8hi);
-v16qi __builtin_ia32_vpcomgeb (v16qi, v16qi);
-v4si __builtin_ia32_vpcomged (v4si, v4si);
-v2di __builtin_ia32_vpcomgeq (v2di, v2di);
-v16qi __builtin_ia32_vpcomgeub (v16qi, v16qi);
-v4si __builtin_ia32_vpcomgeud (v4si, v4si);
-v2di __builtin_ia32_vpcomgeuq (v2di, v2di);
-v8hi __builtin_ia32_vpcomgeuw (v8hi, v8hi);
-v8hi __builtin_ia32_vpcomgew (v8hi, v8hi);
-v16qi __builtin_ia32_vpcomgtb (v16qi, v16qi);
-v4si __builtin_ia32_vpcomgtd (v4si, v4si);
-v2di __builtin_ia32_vpcomgtq (v2di, v2di);
-v16qi __builtin_ia32_vpcomgtub (v16qi, v16qi);
-v4si __builtin_ia32_vpcomgtud (v4si, v4si);
-v2di __builtin_ia32_vpcomgtuq (v2di, v2di);
-v8hi __builtin_ia32_vpcomgtuw (v8hi, v8hi);
-v8hi __builtin_ia32_vpcomgtw (v8hi, v8hi);
-v16qi __builtin_ia32_vpcomleb (v16qi, v16qi);
-v4si __builtin_ia32_vpcomled (v4si, v4si);
-v2di __builtin_ia32_vpcomleq (v2di, v2di);
-v16qi __builtin_ia32_vpcomleub (v16qi, v16qi);
-v4si __builtin_ia32_vpcomleud (v4si, v4si);
-v2di __builtin_ia32_vpcomleuq (v2di, v2di);
-v8hi __builtin_ia32_vpcomleuw (v8hi, v8hi);
-v8hi __builtin_ia32_vpcomlew (v8hi, v8hi);
-v16qi __builtin_ia32_vpcomltb (v16qi, v16qi);
-v4si __builtin_ia32_vpcomltd (v4si, v4si);
-v2di __builtin_ia32_vpcomltq (v2di, v2di);
-v16qi __builtin_ia32_vpcomltub (v16qi, v16qi);
-v4si __builtin_ia32_vpcomltud (v4si, v4si);
-v2di __builtin_ia32_vpcomltuq (v2di, v2di);
-v8hi __builtin_ia32_vpcomltuw (v8hi, v8hi);
-v8hi __builtin_ia32_vpcomltw (v8hi, v8hi);
-v16qi __builtin_ia32_vpcomneb (v16qi, v16qi);
-v4si __builtin_ia32_vpcomned (v4si, v4si);
-v2di __builtin_ia32_vpcomneq (v2di, v2di);
-v16qi __builtin_ia32_vpcomneub (v16qi, v16qi);
-v4si __builtin_ia32_vpcomneud (v4si, v4si);
-v2di __builtin_ia32_vpcomneuq (v2di, v2di);
-v8hi __builtin_ia32_vpcomneuw (v8hi, v8hi);
-v8hi __builtin_ia32_vpcomnew (v8hi, v8hi);
-v16qi __builtin_ia32_vpcomtrueb (v16qi, v16qi);
-v4si __builtin_ia32_vpcomtrued (v4si, v4si);
-v2di __builtin_ia32_vpcomtrueq (v2di, v2di);
-v16qi __builtin_ia32_vpcomtrueub (v16qi, v16qi);
-v4si __builtin_ia32_vpcomtrueud (v4si, v4si);
-v2di __builtin_ia32_vpcomtrueuq (v2di, v2di);
-v8hi __builtin_ia32_vpcomtrueuw (v8hi, v8hi);
-v8hi __builtin_ia32_vpcomtruew (v8hi, v8hi);
-v4si __builtin_ia32_vphaddbd (v16qi);
-v2di __builtin_ia32_vphaddbq (v16qi);
-v8hi __builtin_ia32_vphaddbw (v16qi);
-v2di __builtin_ia32_vphadddq (v4si);
-v4si __builtin_ia32_vphaddubd (v16qi);
-v2di __builtin_ia32_vphaddubq (v16qi);
-v8hi __builtin_ia32_vphaddubw (v16qi);
-v2di __builtin_ia32_vphaddudq (v4si);
-v4si __builtin_ia32_vphadduwd (v8hi);
-v2di __builtin_ia32_vphadduwq (v8hi);
-v4si __builtin_ia32_vphaddwd (v8hi);
-v2di __builtin_ia32_vphaddwq (v8hi);
-v8hi __builtin_ia32_vphsubbw (v16qi);
-v2di __builtin_ia32_vphsubdq (v4si);
-v4si __builtin_ia32_vphsubwd (v8hi);
-v4si __builtin_ia32_vpmacsdd (v4si, v4si, v4si);
-v2di __builtin_ia32_vpmacsdqh (v4si, v4si, v2di);
-v2di __builtin_ia32_vpmacsdql (v4si, v4si, v2di);
-v4si __builtin_ia32_vpmacssdd (v4si, v4si, v4si);
-v2di __builtin_ia32_vpmacssdqh (v4si, v4si, v2di);
-v2di __builtin_ia32_vpmacssdql (v4si, v4si, v2di);
-v4si __builtin_ia32_vpmacsswd (v8hi, v8hi, v4si);
-v8hi __builtin_ia32_vpmacssww (v8hi, v8hi, v8hi);
-v4si __builtin_ia32_vpmacswd (v8hi, v8hi, v4si);
-v8hi __builtin_ia32_vpmacsww (v8hi, v8hi, v8hi);
-v4si __builtin_ia32_vpmadcsswd (v8hi, v8hi, v4si);
-v4si __builtin_ia32_vpmadcswd (v8hi, v8hi, v4si);
-v16qi __builtin_ia32_vpperm (v16qi, v16qi, v16qi);
-v16qi __builtin_ia32_vprotb (v16qi, v16qi);
-v4si __builtin_ia32_vprotd (v4si, v4si);
-v2di __builtin_ia32_vprotq (v2di, v2di);
-v8hi __builtin_ia32_vprotw (v8hi, v8hi);
-v16qi __builtin_ia32_vpshab (v16qi, v16qi);
-v4si __builtin_ia32_vpshad (v4si, v4si);
-v2di __builtin_ia32_vpshaq (v2di, v2di);
-v8hi __builtin_ia32_vpshaw (v8hi, v8hi);
-v16qi __builtin_ia32_vpshlb (v16qi, v16qi);
-v4si __builtin_ia32_vpshld (v4si, v4si);
-v2di __builtin_ia32_vpshlq (v2di, v2di);
-v8hi __builtin_ia32_vpshlw (v8hi, v8hi);
-@end smallexample
-
-The following built-in functions are available when @option{-mfma4} is used.
-All of them generate the machine instruction that is part of the name.
-
-@smallexample
-v2df __builtin_ia32_vfmaddpd (v2df, v2df, v2df);
-v4sf __builtin_ia32_vfmaddps (v4sf, v4sf, v4sf);
-v2df __builtin_ia32_vfmaddsd (v2df, v2df, v2df);
-v4sf __builtin_ia32_vfmaddss (v4sf, v4sf, v4sf);
-v2df __builtin_ia32_vfmsubpd (v2df, v2df, v2df);
-v4sf __builtin_ia32_vfmsubps (v4sf, v4sf, v4sf);
-v2df __builtin_ia32_vfmsubsd (v2df, v2df, v2df);
-v4sf __builtin_ia32_vfmsubss (v4sf, v4sf, v4sf);
-v2df __builtin_ia32_vfnmaddpd (v2df, v2df, v2df);
-v4sf __builtin_ia32_vfnmaddps (v4sf, v4sf, v4sf);
-v2df __builtin_ia32_vfnmaddsd (v2df, v2df, v2df);
-v4sf __builtin_ia32_vfnmaddss (v4sf, v4sf, v4sf);
-v2df __builtin_ia32_vfnmsubpd (v2df, v2df, v2df);
-v4sf __builtin_ia32_vfnmsubps (v4sf, v4sf, v4sf);
-v2df __builtin_ia32_vfnmsubsd (v2df, v2df, v2df);
-v4sf __builtin_ia32_vfnmsubss (v4sf, v4sf, v4sf);
-v2df __builtin_ia32_vfmaddsubpd (v2df, v2df, v2df);
-v4sf __builtin_ia32_vfmaddsubps (v4sf, v4sf, v4sf);
-v2df __builtin_ia32_vfmsubaddpd (v2df, v2df, v2df);
-v4sf __builtin_ia32_vfmsubaddps (v4sf, v4sf, v4sf);
-v4df __builtin_ia32_vfmaddpd256 (v4df, v4df, v4df);
-v8sf __builtin_ia32_vfmaddps256 (v8sf, v8sf, v8sf);
-v4df __builtin_ia32_vfmsubpd256 (v4df, v4df, v4df);
-v8sf __builtin_ia32_vfmsubps256 (v8sf, v8sf, v8sf);
-v4df __builtin_ia32_vfnmaddpd256 (v4df, v4df, v4df);
-v8sf __builtin_ia32_vfnmaddps256 (v8sf, v8sf, v8sf);
-v4df __builtin_ia32_vfnmsubpd256 (v4df, v4df, v4df);
-v8sf __builtin_ia32_vfnmsubps256 (v8sf, v8sf, v8sf);
-v4df __builtin_ia32_vfmaddsubpd256 (v4df, v4df, v4df);
-v8sf __builtin_ia32_vfmaddsubps256 (v8sf, v8sf, v8sf);
-v4df __builtin_ia32_vfmsubaddpd256 (v4df, v4df, v4df);
-v8sf __builtin_ia32_vfmsubaddps256 (v8sf, v8sf, v8sf);
-
-@end smallexample
-
-The following built-in functions are available when @option{-mlwp} is used.
-
-@smallexample
-void __builtin_ia32_llwpcb16 (void *);
-void __builtin_ia32_llwpcb32 (void *);
-void __builtin_ia32_llwpcb64 (void *);
-void * __builtin_ia32_llwpcb16 (void);
-void * __builtin_ia32_llwpcb32 (void);
-void * __builtin_ia32_llwpcb64 (void);
-void __builtin_ia32_lwpval16 (unsigned short, unsigned int, unsigned short);
-void __builtin_ia32_lwpval32 (unsigned int, unsigned int, unsigned int);
-void __builtin_ia32_lwpval64 (unsigned __int64, unsigned int, unsigned int);
-unsigned char __builtin_ia32_lwpins16 (unsigned short, unsigned int, unsigned short);
-unsigned char __builtin_ia32_lwpins32 (unsigned int, unsigned int, unsigned int);
-unsigned char __builtin_ia32_lwpins64 (unsigned __int64, unsigned int, unsigned int);
-@end smallexample
-
-The following built-in functions are available when @option{-mbmi} is used.
-All of them generate the machine instruction that is part of the name.
-@smallexample
-unsigned int __builtin_ia32_bextr_u32(unsigned int, unsigned int);
-unsigned long long __builtin_ia32_bextr_u64 (unsigned long long, unsigned long long);
-@end smallexample
-
-The following built-in functions are available when @option{-mbmi2} is used.
-All of them generate the machine instruction that is part of the name.
-@smallexample
-unsigned int _bzhi_u32 (unsigned int, unsigned int);
-unsigned int _pdep_u32 (unsigned int, unsigned int);
-unsigned int _pext_u32 (unsigned int, unsigned int);
-unsigned long long _bzhi_u64 (unsigned long long, unsigned long long);
-unsigned long long _pdep_u64 (unsigned long long, unsigned long long);
-unsigned long long _pext_u64 (unsigned long long, unsigned long long);
-@end smallexample
-
-The following built-in functions are available when @option{-mlzcnt} is used.
-All of them generate the machine instruction that is part of the name.
-@smallexample
-unsigned short __builtin_ia32_lzcnt_u16(unsigned short);
-unsigned int __builtin_ia32_lzcnt_u32(unsigned int);
-unsigned long long __builtin_ia32_lzcnt_u64 (unsigned long long);
-@end smallexample
-
-The following built-in functions are available when @option{-mfxsr} is used.
-All of them generate the machine instruction that is part of the name.
-@smallexample
-void __builtin_ia32_fxsave (void *);
-void __builtin_ia32_fxrstor (void *);
-void __builtin_ia32_fxsave64 (void *);
-void __builtin_ia32_fxrstor64 (void *);
-@end smallexample
-
-The following built-in functions are available when @option{-mxsave} is used.
-All of them generate the machine instruction that is part of the name.
-@smallexample
-void __builtin_ia32_xsave (void *, long long);
-void __builtin_ia32_xrstor (void *, long long);
-void __builtin_ia32_xsave64 (void *, long long);
-void __builtin_ia32_xrstor64 (void *, long long);
-@end smallexample
-
-The following built-in functions are available when @option{-mxsaveopt} is used.
-All of them generate the machine instruction that is part of the name.
-@smallexample
-void __builtin_ia32_xsaveopt (void *, long long);
-void __builtin_ia32_xsaveopt64 (void *, long long);
-@end smallexample
-
-The following built-in functions are available when @option{-mtbm} is used.
-Both of them generate the immediate form of the bextr machine instruction.
-@smallexample
-unsigned int __builtin_ia32_bextri_u32 (unsigned int,
- const unsigned int);
-unsigned long long __builtin_ia32_bextri_u64 (unsigned long long,
- const unsigned long long);
-@end smallexample
-
-
-The following built-in functions are available when @option{-m3dnow} is used.
-All of them generate the machine instruction that is part of the name.
-
-@smallexample
-void __builtin_ia32_femms (void);
-v8qi __builtin_ia32_pavgusb (v8qi, v8qi);
-v2si __builtin_ia32_pf2id (v2sf);
-v2sf __builtin_ia32_pfacc (v2sf, v2sf);
-v2sf __builtin_ia32_pfadd (v2sf, v2sf);
-v2si __builtin_ia32_pfcmpeq (v2sf, v2sf);
-v2si __builtin_ia32_pfcmpge (v2sf, v2sf);
-v2si __builtin_ia32_pfcmpgt (v2sf, v2sf);
-v2sf __builtin_ia32_pfmax (v2sf, v2sf);
-v2sf __builtin_ia32_pfmin (v2sf, v2sf);
-v2sf __builtin_ia32_pfmul (v2sf, v2sf);
-v2sf __builtin_ia32_pfrcp (v2sf);
-v2sf __builtin_ia32_pfrcpit1 (v2sf, v2sf);
-v2sf __builtin_ia32_pfrcpit2 (v2sf, v2sf);
-v2sf __builtin_ia32_pfrsqrt (v2sf);
-v2sf __builtin_ia32_pfsub (v2sf, v2sf);
-v2sf __builtin_ia32_pfsubr (v2sf, v2sf);
-v2sf __builtin_ia32_pi2fd (v2si);
-v4hi __builtin_ia32_pmulhrw (v4hi, v4hi);
-@end smallexample
-
-The following built-in functions are available when @option{-m3dnowa} is used.
-All of them generate the machine instruction that is part of the name.
-
-@smallexample
-v2si __builtin_ia32_pf2iw (v2sf);
-v2sf __builtin_ia32_pfnacc (v2sf, v2sf);
-v2sf __builtin_ia32_pfpnacc (v2sf, v2sf);
-v2sf __builtin_ia32_pi2fw (v2si);
-v2sf __builtin_ia32_pswapdsf (v2sf);
-v2si __builtin_ia32_pswapdsi (v2si);
-@end smallexample
-
-The following built-in functions are available when @option{-mrtm} is used
-They are used for restricted transactional memory. These are the internal
-low level functions. Normally the functions in
-@ref{x86 transactional memory intrinsics} should be used instead.
-
-@smallexample
-int __builtin_ia32_xbegin ();
-void __builtin_ia32_xend ();
-void __builtin_ia32_xabort (status);
-int __builtin_ia32_xtest ();
-@end smallexample
-
-The following built-in functions are available when @option{-mmwaitx} is used.
-All of them generate the machine instruction that is part of the name.
-@smallexample
-void __builtin_ia32_monitorx (void *, unsigned int, unsigned int);
-void __builtin_ia32_mwaitx (unsigned int, unsigned int, unsigned int);
-@end smallexample
-
-The following built-in functions are available when @option{-mclzero} is used.
-All of them generate the machine instruction that is part of the name.
-@smallexample
-void __builtin_i32_clzero (void *);
-@end smallexample
-
-The following built-in functions are available when @option{-mpku} is used.
-They generate reads and writes to PKRU.
-@smallexample
-void __builtin_ia32_wrpkru (unsigned int);
-unsigned int __builtin_ia32_rdpkru ();
-@end smallexample
-
-The following built-in functions are available when
-@option{-mshstk} option is used. They support shadow stack
-machine instructions from Intel Control-flow Enforcement Technology (CET).
-Each built-in function generates the machine instruction that is part
-of the function's name. These are the internal low-level functions.
-Normally the functions in @ref{x86 control-flow protection intrinsics}
-should be used instead.
-
-@smallexample
-unsigned int __builtin_ia32_rdsspd (void);
-unsigned long long __builtin_ia32_rdsspq (void);
-void __builtin_ia32_incsspd (unsigned int);
-void __builtin_ia32_incsspq (unsigned long long);
-void __builtin_ia32_saveprevssp(void);
-void __builtin_ia32_rstorssp(void *);
-void __builtin_ia32_wrssd(unsigned int, void *);
-void __builtin_ia32_wrssq(unsigned long long, void *);
-void __builtin_ia32_wrussd(unsigned int, void *);
-void __builtin_ia32_wrussq(unsigned long long, void *);
-void __builtin_ia32_setssbsy(void);
-void __builtin_ia32_clrssbsy(void *);
-@end smallexample
-
-@node x86 transactional memory intrinsics
-@subsection x86 Transactional Memory Intrinsics
-
-These hardware transactional memory intrinsics for x86 allow you to use
-memory transactions with RTM (Restricted Transactional Memory).
-This support is enabled with the @option{-mrtm} option.
-For using HLE (Hardware Lock Elision) see
-@ref{x86 specific memory model extensions for transactional memory} instead.
-
-A memory transaction commits all changes to memory in an atomic way,
-as visible to other threads. If the transaction fails it is rolled back
-and all side effects discarded.
-
-Generally there is no guarantee that a memory transaction ever succeeds
-and suitable fallback code always needs to be supplied.
-
-@deftypefn {RTM Function} {unsigned} _xbegin ()
-Start a RTM (Restricted Transactional Memory) transaction.
-Returns @code{_XBEGIN_STARTED} when the transaction
-started successfully (note this is not 0, so the constant has to be
-explicitly tested).
-
-If the transaction aborts, all side effects
-are undone and an abort code encoded as a bit mask is returned.
-The following macros are defined:
-
-@table @code
-@item _XABORT_EXPLICIT
-Transaction was explicitly aborted with @code{_xabort}. The parameter passed
-to @code{_xabort} is available with @code{_XABORT_CODE(status)}.
-@item _XABORT_RETRY
-Transaction retry is possible.
-@item _XABORT_CONFLICT
-Transaction abort due to a memory conflict with another thread.
-@item _XABORT_CAPACITY
-Transaction abort due to the transaction using too much memory.
-@item _XABORT_DEBUG
-Transaction abort due to a debug trap.
-@item _XABORT_NESTED
-Transaction abort in an inner nested transaction.
-@end table
-
-There is no guarantee
-any transaction ever succeeds, so there always needs to be a valid
-fallback path.
-@end deftypefn
-
-@deftypefn {RTM Function} {void} _xend ()
-Commit the current transaction. When no transaction is active this faults.
-All memory side effects of the transaction become visible
-to other threads in an atomic manner.
-@end deftypefn
-
-@deftypefn {RTM Function} {int} _xtest ()
-Return a nonzero value if a transaction is currently active, otherwise 0.
-@end deftypefn
-
-@deftypefn {RTM Function} {void} _xabort (status)
-Abort the current transaction. When no transaction is active this is a no-op.
-The @var{status} is an 8-bit constant; its value is encoded in the return
-value from @code{_xbegin}.
-@end deftypefn
-
-Here is an example showing handling for @code{_XABORT_RETRY}
-and a fallback path for other failures:
-
-@smallexample
-#include <immintrin.h>
-
-int n_tries, max_tries;
-unsigned status = _XABORT_EXPLICIT;
-...
-
-for (n_tries = 0; n_tries < max_tries; n_tries++)
- @{
- status = _xbegin ();
- if (status == _XBEGIN_STARTED || !(status & _XABORT_RETRY))
- break;
- @}
-if (status == _XBEGIN_STARTED)
- @{
- ... transaction code...
- _xend ();
- @}
-else
- @{
- ... non-transactional fallback path...
- @}
-@end smallexample
-
-@noindent
-Note that, in most cases, the transactional and non-transactional code
-must synchronize together to ensure consistency.
-
-@node x86 control-flow protection intrinsics
-@subsection x86 Control-Flow Protection Intrinsics
-
-@deftypefn {CET Function} {ret_type} _get_ssp (void)
-Get the current value of shadow stack pointer if shadow stack support
-from Intel CET is enabled in the hardware or @code{0} otherwise.
-The @code{ret_type} is @code{unsigned long long} for 64-bit targets
-and @code{unsigned int} for 32-bit targets.
-@end deftypefn
-
-@deftypefn {CET Function} void _inc_ssp (unsigned int)
-Increment the current shadow stack pointer by the size specified by the
-function argument. The argument is masked to a byte value for security
-reasons, so to increment by more than 255 bytes you must call the function
-multiple times.
-@end deftypefn
-
-The shadow stack unwind code looks like:
-
-@smallexample
-#include <immintrin.h>
-
-/* Unwind the shadow stack for EH. */
-#define _Unwind_Frames_Extra(x) \
- do \
- @{ \
- _Unwind_Word ssp = _get_ssp (); \
- if (ssp != 0) \
- @{ \
- _Unwind_Word tmp = (x); \
- while (tmp > 255) \
- @{ \
- _inc_ssp (tmp); \
- tmp -= 255; \
- @} \
- _inc_ssp (tmp); \
- @} \
- @} \
- while (0)
-@end smallexample
-
-@noindent
-This code runs unconditionally on all 64-bit processors. For 32-bit
-processors the code runs on those that support multi-byte NOP instructions.
-
-@node Target Format Checks
-@section Format Checks Specific to Particular Target Machines
-
-For some target machines, GCC supports additional options to the
-format attribute
-(@pxref{Function Attributes,,Declaring Attributes of Functions}).
-
-@menu
-* Solaris Format Checks::
-* Darwin Format Checks::
-@end menu
-
-@node Solaris Format Checks
-@subsection Solaris Format Checks
-
-Solaris targets support the @code{cmn_err} (or @code{__cmn_err__}) format
-check. @code{cmn_err} accepts a subset of the standard @code{printf}
-conversions, and the two-argument @code{%b} conversion for displaying
-bit-fields. See the Solaris man page for @code{cmn_err} for more information.
-
-@node Darwin Format Checks
-@subsection Darwin Format Checks
-
-In addition to the full set of format archetypes (attribute format style
-arguments such as @code{printf}, @code{scanf}, @code{strftime}, and
-@code{strfmon}), Darwin targets also support the @code{CFString} (or
-@code{__CFString__}) archetype in the @code{format} attribute.
-Declarations with this archetype are parsed for correct syntax
-and argument types. However, parsing of the format string itself and
-validating arguments against it in calls to such functions is currently
-not performed.
-
-Additionally, @code{CFStringRefs} (defined by the @code{CoreFoundation} headers) may
-also be used as format arguments. Note that the relevant headers are only likely to be
-available on Darwin (OSX) installations. On such installations, the XCode and system
-documentation provide descriptions of @code{CFString}, @code{CFStringRefs} and
-associated functions.
-
-@node Pragmas
-@section Pragmas Accepted by GCC
-@cindex pragmas
-@cindex @code{#pragma}
-
-GCC supports several types of pragmas, primarily in order to compile
-code originally written for other compilers. Note that in general
-we do not recommend the use of pragmas; @xref{Function Attributes},
-for further explanation.
-
-The GNU C preprocessor recognizes several pragmas in addition to the
-compiler pragmas documented here. Refer to the CPP manual for more
-information.
-
-@menu
-* AArch64 Pragmas::
-* ARM Pragmas::
-* M32C Pragmas::
-* MeP Pragmas::
-* PRU Pragmas::
-* RS/6000 and PowerPC Pragmas::
-* S/390 Pragmas::
-* Darwin Pragmas::
-* Solaris Pragmas::
-* Symbol-Renaming Pragmas::
-* Structure-Layout Pragmas::
-* Weak Pragmas::
-* Diagnostic Pragmas::
-* Visibility Pragmas::
-* Push/Pop Macro Pragmas::
-* Function Specific Option Pragmas::
-* Loop-Specific Pragmas::
-@end menu
-
-@node AArch64 Pragmas
-@subsection AArch64 Pragmas
-
-The pragmas defined by the AArch64 target correspond to the AArch64
-target function attributes. They can be specified as below:
-@smallexample
-#pragma GCC target("string")
-@end smallexample
-
-where @code{@var{string}} can be any string accepted as an AArch64 target
-attribute. @xref{AArch64 Function Attributes}, for more details
-on the permissible values of @code{string}.
-
-@node ARM Pragmas
-@subsection ARM Pragmas
-
-The ARM target defines pragmas for controlling the default addition of
-@code{long_call} and @code{short_call} attributes to functions.
-@xref{Function Attributes}, for information about the effects of these
-attributes.
-
-@table @code
-@item long_calls
-@cindex pragma, long_calls
-Set all subsequent functions to have the @code{long_call} attribute.
-
-@item no_long_calls
-@cindex pragma, no_long_calls
-Set all subsequent functions to have the @code{short_call} attribute.
-
-@item long_calls_off
-@cindex pragma, long_calls_off
-Do not affect the @code{long_call} or @code{short_call} attributes of
-subsequent functions.
-@end table
-
-@node M32C Pragmas
-@subsection M32C Pragmas
-
-@table @code
-@item GCC memregs @var{number}
-@cindex pragma, memregs
-Overrides the command-line option @code{-memregs=} for the current
-file. Use with care! This pragma must be before any function in the
-file, and mixing different memregs values in different objects may
-make them incompatible. This pragma is useful when a
-performance-critical function uses a memreg for temporary values,
-as it may allow you to reduce the number of memregs used.
-
-@item ADDRESS @var{name} @var{address}
-@cindex pragma, address
-For any declared symbols matching @var{name}, this does three things
-to that symbol: it forces the symbol to be located at the given
-address (a number), it forces the symbol to be volatile, and it
-changes the symbol's scope to be static. This pragma exists for
-compatibility with other compilers, but note that the common
-@code{1234H} numeric syntax is not supported (use @code{0x1234}
-instead). Example:
-
-@smallexample
-#pragma ADDRESS port3 0x103
-char port3;
-@end smallexample
-
-@end table
-
-@node MeP Pragmas
-@subsection MeP Pragmas
-
-@table @code
-
-@item custom io_volatile (on|off)
-@cindex pragma, custom io_volatile
-Overrides the command-line option @code{-mio-volatile} for the current
-file. Note that for compatibility with future GCC releases, this
-option should only be used once before any @code{io} variables in each
-file.
-
-@item GCC coprocessor available @var{registers}
-@cindex pragma, coprocessor available
-Specifies which coprocessor registers are available to the register
-allocator. @var{registers} may be a single register, register range
-separated by ellipses, or comma-separated list of those. Example:
-
-@smallexample
-#pragma GCC coprocessor available $c0...$c10, $c28
-@end smallexample
-
-@item GCC coprocessor call_saved @var{registers}
-@cindex pragma, coprocessor call_saved
-Specifies which coprocessor registers are to be saved and restored by
-any function using them. @var{registers} may be a single register,
-register range separated by ellipses, or comma-separated list of
-those. Example:
-
-@smallexample
-#pragma GCC coprocessor call_saved $c4...$c6, $c31
-@end smallexample
-
-@item GCC coprocessor subclass '(A|B|C|D)' = @var{registers}
-@cindex pragma, coprocessor subclass
-Creates and defines a register class. These register classes can be
-used by inline @code{asm} constructs. @var{registers} may be a single
-register, register range separated by ellipses, or comma-separated
-list of those. Example:
-
-@smallexample
-#pragma GCC coprocessor subclass 'B' = $c2, $c4, $c6
-
-asm ("cpfoo %0" : "=B" (x));
-@end smallexample
-
-@item GCC disinterrupt @var{name} , @var{name} @dots{}
-@cindex pragma, disinterrupt
-For the named functions, the compiler adds code to disable interrupts
-for the duration of those functions. If any functions so named
-are not encountered in the source, a warning is emitted that the pragma is
-not used. Examples:
-
-@smallexample
-#pragma disinterrupt foo
-#pragma disinterrupt bar, grill
-int foo () @{ @dots{} @}
-@end smallexample
-
-@item GCC call @var{name} , @var{name} @dots{}
-@cindex pragma, call
-For the named functions, the compiler always uses a register-indirect
-call model when calling the named functions. Examples:
-
-@smallexample
-extern int foo ();
-#pragma call foo
-@end smallexample
-
-@end table
-
-@node PRU Pragmas
-@subsection PRU Pragmas
-
-@table @code
-
-@item ctable_entry @var{index} @var{constant_address}
-@cindex pragma, ctable_entry
-Specifies that the PRU CTABLE entry given by @var{index} has the value
-@var{constant_address}. This enables GCC to emit LBCO/SBCO instructions
-when the load/store address is known and can be addressed with some CTABLE
-entry. For example:
-
-@smallexample
-/* will compile to "sbco Rx, 2, 0x10, 4" */
-#pragma ctable_entry 2 0x4802a000
-*(unsigned int *)0x4802a010 = val;
-@end smallexample
-
-@end table
-
-@node RS/6000 and PowerPC Pragmas
-@subsection RS/6000 and PowerPC Pragmas
-
-The RS/6000 and PowerPC targets define one pragma for controlling
-whether or not the @code{longcall} attribute is added to function
-declarations by default. This pragma overrides the @option{-mlongcall}
-option, but not the @code{longcall} and @code{shortcall} attributes.
-@xref{RS/6000 and PowerPC Options}, for more information about when long
-calls are and are not necessary.
-
-@table @code
-@item longcall (1)
-@cindex pragma, longcall
-Apply the @code{longcall} attribute to all subsequent function
-declarations.
-
-@item longcall (0)
-Do not apply the @code{longcall} attribute to subsequent function
-declarations.
-@end table
-
-@c Describe h8300 pragmas here.
-@c Describe sh pragmas here.
-@c Describe v850 pragmas here.
-
-@node S/390 Pragmas
-@subsection S/390 Pragmas
-
-The pragmas defined by the S/390 target correspond to the S/390
-target function attributes and some the additional options:
-
-@table @samp
-@item zvector
-@itemx no-zvector
-@end table
-
-Note that options of the pragma, unlike options of the target
-attribute, do change the value of preprocessor macros like
-@code{__VEC__}. They can be specified as below:
-
-@smallexample
-#pragma GCC target("string[,string]...")
-#pragma GCC target("string"[,"string"]...)
-@end smallexample
-
-@node Darwin Pragmas
-@subsection Darwin Pragmas
-
-The following pragmas are available for all architectures running the
-Darwin operating system. These are useful for compatibility with other
-Mac OS compilers.
-
-@table @code
-@item mark @var{tokens}@dots{}
-@cindex pragma, mark
-This pragma is accepted, but has no effect.
-
-@item options align=@var{alignment}
-@cindex pragma, options align
-This pragma sets the alignment of fields in structures. The values of
-@var{alignment} may be @code{mac68k}, to emulate m68k alignment, or
-@code{power}, to emulate PowerPC alignment. Uses of this pragma nest
-properly; to restore the previous setting, use @code{reset} for the
-@var{alignment}.
-
-@item segment @var{tokens}@dots{}
-@cindex pragma, segment
-This pragma is accepted, but has no effect.
-
-@item unused (@var{var} [, @var{var}]@dots{})
-@cindex pragma, unused
-This pragma declares variables to be possibly unused. GCC does not
-produce warnings for the listed variables. The effect is similar to
-that of the @code{unused} attribute, except that this pragma may appear
-anywhere within the variables' scopes.
-@end table
-
-@node Solaris Pragmas
-@subsection Solaris Pragmas
-
-The Solaris target supports @code{#pragma redefine_extname}
-(@pxref{Symbol-Renaming Pragmas}). It also supports additional
-@code{#pragma} directives for compatibility with the system compiler.
-
-@table @code
-@item align @var{alignment} (@var{variable} [, @var{variable}]...)
-@cindex pragma, align
-
-Increase the minimum alignment of each @var{variable} to @var{alignment}.
-This is the same as GCC's @code{aligned} attribute @pxref{Variable
-Attributes}). Macro expansion occurs on the arguments to this pragma
-when compiling C and Objective-C@. It does not currently occur when
-compiling C++, but this is a bug which may be fixed in a future
-release.
-
-@item fini (@var{function} [, @var{function}]...)
-@cindex pragma, fini
-
-This pragma causes each listed @var{function} to be called after
-main, or during shared module unloading, by adding a call to the
-@code{.fini} section.
-
-@item init (@var{function} [, @var{function}]...)
-@cindex pragma, init
-
-This pragma causes each listed @var{function} to be called during
-initialization (before @code{main}) or during shared module loading, by
-adding a call to the @code{.init} section.
-
-@end table
-
-@node Symbol-Renaming Pragmas
-@subsection Symbol-Renaming Pragmas
-
-GCC supports a @code{#pragma} directive that changes the name used in
-assembly for a given declaration. While this pragma is supported on all
-platforms, it is intended primarily to provide compatibility with the
-Solaris system headers. This effect can also be achieved using the asm
-labels extension (@pxref{Asm Labels}).
-
-@table @code
-@item redefine_extname @var{oldname} @var{newname}
-@cindex pragma, redefine_extname
-
-This pragma gives the C function @var{oldname} the assembly symbol
-@var{newname}. The preprocessor macro @code{__PRAGMA_REDEFINE_EXTNAME}
-is defined if this pragma is available (currently on all platforms).
-@end table
-
-This pragma and the @code{asm} labels extension interact in a complicated
-manner. Here are some corner cases you may want to be aware of:
-
-@enumerate
-@item This pragma silently applies only to declarations with external
-linkage. The @code{asm} label feature does not have this restriction.
-
-@item In C++, this pragma silently applies only to declarations with
-``C'' linkage. Again, @code{asm} labels do not have this restriction.
-
-@item If either of the ways of changing the assembly name of a
-declaration are applied to a declaration whose assembly name has
-already been determined (either by a previous use of one of these
-features, or because the compiler needed the assembly name in order to
-generate code), and the new name is different, a warning issues and
-the name does not change.
-
-@item The @var{oldname} used by @code{#pragma redefine_extname} is
-always the C-language name.
-@end enumerate
-
-@node Structure-Layout Pragmas
-@subsection Structure-Layout Pragmas
-
-For compatibility with Microsoft Windows compilers, GCC supports a
-set of @code{#pragma} directives that change the maximum alignment of
-members of structures (other than zero-width bit-fields), unions, and
-classes subsequently defined. The @var{n} value below always is required
-to be a small power of two and specifies the new alignment in bytes.
-
-@enumerate
-@item @code{#pragma pack(@var{n})} simply sets the new alignment.
-@item @code{#pragma pack()} sets the alignment to the one that was in
-effect when compilation started (see also command-line option
-@option{-fpack-struct[=@var{n}]} @pxref{Code Gen Options}).
-@item @code{#pragma pack(push[,@var{n}])} pushes the current alignment
-setting on an internal stack and then optionally sets the new alignment.
-@item @code{#pragma pack(pop)} restores the alignment setting to the one
-saved at the top of the internal stack (and removes that stack entry).
-Note that @code{#pragma pack([@var{n}])} does not influence this internal
-stack; thus it is possible to have @code{#pragma pack(push)} followed by
-multiple @code{#pragma pack(@var{n})} instances and finalized by a single
-@code{#pragma pack(pop)}.
-@end enumerate
-
-Some targets, e.g.@: x86 and PowerPC, support the @code{#pragma ms_struct}
-directive which lays out structures and unions subsequently defined as the
-documented @code{__attribute__ ((ms_struct))}.
-
-@enumerate
-@item @code{#pragma ms_struct on} turns on the Microsoft layout.
-@item @code{#pragma ms_struct off} turns off the Microsoft layout.
-@item @code{#pragma ms_struct reset} goes back to the default layout.
-@end enumerate
-
-Most targets also support the @code{#pragma scalar_storage_order} directive
-which lays out structures and unions subsequently defined as the documented
-@code{__attribute__ ((scalar_storage_order))}.
-
-@enumerate
-@item @code{#pragma scalar_storage_order big-endian} sets the storage order
-of the scalar fields to big-endian.
-@item @code{#pragma scalar_storage_order little-endian} sets the storage order
-of the scalar fields to little-endian.
-@item @code{#pragma scalar_storage_order default} goes back to the endianness
-that was in effect when compilation started (see also command-line option
-@option{-fsso-struct=@var{endianness}} @pxref{C Dialect Options}).
-@end enumerate
-
-@node Weak Pragmas
-@subsection Weak Pragmas
-
-For compatibility with SVR4, GCC supports a set of @code{#pragma}
-directives for declaring symbols to be weak, and defining weak
-aliases.
-
-@table @code
-@item #pragma weak @var{symbol}
-@cindex pragma, weak
-This pragma declares @var{symbol} to be weak, as if the declaration
-had the attribute of the same name. The pragma may appear before
-or after the declaration of @var{symbol}. It is not an error for
-@var{symbol} to never be defined at all.
-
-@item #pragma weak @var{symbol1} = @var{symbol2}
-This pragma declares @var{symbol1} to be a weak alias of @var{symbol2}.
-It is an error if @var{symbol2} is not defined in the current
-translation unit.
-@end table
-
-@node Diagnostic Pragmas
-@subsection Diagnostic Pragmas
-
-GCC allows the user to selectively enable or disable certain types of
-diagnostics, and change the kind of the diagnostic. For example, a
-project's policy might require that all sources compile with
-@option{-Werror} but certain files might have exceptions allowing
-specific types of warnings. Or, a project might selectively enable
-diagnostics and treat them as errors depending on which preprocessor
-macros are defined.
-
-@table @code
-@item #pragma GCC diagnostic @var{kind} @var{option}
-@cindex pragma, diagnostic
-
-Modifies the disposition of a diagnostic. Note that not all
-diagnostics are modifiable; at the moment only warnings (normally
-controlled by @samp{-W@dots{}}) can be controlled, and not all of them.
-Use @option{-fdiagnostics-show-option} to determine which diagnostics
-are controllable and which option controls them.
-
-@var{kind} is @samp{error} to treat this diagnostic as an error,
-@samp{warning} to treat it like a warning (even if @option{-Werror} is
-in effect), or @samp{ignored} if the diagnostic is to be ignored.
-@var{option} is a double quoted string that matches the command-line
-option.
-
-@smallexample
-#pragma GCC diagnostic warning "-Wformat"
-#pragma GCC diagnostic error "-Wformat"
-#pragma GCC diagnostic ignored "-Wformat"
-@end smallexample
-
-Note that these pragmas override any command-line options. GCC keeps
-track of the location of each pragma, and issues diagnostics according
-to the state as of that point in the source file. Thus, pragmas occurring
-after a line do not affect diagnostics caused by that line.
-
-@item #pragma GCC diagnostic push
-@itemx #pragma GCC diagnostic pop
-
-Causes GCC to remember the state of the diagnostics as of each
-@code{push}, and restore to that point at each @code{pop}. If a
-@code{pop} has no matching @code{push}, the command-line options are
-restored.
-
-@smallexample
-#pragma GCC diagnostic error "-Wuninitialized"
- foo(a); /* error is given for this one */
-#pragma GCC diagnostic push
-#pragma GCC diagnostic ignored "-Wuninitialized"
- foo(b); /* no diagnostic for this one */
-#pragma GCC diagnostic pop
- foo(c); /* error is given for this one */
-#pragma GCC diagnostic pop
- foo(d); /* depends on command-line options */
-@end smallexample
-
-@item #pragma GCC diagnostic ignored_attributes
-
-Similarly to @option{-Wno-attributes=}, this pragma allows users to suppress
-warnings about unknown scoped attributes (in C++11 and C2X). For example,
-@code{#pragma GCC diagnostic ignored_attributes "vendor::attr"} disables
-warning about the following declaration:
-
-@smallexample
-[[vendor::attr]] void f();
-@end smallexample
-
-whereas @code{#pragma GCC diagnostic ignored_attributes "vendor::"} prevents
-warning about both of these declarations:
-
-@smallexample
-[[vendor::safe]] void f();
-[[vendor::unsafe]] void f2();
-@end smallexample
-
-@end table
-
-GCC also offers a simple mechanism for printing messages during
-compilation.
-
-@table @code
-@item #pragma message @var{string}
-@cindex pragma, diagnostic
-
-Prints @var{string} as a compiler message on compilation. The message
-is informational only, and is neither a compilation warning nor an
-error. Newlines can be included in the string by using the @samp{\n}
-escape sequence.
-
-@smallexample
-#pragma message "Compiling " __FILE__ "..."
-@end smallexample
-
-@var{string} may be parenthesized, and is printed with location
-information. For example,
-
-@smallexample
-#define DO_PRAGMA(x) _Pragma (#x)
-#define TODO(x) DO_PRAGMA(message ("TODO - " #x))
-
-TODO(Remember to fix this)
-@end smallexample
-
-@noindent
-prints @samp{/tmp/file.c:4: note: #pragma message:
-TODO - Remember to fix this}.
-
-@item #pragma GCC error @var{message}
-@cindex pragma, diagnostic
-Generates an error message. This pragma @emph{is} considered to
-indicate an error in the compilation, and it will be treated as such.
-
-Newlines can be included in the string by using the @samp{\n}
-escape sequence. They will be displayed as newlines even if the
-@option{-fmessage-length} option is set to zero.
-
-The error is only generated if the pragma is present in the code after
-pre-processing has been completed. It does not matter however if the
-code containing the pragma is unreachable:
-
-@smallexample
-#if 0
-#pragma GCC error "this error is not seen"
-#endif
-void foo (void)
-@{
- return;
-#pragma GCC error "this error is seen"
-@}
-@end smallexample
-
-@item #pragma GCC warning @var{message}
-@cindex pragma, diagnostic
-This is just like @samp{pragma GCC error} except that a warning
-message is issued instead of an error message. Unless
-@option{-Werror} is in effect, in which case this pragma will generate
-an error as well.
-
-@end table
-
-@node Visibility Pragmas
-@subsection Visibility Pragmas
-
-@table @code
-@item #pragma GCC visibility push(@var{visibility})
-@itemx #pragma GCC visibility pop
-@cindex pragma, visibility
-
-This pragma allows the user to set the visibility for multiple
-declarations without having to give each a visibility attribute
-(@pxref{Function Attributes}).
-
-In C++, @samp{#pragma GCC visibility} affects only namespace-scope
-declarations. Class members and template specializations are not
-affected; if you want to override the visibility for a particular
-member or instantiation, you must use an attribute.
-
-@end table
-
-
-@node Push/Pop Macro Pragmas
-@subsection Push/Pop Macro Pragmas
-
-For compatibility with Microsoft Windows compilers, GCC supports
-@samp{#pragma push_macro(@var{"macro_name"})}
-and @samp{#pragma pop_macro(@var{"macro_name"})}.
-
-@table @code
-@item #pragma push_macro(@var{"macro_name"})
-@cindex pragma, push_macro
-This pragma saves the value of the macro named as @var{macro_name} to
-the top of the stack for this macro.
-
-@item #pragma pop_macro(@var{"macro_name"})
-@cindex pragma, pop_macro
-This pragma sets the value of the macro named as @var{macro_name} to
-the value on top of the stack for this macro. If the stack for
-@var{macro_name} is empty, the value of the macro remains unchanged.
-@end table
-
-For example:
-
-@smallexample
-#define X 1
-#pragma push_macro("X")
-#undef X
-#define X -1
-#pragma pop_macro("X")
-int x [X];
-@end smallexample
-
-@noindent
-In this example, the definition of X as 1 is saved by @code{#pragma
-push_macro} and restored by @code{#pragma pop_macro}.
-
-@node Function Specific Option Pragmas
-@subsection Function Specific Option Pragmas
-
-@table @code
-@item #pragma GCC target (@var{string}, @dots{})
-@cindex pragma GCC target
-
-This pragma allows you to set target-specific options for functions
-defined later in the source file. One or more strings can be
-specified. Each function that is defined after this point is treated
-as if it had been declared with one @code{target(}@var{string}@code{)}
-attribute for each @var{string} argument. The parentheses around
-the strings in the pragma are optional. @xref{Function Attributes},
-for more information about the @code{target} attribute and the attribute
-syntax.
-
-The @code{#pragma GCC target} pragma is presently implemented for
-x86, ARM, AArch64, PowerPC, S/390, and Nios II targets only.
-
-@item #pragma GCC optimize (@var{string}, @dots{})
-@cindex pragma GCC optimize
-
-This pragma allows you to set global optimization options for functions
-defined later in the source file. One or more strings can be
-specified. Each function that is defined after this point is treated
-as if it had been declared with one @code{optimize(}@var{string}@code{)}
-attribute for each @var{string} argument. The parentheses around
-the strings in the pragma are optional. @xref{Function Attributes},
-for more information about the @code{optimize} attribute and the attribute
-syntax.
-
-@item #pragma GCC push_options
-@itemx #pragma GCC pop_options
-@cindex pragma GCC push_options
-@cindex pragma GCC pop_options
-
-These pragmas maintain a stack of the current target and optimization
-options. It is intended for include files where you temporarily want
-to switch to using a different @samp{#pragma GCC target} or
-@samp{#pragma GCC optimize} and then to pop back to the previous
-options.
-
-@item #pragma GCC reset_options
-@cindex pragma GCC reset_options
-
-This pragma clears the current @code{#pragma GCC target} and
-@code{#pragma GCC optimize} to use the default switches as specified
-on the command line.
-
-@end table
-
-@node Loop-Specific Pragmas
-@subsection Loop-Specific Pragmas
-
-@table @code
-@item #pragma GCC ivdep
-@cindex pragma GCC ivdep
-
-With this pragma, the programmer asserts that there are no loop-carried
-dependencies which would prevent consecutive iterations of
-the following loop from executing concurrently with SIMD
-(single instruction multiple data) instructions.
-
-For example, the compiler can only unconditionally vectorize the following
-loop with the pragma:
-
-@smallexample
-void foo (int n, int *a, int *b, int *c)
-@{
- int i, j;
-#pragma GCC ivdep
- for (i = 0; i < n; ++i)
- a[i] = b[i] + c[i];
-@}
-@end smallexample
-
-@noindent
-In this example, using the @code{restrict} qualifier had the same
-effect. In the following example, that would not be possible. Assume
-@math{k < -m} or @math{k >= m}. Only with the pragma, the compiler knows
-that it can unconditionally vectorize the following loop:
-
-@smallexample
-void ignore_vec_dep (int *a, int k, int c, int m)
-@{
-#pragma GCC ivdep
- for (int i = 0; i < m; i++)
- a[i] = a[i + k] * c;
-@}
-@end smallexample
-
-@item #pragma GCC unroll @var{n}
-@cindex pragma GCC unroll @var{n}
-
-You can use this pragma to control how many times a loop should be unrolled.
-It must be placed immediately before a @code{for}, @code{while} or @code{do}
-loop or a @code{#pragma GCC ivdep}, and applies only to the loop that follows.
-@var{n} is an integer constant expression specifying the unrolling factor.
-The values of @math{0} and @math{1} block any unrolling of the loop.
-
-@end table
-
-@node Unnamed Fields
-@section Unnamed Structure and Union Fields
-@cindex @code{struct}
-@cindex @code{union}
-
-As permitted by ISO C11 and for compatibility with other compilers,
-GCC allows you to define
-a structure or union that contains, as fields, structures and unions
-without names. For example:
-
-@smallexample
-struct @{
- int a;
- union @{
- int b;
- float c;
- @};
- int d;
-@} foo;
-@end smallexample
-
-@noindent
-In this example, you are able to access members of the unnamed
-union with code like @samp{foo.b}. Note that only unnamed structs and
-unions are allowed, you may not have, for example, an unnamed
-@code{int}.
-
-You must never create such structures that cause ambiguous field definitions.
-For example, in this structure:
-
-@smallexample
-struct @{
- int a;
- struct @{
- int a;
- @};
-@} foo;
-@end smallexample
-
-@noindent
-it is ambiguous which @code{a} is being referred to with @samp{foo.a}.
-The compiler gives errors for such constructs.
-
-@opindex fms-extensions
-Unless @option{-fms-extensions} is used, the unnamed field must be a
-structure or union definition without a tag (for example, @samp{struct
-@{ int a; @};}). If @option{-fms-extensions} is used, the field may
-also be a definition with a tag such as @samp{struct foo @{ int a;
-@};}, a reference to a previously defined structure or union such as
-@samp{struct foo;}, or a reference to a @code{typedef} name for a
-previously defined structure or union type.
-
-@opindex fplan9-extensions
-The option @option{-fplan9-extensions} enables
-@option{-fms-extensions} as well as two other extensions. First, a
-pointer to a structure is automatically converted to a pointer to an
-anonymous field for assignments and function calls. For example:
-
-@smallexample
-struct s1 @{ int a; @};
-struct s2 @{ struct s1; @};
-extern void f1 (struct s1 *);
-void f2 (struct s2 *p) @{ f1 (p); @}
-@end smallexample
-
-@noindent
-In the call to @code{f1} inside @code{f2}, the pointer @code{p} is
-converted into a pointer to the anonymous field.
-
-Second, when the type of an anonymous field is a @code{typedef} for a
-@code{struct} or @code{union}, code may refer to the field using the
-name of the @code{typedef}.
-
-@smallexample
-typedef struct @{ int a; @} s1;
-struct s2 @{ s1; @};
-s1 f1 (struct s2 *p) @{ return p->s1; @}
-@end smallexample
-
-These usages are only permitted when they are not ambiguous.
-
-@node Thread-Local
-@section Thread-Local Storage
-@cindex Thread-Local Storage
-@cindex @acronym{TLS}
-@cindex @code{__thread}
-
-Thread-local storage (@acronym{TLS}) is a mechanism by which variables
-are allocated such that there is one instance of the variable per extant
-thread. The runtime model GCC uses to implement this originates
-in the IA-64 processor-specific ABI, but has since been migrated
-to other processors as well. It requires significant support from
-the linker (@command{ld}), dynamic linker (@command{ld.so}), and
-system libraries (@file{libc.so} and @file{libpthread.so}), so it
-is not available everywhere.
-
-At the user level, the extension is visible with a new storage
-class keyword: @code{__thread}. For example:
-
-@smallexample
-__thread int i;
-extern __thread struct state s;
-static __thread char *p;
-@end smallexample
-
-The @code{__thread} specifier may be used alone, with the @code{extern}
-or @code{static} specifiers, but with no other storage class specifier.
-When used with @code{extern} or @code{static}, @code{__thread} must appear
-immediately after the other storage class specifier.
-
-The @code{__thread} specifier may be applied to any global, file-scoped
-static, function-scoped static, or static data member of a class. It may
-not be applied to block-scoped automatic or non-static data member.
-
-When the address-of operator is applied to a thread-local variable, it is
-evaluated at run time and returns the address of the current thread's
-instance of that variable. An address so obtained may be used by any
-thread. When a thread terminates, any pointers to thread-local variables
-in that thread become invalid.
-
-No static initialization may refer to the address of a thread-local variable.
-
-In C++, if an initializer is present for a thread-local variable, it must
-be a @var{constant-expression}, as defined in 5.19.2 of the ANSI/ISO C++
-standard.
-
-See @uref{https://www.akkadia.org/drepper/tls.pdf,
-ELF Handling For Thread-Local Storage} for a detailed explanation of
-the four thread-local storage addressing models, and how the runtime
-is expected to function.
-
-@menu
-* C99 Thread-Local Edits::
-* C++98 Thread-Local Edits::
-@end menu
-
-@node C99 Thread-Local Edits
-@subsection ISO/IEC 9899:1999 Edits for Thread-Local Storage
-
-The following are a set of changes to ISO/IEC 9899:1999 (aka C99)
-that document the exact semantics of the language extension.
-
-@itemize @bullet
-@item
-@cite{5.1.2 Execution environments}
-
-Add new text after paragraph 1
-
-@quotation
-Within either execution environment, a @dfn{thread} is a flow of
-control within a program. It is implementation defined whether
-or not there may be more than one thread associated with a program.
-It is implementation defined how threads beyond the first are
-created, the name and type of the function called at thread
-startup, and how threads may be terminated. However, objects
-with thread storage duration shall be initialized before thread
-startup.
-@end quotation
-
-@item
-@cite{6.2.4 Storage durations of objects}
-
-Add new text before paragraph 3
-
-@quotation
-An object whose identifier is declared with the storage-class
-specifier @w{@code{__thread}} has @dfn{thread storage duration}.
-Its lifetime is the entire execution of the thread, and its
-stored value is initialized only once, prior to thread startup.
-@end quotation
-
-@item
-@cite{6.4.1 Keywords}
-
-Add @code{__thread}.
-
-@item
-@cite{6.7.1 Storage-class specifiers}
-
-Add @code{__thread} to the list of storage class specifiers in
-paragraph 1.
-
-Change paragraph 2 to
-
-@quotation
-With the exception of @code{__thread}, at most one storage-class
-specifier may be given [@dots{}]. The @code{__thread} specifier may
-be used alone, or immediately following @code{extern} or
-@code{static}.
-@end quotation
-
-Add new text after paragraph 6
-
-@quotation
-The declaration of an identifier for a variable that has
-block scope that specifies @code{__thread} shall also
-specify either @code{extern} or @code{static}.
-
-The @code{__thread} specifier shall be used only with
-variables.
-@end quotation
-@end itemize
-
-@node C++98 Thread-Local Edits
-@subsection ISO/IEC 14882:1998 Edits for Thread-Local Storage
-
-The following are a set of changes to ISO/IEC 14882:1998 (aka C++98)
-that document the exact semantics of the language extension.
-
-@itemize @bullet
-@item
-@b{[intro.execution]}
-
-New text after paragraph 4
-
-@quotation
-A @dfn{thread} is a flow of control within the abstract machine.
-It is implementation defined whether or not there may be more than
-one thread.
-@end quotation
-
-New text after paragraph 7
-
-@quotation
-It is unspecified whether additional action must be taken to
-ensure when and whether side effects are visible to other threads.
-@end quotation
-
-@item
-@b{[lex.key]}
-
-Add @code{__thread}.
-
-@item
-@b{[basic.start.main]}
-
-Add after paragraph 5
-
-@quotation
-The thread that begins execution at the @code{main} function is called
-the @dfn{main thread}. It is implementation defined how functions
-beginning threads other than the main thread are designated or typed.
-A function so designated, as well as the @code{main} function, is called
-a @dfn{thread startup function}. It is implementation defined what
-happens if a thread startup function returns. It is implementation
-defined what happens to other threads when any thread calls @code{exit}.
-@end quotation
-
-@item
-@b{[basic.start.init]}
-
-Add after paragraph 4
-
-@quotation
-The storage for an object of thread storage duration shall be
-statically initialized before the first statement of the thread startup
-function. An object of thread storage duration shall not require
-dynamic initialization.
-@end quotation
-
-@item
-@b{[basic.start.term]}
-
-Add after paragraph 3
-
-@quotation
-The type of an object with thread storage duration shall not have a
-non-trivial destructor, nor shall it be an array type whose elements
-(directly or indirectly) have non-trivial destructors.
-@end quotation
-
-@item
-@b{[basic.stc]}
-
-Add ``thread storage duration'' to the list in paragraph 1.
-
-Change paragraph 2
-
-@quotation
-Thread, static, and automatic storage durations are associated with
-objects introduced by declarations [@dots{}].
-@end quotation
-
-Add @code{__thread} to the list of specifiers in paragraph 3.
-
-@item
-@b{[basic.stc.thread]}
-
-New section before @b{[basic.stc.static]}
-
-@quotation
-The keyword @code{__thread} applied to a non-local object gives the
-object thread storage duration.
-
-A local variable or class data member declared both @code{static}
-and @code{__thread} gives the variable or member thread storage
-duration.
-@end quotation
-
-@item
-@b{[basic.stc.static]}
-
-Change paragraph 1
-
-@quotation
-All objects that have neither thread storage duration, dynamic
-storage duration nor are local [@dots{}].
-@end quotation
-
-@item
-@b{[dcl.stc]}
-
-Add @code{__thread} to the list in paragraph 1.
-
-Change paragraph 1
-
-@quotation
-With the exception of @code{__thread}, at most one
-@var{storage-class-specifier} shall appear in a given
-@var{decl-specifier-seq}. The @code{__thread} specifier may
-be used alone, or immediately following the @code{extern} or
-@code{static} specifiers. [@dots{}]
-@end quotation
-
-Add after paragraph 5
-
-@quotation
-The @code{__thread} specifier can be applied only to the names of objects
-and to anonymous unions.
-@end quotation
-
-@item
-@b{[class.mem]}
-
-Add after paragraph 6
-
-@quotation
-Non-@code{static} members shall not be @code{__thread}.
-@end quotation
-@end itemize
-
-@node Binary constants
-@section Binary Constants using the @samp{0b} Prefix
-@cindex Binary constants using the @samp{0b} prefix
-
-Integer constants can be written as binary constants, consisting of a
-sequence of @samp{0} and @samp{1} digits, prefixed by @samp{0b} or
-@samp{0B}. This is particularly useful in environments that operate a
-lot on the bit level (like microcontrollers).
-
-The following statements are identical:
-
-@smallexample
-i = 42;
-i = 0x2a;
-i = 052;
-i = 0b101010;
-@end smallexample
-
-The type of these constants follows the same rules as for octal or
-hexadecimal integer constants, so suffixes like @samp{L} or @samp{UL}
-can be applied.
-
-@node C++ Extensions
-@chapter Extensions to the C++ Language
-@cindex extensions, C++ language
-@cindex C++ language extensions
-
-The GNU compiler provides these extensions to the C++ language (and you
-can also use most of the C language extensions in your C++ programs). If you
-want to write code that checks whether these features are available, you can
-test for the GNU compiler the same way as for C programs: check for a
-predefined macro @code{__GNUC__}. You can also use @code{__GNUG__} to
-test specifically for GNU C++ (@pxref{Common Predefined Macros,,
-Predefined Macros,cpp,The GNU C Preprocessor}).
-
-@menu
-* C++ Volatiles:: What constitutes an access to a volatile object.
-* Restricted Pointers:: C99 restricted pointers and references.
-* Vague Linkage:: Where G++ puts inlines, vtables and such.
-* C++ Interface:: You can use a single C++ header file for both
- declarations and definitions.
-* Template Instantiation:: Methods for ensuring that exactly one copy of
- each needed template instantiation is emitted.
-* Bound member functions:: You can extract a function pointer to the
- method denoted by a @samp{->*} or @samp{.*} expression.
-* C++ Attributes:: Variable, function, and type attributes for C++ only.
-* Function Multiversioning:: Declaring multiple function versions.
-* Type Traits:: Compiler support for type traits.
-* C++ Concepts:: Improved support for generic programming.
-* Deprecated Features:: Things will disappear from G++.
-* Backwards Compatibility:: Compatibilities with earlier definitions of C++.
-@end menu
-
-@node C++ Volatiles
-@section When is a Volatile C++ Object Accessed?
-@cindex accessing volatiles
-@cindex volatile read
-@cindex volatile write
-@cindex volatile access
-
-The C++ standard differs from the C standard in its treatment of
-volatile objects. It fails to specify what constitutes a volatile
-access, except to say that C++ should behave in a similar manner to C
-with respect to volatiles, where possible. However, the different
-lvalueness of expressions between C and C++ complicate the behavior.
-G++ behaves the same as GCC for volatile access, @xref{C
-Extensions,,Volatiles}, for a description of GCC's behavior.
-
-The C and C++ language specifications differ when an object is
-accessed in a void context:
-
-@smallexample
-volatile int *src = @var{somevalue};
-*src;
-@end smallexample
-
-The C++ standard specifies that such expressions do not undergo lvalue
-to rvalue conversion, and that the type of the dereferenced object may
-be incomplete. The C++ standard does not specify explicitly that it
-is lvalue to rvalue conversion that is responsible for causing an
-access. There is reason to believe that it is, because otherwise
-certain simple expressions become undefined. However, because it
-would surprise most programmers, G++ treats dereferencing a pointer to
-volatile object of complete type as GCC would do for an equivalent
-type in C@. When the object has incomplete type, G++ issues a
-warning; if you wish to force an error, you must force a conversion to
-rvalue with, for instance, a static cast.
-
-When using a reference to volatile, G++ does not treat equivalent
-expressions as accesses to volatiles, but instead issues a warning that
-no volatile is accessed. The rationale for this is that otherwise it
-becomes difficult to determine where volatile access occur, and not
-possible to ignore the return value from functions returning volatile
-references. Again, if you wish to force a read, cast the reference to
-an rvalue.
-
-G++ implements the same behavior as GCC does when assigning to a
-volatile object---there is no reread of the assigned-to object, the
-assigned rvalue is reused. Note that in C++ assignment expressions
-are lvalues, and if used as an lvalue, the volatile object is
-referred to. For instance, @var{vref} refers to @var{vobj}, as
-expected, in the following example:
-
-@smallexample
-volatile int vobj;
-volatile int &vref = vobj = @var{something};
-@end smallexample
-
-@node Restricted Pointers
-@section Restricting Pointer Aliasing
-@cindex restricted pointers
-@cindex restricted references
-@cindex restricted this pointer
-
-As with the C front end, G++ understands the C99 feature of restricted pointers,
-specified with the @code{__restrict__}, or @code{__restrict} type
-qualifier. Because you cannot compile C++ by specifying the @option{-std=c99}
-language flag, @code{restrict} is not a keyword in C++.
-
-In addition to allowing restricted pointers, you can specify restricted
-references, which indicate that the reference is not aliased in the local
-context.
-
-@smallexample
-void fn (int *__restrict__ rptr, int &__restrict__ rref)
-@{
- /* @r{@dots{}} */
-@}
-@end smallexample
-
-@noindent
-In the body of @code{fn}, @var{rptr} points to an unaliased integer and
-@var{rref} refers to a (different) unaliased integer.
-
-You may also specify whether a member function's @var{this} pointer is
-unaliased by using @code{__restrict__} as a member function qualifier.
-
-@smallexample
-void T::fn () __restrict__
-@{
- /* @r{@dots{}} */
-@}
-@end smallexample
-
-@noindent
-Within the body of @code{T::fn}, @var{this} has the effective
-definition @code{T *__restrict__ const this}. Notice that the
-interpretation of a @code{__restrict__} member function qualifier is
-different to that of @code{const} or @code{volatile} qualifier, in that it
-is applied to the pointer rather than the object. This is consistent with
-other compilers that implement restricted pointers.
-
-As with all outermost parameter qualifiers, @code{__restrict__} is
-ignored in function definition matching. This means you only need to
-specify @code{__restrict__} in a function definition, rather than
-in a function prototype as well.
-
-@node Vague Linkage
-@section Vague Linkage
-@cindex vague linkage
-
-There are several constructs in C++ that require space in the object
-file but are not clearly tied to a single translation unit. We say that
-these constructs have ``vague linkage''. Typically such constructs are
-emitted wherever they are needed, though sometimes we can be more
-clever.
-
-@table @asis
-@item Inline Functions
-Inline functions are typically defined in a header file which can be
-included in many different compilations. Hopefully they can usually be
-inlined, but sometimes an out-of-line copy is necessary, if the address
-of the function is taken or if inlining fails. In general, we emit an
-out-of-line copy in all translation units where one is needed. As an
-exception, we only emit inline virtual functions with the vtable, since
-it always requires a copy.
-
-Local static variables and string constants used in an inline function
-are also considered to have vague linkage, since they must be shared
-between all inlined and out-of-line instances of the function.
-
-@item VTables
-@cindex vtable
-C++ virtual functions are implemented in most compilers using a lookup
-table, known as a vtable. The vtable contains pointers to the virtual
-functions provided by a class, and each object of the class contains a
-pointer to its vtable (or vtables, in some multiple-inheritance
-situations). If the class declares any non-inline, non-pure virtual
-functions, the first one is chosen as the ``key method'' for the class,
-and the vtable is only emitted in the translation unit where the key
-method is defined.
-
-@emph{Note:} If the chosen key method is later defined as inline, the
-vtable is still emitted in every translation unit that defines it.
-Make sure that any inline virtuals are declared inline in the class
-body, even if they are not defined there.
-
-@item @code{type_info} objects
-@cindex @code{type_info}
-@cindex RTTI
-C++ requires information about types to be written out in order to
-implement @samp{dynamic_cast}, @samp{typeid} and exception handling.
-For polymorphic classes (classes with virtual functions), the @samp{type_info}
-object is written out along with the vtable so that @samp{dynamic_cast}
-can determine the dynamic type of a class object at run time. For all
-other types, we write out the @samp{type_info} object when it is used: when
-applying @samp{typeid} to an expression, throwing an object, or
-referring to a type in a catch clause or exception specification.
-
-@item Template Instantiations
-Most everything in this section also applies to template instantiations,
-but there are other options as well.
-@xref{Template Instantiation,,Where's the Template?}.
-
-@end table
-
-When used with GNU ld version 2.8 or later on an ELF system such as
-GNU/Linux or Solaris 2, or on Microsoft Windows, duplicate copies of
-these constructs will be discarded at link time. This is known as
-COMDAT support.
-
-On targets that don't support COMDAT, but do support weak symbols, GCC
-uses them. This way one copy overrides all the others, but
-the unused copies still take up space in the executable.
-
-For targets that do not support either COMDAT or weak symbols,
-most entities with vague linkage are emitted as local symbols to
-avoid duplicate definition errors from the linker. This does not happen
-for local statics in inlines, however, as having multiple copies
-almost certainly breaks things.
-
-@xref{C++ Interface,,Declarations and Definitions in One Header}, for
-another way to control placement of these constructs.
-
-@node C++ Interface
-@section C++ Interface and Implementation Pragmas
-
-@cindex interface and implementation headers, C++
-@cindex C++ interface and implementation headers
-@cindex pragmas, interface and implementation
-
-@code{#pragma interface} and @code{#pragma implementation} provide the
-user with a way of explicitly directing the compiler to emit entities
-with vague linkage (and debugging information) in a particular
-translation unit.
-
-@emph{Note:} These @code{#pragma}s have been superceded as of GCC 2.7.2
-by COMDAT support and the ``key method'' heuristic
-mentioned in @ref{Vague Linkage}. Using them can actually cause your
-program to grow due to unnecessary out-of-line copies of inline
-functions.
-
-@table @code
-@item #pragma interface
-@itemx #pragma interface "@var{subdir}/@var{objects}.h"
-@kindex #pragma interface
-Use this directive in @emph{header files} that define object classes, to save
-space in most of the object files that use those classes. Normally,
-local copies of certain information (backup copies of inline member
-functions, debugging information, and the internal tables that implement
-virtual functions) must be kept in each object file that includes class
-definitions. You can use this pragma to avoid such duplication. When a
-header file containing @samp{#pragma interface} is included in a
-compilation, this auxiliary information is not generated (unless
-the main input source file itself uses @samp{#pragma implementation}).
-Instead, the object files contain references to be resolved at link
-time.
-
-The second form of this directive is useful for the case where you have
-multiple headers with the same name in different directories. If you
-use this form, you must specify the same string to @samp{#pragma
-implementation}.
-
-@item #pragma implementation
-@itemx #pragma implementation "@var{objects}.h"
-@kindex #pragma implementation
-Use this pragma in a @emph{main input file}, when you want full output from
-included header files to be generated (and made globally visible). The
-included header file, in turn, should use @samp{#pragma interface}.
-Backup copies of inline member functions, debugging information, and the
-internal tables used to implement virtual functions are all generated in
-implementation files.
-
-@cindex implied @code{#pragma implementation}
-@cindex @code{#pragma implementation}, implied
-@cindex naming convention, implementation headers
-If you use @samp{#pragma implementation} with no argument, it applies to
-an include file with the same basename@footnote{A file's @dfn{basename}
-is the name stripped of all leading path information and of trailing
-suffixes, such as @samp{.h} or @samp{.C} or @samp{.cc}.} as your source
-file. For example, in @file{allclass.cc}, giving just
-@samp{#pragma implementation}
-by itself is equivalent to @samp{#pragma implementation "allclass.h"}.
-
-Use the string argument if you want a single implementation file to
-include code from multiple header files. (You must also use
-@samp{#include} to include the header file; @samp{#pragma
-implementation} only specifies how to use the file---it doesn't actually
-include it.)
-
-There is no way to split up the contents of a single header file into
-multiple implementation files.
-@end table
-
-@cindex inlining and C++ pragmas
-@cindex C++ pragmas, effect on inlining
-@cindex pragmas in C++, effect on inlining
-@samp{#pragma implementation} and @samp{#pragma interface} also have an
-effect on function inlining.
-
-If you define a class in a header file marked with @samp{#pragma
-interface}, the effect on an inline function defined in that class is
-similar to an explicit @code{extern} declaration---the compiler emits
-no code at all to define an independent version of the function. Its
-definition is used only for inlining with its callers.
-
-@opindex fno-implement-inlines
-Conversely, when you include the same header file in a main source file
-that declares it as @samp{#pragma implementation}, the compiler emits
-code for the function itself; this defines a version of the function
-that can be found via pointers (or by callers compiled without
-inlining). If all calls to the function can be inlined, you can avoid
-emitting the function by compiling with @option{-fno-implement-inlines}.
-If any calls are not inlined, you will get linker errors.
-
-@node Template Instantiation
-@section Where's the Template?
-@cindex template instantiation
-
-C++ templates were the first language feature to require more
-intelligence from the environment than was traditionally found on a UNIX
-system. Somehow the compiler and linker have to make sure that each
-template instance occurs exactly once in the executable if it is needed,
-and not at all otherwise. There are two basic approaches to this
-problem, which are referred to as the Borland model and the Cfront model.
-
-@table @asis
-@item Borland model
-Borland C++ solved the template instantiation problem by adding the code
-equivalent of common blocks to their linker; the compiler emits template
-instances in each translation unit that uses them, and the linker
-collapses them together. The advantage of this model is that the linker
-only has to consider the object files themselves; there is no external
-complexity to worry about. The disadvantage is that compilation time
-is increased because the template code is being compiled repeatedly.
-Code written for this model tends to include definitions of all
-templates in the header file, since they must be seen to be
-instantiated.
-
-@item Cfront model
-The AT&T C++ translator, Cfront, solved the template instantiation
-problem by creating the notion of a template repository, an
-automatically maintained place where template instances are stored. A
-more modern version of the repository works as follows: As individual
-object files are built, the compiler places any template definitions and
-instantiations encountered in the repository. At link time, the link
-wrapper adds in the objects in the repository and compiles any needed
-instances that were not previously emitted. The advantages of this
-model are more optimal compilation speed and the ability to use the
-system linker; to implement the Borland model a compiler vendor also
-needs to replace the linker. The disadvantages are vastly increased
-complexity, and thus potential for error; for some code this can be
-just as transparent, but in practice it can been very difficult to build
-multiple programs in one directory and one program in multiple
-directories. Code written for this model tends to separate definitions
-of non-inline member templates into a separate file, which should be
-compiled separately.
-@end table
-
-G++ implements the Borland model on targets where the linker supports it,
-including ELF targets (such as GNU/Linux), Mac OS X and Microsoft Windows.
-Otherwise G++ implements neither automatic model.
-
-You have the following options for dealing with template instantiations:
-
-@enumerate
-@item
-Do nothing. Code written for the Borland model works fine, but
-each translation unit contains instances of each of the templates it
-uses. The duplicate instances will be discarded by the linker, but in
-a large program, this can lead to an unacceptable amount of code
-duplication in object files or shared libraries.
-
-Duplicate instances of a template can be avoided by defining an explicit
-instantiation in one object file, and preventing the compiler from doing
-implicit instantiations in any other object files by using an explicit
-instantiation declaration, using the @code{extern template} syntax:
-
-@smallexample
-extern template int max (int, int);
-@end smallexample
-
-This syntax is defined in the C++ 2011 standard, but has been supported by
-G++ and other compilers since well before 2011.
-
-Explicit instantiations can be used for the largest or most frequently
-duplicated instances, without having to know exactly which other instances
-are used in the rest of the program. You can scatter the explicit
-instantiations throughout your program, perhaps putting them in the
-translation units where the instances are used or the translation units
-that define the templates themselves; you can put all of the explicit
-instantiations you need into one big file; or you can create small files
-like
-
-@smallexample
-#include "Foo.h"
-#include "Foo.cc"
-
-template class Foo<int>;
-template ostream& operator <<
- (ostream&, const Foo<int>&);
-@end smallexample
-
-@noindent
-for each of the instances you need, and create a template instantiation
-library from those.
-
-This is the simplest option, but also offers flexibility and
-fine-grained control when necessary. It is also the most portable
-alternative and programs using this approach will work with most modern
-compilers.
-
-@item
-@opindex fno-implicit-templates
-Compile your code with @option{-fno-implicit-templates} to disable the
-implicit generation of template instances, and explicitly instantiate
-all the ones you use. This approach requires more knowledge of exactly
-which instances you need than do the others, but it's less
-mysterious and allows greater control if you want to ensure that only
-the intended instances are used.
-
-If you are using Cfront-model code, you can probably get away with not
-using @option{-fno-implicit-templates} when compiling files that don't
-@samp{#include} the member template definitions.
-
-If you use one big file to do the instantiations, you may want to
-compile it without @option{-fno-implicit-templates} so you get all of the
-instances required by your explicit instantiations (but not by any
-other files) without having to specify them as well.
-
-In addition to forward declaration of explicit instantiations
-(with @code{extern}), G++ has extended the template instantiation
-syntax to support instantiation of the compiler support data for a
-template class (i.e.@: the vtable) without instantiating any of its
-members (with @code{inline}), and instantiation of only the static data
-members of a template class, without the support data or member
-functions (with @code{static}):
-
-@smallexample
-inline template class Foo<int>;
-static template class Foo<int>;
-@end smallexample
-@end enumerate
-
-@node Bound member functions
-@section Extracting the Function Pointer from a Bound Pointer to Member Function
-@cindex pmf
-@cindex pointer to member function
-@cindex bound pointer to member function
-
-In C++, pointer to member functions (PMFs) are implemented using a wide
-pointer of sorts to handle all the possible call mechanisms; the PMF
-needs to store information about how to adjust the @samp{this} pointer,
-and if the function pointed to is virtual, where to find the vtable, and
-where in the vtable to look for the member function. If you are using
-PMFs in an inner loop, you should really reconsider that decision. If
-that is not an option, you can extract the pointer to the function that
-would be called for a given object/PMF pair and call it directly inside
-the inner loop, to save a bit of time.
-
-Note that you still pay the penalty for the call through a
-function pointer; on most modern architectures, such a call defeats the
-branch prediction features of the CPU@. This is also true of normal
-virtual function calls.
-
-The syntax for this extension is
-
-@smallexample
-extern A a;
-extern int (A::*fp)();
-typedef int (*fptr)(A *);
-
-fptr p = (fptr)(a.*fp);
-@end smallexample
-
-For PMF constants (i.e.@: expressions of the form @samp{&Klasse::Member}),
-no object is needed to obtain the address of the function. They can be
-converted to function pointers directly:
-
-@smallexample
-fptr p1 = (fptr)(&A::foo);
-@end smallexample
-
-@opindex Wno-pmf-conversions
-You must specify @option{-Wno-pmf-conversions} to use this extension.
-
-@node C++ Attributes
-@section C++-Specific Variable, Function, and Type Attributes
-
-Some attributes only make sense for C++ programs.
-
-@table @code
-@item abi_tag ("@var{tag}", ...)
-@cindex @code{abi_tag} function attribute
-@cindex @code{abi_tag} variable attribute
-@cindex @code{abi_tag} type attribute
-The @code{abi_tag} attribute can be applied to a function, variable, or class
-declaration. It modifies the mangled name of the entity to
-incorporate the tag name, in order to distinguish the function or
-class from an earlier version with a different ABI; perhaps the class
-has changed size, or the function has a different return type that is
-not encoded in the mangled name.
-
-The attribute can also be applied to an inline namespace, but does not
-affect the mangled name of the namespace; in this case it is only used
-for @option{-Wabi-tag} warnings and automatic tagging of functions and
-variables. Tagging inline namespaces is generally preferable to
-tagging individual declarations, but the latter is sometimes
-necessary, such as when only certain members of a class need to be
-tagged.
-
-The argument can be a list of strings of arbitrary length. The
-strings are sorted on output, so the order of the list is
-unimportant.
-
-A redeclaration of an entity must not add new ABI tags,
-since doing so would change the mangled name.
-
-The ABI tags apply to a name, so all instantiations and
-specializations of a template have the same tags. The attribute will
-be ignored if applied to an explicit specialization or instantiation.
-
-The @option{-Wabi-tag} flag enables a warning about a class which does
-not have all the ABI tags used by its subobjects and virtual functions; for users with code
-that needs to coexist with an earlier ABI, using this option can help
-to find all affected types that need to be tagged.
-
-When a type involving an ABI tag is used as the type of a variable or
-return type of a function where that tag is not already present in the
-signature of the function, the tag is automatically applied to the
-variable or function. @option{-Wabi-tag} also warns about this
-situation; this warning can be avoided by explicitly tagging the
-variable or function or moving it into a tagged inline namespace.
-
-@item init_priority (@var{priority})
-@cindex @code{init_priority} variable attribute
-
-In Standard C++, objects defined at namespace scope are guaranteed to be
-initialized in an order in strict accordance with that of their definitions
-@emph{in a given translation unit}. No guarantee is made for initializations
-across translation units. However, GNU C++ allows users to control the
-order of initialization of objects defined at namespace scope with the
-@code{init_priority} attribute by specifying a relative @var{priority},
-a constant integral expression currently bounded between 101 and 65535
-inclusive. Lower numbers indicate a higher priority.
-
-In the following example, @code{A} would normally be created before
-@code{B}, but the @code{init_priority} attribute reverses that order:
-
-@smallexample
-Some_Class A __attribute__ ((init_priority (2000)));
-Some_Class B __attribute__ ((init_priority (543)));
-@end smallexample
-
-@noindent
-Note that the particular values of @var{priority} do not matter; only their
-relative ordering.
-
-@item warn_unused
-@cindex @code{warn_unused} type attribute
-
-For C++ types with non-trivial constructors and/or destructors it is
-impossible for the compiler to determine whether a variable of this
-type is truly unused if it is not referenced. This type attribute
-informs the compiler that variables of this type should be warned
-about if they appear to be unused, just like variables of fundamental
-types.
-
-This attribute is appropriate for types which just represent a value,
-such as @code{std::string}; it is not appropriate for types which
-control a resource, such as @code{std::lock_guard}.
-
-This attribute is also accepted in C, but it is unnecessary because C
-does not have constructors or destructors.
-
-@end table
-
-@node Function Multiversioning
-@section Function Multiversioning
-@cindex function versions
-
-With the GNU C++ front end, for x86 targets, you may specify multiple
-versions of a function, where each function is specialized for a
-specific target feature. At runtime, the appropriate version of the
-function is automatically executed depending on the characteristics of
-the execution platform. Here is an example.
-
-@smallexample
-__attribute__ ((target ("default")))
-int foo ()
-@{
- // The default version of foo.
- return 0;
-@}
-
-__attribute__ ((target ("sse4.2")))
-int foo ()
-@{
- // foo version for SSE4.2
- return 1;
-@}
-
-__attribute__ ((target ("arch=atom")))
-int foo ()
-@{
- // foo version for the Intel ATOM processor
- return 2;
-@}
-
-__attribute__ ((target ("arch=amdfam10")))
-int foo ()
-@{
- // foo version for the AMD Family 0x10 processors.
- return 3;
-@}
-
-int main ()
-@{
- int (*p)() = &foo;
- assert ((*p) () == foo ());
- return 0;
-@}
-@end smallexample
-
-In the above example, four versions of function foo are created. The
-first version of foo with the target attribute "default" is the default
-version. This version gets executed when no other target specific
-version qualifies for execution on a particular platform. A new version
-of foo is created by using the same function signature but with a
-different target string. Function foo is called or a pointer to it is
-taken just like a regular function. GCC takes care of doing the
-dispatching to call the right version at runtime. Refer to the
-@uref{https://gcc.gnu.org/wiki/FunctionMultiVersioning, GCC wiki on
-Function Multiversioning} for more details.
-
-@node Type Traits
-@section Type Traits
-
-The C++ front end implements syntactic extensions that allow
-compile-time determination of
-various characteristics of a type (or of a
-pair of types).
-
-@table @code
-@item __has_nothrow_assign (type)
-If @code{type} is @code{const}-qualified or is a reference type then
-the trait is @code{false}. Otherwise if @code{__has_trivial_assign (type)}
-is @code{true} then the trait is @code{true}, else if @code{type} is
-a cv-qualified class or union type with copy assignment operators that are
-known not to throw an exception then the trait is @code{true}, else it is
-@code{false}.
-Requires: @code{type} shall be a complete type, (possibly cv-qualified)
-@code{void}, or an array of unknown bound.
-
-@item __has_nothrow_copy (type)
-If @code{__has_trivial_copy (type)} is @code{true} then the trait is
-@code{true}, else if @code{type} is a cv-qualified class or union type
-with copy constructors that are known not to throw an exception then
-the trait is @code{true}, else it is @code{false}.
-Requires: @code{type} shall be a complete type, (possibly cv-qualified)
-@code{void}, or an array of unknown bound.
-
-@item __has_nothrow_constructor (type)
-If @code{__has_trivial_constructor (type)} is @code{true} then the trait
-is @code{true}, else if @code{type} is a cv class or union type (or array
-thereof) with a default constructor that is known not to throw an
-exception then the trait is @code{true}, else it is @code{false}.
-Requires: @code{type} shall be a complete type, (possibly cv-qualified)
-@code{void}, or an array of unknown bound.
-
-@item __has_trivial_assign (type)
-If @code{type} is @code{const}- qualified or is a reference type then
-the trait is @code{false}. Otherwise if @code{__is_trivial (type)} is
-@code{true} then the trait is @code{true}, else if @code{type} is
-a cv-qualified class or union type with a trivial copy assignment
-([class.copy]) then the trait is @code{true}, else it is @code{false}.
-Requires: @code{type} shall be a complete type, (possibly cv-qualified)
-@code{void}, or an array of unknown bound.
-
-@item __has_trivial_copy (type)
-If @code{__is_trivial (type)} is @code{true} or @code{type} is a reference
-type then the trait is @code{true}, else if @code{type} is a cv class
-or union type with a trivial copy constructor ([class.copy]) then the trait
-is @code{true}, else it is @code{false}. Requires: @code{type} shall be
-a complete type, (possibly cv-qualified) @code{void}, or an array of unknown
-bound.
-
-@item __has_trivial_constructor (type)
-If @code{__is_trivial (type)} is @code{true} then the trait is @code{true},
-else if @code{type} is a cv-qualified class or union type (or array thereof)
-with a trivial default constructor ([class.ctor]) then the trait is @code{true},
-else it is @code{false}.
-Requires: @code{type} shall be a complete type, (possibly cv-qualified)
-@code{void}, or an array of unknown bound.
-
-@item __has_trivial_destructor (type)
-If @code{__is_trivial (type)} is @code{true} or @code{type} is a reference type
-then the trait is @code{true}, else if @code{type} is a cv class or union
-type (or array thereof) with a trivial destructor ([class.dtor]) then
-the trait is @code{true}, else it is @code{false}.
-Requires: @code{type} shall be a complete type, (possibly cv-qualified)
-@code{void}, or an array of unknown bound.
-
-@item __has_virtual_destructor (type)
-If @code{type} is a class type with a virtual destructor
-([class.dtor]) then the trait is @code{true}, else it is @code{false}.
-Requires: If @code{type} is a non-union class type, it shall be a complete type.
-
-@item __is_abstract (type)
-If @code{type} is an abstract class ([class.abstract]) then the trait
-is @code{true}, else it is @code{false}.
-Requires: If @code{type} is a non-union class type, it shall be a complete type.
-
-@item __is_aggregate (type)
-If @code{type} is an aggregate type ([dcl.init.aggr]) the trait is
-@code{true}, else it is @code{false}.
-Requires: If @code{type} is a class type, it shall be a complete type.
-
-@item __is_base_of (base_type, derived_type)
-If @code{base_type} is a base class of @code{derived_type}
-([class.derived]) then the trait is @code{true}, otherwise it is @code{false}.
-Top-level cv-qualifications of @code{base_type} and
-@code{derived_type} are ignored. For the purposes of this trait, a
-class type is considered is own base.
-Requires: if @code{__is_class (base_type)} and @code{__is_class (derived_type)}
-are @code{true} and @code{base_type} and @code{derived_type} are not the same
-type (disregarding cv-qualifiers), @code{derived_type} shall be a complete
-type. A diagnostic is produced if this requirement is not met.
-
-@item __is_class (type)
-If @code{type} is a cv-qualified class type, and not a union type
-([basic.compound]) the trait is @code{true}, else it is @code{false}.
-
-@item __is_empty (type)
-If @code{__is_class (type)} is @code{false} then the trait is @code{false}.
-Otherwise @code{type} is considered empty if and only if: @code{type}
-has no non-static data members, or all non-static data members, if
-any, are bit-fields of length 0, and @code{type} has no virtual
-members, and @code{type} has no virtual base classes, and @code{type}
-has no base classes @code{base_type} for which
-@code{__is_empty (base_type)} is @code{false}.
-Requires: If @code{type} is a non-union class type, it shall be a complete type.
-
-@item __is_enum (type)
-If @code{type} is a cv enumeration type ([basic.compound]) the trait is
-@code{true}, else it is @code{false}.
-
-@item __is_final (type)
-If @code{type} is a class or union type marked @code{final}, then the trait
-is @code{true}, else it is @code{false}.
-Requires: If @code{type} is a class type, it shall be a complete type.
-
-@item __is_literal_type (type)
-If @code{type} is a literal type ([basic.types]) the trait is
-@code{true}, else it is @code{false}.
-Requires: @code{type} shall be a complete type, (possibly cv-qualified)
-@code{void}, or an array of unknown bound.
-
-@item __is_pod (type)
-If @code{type} is a cv POD type ([basic.types]) then the trait is @code{true},
-else it is @code{false}.
-Requires: @code{type} shall be a complete type, (possibly cv-qualified)
-@code{void}, or an array of unknown bound.
-
-@item __is_polymorphic (type)
-If @code{type} is a polymorphic class ([class.virtual]) then the trait
-is @code{true}, else it is @code{false}.
-Requires: If @code{type} is a non-union class type, it shall be a complete type.
-
-@item __is_standard_layout (type)
-If @code{type} is a standard-layout type ([basic.types]) the trait is
-@code{true}, else it is @code{false}.
-Requires: @code{type} shall be a complete type, an array of complete types,
-or (possibly cv-qualified) @code{void}.
-
-@item __is_trivial (type)
-If @code{type} is a trivial type ([basic.types]) the trait is
-@code{true}, else it is @code{false}.
-Requires: @code{type} shall be a complete type, an array of complete types,
-or (possibly cv-qualified) @code{void}.
-
-@item __is_union (type)
-If @code{type} is a cv union type ([basic.compound]) the trait is
-@code{true}, else it is @code{false}.
-
-@item __underlying_type (type)
-The underlying type of @code{type}.
-Requires: @code{type} shall be an enumeration type ([dcl.enum]).
-
-@item __integer_pack (length)
-When used as the pattern of a pack expansion within a template
-definition, expands to a template argument pack containing integers
-from @code{0} to @code{length-1}. This is provided for efficient
-implementation of @code{std::make_integer_sequence}.
-
-@end table
-
-
-@node C++ Concepts
-@section C++ Concepts
-
-C++ concepts provide much-improved support for generic programming. In
-particular, they allow the specification of constraints on template arguments.
-The constraints are used to extend the usual overloading and partial
-specialization capabilities of the language, allowing generic data structures
-and algorithms to be ``refined'' based on their properties rather than their
-type names.
-
-The following keywords are reserved for concepts.
-
-@table @code
-@item assumes
-States an expression as an assumption, and if possible, verifies that the
-assumption is valid. For example, @code{assume(n > 0)}.
-
-@item axiom
-Introduces an axiom definition. Axioms introduce requirements on values.
-
-@item forall
-Introduces a universally quantified object in an axiom. For example,
-@code{forall (int n) n + 0 == n}).
-
-@item concept
-Introduces a concept definition. Concepts are sets of syntactic and semantic
-requirements on types and their values.
-
-@item requires
-Introduces constraints on template arguments or requirements for a member
-function of a class template.
-
-@end table
-
-The front end also exposes a number of internal mechanism that can be used
-to simplify the writing of type traits. Note that some of these traits are
-likely to be removed in the future.
-
-@table @code
-@item __is_same (type1, type2)
-A binary type trait: @code{true} whenever the type arguments are the same.
-
-@end table
-
-
-@node Deprecated Features
-@section Deprecated Features
-
-In the past, the GNU C++ compiler was extended to experiment with new
-features, at a time when the C++ language was still evolving. Now that
-the C++ standard is complete, some of those features are superseded by
-superior alternatives. Using the old features might cause a warning in
-some cases that the feature will be dropped in the future. In other
-cases, the feature might be gone already.
-
-G++ allows a virtual function returning @samp{void *} to be overridden
-by one returning a different pointer type. This extension to the
-covariant return type rules is now deprecated and will be removed from a
-future version.
-
-The use of default arguments in function pointers, function typedefs
-and other places where they are not permitted by the standard is
-deprecated and will be removed from a future version of G++.
-
-G++ allows floating-point literals to appear in integral constant expressions,
-e.g.@: @samp{ enum E @{ e = int(2.2 * 3.7) @} }
-This extension is deprecated and will be removed from a future version.
-
-G++ allows static data members of const floating-point type to be declared
-with an initializer in a class definition. The standard only allows
-initializers for static members of const integral types and const
-enumeration types so this extension has been deprecated and will be removed
-from a future version.
-
-G++ allows attributes to follow a parenthesized direct initializer,
-e.g.@: @samp{ int f (0) __attribute__ ((something)); } This extension
-has been ignored since G++ 3.3 and is deprecated.
-
-G++ allows anonymous structs and unions to have members that are not
-public non-static data members (i.e.@: fields). These extensions are
-deprecated.
-
-@node Backwards Compatibility
-@section Backwards Compatibility
-@cindex Backwards Compatibility
-@cindex ARM [Annotated C++ Reference Manual]
-
-Now that there is a definitive ISO standard C++, G++ has a specification
-to adhere to. The C++ language evolved over time, and features that
-used to be acceptable in previous drafts of the standard, such as the ARM
-[Annotated C++ Reference Manual], are no longer accepted. In order to allow
-compilation of C++ written to such drafts, G++ contains some backwards
-compatibilities. @emph{All such backwards compatibility features are
-liable to disappear in future versions of G++.} They should be considered
-deprecated. @xref{Deprecated Features}.
-
-@table @code
-
-@item Implicit C language
-Old C system header files did not contain an @code{extern "C" @{@dots{}@}}
-scope to set the language. On such systems, all system header files are
-implicitly scoped inside a C language scope. Such headers must
-correctly prototype function argument types, there is no leeway for
-@code{()} to indicate an unspecified set of arguments.
-
-@end table
-
-@c LocalWords: emph deftypefn builtin ARCv2EM SIMD builtins msimd
-@c LocalWords: typedef v4si v8hi DMA dma vdiwr vdowr
+++ /dev/null
-@c Copyright (C) 1988-2022 Free Software Foundation, Inc.
-@c This is part of the GCC manual.
-@c For copying conditions, see the file gcc.texi.
-
-@node Fragments
-@chapter Makefile Fragments
-@cindex makefile fragment
-
-When you configure GCC using the @file{configure} script, it will
-construct the file @file{Makefile} from the template file
-@file{Makefile.in}. When it does this, it can incorporate makefile
-fragments from the @file{config} directory. These are used to set
-Makefile parameters that are not amenable to being calculated by
-autoconf. The list of fragments to incorporate is set by
-@file{config.gcc} (and occasionally @file{config.build}
-and @file{config.host}); @xref{System Config}.
-
-Fragments are named either @file{t-@var{target}} or @file{x-@var{host}},
-depending on whether they are relevant to configuring GCC to produce
-code for a particular target, or to configuring GCC to run on a
-particular host. Here @var{target} and @var{host} are mnemonics
-which usually have some relationship to the canonical system name, but
-no formal connection.
-
-If these files do not exist, it means nothing needs to be added for a
-given target or host. Most targets need a few @file{t-@var{target}}
-fragments, but needing @file{x-@var{host}} fragments is rare.
-
-@menu
-* Target Fragment:: Writing @file{t-@var{target}} files.
-* Host Fragment:: Writing @file{x-@var{host}} files.
-@end menu
-
-@node Target Fragment
-@section Target Makefile Fragments
-@cindex target makefile fragment
-@cindex @file{t-@var{target}}
-
-Target makefile fragments can set these Makefile variables.
-
-@table @code
-@findex LIBGCC2_CFLAGS
-@item LIBGCC2_CFLAGS
-Compiler flags to use when compiling @file{libgcc2.c}.
-
-@findex LIB2FUNCS_EXTRA
-@item LIB2FUNCS_EXTRA
-A list of source file names to be compiled or assembled and inserted
-into @file{libgcc.a}.
-
-@findex CRTSTUFF_T_CFLAGS
-@item CRTSTUFF_T_CFLAGS
-Special flags used when compiling @file{crtstuff.c}.
-@xref{Initialization}.
-
-@findex CRTSTUFF_T_CFLAGS_S
-@item CRTSTUFF_T_CFLAGS_S
-Special flags used when compiling @file{crtstuff.c} for shared
-linking. Used if you use @file{crtbeginS.o} and @file{crtendS.o}
-in @code{EXTRA-PARTS}.
-@xref{Initialization}.
-
-@findex MULTILIB_OPTIONS
-@item MULTILIB_OPTIONS
-For some targets, invoking GCC in different ways produces objects
-that cannot be linked together. For example, for some targets GCC
-produces both big and little endian code. For these targets, you must
-arrange for multiple versions of @file{libgcc.a} to be compiled, one for
-each set of incompatible options. When GCC invokes the linker, it
-arranges to link in the right version of @file{libgcc.a}, based on
-the command line options used.
-
-The @code{MULTILIB_OPTIONS} macro lists the set of options for which
-special versions of @file{libgcc.a} must be built. Write options that
-are mutually incompatible side by side, separated by a slash. Write
-options that may be used together separated by a space. The build
-procedure will build all combinations of compatible options.
-
-For example, if you set @code{MULTILIB_OPTIONS} to @samp{m68000/m68020
-msoft-float}, @file{Makefile} will build special versions of
-@file{libgcc.a} using the following sets of options: @option{-m68000},
-@option{-m68020}, @option{-msoft-float}, @samp{-m68000 -msoft-float}, and
-@samp{-m68020 -msoft-float}.
-
-@findex MULTILIB_DIRNAMES
-@item MULTILIB_DIRNAMES
-If @code{MULTILIB_OPTIONS} is used, this variable specifies the
-directory names that should be used to hold the various libraries.
-Write one element in @code{MULTILIB_DIRNAMES} for each element in
-@code{MULTILIB_OPTIONS}. If @code{MULTILIB_DIRNAMES} is not used, the
-default value will be @code{MULTILIB_OPTIONS}, with all slashes treated
-as spaces.
-
-@code{MULTILIB_DIRNAMES} describes the multilib directories using GCC
-conventions and is applied to directories that are part of the GCC
-installation. When multilib-enabled, the compiler will add a
-subdirectory of the form @var{prefix}/@var{multilib} before each
-directory in the search path for libraries and crt files.
-
-For example, if @code{MULTILIB_OPTIONS} is set to @samp{m68000/m68020
-msoft-float}, then the default value of @code{MULTILIB_DIRNAMES} is
-@samp{m68000 m68020 msoft-float}. You may specify a different value if
-you desire a different set of directory names.
-
-@findex MULTILIB_MATCHES
-@item MULTILIB_MATCHES
-Sometimes the same option may be written in two different ways. If an
-option is listed in @code{MULTILIB_OPTIONS}, GCC needs to know about
-any synonyms. In that case, set @code{MULTILIB_MATCHES} to a list of
-items of the form @samp{option=option} to describe all relevant
-synonyms. For example, @samp{m68000=mc68000 m68020=mc68020}.
-
-@findex MULTILIB_EXCEPTIONS
-@item MULTILIB_EXCEPTIONS
-Sometimes when there are multiple sets of @code{MULTILIB_OPTIONS} being
-specified, there are combinations that should not be built. In that
-case, set @code{MULTILIB_EXCEPTIONS} to be all of the switch exceptions
-in shell case syntax that should not be built.
-
-For example the ARM processor cannot execute both hardware floating
-point instructions and the reduced size THUMB instructions at the same
-time, so there is no need to build libraries with both of these
-options enabled. Therefore @code{MULTILIB_EXCEPTIONS} is set to:
-@smallexample
-*mthumb/*mhard-float*
-@end smallexample
-
-@findex MULTILIB_REQUIRED
-@item MULTILIB_REQUIRED
-Sometimes when there are only a few combinations are required, it would
-be a big effort to come up with a @code{MULTILIB_EXCEPTIONS} list to
-cover all undesired ones. In such a case, just listing all the required
-combinations in @code{MULTILIB_REQUIRED} would be more straightforward.
-
-The way to specify the entries in @code{MULTILIB_REQUIRED} is same with
-the way used for @code{MULTILIB_EXCEPTIONS}, only this time what are
-required will be specified. Suppose there are multiple sets of
-@code{MULTILIB_OPTIONS} and only two combinations are required, one
-for ARMv7-M and one for ARMv7-R with hard floating-point ABI and FPU, the
-@code{MULTILIB_REQUIRED} can be set to:
-@smallexample
-@code{MULTILIB_REQUIRED} = mthumb/march=armv7-m
-@code{MULTILIB_REQUIRED} += march=armv7-r/mfloat-abi=hard/mfpu=vfpv3-d16
-@end smallexample
-
-The @code{MULTILIB_REQUIRED} can be used together with
-@code{MULTILIB_EXCEPTIONS}. The option combinations generated from
-@code{MULTILIB_OPTIONS} will be filtered by @code{MULTILIB_EXCEPTIONS}
-and then by @code{MULTILIB_REQUIRED}.
-
-@findex MULTILIB_REUSE
-@item MULTILIB_REUSE
-Sometimes it is desirable to reuse one existing multilib for different
-sets of options. Such kind of reuse can minimize the number of multilib
-variants. And for some targets it is better to reuse an existing multilib
-than to fall back to default multilib when there is no corresponding multilib.
-This can be done by adding reuse rules to @code{MULTILIB_REUSE}.
-
-A reuse rule is comprised of two parts connected by equality sign. The left
-part is the option set used to build multilib and the right part is the option
-set that will reuse this multilib. Both parts should only use options
-specified in @code{MULTILIB_OPTIONS} and the equality signs found in options
-name should be replaced with periods. An explicit period in the rule can be
-escaped by preceding it with a backslash. The order of options in the left
-part matters and should be same with those specified in
-@code{MULTILIB_REQUIRED} or aligned with the order in @code{MULTILIB_OPTIONS}.
-There is no such limitation for options in the right part as we don't build
-multilib from them.
-
-@code{MULTILIB_REUSE} is different from @code{MULTILIB_MATCHES} in that it
-sets up relations between two option sets rather than two options. Here is an
-example to demo how we reuse libraries built in Thumb mode for applications built
-in ARM mode:
-@smallexample
-@code{MULTILIB_REUSE} = mthumb/march.armv7-r=marm/march.armv7-r
-@end smallexample
-
-Before the advent of @code{MULTILIB_REUSE}, GCC select multilib by comparing command
-line options with options used to build multilib. The @code{MULTILIB_REUSE} is
-complementary to that way. Only when the original comparison matches nothing it will
-work to see if it is OK to reuse some existing multilib.
-
-@findex MULTILIB_EXTRA_OPTS
-@item MULTILIB_EXTRA_OPTS
-Sometimes it is desirable that when building multiple versions of
-@file{libgcc.a} certain options should always be passed on to the
-compiler. In that case, set @code{MULTILIB_EXTRA_OPTS} to be the list
-of options to be used for all builds. If you set this, you should
-probably set @code{CRTSTUFF_T_CFLAGS} to a dash followed by it.
-
-@findex MULTILIB_OSDIRNAMES
-@item MULTILIB_OSDIRNAMES
-If @code{MULTILIB_OPTIONS} is used, this variable specifies
-a list of subdirectory names, that are used to modify the search
-path depending on the chosen multilib. Unlike @code{MULTILIB_DIRNAMES},
-@code{MULTILIB_OSDIRNAMES} describes the multilib directories using
-operating systems conventions, and is applied to the directories such as
-@code{lib} or those in the @env{LIBRARY_PATH} environment variable.
-The format is either the same as of
-@code{MULTILIB_DIRNAMES}, or a set of mappings. When it is the same
-as @code{MULTILIB_DIRNAMES}, it describes the multilib directories
-using operating system conventions, rather than GCC conventions. When it is a set
-of mappings of the form @var{gccdir}=@var{osdir}, the left side gives
-the GCC convention and the right gives the equivalent OS defined
-location. If the @var{osdir} part begins with a @samp{!},
-GCC will not search in the non-multilib directory and use
-exclusively the multilib directory. Otherwise, the compiler will
-examine the search path for libraries and crt files twice; the first
-time it will add @var{multilib} to each directory in the search path,
-the second it will not.
-
-For configurations that support both multilib and multiarch,
-@code{MULTILIB_OSDIRNAMES} also encodes the multiarch name, thus
-subsuming @code{MULTIARCH_DIRNAME}. The multiarch name is appended to
-each directory name, separated by a colon (e.g.@:
-@samp{../lib32:i386-linux-gnu}).
-
-Each multiarch subdirectory will be searched before the corresponding OS
-multilib directory, for example @samp{/lib/i386-linux-gnu} before
-@samp{/lib/../lib32}. The multiarch name will also be used to modify the
-system header search path, as explained for @code{MULTIARCH_DIRNAME}.
-
-@findex MULTIARCH_DIRNAME
-@item MULTIARCH_DIRNAME
-This variable specifies the multiarch name for configurations that are
-multiarch-enabled but not multilibbed configurations.
-
-The multiarch name is used to augment the search path for libraries, crt
-files and system header files with additional locations. The compiler
-will add a multiarch subdirectory of the form
-@var{prefix}/@var{multiarch} before each directory in the library and
-crt search path. It will also add two directories
-@code{LOCAL_INCLUDE_DIR}/@var{multiarch} and
-@code{NATIVE_SYSTEM_HEADER_DIR}/@var{multiarch}) to the system header
-search path, respectively before @code{LOCAL_INCLUDE_DIR} and
-@code{NATIVE_SYSTEM_HEADER_DIR}.
-
-@code{MULTIARCH_DIRNAME} is not used for configurations that support
-both multilib and multiarch. In that case, multiarch names are encoded
-in @code{MULTILIB_OSDIRNAMES} instead.
-
-More documentation about multiarch can be found at
-@uref{https://wiki.debian.org/Multiarch}.
-
-@findex SPECS
-@item SPECS
-Unfortunately, setting @code{MULTILIB_EXTRA_OPTS} is not enough, since
-it does not affect the build of target libraries, at least not the
-build of the default multilib. One possible work-around is to use
-@code{DRIVER_SELF_SPECS} to bring options from the @file{specs} file
-as if they had been passed in the compiler driver command line.
-However, you don't want to be adding these options after the toolchain
-is installed, so you can instead tweak the @file{specs} file that will
-be used during the toolchain build, while you still install the
-original, built-in @file{specs}. The trick is to set @code{SPECS} to
-some other filename (say @file{specs.install}), that will then be
-created out of the built-in specs, and introduce a @file{Makefile}
-rule to generate the @file{specs} file that's going to be used at
-build time out of your @file{specs.install}.
-
-@item T_CFLAGS
-These are extra flags to pass to the C compiler. They are used both
-when building GCC, and when compiling things with the just-built GCC@.
-This variable is deprecated and should not be used.
-@end table
-
-@node Host Fragment
-@section Host Makefile Fragments
-@cindex host makefile fragment
-@cindex @file{x-@var{host}}
-
-The use of @file{x-@var{host}} fragments is discouraged. You should only
-use it for makefile dependencies.
+++ /dev/null
-@c Copyright (C) 1988-2022 Free Software Foundation, Inc.
-@c This is part of the GCC manual.
-@c For copying conditions, see the file gcc.texi.
-
-@node G++ and GCC
-@chapter Programming Languages Supported by GCC
-
-@cindex GCC
-@cindex GNU Compiler Collection
-@cindex GNU C Compiler
-@cindex Ada
-@cindex D
-@cindex Fortran
-@cindex Go
-@cindex Objective-C
-@cindex Objective-C++
-GCC stands for ``GNU Compiler Collection''. GCC is an integrated
-distribution of compilers for several major programming languages. These
-languages currently include C, C++, Objective-C, Objective-C++,
-Fortran, Ada, D, and Go.
-
-The abbreviation @dfn{GCC} has multiple meanings in common use. The
-current official meaning is ``GNU Compiler Collection'', which refers
-generically to the complete suite of tools. The name historically stood
-for ``GNU C Compiler'', and this usage is still common when the emphasis
-is on compiling C programs. Finally, the name is also used when speaking
-of the @dfn{language-independent} component of GCC: code shared among the
-compilers for all supported languages.
-
-The language-independent component of GCC includes the majority of the
-optimizers, as well as the ``back ends'' that generate machine code for
-various processors.
-
-@cindex COBOL
-@cindex Mercury
-The part of a compiler that is specific to a particular language is
-called the ``front end''. In addition to the front ends that are
-integrated components of GCC, there are several other front ends that
-are maintained separately. These support languages such as
-Mercury, and COBOL@. To use these, they must be built together with
-GCC proper.
-
-@cindex C++
-@cindex G++
-@cindex Ada
-@cindex GNAT
-Most of the compilers for languages other than C have their own names.
-The C++ compiler is G++, the Ada compiler is GNAT, and so on. When we
-talk about compiling one of those languages, we might refer to that
-compiler by its own name, or as GCC@. Either is correct.
-
-@cindex compiler compared to C++ preprocessor
-@cindex intermediate C version, nonexistent
-@cindex C intermediate output, nonexistent
-Historically, compilers for many languages, including C++ and Fortran,
-have been implemented as ``preprocessors'' which emit another high
-level language such as C@. None of the compilers included in GCC are
-implemented this way; they all generate machine code directly. This
-sort of preprocessor should not be confused with the @dfn{C
-preprocessor}, which is an integral feature of the C, C++, Objective-C
-and Objective-C++ languages.
+++ /dev/null
-\input texinfo @c -*-texinfo-*-
-@c %**start of header
-@setfilename gcc.info
-@c INTERNALS is used by md.texi to determine whether to include the
-@c whole of that file, in the internals manual, or only the part
-@c dealing with constraints, in the user manual.
-@clear INTERNALS
-
-@c NOTE: checks/things to do:
-@c
-@c -have bob do a search in all seven files for "mew" (ideally --mew,
-@c but i may have forgotten the occasional "--"..).
-@c Just checked... all have `--'! Bob 22Jul96
-@c Use this to search: grep -n '\-\-mew' *.texi
-@c -item/itemx, text after all (sub/sub)section titles, etc..
-@c -consider putting the lists of options on pp 17--> etc in columns or
-@c some such.
-@c -overfulls. do a search for "mew" in the files, and you will see
-@c overfulls that i noted but could not deal with.
-@c -have to add text: beginning of chapter 8
-
-@c
-@c anything else? --mew 10feb93
-
-@include gcc-common.texi
-
-@settitle Using the GNU Compiler Collection (GCC)
-
-@c Create a separate index for command line options.
-@defcodeindex op
-@c Merge the standard indexes into a single one.
-@syncodeindex fn cp
-@syncodeindex vr cp
-@syncodeindex ky cp
-@syncodeindex pg cp
-@syncodeindex tp cp
-
-@paragraphindent 1
-
-@c %**end of header
-
-@copying
-Copyright @copyright{} 1988-2022 Free Software Foundation, Inc.
-
-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 the
-Invariant Sections being ``Funding Free Software'', the Front-Cover
-Texts being (a) (see below), and with the Back-Cover Texts being (b)
-(see below). A copy of the license is included in the section entitled
-``GNU Free Documentation License''.
-
-(a) The FSF's Front-Cover Text is:
-
- A GNU Manual
-
-(b) The FSF's Back-Cover Text is:
-
- You have freedom to copy and modify this GNU Manual, like GNU
- software. Copies published by the Free Software Foundation raise
- funds for GNU development.
-@end copying
-@ifnottex
-@dircategory Software development
-@direntry
-* gcc: (gcc). The GNU Compiler Collection.
-* g++: (gcc). The GNU C++ compiler.
-* gcov: (gcc) Gcov. @command{gcov}---a test coverage program.
-* gcov-tool: (gcc) Gcov-tool. @command{gcov-tool}---an offline gcda profile processing program.
-* gcov-dump: (gcc) Gcov-dump. @command{gcov-dump}---an offline gcda and gcno profile dump tool.
-* lto-dump: (gcc) lto-dump. @command{lto-dump}---Tool for
-dumping LTO object files.
-@end direntry
-This file documents the use of the GNU compilers.
-@sp 1
-@insertcopying
-@sp 1
-@end ifnottex
-
-@setchapternewpage odd
-@titlepage
-@title Using the GNU Compiler Collection
-@versionsubtitle
-@author Richard M. Stallman and the @sc{GCC} Developer Community
-@page
-@vskip 0pt plus 1filll
-Published by:
-@multitable @columnfractions 0.5 0.5
-@item GNU Press
-@tab Website: @uref{http://www.gnupress.org}
-@item a division of the
-@tab General: @email{press@@gnu.org}
-@item Free Software Foundation
-@tab Orders: @email{sales@@gnu.org}
-@item 51 Franklin Street, Fifth Floor
-@tab Tel 617-542-5942
-@item Boston, MA 02110-1301 USA
-@tab Fax 617-542-2652
-@end multitable
-@sp 2
-@ifset FSFPRINT
-@c Update this ISBN when printing a new edition.
-@acronym{ISBN} 1-882114-39-6
-
-Cover art by Gary M. Torrisi. Cover design by Jonathan Richard.
-@end ifset
-@ifclear FSFPRINT
-Last printed October 2003 for GCC 3.3.1.@*
-Printed copies are available for $45 each.
-@end ifclear
-@sp 1
-@insertcopying
-@end titlepage
-@summarycontents
-@contents
-@page
-
-@node Top, G++ and GCC
-@top Introduction
-@cindex introduction
-
-This manual documents how to use the GNU compilers,
-as well as their features and incompatibilities, and how to report
-bugs. It corresponds to the compilers
-@ifset VERSION_PACKAGE
-@value{VERSION_PACKAGE}
-@end ifset
-version @value{version-GCC}.
-The internals of the GNU compilers, including how to port them to new
-targets and some information about how to write front ends for new
-languages, are documented in a separate manual. @xref{Top,,
-Introduction, gccint, GNU Compiler Collection (GCC) Internals}.
-
-@menu
-* G++ and GCC:: You can compile C or C++ programs.
-* Standards:: Language standards supported by GCC.
-* Invoking GCC:: Command options supported by @samp{gcc}.
-* C Implementation:: How GCC implements the ISO C specification.
-* C++ Implementation:: How GCC implements the ISO C++ specification.
-* C Extensions:: GNU extensions to the C language family.
-* C++ Extensions:: GNU extensions to the C++ language.
-* Objective-C:: GNU Objective-C runtime features.
-* Compatibility:: Binary Compatibility
-* Gcov:: @command{gcov}---a test coverage program.
-* Gcov-tool:: @command{gcov-tool}---an offline gcda profile processing program.
-* Gcov-dump:: @command{gcov-dump}---an offline gcda and gcno profile dump tool.
-* lto-dump:: @command{lto-dump}---Tool for dumping LTO
-object files.
-* Trouble:: If you have trouble using GCC.
-* Bugs:: How, why and where to report bugs.
-* Service:: How To Get Help with GCC
-* Contributing:: How to contribute to testing and developing GCC.
-
-* Funding:: How to help assure funding for free software.
-* GNU Project:: The GNU Project and GNU/Linux.
-
-* Copying:: GNU General Public License says
- how you can copy and share GCC.
-* GNU Free Documentation License:: How you can copy and share this manual.
-* Contributors:: People who have contributed to GCC.
-
-* Option Index:: Index to command line options.
-* Keyword Index:: Index of concepts and symbol names.
-@end menu
-
-@include frontends.texi
-@include standards.texi
-@include invoke.texi
-@include implement-c.texi
-@include implement-cxx.texi
-@include extend.texi
-@include objc.texi
-@include compat.texi
-@include gcov.texi
-@include gcov-tool.texi
-@include gcov-dump.texi
-@include lto-dump.texi
-@include trouble.texi
-@include bugreport.texi
-@include service.texi
-@include contribute.texi
-
-@include funding.texi
-@include gnu.texi
-@include gpl_v3.texi
-
-@c ---------------------------------------------------------------------
-@c GFDL
-@c ---------------------------------------------------------------------
-
-@include fdl.texi
-
-@include contrib.texi
-
-@c ---------------------------------------------------------------------
-@c Indexes
-@c ---------------------------------------------------------------------
-
-@node Option Index
-@unnumbered Option Index
-
-GCC's command line options are indexed here without any initial @samp{-}
-or @samp{--}. Where an option has both positive and negative forms
-(such as @option{-f@var{option}} and @option{-fno-@var{option}}),
-relevant entries in the manual are indexed under the most appropriate
-form; it may sometimes be useful to look up both forms.
-
-@printindex op
-
-@node Keyword Index
-@unnumbered Keyword Index
-
-@printindex cp
-
-@c ---------------------------------------------------------------------
-@c Epilogue
-@c ---------------------------------------------------------------------
-
-@bye
+++ /dev/null
-\input texinfo @c -*-texinfo-*-
-@c %**start of header
-@setfilename gccint.info
-@c INTERNALS is used by md.texi to determine whether to include the
-@c whole of that file, in the internals manual, or only the part
-@c dealing with constraints, in the user manual.
-@set INTERNALS
-
-@c See miscellaneous notes in gcc.texi on checks/things to do.
-
-@include gcc-common.texi
-
-@settitle GNU Compiler Collection (GCC) Internals
-
-@c Create a separate index for command line options.
-@defcodeindex op
-@c Merge the standard indexes into a single one.
-@syncodeindex fn cp
-@syncodeindex vr cp
-@syncodeindex ky cp
-@syncodeindex pg cp
-@syncodeindex tp cp
-
-@paragraphindent 1
-
-@c %**end of header
-
-@copying
-Copyright @copyright{} 1988-2022 Free Software Foundation, Inc.
-
-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 the
-Invariant Sections being ``Funding Free Software'', the Front-Cover
-Texts being (a) (see below), and with the Back-Cover Texts being (b)
-(see below). A copy of the license is included in the section entitled
-``GNU Free Documentation License''.
-
-(a) The FSF's Front-Cover Text is:
-
- A GNU Manual
-
-(b) The FSF's Back-Cover Text is:
-
- You have freedom to copy and modify this GNU Manual, like GNU
- software. Copies published by the Free Software Foundation raise
- funds for GNU development.
-@end copying
-@ifnottex
-@dircategory Software development
-@direntry
-* gccint: (gccint). Internals of the GNU Compiler Collection.
-@end direntry
-This file documents the internals of the GNU compilers.
-@sp 1
-@insertcopying
-@sp 1
-@end ifnottex
-
-@setchapternewpage odd
-@titlepage
-@title GNU Compiler Collection Internals
-@versionsubtitle
-@author Richard M. Stallman and the @sc{GCC} Developer Community
-@page
-@vskip 0pt plus 1filll
-@insertcopying
-@end titlepage
-@summarycontents
-@contents
-@page
-
-@node Top, Contributing
-@top Introduction
-@cindex introduction
-
-This manual documents the internals of the GNU compilers, including
-how to port them to new targets and some information about how to
-write front ends for new languages. It corresponds to the compilers
-@ifset VERSION_PACKAGE
-@value{VERSION_PACKAGE}
-@end ifset
-version @value{version-GCC}. The use of the GNU compilers is documented in a
-separate manual. @xref{Top,, Introduction, gcc, Using the GNU
-Compiler Collection (GCC)}.
-
-This manual is mainly a reference manual rather than a tutorial. It
-discusses how to contribute to GCC (@pxref{Contributing}), the
-characteristics of the machines supported by GCC as hosts and targets
-(@pxref{Portability}), how GCC relates to the ABIs on such systems
-(@pxref{Interface}), and the characteristics of the languages for
-which GCC front ends are written (@pxref{Languages}). It then
-describes the GCC source tree structure and build system, some of the
-interfaces to GCC front ends, and how support for a target system is
-implemented in GCC@.
-
-Additional tutorial information is linked to from
-@uref{https://gcc.gnu.org/readings.html}.
-
-@menu
-* Contributing:: How to contribute to testing and developing GCC.
-* Portability:: Goals of GCC's portability features.
-* Interface:: Function-call interface of GCC output.
-* Libgcc:: Low-level runtime library used by GCC.
-* Languages:: Languages for which GCC front ends are written.
-* Source Tree:: GCC source tree structure and build system.
-* Testsuites:: GCC testsuites.
-* Options:: Option specification files.
-* Passes:: Order of passes, what they do, and what each file is for.
-* poly_int:: Representation of runtime sizes and offsets.
-* GENERIC:: Language-independent representation generated by Front Ends
-* GIMPLE:: Tuple representation used by Tree SSA optimizers
-* Tree SSA:: Analysis and optimization of GIMPLE
-* RTL:: Machine-dependent low-level intermediate representation.
-* Control Flow:: Maintaining and manipulating the control flow graph.
-* Loop Analysis and Representation:: Analysis and representation of loops
-* Machine Desc:: How to write machine description instruction patterns.
-* Target Macros:: How to write the machine description C macros and functions.
-* Host Config:: Writing the @file{xm-@var{machine}.h} file.
-* Fragments:: Writing the @file{t-@var{target}} and @file{x-@var{host}} files.
-* Collect2:: How @code{collect2} works; how it finds @code{ld}.
-* Header Dirs:: Understanding the standard header file directories.
-* Type Information:: GCC's memory management; generating type information.
-* Plugins:: Extending the compiler with plugins.
-* LTO:: Using Link-Time Optimization.
-
-* Match and Simplify:: How to write expression simplification patterns for GIMPLE and GENERIC
-* Static Analyzer:: Working with the static analyzer.
-* User Experience Guidelines:: Guidelines for implementing diagnostics and options.
-* Funding:: How to help assure funding for free software.
-* GNU Project:: The GNU Project and GNU/Linux.
-
-* Copying:: GNU General Public License says
- how you can copy and share GCC.
-* GNU Free Documentation License:: How you can copy and share this manual.
-* Contributors:: People who have contributed to GCC.
-
-* Option Index:: Index to command line options.
-* Concept Index:: Index of concepts and symbol names.
-@end menu
-
-@include contribute.texi
-@include portability.texi
-@include interface.texi
-@include libgcc.texi
-@include languages.texi
-@include sourcebuild.texi
-@include options.texi
-@include passes.texi
-@include poly-int.texi
-@include generic.texi
-@include gimple.texi
-@include tree-ssa.texi
-@include rtl.texi
-@include cfg.texi
-@include loop.texi
-@include md.texi
-@include tm.texi
-@include hostconfig.texi
-@include fragments.texi
-@include collect2.texi
-@include headerdirs.texi
-@include gty.texi
-@include plugins.texi
-@include lto.texi
-@include match-and-simplify.texi
-@include analyzer.texi
-@include ux.texi
-
-@include funding.texi
-@include gnu.texi
-@include gpl_v3.texi
-
-@c ---------------------------------------------------------------------
-@c GFDL
-@c ---------------------------------------------------------------------
-
-@include fdl.texi
-
-@include contrib.texi
-
-@c ---------------------------------------------------------------------
-@c Indexes
-@c ---------------------------------------------------------------------
-
-@node Option Index
-@unnumbered Option Index
-
-GCC's command line options are indexed here without any initial @samp{-}
-or @samp{--}. Where an option has both positive and negative forms
-(such as @option{-f@var{option}} and @option{-fno-@var{option}}),
-relevant entries in the manual are indexed under the most appropriate
-form; it may sometimes be useful to look up both forms.
-
-@printindex op
-
-@node Concept Index
-@unnumbered Concept Index
-
-@printindex cp
-
-@c ---------------------------------------------------------------------
-@c Epilogue
-@c ---------------------------------------------------------------------
-
-@bye
+++ /dev/null
-@c Copyright (C) 2017-2022 Free Software Foundation, Inc.
-@c This is part of the GCC manual.
-@c For copying conditions, see the file gcc.texi.
-
-@ignore
-@c man begin COPYRIGHT
-Copyright @copyright{} 2017-2022 Free Software Foundation, Inc.
-
-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 the
-Invariant Sections being ``GNU General Public License'' and ``Funding
-Free Software'', the Front-Cover texts being (a) (see below), and with
-the Back-Cover Texts being (b) (see below). A copy of the license is
-included in the gfdl(7) man page.
-
-(a) The FSF's Front-Cover Text is:
-
- A GNU Manual
-
-(b) The FSF's Back-Cover Text is:
-
- You have freedom to copy and modify this GNU Manual, like GNU
- software. Copies published by the Free Software Foundation raise
- funds for GNU development.
-@c man end
-@c Set file name and title for the man page.
-@setfilename gcov-dump
-@settitle offline gcda and gcno profile dump tool
-@end ignore
-
-@node Gcov-dump
-@chapter @command{gcov-dump}---an Offline Gcda and Gcno Profile Dump Tool
-
-@menu
-* Gcov-dump Intro:: Introduction to gcov-dump.
-* Invoking Gcov-dump:: How to use gcov-dump.
-@end menu
-
-@node Gcov-dump Intro
-@section Introduction to @command{gcov-dump}
-@c man begin DESCRIPTION
-
-@command{gcov-dump} is a tool you can use in conjunction with GCC to
-dump content of gcda and gcno profile files offline.
-
-@c man end
-
-@node Invoking Gcov-dump
-@section Invoking @command{gcov-dump}
-
-@smallexample
-Usage: gcov-dump @r{[}@var{OPTION}@r{]} ... @var{gcovfiles}
-@end smallexample
-
-@command{gcov-dump} accepts the following options:
-
-@ignore
-@c man begin SYNOPSIS
-gcov-dump [@option{-v}|@option{--version}]
- [@option{-h}|@option{--help}]
- [@option{-l}|@option{--long}]
- [@option{-p}|@option{--positions}]
- [@option{-r}|@option{--raw}]
- [@option{-s}|@option{--stable}]
- @var{gcovfiles}
-@c man end
-@end ignore
-
-@c man begin OPTIONS
-@table @gcctabopt
-@item -h
-@itemx --help
-Display help about using @command{gcov-dump} (on the standard output), and
-exit without doing any further processing.
-
-@item -l
-@itemx --long
-Dump content of records.
-
-@item -p
-@itemx --positions
-Dump positions of records.
-
-@item -r
-@itemx --raw
-Print content records in raw format.
-
-@item -s
-@itemx --stable
-Print content in stable format usable for comparison.
-
-@item -v
-@itemx --version
-Display the @command{gcov-dump} version number (on the standard output),
-and exit without doing any further processing.
-@end table
-
-@c man end
+++ /dev/null
-@c Copyright (C) 2014-2022 Free Software Foundation, Inc.
-@c This is part of the GCC manual.
-@c For copying conditions, see the file gcc.texi.
-
-@ignore
-@c man begin COPYRIGHT
-Copyright @copyright{} 2014-2022 Free Software Foundation, Inc.
-
-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 the
-Invariant Sections being ``GNU General Public License'' and ``Funding
-Free Software'', the Front-Cover texts being (a) (see below), and with
-the Back-Cover Texts being (b) (see below). A copy of the license is
-included in the gfdl(7) man page.
-
-(a) The FSF's Front-Cover Text is:
-
- A GNU Manual
-
-(b) The FSF's Back-Cover Text is:
-
- You have freedom to copy and modify this GNU Manual, like GNU
- software. Copies published by the Free Software Foundation raise
- funds for GNU development.
-@c man end
-@c Set file name and title for the man page.
-@setfilename gcov-tool
-@settitle offline gcda profile processing tool
-@end ignore
-
-@node Gcov-tool
-@chapter @command{gcov-tool}---an Offline Gcda Profile Processing Tool
-
-@command{gcov-tool} is a tool you can use in conjunction with GCC to
-manipulate or process gcda profile files offline.
-
-@menu
-* Gcov-tool Intro:: Introduction to gcov-tool.
-* Invoking Gcov-tool:: How to use gcov-tool.
-@end menu
-
-@node Gcov-tool Intro
-@section Introduction to @command{gcov-tool}
-@c man begin DESCRIPTION
-
-@command{gcov-tool} is an offline tool to process gcc's gcda profile files.
-
-Current gcov-tool supports the following functionalities:
-
-@itemize @bullet
-@item
-merge two sets of profiles with weights.
-
-@item
-read a stream of profiles with associated filenames and merge it with a set of
-profiles with weights.
-
-@item
-read one set of profile and rewrite profile contents. One can scale or
-normalize the count values.
-@end itemize
-
-Examples of the use cases for this tool are:
-@itemize @bullet
-@item
-Collect the profiles for different set of inputs, and use this tool to merge
-them. One can specify the weight to factor in the relative importance of
-each input.
-
-@item
-Collect profiles from target systems without a filesystem (freestanding
-environments). Merge the collected profiles with associated profiles
-present on the host system. One can specify the weight to factor in the
-relative importance of each input.
-
-@item
-Rewrite the profile after removing a subset of the gcda files, while maintaining
-the consistency of the summary and the histogram.
-
-@item
-It can also be used to debug or libgcov code as the tools shares the majority
-code as the runtime library.
-@end itemize
-
-Note that for the merging operation, this profile generated offline may
-contain slight different values from the online merged profile. Here are
-a list of typical differences:
-
-@itemize @bullet
-@item
-histogram difference: This offline tool recomputes the histogram after merging
-the counters. The resulting histogram, therefore, is precise. The online
-merging does not have this capability -- the histogram is merged from two
-histograms and the result is an approximation.
-
-@item
-summary checksum difference: Summary checksum uses a CRC32 operation. The value
-depends on the link list order of gcov-info objects. This order is different in
-gcov-tool from that in the online merge. It's expected to have different
-summary checksums. It does not really matter as the compiler does not use this
-checksum anywhere.
-
-@item
-value profile counter values difference: Some counter values for value profile
-are runtime dependent, like heap addresses. It's normal to see some difference
-in these kind of counters.
-@end itemize
-
-@c man end
-
-@node Invoking Gcov-tool
-@section Invoking @command{gcov-tool}
-
-@smallexample
-gcov-tool @r{[}@var{global-options}@r{]} SUB_COMMAND @r{[}@var{sub_command-options}@r{]} @var{profile_dir}
-@end smallexample
-
-@command{gcov-tool} accepts the following options:
-
-@ignore
-@c man begin SYNOPSIS
-gcov-tool [@option{-v}|@option{--version}] [@option{-h}|@option{--help}]
-
-gcov-tool merge [merge-options] @var{directory1} @var{directory2}
- [@option{-o}|@option{--output} @var{directory}]
- [@option{-v}|@option{--verbose}]
- [@option{-w}|@option{--weight} @var{w1,w2}]
-
-gcov-tool merge-stream [merge-stream-options] [@var{file}]
- [@option{-v}|@option{--verbose}]
- [@option{-w}|@option{--weight} @var{w1,w2}]
-
-gcov-tool rewrite [rewrite-options] @var{directory}
- [@option{-n}|@option{--normalize} @var{long_long_value}]
- [@option{-o}|@option{--output} @var{directory}]
- [@option{-s}|@option{--scale} @var{float_or_simple-frac_value}]
- [@option{-v}|@option{--verbose}]
-
-gcov-tool overlap [overlap-options] @var{directory1} @var{directory2}
- [@option{-f}|@option{--function}]
- [@option{-F}|@option{--fullname}]
- [@option{-h}|@option{--hotonly}]
- [@option{-o}|@option{--object}]
- [@option{-t}|@option{--hot_threshold}] @var{float}
- [@option{-v}|@option{--verbose}]
-
-@c man end
-@c man begin SEEALSO
-gpl(7), gfdl(7), fsf-funding(7), gcc(1), gcov(1) and the Info entry for
-@file{gcc}.
-@c man end
-@end ignore
-
-@c man begin OPTIONS
-@table @gcctabopt
-@item -h
-@itemx --help
-Display help about using @command{gcov-tool} (on the standard output), and
-exit without doing any further processing.
-
-@item -v
-@itemx --version
-Display the @command{gcov-tool} version number (on the standard output),
-and exit without doing any further processing.
-
-@item merge
-Merge two profile directories.
-@table @gcctabopt
-
-@item -o @var{directory}
-@itemx --output @var{directory}
-Set the output profile directory. Default output directory name is
-@var{merged_profile}.
-
-@item -v
-@itemx --verbose
-Set the verbose mode.
-
-@item -w @var{w1},@var{w2}
-@itemx --weight @var{w1},@var{w2}
-Set the merge weights of the @var{directory1} and @var{directory2},
-respectively. The default weights are 1 for both.
-@end table
-
-@item merge-stream
-Collect profiles with associated filenames from a @emph{gcfn} and @emph{gcda}
-data stream. Read the stream from the file specified by @var{file} or from
-@file{stdin}. Merge the profiles with associated profiles in the host
-filesystem. Apply the optional weights while merging profiles.
-
-For the generation of a @emph{gcfn} and @emph{gcda} data stream on the target
-system, please have a look at the @code{__gcov_filename_to_gcfn()} and
-@code{__gcov_info_to_gcda()} functions declared in @code{#include <gcov.h>}.
-@table @gcctabopt
-
-@item -v
-@itemx --verbose
-Set the verbose mode.
-
-@item -w @var{w1},@var{w2}
-@itemx --weight @var{w1},@var{w2}
-Set the merge weights of the profiles from the @emph{gcfn} and @emph{gcda} data
-stream and the associated profiles in the host filesystem, respectively. The
-default weights are 1 for both.
-@end table
-
-@item rewrite
-Read the specified profile directory and rewrite to a new directory.
-@table @gcctabopt
-
-@item -n @var{long_long_value}
-@itemx --normalize <long_long_value>
-Normalize the profile. The specified value is the max counter value
-in the new profile.
-
-@item -o @var{directory}
-@itemx --output @var{directory}
-Set the output profile directory. Default output name is @var{rewrite_profile}.
-
-@item -s @var{float_or_simple-frac_value}
-@itemx --scale @var{float_or_simple-frac_value}
-Scale the profile counters. The specified value can be in floating point value,
-or simple fraction value form, such 1, 2, 2/3, and 5/3.
-
-@item -v
-@itemx --verbose
-Set the verbose mode.
-@end table
-
-@item overlap
-Compute the overlap score between the two specified profile directories.
-The overlap score is computed based on the arc profiles. It is defined as
-the sum of min (p1_counter[i] / p1_sum_all, p2_counter[i] / p2_sum_all),
-for all arc counter i, where p1_counter[i] and p2_counter[i] are two
-matched counters and p1_sum_all and p2_sum_all are the sum of counter
-values in profile 1 and profile 2, respectively.
-
-@table @gcctabopt
-@item -f
-@itemx --function
-Print function level overlap score.
-
-@item -F
-@itemx --fullname
-Print full gcda filename.
-
-@item -h
-@itemx --hotonly
-Only print info for hot objects/functions.
-
-@item -o
-@itemx --object
-Print object level overlap score.
-
-@item -t @var{float}
-@itemx --hot_threshold <float>
-Set the threshold for hot counter value.
-
-@item -v
-@itemx --verbose
-Set the verbose mode.
-@end table
-
-@end table
-
-@c man end
+++ /dev/null
-@c Copyright (C) 1996-2022 Free Software Foundation, Inc.
-@c This is part of the GCC manual.
-@c For copying conditions, see the file gcc.texi.
-
-@ignore
-@c man begin COPYRIGHT
-Copyright @copyright{} 1996-2022 Free Software Foundation, Inc.
-
-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 the
-Invariant Sections being ``GNU General Public License'' and ``Funding
-Free Software'', the Front-Cover texts being (a) (see below), and with
-the Back-Cover Texts being (b) (see below). A copy of the license is
-included in the gfdl(7) man page.
-
-(a) The FSF's Front-Cover Text is:
-
- A GNU Manual
-
-(b) The FSF's Back-Cover Text is:
-
- You have freedom to copy and modify this GNU Manual, like GNU
- software. Copies published by the Free Software Foundation raise
- funds for GNU development.
-@c man end
-@c Set file name and title for the man page.
-@setfilename gcov
-@settitle coverage testing tool
-@end ignore
-
-@node Gcov
-@chapter @command{gcov}---a Test Coverage Program
-
-@command{gcov} is a tool you can use in conjunction with GCC to
-test code coverage in your programs.
-
-@menu
-* Gcov Intro:: Introduction to gcov.
-* Invoking Gcov:: How to use gcov.
-* Gcov and Optimization:: Using gcov with GCC optimization.
-* Gcov Data Files:: The files used by gcov.
-* Cross-profiling:: Data file relocation.
-* Freestanding Environments:: How to use profiling and test
- coverage in freestanding environments.
-@end menu
-
-@node Gcov Intro
-@section Introduction to @command{gcov}
-@c man begin DESCRIPTION
-
-@command{gcov} is a test coverage program. Use it in concert with GCC
-to analyze your programs to help create more efficient, faster running
-code and to discover untested parts of your program. You can use
-@command{gcov} as a profiling tool to help discover where your
-optimization efforts will best affect your code. You can also use
-@command{gcov} along with the other profiling tool, @command{gprof}, to
-assess which parts of your code use the greatest amount of computing
-time.
-
-Profiling tools help you analyze your code's performance. Using a
-profiler such as @command{gcov} or @command{gprof}, you can find out some
-basic performance statistics, such as:
-
-@itemize @bullet
-@item
-how often each line of code executes
-
-@item
-what lines of code are actually executed
-
-@item
-how much computing time each section of code uses
-@end itemize
-
-Once you know these things about how your code works when compiled, you
-can look at each module to see which modules should be optimized.
-@command{gcov} helps you determine where to work on optimization.
-
-Software developers also use coverage testing in concert with
-testsuites, to make sure software is actually good enough for a release.
-Testsuites can verify that a program works as expected; a coverage
-program tests to see how much of the program is exercised by the
-testsuite. Developers can then determine what kinds of test cases need
-to be added to the testsuites to create both better testing and a better
-final product.
-
-You should compile your code without optimization if you plan to use
-@command{gcov} because the optimization, by combining some lines of code
-into one function, may not give you as much information as you need to
-look for `hot spots' where the code is using a great deal of computer
-time. Likewise, because @command{gcov} accumulates statistics by line (at
-the lowest resolution), it works best with a programming style that
-places only one statement on each line. If you use complicated macros
-that expand to loops or to other control structures, the statistics are
-less helpful---they only report on the line where the macro call
-appears. If your complex macros behave like functions, you can replace
-them with inline functions to solve this problem.
-
-@command{gcov} creates a logfile called @file{@var{sourcefile}.gcov} which
-indicates how many times each line of a source file @file{@var{sourcefile}.c}
-has executed. You can use these logfiles along with @command{gprof} to aid
-in fine-tuning the performance of your programs. @command{gprof} gives
-timing information you can use along with the information you get from
-@command{gcov}.
-
-@command{gcov} works only on code compiled with GCC@. It is not
-compatible with any other profiling or test coverage mechanism.
-
-@c man end
-
-@node Invoking Gcov
-@section Invoking @command{gcov}
-
-@smallexample
-gcov @r{[}@var{options}@r{]} @var{files}
-@end smallexample
-
-@command{gcov} accepts the following options:
-
-@ignore
-@c man begin SYNOPSIS
-gcov [@option{-v}|@option{--version}] [@option{-h}|@option{--help}]
- [@option{-a}|@option{--all-blocks}]
- [@option{-b}|@option{--branch-probabilities}]
- [@option{-c}|@option{--branch-counts}]
- [@option{-d}|@option{--display-progress}]
- [@option{-f}|@option{--function-summaries}]
- [@option{-j}|@option{--json-format}]
- [@option{-H}|@option{--human-readable}]
- [@option{-k}|@option{--use-colors}]
- [@option{-l}|@option{--long-file-names}]
- [@option{-m}|@option{--demangled-names}]
- [@option{-n}|@option{--no-output}]
- [@option{-o}|@option{--object-directory} @var{directory|file}]
- [@option{-p}|@option{--preserve-paths}]
- [@option{-q}|@option{--use-hotness-colors}]
- [@option{-r}|@option{--relative-only}]
- [@option{-s}|@option{--source-prefix} @var{directory}]
- [@option{-t}|@option{--stdout}]
- [@option{-u}|@option{--unconditional-branches}]
- [@option{-x}|@option{--hash-filenames}]
- @var{files}
-@c man end
-@c man begin SEEALSO
-gpl(7), gfdl(7), fsf-funding(7), gcc(1) and the Info entry for @file{gcc}.
-@c man end
-@end ignore
-
-@c man begin OPTIONS
-@table @gcctabopt
-
-@item -a
-@itemx --all-blocks
-Write individual execution counts for every basic block. Normally gcov
-outputs execution counts only for the main blocks of a line. With this
-option you can determine if blocks within a single line are not being
-executed.
-
-@item -b
-@itemx --branch-probabilities
-Write branch frequencies to the output file, and write branch summary
-info to the standard output. This option allows you to see how often
-each branch in your program was taken. Unconditional branches will not
-be shown, unless the @option{-u} option is given.
-
-@item -c
-@itemx --branch-counts
-Write branch frequencies as the number of branches taken, rather than
-the percentage of branches taken.
-
-@item -d
-@itemx --display-progress
-Display the progress on the standard output.
-
-@item -f
-@itemx --function-summaries
-Output summaries for each function in addition to the file level summary.
-
-@item -h
-@itemx --help
-Display help about using @command{gcov} (on the standard output), and
-exit without doing any further processing.
-
-@item -j
-@itemx --json-format
-Output gcov file in an easy-to-parse JSON intermediate format
-which does not require source code for generation. The JSON
-file is compressed with gzip compression algorithm
-and the files have @file{.gcov.json.gz} extension.
-
-Structure of the JSON is following:
-
-@smallexample
-@{
- "current_working_directory": "foo/bar",
- "data_file": "a.out",
- "format_version": "1",
- "gcc_version": "11.1.1 20210510"
- "files": ["$file"]
-@}
-@end smallexample
-
-Fields of the root element have following semantics:
-
-@itemize @bullet
-@item
-@var{current_working_directory}: working directory where
-a compilation unit was compiled
-
-@item
-@var{data_file}: name of the data file (GCDA)
-
-@item
-@var{format_version}: semantic version of the format
-
-@item
-@var{gcc_version}: version of the GCC compiler
-@end itemize
-
-Each @var{file} has the following form:
-
-@smallexample
-@{
- "file": "a.c",
- "functions": ["$function"],
- "lines": ["$line"]
-@}
-@end smallexample
-
-Fields of the @var{file} element have following semantics:
-
-@itemize @bullet
-@item
-@var{file_name}: name of the source file
-@end itemize
-
-Each @var{function} has the following form:
-
-@smallexample
-@{
- "blocks": 2,
- "blocks_executed": 2,
- "demangled_name": "foo",
- "end_column": 1,
- "end_line": 4,
- "execution_count": 1,
- "name": "foo",
- "start_column": 5,
- "start_line": 1
-@}
-@end smallexample
-
-Fields of the @var{function} element have following semantics:
-
-@itemize @bullet
-@item
-@var{blocks}: number of blocks that are in the function
-
-@item
-@var{blocks_executed}: number of executed blocks of the function
-
-@item
-@var{demangled_name}: demangled name of the function
-
-@item
-@var{end_column}: column in the source file where the function ends
-
-@item
-@var{end_line}: line in the source file where the function ends
-
-@item
-@var{execution_count}: number of executions of the function
-
-@item
-@var{name}: name of the function
-
-@item
-@var{start_column}: column in the source file where the function begins
-
-@item
-@var{start_line}: line in the source file where the function begins
-@end itemize
-
-Note that line numbers and column numbers number from 1. In the current
-implementation, @var{start_line} and @var{start_column} do not include
-any template parameters and the leading return type but that
-this is likely to be fixed in the future.
-
-Each @var{line} has the following form:
-
-@smallexample
-@{
- "branches": ["$branch"],
- "count": 2,
- "line_number": 15,
- "unexecuted_block": false,
- "function_name": "foo",
-@}
-@end smallexample
-
-Branches are present only with @var{-b} option.
-Fields of the @var{line} element have following semantics:
-
-@itemize @bullet
-@item
-@var{count}: number of executions of the line
-
-@item
-@var{line_number}: line number
-
-@item
-@var{unexecuted_block}: flag whether the line contains an unexecuted block
-(not all statements on the line are executed)
-
-@item
-@var{function_name}: a name of a function this @var{line} belongs to
-(for a line with an inlined statements can be not set)
-@end itemize
-
-Each @var{branch} has the following form:
-
-@smallexample
-@{
- "count": 11,
- "fallthrough": true,
- "throw": false
-@}
-@end smallexample
-
-Fields of the @var{branch} element have following semantics:
-
-@itemize @bullet
-@item
-@var{count}: number of executions of the branch
-
-@item
-@var{fallthrough}: true when the branch is a fall through branch
-
-@item
-@var{throw}: true when the branch is an exceptional branch
-@end itemize
-
-@item -H
-@itemx --human-readable
-Write counts in human readable format (like 24.6k).
-
-@item -k
-@itemx --use-colors
-
-Use colors for lines of code that have zero coverage. We use red color for
-non-exceptional lines and cyan for exceptional. Same colors are used for
-basic blocks with @option{-a} option.
-
-@item -l
-@itemx --long-file-names
-Create long file names for included source files. For example, if the
-header file @file{x.h} contains code, and was included in the file
-@file{a.c}, then running @command{gcov} on the file @file{a.c} will
-produce an output file called @file{a.c##x.h.gcov} instead of
-@file{x.h.gcov}. This can be useful if @file{x.h} is included in
-multiple source files and you want to see the individual
-contributions. If you use the @samp{-p} option, both the including
-and included file names will be complete path names.
-
-@item -m
-@itemx --demangled-names
-Display demangled function names in output. The default is to show
-mangled function names.
-
-@item -n
-@itemx --no-output
-Do not create the @command{gcov} output file.
-
-@item -o @var{directory|file}
-@itemx --object-directory @var{directory}
-@itemx --object-file @var{file}
-Specify either the directory containing the gcov data files, or the
-object path name. The @file{.gcno}, and
-@file{.gcda} data files are searched for using this option. If a directory
-is specified, the data files are in that directory and named after the
-input file name, without its extension. If a file is specified here,
-the data files are named after that file, without its extension.
-
-@item -p
-@itemx --preserve-paths
-Preserve complete path information in the names of generated
-@file{.gcov} files. Without this option, just the filename component is
-used. With this option, all directories are used, with @samp{/} characters
-translated to @samp{#} characters, @file{.} directory components
-removed and unremoveable @file{..}
-components renamed to @samp{^}. This is useful if sourcefiles are in several
-different directories.
-
-@item -q
-@itemx --use-hotness-colors
-
-Emit perf-like colored output for hot lines. Legend of the color scale
-is printed at the very beginning of the output file.
-
-@item -r
-@itemx --relative-only
-Only output information about source files with a relative pathname
-(after source prefix elision). Absolute paths are usually system
-header files and coverage of any inline functions therein is normally
-uninteresting.
-
-@item -s @var{directory}
-@itemx --source-prefix @var{directory}
-A prefix for source file names to remove when generating the output
-coverage files. This option is useful when building in a separate
-directory, and the pathname to the source directory is not wanted when
-determining the output file names. Note that this prefix detection is
-applied before determining whether the source file is absolute.
-
-@item -t
-@itemx --stdout
-Output to standard output instead of output files.
-
-@item -u
-@itemx --unconditional-branches
-When branch probabilities are given, include those of unconditional branches.
-Unconditional branches are normally not interesting.
-
-@item -v
-@itemx --version
-Display the @command{gcov} version number (on the standard output),
-and exit without doing any further processing.
-
-@item -w
-@itemx --verbose
-Print verbose informations related to basic blocks and arcs.
-
-@item -x
-@itemx --hash-filenames
-When using @var{--preserve-paths},
-gcov uses the full pathname of the source files to create
-an output filename. This can lead to long filenames that can overflow
-filesystem limits. This option creates names of the form
-@file{@var{source-file}##@var{md5}.gcov},
-where the @var{source-file} component is the final filename part and
-the @var{md5} component is calculated from the full mangled name that
-would have been used otherwise. The option is an alternative
-to the @var{--preserve-paths} on systems which have a filesystem limit.
-
-@end table
-
-@command{gcov} should be run with the current directory the same as that
-when you invoked the compiler. Otherwise it will not be able to locate
-the source files. @command{gcov} produces files called
-@file{@var{mangledname}.gcov} in the current directory. These contain
-the coverage information of the source file they correspond to.
-One @file{.gcov} file is produced for each source (or header) file
-containing code,
-which was compiled to produce the data files. The @var{mangledname} part
-of the output file name is usually simply the source file name, but can
-be something more complicated if the @samp{-l} or @samp{-p} options are
-given. Refer to those options for details.
-
-If you invoke @command{gcov} with multiple input files, the
-contributions from each input file are summed. Typically you would
-invoke it with the same list of files as the final link of your executable.
-
-The @file{.gcov} files contain the @samp{:} separated fields along with
-program source code. The format is
-
-@smallexample
-@var{execution_count}:@var{line_number}:@var{source line text}
-@end smallexample
-
-Additional block information may succeed each line, when requested by
-command line option. The @var{execution_count} is @samp{-} for lines
-containing no code. Unexecuted lines are marked @samp{#####} or
-@samp{=====}, depending on whether they are reachable by
-non-exceptional paths or only exceptional paths such as C++ exception
-handlers, respectively. Given the @samp{-a} option, unexecuted blocks are
-marked @samp{$$$$$} or @samp{%%%%%}, depending on whether a basic block
-is reachable via non-exceptional or exceptional paths.
-Executed basic blocks having a statement with zero @var{execution_count}
-end with @samp{*} character and are colored with magenta color with
-the @option{-k} option. This functionality is not supported in Ada.
-
-Note that GCC can completely remove the bodies of functions that are
-not needed -- for instance if they are inlined everywhere. Such functions
-are marked with @samp{-}, which can be confusing.
-Use the @option{-fkeep-inline-functions} and @option{-fkeep-static-functions}
-options to retain these functions and
-allow gcov to properly show their @var{execution_count}.
-
-Some lines of information at the start have @var{line_number} of zero.
-These preamble lines are of the form
-
-@smallexample
--:0:@var{tag}:@var{value}
-@end smallexample
-
-The ordering and number of these preamble lines will be augmented as
-@command{gcov} development progresses --- do not rely on them remaining
-unchanged. Use @var{tag} to locate a particular preamble line.
-
-The additional block information is of the form
-
-@smallexample
-@var{tag} @var{information}
-@end smallexample
-
-The @var{information} is human readable, but designed to be simple
-enough for machine parsing too.
-
-When printing percentages, 0% and 100% are only printed when the values
-are @emph{exactly} 0% and 100% respectively. Other values which would
-conventionally be rounded to 0% or 100% are instead printed as the
-nearest non-boundary value.
-
-When using @command{gcov}, you must first compile your program
-with a special GCC option @samp{--coverage}.
-This tells the compiler to generate additional information needed by
-gcov (basically a flow graph of the program) and also includes
-additional code in the object files for generating the extra profiling
-information needed by gcov. These additional files are placed in the
-directory where the object file is located.
-
-Running the program will cause profile output to be generated. For each
-source file compiled with @option{-fprofile-arcs}, an accompanying
-@file{.gcda} file will be placed in the object file directory.
-
-Running @command{gcov} with your program's source file names as arguments
-will now produce a listing of the code along with frequency of execution
-for each line. For example, if your program is called @file{tmp.cpp}, this
-is what you see when you use the basic @command{gcov} facility:
-
-@smallexample
-$ g++ --coverage tmp.cpp -c
-$ g++ --coverage tmp.o
-$ a.out
-$ gcov tmp.cpp -m
-File 'tmp.cpp'
-Lines executed:92.86% of 14
-Creating 'tmp.cpp.gcov'
-@end smallexample
-
-The file @file{tmp.cpp.gcov} contains output from @command{gcov}.
-Here is a sample:
-
-@smallexample
- -: 0:Source:tmp.cpp
- -: 0:Working directory:/home/gcc/testcase
- -: 0:Graph:tmp.gcno
- -: 0:Data:tmp.gcda
- -: 0:Runs:1
- -: 0:Programs:1
- -: 1:#include <stdio.h>
- -: 2:
- -: 3:template<class T>
- -: 4:class Foo
- -: 5:@{
- -: 6: public:
- 1*: 7: Foo(): b (1000) @{@}
-------------------
-Foo<char>::Foo():
- #####: 7: Foo(): b (1000) @{@}
-------------------
-Foo<int>::Foo():
- 1: 7: Foo(): b (1000) @{@}
-------------------
- 2*: 8: void inc () @{ b++; @}
-------------------
-Foo<char>::inc():
- #####: 8: void inc () @{ b++; @}
-------------------
-Foo<int>::inc():
- 2: 8: void inc () @{ b++; @}
-------------------
- -: 9:
- -: 10: private:
- -: 11: int b;
- -: 12:@};
- -: 13:
- -: 14:template class Foo<int>;
- -: 15:template class Foo<char>;
- -: 16:
- -: 17:int
- 1: 18:main (void)
- -: 19:@{
- -: 20: int i, total;
- 1: 21: Foo<int> counter;
- -: 22:
- 1: 23: counter.inc();
- 1: 24: counter.inc();
- 1: 25: total = 0;
- -: 26:
- 11: 27: for (i = 0; i < 10; i++)
- 10: 28: total += i;
- -: 29:
- 1*: 30: int v = total > 100 ? 1 : 2;
- -: 31:
- 1: 32: if (total != 45)
- #####: 33: printf ("Failure\n");
- -: 34: else
- 1: 35: printf ("Success\n");
- 1: 36: return 0;
- -: 37:@}
-@end smallexample
-
-Note that line 7 is shown in the report multiple times. First occurrence
-presents total number of execution of the line and the next two belong
-to instances of class Foo constructors. As you can also see, line 30 contains
-some unexecuted basic blocks and thus execution count has asterisk symbol.
-
-When you use the @option{-a} option, you will get individual block
-counts, and the output looks like this:
-
-@smallexample
- -: 0:Source:tmp.cpp
- -: 0:Working directory:/home/gcc/testcase
- -: 0:Graph:tmp.gcno
- -: 0:Data:tmp.gcda
- -: 0:Runs:1
- -: 0:Programs:1
- -: 1:#include <stdio.h>
- -: 2:
- -: 3:template<class T>
- -: 4:class Foo
- -: 5:@{
- -: 6: public:
- 1*: 7: Foo(): b (1000) @{@}
-------------------
-Foo<char>::Foo():
- #####: 7: Foo(): b (1000) @{@}
-------------------
-Foo<int>::Foo():
- 1: 7: Foo(): b (1000) @{@}
-------------------
- 2*: 8: void inc () @{ b++; @}
-------------------
-Foo<char>::inc():
- #####: 8: void inc () @{ b++; @}
-------------------
-Foo<int>::inc():
- 2: 8: void inc () @{ b++; @}
-------------------
- -: 9:
- -: 10: private:
- -: 11: int b;
- -: 12:@};
- -: 13:
- -: 14:template class Foo<int>;
- -: 15:template class Foo<char>;
- -: 16:
- -: 17:int
- 1: 18:main (void)
- -: 19:@{
- -: 20: int i, total;
- 1: 21: Foo<int> counter;
- 1: 21-block 0
- -: 22:
- 1: 23: counter.inc();
- 1: 23-block 0
- 1: 24: counter.inc();
- 1: 24-block 0
- 1: 25: total = 0;
- -: 26:
- 11: 27: for (i = 0; i < 10; i++)
- 1: 27-block 0
- 11: 27-block 1
- 10: 28: total += i;
- 10: 28-block 0
- -: 29:
- 1*: 30: int v = total > 100 ? 1 : 2;
- 1: 30-block 0
- %%%%%: 30-block 1
- 1: 30-block 2
- -: 31:
- 1: 32: if (total != 45)
- 1: 32-block 0
- #####: 33: printf ("Failure\n");
- %%%%%: 33-block 0
- -: 34: else
- 1: 35: printf ("Success\n");
- 1: 35-block 0
- 1: 36: return 0;
- 1: 36-block 0
- -: 37:@}
-@end smallexample
-
-In this mode, each basic block is only shown on one line -- the last
-line of the block. A multi-line block will only contribute to the
-execution count of that last line, and other lines will not be shown
-to contain code, unless previous blocks end on those lines.
-The total execution count of a line is shown and subsequent lines show
-the execution counts for individual blocks that end on that line. After each
-block, the branch and call counts of the block will be shown, if the
-@option{-b} option is given.
-
-Because of the way GCC instruments calls, a call count can be shown
-after a line with no individual blocks.
-As you can see, line 33 contains a basic block that was not executed.
-
-@need 450
-When you use the @option{-b} option, your output looks like this:
-
-@smallexample
- -: 0:Source:tmp.cpp
- -: 0:Working directory:/home/gcc/testcase
- -: 0:Graph:tmp.gcno
- -: 0:Data:tmp.gcda
- -: 0:Runs:1
- -: 0:Programs:1
- -: 1:#include <stdio.h>
- -: 2:
- -: 3:template<class T>
- -: 4:class Foo
- -: 5:@{
- -: 6: public:
- 1*: 7: Foo(): b (1000) @{@}
-------------------
-Foo<char>::Foo():
-function Foo<char>::Foo() called 0 returned 0% blocks executed 0%
- #####: 7: Foo(): b (1000) @{@}
-------------------
-Foo<int>::Foo():
-function Foo<int>::Foo() called 1 returned 100% blocks executed 100%
- 1: 7: Foo(): b (1000) @{@}
-------------------
- 2*: 8: void inc () @{ b++; @}
-------------------
-Foo<char>::inc():
-function Foo<char>::inc() called 0 returned 0% blocks executed 0%
- #####: 8: void inc () @{ b++; @}
-------------------
-Foo<int>::inc():
-function Foo<int>::inc() called 2 returned 100% blocks executed 100%
- 2: 8: void inc () @{ b++; @}
-------------------
- -: 9:
- -: 10: private:
- -: 11: int b;
- -: 12:@};
- -: 13:
- -: 14:template class Foo<int>;
- -: 15:template class Foo<char>;
- -: 16:
- -: 17:int
-function main called 1 returned 100% blocks executed 81%
- 1: 18:main (void)
- -: 19:@{
- -: 20: int i, total;
- 1: 21: Foo<int> counter;
-call 0 returned 100%
-branch 1 taken 100% (fallthrough)
-branch 2 taken 0% (throw)
- -: 22:
- 1: 23: counter.inc();
-call 0 returned 100%
-branch 1 taken 100% (fallthrough)
-branch 2 taken 0% (throw)
- 1: 24: counter.inc();
-call 0 returned 100%
-branch 1 taken 100% (fallthrough)
-branch 2 taken 0% (throw)
- 1: 25: total = 0;
- -: 26:
- 11: 27: for (i = 0; i < 10; i++)
-branch 0 taken 91% (fallthrough)
-branch 1 taken 9%
- 10: 28: total += i;
- -: 29:
- 1*: 30: int v = total > 100 ? 1 : 2;
-branch 0 taken 0% (fallthrough)
-branch 1 taken 100%
- -: 31:
- 1: 32: if (total != 45)
-branch 0 taken 0% (fallthrough)
-branch 1 taken 100%
- #####: 33: printf ("Failure\n");
-call 0 never executed
-branch 1 never executed
-branch 2 never executed
- -: 34: else
- 1: 35: printf ("Success\n");
-call 0 returned 100%
-branch 1 taken 100% (fallthrough)
-branch 2 taken 0% (throw)
- 1: 36: return 0;
- -: 37:@}
-@end smallexample
-
-For each function, a line is printed showing how many times the function
-is called, how many times it returns and what percentage of the
-function's blocks were executed.
-
-For each basic block, a line is printed after the last line of the basic
-block describing the branch or call that ends the basic block. There can
-be multiple branches and calls listed for a single source line if there
-are multiple basic blocks that end on that line. In this case, the
-branches and calls are each given a number. There is no simple way to map
-these branches and calls back to source constructs. In general, though,
-the lowest numbered branch or call will correspond to the leftmost construct
-on the source line.
-
-For a branch, if it was executed at least once, then a percentage
-indicating the number of times the branch was taken divided by the
-number of times the branch was executed will be printed. Otherwise, the
-message ``never executed'' is printed.
-
-For a call, if it was executed at least once, then a percentage
-indicating the number of times the call returned divided by the number
-of times the call was executed will be printed. This will usually be
-100%, but may be less for functions that call @code{exit} or @code{longjmp},
-and thus may not return every time they are called.
-
-The execution counts are cumulative. If the example program were
-executed again without removing the @file{.gcda} file, the count for the
-number of times each line in the source was executed would be added to
-the results of the previous run(s). This is potentially useful in
-several ways. For example, it could be used to accumulate data over a
-number of program runs as part of a test verification suite, or to
-provide more accurate long-term information over a large number of
-program runs.
-
-The data in the @file{.gcda} files is saved immediately before the program
-exits. For each source file compiled with @option{-fprofile-arcs}, the
-profiling code first attempts to read in an existing @file{.gcda} file; if
-the file doesn't match the executable (differing number of basic block
-counts) it will ignore the contents of the file. It then adds in the
-new execution counts and finally writes the data to the file.
-
-@node Gcov and Optimization
-@section Using @command{gcov} with GCC Optimization
-
-If you plan to use @command{gcov} to help optimize your code, you must
-first compile your program with a special GCC option
-@samp{--coverage}. Aside from that, you can use any
-other GCC options; but if you want to prove that every single line
-in your program was executed, you should not compile with optimization
-at the same time. On some machines the optimizer can eliminate some
-simple code lines by combining them with other lines. For example, code
-like this:
-
-@smallexample
-if (a != b)
- c = 1;
-else
- c = 0;
-@end smallexample
-
-@noindent
-can be compiled into one instruction on some machines. In this case,
-there is no way for @command{gcov} to calculate separate execution counts
-for each line because there isn't separate code for each line. Hence
-the @command{gcov} output looks like this if you compiled the program with
-optimization:
-
-@smallexample
- 100: 12:if (a != b)
- 100: 13: c = 1;
- 100: 14:else
- 100: 15: c = 0;
-@end smallexample
-
-The output shows that this block of code, combined by optimization,
-executed 100 times. In one sense this result is correct, because there
-was only one instruction representing all four of these lines. However,
-the output does not indicate how many times the result was 0 and how
-many times the result was 1.
-
-Inlineable functions can create unexpected line counts. Line counts are
-shown for the source code of the inlineable function, but what is shown
-depends on where the function is inlined, or if it is not inlined at all.
-
-If the function is not inlined, the compiler must emit an out of line
-copy of the function, in any object file that needs it. If
-@file{fileA.o} and @file{fileB.o} both contain out of line bodies of a
-particular inlineable function, they will also both contain coverage
-counts for that function. When @file{fileA.o} and @file{fileB.o} are
-linked together, the linker will, on many systems, select one of those
-out of line bodies for all calls to that function, and remove or ignore
-the other. Unfortunately, it will not remove the coverage counters for
-the unused function body. Hence when instrumented, all but one use of
-that function will show zero counts.
-
-If the function is inlined in several places, the block structure in
-each location might not be the same. For instance, a condition might
-now be calculable at compile time in some instances. Because the
-coverage of all the uses of the inline function will be shown for the
-same source lines, the line counts themselves might seem inconsistent.
-
-Long-running applications can use the @code{__gcov_reset} and @code{__gcov_dump}
-facilities to restrict profile collection to the program region of
-interest. Calling @code{__gcov_reset(void)} will clear all run-time profile
-counters to zero, and calling @code{__gcov_dump(void)} will cause the profile
-information collected at that point to be dumped to @file{.gcda} output files.
-Instrumented applications use a static destructor with priority 99
-to invoke the @code{__gcov_dump} function. Thus @code{__gcov_dump}
-is executed after all user defined static destructors,
-as well as handlers registered with @code{atexit}.
-
-If an executable loads a dynamic shared object via dlopen functionality,
-@option{-Wl,--dynamic-list-data} is needed to dump all profile data.
-
-Profiling run-time library reports various errors related to profile
-manipulation and profile saving. Errors are printed into standard error output
-or @samp{GCOV_ERROR_FILE} file, if environment variable is used.
-In order to terminate immediately after an errors occurs
-set @samp{GCOV_EXIT_AT_ERROR} environment variable.
-That can help users to find profile clashing which leads
-to a misleading profile.
-
-@c man end
-
-@node Gcov Data Files
-@section Brief Description of @command{gcov} Data Files
-
-@command{gcov} uses two files for profiling. The names of these files
-are derived from the original @emph{object} file by substituting the
-file suffix with either @file{.gcno}, or @file{.gcda}. The files
-contain coverage and profile data stored in a platform-independent format.
-The @file{.gcno} files are placed in the same directory as the object
-file. By default, the @file{.gcda} files are also stored in the same
-directory as the object file, but the GCC @option{-fprofile-dir} option
-may be used to store the @file{.gcda} files in a separate directory.
-
-The @file{.gcno} notes file is generated when the source file is compiled
-with the GCC @option{-ftest-coverage} option. It contains information to
-reconstruct the basic block graphs and assign source line numbers to
-blocks.
-
-The @file{.gcda} count data file is generated when a program containing
-object files built with the GCC @option{-fprofile-arcs} option is executed.
-A separate @file{.gcda} file is created for each object file compiled with
-this option. It contains arc transition counts, value profile counts, and
-some summary information.
-
-It is not recommended to access the coverage files directly.
-Consumers should use the intermediate format that is provided
-by @command{gcov} tool via @option{--json-format} option.
-
-@node Cross-profiling
-@section Data File Relocation to Support Cross-Profiling
-
-Running the program will cause profile output to be generated. For each
-source file compiled with @option{-fprofile-arcs}, an accompanying @file{.gcda}
-file will be placed in the object file directory. That implicitly requires
-running the program on the same system as it was built or having the same
-absolute directory structure on the target system. The program will try
-to create the needed directory structure, if it is not already present.
-
-To support cross-profiling, a program compiled with @option{-fprofile-arcs}
-can relocate the data files based on two environment variables:
-
-@itemize @bullet
-@item
-GCOV_PREFIX contains the prefix to add to the absolute paths
-in the object file. Prefix can be absolute, or relative. The
-default is no prefix.
-
-@item
-GCOV_PREFIX_STRIP indicates the how many initial directory names to strip off
-the hardwired absolute paths. Default value is 0.
-
-@emph{Note:} If GCOV_PREFIX_STRIP is set without GCOV_PREFIX is undefined,
- then a relative path is made out of the hardwired absolute paths.
-@end itemize
-
-For example, if the object file @file{/user/build/foo.o} was built with
-@option{-fprofile-arcs}, the final executable will try to create the data file
-@file{/user/build/foo.gcda} when running on the target system. This will
-fail if the corresponding directory does not exist and it is unable to create
-it. This can be overcome by, for example, setting the environment as
-@samp{GCOV_PREFIX=/target/run} and @samp{GCOV_PREFIX_STRIP=1}. Such a
-setting will name the data file @file{/target/run/build/foo.gcda}.
-
-You must move the data files to the expected directory tree in order to
-use them for profile directed optimizations (@option{-fprofile-use}), or to
-use the @command{gcov} tool.
-
-@node Freestanding Environments
-@section Profiling and Test Coverage in Freestanding Environments
-
-In case your application runs in a hosted environment such as GNU/Linux, then
-this section is likely not relevant to you. This section is intended for
-application developers targeting freestanding environments (for example
-embedded systems) with limited resources. In particular, systems or test cases
-which do not support constructors/destructors or the C library file I/O. In
-this section, the @dfn{target system} runs your application instrumented for
-profiling or test coverage. You develop and analyze your application on the
-@dfn{host system}. We now provide an overview how profiling and test coverage
-can be obtained in this scenario followed by a tutorial which can be exercised
-on the host system. Finally, some system initialization caveats are listed.
-
-@subsection Overview
-
-For an application instrumented for profiling or test coverage, the compiler
-generates some global data structures which are updated by instrumentation code
-while the application runs. These data structures are called the @dfn{gcov
-information}. Normally, when the application exits, the gcov information is
-stored to @file{.gcda} files. There is one file per translation unit
-instrumented for profiling or test coverage. The function
-@code{__gcov_exit()}, which stores the gcov information to a file, is called by
-a global destructor function for each translation unit instrumented for
-profiling or test coverage. It runs at process exit. In a global constructor
-function, the @code{__gcov_init()} function is called to register the gcov
-information of a translation unit in a global list. In some situations, this
-procedure does not work. Firstly, if you want to profile the global
-constructor or exit processing of an operating system, the compiler generated
-functions may conflict with the test objectives. Secondly, you may want to
-test early parts of the system initialization or abnormal program behaviour
-which do not allow a global constructor or exit processing. Thirdly, you need
-a filesystem to store the files.
-
-The @option{-fprofile-info-section} GCC option enables you to use profiling and
-test coverage in freestanding environments. This option disables the use of
-global constructors and destructors for the gcov information. Instead, a
-pointer to the gcov information is stored in a special linker input section for
-each translation unit which is compiled with this option. By default, the
-section name is @code{.gcov_info}. The gcov information is statically
-initialized. The pointers to the gcov information from all translation units
-of an executable can be collected by the linker in a contiguous memory block.
-For the GNU linker, the below linker script output section definition can be
-used to achieve this:
-
-@smallexample
- .gcov_info :
- @{
- PROVIDE (__gcov_info_start = .);
- KEEP (*(.gcov_info))
- PROVIDE (__gcov_info_end = .);
- @}
-@end smallexample
-
-The linker will provide two global symbols, @code{__gcov_info_start} and
-@code{__gcov_info_end}, which define the start and end of the array of pointers
-to gcov information blocks, respectively. The @code{KEEP ()} directive is
-required to prevent a garbage collection of the pointers. They are not
-directly referenced by anything in the executable. The section may be placed
-in a read-only memory area.
-
-In order to transfer the profiling and test coverage data from the target to
-the host system, the application has to provide a function to produce a
-reliable in order byte stream from the target to the host. The byte stream may
-be compressed and encoded using error detection and correction codes to meet
-application-specific requirements. The GCC provided @file{libgcov} target
-library provides two functions, @code{__gcov_info_to_gcda()} and
-@code{__gcov_filename_to_gcfn()}, to generate a byte stream from a gcov
-information bock. The functions are declared in @code{#include <gcov.h>}. The
-byte stream can be deserialized by the @command{merge-stream} subcommand of the
-@command{gcov-tool} to create or update @file{.gcda} files in the host
-filesystem for the instrumented application.
-
-@subsection Tutorial
-
-This tutorial should be exercised on the host system. We will build a program
-instrumented for test coverage. The program runs an application and dumps the
-gcov information to @file{stderr} encoded as a printable character stream. The
-application simply decodes such character streams from @file{stdin} and writes
-the decoded character stream to @file{stdout} (warning: this is binary data).
-The decoded character stream is consumed by the @command{merge-stream}
-subcommand of the @command{gcov-tool} to create or update the @file{.gcda}
-files.
-
-To get started, create an empty directory. Change into the new directory.
-Then you will create the following three files in this directory
-
-@enumerate
-@item
-@file{app.h} - a header file included by @file{app.c} and @file{main.c},
-
-@item
-@file{app.c} - a source file which contains an example application, and
-
-@item
-@file{main.c} - a source file which contains the program main function and code
-to dump the gcov information.
-@end enumerate
-
-Firstly, create the header file @file{app.h} with the following content:
-
-@smallexample
-static const unsigned char a = 'a';
-
-static inline unsigned char *
-encode (unsigned char c, unsigned char buf[2])
-@{
- buf[0] = c % 16 + a;
- buf[1] = (c / 16) % 16 + a;
- return buf;
-@}
-
-extern void application (void);
-@end smallexample
-
-Secondly, create the source file @file{app.c} with the following content:
-
-@smallexample
-#include "app.h"
-
-#include <stdio.h>
-
-/* The application reads a character stream encoded by encode() from stdin,
- decodes it, and writes the decoded characters to stdout. Characters other
- than the 16 characters 'a' to 'p' are ignored. */
-
-static int can_decode (unsigned char c)
-@{
- return (unsigned char)(c - a) < 16;
-@}
-
-void
-application (void)
-@{
- int first = 1;
- int i;
- unsigned char c;
-
- while ((i = fgetc (stdin)) != EOF)
- @{
- unsigned char x = (unsigned char)i;
-
- if (can_decode (x))
- @{
- if (first)
- c = x - a;
- else
- fputc (c + 16 * (x - a), stdout);
- first = !first;
- @}
- else
- first = 1;
- @}
-@}
-@end smallexample
-
-Thirdly, create the source file @file{main.c} with the following content:
-
-@smallexample
-#include "app.h"
-
-#include <gcov.h>
-#include <stdio.h>
-#include <stdlib.h>
-
-/* The start and end symbols are provided by the linker script. We use the
- array notation to avoid issues with a potential small-data area. */
-
-extern const struct gcov_info *const __gcov_info_start[];
-extern const struct gcov_info *const __gcov_info_end[];
-
-/* This function shall produce a reliable in order byte stream to transfer the
- gcov information from the target to the host system. */
-
-static void
-dump (const void *d, unsigned n, void *arg)
-@{
- (void)arg;
- const unsigned char *c = d;
- unsigned char buf[2];
-
- for (unsigned i = 0; i < n; ++i)
- fwrite (encode (c[i], buf), sizeof (buf), 1, stderr);
-@}
-
-/* The filename is serialized to a gcfn data stream by the
- __gcov_filename_to_gcfn() function. The gcfn data is used by the
- "merge-stream" subcommand of the "gcov-tool" to figure out the filename
- associated with the gcov information. */
-
-static void
-filename (const char *f, void *arg)
-@{
- __gcov_filename_to_gcfn (f, dump, arg);
-@}
-
-/* The __gcov_info_to_gcda() function may have to allocate memory under
- certain conditions. Simply try it out if it is needed for your application
- or not. */
-
-static void *
-allocate (unsigned length, void *arg)
-@{
- (void)arg;
- return malloc (length);
-@}
-
-/* Dump the gcov information of all translation units. */
-
-static void
-dump_gcov_info (void)
-@{
- const struct gcov_info *const *info = __gcov_info_start;
- const struct gcov_info *const *end = __gcov_info_end;
-
- /* Obfuscate variable to prevent compiler optimizations. */
- __asm__ ("" : "+r" (info));
-
- while (info != end)
- @{
- void *arg = NULL;
- __gcov_info_to_gcda (*info, filename, dump, allocate, arg);
- fputc ('\n', stderr);
- ++info;
- @}
-@}
-
-/* The main() function just runs the application and then dumps the gcov
- information to stderr. */
-
-int
-main (void)
-@{
- application ();
- dump_gcov_info ();
- return 0;
-@}
-@end smallexample
-
-If we compile @file{app.c} with test coverage and no extra profiling options,
-then a global constructor (@code{_sub_I_00100_0} here, it may have a different
-name in your environment) and destructor (@code{_sub_D_00100_1}) is used to
-register and dump the gcov information, respectively. We also see undefined
-references to @code{__gcov_init} and @code{__gcov_exit}:
-
-@smallexample
-$ gcc --coverage -c app.c
-$ nm app.o
-0000000000000000 r a
-0000000000000030 T application
-0000000000000000 t can_decode
- U fgetc
- U fputc
-0000000000000000 b __gcov0.application
-0000000000000038 b __gcov0.can_decode
-0000000000000000 d __gcov_.application
-00000000000000c0 d __gcov_.can_decode
- U __gcov_exit
- U __gcov_init
- U __gcov_merge_add
- U stdin
- U stdout
-0000000000000161 t _sub_D_00100_1
-0000000000000151 t _sub_I_00100_0
-@end smallexample
-
-Compile @file{app.c} and @file{main.c} with test coverage and
-@option{-fprofile-info-section}. Now, a read-only pointer size object is
-present in the @code{.gcov_info} section and there are no undefined references
-to @code{__gcov_init} and @code{__gcov_exit}:
-
-@smallexample
-$ gcc --coverage -fprofile-info-section -c main.c
-$ gcc --coverage -fprofile-info-section -c app.c
-$ objdump -h app.o
-
-app.o: file format elf64-x86-64
-
-Sections:
-Idx Name Size VMA LMA File off Algn
- 0 .text 00000151 0000000000000000 0000000000000000 00000040 2**0
- CONTENTS, ALLOC, LOAD, RELOC, READONLY, CODE
- 1 .data 00000100 0000000000000000 0000000000000000 000001a0 2**5
- CONTENTS, ALLOC, LOAD, RELOC, DATA
- 2 .bss 00000040 0000000000000000 0000000000000000 000002a0 2**5
- ALLOC
- 3 .rodata 0000003c 0000000000000000 0000000000000000 000002a0 2**3
- CONTENTS, ALLOC, LOAD, READONLY, DATA
- 4 .gcov_info 00000008 0000000000000000 0000000000000000 000002e0 2**3
- CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA
- 5 .comment 0000004e 0000000000000000 0000000000000000 000002e8 2**0
- CONTENTS, READONLY
- 6 .note.GNU-stack 00000000 0000000000000000 0000000000000000 00000336 2**0
- CONTENTS, READONLY
- 7 .eh_frame 00000058 0000000000000000 0000000000000000 00000338 2**3
- CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA
-@end smallexample
-
-We have to customize the program link procedure so that all the
-@code{.gcov_info} linker input sections are placed in a contiguous memory block
-with a begin and end symbol. Firstly, get the default linker script using the
-following commands (we assume a GNU linker):
-
-@smallexample
-$ ld --verbose | sed '1,/^===/d' | sed '/^===/d' > linkcmds
-@end smallexample
-
-Secondly, open the file @file{linkcmds} with a text editor and place the linker
-output section definition from the overview after the @code{.rodata} section
-definition. Link the program executable using the customized linker script:
-
-@smallexample
-$ gcc --coverage main.o app.o -T linkcmds -Wl,-Map,app.map
-@end smallexample
-
-In the linker map file @file{app.map}, we see that the linker placed the
-read-only pointer size objects of our objects files @file{main.o} and
-@file{app.o} into a contiguous memory block and provided the symbols
-@code{__gcov_info_start} and @code{__gcov_info_end}:
-
-@smallexample
-$ grep -C 1 "\.gcov_info" app.map
-
-.gcov_info 0x0000000000403ac0 0x10
- 0x0000000000403ac0 PROVIDE (__gcov_info_start = .)
- *(.gcov_info)
- .gcov_info 0x0000000000403ac0 0x8 main.o
- .gcov_info 0x0000000000403ac8 0x8 app.o
- 0x0000000000403ad0 PROVIDE (__gcov_info_end = .)
-@end smallexample
-
-Make sure no @file{.gcda} files are present. Run the program with nothing to
-decode and dump @file{stderr} to the file @file{gcda-0.txt} (first run). Run
-the program to decode @file{gcda-0.txt} and send it to the @command{gcov-tool}
-using the @command{merge-stream} subcommand to create the @file{.gcda} files
-(second run). Run @command{gcov} to produce a report for @file{app.c}. We see
-that the first run with nothing to decode results in a partially covered
-application:
-
-@smallexample
-$ rm -f app.gcda main.gcda
-$ echo "" | ./a.out 2>gcda-0.txt
-$ ./a.out <gcda-0.txt 2>gcda-1.txt | gcov-tool merge-stream
-$ gcov -bc app.c
-File 'app.c'
-Lines executed:69.23% of 13
-Branches executed:66.67% of 6
-Taken at least once:50.00% of 6
-Calls executed:66.67% of 3
-Creating 'app.c.gcov'
-
-Lines executed:69.23% of 13
-@end smallexample
-
-Run the program to decode @file{gcda-1.txt} and send it to the
-@command{gcov-tool} using the @command{merge-stream} subcommand to update the
-@file{.gcda} files. Run @command{gcov} to produce a report for @file{app.c}.
-Since the second run decoded the gcov information of the first run, we have now
-a fully covered application:
-
-@smallexample
-$ ./a.out <gcda-1.txt 2>gcda-2.txt | gcov-tool merge-stream
-$ gcov -bc app.c
-File 'app.c'
-Lines executed:100.00% of 13
-Branches executed:100.00% of 6
-Taken at least once:100.00% of 6
-Calls executed:100.00% of 3
-Creating 'app.c.gcov'
-
-Lines executed:100.00% of 13
-@end smallexample
-
-@subsection System Initialization Caveats
-
-The gcov information of a translation unit consists of several global data
-structures. For example, the instrumented code may update program flow graph
-edge counters in a zero-initialized data structure. It is safe to run
-instrumented code before the zero-initialized data is cleared to zero. The
-coverage information obtained before the zero-initialized data is cleared to
-zero is unusable. Dumping the gcov information using
-@code{__gcov_info_to_gcda()} before the zero-initialized data is cleared to
-zero or the initialized data is loaded, is undefined behaviour. Clearing the
-zero-initialized data to zero through a function instrumented for profiling or
-test coverage is undefined behaviour, since it may produce inconsistent program
-flow graph edge counters for example.
+++ /dev/null
-@c Copyright (C) 2004-2022 Free Software Foundation, Inc.
-@c This is part of the GCC manual.
-@c For copying conditions, see the file gcc.texi.
-
-@c ---------------------------------------------------------------------
-@c GENERIC
-@c ---------------------------------------------------------------------
-
-@node GENERIC
-@chapter GENERIC
-@cindex GENERIC
-
-The purpose of GENERIC is simply to provide a
-language-independent way of representing an entire function in
-trees. To this end, it was necessary to add a few new tree codes
-to the back end, but almost everything was already there. If you
-can express it with the codes in @code{gcc/tree.def}, it's
-GENERIC@.
-
-Early on, there was a great deal of debate about how to think
-about statements in a tree IL@. In GENERIC, a statement is
-defined as any expression whose value, if any, is ignored. A
-statement will always have @code{TREE_SIDE_EFFECTS} set (or it
-will be discarded), but a non-statement expression may also have
-side effects. A @code{CALL_EXPR}, for instance.
-
-It would be possible for some local optimizations to work on the
-GENERIC form of a function; indeed, the adapted tree inliner
-works fine on GENERIC, but the current compiler performs inlining
-after lowering to GIMPLE (a restricted form described in the next
-section). Indeed, currently the frontends perform this lowering
-before handing off to @code{tree_rest_of_compilation}, but this
-seems inelegant.
-
-@menu
-* Deficiencies:: Topics not yet covered in this document.
-* Tree overview:: All about @code{tree}s.
-* Types:: Fundamental and aggregate types.
-* Declarations:: Type declarations and variables.
-* Attributes:: Declaration and type attributes.
-* Expressions: Expression trees. Operating on data.
-* Statements:: Control flow and related trees.
-* Functions:: Function bodies, linkage, and other aspects.
-* Language-dependent trees:: Topics and trees specific to language front ends.
-* C and C++ Trees:: Trees specific to C and C++.
-@end menu
-
-@c ---------------------------------------------------------------------
-@c Deficiencies
-@c ---------------------------------------------------------------------
-
-@node Deficiencies
-@section Deficiencies
-
-@c The spelling of "incomplet" and "incorrekt" below is intentional.
-There are many places in which this document is incomplet and incorrekt.
-It is, as of yet, only @emph{preliminary} documentation.
-
-@c ---------------------------------------------------------------------
-@c Overview
-@c ---------------------------------------------------------------------
-
-@node Tree overview
-@section Overview
-@cindex tree
-@findex TREE_CODE
-
-The central data structure used by the internal representation is the
-@code{tree}. These nodes, while all of the C type @code{tree}, are of
-many varieties. A @code{tree} is a pointer type, but the object to
-which it points may be of a variety of types. From this point forward,
-we will refer to trees in ordinary type, rather than in @code{this
-font}, except when talking about the actual C type @code{tree}.
-
-You can tell what kind of node a particular tree is by using the
-@code{TREE_CODE} macro. Many, many macros take trees as input and
-return trees as output. However, most macros require a certain kind of
-tree node as input. In other words, there is a type-system for trees,
-but it is not reflected in the C type-system.
-
-For safety, it is useful to configure GCC with @option{--enable-checking}.
-Although this results in a significant performance penalty (since all
-tree types are checked at run-time), and is therefore inappropriate in a
-release version, it is extremely helpful during the development process.
-
-Many macros behave as predicates. Many, although not all, of these
-predicates end in @samp{_P}. Do not rely on the result type of these
-macros being of any particular type. You may, however, rely on the fact
-that the type can be compared to @code{0}, so that statements like
-@smallexample
-if (TEST_P (t) && !TEST_P (y))
- x = 1;
-@end smallexample
-@noindent
-and
-@smallexample
-int i = (TEST_P (t) != 0);
-@end smallexample
-@noindent
-are legal. Macros that return @code{int} values now may be changed to
-return @code{tree} values, or other pointers in the future. Even those
-that continue to return @code{int} may return multiple nonzero codes
-where previously they returned only zero and one. Therefore, you should
-not write code like
-@smallexample
-if (TEST_P (t) == 1)
-@end smallexample
-@noindent
-as this code is not guaranteed to work correctly in the future.
-
-You should not take the address of values returned by the macros or
-functions described here. In particular, no guarantee is given that the
-values are lvalues.
-
-In general, the names of macros are all in uppercase, while the names of
-functions are entirely in lowercase. There are rare exceptions to this
-rule. You should assume that any macro or function whose name is made
-up entirely of uppercase letters may evaluate its arguments more than
-once. You may assume that a macro or function whose name is made up
-entirely of lowercase letters will evaluate its arguments only once.
-
-The @code{error_mark_node} is a special tree. Its tree code is
-@code{ERROR_MARK}, but since there is only ever one node with that code,
-the usual practice is to compare the tree against
-@code{error_mark_node}. (This test is just a test for pointer
-equality.) If an error has occurred during front-end processing the
-flag @code{errorcount} will be set. If the front end has encountered
-code it cannot handle, it will issue a message to the user and set
-@code{sorrycount}. When these flags are set, any macro or function
-which normally returns a tree of a particular kind may instead return
-the @code{error_mark_node}. Thus, if you intend to do any processing of
-erroneous code, you must be prepared to deal with the
-@code{error_mark_node}.
-
-Occasionally, a particular tree slot (like an operand to an expression,
-or a particular field in a declaration) will be referred to as
-``reserved for the back end''. These slots are used to store RTL when
-the tree is converted to RTL for use by the GCC back end. However, if
-that process is not taking place (e.g., if the front end is being hooked
-up to an intelligent editor), then those slots may be used by the
-back end presently in use.
-
-If you encounter situations that do not match this documentation, such
-as tree nodes of types not mentioned here, or macros documented to
-return entities of a particular kind that instead return entities of
-some different kind, you have found a bug, either in the front end or in
-the documentation. Please report these bugs as you would any other
-bug.
-
-@menu
-* Macros and Functions::Macros and functions that can be used with all trees.
-* Identifiers:: The names of things.
-* Containers:: Lists and vectors.
-@end menu
-
-@c ---------------------------------------------------------------------
-@c Trees
-@c ---------------------------------------------------------------------
-
-@node Macros and Functions
-@subsection Trees
-@cindex tree
-@findex TREE_CHAIN
-@findex TREE_TYPE
-
-All GENERIC trees have two fields in common. First, @code{TREE_CHAIN}
-is a pointer that can be used as a singly-linked list to other trees.
-The other is @code{TREE_TYPE}. Many trees store the type of an
-expression or declaration in this field.
-
-These are some other functions for handling trees:
-
-@ftable @code
-
-@item tree_size
-Return the number of bytes a tree takes.
-
-@item build0
-@itemx build1
-@itemx build2
-@itemx build3
-@itemx build4
-@itemx build5
-@itemx build6
-
-These functions build a tree and supply values to put in each
-parameter. The basic signature is @samp{@w{code, type, [operands]}}.
-@code{code} is the @code{TREE_CODE}, and @code{type} is a tree
-representing the @code{TREE_TYPE}. These are followed by the
-operands, each of which is also a tree.
-
-@end ftable
-
-
-@c ---------------------------------------------------------------------
-@c Identifiers
-@c ---------------------------------------------------------------------
-
-@node Identifiers
-@subsection Identifiers
-@cindex identifier
-@cindex name
-@tindex IDENTIFIER_NODE
-
-An @code{IDENTIFIER_NODE} represents a slightly more general concept
-than the standard C or C++ concept of identifier. In particular, an
-@code{IDENTIFIER_NODE} may contain a @samp{$}, or other extraordinary
-characters.
-
-There are never two distinct @code{IDENTIFIER_NODE}s representing the
-same identifier. Therefore, you may use pointer equality to compare
-@code{IDENTIFIER_NODE}s, rather than using a routine like
-@code{strcmp}. Use @code{get_identifier} to obtain the unique
-@code{IDENTIFIER_NODE} for a supplied string.
-
-You can use the following macros to access identifiers:
-@ftable @code
-@item IDENTIFIER_POINTER
-The string represented by the identifier, represented as a
-@code{char*}. This string is always @code{NUL}-terminated, and contains
-no embedded @code{NUL} characters.
-
-@item IDENTIFIER_LENGTH
-The length of the string returned by @code{IDENTIFIER_POINTER}, not
-including the trailing @code{NUL}. This value of
-@code{IDENTIFIER_LENGTH (x)} is always the same as @code{strlen
-(IDENTIFIER_POINTER (x))}.
-
-@item IDENTIFIER_OPNAME_P
-This predicate holds if the identifier represents the name of an
-overloaded operator. In this case, you should not depend on the
-contents of either the @code{IDENTIFIER_POINTER} or the
-@code{IDENTIFIER_LENGTH}.
-
-@item IDENTIFIER_TYPENAME_P
-This predicate holds if the identifier represents the name of a
-user-defined conversion operator. In this case, the @code{TREE_TYPE} of
-the @code{IDENTIFIER_NODE} holds the type to which the conversion
-operator converts.
-
-@end ftable
-
-@c ---------------------------------------------------------------------
-@c Containers
-@c ---------------------------------------------------------------------
-
-@node Containers
-@subsection Containers
-@cindex container
-@cindex list
-@cindex vector
-@tindex TREE_LIST
-@tindex TREE_VEC
-@findex TREE_PURPOSE
-@findex TREE_VALUE
-@findex TREE_VEC_LENGTH
-@findex TREE_VEC_ELT
-
-Two common container data structures can be represented directly with
-tree nodes. A @code{TREE_LIST} is a singly linked list containing two
-trees per node. These are the @code{TREE_PURPOSE} and @code{TREE_VALUE}
-of each node. (Often, the @code{TREE_PURPOSE} contains some kind of
-tag, or additional information, while the @code{TREE_VALUE} contains the
-majority of the payload. In other cases, the @code{TREE_PURPOSE} is
-simply @code{NULL_TREE}, while in still others both the
-@code{TREE_PURPOSE} and @code{TREE_VALUE} are of equal stature.) Given
-one @code{TREE_LIST} node, the next node is found by following the
-@code{TREE_CHAIN}. If the @code{TREE_CHAIN} is @code{NULL_TREE}, then
-you have reached the end of the list.
-
-A @code{TREE_VEC} is a simple vector. The @code{TREE_VEC_LENGTH} is an
-integer (not a tree) giving the number of nodes in the vector. The
-nodes themselves are accessed using the @code{TREE_VEC_ELT} macro, which
-takes two arguments. The first is the @code{TREE_VEC} in question; the
-second is an integer indicating which element in the vector is desired.
-The elements are indexed from zero.
-
-@c ---------------------------------------------------------------------
-@c Types
-@c ---------------------------------------------------------------------
-
-@node Types
-@section Types
-@cindex type
-@cindex pointer
-@cindex reference
-@cindex fundamental type
-@cindex array
-@tindex VOID_TYPE
-@tindex INTEGER_TYPE
-@tindex TYPE_MIN_VALUE
-@tindex TYPE_MAX_VALUE
-@tindex REAL_TYPE
-@tindex FIXED_POINT_TYPE
-@tindex COMPLEX_TYPE
-@tindex ENUMERAL_TYPE
-@tindex BOOLEAN_TYPE
-@tindex POINTER_TYPE
-@tindex REFERENCE_TYPE
-@tindex FUNCTION_TYPE
-@tindex METHOD_TYPE
-@tindex ARRAY_TYPE
-@tindex RECORD_TYPE
-@tindex UNION_TYPE
-@tindex OPAQUE_TYPE
-@tindex UNKNOWN_TYPE
-@tindex OFFSET_TYPE
-@findex TYPE_UNQUALIFIED
-@findex TYPE_QUAL_CONST
-@findex TYPE_QUAL_VOLATILE
-@findex TYPE_QUAL_RESTRICT
-@findex TYPE_MAIN_VARIANT
-@cindex qualified type
-@findex TYPE_SIZE
-@findex TYPE_ALIGN
-@findex TYPE_PRECISION
-@findex TYPE_ARG_TYPES
-@findex TYPE_METHOD_BASETYPE
-@findex TYPE_OFFSET_BASETYPE
-@findex TREE_TYPE
-@findex TYPE_CONTEXT
-@findex TYPE_NAME
-@findex TYPENAME_TYPE_FULLNAME
-@findex TYPE_FIELDS
-@findex TYPE_CANONICAL
-@findex TYPE_STRUCTURAL_EQUALITY_P
-@findex SET_TYPE_STRUCTURAL_EQUALITY
-
-All types have corresponding tree nodes. However, you should not assume
-that there is exactly one tree node corresponding to each type. There
-are often multiple nodes corresponding to the same type.
-
-For the most part, different kinds of types have different tree codes.
-(For example, pointer types use a @code{POINTER_TYPE} code while arrays
-use an @code{ARRAY_TYPE} code.) However, pointers to member functions
-use the @code{RECORD_TYPE} code. Therefore, when writing a
-@code{switch} statement that depends on the code associated with a
-particular type, you should take care to handle pointers to member
-functions under the @code{RECORD_TYPE} case label.
-
-The following functions and macros deal with cv-qualification of types:
-@ftable @code
-@item TYPE_MAIN_VARIANT
-This macro returns the unqualified version of a type. It may be applied
-to an unqualified type, but it is not always the identity function in
-that case.
-@end ftable
-
-A few other macros and functions are usable with all types:
-@ftable @code
-@item TYPE_SIZE
-The number of bits required to represent the type, represented as an
-@code{INTEGER_CST}. For an incomplete type, @code{TYPE_SIZE} will be
-@code{NULL_TREE}.
-
-@item TYPE_ALIGN
-The alignment of the type, in bits, represented as an @code{int}.
-
-@item TYPE_NAME
-This macro returns a declaration (in the form of a @code{TYPE_DECL}) for
-the type. (Note this macro does @emph{not} return an
-@code{IDENTIFIER_NODE}, as you might expect, given its name!) You can
-look at the @code{DECL_NAME} of the @code{TYPE_DECL} to obtain the
-actual name of the type. The @code{TYPE_NAME} will be @code{NULL_TREE}
-for a type that is not a built-in type, the result of a typedef, or a
-named class type.
-
-@item TYPE_CANONICAL
-This macro returns the ``canonical'' type for the given type
-node. Canonical types are used to improve performance in the C++ and
-Objective-C++ front ends by allowing efficient comparison between two
-type nodes in @code{same_type_p}: if the @code{TYPE_CANONICAL} values
-of the types are equal, the types are equivalent; otherwise, the types
-are not equivalent. The notion of equivalence for canonical types is
-the same as the notion of type equivalence in the language itself. For
-instance,
-
-When @code{TYPE_CANONICAL} is @code{NULL_TREE}, there is no canonical
-type for the given type node. In this case, comparison between this
-type and any other type requires the compiler to perform a deep,
-``structural'' comparison to see if the two type nodes have the same
-form and properties.
-
-The canonical type for a node is always the most fundamental type in
-the equivalence class of types. For instance, @code{int} is its own
-canonical type. A typedef @code{I} of @code{int} will have @code{int}
-as its canonical type. Similarly, @code{I*}@ and a typedef @code{IP}@
-(defined to @code{I*}) will has @code{int*} as their canonical
-type. When building a new type node, be sure to set
-@code{TYPE_CANONICAL} to the appropriate canonical type. If the new
-type is a compound type (built from other types), and any of those
-other types require structural equality, use
-@code{SET_TYPE_STRUCTURAL_EQUALITY} to ensure that the new type also
-requires structural equality. Finally, if for some reason you cannot
-guarantee that @code{TYPE_CANONICAL} will point to the canonical type,
-use @code{SET_TYPE_STRUCTURAL_EQUALITY} to make sure that the new
-type--and any type constructed based on it--requires structural
-equality. If you suspect that the canonical type system is
-miscomparing types, pass @code{--param verify-canonical-types=1} to
-the compiler or configure with @code{--enable-checking} to force the
-compiler to verify its canonical-type comparisons against the
-structural comparisons; the compiler will then print any warnings if
-the canonical types miscompare.
-
-@item TYPE_STRUCTURAL_EQUALITY_P
-This predicate holds when the node requires structural equality
-checks, e.g., when @code{TYPE_CANONICAL} is @code{NULL_TREE}.
-
-@item SET_TYPE_STRUCTURAL_EQUALITY
-This macro states that the type node it is given requires structural
-equality checks, e.g., it sets @code{TYPE_CANONICAL} to
-@code{NULL_TREE}.
-
-@item same_type_p
-This predicate takes two types as input, and holds if they are the same
-type. For example, if one type is a @code{typedef} for the other, or
-both are @code{typedef}s for the same type. This predicate also holds if
-the two trees given as input are simply copies of one another; i.e.,
-there is no difference between them at the source level, but, for
-whatever reason, a duplicate has been made in the representation. You
-should never use @code{==} (pointer equality) to compare types; always
-use @code{same_type_p} instead.
-@end ftable
-
-Detailed below are the various kinds of types, and the macros that can
-be used to access them. Although other kinds of types are used
-elsewhere in G++, the types described here are the only ones that you
-will encounter while examining the intermediate representation.
-
-@table @code
-@item VOID_TYPE
-Used to represent the @code{void} type.
-
-@item INTEGER_TYPE
-Used to represent the various integral types, including @code{char},
-@code{short}, @code{int}, @code{long}, and @code{long long}. This code
-is not used for enumeration types, nor for the @code{bool} type.
-The @code{TYPE_PRECISION} is the number of bits used in
-the representation, represented as an @code{unsigned int}. (Note that
-in the general case this is not the same value as @code{TYPE_SIZE};
-suppose that there were a 24-bit integer type, but that alignment
-requirements for the ABI required 32-bit alignment. Then,
-@code{TYPE_SIZE} would be an @code{INTEGER_CST} for 32, while
-@code{TYPE_PRECISION} would be 24.) The integer type is unsigned if
-@code{TYPE_UNSIGNED} holds; otherwise, it is signed.
-
-The @code{TYPE_MIN_VALUE} is an @code{INTEGER_CST} for the smallest
-integer that may be represented by this type. Similarly, the
-@code{TYPE_MAX_VALUE} is an @code{INTEGER_CST} for the largest integer
-that may be represented by this type.
-
-@item REAL_TYPE
-Used to represent the @code{float}, @code{double}, and @code{long
-double} types. The number of bits in the floating-point representation
-is given by @code{TYPE_PRECISION}, as in the @code{INTEGER_TYPE} case.
-
-@item FIXED_POINT_TYPE
-Used to represent the @code{short _Fract}, @code{_Fract}, @code{long
-_Fract}, @code{long long _Fract}, @code{short _Accum}, @code{_Accum},
-@code{long _Accum}, and @code{long long _Accum} types. The number of bits
-in the fixed-point representation is given by @code{TYPE_PRECISION},
-as in the @code{INTEGER_TYPE} case. There may be padding bits, fractional
-bits and integral bits. The number of fractional bits is given by
-@code{TYPE_FBIT}, and the number of integral bits is given by @code{TYPE_IBIT}.
-The fixed-point type is unsigned if @code{TYPE_UNSIGNED} holds; otherwise,
-it is signed.
-The fixed-point type is saturating if @code{TYPE_SATURATING} holds; otherwise,
-it is not saturating.
-
-@item COMPLEX_TYPE
-Used to represent GCC built-in @code{__complex__} data types. The
-@code{TREE_TYPE} is the type of the real and imaginary parts.
-
-@item ENUMERAL_TYPE
-Used to represent an enumeration type. The @code{TYPE_PRECISION} gives
-(as an @code{int}), the number of bits used to represent the type. If
-there are no negative enumeration constants, @code{TYPE_UNSIGNED} will
-hold. The minimum and maximum enumeration constants may be obtained
-with @code{TYPE_MIN_VALUE} and @code{TYPE_MAX_VALUE}, respectively; each
-of these macros returns an @code{INTEGER_CST}.
-
-The actual enumeration constants themselves may be obtained by looking
-at the @code{TYPE_VALUES}. This macro will return a @code{TREE_LIST},
-containing the constants. The @code{TREE_PURPOSE} of each node will be
-an @code{IDENTIFIER_NODE} giving the name of the constant; the
-@code{TREE_VALUE} will be an @code{INTEGER_CST} giving the value
-assigned to that constant. These constants will appear in the order in
-which they were declared. The @code{TREE_TYPE} of each of these
-constants will be the type of enumeration type itself.
-
-@item OPAQUE_TYPE
-Used for things that have a @code{MODE_OPAQUE} mode class in the
-backend. Opaque types have a size and precision, and can be held in
-memory or registers. They are used when we do not want the compiler to
-make assumptions about the availability of other operations as would
-happen with integer types.
-
-@item BOOLEAN_TYPE
-Used to represent the @code{bool} type.
-
-@item POINTER_TYPE
-Used to represent pointer types, and pointer to data member types. The
-@code{TREE_TYPE} gives the type to which this type points.
-
-@item REFERENCE_TYPE
-Used to represent reference types. The @code{TREE_TYPE} gives the type
-to which this type refers.
-
-@item FUNCTION_TYPE
-Used to represent the type of non-member functions and of static member
-functions. The @code{TREE_TYPE} gives the return type of the function.
-The @code{TYPE_ARG_TYPES} are a @code{TREE_LIST} of the argument types.
-The @code{TREE_VALUE} of each node in this list is the type of the
-corresponding argument; the @code{TREE_PURPOSE} is an expression for the
-default argument value, if any. If the last node in the list is
-@code{void_list_node} (a @code{TREE_LIST} node whose @code{TREE_VALUE}
-is the @code{void_type_node}), then functions of this type do not take
-variable arguments. Otherwise, they do take a variable number of
-arguments.
-
-Note that in C (but not in C++) a function declared like @code{void f()}
-is an unprototyped function taking a variable number of arguments; the
-@code{TYPE_ARG_TYPES} of such a function will be @code{NULL}.
-
-@item METHOD_TYPE
-Used to represent the type of a non-static member function. Like a
-@code{FUNCTION_TYPE}, the return type is given by the @code{TREE_TYPE}.
-The type of @code{*this}, i.e., the class of which functions of this
-type are a member, is given by the @code{TYPE_METHOD_BASETYPE}. The
-@code{TYPE_ARG_TYPES} is the parameter list, as for a
-@code{FUNCTION_TYPE}, and includes the @code{this} argument.
-
-@item ARRAY_TYPE
-Used to represent array types. The @code{TREE_TYPE} gives the type of
-the elements in the array. If the array-bound is present in the type,
-the @code{TYPE_DOMAIN} is an @code{INTEGER_TYPE} whose
-@code{TYPE_MIN_VALUE} and @code{TYPE_MAX_VALUE} will be the lower and
-upper bounds of the array, respectively. The @code{TYPE_MIN_VALUE} will
-always be an @code{INTEGER_CST} for zero, while the
-@code{TYPE_MAX_VALUE} will be one less than the number of elements in
-the array, i.e., the highest value which may be used to index an element
-in the array.
-
-@item RECORD_TYPE
-Used to represent @code{struct} and @code{class} types, as well as
-pointers to member functions and similar constructs in other languages.
-@code{TYPE_FIELDS} contains the items contained in this type, each of
-which can be a @code{FIELD_DECL}, @code{VAR_DECL}, @code{CONST_DECL}, or
-@code{TYPE_DECL}. You may not make any assumptions about the ordering
-of the fields in the type or whether one or more of them overlap.
-
-@item UNION_TYPE
-Used to represent @code{union} types. Similar to @code{RECORD_TYPE}
-except that all @code{FIELD_DECL} nodes in @code{TYPE_FIELD} start at
-bit position zero.
-
-@item QUAL_UNION_TYPE
-Used to represent part of a variant record in Ada. Similar to
-@code{UNION_TYPE} except that each @code{FIELD_DECL} has a
-@code{DECL_QUALIFIER} field, which contains a boolean expression that
-indicates whether the field is present in the object. The type will only
-have one field, so each field's @code{DECL_QUALIFIER} is only evaluated
-if none of the expressions in the previous fields in @code{TYPE_FIELDS}
-are nonzero. Normally these expressions will reference a field in the
-outer object using a @code{PLACEHOLDER_EXPR}.
-
-@item LANG_TYPE
-This node is used to represent a language-specific type. The front
-end must handle it.
-
-@item OFFSET_TYPE
-This node is used to represent a pointer-to-data member. For a data
-member @code{X::m} the @code{TYPE_OFFSET_BASETYPE} is @code{X} and the
-@code{TREE_TYPE} is the type of @code{m}.
-
-@end table
-
-There are variables whose values represent some of the basic types.
-These include:
-@table @code
-@item void_type_node
-A node for @code{void}.
-
-@item integer_type_node
-A node for @code{int}.
-
-@item unsigned_type_node.
-A node for @code{unsigned int}.
-
-@item char_type_node.
-A node for @code{char}.
-@end table
-@noindent
-It may sometimes be useful to compare one of these variables with a type
-in hand, using @code{same_type_p}.
-
-@c ---------------------------------------------------------------------
-@c Declarations
-@c ---------------------------------------------------------------------
-
-@node Declarations
-@section Declarations
-@cindex declaration
-@cindex variable
-@cindex type declaration
-@tindex LABEL_DECL
-@tindex CONST_DECL
-@tindex TYPE_DECL
-@tindex VAR_DECL
-@tindex PARM_DECL
-@tindex DEBUG_EXPR_DECL
-@tindex FIELD_DECL
-@tindex NAMESPACE_DECL
-@tindex RESULT_DECL
-@tindex TEMPLATE_DECL
-@tindex THUNK_DECL
-@findex THUNK_DELTA
-@findex DECL_INITIAL
-@findex DECL_SIZE
-@findex DECL_ALIGN
-@findex DECL_EXTERNAL
-
-This section covers the various kinds of declarations that appear in the
-internal representation, except for declarations of functions
-(represented by @code{FUNCTION_DECL} nodes), which are described in
-@ref{Functions}.
-
-@menu
-* Working with declarations:: Macros and functions that work on
-declarations.
-* Internal structure:: How declaration nodes are represented.
-@end menu
-
-@node Working with declarations
-@subsection Working with declarations
-
-Some macros can be used with any kind of declaration. These include:
-@ftable @code
-@item DECL_NAME
-This macro returns an @code{IDENTIFIER_NODE} giving the name of the
-entity.
-
-@item TREE_TYPE
-This macro returns the type of the entity declared.
-
-@item EXPR_FILENAME
-This macro returns the name of the file in which the entity was
-declared, as a @code{char*}. For an entity declared implicitly by the
-compiler (like @code{__builtin_memcpy}), this will be the string
-@code{"<internal>"}.
-
-@item EXPR_LINENO
-This macro returns the line number at which the entity was declared, as
-an @code{int}.
-
-@item DECL_ARTIFICIAL
-This predicate holds if the declaration was implicitly generated by the
-compiler. For example, this predicate will hold of an implicitly
-declared member function, or of the @code{TYPE_DECL} implicitly
-generated for a class type. Recall that in C++ code like:
-@smallexample
-struct S @{@};
-@end smallexample
-@noindent
-is roughly equivalent to C code like:
-@smallexample
-struct S @{@};
-typedef struct S S;
-@end smallexample
-The implicitly generated @code{typedef} declaration is represented by a
-@code{TYPE_DECL} for which @code{DECL_ARTIFICIAL} holds.
-
-@end ftable
-
-The various kinds of declarations include:
-@table @code
-@item LABEL_DECL
-These nodes are used to represent labels in function bodies. For more
-information, see @ref{Functions}. These nodes only appear in block
-scopes.
-
-@item CONST_DECL
-These nodes are used to represent enumeration constants. The value of
-the constant is given by @code{DECL_INITIAL} which will be an
-@code{INTEGER_CST} with the same type as the @code{TREE_TYPE} of the
-@code{CONST_DECL}, i.e., an @code{ENUMERAL_TYPE}.
-
-@item RESULT_DECL
-These nodes represent the value returned by a function. When a value is
-assigned to a @code{RESULT_DECL}, that indicates that the value should
-be returned, via bitwise copy, by the function. You can use
-@code{DECL_SIZE} and @code{DECL_ALIGN} on a @code{RESULT_DECL}, just as
-with a @code{VAR_DECL}.
-
-@item TYPE_DECL
-These nodes represent @code{typedef} declarations. The @code{TREE_TYPE}
-is the type declared to have the name given by @code{DECL_NAME}. In
-some cases, there is no associated name.
-
-@item VAR_DECL
-These nodes represent variables with namespace or block scope, as well
-as static data members. The @code{DECL_SIZE} and @code{DECL_ALIGN} are
-analogous to @code{TYPE_SIZE} and @code{TYPE_ALIGN}. For a declaration,
-you should always use the @code{DECL_SIZE} and @code{DECL_ALIGN} rather
-than the @code{TYPE_SIZE} and @code{TYPE_ALIGN} given by the
-@code{TREE_TYPE}, since special attributes may have been applied to the
-variable to give it a particular size and alignment. You may use the
-predicates @code{DECL_THIS_STATIC} or @code{DECL_THIS_EXTERN} to test
-whether the storage class specifiers @code{static} or @code{extern} were
-used to declare a variable.
-
-If this variable is initialized (but does not require a constructor),
-the @code{DECL_INITIAL} will be an expression for the initializer. The
-initializer should be evaluated, and a bitwise copy into the variable
-performed. If the @code{DECL_INITIAL} is the @code{error_mark_node},
-there is an initializer, but it is given by an explicit statement later
-in the code; no bitwise copy is required.
-
-GCC provides an extension that allows either automatic variables, or
-global variables, to be placed in particular registers. This extension
-is being used for a particular @code{VAR_DECL} if @code{DECL_REGISTER}
-holds for the @code{VAR_DECL}, and if @code{DECL_ASSEMBLER_NAME} is not
-equal to @code{DECL_NAME}. In that case, @code{DECL_ASSEMBLER_NAME} is
-the name of the register into which the variable will be placed.
-
-@item PARM_DECL
-Used to represent a parameter to a function. Treat these nodes
-similarly to @code{VAR_DECL} nodes. These nodes only appear in the
-@code{DECL_ARGUMENTS} for a @code{FUNCTION_DECL}.
-
-The @code{DECL_ARG_TYPE} for a @code{PARM_DECL} is the type that will
-actually be used when a value is passed to this function. It may be a
-wider type than the @code{TREE_TYPE} of the parameter; for example, the
-ordinary type might be @code{short} while the @code{DECL_ARG_TYPE} is
-@code{int}.
-
-@item DEBUG_EXPR_DECL
-Used to represent an anonymous debug-information temporary created to
-hold an expression as it is optimized away, so that its value can be
-referenced in debug bind statements.
-
-@item FIELD_DECL
-These nodes represent non-static data members. The @code{DECL_SIZE} and
-@code{DECL_ALIGN} behave as for @code{VAR_DECL} nodes.
-The position of the field within the parent record is specified by a
-combination of three attributes. @code{DECL_FIELD_OFFSET} is the position,
-counting in bytes, of the @code{DECL_OFFSET_ALIGN}-bit sized word containing
-the bit of the field closest to the beginning of the structure.
-@code{DECL_FIELD_BIT_OFFSET} is the bit offset of the first bit of the field
-within this word; this may be nonzero even for fields that are not bit-fields,
-since @code{DECL_OFFSET_ALIGN} may be greater than the natural alignment
-of the field's type.
-
-If @code{DECL_C_BIT_FIELD} holds, this field is a bit-field. In a bit-field,
-@code{DECL_BIT_FIELD_TYPE} also contains the type that was originally
-specified for it, while DECL_TYPE may be a modified type with lesser precision,
-according to the size of the bit field.
-
-@item NAMESPACE_DECL
-Namespaces provide a name hierarchy for other declarations. They
-appear in the @code{DECL_CONTEXT} of other @code{_DECL} nodes.
-
-@end table
-
-@node Internal structure
-@subsection Internal structure
-
-@code{DECL} nodes are represented internally as a hierarchy of
-structures.
-
-@menu
-* Current structure hierarchy:: The current DECL node structure
-hierarchy.
-* Adding new DECL node types:: How to add a new DECL node to a
-frontend.
-@end menu
-
-@node Current structure hierarchy
-@subsubsection Current structure hierarchy
-
-@table @code
-
-@item struct tree_decl_minimal
-This is the minimal structure to inherit from in order for common
-@code{DECL} macros to work. The fields it contains are a unique ID,
-source location, context, and name.
-
-@item struct tree_decl_common
-This structure inherits from @code{struct tree_decl_minimal}. It
-contains fields that most @code{DECL} nodes need, such as a field to
-store alignment, machine mode, size, and attributes.
-
-@item struct tree_field_decl
-This structure inherits from @code{struct tree_decl_common}. It is
-used to represent @code{FIELD_DECL}.
-
-@item struct tree_label_decl
-This structure inherits from @code{struct tree_decl_common}. It is
-used to represent @code{LABEL_DECL}.
-
-@item struct tree_translation_unit_decl
-This structure inherits from @code{struct tree_decl_common}. It is
-used to represent @code{TRANSLATION_UNIT_DECL}.
-
-@item struct tree_decl_with_rtl
-This structure inherits from @code{struct tree_decl_common}. It
-contains a field to store the low-level RTL associated with a
-@code{DECL} node.
-
-@item struct tree_result_decl
-This structure inherits from @code{struct tree_decl_with_rtl}. It is
-used to represent @code{RESULT_DECL}.
-
-@item struct tree_const_decl
-This structure inherits from @code{struct tree_decl_with_rtl}. It is
-used to represent @code{CONST_DECL}.
-
-@item struct tree_parm_decl
-This structure inherits from @code{struct tree_decl_with_rtl}. It is
-used to represent @code{PARM_DECL}.
-
-@item struct tree_decl_with_vis
-This structure inherits from @code{struct tree_decl_with_rtl}. It
-contains fields necessary to store visibility information, as well as
-a section name and assembler name.
-
-@item struct tree_var_decl
-This structure inherits from @code{struct tree_decl_with_vis}. It is
-used to represent @code{VAR_DECL}.
-
-@item struct tree_function_decl
-This structure inherits from @code{struct tree_decl_with_vis}. It is
-used to represent @code{FUNCTION_DECL}.
-
-@end table
-@node Adding new DECL node types
-@subsubsection Adding new DECL node types
-
-Adding a new @code{DECL} tree consists of the following steps
-
-@table @asis
-
-@item Add a new tree code for the @code{DECL} node
-For language specific @code{DECL} nodes, there is a @file{.def} file
-in each frontend directory where the tree code should be added.
-For @code{DECL} nodes that are part of the middle-end, the code should
-be added to @file{tree.def}.
-
-@item Create a new structure type for the @code{DECL} node
-These structures should inherit from one of the existing structures in
-the language hierarchy by using that structure as the first member.
-
-@smallexample
-struct tree_foo_decl
-@{
- struct tree_decl_with_vis common;
-@}
-@end smallexample
-
-Would create a structure name @code{tree_foo_decl} that inherits from
-@code{struct tree_decl_with_vis}.
-
-For language specific @code{DECL} nodes, this new structure type
-should go in the appropriate @file{.h} file.
-For @code{DECL} nodes that are part of the middle-end, the structure
-type should go in @file{tree.h}.
-
-@item Add a member to the tree structure enumerator for the node
-For garbage collection and dynamic checking purposes, each @code{DECL}
-node structure type is required to have a unique enumerator value
-specified with it.
-For language specific @code{DECL} nodes, this new enumerator value
-should go in the appropriate @file{.def} file.
-For @code{DECL} nodes that are part of the middle-end, the enumerator
-values are specified in @file{treestruct.def}.
-
-@item Update @code{union tree_node}
-In order to make your new structure type usable, it must be added to
-@code{union tree_node}.
-For language specific @code{DECL} nodes, a new entry should be added
-to the appropriate @file{.h} file of the form
-@smallexample
- struct tree_foo_decl GTY ((tag ("TS_VAR_DECL"))) foo_decl;
-@end smallexample
-For @code{DECL} nodes that are part of the middle-end, the additional
-member goes directly into @code{union tree_node} in @file{tree.h}.
-
-@item Update dynamic checking info
-In order to be able to check whether accessing a named portion of
-@code{union tree_node} is legal, and whether a certain @code{DECL} node
-contains one of the enumerated @code{DECL} node structures in the
-hierarchy, a simple lookup table is used.
-This lookup table needs to be kept up to date with the tree structure
-hierarchy, or else checking and containment macros will fail
-inappropriately.
-
-For language specific @code{DECL} nodes, there is an @code{init_ts}
-function in an appropriate @file{.c} file, which initializes the lookup
-table.
-Code setting up the table for new @code{DECL} nodes should be added
-there.
-For each @code{DECL} tree code and enumerator value representing a
-member of the inheritance hierarchy, the table should contain 1 if
-that tree code inherits (directly or indirectly) from that member.
-Thus, a @code{FOO_DECL} node derived from @code{struct decl_with_rtl},
-and enumerator value @code{TS_FOO_DECL}, would be set up as follows
-@smallexample
-tree_contains_struct[FOO_DECL][TS_FOO_DECL] = 1;
-tree_contains_struct[FOO_DECL][TS_DECL_WRTL] = 1;
-tree_contains_struct[FOO_DECL][TS_DECL_COMMON] = 1;
-tree_contains_struct[FOO_DECL][TS_DECL_MINIMAL] = 1;
-@end smallexample
-
-For @code{DECL} nodes that are part of the middle-end, the setup code
-goes into @file{tree.cc}.
-
-@item Add macros to access any new fields and flags
-
-Each added field or flag should have a macro that is used to access
-it, that performs appropriate checking to ensure only the right type of
-@code{DECL} nodes access the field.
-
-These macros generally take the following form
-@smallexample
-#define FOO_DECL_FIELDNAME(NODE) FOO_DECL_CHECK(NODE)->foo_decl.fieldname
-@end smallexample
-However, if the structure is simply a base class for further
-structures, something like the following should be used
-@smallexample
-#define BASE_STRUCT_CHECK(T) CONTAINS_STRUCT_CHECK(T, TS_BASE_STRUCT)
-#define BASE_STRUCT_FIELDNAME(NODE) \
- (BASE_STRUCT_CHECK(NODE)->base_struct.fieldname
-@end smallexample
-
-Reading them from the generated @file{all-tree.def} file (which in
-turn includes all the @file{tree.def} files), @file{gencheck.cc} is
-used during GCC's build to generate the @code{*_CHECK} macros for all
-tree codes.
-
-@end table
-
-
-@c ---------------------------------------------------------------------
-@c Attributes
-@c ---------------------------------------------------------------------
-@node Attributes
-@section Attributes in trees
-@cindex attributes
-
-Attributes, as specified using the @code{__attribute__} keyword, are
-represented internally as a @code{TREE_LIST}. The @code{TREE_PURPOSE}
-is the name of the attribute, as an @code{IDENTIFIER_NODE}. The
-@code{TREE_VALUE} is a @code{TREE_LIST} of the arguments of the
-attribute, if any, or @code{NULL_TREE} if there are no arguments; the
-arguments are stored as the @code{TREE_VALUE} of successive entries in
-the list, and may be identifiers or expressions. The @code{TREE_CHAIN}
-of the attribute is the next attribute in a list of attributes applying
-to the same declaration or type, or @code{NULL_TREE} if there are no
-further attributes in the list.
-
-Attributes may be attached to declarations and to types; these
-attributes may be accessed with the following macros. All attributes
-are stored in this way, and many also cause other changes to the
-declaration or type or to other internal compiler data structures.
-
-@deftypefn {Tree Macro} tree DECL_ATTRIBUTES (tree @var{decl})
-This macro returns the attributes on the declaration @var{decl}.
-@end deftypefn
-
-@deftypefn {Tree Macro} tree TYPE_ATTRIBUTES (tree @var{type})
-This macro returns the attributes on the type @var{type}.
-@end deftypefn
-
-
-@c ---------------------------------------------------------------------
-@c Expressions
-@c ---------------------------------------------------------------------
-
-@node Expression trees
-@section Expressions
-@cindex expression
-@findex TREE_TYPE
-@findex TREE_OPERAND
-
-The internal representation for expressions is for the most part quite
-straightforward. However, there are a few facts that one must bear in
-mind. In particular, the expression ``tree'' is actually a directed
-acyclic graph. (For example there may be many references to the integer
-constant zero throughout the source program; many of these will be
-represented by the same expression node.) You should not rely on
-certain kinds of node being shared, nor should you rely on certain kinds of
-nodes being unshared.
-
-The following macros can be used with all expression nodes:
-
-@ftable @code
-@item TREE_TYPE
-Returns the type of the expression. This value may not be precisely the
-same type that would be given the expression in the original program.
-@end ftable
-
-In what follows, some nodes that one might expect to always have type
-@code{bool} are documented to have either integral or boolean type. At
-some point in the future, the C front end may also make use of this same
-intermediate representation, and at this point these nodes will
-certainly have integral type. The previous sentence is not meant to
-imply that the C++ front end does not or will not give these nodes
-integral type.
-
-Below, we list the various kinds of expression nodes. Except where
-noted otherwise, the operands to an expression are accessed using the
-@code{TREE_OPERAND} macro. For example, to access the first operand to
-a binary plus expression @code{expr}, use:
-
-@smallexample
-TREE_OPERAND (expr, 0)
-@end smallexample
-@noindent
-
-As this example indicates, the operands are zero-indexed.
-
-
-@menu
-* Constants: Constant expressions.
-* Storage References::
-* Unary and Binary Expressions::
-* Vectors::
-@end menu
-
-@node Constant expressions
-@subsection Constant expressions
-@tindex INTEGER_CST
-@findex tree_int_cst_lt
-@findex tree_int_cst_equal
-@tindex tree_fits_uhwi_p
-@tindex tree_fits_shwi_p
-@tindex tree_to_uhwi
-@tindex tree_to_shwi
-@tindex TREE_INT_CST_NUNITS
-@tindex TREE_INT_CST_ELT
-@tindex TREE_INT_CST_LOW
-@tindex REAL_CST
-@tindex FIXED_CST
-@tindex COMPLEX_CST
-@tindex VECTOR_CST
-@tindex STRING_CST
-@tindex POLY_INT_CST
-@findex TREE_STRING_LENGTH
-@findex TREE_STRING_POINTER
-
-The table below begins with constants, moves on to unary expressions,
-then proceeds to binary expressions, and concludes with various other
-kinds of expressions:
-
-@table @code
-@item INTEGER_CST
-These nodes represent integer constants. Note that the type of these
-constants is obtained with @code{TREE_TYPE}; they are not always of type
-@code{int}. In particular, @code{char} constants are represented with
-@code{INTEGER_CST} nodes. The value of the integer constant @code{e} is
-represented in an array of HOST_WIDE_INT. There are enough elements
-in the array to represent the value without taking extra elements for
-redundant 0s or -1. The number of elements used to represent @code{e}
-is available via @code{TREE_INT_CST_NUNITS}. Element @code{i} can be
-extracted by using @code{TREE_INT_CST_ELT (e, i)}.
-@code{TREE_INT_CST_LOW} is a shorthand for @code{TREE_INT_CST_ELT (e, 0)}.
-
-The functions @code{tree_fits_shwi_p} and @code{tree_fits_uhwi_p}
-can be used to tell if the value is small enough to fit in a
-signed HOST_WIDE_INT or an unsigned HOST_WIDE_INT respectively.
-The value can then be extracted using @code{tree_to_shwi} and
-@code{tree_to_uhwi}.
-
-@item REAL_CST
-
-FIXME: Talk about how to obtain representations of this constant, do
-comparisons, and so forth.
-
-@item FIXED_CST
-
-These nodes represent fixed-point constants. The type of these constants
-is obtained with @code{TREE_TYPE}. @code{TREE_FIXED_CST_PTR} points to
-a @code{struct fixed_value}; @code{TREE_FIXED_CST} returns the structure
-itself. @code{struct fixed_value} contains @code{data} with the size of two
-@code{HOST_BITS_PER_WIDE_INT} and @code{mode} as the associated fixed-point
-machine mode for @code{data}.
-
-@item COMPLEX_CST
-These nodes are used to represent complex number constants, that is a
-@code{__complex__} whose parts are constant nodes. The
-@code{TREE_REALPART} and @code{TREE_IMAGPART} return the real and the
-imaginary parts respectively.
-
-@item VECTOR_CST
-These nodes are used to represent vector constants. Each vector
-constant @var{v} is treated as a specific instance of an arbitrary-length
-sequence that itself contains @samp{VECTOR_CST_NPATTERNS (@var{v})}
-interleaved patterns. Each pattern has the form:
-
-@smallexample
-@{ @var{base0}, @var{base1}, @var{base1} + @var{step}, @var{base1} + @var{step} * 2, @dots{} @}
-@end smallexample
-
-The first three elements in each pattern are enough to determine the
-values of the other elements. However, if all @var{step}s are zero,
-only the first two elements are needed. If in addition each @var{base1}
-is equal to the corresponding @var{base0}, only the first element in
-each pattern is needed. The number of encoded elements per pattern
-is given by @samp{VECTOR_CST_NELTS_PER_PATTERN (@var{v})}.
-
-For example, the constant:
-
-@smallexample
-@{ 0, 1, 2, 6, 3, 8, 4, 10, 5, 12, 6, 14, 7, 16, 8, 18 @}
-@end smallexample
-
-is interpreted as an interleaving of the sequences:
-
-@smallexample
-@{ 0, 2, 3, 4, 5, 6, 7, 8 @}
-@{ 1, 6, 8, 10, 12, 14, 16, 18 @}
-@end smallexample
-
-where the sequences are represented by the following patterns:
-
-@smallexample
-@var{base0} == 0, @var{base1} == 2, @var{step} == 1
-@var{base0} == 1, @var{base1} == 6, @var{step} == 2
-@end smallexample
-
-In this case:
-
-@smallexample
-VECTOR_CST_NPATTERNS (@var{v}) == 2
-VECTOR_CST_NELTS_PER_PATTERN (@var{v}) == 3
-@end smallexample
-
-The vector is therefore encoded using the first 6 elements
-(@samp{@{ 0, 1, 2, 6, 3, 8 @}}), with the remaining 10 elements
-being implicit extensions of them.
-
-Sometimes this scheme can create two possible encodings of the same
-vector. For example @{ 0, 1 @} could be seen as two patterns with
-one element each or one pattern with two elements (@var{base0} and
-@var{base1}). The canonical encoding is always the one with the
-fewest patterns or (if both encodings have the same number of
-petterns) the one with the fewest encoded elements.
-
-@samp{vector_cst_encoding_nelts (@var{v})} gives the total number of
-encoded elements in @var{v}, which is 6 in the example above.
-@code{VECTOR_CST_ENCODED_ELTS (@var{v})} gives a pointer to the elements
-encoded in @var{v} and @code{VECTOR_CST_ENCODED_ELT (@var{v}, @var{i})}
-accesses the value of encoded element @var{i}.
-
-@samp{VECTOR_CST_DUPLICATE_P (@var{v})} is true if @var{v} simply contains
-repeated instances of @samp{VECTOR_CST_NPATTERNS (@var{v})} values. This is
-a shorthand for testing @samp{VECTOR_CST_NELTS_PER_PATTERN (@var{v}) == 1}.
-
-@samp{VECTOR_CST_STEPPED_P (@var{v})} is true if at least one
-pattern in @var{v} has a nonzero step. This is a shorthand for
-testing @samp{VECTOR_CST_NELTS_PER_PATTERN (@var{v}) == 3}.
-
-The utility function @code{vector_cst_elt} gives the value of an
-arbitrary index as a @code{tree}. @code{vector_cst_int_elt} gives
-the same value as a @code{wide_int}.
-
-@item STRING_CST
-These nodes represent string-constants. The @code{TREE_STRING_LENGTH}
-returns the length of the string, as an @code{int}. The
-@code{TREE_STRING_POINTER} is a @code{char*} containing the string
-itself. The string may not be @code{NUL}-terminated, and it may contain
-embedded @code{NUL} characters. Therefore, the
-@code{TREE_STRING_LENGTH} includes the trailing @code{NUL} if it is
-present.
-
-For wide string constants, the @code{TREE_STRING_LENGTH} is the number
-of bytes in the string, and the @code{TREE_STRING_POINTER}
-points to an array of the bytes of the string, as represented on the
-target system (that is, as integers in the target endianness). Wide and
-non-wide string constants are distinguished only by the @code{TREE_TYPE}
-of the @code{STRING_CST}.
-
-FIXME: The formats of string constants are not well-defined when the
-target system bytes are not the same width as host system bytes.
-
-@item POLY_INT_CST
-These nodes represent invariants that depend on some target-specific
-runtime parameters. They consist of @code{NUM_POLY_INT_COEFFS}
-coefficients, with the first coefficient being the constant term and
-the others being multipliers that are applied to the runtime parameters.
-
-@code{POLY_INT_CST_ELT (@var{x}, @var{i})} references coefficient number
-@var{i} of @code{POLY_INT_CST} node @var{x}. Each coefficient is an
-@code{INTEGER_CST}.
-
-@end table
-
-@node Storage References
-@subsection References to storage
-@tindex ADDR_EXPR
-@tindex INDIRECT_REF
-@tindex MEM_REF
-@tindex ARRAY_REF
-@tindex ARRAY_RANGE_REF
-@tindex TARGET_MEM_REF
-@tindex COMPONENT_REF
-
-@table @code
-@item ARRAY_REF
-These nodes represent array accesses. The first operand is the array;
-the second is the index. To calculate the address of the memory
-accessed, you must scale the index by the size of the type of the array
-elements. The type of these expressions must be the type of a component of
-the array. The third and fourth operands are used after gimplification
-to represent the lower bound and component size but should not be used
-directly; call @code{array_ref_low_bound} and @code{array_ref_element_size}
-instead.
-
-@item ARRAY_RANGE_REF
-These nodes represent access to a range (or ``slice'') of an array. The
-operands are the same as that for @code{ARRAY_REF} and have the same
-meanings. The type of these expressions must be an array whose component
-type is the same as that of the first operand. The range of that array
-type determines the amount of data these expressions access.
-
-@item COMPONENT_REF
-These nodes represent non-static data member accesses. The first
-operand is the object (rather than a pointer to it); the second operand
-is the @code{FIELD_DECL} for the data member. The third operand represents
-the byte offset of the field, but should not be used directly; call
-@code{component_ref_field_offset} instead.
-
-@item ADDR_EXPR
-These nodes are used to represent the address of an object. (These
-expressions will always have pointer or reference type.) The operand may
-be another expression, or it may be a declaration.
-
-As an extension, GCC allows users to take the address of a label. In
-this case, the operand of the @code{ADDR_EXPR} will be a
-@code{LABEL_DECL}. The type of such an expression is @code{void*}.
-
-If the object addressed is not an lvalue, a temporary is created, and
-the address of the temporary is used.
-
-@item INDIRECT_REF
-These nodes are used to represent the object pointed to by a pointer.
-The operand is the pointer being dereferenced; it will always have
-pointer or reference type.
-
-@item MEM_REF
-These nodes are used to represent the object pointed to by a pointer
-offset by a constant.
-The first operand is the pointer being dereferenced; it will always have
-pointer or reference type. The second operand is a pointer constant
-serving as constant offset applied to the pointer being dereferenced
-with its type specifying the type to be used for type-based alias analysis.
-The type of the node specifies the alignment of the access.
-
-@item TARGET_MEM_REF
-These nodes represent memory accesses whose address directly map to
-an addressing mode of the target architecture. The first argument
-is @code{TMR_BASE} and is a pointer to the object being accessed.
-The second argument is @code{TMR_OFFSET} which is a pointer constant
-with dual purpose serving both as constant offset and holder of
-the type used for type-based alias analysis. The first two operands
-have exactly the same semantics as @code{MEM_REF}. The third
-and fourth operand are @code{TMR_INDEX} and @code{TMR_STEP} where
-the former is an integer and the latter an integer constant. The
-fifth and last operand is @code{TMR_INDEX2} which is an alternate
-non-constant offset. Any of the third to last operands may be
-@code{NULL} if the corresponding component does not appear in
-the address, but @code{TMR_INDEX} and @code{TMR_STEP} shall be
-always supplied in pair. The Address of the @code{TARGET_MEM_REF}
-is determined in the following way.
-
-@smallexample
-TMR_BASE + TMR_OFFSET + TMR_INDEX * TMR_STEP + TMR_INDEX2
-@end smallexample
-
-The type of the node specifies the alignment of the access.
-
-@end table
-
-@node Unary and Binary Expressions
-@subsection Unary and Binary Expressions
-@tindex NEGATE_EXPR
-@tindex ABS_EXPR
-@tindex ABSU_EXPR
-@tindex BIT_NOT_EXPR
-@tindex TRUTH_NOT_EXPR
-@tindex PREDECREMENT_EXPR
-@tindex PREINCREMENT_EXPR
-@tindex POSTDECREMENT_EXPR
-@tindex POSTINCREMENT_EXPR
-@tindex FIX_TRUNC_EXPR
-@tindex FLOAT_EXPR
-@tindex COMPLEX_EXPR
-@tindex CONJ_EXPR
-@tindex REALPART_EXPR
-@tindex IMAGPART_EXPR
-@tindex NON_LVALUE_EXPR
-@tindex NOP_EXPR
-@tindex CONVERT_EXPR
-@tindex FIXED_CONVERT_EXPR
-@tindex THROW_EXPR
-@tindex LSHIFT_EXPR
-@tindex RSHIFT_EXPR
-@tindex BIT_IOR_EXPR
-@tindex BIT_XOR_EXPR
-@tindex BIT_AND_EXPR
-@tindex TRUTH_ANDIF_EXPR
-@tindex TRUTH_ORIF_EXPR
-@tindex TRUTH_AND_EXPR
-@tindex TRUTH_OR_EXPR
-@tindex TRUTH_XOR_EXPR
-@tindex POINTER_PLUS_EXPR
-@tindex POINTER_DIFF_EXPR
-@tindex PLUS_EXPR
-@tindex MINUS_EXPR
-@tindex MULT_EXPR
-@tindex WIDEN_MULT_EXPR
-@tindex MULT_HIGHPART_EXPR
-@tindex RDIV_EXPR
-@tindex TRUNC_DIV_EXPR
-@tindex FLOOR_DIV_EXPR
-@tindex CEIL_DIV_EXPR
-@tindex ROUND_DIV_EXPR
-@tindex TRUNC_MOD_EXPR
-@tindex FLOOR_MOD_EXPR
-@tindex CEIL_MOD_EXPR
-@tindex ROUND_MOD_EXPR
-@tindex EXACT_DIV_EXPR
-@tindex LT_EXPR
-@tindex LE_EXPR
-@tindex GT_EXPR
-@tindex GE_EXPR
-@tindex EQ_EXPR
-@tindex NE_EXPR
-@tindex ORDERED_EXPR
-@tindex UNORDERED_EXPR
-@tindex UNLT_EXPR
-@tindex UNLE_EXPR
-@tindex UNGT_EXPR
-@tindex UNGE_EXPR
-@tindex UNEQ_EXPR
-@tindex LTGT_EXPR
-@tindex MODIFY_EXPR
-@tindex INIT_EXPR
-@tindex COMPOUND_EXPR
-@tindex COND_EXPR
-@tindex CALL_EXPR
-@tindex STMT_EXPR
-@tindex BIND_EXPR
-@tindex LOOP_EXPR
-@tindex EXIT_EXPR
-@tindex CLEANUP_POINT_EXPR
-@tindex CONSTRUCTOR
-@tindex COMPOUND_LITERAL_EXPR
-@tindex SAVE_EXPR
-@tindex TARGET_EXPR
-@tindex VA_ARG_EXPR
-@tindex ANNOTATE_EXPR
-
-@table @code
-@item NEGATE_EXPR
-These nodes represent unary negation of the single operand, for both
-integer and floating-point types. The type of negation can be
-determined by looking at the type of the expression.
-
-The behavior of this operation on signed arithmetic overflow is
-controlled by the @code{flag_wrapv} and @code{flag_trapv} variables.
-
-@item ABS_EXPR
-These nodes represent the absolute value of the single operand, for
-both integer and floating-point types. This is typically used to
-implement the @code{abs}, @code{labs} and @code{llabs} builtins for
-integer types, and the @code{fabs}, @code{fabsf} and @code{fabsl}
-builtins for floating point types. The type of abs operation can
-be determined by looking at the type of the expression.
-
-This node is not used for complex types. To represent the modulus
-or complex abs of a complex value, use the @code{BUILT_IN_CABS},
-@code{BUILT_IN_CABSF} or @code{BUILT_IN_CABSL} builtins, as used
-to implement the C99 @code{cabs}, @code{cabsf} and @code{cabsl}
-built-in functions.
-
-@item ABSU_EXPR
-These nodes represent the absolute value of the single operand in
-equivalent unsigned type such that @code{ABSU_EXPR} of @code{TYPE_MIN}
-is well defined.
-
-@item BIT_NOT_EXPR
-These nodes represent bitwise complement, and will always have integral
-type. The only operand is the value to be complemented.
-
-@item TRUTH_NOT_EXPR
-These nodes represent logical negation, and will always have integral
-(or boolean) type. The operand is the value being negated. The type
-of the operand and that of the result are always of @code{BOOLEAN_TYPE}
-or @code{INTEGER_TYPE}.
-
-@item PREDECREMENT_EXPR
-@itemx PREINCREMENT_EXPR
-@itemx POSTDECREMENT_EXPR
-@itemx POSTINCREMENT_EXPR
-These nodes represent increment and decrement expressions. The value of
-the single operand is computed, and the operand incremented or
-decremented. In the case of @code{PREDECREMENT_EXPR} and
-@code{PREINCREMENT_EXPR}, the value of the expression is the value
-resulting after the increment or decrement; in the case of
-@code{POSTDECREMENT_EXPR} and @code{POSTINCREMENT_EXPR} is the value
-before the increment or decrement occurs. The type of the operand, like
-that of the result, will be either integral, boolean, or floating-point.
-
-@item FIX_TRUNC_EXPR
-These nodes represent conversion of a floating-point value to an
-integer. The single operand will have a floating-point type, while
-the complete expression will have an integral (or boolean) type. The
-operand is rounded towards zero.
-
-@item FLOAT_EXPR
-These nodes represent conversion of an integral (or boolean) value to a
-floating-point value. The single operand will have integral type, while
-the complete expression will have a floating-point type.
-
-FIXME: How is the operand supposed to be rounded? Is this dependent on
-@option{-mieee}?
-
-@item COMPLEX_EXPR
-These nodes are used to represent complex numbers constructed from two
-expressions of the same (integer or real) type. The first operand is the
-real part and the second operand is the imaginary part.
-
-@item CONJ_EXPR
-These nodes represent the conjugate of their operand.
-
-@item REALPART_EXPR
-@itemx IMAGPART_EXPR
-These nodes represent respectively the real and the imaginary parts
-of complex numbers (their sole argument).
-
-@item NON_LVALUE_EXPR
-These nodes indicate that their one and only operand is not an lvalue.
-A back end can treat these identically to the single operand.
-
-@item NOP_EXPR
-These nodes are used to represent conversions that do not require any
-code-generation. For example, conversion of a @code{char*} to an
-@code{int*} does not require any code be generated; such a conversion is
-represented by a @code{NOP_EXPR}. The single operand is the expression
-to be converted. The conversion from a pointer to a reference is also
-represented with a @code{NOP_EXPR}.
-
-@item CONVERT_EXPR
-These nodes are similar to @code{NOP_EXPR}s, but are used in those
-situations where code may need to be generated. For example, if an
-@code{int*} is converted to an @code{int} code may need to be generated
-on some platforms. These nodes are never used for C++-specific
-conversions, like conversions between pointers to different classes in
-an inheritance hierarchy. Any adjustments that need to be made in such
-cases are always indicated explicitly. Similarly, a user-defined
-conversion is never represented by a @code{CONVERT_EXPR}; instead, the
-function calls are made explicit.
-
-@item FIXED_CONVERT_EXPR
-These nodes are used to represent conversions that involve fixed-point
-values. For example, from a fixed-point value to another fixed-point value,
-from an integer to a fixed-point value, from a fixed-point value to an
-integer, from a floating-point value to a fixed-point value, or from
-a fixed-point value to a floating-point value.
-
-@item LSHIFT_EXPR
-@itemx RSHIFT_EXPR
-These nodes represent left and right shifts, respectively. The first
-operand is the value to shift; it will always be of integral type. The
-second operand is an expression for the number of bits by which to
-shift. Right shift should be treated as arithmetic, i.e., the
-high-order bits should be zero-filled when the expression has unsigned
-type and filled with the sign bit when the expression has signed type.
-Note that the result is undefined if the second operand is larger
-than or equal to the first operand's type size. Unlike most nodes, these
-can have a vector as first operand and a scalar as second operand.
-
-
-@item BIT_IOR_EXPR
-@itemx BIT_XOR_EXPR
-@itemx BIT_AND_EXPR
-These nodes represent bitwise inclusive or, bitwise exclusive or, and
-bitwise and, respectively. Both operands will always have integral
-type.
-
-@item TRUTH_ANDIF_EXPR
-@itemx TRUTH_ORIF_EXPR
-These nodes represent logical ``and'' and logical ``or'', respectively.
-These operators are not strict; i.e., the second operand is evaluated
-only if the value of the expression is not determined by evaluation of
-the first operand. The type of the operands and that of the result are
-always of @code{BOOLEAN_TYPE} or @code{INTEGER_TYPE}.
-
-@item TRUTH_AND_EXPR
-@itemx TRUTH_OR_EXPR
-@itemx TRUTH_XOR_EXPR
-These nodes represent logical and, logical or, and logical exclusive or.
-They are strict; both arguments are always evaluated. There are no
-corresponding operators in C or C++, but the front end will sometimes
-generate these expressions anyhow, if it can tell that strictness does
-not matter. The type of the operands and that of the result are
-always of @code{BOOLEAN_TYPE} or @code{INTEGER_TYPE}.
-
-@item POINTER_PLUS_EXPR
-This node represents pointer arithmetic. The first operand is always
-a pointer/reference type. The second operand is always an unsigned
-integer type compatible with sizetype. This and POINTER_DIFF_EXPR are
-the only binary arithmetic operators that can operate on pointer types.
-
-@item POINTER_DIFF_EXPR
-This node represents pointer subtraction. The two operands always
-have pointer/reference type. It returns a signed integer of the same
-precision as the pointers. The behavior is undefined if the difference
-of the two pointers, seen as infinite precision non-negative integers,
-does not fit in the result type. The result does not depend on the
-pointer type, it is not divided by the size of the pointed-to type.
-
-@item PLUS_EXPR
-@itemx MINUS_EXPR
-@itemx MULT_EXPR
-These nodes represent various binary arithmetic operations.
-Respectively, these operations are addition, subtraction (of the second
-operand from the first) and multiplication. Their operands may have
-either integral or floating type, but there will never be case in which
-one operand is of floating type and the other is of integral type.
-
-The behavior of these operations on signed arithmetic overflow is
-controlled by the @code{flag_wrapv} and @code{flag_trapv} variables.
-
-@item WIDEN_MULT_EXPR
-This node represents a widening multiplication. The operands have
-integral types with same @var{b} bits of precision, producing an
-integral type result with at least @math{2@var{b}} bits of precision.
-The behaviour is equivalent to extending both operands, possibly of
-different signedness, to the result type, then multiplying them.
-
-@item MULT_HIGHPART_EXPR
-This node represents the ``high-part'' of a widening multiplication.
-For an integral type with @var{b} bits of precision, the result is
-the most significant @var{b} bits of the full @math{2@var{b}} product.
-Both operands must have the same precision and same signedness.
-
-@item RDIV_EXPR
-This node represents a floating point division operation.
-
-@item TRUNC_DIV_EXPR
-@itemx FLOOR_DIV_EXPR
-@itemx CEIL_DIV_EXPR
-@itemx ROUND_DIV_EXPR
-These nodes represent integer division operations that return an integer
-result. @code{TRUNC_DIV_EXPR} rounds towards zero, @code{FLOOR_DIV_EXPR}
-rounds towards negative infinity, @code{CEIL_DIV_EXPR} rounds towards
-positive infinity and @code{ROUND_DIV_EXPR} rounds to the closest integer.
-Integer division in C and C++ is truncating, i.e.@: @code{TRUNC_DIV_EXPR}.
-
-The behavior of these operations on signed arithmetic overflow, when
-dividing the minimum signed integer by minus one, is controlled by the
-@code{flag_wrapv} and @code{flag_trapv} variables.
-
-@item TRUNC_MOD_EXPR
-@itemx FLOOR_MOD_EXPR
-@itemx CEIL_MOD_EXPR
-@itemx ROUND_MOD_EXPR
-These nodes represent the integer remainder or modulus operation.
-The integer modulus of two operands @code{a} and @code{b} is
-defined as @code{a - (a/b)*b} where the division calculated using
-the corresponding division operator. Hence for @code{TRUNC_MOD_EXPR}
-this definition assumes division using truncation towards zero, i.e.@:
-@code{TRUNC_DIV_EXPR}. Integer remainder in C and C++ uses truncating
-division, i.e.@: @code{TRUNC_MOD_EXPR}.
-
-@item EXACT_DIV_EXPR
-The @code{EXACT_DIV_EXPR} code is used to represent integer divisions where
-the numerator is known to be an exact multiple of the denominator. This
-allows the backend to choose between the faster of @code{TRUNC_DIV_EXPR},
-@code{CEIL_DIV_EXPR} and @code{FLOOR_DIV_EXPR} for the current target.
-
-@item LT_EXPR
-@itemx LE_EXPR
-@itemx GT_EXPR
-@itemx GE_EXPR
-@itemx LTGT_EXPR
-@itemx EQ_EXPR
-@itemx NE_EXPR
-These nodes represent the less than, less than or equal to, greater than,
-greater than or equal to, less or greater than, equal, and not equal
-comparison operators. The first and second operands will either be both
-of integral type, both of floating type or both of vector type, except for
-LTGT_EXPR where they will only be both of floating type. The result type
-of these expressions will always be of integral, boolean or signed integral
-vector type. These operations return the result type's zero value for false,
-the result type's one value for true, and a vector whose elements are zero
-(false) or minus one (true) for vectors.
-
-For floating point comparisons, if we honor IEEE NaNs and either operand
-is NaN, then @code{NE_EXPR} always returns true and the remaining operators
-always return false. On some targets, comparisons against an IEEE NaN,
-other than equality and inequality, may generate a floating-point exception.
-
-@item ORDERED_EXPR
-@itemx UNORDERED_EXPR
-These nodes represent non-trapping ordered and unordered comparison
-operators. These operations take two floating point operands and
-determine whether they are ordered or unordered relative to each other.
-If either operand is an IEEE NaN, their comparison is defined to be
-unordered, otherwise the comparison is defined to be ordered. The
-result type of these expressions will always be of integral or boolean
-type. These operations return the result type's zero value for false,
-and the result type's one value for true.
-
-@item UNLT_EXPR
-@itemx UNLE_EXPR
-@itemx UNGT_EXPR
-@itemx UNGE_EXPR
-@itemx UNEQ_EXPR
-These nodes represent the unordered comparison operators.
-These operations take two floating point operands and determine whether
-the operands are unordered or are less than, less than or equal to,
-greater than, greater than or equal to, or equal respectively. For
-example, @code{UNLT_EXPR} returns true if either operand is an IEEE
-NaN or the first operand is less than the second. All these operations
-are guaranteed not to generate a floating point exception. The result
-type of these expressions will always be of integral or boolean type.
-These operations return the result type's zero value for false,
-and the result type's one value for true.
-
-@item MODIFY_EXPR
-These nodes represent assignment. The left-hand side is the first
-operand; the right-hand side is the second operand. The left-hand side
-will be a @code{VAR_DECL}, @code{INDIRECT_REF}, @code{COMPONENT_REF}, or
-other lvalue.
-
-These nodes are used to represent not only assignment with @samp{=} but
-also compound assignments (like @samp{+=}), by reduction to @samp{=}
-assignment. In other words, the representation for @samp{i += 3} looks
-just like that for @samp{i = i + 3}.
-
-@item INIT_EXPR
-These nodes are just like @code{MODIFY_EXPR}, but are used only when a
-variable is initialized, rather than assigned to subsequently. This
-means that we can assume that the target of the initialization is not
-used in computing its own value; any reference to the lhs in computing
-the rhs is undefined.
-
-@item COMPOUND_EXPR
-These nodes represent comma-expressions. The first operand is an
-expression whose value is computed and thrown away prior to the
-evaluation of the second operand. The value of the entire expression is
-the value of the second operand.
-
-@item COND_EXPR
-These nodes represent @code{?:} expressions. The first operand
-is of boolean or integral type. If it evaluates to a nonzero value,
-the second operand should be evaluated, and returned as the value of the
-expression. Otherwise, the third operand is evaluated, and returned as
-the value of the expression.
-
-The second operand must have the same type as the entire expression,
-unless it unconditionally throws an exception or calls a noreturn
-function, in which case it should have void type. The same constraints
-apply to the third operand. This allows array bounds checks to be
-represented conveniently as @code{(i >= 0 && i < 10) ? i : abort()}.
-
-As a GNU extension, the C language front-ends allow the second
-operand of the @code{?:} operator may be omitted in the source.
-For example, @code{x ? : 3} is equivalent to @code{x ? x : 3},
-assuming that @code{x} is an expression without side effects.
-In the tree representation, however, the second operand is always
-present, possibly protected by @code{SAVE_EXPR} if the first
-argument does cause side effects.
-
-@item CALL_EXPR
-These nodes are used to represent calls to functions, including
-non-static member functions. @code{CALL_EXPR}s are implemented as
-expression nodes with a variable number of operands. Rather than using
-@code{TREE_OPERAND} to extract them, it is preferable to use the
-specialized accessor macros and functions that operate specifically on
-@code{CALL_EXPR} nodes.
-
-@code{CALL_EXPR_FN} returns a pointer to the
-function to call; it is always an expression whose type is a
-@code{POINTER_TYPE}.
-
-The number of arguments to the call is returned by @code{call_expr_nargs},
-while the arguments themselves can be accessed with the @code{CALL_EXPR_ARG}
-macro. The arguments are zero-indexed and numbered left-to-right.
-You can iterate over the arguments using @code{FOR_EACH_CALL_EXPR_ARG}, as in:
-
-@smallexample
-tree call, arg;
-call_expr_arg_iterator iter;
-FOR_EACH_CALL_EXPR_ARG (arg, iter, call)
- /* arg is bound to successive arguments of call. */
- @dots{};
-@end smallexample
-
-For non-static
-member functions, there will be an operand corresponding to the
-@code{this} pointer. There will always be expressions corresponding to
-all of the arguments, even if the function is declared with default
-arguments and some arguments are not explicitly provided at the call
-sites.
-
-@code{CALL_EXPR}s also have a @code{CALL_EXPR_STATIC_CHAIN} operand that
-is used to implement nested functions. This operand is otherwise null.
-
-@item CLEANUP_POINT_EXPR
-These nodes represent full-expressions. The single operand is an
-expression to evaluate. Any destructor calls engendered by the creation
-of temporaries during the evaluation of that expression should be
-performed immediately after the expression is evaluated.
-
-@item CONSTRUCTOR
-These nodes represent the brace-enclosed initializers for a structure or an
-array. They contain a sequence of component values made out of a vector of
-constructor_elt, which is a (@code{INDEX}, @code{VALUE}) pair.
-
-If the @code{TREE_TYPE} of the @code{CONSTRUCTOR} is a @code{RECORD_TYPE},
-@code{UNION_TYPE} or @code{QUAL_UNION_TYPE} then the @code{INDEX} of each
-node in the sequence will be a @code{FIELD_DECL} and the @code{VALUE} will
-be the expression used to initialize that field.
-
-If the @code{TREE_TYPE} of the @code{CONSTRUCTOR} is an @code{ARRAY_TYPE},
-then the @code{INDEX} of each node in the sequence will be an
-@code{INTEGER_CST} or a @code{RANGE_EXPR} of two @code{INTEGER_CST}s.
-A single @code{INTEGER_CST} indicates which element of the array is being
-assigned to. A @code{RANGE_EXPR} indicates an inclusive range of elements
-to initialize. In both cases the @code{VALUE} is the corresponding
-initializer. It is re-evaluated for each element of a
-@code{RANGE_EXPR}. If the @code{INDEX} is @code{NULL_TREE}, then
-the initializer is for the next available array element.
-
-In the front end, you should not depend on the fields appearing in any
-particular order. However, in the middle end, fields must appear in
-declaration order. You should not assume that all fields will be
-represented. Unrepresented fields will be cleared (zeroed), unless the
-CONSTRUCTOR_NO_CLEARING flag is set, in which case their value becomes
-undefined.
-
-@item COMPOUND_LITERAL_EXPR
-@findex COMPOUND_LITERAL_EXPR_DECL_EXPR
-@findex COMPOUND_LITERAL_EXPR_DECL
-These nodes represent ISO C99 compound literals. The
-@code{COMPOUND_LITERAL_EXPR_DECL_EXPR} is a @code{DECL_EXPR}
-containing an anonymous @code{VAR_DECL} for
-the unnamed object represented by the compound literal; the
-@code{DECL_INITIAL} of that @code{VAR_DECL} is a @code{CONSTRUCTOR}
-representing the brace-enclosed list of initializers in the compound
-literal. That anonymous @code{VAR_DECL} can also be accessed directly
-by the @code{COMPOUND_LITERAL_EXPR_DECL} macro.
-
-@item SAVE_EXPR
-
-A @code{SAVE_EXPR} represents an expression (possibly involving
-side effects) that is used more than once. The side effects should
-occur only the first time the expression is evaluated. Subsequent uses
-should just reuse the computed value. The first operand to the
-@code{SAVE_EXPR} is the expression to evaluate. The side effects should
-be executed where the @code{SAVE_EXPR} is first encountered in a
-depth-first preorder traversal of the expression tree.
-
-@item TARGET_EXPR
-A @code{TARGET_EXPR} represents a temporary object. The first operand
-is a @code{VAR_DECL} for the temporary variable. The second operand is
-the initializer for the temporary. The initializer is evaluated and,
-if non-void, copied (bitwise) into the temporary. If the initializer
-is void, that means that it will perform the initialization itself.
-
-Often, a @code{TARGET_EXPR} occurs on the right-hand side of an
-assignment, or as the second operand to a comma-expression which is
-itself the right-hand side of an assignment, etc. In this case, we say
-that the @code{TARGET_EXPR} is ``normal''; otherwise, we say it is
-``orphaned''. For a normal @code{TARGET_EXPR} the temporary variable
-should be treated as an alias for the left-hand side of the assignment,
-rather than as a new temporary variable.
-
-The third operand to the @code{TARGET_EXPR}, if present, is a
-cleanup-expression (i.e., destructor call) for the temporary. If this
-expression is orphaned, then this expression must be executed when the
-statement containing this expression is complete. These cleanups must
-always be executed in the order opposite to that in which they were
-encountered. Note that if a temporary is created on one branch of a
-conditional operator (i.e., in the second or third operand to a
-@code{COND_EXPR}), the cleanup must be run only if that branch is
-actually executed.
-
-@item VA_ARG_EXPR
-This node is used to implement support for the C/C++ variable argument-list
-mechanism. It represents expressions like @code{va_arg (ap, type)}.
-Its @code{TREE_TYPE} yields the tree representation for @code{type} and
-its sole argument yields the representation for @code{ap}.
-
-@item ANNOTATE_EXPR
-This node is used to attach markers to an expression. The first operand
-is the annotated expression, the second is an @code{INTEGER_CST} with
-a value from @code{enum annot_expr_kind}, the third is an @code{INTEGER_CST}.
-@end table
-
-
-@node Vectors
-@subsection Vectors
-@tindex VEC_DUPLICATE_EXPR
-@tindex VEC_SERIES_EXPR
-@tindex VEC_LSHIFT_EXPR
-@tindex VEC_RSHIFT_EXPR
-@tindex VEC_WIDEN_MULT_HI_EXPR
-@tindex VEC_WIDEN_MULT_LO_EXPR
-@tindex VEC_WIDEN_PLUS_HI_EXPR
-@tindex VEC_WIDEN_PLUS_LO_EXPR
-@tindex VEC_WIDEN_MINUS_HI_EXPR
-@tindex VEC_WIDEN_MINUS_LO_EXPR
-@tindex VEC_UNPACK_HI_EXPR
-@tindex VEC_UNPACK_LO_EXPR
-@tindex VEC_UNPACK_FLOAT_HI_EXPR
-@tindex VEC_UNPACK_FLOAT_LO_EXPR
-@tindex VEC_UNPACK_FIX_TRUNC_HI_EXPR
-@tindex VEC_UNPACK_FIX_TRUNC_LO_EXPR
-@tindex VEC_PACK_TRUNC_EXPR
-@tindex VEC_PACK_SAT_EXPR
-@tindex VEC_PACK_FIX_TRUNC_EXPR
-@tindex VEC_PACK_FLOAT_EXPR
-@tindex VEC_COND_EXPR
-@tindex SAD_EXPR
-
-@table @code
-@item VEC_DUPLICATE_EXPR
-This node has a single operand and represents a vector in which every
-element is equal to that operand.
-
-@item VEC_SERIES_EXPR
-This node represents a vector formed from a scalar base and step,
-given as the first and second operands respectively. Element @var{i}
-of the result is equal to @samp{@var{base} + @var{i}*@var{step}}.
-
-This node is restricted to integral types, in order to avoid
-specifying the rounding behavior for floating-point types.
-
-@item VEC_LSHIFT_EXPR
-@itemx VEC_RSHIFT_EXPR
-These nodes represent whole vector left and right shifts, respectively.
-The first operand is the vector to shift; it will always be of vector type.
-The second operand is an expression for the number of bits by which to
-shift. Note that the result is undefined if the second operand is larger
-than or equal to the first operand's type size.
-
-@item VEC_WIDEN_MULT_HI_EXPR
-@itemx VEC_WIDEN_MULT_LO_EXPR
-These nodes represent widening vector multiplication of the high and low
-parts of the two input vectors, respectively. Their operands are vectors
-that contain the same number of elements (@code{N}) of the same integral type.
-The result is a vector that contains half as many elements, of an integral type
-whose size is twice as wide. In the case of @code{VEC_WIDEN_MULT_HI_EXPR} the
-high @code{N/2} elements of the two vector are multiplied to produce the
-vector of @code{N/2} products. In the case of @code{VEC_WIDEN_MULT_LO_EXPR} the
-low @code{N/2} elements of the two vector are multiplied to produce the
-vector of @code{N/2} products.
-
-@item VEC_WIDEN_PLUS_HI_EXPR
-@itemx VEC_WIDEN_PLUS_LO_EXPR
-These nodes represent widening vector addition of the high and low parts of
-the two input vectors, respectively. Their operands are vectors that contain
-the same number of elements (@code{N}) of the same integral type. The result
-is a vector that contains half as many elements, of an integral type whose size
-is twice as wide. In the case of @code{VEC_WIDEN_PLUS_HI_EXPR} the high
-@code{N/2} elements of the two vectors are added to produce the vector of
-@code{N/2} products. In the case of @code{VEC_WIDEN_PLUS_LO_EXPR} the low
-@code{N/2} elements of the two vectors are added to produce the vector of
-@code{N/2} products.
-
-@item VEC_WIDEN_MINUS_HI_EXPR
-@itemx VEC_WIDEN_MINUS_LO_EXPR
-These nodes represent widening vector subtraction of the high and low parts of
-the two input vectors, respectively. Their operands are vectors that contain
-the same number of elements (@code{N}) of the same integral type. The high/low
-elements of the second vector are subtracted from the high/low elements of the
-first. The result is a vector that contains half as many elements, of an
-integral type whose size is twice as wide. In the case of
-@code{VEC_WIDEN_MINUS_HI_EXPR} the high @code{N/2} elements of the second
-vector are subtracted from the high @code{N/2} of the first to produce the
-vector of @code{N/2} products. In the case of
-@code{VEC_WIDEN_MINUS_LO_EXPR} the low @code{N/2} elements of the second
-vector are subtracted from the low @code{N/2} of the first to produce the
-vector of @code{N/2} products.
-
-@item VEC_UNPACK_HI_EXPR
-@itemx VEC_UNPACK_LO_EXPR
-These nodes represent unpacking of the high and low parts of the input vector,
-respectively. The single operand is a vector that contains @code{N} elements
-of the same integral or floating point type. The result is a vector
-that contains half as many elements, of an integral or floating point type
-whose size is twice as wide. In the case of @code{VEC_UNPACK_HI_EXPR} the
-high @code{N/2} elements of the vector are extracted and widened (promoted).
-In the case of @code{VEC_UNPACK_LO_EXPR} the low @code{N/2} elements of the
-vector are extracted and widened (promoted).
-
-@item VEC_UNPACK_FLOAT_HI_EXPR
-@itemx VEC_UNPACK_FLOAT_LO_EXPR
-These nodes represent unpacking of the high and low parts of the input vector,
-where the values are converted from fixed point to floating point. The
-single operand is a vector that contains @code{N} elements of the same
-integral type. The result is a vector that contains half as many elements
-of a floating point type whose size is twice as wide. In the case of
-@code{VEC_UNPACK_FLOAT_HI_EXPR} the high @code{N/2} elements of the vector are
-extracted, converted and widened. In the case of @code{VEC_UNPACK_FLOAT_LO_EXPR}
-the low @code{N/2} elements of the vector are extracted, converted and widened.
-
-@item VEC_UNPACK_FIX_TRUNC_HI_EXPR
-@itemx VEC_UNPACK_FIX_TRUNC_LO_EXPR
-These nodes represent unpacking of the high and low parts of the input vector,
-where the values are truncated from floating point to fixed point. The
-single operand is a vector that contains @code{N} elements of the same
-floating point type. The result is a vector that contains half as many
-elements of an integral type whose size is twice as wide. In the case of
-@code{VEC_UNPACK_FIX_TRUNC_HI_EXPR} the high @code{N/2} elements of the
-vector are extracted and converted with truncation. In the case of
-@code{VEC_UNPACK_FIX_TRUNC_LO_EXPR} the low @code{N/2} elements of the
-vector are extracted and converted with truncation.
-
-@item VEC_PACK_TRUNC_EXPR
-This node represents packing of truncated elements of the two input vectors
-into the output vector. Input operands are vectors that contain the same
-number of elements of the same integral or floating point type. The result
-is a vector that contains twice as many elements of an integral or floating
-point type whose size is half as wide. The elements of the two vectors are
-demoted and merged (concatenated) to form the output vector.
-
-@item VEC_PACK_SAT_EXPR
-This node represents packing of elements of the two input vectors into the
-output vector using saturation. Input operands are vectors that contain
-the same number of elements of the same integral type. The result is a
-vector that contains twice as many elements of an integral type whose size
-is half as wide. The elements of the two vectors are demoted and merged
-(concatenated) to form the output vector.
-
-@item VEC_PACK_FIX_TRUNC_EXPR
-This node represents packing of elements of the two input vectors into the
-output vector, where the values are converted from floating point
-to fixed point. Input operands are vectors that contain the same number
-of elements of a floating point type. The result is a vector that contains
-twice as many elements of an integral type whose size is half as wide. The
-elements of the two vectors are merged (concatenated) to form the output
-vector.
-
-@item VEC_PACK_FLOAT_EXPR
-This node represents packing of elements of the two input vectors into the
-output vector, where the values are converted from fixed point to floating
-point. Input operands are vectors that contain the same number of elements
-of an integral type. The result is a vector that contains twice as many
-elements of floating point type whose size is half as wide. The elements of
-the two vectors are merged (concatenated) to form the output vector.
-
-@item VEC_COND_EXPR
-These nodes represent @code{?:} expressions. The three operands must be
-vectors of the same size and number of elements. The second and third
-operands must have the same type as the entire expression. The first
-operand is of signed integral vector type. If an element of the first
-operand evaluates to a zero value, the corresponding element of the
-result is taken from the third operand. If it evaluates to a minus one
-value, it is taken from the second operand. It should never evaluate to
-any other value currently, but optimizations should not rely on that
-property. In contrast with a @code{COND_EXPR}, all operands are always
-evaluated.
-
-@item SAD_EXPR
-This node represents the Sum of Absolute Differences operation. The three
-operands must be vectors of integral types. The first and second operand
-must have the same type. The size of the vector element of the third
-operand must be at lease twice of the size of the vector element of the
-first and second one. The SAD is calculated between the first and second
-operands, added to the third operand, and returned.
-
-@end table
-
-
-@c ---------------------------------------------------------------------
-@c Statements
-@c ---------------------------------------------------------------------
-
-@node Statements
-@section Statements
-@cindex Statements
-
-Most statements in GIMPLE are assignment statements, represented by
-@code{GIMPLE_ASSIGN}. No other C expressions can appear at statement level;
-a reference to a volatile object is converted into a
-@code{GIMPLE_ASSIGN}.
-
-There are also several varieties of complex statements.
-
-@menu
-* Basic Statements::
-* Blocks::
-* Statement Sequences::
-* Empty Statements::
-* Jumps::
-* Cleanups::
-* OpenMP::
-* OpenACC::
-@end menu
-
-@node Basic Statements
-@subsection Basic Statements
-@cindex Basic Statements
-
-@table @code
-@item ASM_EXPR
-
-Used to represent an inline assembly statement. For an inline assembly
-statement like:
-@smallexample
-asm ("mov x, y");
-@end smallexample
-The @code{ASM_STRING} macro will return a @code{STRING_CST} node for
-@code{"mov x, y"}. If the original statement made use of the
-extended-assembly syntax, then @code{ASM_OUTPUTS},
-@code{ASM_INPUTS}, and @code{ASM_CLOBBERS} will be the outputs, inputs,
-and clobbers for the statement, represented as @code{STRING_CST} nodes.
-The extended-assembly syntax looks like:
-@smallexample
-asm ("fsinx %1,%0" : "=f" (result) : "f" (angle));
-@end smallexample
-The first string is the @code{ASM_STRING}, containing the instruction
-template. The next two strings are the output and inputs, respectively;
-this statement has no clobbers. As this example indicates, ``plain''
-assembly statements are merely a special case of extended assembly
-statements; they have no cv-qualifiers, outputs, inputs, or clobbers.
-All of the strings will be @code{NUL}-terminated, and will contain no
-embedded @code{NUL}-characters.
-
-If the assembly statement is declared @code{volatile}, or if the
-statement was not an extended assembly statement, and is therefore
-implicitly volatile, then the predicate @code{ASM_VOLATILE_P} will hold
-of the @code{ASM_EXPR}.
-
-@item DECL_EXPR
-
-Used to represent a local declaration. The @code{DECL_EXPR_DECL} macro
-can be used to obtain the entity declared. This declaration may be a
-@code{LABEL_DECL}, indicating that the label declared is a local label.
-(As an extension, GCC allows the declaration of labels with scope.) In
-C, this declaration may be a @code{FUNCTION_DECL}, indicating the
-use of the GCC nested function extension. For more information,
-@pxref{Functions}.
-
-@item LABEL_EXPR
-
-Used to represent a label. The @code{LABEL_DECL} declared by this
-statement can be obtained with the @code{LABEL_EXPR_LABEL} macro. The
-@code{IDENTIFIER_NODE} giving the name of the label can be obtained from
-the @code{LABEL_DECL} with @code{DECL_NAME}.
-
-@item GOTO_EXPR
-
-Used to represent a @code{goto} statement. The @code{GOTO_DESTINATION} will
-usually be a @code{LABEL_DECL}. However, if the ``computed goto'' extension
-has been used, the @code{GOTO_DESTINATION} will be an arbitrary expression
-indicating the destination. This expression will always have pointer type.
-
-@item RETURN_EXPR
-
-Used to represent a @code{return} statement. Operand 0 represents the
-value to return. It should either be the @code{RESULT_DECL} for the
-containing function, or a @code{MODIFY_EXPR} or @code{INIT_EXPR}
-setting the function's @code{RESULT_DECL}. It will be
-@code{NULL_TREE} if the statement was just
-@smallexample
-return;
-@end smallexample
-
-@item LOOP_EXPR
-These nodes represent ``infinite'' loops. The @code{LOOP_EXPR_BODY}
-represents the body of the loop. It should be executed forever, unless
-an @code{EXIT_EXPR} is encountered.
-
-@item EXIT_EXPR
-These nodes represent conditional exits from the nearest enclosing
-@code{LOOP_EXPR}. The single operand is the condition; if it is
-nonzero, then the loop should be exited. An @code{EXIT_EXPR} will only
-appear within a @code{LOOP_EXPR}.
-
-@item SWITCH_EXPR
-
-Used to represent a @code{switch} statement. The @code{SWITCH_COND}
-is the expression on which the switch is occurring. The
-@code{SWITCH_BODY} is the body of the switch statement.
-@code{SWITCH_ALL_CASES_P} is true if the switch includes a default
-label or the case label ranges cover all possible values of the
-condition expression.
-
-Note that @code{TREE_TYPE} for a @code{SWITCH_EXPR} represents the
-original type of switch expression as given in the source, before any
-compiler conversions, instead of the type of the switch expression
-itself (which is not meaningful).
-
-@item CASE_LABEL_EXPR
-
-Use to represent a @code{case} label, range of @code{case} labels, or a
-@code{default} label. If @code{CASE_LOW} is @code{NULL_TREE}, then this is a
-@code{default} label. Otherwise, if @code{CASE_HIGH} is @code{NULL_TREE}, then
-this is an ordinary @code{case} label. In this case, @code{CASE_LOW} is
-an expression giving the value of the label. Both @code{CASE_LOW} and
-@code{CASE_HIGH} are @code{INTEGER_CST} nodes. These values will have
-the same type as the condition expression in the switch statement.
-
-Otherwise, if both @code{CASE_LOW} and @code{CASE_HIGH} are defined, the
-statement is a range of case labels. Such statements originate with the
-extension that allows users to write things of the form:
-@smallexample
-case 2 ... 5:
-@end smallexample
-The first value will be @code{CASE_LOW}, while the second will be
-@code{CASE_HIGH}.
-
-@item DEBUG_BEGIN_STMT
-
-Marks the beginning of a source statement, for purposes of debug
-information generation.
-
-@end table
-
-
-@node Blocks
-@subsection Blocks
-@cindex Blocks
-
-Block scopes and the variables they declare in GENERIC are
-expressed using the @code{BIND_EXPR} code, which in previous
-versions of GCC was primarily used for the C statement-expression
-extension.
-
-Variables in a block are collected into @code{BIND_EXPR_VARS} in
-declaration order through their @code{TREE_CHAIN} field. Any runtime
-initialization is moved out of @code{DECL_INITIAL} and into a
-statement in the controlled block. When gimplifying from C or C++,
-this initialization replaces the @code{DECL_STMT}. These variables
-will never require cleanups. The scope of these variables is just the
-body
-
-Variable-length arrays (VLAs) complicate this process, as their size
-often refers to variables initialized earlier in the block and their
-initialization involves an explicit stack allocation. To handle this,
-we add an indirection and replace them with a pointer to stack space
-allocated by means of @code{alloca}. In most cases, we also arrange
-for this space to be reclaimed when the enclosing @code{BIND_EXPR} is
-exited, the exception to this being when there is an explicit call to
-@code{alloca} in the source code, in which case the stack is left
-depressed on exit of the @code{BIND_EXPR}.
-
-A C++ program will usually contain more @code{BIND_EXPR}s than
-there are syntactic blocks in the source code, since several C++
-constructs have implicit scopes associated with them. On the
-other hand, although the C++ front end uses pseudo-scopes to
-handle cleanups for objects with destructors, these don't
-translate into the GIMPLE form; multiple declarations at the same
-level use the same @code{BIND_EXPR}.
-
-@node Statement Sequences
-@subsection Statement Sequences
-@cindex Statement Sequences
-
-Multiple statements at the same nesting level are collected into
-a @code{STATEMENT_LIST}. Statement lists are modified and
-traversed using the interface in @samp{tree-iterator.h}.
-
-@node Empty Statements
-@subsection Empty Statements
-@cindex Empty Statements
-
-Whenever possible, statements with no effect are discarded. But
-if they are nested within another construct which cannot be
-discarded for some reason, they are instead replaced with an
-empty statement, generated by @code{build_empty_stmt}.
-Initially, all empty statements were shared, after the pattern of
-the Java front end, but this caused a lot of trouble in practice.
-
-An empty statement is represented as @code{(void)0}.
-
-@node Jumps
-@subsection Jumps
-@cindex Jumps
-
-Other jumps are expressed by either @code{GOTO_EXPR} or
-@code{RETURN_EXPR}.
-
-The operand of a @code{GOTO_EXPR} must be either a label or a
-variable containing the address to jump to.
-
-The operand of a @code{RETURN_EXPR} is either @code{NULL_TREE},
-@code{RESULT_DECL}, or a @code{MODIFY_EXPR} which sets the return
-value. It would be nice to move the @code{MODIFY_EXPR} into a
-separate statement, but the special return semantics in
-@code{expand_return} make that difficult. It may still happen in
-the future, perhaps by moving most of that logic into
-@code{expand_assignment}.
-
-@node Cleanups
-@subsection Cleanups
-@cindex Cleanups
-
-Destructors for local C++ objects and similar dynamic cleanups are
-represented in GIMPLE by a @code{TRY_FINALLY_EXPR}.
-@code{TRY_FINALLY_EXPR} has two operands, both of which are a sequence
-of statements to execute. The first sequence is executed. When it
-completes the second sequence is executed.
-
-The first sequence may complete in the following ways:
-
-@enumerate
-
-@item Execute the last statement in the sequence and fall off the
-end.
-
-@item Execute a goto statement (@code{GOTO_EXPR}) to an ordinary
-label outside the sequence.
-
-@item Execute a return statement (@code{RETURN_EXPR}).
-
-@item Throw an exception. This is currently not explicitly represented in
-GIMPLE.
-
-@end enumerate
-
-The second sequence is not executed if the first sequence completes by
-calling @code{setjmp} or @code{exit} or any other function that does
-not return. The second sequence is also not executed if the first
-sequence completes via a non-local goto or a computed goto (in general
-the compiler does not know whether such a goto statement exits the
-first sequence or not, so we assume that it doesn't).
-
-After the second sequence is executed, if it completes normally by
-falling off the end, execution continues wherever the first sequence
-would have continued, by falling off the end, or doing a goto, etc.
-
-If the second sequence is an @code{EH_ELSE_EXPR} selector, then the
-sequence in its first operand is used when the first sequence completes
-normally, and that in its second operand is used for exceptional
-cleanups, i.e., when an exception propagates out of the first sequence.
-
-@code{TRY_FINALLY_EXPR} complicates the flow graph, since the cleanup
-needs to appear on every edge out of the controlled block; this
-reduces the freedom to move code across these edges. Therefore, the
-EH lowering pass which runs before most of the optimization passes
-eliminates these expressions by explicitly adding the cleanup to each
-edge. Rethrowing the exception is represented using @code{RESX_EXPR}.
-
-@node OpenMP
-@subsection OpenMP
-@tindex OMP_PARALLEL
-@tindex OMP_FOR
-@tindex OMP_SECTIONS
-@tindex OMP_SINGLE
-@tindex OMP_SECTION
-@tindex OMP_MASTER
-@tindex OMP_ORDERED
-@tindex OMP_CRITICAL
-@tindex OMP_RETURN
-@tindex OMP_CONTINUE
-@tindex OMP_ATOMIC
-@tindex OMP_CLAUSE
-
-All the statements starting with @code{OMP_} represent directives and
-clauses used by the OpenMP API @w{@uref{https://www.openmp.org}}.
-
-@table @code
-@item OMP_PARALLEL
-
-Represents @code{#pragma omp parallel [clause1 @dots{} clauseN]}. It
-has four operands:
-
-Operand @code{OMP_PARALLEL_BODY} is valid while in GENERIC and
-High GIMPLE forms. It contains the body of code to be executed
-by all the threads. During GIMPLE lowering, this operand becomes
-@code{NULL} and the body is emitted linearly after
-@code{OMP_PARALLEL}.
-
-Operand @code{OMP_PARALLEL_CLAUSES} is the list of clauses
-associated with the directive.
-
-Operand @code{OMP_PARALLEL_FN} is created by
-@code{pass_lower_omp}, it contains the @code{FUNCTION_DECL}
-for the function that will contain the body of the parallel
-region.
-
-Operand @code{OMP_PARALLEL_DATA_ARG} is also created by
-@code{pass_lower_omp}. If there are shared variables to be
-communicated to the children threads, this operand will contain
-the @code{VAR_DECL} that contains all the shared values and
-variables.
-
-@item OMP_FOR
-
-Represents @code{#pragma omp for [clause1 @dots{} clauseN]}. It has
-six operands:
-
-Operand @code{OMP_FOR_BODY} contains the loop body.
-
-Operand @code{OMP_FOR_CLAUSES} is the list of clauses
-associated with the directive.
-
-Operand @code{OMP_FOR_INIT} is the loop initialization code of
-the form @code{VAR = N1}.
-
-Operand @code{OMP_FOR_COND} is the loop conditional expression
-of the form @code{VAR @{<,>,<=,>=@} N2}.
-
-Operand @code{OMP_FOR_INCR} is the loop index increment of the
-form @code{VAR @{+=,-=@} INCR}.
-
-Operand @code{OMP_FOR_PRE_BODY} contains side effect code from
-operands @code{OMP_FOR_INIT}, @code{OMP_FOR_COND} and
-@code{OMP_FOR_INC}. These side effects are part of the
-@code{OMP_FOR} block but must be evaluated before the start of
-loop body.
-
-The loop index variable @code{VAR} must be a signed integer variable,
-which is implicitly private to each thread. Bounds
-@code{N1} and @code{N2} and the increment expression
-@code{INCR} are required to be loop invariant integer
-expressions that are evaluated without any synchronization. The
-evaluation order, frequency of evaluation and side effects are
-unspecified by the standard.
-
-@item OMP_SECTIONS
-
-Represents @code{#pragma omp sections [clause1 @dots{} clauseN]}.
-
-Operand @code{OMP_SECTIONS_BODY} contains the sections body,
-which in turn contains a set of @code{OMP_SECTION} nodes for
-each of the concurrent sections delimited by @code{#pragma omp
-section}.
-
-Operand @code{OMP_SECTIONS_CLAUSES} is the list of clauses
-associated with the directive.
-
-@item OMP_SECTION
-
-Section delimiter for @code{OMP_SECTIONS}.
-
-@item OMP_SINGLE
-
-Represents @code{#pragma omp single}.
-
-Operand @code{OMP_SINGLE_BODY} contains the body of code to be
-executed by a single thread.
-
-Operand @code{OMP_SINGLE_CLAUSES} is the list of clauses
-associated with the directive.
-
-@item OMP_MASTER
-
-Represents @code{#pragma omp master}.
-
-Operand @code{OMP_MASTER_BODY} contains the body of code to be
-executed by the master thread.
-
-@item OMP_ORDERED
-
-Represents @code{#pragma omp ordered}.
-
-Operand @code{OMP_ORDERED_BODY} contains the body of code to be
-executed in the sequential order dictated by the loop index
-variable.
-
-@item OMP_CRITICAL
-
-Represents @code{#pragma omp critical [name]}.
-
-Operand @code{OMP_CRITICAL_BODY} is the critical section.
-
-Operand @code{OMP_CRITICAL_NAME} is an optional identifier to
-label the critical section.
-
-@item OMP_RETURN
-
-This does not represent any OpenMP directive, it is an artificial
-marker to indicate the end of the body of an OpenMP@. It is used
-by the flow graph (@code{tree-cfg.cc}) and OpenMP region
-building code (@code{omp-low.cc}).
-
-@item OMP_CONTINUE
-
-Similarly, this instruction does not represent an OpenMP
-directive, it is used by @code{OMP_FOR} (and similar codes) as well as
-@code{OMP_SECTIONS} to mark the place where the code needs to
-loop to the next iteration, or the next section, respectively.
-
-In some cases, @code{OMP_CONTINUE} is placed right before
-@code{OMP_RETURN}. But if there are cleanups that need to
-occur right after the looping body, it will be emitted between
-@code{OMP_CONTINUE} and @code{OMP_RETURN}.
-
-@item OMP_ATOMIC
-
-Represents @code{#pragma omp atomic}.
-
-Operand 0 is the address at which the atomic operation is to be
-performed.
-
-Operand 1 is the expression to evaluate. The gimplifier tries
-three alternative code generation strategies. Whenever possible,
-an atomic update built-in is used. If that fails, a
-compare-and-swap loop is attempted. If that also fails, a
-regular critical section around the expression is used.
-
-@item OMP_CLAUSE
-
-Represents clauses associated with one of the @code{OMP_} directives.
-Clauses are represented by separate subcodes defined in
-@file{tree.h}. Clauses codes can be one of:
-@code{OMP_CLAUSE_PRIVATE}, @code{OMP_CLAUSE_SHARED},
-@code{OMP_CLAUSE_FIRSTPRIVATE},
-@code{OMP_CLAUSE_LASTPRIVATE}, @code{OMP_CLAUSE_COPYIN},
-@code{OMP_CLAUSE_COPYPRIVATE}, @code{OMP_CLAUSE_IF},
-@code{OMP_CLAUSE_NUM_THREADS}, @code{OMP_CLAUSE_SCHEDULE},
-@code{OMP_CLAUSE_NOWAIT}, @code{OMP_CLAUSE_ORDERED},
-@code{OMP_CLAUSE_DEFAULT}, @code{OMP_CLAUSE_REDUCTION},
-@code{OMP_CLAUSE_COLLAPSE}, @code{OMP_CLAUSE_UNTIED},
-@code{OMP_CLAUSE_FINAL}, and @code{OMP_CLAUSE_MERGEABLE}. Each code
-represents the corresponding OpenMP clause.
-
-Clauses associated with the same directive are chained together
-via @code{OMP_CLAUSE_CHAIN}. Those clauses that accept a list
-of variables are restricted to exactly one, accessed with
-@code{OMP_CLAUSE_VAR}. Therefore, multiple variables under the
-same clause @code{C} need to be represented as multiple @code{C} clauses
-chained together. This facilitates adding new clauses during
-compilation.
-
-@end table
-
-@node OpenACC
-@subsection OpenACC
-@tindex OACC_CACHE
-@tindex OACC_DATA
-@tindex OACC_DECLARE
-@tindex OACC_ENTER_DATA
-@tindex OACC_EXIT_DATA
-@tindex OACC_HOST_DATA
-@tindex OACC_KERNELS
-@tindex OACC_LOOP
-@tindex OACC_PARALLEL
-@tindex OACC_SERIAL
-@tindex OACC_UPDATE
-
-All the statements starting with @code{OACC_} represent directives and
-clauses used by the OpenACC API @w{@uref{https://www.openacc.org}}.
-
-@table @code
-@item OACC_CACHE
-
-Represents @code{#pragma acc cache (var @dots{})}.
-
-@item OACC_DATA
-
-Represents @code{#pragma acc data [clause1 @dots{} clauseN]}.
-
-@item OACC_DECLARE
-
-Represents @code{#pragma acc declare [clause1 @dots{} clauseN]}.
-
-@item OACC_ENTER_DATA
-
-Represents @code{#pragma acc enter data [clause1 @dots{} clauseN]}.
-
-@item OACC_EXIT_DATA
-
-Represents @code{#pragma acc exit data [clause1 @dots{} clauseN]}.
-
-@item OACC_HOST_DATA
-
-Represents @code{#pragma acc host_data [clause1 @dots{} clauseN]}.
-
-@item OACC_KERNELS
-
-Represents @code{#pragma acc kernels [clause1 @dots{} clauseN]}.
-
-@item OACC_LOOP
-
-Represents @code{#pragma acc loop [clause1 @dots{} clauseN]}.
-
-See the description of the @code{OMP_FOR} code.
-
-@item OACC_PARALLEL
-
-Represents @code{#pragma acc parallel [clause1 @dots{} clauseN]}.
-
-@item OACC_SERIAL
-
-Represents @code{#pragma acc serial [clause1 @dots{} clauseN]}.
-
-@item OACC_UPDATE
-
-Represents @code{#pragma acc update [clause1 @dots{} clauseN]}.
-
-@end table
-
-@c ---------------------------------------------------------------------
-@c Functions
-@c ---------------------------------------------------------------------
-
-@node Functions
-@section Functions
-@cindex function
-@tindex FUNCTION_DECL
-
-A function is represented by a @code{FUNCTION_DECL} node. It stores
-the basic pieces of the function such as body, parameters, and return
-type as well as information on the surrounding context, visibility,
-and linkage.
-
-@menu
-* Function Basics:: Function names, body, and parameters.
-* Function Properties:: Context, linkage, etc.
-@end menu
-
-@c ---------------------------------------------------------------------
-@c Function Basics
-@c ---------------------------------------------------------------------
-
-@node Function Basics
-@subsection Function Basics
-@findex DECL_NAME
-@findex DECL_ASSEMBLER_NAME
-@findex TREE_PUBLIC
-@findex DECL_ARTIFICIAL
-@findex DECL_FUNCTION_SPECIFIC_TARGET
-@findex DECL_FUNCTION_SPECIFIC_OPTIMIZATION
-
-A function has four core parts: the name, the parameters, the result,
-and the body. The following macros and functions access these parts
-of a @code{FUNCTION_DECL} as well as other basic features:
-@ftable @code
-@item DECL_NAME
-This macro returns the unqualified name of the function, as an
-@code{IDENTIFIER_NODE}. For an instantiation of a function template,
-the @code{DECL_NAME} is the unqualified name of the template, not
-something like @code{f<int>}. The value of @code{DECL_NAME} is
-undefined when used on a constructor, destructor, overloaded operator,
-or type-conversion operator, or any function that is implicitly
-generated by the compiler. See below for macros that can be used to
-distinguish these cases.
-
-@item DECL_ASSEMBLER_NAME
-This macro returns the mangled name of the function, also an
-@code{IDENTIFIER_NODE}. This name does not contain leading underscores
-on systems that prefix all identifiers with underscores. The mangled
-name is computed in the same way on all platforms; if special processing
-is required to deal with the object file format used on a particular
-platform, it is the responsibility of the back end to perform those
-modifications. (Of course, the back end should not modify
-@code{DECL_ASSEMBLER_NAME} itself.)
-
-Using @code{DECL_ASSEMBLER_NAME} will cause additional memory to be
-allocated (for the mangled name of the entity) so it should be used
-only when emitting assembly code. It should not be used within the
-optimizers to determine whether or not two declarations are the same,
-even though some of the existing optimizers do use it in that way.
-These uses will be removed over time.
-
-@item DECL_ARGUMENTS
-This macro returns the @code{PARM_DECL} for the first argument to the
-function. Subsequent @code{PARM_DECL} nodes can be obtained by
-following the @code{TREE_CHAIN} links.
-
-@item DECL_RESULT
-This macro returns the @code{RESULT_DECL} for the function.
-
-@item DECL_SAVED_TREE
-This macro returns the complete body of the function.
-
-@item TREE_TYPE
-This macro returns the @code{FUNCTION_TYPE} or @code{METHOD_TYPE} for
-the function.
-
-@item DECL_INITIAL
-A function that has a definition in the current translation unit will
-have a non-@code{NULL} @code{DECL_INITIAL}. However, back ends should not make
-use of the particular value given by @code{DECL_INITIAL}.
-
-It should contain a tree of @code{BLOCK} nodes that mirrors the scopes
-that variables are bound in the function. Each block contains a list
-of decls declared in a basic block, a pointer to a chain of blocks at
-the next lower scope level, then a pointer to the next block at the
-same level and a backpointer to the parent @code{BLOCK} or
-@code{FUNCTION_DECL}. So given a function as follows:
-
-@smallexample
-void foo()
-@{
- int a;
- @{
- int b;
- @}
- int c;
-@}
-@end smallexample
-
-you would get the following:
-
-@smallexample
-tree foo = FUNCTION_DECL;
-tree decl_a = VAR_DECL;
-tree decl_b = VAR_DECL;
-tree decl_c = VAR_DECL;
-tree block_a = BLOCK;
-tree block_b = BLOCK;
-tree block_c = BLOCK;
-BLOCK_VARS(block_a) = decl_a;
-BLOCK_SUBBLOCKS(block_a) = block_b;
-BLOCK_CHAIN(block_a) = block_c;
-BLOCK_SUPERCONTEXT(block_a) = foo;
-BLOCK_VARS(block_b) = decl_b;
-BLOCK_SUPERCONTEXT(block_b) = block_a;
-BLOCK_VARS(block_c) = decl_c;
-BLOCK_SUPERCONTEXT(block_c) = foo;
-DECL_INITIAL(foo) = block_a;
-@end smallexample
-
-@end ftable
-
-@c ---------------------------------------------------------------------
-@c Function Properties
-@c ---------------------------------------------------------------------
-
-@node Function Properties
-@subsection Function Properties
-@cindex function properties
-@cindex statements
-
-To determine the scope of a function, you can use the
-@code{DECL_CONTEXT} macro. This macro will return the class
-(either a @code{RECORD_TYPE} or a @code{UNION_TYPE}) or namespace (a
-@code{NAMESPACE_DECL}) of which the function is a member. For a virtual
-function, this macro returns the class in which the function was
-actually defined, not the base class in which the virtual declaration
-occurred.
-
-In C, the @code{DECL_CONTEXT} for a function maybe another function.
-This representation indicates that the GNU nested function extension
-is in use. For details on the semantics of nested functions, see the
-GCC Manual. The nested function can refer to local variables in its
-containing function. Such references are not explicitly marked in the
-tree structure; back ends must look at the @code{DECL_CONTEXT} for the
-referenced @code{VAR_DECL}. If the @code{DECL_CONTEXT} for the
-referenced @code{VAR_DECL} is not the same as the function currently
-being processed, and neither @code{DECL_EXTERNAL} nor
-@code{TREE_STATIC} hold, then the reference is to a local variable in
-a containing function, and the back end must take appropriate action.
-
-@ftable @code
-@item DECL_EXTERNAL
-This predicate holds if the function is undefined.
-
-@item TREE_PUBLIC
-This predicate holds if the function has external linkage.
-
-@item TREE_STATIC
-This predicate holds if the function has been defined.
-
-@item TREE_THIS_VOLATILE
-This predicate holds if the function does not return normally.
-
-@item TREE_READONLY
-This predicate holds if the function can only read its arguments.
-
-@item DECL_PURE_P
-This predicate holds if the function can only read its arguments, but
-may also read global memory.
-
-@item DECL_VIRTUAL_P
-This predicate holds if the function is virtual.
-
-@item DECL_ARTIFICIAL
-This macro holds if the function was implicitly generated by the
-compiler, rather than explicitly declared. In addition to implicitly
-generated class member functions, this macro holds for the special
-functions created to implement static initialization and destruction, to
-compute run-time type information, and so forth.
-
-@item DECL_FUNCTION_SPECIFIC_TARGET
-This macro returns a tree node that holds the target options that are
-to be used to compile this particular function or @code{NULL_TREE} if
-the function is to be compiled with the target options specified on
-the command line.
-
-@item DECL_FUNCTION_SPECIFIC_OPTIMIZATION
-This macro returns a tree node that holds the optimization options
-that are to be used to compile this particular function or
-@code{NULL_TREE} if the function is to be compiled with the
-optimization options specified on the command line.
-
-@end ftable
-
-@c ---------------------------------------------------------------------
-@c Language-dependent trees
-@c ---------------------------------------------------------------------
-
-@node Language-dependent trees
-@section Language-dependent trees
-@cindex language-dependent trees
-
-Front ends may wish to keep some state associated with various GENERIC
-trees while parsing. To support this, trees provide a set of flags
-that may be used by the front end. They are accessed using
-@code{TREE_LANG_FLAG_n} where @samp{n} is currently 0 through 6.
-
-If necessary, a front end can use some language-dependent tree
-codes in its GENERIC representation, so long as it provides a
-hook for converting them to GIMPLE and doesn't expect them to
-work with any (hypothetical) optimizers that run before the
-conversion to GIMPLE@. The intermediate representation used while
-parsing C and C++ looks very little like GENERIC, but the C and
-C++ gimplifier hooks are perfectly happy to take it as input and
-spit out GIMPLE@.
-
-
-
-@node C and C++ Trees
-@section C and C++ Trees
-
-This section documents the internal representation used by GCC to
-represent C and C++ source programs. When presented with a C or C++
-source program, GCC parses the program, performs semantic analysis
-(including the generation of error messages), and then produces the
-internal representation described here. This representation contains a
-complete representation for the entire translation unit provided as
-input to the front end. This representation is then typically processed
-by a code-generator in order to produce machine code, but could also be
-used in the creation of source browsers, intelligent editors, automatic
-documentation generators, interpreters, and any other programs needing
-the ability to process C or C++ code.
-
-This section explains the internal representation. In particular, it
-documents the internal representation for C and C++ source
-constructs, and the macros, functions, and variables that can be used to
-access these constructs. The C++ representation is largely a superset
-of the representation used in the C front end. There is only one
-construct used in C that does not appear in the C++ front end and that
-is the GNU ``nested function'' extension. Many of the macros documented
-here do not apply in C because the corresponding language constructs do
-not appear in C@.
-
-The C and C++ front ends generate a mix of GENERIC trees and ones
-specific to C and C++. These language-specific trees are higher-level
-constructs than the ones in GENERIC to make the parser's job easier.
-This section describes those trees that aren't part of GENERIC as well
-as aspects of GENERIC trees that are treated in a language-specific
-manner.
-
-If you are developing a ``back end'', be it is a code-generator or some
-other tool, that uses this representation, you may occasionally find
-that you need to ask questions not easily answered by the functions and
-macros available here. If that situation occurs, it is quite likely
-that GCC already supports the functionality you desire, but that the
-interface is simply not documented here. In that case, you should ask
-the GCC maintainers (via mail to @email{gcc@@gcc.gnu.org}) about
-documenting the functionality you require. Similarly, if you find
-yourself writing functions that do not deal directly with your back end,
-but instead might be useful to other people using the GCC front end, you
-should submit your patches for inclusion in GCC@.
-
-@menu
-* Types for C++:: Fundamental and aggregate types.
-* Namespaces:: Namespaces.
-* Classes:: Classes.
-* Functions for C++:: Overloading and accessors for C++.
-* Statements for C and C++:: Statements specific to C and C++.
-* C++ Expressions:: From @code{typeid} to @code{throw}.
-@end menu
-
-@node Types for C++
-@subsection Types for C++
-@tindex UNKNOWN_TYPE
-@tindex TYPENAME_TYPE
-@tindex TYPEOF_TYPE
-@findex cp_type_quals
-@findex TYPE_UNQUALIFIED
-@findex TYPE_QUAL_CONST
-@findex TYPE_QUAL_VOLATILE
-@findex TYPE_QUAL_RESTRICT
-@findex TYPE_MAIN_VARIANT
-@cindex qualified type
-@findex TYPE_SIZE
-@findex TYPE_ALIGN
-@findex TYPE_PRECISION
-@findex TYPE_ARG_TYPES
-@findex TYPE_METHOD_BASETYPE
-@findex TYPE_PTRDATAMEM_P
-@findex TYPE_OFFSET_BASETYPE
-@findex TREE_TYPE
-@findex TYPE_CONTEXT
-@findex TYPE_NAME
-@findex TYPENAME_TYPE_FULLNAME
-@findex TYPE_FIELDS
-@findex TYPE_PTROBV_P
-
-In C++, an array type is not qualified; rather the type of the array
-elements is qualified. This situation is reflected in the intermediate
-representation. The macros described here will always examine the
-qualification of the underlying element type when applied to an array
-type. (If the element type is itself an array, then the recursion
-continues until a non-array type is found, and the qualification of this
-type is examined.) So, for example, @code{CP_TYPE_CONST_P} will hold of
-the type @code{const int ()[7]}, denoting an array of seven @code{int}s.
-
-The following functions and macros deal with cv-qualification of types:
-@ftable @code
-@item cp_type_quals
-This function returns the set of type qualifiers applied to this type.
-This value is @code{TYPE_UNQUALIFIED} if no qualifiers have been
-applied. The @code{TYPE_QUAL_CONST} bit is set if the type is
-@code{const}-qualified. The @code{TYPE_QUAL_VOLATILE} bit is set if the
-type is @code{volatile}-qualified. The @code{TYPE_QUAL_RESTRICT} bit is
-set if the type is @code{restrict}-qualified.
-
-@item CP_TYPE_CONST_P
-This macro holds if the type is @code{const}-qualified.
-
-@item CP_TYPE_VOLATILE_P
-This macro holds if the type is @code{volatile}-qualified.
-
-@item CP_TYPE_RESTRICT_P
-This macro holds if the type is @code{restrict}-qualified.
-
-@item CP_TYPE_CONST_NON_VOLATILE_P
-This predicate holds for a type that is @code{const}-qualified, but
-@emph{not} @code{volatile}-qualified; other cv-qualifiers are ignored as
-well: only the @code{const}-ness is tested.
-
-@end ftable
-
-A few other macros and functions are usable with all types:
-@ftable @code
-@item TYPE_SIZE
-The number of bits required to represent the type, represented as an
-@code{INTEGER_CST}. For an incomplete type, @code{TYPE_SIZE} will be
-@code{NULL_TREE}.
-
-@item TYPE_ALIGN
-The alignment of the type, in bits, represented as an @code{int}.
-
-@item TYPE_NAME
-This macro returns a declaration (in the form of a @code{TYPE_DECL}) for
-the type. (Note this macro does @emph{not} return an
-@code{IDENTIFIER_NODE}, as you might expect, given its name!) You can
-look at the @code{DECL_NAME} of the @code{TYPE_DECL} to obtain the
-actual name of the type. The @code{TYPE_NAME} will be @code{NULL_TREE}
-for a type that is not a built-in type, the result of a typedef, or a
-named class type.
-
-@item CP_INTEGRAL_TYPE
-This predicate holds if the type is an integral type. Notice that in
-C++, enumerations are @emph{not} integral types.
-
-@item ARITHMETIC_TYPE_P
-This predicate holds if the type is an integral type (in the C++ sense)
-or a floating point type.
-
-@item CLASS_TYPE_P
-This predicate holds for a class-type.
-
-@item TYPE_BUILT_IN
-This predicate holds for a built-in type.
-
-@item TYPE_PTRDATAMEM_P
-This predicate holds if the type is a pointer to data member.
-
-@item TYPE_PTR_P
-This predicate holds if the type is a pointer type, and the pointee is
-not a data member.
-
-@item TYPE_PTRFN_P
-This predicate holds for a pointer to function type.
-
-@item TYPE_PTROB_P
-This predicate holds for a pointer to object type. Note however that it
-does not hold for the generic pointer to object type @code{void *}. You
-may use @code{TYPE_PTROBV_P} to test for a pointer to object type as
-well as @code{void *}.
-
-@end ftable
-
-The table below describes types specific to C and C++ as well as
-language-dependent info about GENERIC types.
-
-@table @code
-
-@item POINTER_TYPE
-Used to represent pointer types, and pointer to data member types. If
-@code{TREE_TYPE}
-is a pointer to data member type, then @code{TYPE_PTRDATAMEM_P} will hold.
-For a pointer to data member type of the form @samp{T X::*},
-@code{TYPE_PTRMEM_CLASS_TYPE} will be the type @code{X}, while
-@code{TYPE_PTRMEM_POINTED_TO_TYPE} will be the type @code{T}.
-
-@item RECORD_TYPE
-Used to represent @code{struct} and @code{class} types in C and C++. If
-@code{TYPE_PTRMEMFUNC_P} holds, then this type is a pointer-to-member
-type. In that case, the @code{TYPE_PTRMEMFUNC_FN_TYPE} is a
-@code{POINTER_TYPE} pointing to a @code{METHOD_TYPE}. The
-@code{METHOD_TYPE} is the type of a function pointed to by the
-pointer-to-member function. If @code{TYPE_PTRMEMFUNC_P} does not hold,
-this type is a class type. For more information, @pxref{Classes}.
-
-@item UNKNOWN_TYPE
-This node is used to represent a type the knowledge of which is
-insufficient for a sound processing.
-
-@item TYPENAME_TYPE
-Used to represent a construct of the form @code{typename T::A}. The
-@code{TYPE_CONTEXT} is @code{T}; the @code{TYPE_NAME} is an
-@code{IDENTIFIER_NODE} for @code{A}. If the type is specified via a
-template-id, then @code{TYPENAME_TYPE_FULLNAME} yields a
-@code{TEMPLATE_ID_EXPR}. The @code{TREE_TYPE} is non-@code{NULL} if the
-node is implicitly generated in support for the implicit typename
-extension; in which case the @code{TREE_TYPE} is a type node for the
-base-class.
-
-@item TYPEOF_TYPE
-Used to represent the @code{__typeof__} extension. The
-@code{TYPE_FIELDS} is the expression the type of which is being
-represented.
-
-@end table
-
-
-@c ---------------------------------------------------------------------
-@c Namespaces
-@c ---------------------------------------------------------------------
-
-@node Namespaces
-@subsection Namespaces
-@cindex namespace, scope
-@tindex NAMESPACE_DECL
-
-The root of the entire intermediate representation is the variable
-@code{global_namespace}. This is the namespace specified with @code{::}
-in C++ source code. All other namespaces, types, variables, functions,
-and so forth can be found starting with this namespace.
-
-However, except for the fact that it is distinguished as the root of the
-representation, the global namespace is no different from any other
-namespace. Thus, in what follows, we describe namespaces generally,
-rather than the global namespace in particular.
-
-A namespace is represented by a @code{NAMESPACE_DECL} node.
-
-The following macros and functions can be used on a @code{NAMESPACE_DECL}:
-
-@ftable @code
-@item DECL_NAME
-This macro is used to obtain the @code{IDENTIFIER_NODE} corresponding to
-the unqualified name of the name of the namespace (@pxref{Identifiers}).
-The name of the global namespace is @samp{::}, even though in C++ the
-global namespace is unnamed. However, you should use comparison with
-@code{global_namespace}, rather than @code{DECL_NAME} to determine
-whether or not a namespace is the global one. An unnamed namespace
-will have a @code{DECL_NAME} equal to @code{anonymous_namespace_name}.
-Within a single translation unit, all unnamed namespaces will have the
-same name.
-
-@item DECL_CONTEXT
-This macro returns the enclosing namespace. The @code{DECL_CONTEXT} for
-the @code{global_namespace} is @code{NULL_TREE}.
-
-@item DECL_NAMESPACE_ALIAS
-If this declaration is for a namespace alias, then
-@code{DECL_NAMESPACE_ALIAS} is the namespace for which this one is an
-alias.
-
-Do not attempt to use @code{cp_namespace_decls} for a namespace which is
-an alias. Instead, follow @code{DECL_NAMESPACE_ALIAS} links until you
-reach an ordinary, non-alias, namespace, and call
-@code{cp_namespace_decls} there.
-
-@item DECL_NAMESPACE_STD_P
-This predicate holds if the namespace is the special @code{::std}
-namespace.
-
-@item cp_namespace_decls
-This function will return the declarations contained in the namespace,
-including types, overloaded functions, other namespaces, and so forth.
-If there are no declarations, this function will return
-@code{NULL_TREE}. The declarations are connected through their
-@code{TREE_CHAIN} fields.
-
-Although most entries on this list will be declarations,
-@code{TREE_LIST} nodes may also appear. In this case, the
-@code{TREE_VALUE} will be an @code{OVERLOAD}. The value of the
-@code{TREE_PURPOSE} is unspecified; back ends should ignore this value.
-As with the other kinds of declarations returned by
-@code{cp_namespace_decls}, the @code{TREE_CHAIN} will point to the next
-declaration in this list.
-
-For more information on the kinds of declarations that can occur on this
-list, @xref{Declarations}. Some declarations will not appear on this
-list. In particular, no @code{FIELD_DECL}, @code{LABEL_DECL}, or
-@code{PARM_DECL} nodes will appear here.
-
-This function cannot be used with namespaces that have
-@code{DECL_NAMESPACE_ALIAS} set.
-
-@end ftable
-
-@c ---------------------------------------------------------------------
-@c Classes
-@c ---------------------------------------------------------------------
-
-@node Classes
-@subsection Classes
-@cindex class, scope
-@tindex RECORD_TYPE
-@tindex UNION_TYPE
-@findex CLASSTYPE_DECLARED_CLASS
-@findex TYPE_BINFO
-@findex BINFO_TYPE
-@findex TYPE_FIELDS
-@findex TYPE_VFIELD
-
-Besides namespaces, the other high-level scoping construct in C++ is the
-class. (Throughout this manual the term @dfn{class} is used to mean the
-types referred to in the ANSI/ISO C++ Standard as classes; these include
-types defined with the @code{class}, @code{struct}, and @code{union}
-keywords.)
-
-A class type is represented by either a @code{RECORD_TYPE} or a
-@code{UNION_TYPE}. A class declared with the @code{union} tag is
-represented by a @code{UNION_TYPE}, while classes declared with either
-the @code{struct} or the @code{class} tag are represented by
-@code{RECORD_TYPE}s. You can use the @code{CLASSTYPE_DECLARED_CLASS}
-macro to discern whether or not a particular type is a @code{class} as
-opposed to a @code{struct}. This macro will be true only for classes
-declared with the @code{class} tag.
-
-Almost all members are available on the @code{TYPE_FIELDS}
-list. Given one member, the next can be found by following the
-@code{TREE_CHAIN}. You should not depend in any way on the order in
-which fields appear on this list. All nodes on this list will be
-@samp{DECL} nodes. A @code{FIELD_DECL} is used to represent a non-static
-data member, a @code{VAR_DECL} is used to represent a static data
-member, and a @code{TYPE_DECL} is used to represent a type. Note that
-the @code{CONST_DECL} for an enumeration constant will appear on this
-list, if the enumeration type was declared in the class. (Of course,
-the @code{TYPE_DECL} for the enumeration type will appear here as well.)
-There are no entries for base classes on this list. In particular,
-there is no @code{FIELD_DECL} for the ``base-class portion'' of an
-object. If a function member is overloaded, each of the overloaded
-functions appears; no @code{OVERLOAD} nodes appear on the @code{TYPE_FIELDS}
-list. Implicitly declared functions (including default constructors,
-copy constructors, assignment operators, and destructors) will appear on
-this list as well.
-
-The @code{TYPE_VFIELD} is a compiler-generated field used to point to
-virtual function tables. It may or may not appear on the
-@code{TYPE_FIELDS} list. However, back ends should handle the
-@code{TYPE_VFIELD} just like all the entries on the @code{TYPE_FIELDS}
-list.
-
-Every class has an associated @dfn{binfo}, which can be obtained with
-@code{TYPE_BINFO}. Binfos are used to represent base-classes. The
-binfo given by @code{TYPE_BINFO} is the degenerate case, whereby every
-class is considered to be its own base-class. The base binfos for a
-particular binfo are held in a vector, whose length is obtained with
-@code{BINFO_N_BASE_BINFOS}. The base binfos themselves are obtained
-with @code{BINFO_BASE_BINFO} and @code{BINFO_BASE_ITERATE}. To add a
-new binfo, use @code{BINFO_BASE_APPEND}. The vector of base binfos can
-be obtained with @code{BINFO_BASE_BINFOS}, but normally you do not need
-to use that. The class type associated with a binfo is given by
-@code{BINFO_TYPE}. It is not always the case that @code{BINFO_TYPE
-(TYPE_BINFO (x))}, because of typedefs and qualified types. Neither is
-it the case that @code{TYPE_BINFO (BINFO_TYPE (y))} is the same binfo as
-@code{y}. The reason is that if @code{y} is a binfo representing a
-base-class @code{B} of a derived class @code{D}, then @code{BINFO_TYPE
-(y)} will be @code{B}, and @code{TYPE_BINFO (BINFO_TYPE (y))} will be
-@code{B} as its own base-class, rather than as a base-class of @code{D}.
-
-The access to a base type can be found with @code{BINFO_BASE_ACCESS}.
-This will produce @code{access_public_node}, @code{access_private_node}
-or @code{access_protected_node}. If bases are always public,
-@code{BINFO_BASE_ACCESSES} may be @code{NULL}.
-
-@code{BINFO_VIRTUAL_P} is used to specify whether the binfo is inherited
-virtually or not. The other flags, @code{BINFO_FLAG_0} to
-@code{BINFO_FLAG_6}, can be used for language specific use.
-
-The following macros can be used on a tree node representing a class-type.
-
-@ftable @code
-@item LOCAL_CLASS_P
-This predicate holds if the class is local class @emph{i.e.}@: declared
-inside a function body.
-
-@item TYPE_POLYMORPHIC_P
-This predicate holds if the class has at least one virtual function
-(declared or inherited).
-
-@item TYPE_HAS_DEFAULT_CONSTRUCTOR
-This predicate holds whenever its argument represents a class-type with
-default constructor.
-
-@item CLASSTYPE_HAS_MUTABLE
-@itemx TYPE_HAS_MUTABLE_P
-These predicates hold for a class-type having a mutable data member.
-
-@item CLASSTYPE_NON_POD_P
-This predicate holds only for class-types that are not PODs.
-
-@item TYPE_HAS_NEW_OPERATOR
-This predicate holds for a class-type that defines
-@code{operator new}.
-
-@item TYPE_HAS_ARRAY_NEW_OPERATOR
-This predicate holds for a class-type for which
-@code{operator new[]} is defined.
-
-@item TYPE_OVERLOADS_CALL_EXPR
-This predicate holds for class-type for which the function call
-@code{operator()} is overloaded.
-
-@item TYPE_OVERLOADS_ARRAY_REF
-This predicate holds for a class-type that overloads
-@code{operator[]}
-
-@item TYPE_OVERLOADS_ARROW
-This predicate holds for a class-type for which @code{operator->} is
-overloaded.
-
-@end ftable
-
-@node Functions for C++
-@subsection Functions for C++
-@cindex function
-@tindex FUNCTION_DECL
-@tindex OVERLOAD
-@findex OVL_CURRENT
-@findex OVL_NEXT
-
-A function is represented by a @code{FUNCTION_DECL} node. A set of
-overloaded functions is sometimes represented by an @code{OVERLOAD} node.
-
-An @code{OVERLOAD} node is not a declaration, so none of the
-@samp{DECL_} macros should be used on an @code{OVERLOAD}. An
-@code{OVERLOAD} node is similar to a @code{TREE_LIST}. Use
-@code{OVL_CURRENT} to get the function associated with an
-@code{OVERLOAD} node; use @code{OVL_NEXT} to get the next
-@code{OVERLOAD} node in the list of overloaded functions. The macros
-@code{OVL_CURRENT} and @code{OVL_NEXT} are actually polymorphic; you can
-use them to work with @code{FUNCTION_DECL} nodes as well as with
-overloads. In the case of a @code{FUNCTION_DECL}, @code{OVL_CURRENT}
-will always return the function itself, and @code{OVL_NEXT} will always
-be @code{NULL_TREE}.
-
-To determine the scope of a function, you can use the
-@code{DECL_CONTEXT} macro. This macro will return the class
-(either a @code{RECORD_TYPE} or a @code{UNION_TYPE}) or namespace (a
-@code{NAMESPACE_DECL}) of which the function is a member. For a virtual
-function, this macro returns the class in which the function was
-actually defined, not the base class in which the virtual declaration
-occurred.
-
-If a friend function is defined in a class scope, the
-@code{DECL_FRIEND_CONTEXT} macro can be used to determine the class in
-which it was defined. For example, in
-@smallexample
-class C @{ friend void f() @{@} @};
-@end smallexample
-@noindent
-the @code{DECL_CONTEXT} for @code{f} will be the
-@code{global_namespace}, but the @code{DECL_FRIEND_CONTEXT} will be the
-@code{RECORD_TYPE} for @code{C}.
-
-
-The following macros and functions can be used on a @code{FUNCTION_DECL}:
-@ftable @code
-@item DECL_MAIN_P
-This predicate holds for a function that is the program entry point
-@code{::code}.
-
-@item DECL_LOCAL_FUNCTION_P
-This predicate holds if the function was declared at block scope, even
-though it has a global scope.
-
-@item DECL_ANTICIPATED
-This predicate holds if the function is a built-in function but its
-prototype is not yet explicitly declared.
-
-@item DECL_EXTERN_C_FUNCTION_P
-This predicate holds if the function is declared as an
-`@code{extern "C"}' function.
-
-@item DECL_LINKONCE_P
-This macro holds if multiple copies of this function may be emitted in
-various translation units. It is the responsibility of the linker to
-merge the various copies. Template instantiations are the most common
-example of functions for which @code{DECL_LINKONCE_P} holds; G++
-instantiates needed templates in all translation units which require them,
-and then relies on the linker to remove duplicate instantiations.
-
-FIXME: This macro is not yet implemented.
-
-@item DECL_FUNCTION_MEMBER_P
-This macro holds if the function is a member of a class, rather than a
-member of a namespace.
-
-@item DECL_STATIC_FUNCTION_P
-This predicate holds if the function a static member function.
-
-@item DECL_NONSTATIC_MEMBER_FUNCTION_P
-This macro holds for a non-static member function.
-
-@item DECL_CONST_MEMFUNC_P
-This predicate holds for a @code{const}-member function.
-
-@item DECL_VOLATILE_MEMFUNC_P
-This predicate holds for a @code{volatile}-member function.
-
-@item DECL_CONSTRUCTOR_P
-This macro holds if the function is a constructor.
-
-@item DECL_NONCONVERTING_P
-This predicate holds if the constructor is a non-converting constructor.
-
-@item DECL_COMPLETE_CONSTRUCTOR_P
-This predicate holds for a function which is a constructor for an object
-of a complete type.
-
-@item DECL_BASE_CONSTRUCTOR_P
-This predicate holds for a function which is a constructor for a base
-class sub-object.
-
-@item DECL_COPY_CONSTRUCTOR_P
-This predicate holds for a function which is a copy-constructor.
-
-@item DECL_DESTRUCTOR_P
-This macro holds if the function is a destructor.
-
-@item DECL_COMPLETE_DESTRUCTOR_P
-This predicate holds if the function is the destructor for an object a
-complete type.
-
-@item DECL_OVERLOADED_OPERATOR_P
-This macro holds if the function is an overloaded operator.
-
-@item DECL_CONV_FN_P
-This macro holds if the function is a type-conversion operator.
-
-@item DECL_GLOBAL_CTOR_P
-This predicate holds if the function is a file-scope initialization
-function.
-
-@item DECL_GLOBAL_DTOR_P
-This predicate holds if the function is a file-scope finalization
-function.
-
-@item DECL_THUNK_P
-This predicate holds if the function is a thunk.
-
-These functions represent stub code that adjusts the @code{this} pointer
-and then jumps to another function. When the jumped-to function
-returns, control is transferred directly to the caller, without
-returning to the thunk. The first parameter to the thunk is always the
-@code{this} pointer; the thunk should add @code{THUNK_DELTA} to this
-value. (The @code{THUNK_DELTA} is an @code{int}, not an
-@code{INTEGER_CST}.)
-
-Then, if @code{THUNK_VCALL_OFFSET} (an @code{INTEGER_CST}) is nonzero
-the adjusted @code{this} pointer must be adjusted again. The complete
-calculation is given by the following pseudo-code:
-
-@smallexample
-this += THUNK_DELTA
-if (THUNK_VCALL_OFFSET)
- this += (*((ptrdiff_t **) this))[THUNK_VCALL_OFFSET]
-@end smallexample
-
-Finally, the thunk should jump to the location given
-by @code{DECL_INITIAL}; this will always be an expression for the
-address of a function.
-
-@item DECL_NON_THUNK_FUNCTION_P
-This predicate holds if the function is @emph{not} a thunk function.
-
-@item GLOBAL_INIT_PRIORITY
-If either @code{DECL_GLOBAL_CTOR_P} or @code{DECL_GLOBAL_DTOR_P} holds,
-then this gives the initialization priority for the function. The
-linker will arrange that all functions for which
-@code{DECL_GLOBAL_CTOR_P} holds are run in increasing order of priority
-before @code{main} is called. When the program exits, all functions for
-which @code{DECL_GLOBAL_DTOR_P} holds are run in the reverse order.
-
-@item TYPE_RAISES_EXCEPTIONS
-This macro returns the list of exceptions that a (member-)function can
-raise. The returned list, if non @code{NULL}, is comprised of nodes
-whose @code{TREE_VALUE} represents a type.
-
-@item TYPE_NOTHROW_P
-This predicate holds when the exception-specification of its arguments
-is of the form `@code{()}'.
-
-@item DECL_ARRAY_DELETE_OPERATOR_P
-This predicate holds if the function an overloaded
-@code{operator delete[]}.
-
-@end ftable
-
-@c ---------------------------------------------------------------------
-@c Function Bodies
-@c ---------------------------------------------------------------------
-
-@node Statements for C and C++
-@subsection Statements for C and C++
-@cindex statements
-@tindex BREAK_STMT
-@tindex CLEANUP_STMT
-@findex CLEANUP_DECL
-@findex CLEANUP_EXPR
-@tindex CONTINUE_STMT
-@tindex DECL_STMT
-@findex DECL_STMT_DECL
-@tindex DO_STMT
-@findex DO_BODY
-@findex DO_COND
-@tindex EMPTY_CLASS_EXPR
-@tindex EXPR_STMT
-@findex EXPR_STMT_EXPR
-@tindex FOR_STMT
-@findex FOR_INIT_STMT
-@findex FOR_COND
-@findex FOR_EXPR
-@findex FOR_BODY
-@tindex HANDLER
-@tindex IF_STMT
-@findex IF_COND
-@findex THEN_CLAUSE
-@findex ELSE_CLAUSE
-@tindex RETURN_STMT
-@findex RETURN_EXPR
-@tindex SUBOBJECT
-@findex SUBOBJECT_CLEANUP
-@tindex SWITCH_STMT
-@findex SWITCH_COND
-@findex SWITCH_BODY
-@tindex TRY_BLOCK
-@findex TRY_STMTS
-@findex TRY_HANDLERS
-@findex HANDLER_PARMS
-@findex HANDLER_BODY
-@findex USING_STMT
-@tindex WHILE_STMT
-@findex WHILE_BODY
-@findex WHILE_COND
-
-A function that has a definition in the current translation unit has
-a non-@code{NULL} @code{DECL_INITIAL}. However, back ends should not make
-use of the particular value given by @code{DECL_INITIAL}.
-
-The @code{DECL_SAVED_TREE} gives the complete body of the
-function.
-
-There are tree nodes corresponding to all of the source-level
-statement constructs, used within the C and C++ frontends. These are
-enumerated here, together with a list of the various macros that can
-be used to obtain information about them. There are a few macros that
-can be used with all statements:
-
-@ftable @code
-@item STMT_IS_FULL_EXPR_P
-In C++, statements normally constitute ``full expressions''; temporaries
-created during a statement are destroyed when the statement is complete.
-However, G++ sometimes represents expressions by statements; these
-statements will not have @code{STMT_IS_FULL_EXPR_P} set. Temporaries
-created during such statements should be destroyed when the innermost
-enclosing statement with @code{STMT_IS_FULL_EXPR_P} set is exited.
-
-@end ftable
-
-Here is the list of the various statement nodes, and the macros used to
-access them. This documentation describes the use of these nodes in
-non-template functions (including instantiations of template functions).
-In template functions, the same nodes are used, but sometimes in
-slightly different ways.
-
-Many of the statements have substatements. For example, a @code{while}
-loop has a body, which is itself a statement. If the substatement
-is @code{NULL_TREE}, it is considered equivalent to a statement
-consisting of a single @code{;}, i.e., an expression statement in which
-the expression has been omitted. A substatement may in fact be a list
-of statements, connected via their @code{TREE_CHAIN}s. So, you should
-always process the statement tree by looping over substatements, like
-this:
-@smallexample
-void process_stmt (stmt)
- tree stmt;
-@{
- while (stmt)
- @{
- switch (TREE_CODE (stmt))
- @{
- case IF_STMT:
- process_stmt (THEN_CLAUSE (stmt));
- /* @r{More processing here.} */
- break;
-
- @dots{}
- @}
-
- stmt = TREE_CHAIN (stmt);
- @}
-@}
-@end smallexample
-In other words, while the @code{then} clause of an @code{if} statement
-in C++ can be only one statement (although that one statement may be a
-compound statement), the intermediate representation sometimes uses
-several statements chained together.
-
-@table @code
-@item BREAK_STMT
-
-Used to represent a @code{break} statement. There are no additional
-fields.
-
-@item CLEANUP_STMT
-
-Used to represent an action that should take place upon exit from the
-enclosing scope. Typically, these actions are calls to destructors for
-local objects, but back ends cannot rely on this fact. If these nodes
-are in fact representing such destructors, @code{CLEANUP_DECL} will be
-the @code{VAR_DECL} destroyed. Otherwise, @code{CLEANUP_DECL} will be
-@code{NULL_TREE}. In any case, the @code{CLEANUP_EXPR} is the
-expression to execute. The cleanups executed on exit from a scope
-should be run in the reverse order of the order in which the associated
-@code{CLEANUP_STMT}s were encountered.
-
-@item CONTINUE_STMT
-
-Used to represent a @code{continue} statement. There are no additional
-fields.
-
-@item CTOR_STMT
-
-Used to mark the beginning (if @code{CTOR_BEGIN_P} holds) or end (if
-@code{CTOR_END_P} holds of the main body of a constructor. See also
-@code{SUBOBJECT} for more information on how to use these nodes.
-
-@item DO_STMT
-
-Used to represent a @code{do} loop. The body of the loop is given by
-@code{DO_BODY} while the termination condition for the loop is given by
-@code{DO_COND}. The condition for a @code{do}-statement is always an
-expression.
-
-@item EMPTY_CLASS_EXPR
-
-Used to represent a temporary object of a class with no data whose
-address is never taken. (All such objects are interchangeable.) The
-@code{TREE_TYPE} represents the type of the object.
-
-@item EXPR_STMT
-
-Used to represent an expression statement. Use @code{EXPR_STMT_EXPR} to
-obtain the expression.
-
-@item FOR_STMT
-
-Used to represent a @code{for} statement. The @code{FOR_INIT_STMT} is
-the initialization statement for the loop. The @code{FOR_COND} is the
-termination condition. The @code{FOR_EXPR} is the expression executed
-right before the @code{FOR_COND} on each loop iteration; often, this
-expression increments a counter. The body of the loop is given by
-@code{FOR_BODY}. @code{FOR_SCOPE} holds the scope of the @code{for}
-statement (used in the C++ front end only). Note that
-@code{FOR_INIT_STMT} and @code{FOR_BODY} return statements, while
-@code{FOR_COND} and @code{FOR_EXPR} return expressions.
-
-@item HANDLER
-
-Used to represent a C++ @code{catch} block. The @code{HANDLER_TYPE}
-is the type of exception that will be caught by this handler; it is
-equal (by pointer equality) to @code{NULL} if this handler is for all
-types. @code{HANDLER_PARMS} is the @code{DECL_STMT} for the catch
-parameter, and @code{HANDLER_BODY} is the code for the block itself.
-
-@item IF_STMT
-
-Used to represent an @code{if} statement. The @code{IF_COND} is the
-expression.
-
-If the condition is a @code{TREE_LIST}, then the @code{TREE_PURPOSE} is
-a statement (usually a @code{DECL_STMT}). Each time the condition is
-evaluated, the statement should be executed. Then, the
-@code{TREE_VALUE} should be used as the conditional expression itself.
-This representation is used to handle C++ code like this:
-
-@smallexample
-if (int i = 7) @dots{}
-@end smallexample
-
-where there is a new local variable (or variables) declared within the
-condition.
-
-The @code{THEN_CLAUSE} represents the statement given by the @code{then}
-condition, while the @code{ELSE_CLAUSE} represents the statement given
-by the @code{else} condition.
-
-C++ distinguishes between this and @code{COND_EXPR} for handling templates.
-
-@item SUBOBJECT
-
-In a constructor, these nodes are used to mark the point at which a
-subobject of @code{this} is fully constructed. If, after this point, an
-exception is thrown before a @code{CTOR_STMT} with @code{CTOR_END_P} set
-is encountered, the @code{SUBOBJECT_CLEANUP} must be executed. The
-cleanups must be executed in the reverse order in which they appear.
-
-@item SWITCH_STMT
-
-Used to represent a @code{switch} statement. The @code{SWITCH_STMT_COND}
-is the expression on which the switch is occurring. See the documentation
-for an @code{IF_STMT} for more information on the representation used
-for the condition. The @code{SWITCH_STMT_BODY} is the body of the switch
-statement. The @code{SWITCH_STMT_TYPE} is the original type of switch
-expression as given in the source, before any compiler conversions.
-The @code{SWITCH_STMT_SCOPE} is the statement scope (used in the
-C++ front end only).
-
-There are also two boolean flags used with @code{SWITCH_STMT}.
-@code{SWITCH_STMT_ALL_CASES_P} is true if the switch includes a default label
-or the case label ranges cover all possible values of the condition
-expression. @code{SWITCH_STMT_NO_BREAK_P} is true if there are no
-@code{break} statements in the switch.
-
-@item TRY_BLOCK
-Used to represent a @code{try} block. The body of the try block is
-given by @code{TRY_STMTS}. Each of the catch blocks is a @code{HANDLER}
-node. The first handler is given by @code{TRY_HANDLERS}. Subsequent
-handlers are obtained by following the @code{TREE_CHAIN} link from one
-handler to the next. The body of the handler is given by
-@code{HANDLER_BODY}.
-
-If @code{CLEANUP_P} holds of the @code{TRY_BLOCK}, then the
-@code{TRY_HANDLERS} will not be a @code{HANDLER} node. Instead, it will
-be an expression that should be executed if an exception is thrown in
-the try block. It must rethrow the exception after executing that code.
-And, if an exception is thrown while the expression is executing,
-@code{terminate} must be called.
-
-@item USING_STMT
-Used to represent a @code{using} directive. The namespace is given by
-@code{USING_STMT_NAMESPACE}, which will be a NAMESPACE_DECL@. This node
-is needed inside template functions, to implement using directives
-during instantiation.
-
-@item WHILE_STMT
-
-Used to represent a @code{while} loop. The @code{WHILE_COND} is the
-termination condition for the loop. See the documentation for an
-@code{IF_STMT} for more information on the representation used for the
-condition.
-
-The @code{WHILE_BODY} is the body of the loop.
-
-@end table
-
-@node C++ Expressions
-@subsection C++ Expressions
-
-This section describes expressions specific to the C and C++ front
-ends.
-
-@table @code
-@item TYPEID_EXPR
-
-Used to represent a @code{typeid} expression.
-
-@item NEW_EXPR
-@itemx VEC_NEW_EXPR
-
-Used to represent a call to @code{new} and @code{new[]} respectively.
-
-@item DELETE_EXPR
-@itemx VEC_DELETE_EXPR
-
-Used to represent a call to @code{delete} and @code{delete[]} respectively.
-
-@item MEMBER_REF
-
-Represents a reference to a member of a class.
-
-@item THROW_EXPR
-
-Represents an instance of @code{throw} in the program. Operand 0,
-which is the expression to throw, may be @code{NULL_TREE}.
-
-
-@item AGGR_INIT_EXPR
-An @code{AGGR_INIT_EXPR} represents the initialization as the return
-value of a function call, or as the result of a constructor. An
-@code{AGGR_INIT_EXPR} will only appear as a full-expression, or as the
-second operand of a @code{TARGET_EXPR}. @code{AGGR_INIT_EXPR}s have
-a representation similar to that of @code{CALL_EXPR}s. You can use
-the @code{AGGR_INIT_EXPR_FN} and @code{AGGR_INIT_EXPR_ARG} macros to access
-the function to call and the arguments to pass.
-
-If @code{AGGR_INIT_VIA_CTOR_P} holds of the @code{AGGR_INIT_EXPR}, then
-the initialization is via a constructor call. The address of the
-@code{AGGR_INIT_EXPR_SLOT} operand, which is always a @code{VAR_DECL},
-is taken, and this value replaces the first argument in the argument
-list.
-
-In either case, the expression is void.
-
-
-@end table
+++ /dev/null
-@c Copyright (C) 2008-2022 Free Software Foundation, Inc.
-@c Free Software Foundation, Inc.
-@c This is part of the GCC manual.
-@c For copying conditions, see the file gcc.texi.
-
-@node GIMPLE
-@chapter GIMPLE
-@cindex GIMPLE
-
-GIMPLE is a three-address representation derived from GENERIC by
-breaking down GENERIC expressions into tuples of no more than 3
-operands (with some exceptions like function calls). GIMPLE was
-heavily influenced by the SIMPLE IL used by the McCAT compiler
-project at McGill University, though we have made some different
-choices. For one thing, SIMPLE doesn't support @code{goto}.
-
-Temporaries are introduced to hold intermediate values needed to
-compute complex expressions. Additionally, all the control
-structures used in GENERIC are lowered into conditional jumps,
-lexical scopes are removed and exception regions are converted
-into an on the side exception region tree.
-
-The compiler pass which converts GENERIC into GIMPLE is referred to as
-the @samp{gimplifier}. The gimplifier works recursively, generating
-GIMPLE tuples out of the original GENERIC expressions.
-
-One of the early implementation strategies used for the GIMPLE
-representation was to use the same internal data structures used
-by front ends to represent parse trees. This simplified
-implementation because we could leverage existing functionality
-and interfaces. However, GIMPLE is a much more restrictive
-representation than abstract syntax trees (AST), therefore it
-does not require the full structural complexity provided by the
-main tree data structure.
-
-The GENERIC representation of a function is stored in the
-@code{DECL_SAVED_TREE} field of the associated @code{FUNCTION_DECL}
-tree node. It is converted to GIMPLE by a call to
-@code{gimplify_function_tree}.
-
-If a front end wants to include language-specific tree codes in the tree
-representation which it provides to the back end, it must provide a
-definition of @code{LANG_HOOKS_GIMPLIFY_EXPR} which knows how to
-convert the front end trees to GIMPLE@. Usually such a hook will involve
-much of the same code for expanding front end trees to RTL@. This function
-can return fully lowered GIMPLE, or it can return GENERIC trees and let the
-main gimplifier lower them the rest of the way; this is often simpler.
-GIMPLE that is not fully lowered is known as ``High GIMPLE'' and
-consists of the IL before the pass @code{pass_lower_cf}. High GIMPLE
-contains some container statements like lexical scopes
-(represented by @code{GIMPLE_BIND}) and nested expressions (e.g.,
-@code{GIMPLE_TRY}), while ``Low GIMPLE'' exposes all of the
-implicit jumps for control and exception expressions directly in
-the IL and EH region trees.
-
-The C and C++ front ends currently convert directly from front end
-trees to GIMPLE, and hand that off to the back end rather than first
-converting to GENERIC@. Their gimplifier hooks know about all the
-@code{_STMT} nodes and how to convert them to GENERIC forms. There
-was some work done on a genericization pass which would run first, but
-the existence of @code{STMT_EXPR} meant that in order to convert all
-of the C statements into GENERIC equivalents would involve walking the
-entire tree anyway, so it was simpler to lower all the way. This
-might change in the future if someone writes an optimization pass
-which would work better with higher-level trees, but currently the
-optimizers all expect GIMPLE@.
-
-You can request to dump a C-like representation of the GIMPLE form
-with the flag @option{-fdump-tree-gimple}.
-
-@menu
-* Tuple representation::
-* Class hierarchy of GIMPLE statements::
-* GIMPLE instruction set::
-* GIMPLE Exception Handling::
-* Temporaries::
-* Operands::
-* Manipulating GIMPLE statements::
-* Tuple specific accessors::
-* GIMPLE sequences::
-* Sequence iterators::
-* Adding a new GIMPLE statement code::
-* Statement and operand traversals::
-@end menu
-
-@node Tuple representation
-@section Tuple representation
-@cindex tuples
-
-GIMPLE instructions are tuples of variable size divided in two
-groups: a header describing the instruction and its locations,
-and a variable length body with all the operands. Tuples are
-organized into a hierarchy with 3 main classes of tuples.
-
-@subsection @code{gimple} (gsbase)
-@cindex gimple
-
-This is the root of the hierarchy, it holds basic information
-needed by most GIMPLE statements. There are some fields that
-may not be relevant to every GIMPLE statement, but those were
-moved into the base structure to take advantage of holes left by
-other fields (thus making the structure more compact). The
-structure takes 4 words (32 bytes) on 64 bit hosts:
-
-@multitable {@code{references_memory_p}} {Size (bits)}
-@item Field @tab Size (bits)
-@item @code{code} @tab 8
-@item @code{subcode} @tab 16
-@item @code{no_warning} @tab 1
-@item @code{visited} @tab 1
-@item @code{nontemporal_move} @tab 1
-@item @code{plf} @tab 2
-@item @code{modified} @tab 1
-@item @code{has_volatile_ops} @tab 1
-@item @code{references_memory_p} @tab 1
-@item @code{uid} @tab 32
-@item @code{location} @tab 32
-@item @code{num_ops} @tab 32
-@item @code{bb} @tab 64
-@item @code{block} @tab 63
-@item Total size @tab 32 bytes
-@end multitable
-
-@itemize @bullet
-@item @code{code}
-Main identifier for a GIMPLE instruction.
-
-@item @code{subcode}
-Used to distinguish different variants of the same basic
-instruction or provide flags applicable to a given code. The
-@code{subcode} flags field has different uses depending on the code of
-the instruction, but mostly it distinguishes instructions of the
-same family. The most prominent use of this field is in
-assignments, where subcode indicates the operation done on the
-RHS of the assignment. For example, a = b + c is encoded as
-@code{GIMPLE_ASSIGN <PLUS_EXPR, a, b, c>}.
-
-@item @code{no_warning}
-Bitflag to indicate whether a warning has already been issued on
-this statement.
-
-@item @code{visited}
-General purpose ``visited'' marker. Set and cleared by each pass
-when needed.
-
-@item @code{nontemporal_move}
-Bitflag used in assignments that represent non-temporal moves.
-Although this bitflag is only used in assignments, it was moved
-into the base to take advantage of the bit holes left by the
-previous fields.
-
-@item @code{plf}
-Pass Local Flags. This 2-bit mask can be used as general purpose
-markers by any pass. Passes are responsible for clearing and
-setting these two flags accordingly.
-
-@item @code{modified}
-Bitflag to indicate whether the statement has been modified.
-Used mainly by the operand scanner to determine when to re-scan a
-statement for operands.
-
-@item @code{has_volatile_ops}
-Bitflag to indicate whether this statement contains operands that
-have been marked volatile.
-
-@item @code{references_memory_p}
-Bitflag to indicate whether this statement contains memory
-references (i.e., its operands are either global variables, or
-pointer dereferences or anything that must reside in memory).
-
-@item @code{uid}
-This is an unsigned integer used by passes that want to assign
-IDs to every statement. These IDs must be assigned and used by
-each pass.
-
-@item @code{location}
-This is a @code{location_t} identifier to specify source code
-location for this statement. It is inherited from the front
-end.
-
-@item @code{num_ops}
-Number of operands that this statement has. This specifies the
-size of the operand vector embedded in the tuple. Only used in
-some tuples, but it is declared in the base tuple to take
-advantage of the 32-bit hole left by the previous fields.
-
-@item @code{bb}
-Basic block holding the instruction.
-
-@item @code{block}
-Lexical block holding this statement. Also used for debug
-information generation.
-@end itemize
-
-@subsection @code{gimple_statement_with_ops}
-@cindex gimple_statement_with_ops
-
-This tuple is actually split in two:
-@code{gimple_statement_with_ops_base} and
-@code{gimple_statement_with_ops}. This is needed to accommodate the
-way the operand vector is allocated. The operand vector is
-defined to be an array of 1 element. So, to allocate a dynamic
-number of operands, the memory allocator (@code{gimple_alloc}) simply
-allocates enough memory to hold the structure itself plus @code{N
-- 1} operands which run ``off the end'' of the structure. For
-example, to allocate space for a tuple with 3 operands,
-@code{gimple_alloc} reserves @code{sizeof (struct
-gimple_statement_with_ops) + 2 * sizeof (tree)} bytes.
-
-On the other hand, several fields in this tuple need to be shared
-with the @code{gimple_statement_with_memory_ops} tuple. So, these
-common fields are placed in @code{gimple_statement_with_ops_base} which
-is then inherited from the other two tuples.
-
-
-@multitable {@code{def_ops}} {48 + 8 * @code{num_ops} bytes}
-@item @code{gsbase} @tab 256
-@item @code{def_ops} @tab 64
-@item @code{use_ops} @tab 64
-@item @code{op} @tab @code{num_ops} * 64
-@item Total size @tab 48 + 8 * @code{num_ops} bytes
-@end multitable
-
-@itemize @bullet
-@item @code{gsbase}
-Inherited from @code{struct gimple}.
-
-@item @code{def_ops}
-Array of pointers into the operand array indicating all the slots that
-contain a variable written-to by the statement. This array is
-also used for immediate use chaining. Note that it would be
-possible to not rely on this array, but the changes required to
-implement this are pretty invasive.
-
-@item @code{use_ops}
-Similar to @code{def_ops} but for variables read by the statement.
-
-@item @code{op}
-Array of trees with @code{num_ops} slots.
-@end itemize
-
-@subsection @code{gimple_statement_with_memory_ops}
-
-This tuple is essentially identical to @code{gimple_statement_with_ops},
-except that it contains 4 additional fields to hold vectors
-related memory stores and loads. Similar to the previous case,
-the structure is split in two to accommodate for the operand
-vector (@code{gimple_statement_with_memory_ops_base} and
-@code{gimple_statement_with_memory_ops}).
-
-
-@multitable {@code{vdef_ops}} {80 + 8 * @code{num_ops} bytes}
-@item Field @tab Size (bits)
-@item @code{gsbase} @tab 256
-@item @code{def_ops} @tab 64
-@item @code{use_ops} @tab 64
-@item @code{vdef_ops} @tab 64
-@item @code{vuse_ops} @tab 64
-@item @code{stores} @tab 64
-@item @code{loads} @tab 64
-@item @code{op} @tab @code{num_ops} * 64
-@item Total size @tab 80 + 8 * @code{num_ops} bytes
-@end multitable
-
-@itemize @bullet
-@item @code{vdef_ops}
-Similar to @code{def_ops} but for @code{VDEF} operators. There is
-one entry per memory symbol written by this statement. This is
-used to maintain the memory SSA use-def and def-def chains.
-
-@item @code{vuse_ops}
-Similar to @code{use_ops} but for @code{VUSE} operators. There is
-one entry per memory symbol loaded by this statement. This is
-used to maintain the memory SSA use-def chains.
-
-@item @code{stores}
-Bitset with all the UIDs for the symbols written-to by the
-statement. This is different than @code{vdef_ops} in that all the
-affected symbols are mentioned in this set. If memory
-partitioning is enabled, the @code{vdef_ops} vector will refer to memory
-partitions. Furthermore, no SSA information is stored in this
-set.
-
-@item @code{loads}
-Similar to @code{stores}, but for memory loads. (Note that there
-is some amount of redundancy here, it should be possible to
-reduce memory utilization further by removing these sets).
-@end itemize
-
-All the other tuples are defined in terms of these three basic
-ones. Each tuple will add some fields.
-
-
-@node Class hierarchy of GIMPLE statements
-@section Class hierarchy of GIMPLE statements
-@cindex GIMPLE class hierarchy
-
-The following diagram shows the C++ inheritance hierarchy of statement
-kinds, along with their relationships to @code{GSS_} values (layouts) and
-@code{GIMPLE_} values (codes):
-
-@smallexample
- gimple
- | layout: GSS_BASE
- | used for 4 codes: GIMPLE_ERROR_MARK
- | GIMPLE_NOP
- | GIMPLE_OMP_SECTIONS_SWITCH
- | GIMPLE_PREDICT
- |
- + gimple_statement_with_ops_base
- | | (no GSS layout)
- | |
- | + gimple_statement_with_ops
- | | | layout: GSS_WITH_OPS
- | | |
- | | + gcond
- | | | code: GIMPLE_COND
- | | |
- | | + gdebug
- | | | code: GIMPLE_DEBUG
- | | |
- | | + ggoto
- | | | code: GIMPLE_GOTO
- | | |
- | | + glabel
- | | | code: GIMPLE_LABEL
- | | |
- | | + gswitch
- | | code: GIMPLE_SWITCH
- | |
- | + gimple_statement_with_memory_ops_base
- | | layout: GSS_WITH_MEM_OPS_BASE
- | |
- | + gimple_statement_with_memory_ops
- | | | layout: GSS_WITH_MEM_OPS
- | | |
- | | + gassign
- | | | code GIMPLE_ASSIGN
- | | |
- | | + greturn
- | | code GIMPLE_RETURN
- | |
- | + gcall
- | | layout: GSS_CALL, code: GIMPLE_CALL
- | |
- | + gasm
- | | layout: GSS_ASM, code: GIMPLE_ASM
- | |
- | + gtransaction
- | layout: GSS_TRANSACTION, code: GIMPLE_TRANSACTION
- |
- + gimple_statement_omp
- | | layout: GSS_OMP. Used for code GIMPLE_OMP_SECTION
- | |
- | + gomp_critical
- | | layout: GSS_OMP_CRITICAL, code: GIMPLE_OMP_CRITICAL
- | |
- | + gomp_for
- | | layout: GSS_OMP_FOR, code: GIMPLE_OMP_FOR
- | |
- | + gomp_parallel_layout
- | | | layout: GSS_OMP_PARALLEL_LAYOUT
- | | |
- | | + gimple_statement_omp_taskreg
- | | | |
- | | | + gomp_parallel
- | | | | code: GIMPLE_OMP_PARALLEL
- | | | |
- | | | + gomp_task
- | | | code: GIMPLE_OMP_TASK
- | | |
- | | + gimple_statement_omp_target
- | | code: GIMPLE_OMP_TARGET
- | |
- | + gomp_sections
- | | layout: GSS_OMP_SECTIONS, code: GIMPLE_OMP_SECTIONS
- | |
- | + gimple_statement_omp_single_layout
- | | layout: GSS_OMP_SINGLE_LAYOUT
- | |
- | + gomp_single
- | | code: GIMPLE_OMP_SINGLE
- | |
- | + gomp_teams
- | code: GIMPLE_OMP_TEAMS
- |
- + gbind
- | layout: GSS_BIND, code: GIMPLE_BIND
- |
- + gcatch
- | layout: GSS_CATCH, code: GIMPLE_CATCH
- |
- + geh_filter
- | layout: GSS_EH_FILTER, code: GIMPLE_EH_FILTER
- |
- + geh_else
- | layout: GSS_EH_ELSE, code: GIMPLE_EH_ELSE
- |
- + geh_mnt
- | layout: GSS_EH_MNT, code: GIMPLE_EH_MUST_NOT_THROW
- |
- + gphi
- | layout: GSS_PHI, code: GIMPLE_PHI
- |
- + gimple_statement_eh_ctrl
- | | layout: GSS_EH_CTRL
- | |
- | + gresx
- | | code: GIMPLE_RESX
- | |
- | + geh_dispatch
- | code: GIMPLE_EH_DISPATCH
- |
- + gtry
- | layout: GSS_TRY, code: GIMPLE_TRY
- |
- + gimple_statement_wce
- | layout: GSS_WCE, code: GIMPLE_WITH_CLEANUP_EXPR
- |
- + gomp_continue
- | layout: GSS_OMP_CONTINUE, code: GIMPLE_OMP_CONTINUE
- |
- + gomp_atomic_load
- | layout: GSS_OMP_ATOMIC_LOAD, code: GIMPLE_OMP_ATOMIC_LOAD
- |
- + gimple_statement_omp_atomic_store_layout
- | layout: GSS_OMP_ATOMIC_STORE_LAYOUT,
- | code: GIMPLE_OMP_ATOMIC_STORE
- |
- + gomp_atomic_store
- | code: GIMPLE_OMP_ATOMIC_STORE
- |
- + gomp_return
- code: GIMPLE_OMP_RETURN
-@end smallexample
-
-
-@node GIMPLE instruction set
-@section GIMPLE instruction set
-@cindex GIMPLE instruction set
-
-The following table briefly describes the GIMPLE instruction set.
-
-@multitable {@code{GIMPLE_OMP_SECTIONS_SWITCH}} {High GIMPLE} {Low GIMPLE}
-@item Instruction @tab High GIMPLE @tab Low GIMPLE
-@item @code{GIMPLE_ASM} @tab x @tab x
-@item @code{GIMPLE_ASSIGN} @tab x @tab x
-@item @code{GIMPLE_BIND} @tab x @tab
-@item @code{GIMPLE_CALL} @tab x @tab x
-@item @code{GIMPLE_CATCH} @tab x @tab
-@item @code{GIMPLE_COND} @tab x @tab x
-@item @code{GIMPLE_DEBUG} @tab x @tab x
-@item @code{GIMPLE_EH_FILTER} @tab x @tab
-@item @code{GIMPLE_GOTO} @tab x @tab x
-@item @code{GIMPLE_LABEL} @tab x @tab x
-@item @code{GIMPLE_NOP} @tab x @tab x
-@item @code{GIMPLE_OMP_ATOMIC_LOAD} @tab x @tab x
-@item @code{GIMPLE_OMP_ATOMIC_STORE} @tab x @tab x
-@item @code{GIMPLE_OMP_CONTINUE} @tab x @tab x
-@item @code{GIMPLE_OMP_CRITICAL} @tab x @tab x
-@item @code{GIMPLE_OMP_FOR} @tab x @tab x
-@item @code{GIMPLE_OMP_MASTER} @tab x @tab x
-@item @code{GIMPLE_OMP_ORDERED} @tab x @tab x
-@item @code{GIMPLE_OMP_PARALLEL} @tab x @tab x
-@item @code{GIMPLE_OMP_RETURN} @tab x @tab x
-@item @code{GIMPLE_OMP_SECTION} @tab x @tab x
-@item @code{GIMPLE_OMP_SECTIONS} @tab x @tab x
-@item @code{GIMPLE_OMP_SECTIONS_SWITCH} @tab x @tab x
-@item @code{GIMPLE_OMP_SINGLE} @tab x @tab x
-@item @code{GIMPLE_PHI} @tab @tab x
-@item @code{GIMPLE_RESX} @tab @tab x
-@item @code{GIMPLE_RETURN} @tab x @tab x
-@item @code{GIMPLE_SWITCH} @tab x @tab x
-@item @code{GIMPLE_TRY} @tab x @tab
-@end multitable
-
-@node GIMPLE Exception Handling
-@section Exception Handling
-@cindex GIMPLE Exception Handling
-
-Other exception handling constructs are represented using
-@code{GIMPLE_TRY_CATCH}. @code{GIMPLE_TRY_CATCH} has two operands. The
-first operand is a sequence of statements to execute. If executing
-these statements does not throw an exception, then the second operand
-is ignored. Otherwise, if an exception is thrown, then the second
-operand of the @code{GIMPLE_TRY_CATCH} is checked. The second
-operand may have the following forms:
-
-@enumerate
-
-@item A sequence of statements to execute. When an exception occurs,
-these statements are executed, and then the exception is rethrown.
-
-@item A sequence of @code{GIMPLE_CATCH} statements. Each
-@code{GIMPLE_CATCH} has a list of applicable exception types and
-handler code. If the thrown exception matches one of the caught
-types, the associated handler code is executed. If the handler
-code falls off the bottom, execution continues after the original
-@code{GIMPLE_TRY_CATCH}.
-
-@item A @code{GIMPLE_EH_FILTER} statement. This has a list of
-permitted exception types, and code to handle a match failure. If the
-thrown exception does not match one of the allowed types, the
-associated match failure code is executed. If the thrown exception
-does match, it continues unwinding the stack looking for the next
-handler.
-
-@end enumerate
-
-Currently throwing an exception is not directly represented in
-GIMPLE, since it is implemented by calling a function. At some
-point in the future we will want to add some way to express that
-the call will throw an exception of a known type.
-
-Just before running the optimizers, the compiler lowers the
-high-level EH constructs above into a set of @samp{goto}s, magic
-labels, and EH regions. Continuing to unwind at the end of a
-cleanup is represented with a @code{GIMPLE_RESX}.
-
-
-@node Temporaries
-@section Temporaries
-@cindex Temporaries
-
-When gimplification encounters a subexpression that is too
-complex, it creates a new temporary variable to hold the value of
-the subexpression, and adds a new statement to initialize it
-before the current statement. These special temporaries are known
-as @samp{expression temporaries}, and are allocated using
-@code{get_formal_tmp_var}. The compiler tries to always evaluate
-identical expressions into the same temporary, to simplify
-elimination of redundant calculations.
-
-We can only use expression temporaries when we know that it will
-not be reevaluated before its value is used, and that it will not
-be otherwise modified@footnote{These restrictions are derived
-from those in Morgan 4.8.}. Other temporaries can be allocated
-using @code{get_initialized_tmp_var} or @code{create_tmp_var}.
-
-Currently, an expression like @code{a = b + 5} is not reduced any
-further. We tried converting it to something like
-@smallexample
-T1 = b + 5;
-a = T1;
-@end smallexample
-but this bloated the representation for minimal benefit. However, a
-variable which must live in memory cannot appear in an expression; its
-value is explicitly loaded into a temporary first. Similarly, storing
-the value of an expression to a memory variable goes through a
-temporary.
-
-@node Operands
-@section Operands
-@cindex Operands
-
-In general, expressions in GIMPLE consist of an operation and the
-appropriate number of simple operands; these operands must either be a
-GIMPLE rvalue (@code{is_gimple_val}), i.e.@: a constant or a register
-variable. More complex operands are factored out into temporaries, so
-that
-@smallexample
-a = b + c + d
-@end smallexample
-becomes
-@smallexample
-T1 = b + c;
-a = T1 + d;
-@end smallexample
-
-The same rule holds for arguments to a @code{GIMPLE_CALL}.
-
-The target of an assignment is usually a variable, but can also be a
-@code{MEM_REF} or a compound lvalue as described below.
-
-@menu
-* Compound Expressions::
-* Compound Lvalues::
-* Conditional Expressions::
-* Logical Operators::
-@end menu
-
-@node Compound Expressions
-@subsection Compound Expressions
-@cindex Compound Expressions
-
-The left-hand side of a C comma expression is simply moved into a separate
-statement.
-
-@node Compound Lvalues
-@subsection Compound Lvalues
-@cindex Compound Lvalues
-
-Currently compound lvalues involving array and structure field references
-are not broken down; an expression like @code{a.b[2] = 42} is not reduced
-any further (though complex array subscripts are). This restriction is a
-workaround for limitations in later optimizers; if we were to convert this
-to
-
-@smallexample
-T1 = &a.b;
-T1[2] = 42;
-@end smallexample
-
-alias analysis would not remember that the reference to @code{T1[2]} came
-by way of @code{a.b}, so it would think that the assignment could alias
-another member of @code{a}; this broke @code{struct-alias-1.c}. Future
-optimizer improvements may make this limitation unnecessary.
-
-@node Conditional Expressions
-@subsection Conditional Expressions
-@cindex Conditional Expressions
-
-A C @code{?:} expression is converted into an @code{if} statement with
-each branch assigning to the same temporary. So,
-
-@smallexample
-a = b ? c : d;
-@end smallexample
-becomes
-@smallexample
-if (b == 1)
- T1 = c;
-else
- T1 = d;
-a = T1;
-@end smallexample
-
-The GIMPLE level if-conversion pass re-introduces @code{?:}
-expression, if appropriate. It is used to vectorize loops with
-conditions using vector conditional operations.
-
-Note that in GIMPLE, @code{if} statements are represented using
-@code{GIMPLE_COND}, as described below.
-
-@node Logical Operators
-@subsection Logical Operators
-@cindex Logical Operators
-
-Except when they appear in the condition operand of a
-@code{GIMPLE_COND}, logical `and' and `or' operators are simplified
-as follows: @code{a = b && c} becomes
-
-@smallexample
-T1 = (bool)b;
-if (T1 == true)
- T1 = (bool)c;
-a = T1;
-@end smallexample
-
-Note that @code{T1} in this example cannot be an expression temporary,
-because it has two different assignments.
-
-@subsection Manipulating operands
-
-All gimple operands are of type @code{tree}. But only certain
-types of trees are allowed to be used as operand tuples. Basic
-validation is controlled by the function
-@code{get_gimple_rhs_class}, which given a tree code, returns an
-@code{enum} with the following values of type @code{enum
-gimple_rhs_class}
-
-@itemize @bullet
-@item @code{GIMPLE_INVALID_RHS}
-The tree cannot be used as a GIMPLE operand.
-
-@item @code{GIMPLE_TERNARY_RHS}
-The tree is a valid GIMPLE ternary operation.
-
-@item @code{GIMPLE_BINARY_RHS}
-The tree is a valid GIMPLE binary operation.
-
-@item @code{GIMPLE_UNARY_RHS}
-The tree is a valid GIMPLE unary operation.
-
-@item @code{GIMPLE_SINGLE_RHS}
-The tree is a single object, that cannot be split into simpler
-operands (for instance, @code{SSA_NAME}, @code{VAR_DECL}, @code{COMPONENT_REF}, etc).
-
-This operand class also acts as an escape hatch for tree nodes
-that may be flattened out into the operand vector, but would need
-more than two slots on the RHS. For instance, a @code{COND_EXPR}
-expression of the form @code{(a op b) ? x : y} could be flattened
-out on the operand vector using 4 slots, but it would also
-require additional processing to distinguish @code{c = a op b}
-from @code{c = a op b ? x : y}. Something similar occurs with
-@code{ASSERT_EXPR}. In time, these special case tree
-expressions should be flattened into the operand vector.
-@end itemize
-
-For tree nodes in the categories @code{GIMPLE_TERNARY_RHS},
-@code{GIMPLE_BINARY_RHS} and @code{GIMPLE_UNARY_RHS}, they cannot be
-stored inside tuples directly. They first need to be flattened and
-separated into individual components. For instance, given the GENERIC
-expression
-
-@smallexample
-a = b + c
-@end smallexample
-
-its tree representation is:
-
-@smallexample
-MODIFY_EXPR <VAR_DECL <a>, PLUS_EXPR <VAR_DECL <b>, VAR_DECL <c>>>
-@end smallexample
-
-In this case, the GIMPLE form for this statement is logically
-identical to its GENERIC form but in GIMPLE, the @code{PLUS_EXPR}
-on the RHS of the assignment is not represented as a tree,
-instead the two operands are taken out of the @code{PLUS_EXPR} sub-tree
-and flattened into the GIMPLE tuple as follows:
-
-@smallexample
-GIMPLE_ASSIGN <PLUS_EXPR, VAR_DECL <a>, VAR_DECL <b>, VAR_DECL <c>>
-@end smallexample
-
-@subsection Operand vector allocation
-
-The operand vector is stored at the bottom of the three tuple
-structures that accept operands. This means, that depending on
-the code of a given statement, its operand vector will be at
-different offsets from the base of the structure. To access
-tuple operands use the following accessors
-
-@deftypefn {GIMPLE function} unsigned gimple_num_ops (gimple g)
-Returns the number of operands in statement G.
-@end deftypefn
-
-@deftypefn {GIMPLE function} tree gimple_op (gimple g, unsigned i)
-Returns operand @code{I} from statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} {tree *} gimple_ops (gimple g)
-Returns a pointer into the operand vector for statement @code{G}. This
-is computed using an internal table called @code{gimple_ops_offset_}[].
-This table is indexed by the gimple code of @code{G}.
-
-When the compiler is built, this table is filled-in using the
-sizes of the structures used by each statement code defined in
-gimple.def. Since the operand vector is at the bottom of the
-structure, for a gimple code @code{C} the offset is computed as sizeof
-(struct-of @code{C}) - sizeof (tree).
-
-This mechanism adds one memory indirection to every access when
-using @code{gimple_op}(), if this becomes a bottleneck, a pass can
-choose to memoize the result from @code{gimple_ops}() and use that to
-access the operands.
-@end deftypefn
-
-@subsection Operand validation
-
-When adding a new operand to a gimple statement, the operand will
-be validated according to what each tuple accepts in its operand
-vector. These predicates are called by the
-@code{gimple_@var{name}_set_...()}. Each tuple will use one of the
-following predicates (Note, this list is not exhaustive):
-
-@deftypefn {GIMPLE function} bool is_gimple_val (tree t)
-Returns true if t is a "GIMPLE value", which are all the
-non-addressable stack variables (variables for which
-@code{is_gimple_reg} returns true) and constants (expressions for which
-@code{is_gimple_min_invariant} returns true).
-@end deftypefn
-
-@deftypefn {GIMPLE function} bool is_gimple_addressable (tree t)
-Returns true if t is a symbol or memory reference whose address
-can be taken.
-@end deftypefn
-
-@deftypefn {GIMPLE function} bool is_gimple_asm_val (tree t)
-Similar to @code{is_gimple_val} but it also accepts hard registers.
-@end deftypefn
-
-@deftypefn {GIMPLE function} bool is_gimple_call_addr (tree t)
-Return true if t is a valid expression to use as the function
-called by a @code{GIMPLE_CALL}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} bool is_gimple_mem_ref_addr (tree t)
-Return true if t is a valid expression to use as first operand
-of a @code{MEM_REF} expression.
-@end deftypefn
-
-@deftypefn {GIMPLE function} bool is_gimple_constant (tree t)
-Return true if t is a valid gimple constant.
-@end deftypefn
-
-@deftypefn {GIMPLE function} bool is_gimple_min_invariant (tree t)
-Return true if t is a valid minimal invariant. This is different
-from constants, in that the specific value of t may not be known
-at compile time, but it is known that it doesn't change (e.g.,
-the address of a function local variable).
-@end deftypefn
-
-@deftypefn {GIMPLE function} bool is_gimple_ip_invariant (tree t)
-Return true if t is an interprocedural invariant. This means that t
-is a valid invariant in all functions (e.g.@: it can be an address of a
-global variable but not of a local one).
-@end deftypefn
-
-@deftypefn {GIMPLE function} bool is_gimple_ip_invariant_address (tree t)
-Return true if t is an @code{ADDR_EXPR} that does not change once the
-program is running (and which is valid in all functions).
-@end deftypefn
-
-
-@subsection Statement validation
-
-@deftypefn {GIMPLE function} bool is_gimple_assign (gimple g)
-Return true if the code of g is @code{GIMPLE_ASSIGN}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} bool is_gimple_call (gimple g)
-Return true if the code of g is @code{GIMPLE_CALL}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} bool is_gimple_debug (gimple g)
-Return true if the code of g is @code{GIMPLE_DEBUG}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} bool gimple_assign_cast_p (const_gimple g)
-Return true if g is a @code{GIMPLE_ASSIGN} that performs a type cast
-operation.
-@end deftypefn
-
-@deftypefn {GIMPLE function} bool gimple_debug_bind_p (gimple g)
-Return true if g is a @code{GIMPLE_DEBUG} that binds the value of an
-expression to a variable.
-@end deftypefn
-
-@deftypefn {GIMPLE function} bool is_gimple_omp (gimple g)
-Return true if g is any of the OpenMP codes.
-@end deftypefn
-
-@deftypefn {GIMPLE function} bool gimple_debug_begin_stmt_p (gimple g)
-Return true if g is a @code{GIMPLE_DEBUG} that marks the beginning of
-a source statement.
-@end deftypefn
-
-@deftypefn {GIMPLE function} bool gimple_debug_inline_entry_p (gimple g)
-Return true if g is a @code{GIMPLE_DEBUG} that marks the entry
-point of an inlined function.
-@end deftypefn
-
-@deftypefn {GIMPLE function} bool gimple_debug_nonbind_marker_p (gimple g)
-Return true if g is a @code{GIMPLE_DEBUG} that marks a program location,
-without any variable binding.
-@end deftypefn
-
-@node Manipulating GIMPLE statements
-@section Manipulating GIMPLE statements
-@cindex Manipulating GIMPLE statements
-
-This section documents all the functions available to handle each
-of the GIMPLE instructions.
-
-@subsection Common accessors
-The following are common accessors for gimple statements.
-
-@deftypefn {GIMPLE function} {enum gimple_code} gimple_code (gimple g)
-Return the code for statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} basic_block gimple_bb (gimple g)
-Return the basic block to which statement @code{G} belongs to.
-@end deftypefn
-
-@deftypefn {GIMPLE function} tree gimple_block (gimple g)
-Return the lexical scope block holding statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} {enum tree_code} gimple_expr_code (gimple stmt)
-Return the tree code for the expression computed by @code{STMT}. This
-is only meaningful for @code{GIMPLE_CALL}, @code{GIMPLE_ASSIGN} and
-@code{GIMPLE_COND}. If @code{STMT} is @code{GIMPLE_CALL}, it will return @code{CALL_EXPR}.
-For @code{GIMPLE_COND}, it returns the code of the comparison predicate.
-For @code{GIMPLE_ASSIGN} it returns the code of the operation performed
-by the @code{RHS} of the assignment.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_set_block (gimple g, tree block)
-Set the lexical scope block of @code{G} to @code{BLOCK}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} location_t gimple_locus (gimple g)
-Return locus information for statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_set_locus (gimple g, location_t locus)
-Set locus information for statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} bool gimple_locus_empty_p (gimple g)
-Return true if @code{G} does not have locus information.
-@end deftypefn
-
-@deftypefn {GIMPLE function} bool gimple_no_warning_p (gimple stmt)
-Return true if no warnings should be emitted for statement @code{STMT}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_set_visited (gimple stmt, bool visited_p)
-Set the visited status on statement @code{STMT} to @code{VISITED_P}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} bool gimple_visited_p (gimple stmt)
-Return the visited status on statement @code{STMT}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_set_plf (gimple stmt, enum plf_mask plf, bool val_p)
-Set pass local flag @code{PLF} on statement @code{STMT} to @code{VAL_P}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} {unsigned int} gimple_plf (gimple stmt, enum plf_mask plf)
-Return the value of pass local flag @code{PLF} on statement @code{STMT}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} bool gimple_has_ops (gimple g)
-Return true if statement @code{G} has register or memory operands.
-@end deftypefn
-
-@deftypefn {GIMPLE function} bool gimple_has_mem_ops (gimple g)
-Return true if statement @code{G} has memory operands.
-@end deftypefn
-
-@deftypefn {GIMPLE function} unsigned gimple_num_ops (gimple g)
-Return the number of operands for statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} {tree *} gimple_ops (gimple g)
-Return the array of operands for statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} tree gimple_op (gimple g, unsigned i)
-Return operand @code{I} for statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} {tree *} gimple_op_ptr (gimple g, unsigned i)
-Return a pointer to operand @code{I} for statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_set_op (gimple g, unsigned i, tree op)
-Set operand @code{I} of statement @code{G} to @code{OP}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} bitmap gimple_addresses_taken (gimple stmt)
-Return the set of symbols that have had their address taken by
-@code{STMT}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} {struct def_optype_d *} gimple_def_ops (gimple g)
-Return the set of @code{DEF} operands for statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_set_def_ops (gimple g, struct def_optype_d *def)
-Set @code{DEF} to be the set of @code{DEF} operands for statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} {struct use_optype_d *} gimple_use_ops (gimple g)
-Return the set of @code{USE} operands for statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_set_use_ops (gimple g, struct use_optype_d *use)
-Set @code{USE} to be the set of @code{USE} operands for statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} {struct voptype_d *} gimple_vuse_ops (gimple g)
-Return the set of @code{VUSE} operands for statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_set_vuse_ops (gimple g, struct voptype_d *ops)
-Set @code{OPS} to be the set of @code{VUSE} operands for statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} {struct voptype_d *} gimple_vdef_ops (gimple g)
-Return the set of @code{VDEF} operands for statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_set_vdef_ops (gimple g, struct voptype_d *ops)
-Set @code{OPS} to be the set of @code{VDEF} operands for statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} bitmap gimple_loaded_syms (gimple g)
-Return the set of symbols loaded by statement @code{G}. Each element of
-the set is the @code{DECL_UID} of the corresponding symbol.
-@end deftypefn
-
-@deftypefn {GIMPLE function} bitmap gimple_stored_syms (gimple g)
-Return the set of symbols stored by statement @code{G}. Each element of
-the set is the @code{DECL_UID} of the corresponding symbol.
-@end deftypefn
-
-@deftypefn {GIMPLE function} bool gimple_modified_p (gimple g)
-Return true if statement @code{G} has operands and the modified field
-has been set.
-@end deftypefn
-
-@deftypefn {GIMPLE function} bool gimple_has_volatile_ops (gimple stmt)
-Return true if statement @code{STMT} contains volatile operands.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_set_has_volatile_ops (gimple stmt, bool volatilep)
-Return true if statement @code{STMT} contains volatile operands.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void update_stmt (gimple s)
-Mark statement @code{S} as modified, and update it.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void update_stmt_if_modified (gimple s)
-Update statement @code{S} if it has been marked modified.
-@end deftypefn
-
-@deftypefn {GIMPLE function} gimple gimple_copy (gimple stmt)
-Return a deep copy of statement @code{STMT}.
-@end deftypefn
-
-@node Tuple specific accessors
-@section Tuple specific accessors
-@cindex Tuple specific accessors
-
-@menu
-* @code{GIMPLE_ASM}::
-* @code{GIMPLE_ASSIGN}::
-* @code{GIMPLE_BIND}::
-* @code{GIMPLE_CALL}::
-* @code{GIMPLE_CATCH}::
-* @code{GIMPLE_COND}::
-* @code{GIMPLE_DEBUG}::
-* @code{GIMPLE_EH_FILTER}::
-* @code{GIMPLE_LABEL}::
-* @code{GIMPLE_GOTO}::
-* @code{GIMPLE_NOP}::
-* @code{GIMPLE_OMP_ATOMIC_LOAD}::
-* @code{GIMPLE_OMP_ATOMIC_STORE}::
-* @code{GIMPLE_OMP_CONTINUE}::
-* @code{GIMPLE_OMP_CRITICAL}::
-* @code{GIMPLE_OMP_FOR}::
-* @code{GIMPLE_OMP_MASTER}::
-* @code{GIMPLE_OMP_ORDERED}::
-* @code{GIMPLE_OMP_PARALLEL}::
-* @code{GIMPLE_OMP_RETURN}::
-* @code{GIMPLE_OMP_SECTION}::
-* @code{GIMPLE_OMP_SECTIONS}::
-* @code{GIMPLE_OMP_SINGLE}::
-* @code{GIMPLE_PHI}::
-* @code{GIMPLE_RESX}::
-* @code{GIMPLE_RETURN}::
-* @code{GIMPLE_SWITCH}::
-* @code{GIMPLE_TRY}::
-* @code{GIMPLE_WITH_CLEANUP_EXPR}::
-@end menu
-
-
-@node @code{GIMPLE_ASM}
-@subsection @code{GIMPLE_ASM}
-@cindex @code{GIMPLE_ASM}
-
-@deftypefn {GIMPLE function} gasm *gimple_build_asm_vec ( @
-const char *string, vec<tree, va_gc> *inputs, @
-vec<tree, va_gc> *outputs, vec<tree, va_gc> *clobbers, @
-vec<tree, va_gc> *labels)
-Build a @code{GIMPLE_ASM} statement. This statement is used for
-building in-line assembly constructs. @code{STRING} is the assembly
-code. @code{INPUTS}, @code{OUTPUTS}, @code{CLOBBERS} and @code{LABELS}
-are the inputs, outputs, clobbered registers and labels.
-@end deftypefn
-
-@deftypefn {GIMPLE function} unsigned gimple_asm_ninputs (const gasm *g)
-Return the number of input operands for @code{GIMPLE_ASM} @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} unsigned gimple_asm_noutputs (const gasm *g)
-Return the number of output operands for @code{GIMPLE_ASM} @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} unsigned gimple_asm_nclobbers (const gasm *g)
-Return the number of clobber operands for @code{GIMPLE_ASM} @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} tree gimple_asm_input_op (const gasm *g, @
-unsigned index)
-Return input operand @code{INDEX} of @code{GIMPLE_ASM} @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_asm_set_input_op (gasm *g, @
-unsigned index, tree in_op)
-Set @code{IN_OP} to be input operand @code{INDEX} in @code{GIMPLE_ASM} @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} tree gimple_asm_output_op (const gasm *g, @
-unsigned index)
-Return output operand @code{INDEX} of @code{GIMPLE_ASM} @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_asm_set_output_op (gasm *g, @
-unsigned index, tree out_op)
-Set @code{OUT_OP} to be output operand @code{INDEX} in @code{GIMPLE_ASM} @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} tree gimple_asm_clobber_op (const gasm *g, @
-unsigned index)
-Return clobber operand @code{INDEX} of @code{GIMPLE_ASM} @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_asm_set_clobber_op (gasm *g, @
-unsigned index, tree clobber_op)
-Set @code{CLOBBER_OP} to be clobber operand @code{INDEX} in @code{GIMPLE_ASM} @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} {const char *} gimple_asm_string (const gasm *g)
-Return the string representing the assembly instruction in
-@code{GIMPLE_ASM} @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} bool gimple_asm_volatile_p (const gasm *g)
-Return true if @code{G} is an asm statement marked volatile.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_asm_set_volatile (gasm *g, @
-bool volatile_p)
-Mark asm statement @code{G} as volatile or non-volatile based on
-@code{VOLATILE_P}.
-@end deftypefn
-
-@node @code{GIMPLE_ASSIGN}
-@subsection @code{GIMPLE_ASSIGN}
-@cindex @code{GIMPLE_ASSIGN}
-
-@deftypefn {GIMPLE function} gassign *gimple_build_assign (tree lhs, tree rhs)
-Build a @code{GIMPLE_ASSIGN} statement. The left-hand side is an lvalue
-passed in lhs. The right-hand side can be either a unary or
-binary tree expression. The expression tree rhs will be
-flattened and its operands assigned to the corresponding operand
-slots in the new statement. This function is useful when you
-already have a tree expression that you want to convert into a
-tuple. However, try to avoid building expression trees for the
-sole purpose of calling this function. If you already have the
-operands in separate trees, it is better to use
-@code{gimple_build_assign} with @code{enum tree_code} argument and separate
-arguments for each operand.
-@end deftypefn
-
-@deftypefn {GIMPLE function} gassign *gimple_build_assign @
-(tree lhs, enum tree_code subcode, tree op1, tree op2, tree op3)
-This function is similar to two operand @code{gimple_build_assign},
-but is used to build a @code{GIMPLE_ASSIGN} statement when the operands of the
-right-hand side of the assignment are already split into
-different operands.
-
-The left-hand side is an lvalue passed in lhs. Subcode is the
-@code{tree_code} for the right-hand side of the assignment. Op1, op2 and op3
-are the operands.
-@end deftypefn
-
-@deftypefn {GIMPLE function} gassign *gimple_build_assign @
-(tree lhs, enum tree_code subcode, tree op1, tree op2)
-Like the above 5 operand @code{gimple_build_assign}, but with the last
-argument @code{NULL} - this overload should not be used for
-@code{GIMPLE_TERNARY_RHS} assignments.
-@end deftypefn
-
-@deftypefn {GIMPLE function} gassign *gimple_build_assign @
-(tree lhs, enum tree_code subcode, tree op1)
-Like the above 4 operand @code{gimple_build_assign}, but with the last
-argument @code{NULL} - this overload should be used only for
-@code{GIMPLE_UNARY_RHS} and @code{GIMPLE_SINGLE_RHS} assignments.
-@end deftypefn
-
-@deftypefn {GIMPLE function} gimple gimplify_assign (tree dst, tree src, gimple_seq *seq_p)
-Build a new @code{GIMPLE_ASSIGN} tuple and append it to the end of
-@code{*SEQ_P}.
-@end deftypefn
-
-@code{DST}/@code{SRC} are the destination and source respectively. You can
-pass ungimplified trees in @code{DST} or @code{SRC}, in which
-case they will be converted to a gimple operand if necessary.
-
-This function returns the newly created @code{GIMPLE_ASSIGN} tuple.
-
-@deftypefn {GIMPLE function} {enum tree_code} gimple_assign_rhs_code (gimple g)
-Return the code of the expression computed on the @code{RHS} of
-assignment statement @code{G}.
-@end deftypefn
-
-
-@deftypefn {GIMPLE function} {enum gimple_rhs_class} gimple_assign_rhs_class (gimple g)
-Return the gimple rhs class of the code for the expression
-computed on the rhs of assignment statement @code{G}. This will never
-return @code{GIMPLE_INVALID_RHS}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} tree gimple_assign_lhs (gimple g)
-Return the @code{LHS} of assignment statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} {tree *} gimple_assign_lhs_ptr (gimple g)
-Return a pointer to the @code{LHS} of assignment statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} tree gimple_assign_rhs1 (gimple g)
-Return the first operand on the @code{RHS} of assignment statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} {tree *} gimple_assign_rhs1_ptr (gimple g)
-Return the address of the first operand on the @code{RHS} of assignment
-statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} tree gimple_assign_rhs2 (gimple g)
-Return the second operand on the @code{RHS} of assignment statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} {tree *} gimple_assign_rhs2_ptr (gimple g)
-Return the address of the second operand on the @code{RHS} of assignment
-statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} tree gimple_assign_rhs3 (gimple g)
-Return the third operand on the @code{RHS} of assignment statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} {tree *} gimple_assign_rhs3_ptr (gimple g)
-Return the address of the third operand on the @code{RHS} of assignment
-statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_assign_set_lhs (gimple g, tree lhs)
-Set @code{LHS} to be the @code{LHS} operand of assignment statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_assign_set_rhs1 (gimple g, tree rhs)
-Set @code{RHS} to be the first operand on the @code{RHS} of assignment
-statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_assign_set_rhs2 (gimple g, tree rhs)
-Set @code{RHS} to be the second operand on the @code{RHS} of assignment
-statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_assign_set_rhs3 (gimple g, tree rhs)
-Set @code{RHS} to be the third operand on the @code{RHS} of assignment
-statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} bool gimple_assign_cast_p (const_gimple s)
-Return true if @code{S} is a type-cast assignment.
-@end deftypefn
-
-
-@node @code{GIMPLE_BIND}
-@subsection @code{GIMPLE_BIND}
-@cindex @code{GIMPLE_BIND}
-
-@deftypefn {GIMPLE function} gbind *gimple_build_bind (tree vars, @
-gimple_seq body)
-Build a @code{GIMPLE_BIND} statement with a list of variables in @code{VARS}
-and a body of statements in sequence @code{BODY}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} tree gimple_bind_vars (const gbind *g)
-Return the variables declared in the @code{GIMPLE_BIND} statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_bind_set_vars (gbind *g, tree vars)
-Set @code{VARS} to be the set of variables declared in the @code{GIMPLE_BIND}
-statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_bind_append_vars (gbind *g, tree vars)
-Append @code{VARS} to the set of variables declared in the @code{GIMPLE_BIND}
-statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} gimple_seq gimple_bind_body (gbind *g)
-Return the GIMPLE sequence contained in the @code{GIMPLE_BIND} statement
-@code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_bind_set_body (gbind *g, @
-gimple_seq seq)
-Set @code{SEQ} to be sequence contained in the @code{GIMPLE_BIND} statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_bind_add_stmt (gbind *gs, gimple stmt)
-Append a statement to the end of a @code{GIMPLE_BIND}'s body.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_bind_add_seq (gbind *gs, @
-gimple_seq seq)
-Append a sequence of statements to the end of a @code{GIMPLE_BIND}'s
-body.
-@end deftypefn
-
-@deftypefn {GIMPLE function} tree gimple_bind_block (const gbind *g)
-Return the @code{TREE_BLOCK} node associated with @code{GIMPLE_BIND} statement
-@code{G}. This is analogous to the @code{BIND_EXPR_BLOCK} field in trees.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_bind_set_block (gbind *g, tree block)
-Set @code{BLOCK} to be the @code{TREE_BLOCK} node associated with @code{GIMPLE_BIND}
-statement @code{G}.
-@end deftypefn
-
-
-@node @code{GIMPLE_CALL}
-@subsection @code{GIMPLE_CALL}
-@cindex @code{GIMPLE_CALL}
-
-@deftypefn {GIMPLE function} gcall *gimple_build_call (tree fn, @
-unsigned nargs, ...)
-Build a @code{GIMPLE_CALL} statement to function @code{FN}. The argument @code{FN}
-must be either a @code{FUNCTION_DECL} or a gimple call address as
-determined by @code{is_gimple_call_addr}. @code{NARGS} are the number of
-arguments. The rest of the arguments follow the argument @code{NARGS},
-and must be trees that are valid as rvalues in gimple (i.e., each
-operand is validated with @code{is_gimple_operand}).
-@end deftypefn
-
-
-@deftypefn {GIMPLE function} gcall *gimple_build_call_from_tree (tree call_expr, @
-tree fnptrtype)
-Build a @code{GIMPLE_CALL} from a @code{CALL_EXPR} node. The arguments
-and the function are taken from the expression directly. The type of the
-@code{GIMPLE_CALL} is set from the second parameter passed by a caller.
-This routine assumes that @code{call_expr} is already in GIMPLE form.
-That is, its operands are GIMPLE values and the function call needs no further
-simplification. All the call flags in @code{call_expr} are copied over
-to the new @code{GIMPLE_CALL}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} gcall *gimple_build_call_vec (tree fn, @
-@code{vec<tree>} args)
-Identical to @code{gimple_build_call} but the arguments are stored in a
-@code{vec<tree>}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} tree gimple_call_lhs (gimple g)
-Return the @code{LHS} of call statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} {tree *} gimple_call_lhs_ptr (gimple g)
-Return a pointer to the @code{LHS} of call statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_call_set_lhs (gimple g, tree lhs)
-Set @code{LHS} to be the @code{LHS} operand of call statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} tree gimple_call_fn (gimple g)
-Return the tree node representing the function called by call
-statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_call_set_fn (gcall *g, tree fn)
-Set @code{FN} to be the function called by call statement @code{G}. This has
-to be a gimple value specifying the address of the called
-function.
-@end deftypefn
-
-@deftypefn {GIMPLE function} tree gimple_call_fndecl (gimple g)
-If a given @code{GIMPLE_CALL}'s callee is a @code{FUNCTION_DECL}, return it.
-Otherwise return @code{NULL}. This function is analogous to
-@code{get_callee_fndecl} in @code{GENERIC}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} tree gimple_call_set_fndecl (gimple g, tree fndecl)
-Set the called function to @code{FNDECL}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} tree gimple_call_return_type (const gcall *g)
-Return the type returned by call statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} tree gimple_call_chain (gimple g)
-Return the static chain for call statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_call_set_chain (gcall *g, tree chain)
-Set @code{CHAIN} to be the static chain for call statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} unsigned gimple_call_num_args (gimple g)
-Return the number of arguments used by call statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} tree gimple_call_arg (gimple g, unsigned index)
-Return the argument at position @code{INDEX} for call statement @code{G}. The
-first argument is 0.
-@end deftypefn
-
-@deftypefn {GIMPLE function} {tree *} gimple_call_arg_ptr (gimple g, unsigned index)
-Return a pointer to the argument at position @code{INDEX} for call
-statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_call_set_arg (gimple g, unsigned index, tree arg)
-Set @code{ARG} to be the argument at position @code{INDEX} for call statement
-@code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_call_set_tail (gcall *s)
-Mark call statement @code{S} as being a tail call (i.e., a call just
-before the exit of a function). These calls are candidate for
-tail call optimization.
-@end deftypefn
-
-@deftypefn {GIMPLE function} bool gimple_call_tail_p (gcall *s)
-Return true if @code{GIMPLE_CALL} @code{S} is marked as a tail call.
-@end deftypefn
-
-@deftypefn {GIMPLE function} bool gimple_call_noreturn_p (gimple s)
-Return true if @code{S} is a noreturn call.
-@end deftypefn
-
-@deftypefn {GIMPLE function} gimple gimple_call_copy_skip_args (gcall *stmt, @
-bitmap args_to_skip)
-Build a @code{GIMPLE_CALL} identical to @code{STMT} but skipping the arguments
-in the positions marked by the set @code{ARGS_TO_SKIP}.
-@end deftypefn
-
-
-@node @code{GIMPLE_CATCH}
-@subsection @code{GIMPLE_CATCH}
-@cindex @code{GIMPLE_CATCH}
-
-@deftypefn {GIMPLE function} gcatch *gimple_build_catch (tree types, @
-gimple_seq handler)
-Build a @code{GIMPLE_CATCH} statement. @code{TYPES} are the tree types this
-catch handles. @code{HANDLER} is a sequence of statements with the code
-for the handler.
-@end deftypefn
-
-@deftypefn {GIMPLE function} tree gimple_catch_types (const gcatch *g)
-Return the types handled by @code{GIMPLE_CATCH} statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} {tree *} gimple_catch_types_ptr (gcatch *g)
-Return a pointer to the types handled by @code{GIMPLE_CATCH} statement
-@code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} gimple_seq gimple_catch_handler (gcatch *g)
-Return the GIMPLE sequence representing the body of the handler
-of @code{GIMPLE_CATCH} statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_catch_set_types (gcatch *g, tree t)
-Set @code{T} to be the set of types handled by @code{GIMPLE_CATCH} @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_catch_set_handler (gcatch *g, @
-gimple_seq handler)
-Set @code{HANDLER} to be the body of @code{GIMPLE_CATCH} @code{G}.
-@end deftypefn
-
-
-@node @code{GIMPLE_COND}
-@subsection @code{GIMPLE_COND}
-@cindex @code{GIMPLE_COND}
-
-@deftypefn {GIMPLE function} gcond *gimple_build_cond ( @
-enum tree_code pred_code, tree lhs, tree rhs, tree t_label, tree f_label)
-Build a @code{GIMPLE_COND} statement. @code{A} @code{GIMPLE_COND} statement compares
-@code{LHS} and @code{RHS} and if the condition in @code{PRED_CODE} is true, jump to
-the label in @code{t_label}, otherwise jump to the label in @code{f_label}.
-@code{PRED_CODE} are relational operator tree codes like @code{EQ_EXPR},
-@code{LT_EXPR}, @code{LE_EXPR}, @code{NE_EXPR}, etc.
-@end deftypefn
-
-
-@deftypefn {GIMPLE function} gcond *gimple_build_cond_from_tree (tree cond, @
-tree t_label, tree f_label)
-Build a @code{GIMPLE_COND} statement from the conditional expression
-tree @code{COND}. @code{T_LABEL} and @code{F_LABEL} are as in @code{gimple_build_cond}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} {enum tree_code} gimple_cond_code (gimple g)
-Return the code of the predicate computed by conditional
-statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_cond_set_code (gcond *g, @
-enum tree_code code)
-Set @code{CODE} to be the predicate code for the conditional statement
-@code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} tree gimple_cond_lhs (gimple g)
-Return the @code{LHS} of the predicate computed by conditional statement
-@code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_cond_set_lhs (gcond *g, tree lhs)
-Set @code{LHS} to be the @code{LHS} operand of the predicate computed by
-conditional statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} tree gimple_cond_rhs (gimple g)
-Return the @code{RHS} operand of the predicate computed by conditional
-@code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_cond_set_rhs (gcond *g, tree rhs)
-Set @code{RHS} to be the @code{RHS} operand of the predicate computed by
-conditional statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} tree gimple_cond_true_label (const gcond *g)
-Return the label used by conditional statement @code{G} when its
-predicate evaluates to true.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_cond_set_true_label (gcond *g, tree label)
-Set @code{LABEL} to be the label used by conditional statement @code{G} when
-its predicate evaluates to true.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_cond_set_false_label (gcond *g, tree label)
-Set @code{LABEL} to be the label used by conditional statement @code{G} when
-its predicate evaluates to false.
-@end deftypefn
-
-@deftypefn {GIMPLE function} tree gimple_cond_false_label (const gcond *g)
-Return the label used by conditional statement @code{G} when its
-predicate evaluates to false.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_cond_make_false (gcond *g)
-Set the conditional @code{COND_STMT} to be of the form 'if (1 == 0)'.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_cond_make_true (gcond *g)
-Set the conditional @code{COND_STMT} to be of the form 'if (1 == 1)'.
-@end deftypefn
-
-@node @code{GIMPLE_DEBUG}
-@subsection @code{GIMPLE_DEBUG}
-@cindex @code{GIMPLE_DEBUG}
-@cindex @code{GIMPLE_DEBUG_BIND}
-@cindex @code{GIMPLE_DEBUG_BEGIN_STMT}
-@cindex @code{GIMPLE_DEBUG_INLINE_ENTRY}
-
-@deftypefn {GIMPLE function} gdebug *gimple_build_debug_bind (tree var, @
-tree value, gimple stmt)
-Build a @code{GIMPLE_DEBUG} statement with @code{GIMPLE_DEBUG_BIND}
-@code{subcode}. The effect of this statement is to tell debug
-information generation machinery that the value of user variable
-@code{var} is given by @code{value} at that point, and to remain with
-that value until @code{var} runs out of scope, a
-dynamically-subsequent debug bind statement overrides the binding, or
-conflicting values reach a control flow merge point. Even if
-components of the @code{value} expression change afterwards, the
-variable is supposed to retain the same value, though not necessarily
-the same location.
-
-It is expected that @code{var} be most often a tree for automatic user
-variables (@code{VAR_DECL} or @code{PARM_DECL}) that satisfy the
-requirements for gimple registers, but it may also be a tree for a
-scalarized component of a user variable (@code{ARRAY_REF},
-@code{COMPONENT_REF}), or a debug temporary (@code{DEBUG_EXPR_DECL}).
-
-As for @code{value}, it can be an arbitrary tree expression, but it is
-recommended that it be in a suitable form for a gimple assignment
-@code{RHS}. It is not expected that user variables that could appear
-as @code{var} ever appear in @code{value}, because in the latter we'd
-have their @code{SSA_NAME}s instead, but even if they were not in SSA
-form, user variables appearing in @code{value} are to be regarded as
-part of the executable code space, whereas those in @code{var} are to
-be regarded as part of the source code space. There is no way to
-refer to the value bound to a user variable within a @code{value}
-expression.
-
-If @code{value} is @code{GIMPLE_DEBUG_BIND_NOVALUE}, debug information
-generation machinery is informed that the variable @code{var} is
-unbound, i.e., that its value is indeterminate, which sometimes means
-it is really unavailable, and other times that the compiler could not
-keep track of it.
-
-Block and location information for the newly-created stmt are
-taken from @code{stmt}, if given.
-@end deftypefn
-
-@deftypefn {GIMPLE function} tree gimple_debug_bind_get_var (gimple stmt)
-Return the user variable @var{var} that is bound at @code{stmt}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} tree gimple_debug_bind_get_value (gimple stmt)
-Return the value expression that is bound to a user variable at
-@code{stmt}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} {tree *} gimple_debug_bind_get_value_ptr (gimple stmt)
-Return a pointer to the value expression that is bound to a user
-variable at @code{stmt}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_debug_bind_set_var (gimple stmt, tree var)
-Modify the user variable bound at @code{stmt} to @var{var}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_debug_bind_set_value (gimple stmt, tree var)
-Modify the value bound to the user variable bound at @code{stmt} to
-@var{value}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_debug_bind_reset_value (gimple stmt)
-Modify the value bound to the user variable bound at @code{stmt} so
-that the variable becomes unbound.
-@end deftypefn
-
-@deftypefn {GIMPLE function} bool gimple_debug_bind_has_value_p (gimple stmt)
-Return @code{TRUE} if @code{stmt} binds a user variable to a value,
-and @code{FALSE} if it unbinds the variable.
-@end deftypefn
-
-@deftypefn {GIMPLE function} gimple gimple_build_debug_begin_stmt (tree block, location_t location)
-Build a @code{GIMPLE_DEBUG} statement with
-@code{GIMPLE_DEBUG_BEGIN_STMT} @code{subcode}. The effect of this
-statement is to tell debug information generation machinery that the
-user statement at the given @code{location} and @code{block} starts at
-the point at which the statement is inserted. The intent is that side
-effects (e.g.@: variable bindings) of all prior user statements are
-observable, and that none of the side effects of subsequent user
-statements are.
-@end deftypefn
-
-@deftypefn {GIMPLE function} gimple gimple_build_debug_inline_entry (tree block, location_t location)
-Build a @code{GIMPLE_DEBUG} statement with
-@code{GIMPLE_DEBUG_INLINE_ENTRY} @code{subcode}. The effect of this
-statement is to tell debug information generation machinery that a
-function call at @code{location} underwent inline substitution, that
-@code{block} is the enclosing lexical block created for the
-substitution, and that at the point of the program in which the stmt is
-inserted, all parameters for the inlined function are bound to the
-respective arguments, and none of the side effects of its stmts are
-observable.
-@end deftypefn
-
-@node @code{GIMPLE_EH_FILTER}
-@subsection @code{GIMPLE_EH_FILTER}
-@cindex @code{GIMPLE_EH_FILTER}
-
-@deftypefn {GIMPLE function} geh_filter *gimple_build_eh_filter (tree types, @
-gimple_seq failure)
-Build a @code{GIMPLE_EH_FILTER} statement. @code{TYPES} are the filter's
-types. @code{FAILURE} is a sequence with the filter's failure action.
-@end deftypefn
-
-@deftypefn {GIMPLE function} tree gimple_eh_filter_types (gimple g)
-Return the types handled by @code{GIMPLE_EH_FILTER} statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} {tree *} gimple_eh_filter_types_ptr (gimple g)
-Return a pointer to the types handled by @code{GIMPLE_EH_FILTER}
-statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} gimple_seq gimple_eh_filter_failure (gimple g)
-Return the sequence of statement to execute when @code{GIMPLE_EH_FILTER}
-statement fails.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_eh_filter_set_types (geh_filter *g, @
-tree types)
-Set @code{TYPES} to be the set of types handled by @code{GIMPLE_EH_FILTER} @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_eh_filter_set_failure (geh_filter *g, @
-gimple_seq failure)
-Set @code{FAILURE} to be the sequence of statements to execute on
-failure for @code{GIMPLE_EH_FILTER} @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} tree gimple_eh_must_not_throw_fndecl ( @
-geh_mnt *eh_mnt_stmt)
-Get the function decl to be called by the MUST_NOT_THROW region.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_eh_must_not_throw_set_fndecl ( @
-geh_mnt *eh_mnt_stmt, tree decl)
-Set the function decl to be called by GS to DECL.
-@end deftypefn
-
-
-@node @code{GIMPLE_LABEL}
-@subsection @code{GIMPLE_LABEL}
-@cindex @code{GIMPLE_LABEL}
-
-@deftypefn {GIMPLE function} glabel *gimple_build_label (tree label)
-Build a @code{GIMPLE_LABEL} statement with corresponding to the tree
-label, @code{LABEL}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} tree gimple_label_label (const glabel *g)
-Return the @code{LABEL_DECL} node used by @code{GIMPLE_LABEL} statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_label_set_label (glabel *g, tree label)
-Set @code{LABEL} to be the @code{LABEL_DECL} node used by @code{GIMPLE_LABEL}
-statement @code{G}.
-@end deftypefn
-
-@node @code{GIMPLE_GOTO}
-@subsection @code{GIMPLE_GOTO}
-@cindex @code{GIMPLE_GOTO}
-
-@deftypefn {GIMPLE function} ggoto *gimple_build_goto (tree dest)
-Build a @code{GIMPLE_GOTO} statement to label @code{DEST}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} tree gimple_goto_dest (gimple g)
-Return the destination of the unconditional jump @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_goto_set_dest (ggoto *g, tree dest)
-Set @code{DEST} to be the destination of the unconditional jump @code{G}.
-@end deftypefn
-
-
-@node @code{GIMPLE_NOP}
-@subsection @code{GIMPLE_NOP}
-@cindex @code{GIMPLE_NOP}
-
-@deftypefn {GIMPLE function} gimple gimple_build_nop (void)
-Build a @code{GIMPLE_NOP} statement.
-@end deftypefn
-
-@deftypefn {GIMPLE function} bool gimple_nop_p (gimple g)
-Returns @code{TRUE} if statement @code{G} is a @code{GIMPLE_NOP}.
-@end deftypefn
-
-@node @code{GIMPLE_OMP_ATOMIC_LOAD}
-@subsection @code{GIMPLE_OMP_ATOMIC_LOAD}
-@cindex @code{GIMPLE_OMP_ATOMIC_LOAD}
-
-@deftypefn {GIMPLE function} gomp_atomic_load *gimple_build_omp_atomic_load ( @
-tree lhs, tree rhs)
-Build a @code{GIMPLE_OMP_ATOMIC_LOAD} statement. @code{LHS} is the left-hand
-side of the assignment. @code{RHS} is the right-hand side of the
-assignment.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_omp_atomic_load_set_lhs ( @
-gomp_atomic_load *g, tree lhs)
-Set the @code{LHS} of an atomic load.
-@end deftypefn
-
-@deftypefn {GIMPLE function} tree gimple_omp_atomic_load_lhs ( @
-const gomp_atomic_load *g)
-Get the @code{LHS} of an atomic load.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_omp_atomic_load_set_rhs ( @
-gomp_atomic_load *g, tree rhs)
-Set the @code{RHS} of an atomic set.
-@end deftypefn
-
-@deftypefn {GIMPLE function} tree gimple_omp_atomic_load_rhs ( @
-const gomp_atomic_load *g)
-Get the @code{RHS} of an atomic set.
-@end deftypefn
-
-
-@node @code{GIMPLE_OMP_ATOMIC_STORE}
-@subsection @code{GIMPLE_OMP_ATOMIC_STORE}
-@cindex @code{GIMPLE_OMP_ATOMIC_STORE}
-
-@deftypefn {GIMPLE function} gomp_atomic_store *gimple_build_omp_atomic_store ( @
-tree val)
-Build a @code{GIMPLE_OMP_ATOMIC_STORE} statement. @code{VAL} is the value to be
-stored.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_omp_atomic_store_set_val ( @
-gomp_atomic_store *g, tree val)
-Set the value being stored in an atomic store.
-@end deftypefn
-
-@deftypefn {GIMPLE function} tree gimple_omp_atomic_store_val ( @
-const gomp_atomic_store *g)
-Return the value being stored in an atomic store.
-@end deftypefn
-
-@node @code{GIMPLE_OMP_CONTINUE}
-@subsection @code{GIMPLE_OMP_CONTINUE}
-@cindex @code{GIMPLE_OMP_CONTINUE}
-
-@deftypefn {GIMPLE function} gomp_continue *gimple_build_omp_continue ( @
-tree control_def, tree control_use)
-Build a @code{GIMPLE_OMP_CONTINUE} statement. @code{CONTROL_DEF} is the
-definition of the control variable. @code{CONTROL_USE} is the use of
-the control variable.
-@end deftypefn
-
-@deftypefn {GIMPLE function} tree gimple_omp_continue_control_def ( @
-const gomp_continue *s)
-Return the definition of the control variable on a
-@code{GIMPLE_OMP_CONTINUE} in @code{S}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} tree gimple_omp_continue_control_def_ptr ( @
-gomp_continue *s)
-Same as above, but return the pointer.
-@end deftypefn
-
-@deftypefn {GIMPLE function} tree gimple_omp_continue_set_control_def ( @
-gomp_continue *s)
-Set the control variable definition for a @code{GIMPLE_OMP_CONTINUE}
-statement in @code{S}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} tree gimple_omp_continue_control_use ( @
-const gomp_continue *s)
-Return the use of the control variable on a @code{GIMPLE_OMP_CONTINUE}
-in @code{S}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} tree gimple_omp_continue_control_use_ptr ( @
-gomp_continue *s)
-Same as above, but return the pointer.
-@end deftypefn
-
-@deftypefn {GIMPLE function} tree gimple_omp_continue_set_control_use ( @
-gomp_continue *s)
-Set the control variable use for a @code{GIMPLE_OMP_CONTINUE} statement
-in @code{S}.
-@end deftypefn
-
-
-@node @code{GIMPLE_OMP_CRITICAL}
-@subsection @code{GIMPLE_OMP_CRITICAL}
-@cindex @code{GIMPLE_OMP_CRITICAL}
-
-@deftypefn {GIMPLE function} gomp_critical *gimple_build_omp_critical ( @
-gimple_seq body, tree name)
-Build a @code{GIMPLE_OMP_CRITICAL} statement. @code{BODY} is the sequence of
-statements for which only one thread can execute. @code{NAME} is an
-optional identifier for this critical block.
-@end deftypefn
-
-@deftypefn {GIMPLE function} tree gimple_omp_critical_name ( @
-const gomp_critical *g)
-Return the name associated with @code{OMP_CRITICAL} statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} {tree *} gimple_omp_critical_name_ptr ( @
-gomp_critical *g)
-Return a pointer to the name associated with @code{OMP} critical
-statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_omp_critical_set_name ( @
-gomp_critical *g, tree name)
-Set @code{NAME} to be the name associated with @code{OMP} critical statement @code{G}.
-@end deftypefn
-
-@node @code{GIMPLE_OMP_FOR}
-@subsection @code{GIMPLE_OMP_FOR}
-@cindex @code{GIMPLE_OMP_FOR}
-
-@deftypefn {GIMPLE function} gomp_for *gimple_build_omp_for (gimple_seq body, @
-tree clauses, tree index, tree initial, tree final, tree incr, @
-gimple_seq pre_body, enum tree_code omp_for_cond)
-Build a @code{GIMPLE_OMP_FOR} statement. @code{BODY} is sequence of statements
-inside the for loop. @code{CLAUSES}, are any of the loop
-construct's clauses. @code{PRE_BODY} is the
-sequence of statements that are loop invariant. @code{INDEX} is the
-index variable. @code{INITIAL} is the initial value of @code{INDEX}. @code{FINAL} is
-final value of @code{INDEX}. OMP_FOR_COND is the predicate used to
-compare @code{INDEX} and @code{FINAL}. @code{INCR} is the increment expression.
-@end deftypefn
-
-@deftypefn {GIMPLE function} tree gimple_omp_for_clauses (gimple g)
-Return the clauses associated with @code{OMP_FOR} @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} {tree *} gimple_omp_for_clauses_ptr (gimple g)
-Return a pointer to the @code{OMP_FOR} @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_omp_for_set_clauses (gimple g, tree clauses)
-Set @code{CLAUSES} to be the list of clauses associated with @code{OMP_FOR} @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} tree gimple_omp_for_index (gimple g)
-Return the index variable for @code{OMP_FOR} @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} {tree *} gimple_omp_for_index_ptr (gimple g)
-Return a pointer to the index variable for @code{OMP_FOR} @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_omp_for_set_index (gimple g, tree index)
-Set @code{INDEX} to be the index variable for @code{OMP_FOR} @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} tree gimple_omp_for_initial (gimple g)
-Return the initial value for @code{OMP_FOR} @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} {tree *} gimple_omp_for_initial_ptr (gimple g)
-Return a pointer to the initial value for @code{OMP_FOR} @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_omp_for_set_initial (gimple g, tree initial)
-Set @code{INITIAL} to be the initial value for @code{OMP_FOR} @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} tree gimple_omp_for_final (gimple g)
-Return the final value for @code{OMP_FOR} @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} {tree *} gimple_omp_for_final_ptr (gimple g)
-turn a pointer to the final value for @code{OMP_FOR} @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_omp_for_set_final (gimple g, tree final)
-Set @code{FINAL} to be the final value for @code{OMP_FOR} @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} tree gimple_omp_for_incr (gimple g)
-Return the increment value for @code{OMP_FOR} @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} {tree *} gimple_omp_for_incr_ptr (gimple g)
-Return a pointer to the increment value for @code{OMP_FOR} @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_omp_for_set_incr (gimple g, tree incr)
-Set @code{INCR} to be the increment value for @code{OMP_FOR} @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} gimple_seq gimple_omp_for_pre_body (gimple g)
-Return the sequence of statements to execute before the @code{OMP_FOR}
-statement @code{G} starts.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_omp_for_set_pre_body (gimple g, gimple_seq pre_body)
-Set @code{PRE_BODY} to be the sequence of statements to execute before
-the @code{OMP_FOR} statement @code{G} starts.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_omp_for_set_cond (gimple g, enum tree_code cond)
-Set @code{COND} to be the condition code for @code{OMP_FOR} @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} {enum tree_code} gimple_omp_for_cond (gimple g)
-Return the condition code associated with @code{OMP_FOR} @code{G}.
-@end deftypefn
-
-
-@node @code{GIMPLE_OMP_MASTER}
-@subsection @code{GIMPLE_OMP_MASTER}
-@cindex @code{GIMPLE_OMP_MASTER}
-
-@deftypefn {GIMPLE function} gimple gimple_build_omp_master (gimple_seq body)
-Build a @code{GIMPLE_OMP_MASTER} statement. @code{BODY} is the sequence of
-statements to be executed by just the master.
-@end deftypefn
-
-
-@node @code{GIMPLE_OMP_ORDERED}
-@subsection @code{GIMPLE_OMP_ORDERED}
-@cindex @code{GIMPLE_OMP_ORDERED}
-
-@deftypefn {GIMPLE function} gimple gimple_build_omp_ordered (gimple_seq body)
-Build a @code{GIMPLE_OMP_ORDERED} statement.
-
-@code{BODY} is the sequence of statements inside a loop that will
-executed in sequence.
-@end deftypefn
-
-@node @code{GIMPLE_OMP_PARALLEL}
-@subsection @code{GIMPLE_OMP_PARALLEL}
-@cindex @code{GIMPLE_OMP_PARALLEL}
-
-@deftypefn {GIMPLE function} gomp_parallel *gimple_build_omp_parallel (@
-gimple_seq body, tree clauses, tree child_fn, tree data_arg)
-Build a @code{GIMPLE_OMP_PARALLEL} statement.
-
-@code{BODY} is sequence of statements which are executed in parallel.
-@code{CLAUSES}, are the @code{OMP} parallel construct's clauses. @code{CHILD_FN} is
-the function created for the parallel threads to execute.
-@code{DATA_ARG} are the shared data argument(s).
-@end deftypefn
-
-@deftypefn {GIMPLE function} bool gimple_omp_parallel_combined_p (gimple g)
-Return true if @code{OMP} parallel statement @code{G} has the
-@code{GF_OMP_PARALLEL_COMBINED} flag set.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_omp_parallel_set_combined_p (gimple g)
-Set the @code{GF_OMP_PARALLEL_COMBINED} field in @code{OMP} parallel statement
-@code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} gimple_seq gimple_omp_body (gimple g)
-Return the body for the @code{OMP} statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_omp_set_body (gimple g, gimple_seq body)
-Set @code{BODY} to be the body for the @code{OMP} statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} tree gimple_omp_parallel_clauses (gimple g)
-Return the clauses associated with @code{OMP_PARALLEL} @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} {tree *} gimple_omp_parallel_clauses_ptr ( @
-gomp_parallel *g)
-Return a pointer to the clauses associated with @code{OMP_PARALLEL} @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_omp_parallel_set_clauses ( @
-gomp_parallel *g, tree clauses)
-Set @code{CLAUSES} to be the list of clauses associated with
-@code{OMP_PARALLEL} @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} tree gimple_omp_parallel_child_fn ( @
-const gomp_parallel *g)
-Return the child function used to hold the body of @code{OMP_PARALLEL}
-@code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} {tree *} gimple_omp_parallel_child_fn_ptr ( @
-gomp_parallel *g)
-Return a pointer to the child function used to hold the body of
-@code{OMP_PARALLEL} @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_omp_parallel_set_child_fn ( @
-gomp_parallel *g, tree child_fn)
-Set @code{CHILD_FN} to be the child function for @code{OMP_PARALLEL} @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} tree gimple_omp_parallel_data_arg ( @
-const gomp_parallel *g)
-Return the artificial argument used to send variables and values
-from the parent to the children threads in @code{OMP_PARALLEL} @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} {tree *} gimple_omp_parallel_data_arg_ptr ( @
-gomp_parallel *g)
-Return a pointer to the data argument for @code{OMP_PARALLEL} @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_omp_parallel_set_data_arg ( @
-gomp_parallel *g, tree data_arg)
-Set @code{DATA_ARG} to be the data argument for @code{OMP_PARALLEL} @code{G}.
-@end deftypefn
-
-
-@node @code{GIMPLE_OMP_RETURN}
-@subsection @code{GIMPLE_OMP_RETURN}
-@cindex @code{GIMPLE_OMP_RETURN}
-
-@deftypefn {GIMPLE function} gimple gimple_build_omp_return (bool wait_p)
-Build a @code{GIMPLE_OMP_RETURN} statement. @code{WAIT_P} is true if this is a
-non-waiting return.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_omp_return_set_nowait (gimple s)
-Set the nowait flag on @code{GIMPLE_OMP_RETURN} statement @code{S}.
-@end deftypefn
-
-
-@deftypefn {GIMPLE function} bool gimple_omp_return_nowait_p (gimple g)
-Return true if @code{OMP} return statement @code{G} has the
-@code{GF_OMP_RETURN_NOWAIT} flag set.
-@end deftypefn
-
-@node @code{GIMPLE_OMP_SECTION}
-@subsection @code{GIMPLE_OMP_SECTION}
-@cindex @code{GIMPLE_OMP_SECTION}
-
-@deftypefn {GIMPLE function} gimple gimple_build_omp_section (gimple_seq body)
-Build a @code{GIMPLE_OMP_SECTION} statement for a sections statement.
-
-@code{BODY} is the sequence of statements in the section.
-@end deftypefn
-
-@deftypefn {GIMPLE function} bool gimple_omp_section_last_p (gimple g)
-Return true if @code{OMP} section statement @code{G} has the
-@code{GF_OMP_SECTION_LAST} flag set.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_omp_section_set_last (gimple g)
-Set the @code{GF_OMP_SECTION_LAST} flag on @code{G}.
-@end deftypefn
-
-@node @code{GIMPLE_OMP_SECTIONS}
-@subsection @code{GIMPLE_OMP_SECTIONS}
-@cindex @code{GIMPLE_OMP_SECTIONS}
-
-@deftypefn {GIMPLE function} gomp_sections *gimple_build_omp_sections ( @
-gimple_seq body, tree clauses)
-Build a @code{GIMPLE_OMP_SECTIONS} statement. @code{BODY} is a sequence of
-section statements. @code{CLAUSES} are any of the @code{OMP} sections
-construct's clauses: private, firstprivate, lastprivate,
-reduction, and nowait.
-@end deftypefn
-
-
-@deftypefn {GIMPLE function} gimple gimple_build_omp_sections_switch (void)
-Build a @code{GIMPLE_OMP_SECTIONS_SWITCH} statement.
-@end deftypefn
-
-@deftypefn {GIMPLE function} tree gimple_omp_sections_control (gimple g)
-Return the control variable associated with the
-@code{GIMPLE_OMP_SECTIONS} in @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} {tree *} gimple_omp_sections_control_ptr (gimple g)
-Return a pointer to the clauses associated with the
-@code{GIMPLE_OMP_SECTIONS} in @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_omp_sections_set_control (gimple g, tree control)
-Set @code{CONTROL} to be the set of clauses associated with the
-@code{GIMPLE_OMP_SECTIONS} in @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} tree gimple_omp_sections_clauses (gimple g)
-Return the clauses associated with @code{OMP_SECTIONS} @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} {tree *} gimple_omp_sections_clauses_ptr (gimple g)
-Return a pointer to the clauses associated with @code{OMP_SECTIONS} @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_omp_sections_set_clauses (gimple g, tree clauses)
-Set @code{CLAUSES} to be the set of clauses associated with @code{OMP_SECTIONS}
-@code{G}.
-@end deftypefn
-
-
-@node @code{GIMPLE_OMP_SINGLE}
-@subsection @code{GIMPLE_OMP_SINGLE}
-@cindex @code{GIMPLE_OMP_SINGLE}
-
-@deftypefn {GIMPLE function} gomp_single *gimple_build_omp_single ( @
-gimple_seq body, tree clauses)
-Build a @code{GIMPLE_OMP_SINGLE} statement. @code{BODY} is the sequence of
-statements that will be executed once. @code{CLAUSES} are any of the
-@code{OMP} single construct's clauses: private, firstprivate,
-copyprivate, nowait.
-@end deftypefn
-
-@deftypefn {GIMPLE function} tree gimple_omp_single_clauses (gimple g)
-Return the clauses associated with @code{OMP_SINGLE} @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} {tree *} gimple_omp_single_clauses_ptr (gimple g)
-Return a pointer to the clauses associated with @code{OMP_SINGLE} @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_omp_single_set_clauses ( @
-gomp_single *g, tree clauses)
-Set @code{CLAUSES} to be the clauses associated with @code{OMP_SINGLE} @code{G}.
-@end deftypefn
-
-
-@node @code{GIMPLE_PHI}
-@subsection @code{GIMPLE_PHI}
-@cindex @code{GIMPLE_PHI}
-
-@deftypefn {GIMPLE function} unsigned gimple_phi_capacity (gimple g)
-Return the maximum number of arguments supported by @code{GIMPLE_PHI} @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} unsigned gimple_phi_num_args (gimple g)
-Return the number of arguments in @code{GIMPLE_PHI} @code{G}. This must always
-be exactly the number of incoming edges for the basic block
-holding @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} tree gimple_phi_result (gimple g)
-Return the @code{SSA} name created by @code{GIMPLE_PHI} @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} {tree *} gimple_phi_result_ptr (gimple g)
-Return a pointer to the @code{SSA} name created by @code{GIMPLE_PHI} @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_phi_set_result (gphi *g, tree result)
-Set @code{RESULT} to be the @code{SSA} name created by @code{GIMPLE_PHI} @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} {struct phi_arg_d *} gimple_phi_arg (gimple g, index)
-Return the @code{PHI} argument corresponding to incoming edge @code{INDEX} for
-@code{GIMPLE_PHI} @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_phi_set_arg (gphi *g, index, @
-struct phi_arg_d * phiarg)
-Set @code{PHIARG} to be the argument corresponding to incoming edge
-@code{INDEX} for @code{GIMPLE_PHI} @code{G}.
-@end deftypefn
-
-@node @code{GIMPLE_RESX}
-@subsection @code{GIMPLE_RESX}
-@cindex @code{GIMPLE_RESX}
-
-@deftypefn {GIMPLE function} gresx *gimple_build_resx (int region)
-Build a @code{GIMPLE_RESX} statement which is a statement. This
-statement is a placeholder for _Unwind_Resume before we know if a
-function call or a branch is needed. @code{REGION} is the exception
-region from which control is flowing.
-@end deftypefn
-
-@deftypefn {GIMPLE function} int gimple_resx_region (const gresx *g)
-Return the region number for @code{GIMPLE_RESX} @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_resx_set_region (gresx *g, int region)
-Set @code{REGION} to be the region number for @code{GIMPLE_RESX} @code{G}.
-@end deftypefn
-
-@node @code{GIMPLE_RETURN}
-@subsection @code{GIMPLE_RETURN}
-@cindex @code{GIMPLE_RETURN}
-
-@deftypefn {GIMPLE function} greturn *gimple_build_return (tree retval)
-Build a @code{GIMPLE_RETURN} statement whose return value is retval.
-@end deftypefn
-
-@deftypefn {GIMPLE function} tree gimple_return_retval (const greturn *g)
-Return the return value for @code{GIMPLE_RETURN} @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_return_set_retval (greturn *g, @
-tree retval)
-Set @code{RETVAL} to be the return value for @code{GIMPLE_RETURN} @code{G}.
-@end deftypefn
-
-@node @code{GIMPLE_SWITCH}
-@subsection @code{GIMPLE_SWITCH}
-@cindex @code{GIMPLE_SWITCH}
-
-@deftypefn {GIMPLE function} gswitch *gimple_build_switch (tree index, @
-tree default_label, @code{vec}<tree> *args)
-Build a @code{GIMPLE_SWITCH} statement. @code{INDEX} is the index variable
-to switch on, and @code{DEFAULT_LABEL} represents the default label.
-@code{ARGS} is a vector of @code{CASE_LABEL_EXPR} trees that contain the
-non-default case labels. Each label is a tree of code @code{CASE_LABEL_EXPR}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} unsigned gimple_switch_num_labels ( @
-const gswitch *g)
-Return the number of labels associated with the switch statement
-@code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_switch_set_num_labels (gswitch *g, @
-unsigned nlabels)
-Set @code{NLABELS} to be the number of labels for the switch statement
-@code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} tree gimple_switch_index (const gswitch *g)
-Return the index variable used by the switch statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_switch_set_index (gswitch *g, @
-tree index)
-Set @code{INDEX} to be the index variable for switch statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} tree gimple_switch_label (const gswitch *g, @
-unsigned index)
-Return the label numbered @code{INDEX}. The default label is 0, followed
-by any labels in a switch statement.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_switch_set_label (gswitch *g, @
-unsigned index, tree label)
-Set the label number @code{INDEX} to @code{LABEL}. 0 is always the default
-label.
-@end deftypefn
-
-@deftypefn {GIMPLE function} tree gimple_switch_default_label ( @
-const gswitch *g)
-Return the default label for a switch statement.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_switch_set_default_label (gswitch *g, @
-tree label)
-Set the default label for a switch statement.
-@end deftypefn
-
-
-@node @code{GIMPLE_TRY}
-@subsection @code{GIMPLE_TRY}
-@cindex @code{GIMPLE_TRY}
-
-@deftypefn {GIMPLE function} gtry *gimple_build_try (gimple_seq eval, @
-gimple_seq cleanup, unsigned int kind)
-Build a @code{GIMPLE_TRY} statement. @code{EVAL} is a sequence with the
-expression to evaluate. @code{CLEANUP} is a sequence of statements to
-run at clean-up time. @code{KIND} is the enumeration value
-@code{GIMPLE_TRY_CATCH} if this statement denotes a try/catch construct
-or @code{GIMPLE_TRY_FINALLY} if this statement denotes a try/finally
-construct.
-@end deftypefn
-
-@deftypefn {GIMPLE function} {enum gimple_try_flags} gimple_try_kind (gimple g)
-Return the kind of try block represented by @code{GIMPLE_TRY} @code{G}. This is
-either @code{GIMPLE_TRY_CATCH} or @code{GIMPLE_TRY_FINALLY}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} bool gimple_try_catch_is_cleanup (gimple g)
-Return the @code{GIMPLE_TRY_CATCH_IS_CLEANUP} flag.
-@end deftypefn
-
-@deftypefn {GIMPLE function} gimple_seq gimple_try_eval (gimple g)
-Return the sequence of statements used as the body for @code{GIMPLE_TRY}
-@code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} gimple_seq gimple_try_cleanup (gimple g)
-Return the sequence of statements used as the cleanup body for
-@code{GIMPLE_TRY} @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_try_set_catch_is_cleanup (gimple g, @
-bool catch_is_cleanup)
-Set the @code{GIMPLE_TRY_CATCH_IS_CLEANUP} flag.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_try_set_eval (gtry *g, gimple_seq eval)
-Set @code{EVAL} to be the sequence of statements to use as the body for
-@code{GIMPLE_TRY} @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_try_set_cleanup (gtry *g, @
-gimple_seq cleanup)
-Set @code{CLEANUP} to be the sequence of statements to use as the
-cleanup body for @code{GIMPLE_TRY} @code{G}.
-@end deftypefn
-
-@node @code{GIMPLE_WITH_CLEANUP_EXPR}
-@subsection @code{GIMPLE_WITH_CLEANUP_EXPR}
-@cindex @code{GIMPLE_WITH_CLEANUP_EXPR}
-
-@deftypefn {GIMPLE function} gimple gimple_build_wce (gimple_seq cleanup)
-Build a @code{GIMPLE_WITH_CLEANUP_EXPR} statement. @code{CLEANUP} is the
-clean-up expression.
-@end deftypefn
-
-@deftypefn {GIMPLE function} gimple_seq gimple_wce_cleanup (gimple g)
-Return the cleanup sequence for cleanup statement @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_wce_set_cleanup (gimple g, gimple_seq cleanup)
-Set @code{CLEANUP} to be the cleanup sequence for @code{G}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} bool gimple_wce_cleanup_eh_only (gimple g)
-Return the @code{CLEANUP_EH_ONLY} flag for a @code{WCE} tuple.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_wce_set_cleanup_eh_only (gimple g, bool eh_only_p)
-Set the @code{CLEANUP_EH_ONLY} flag for a @code{WCE} tuple.
-@end deftypefn
-
-
-@node GIMPLE sequences
-@section GIMPLE sequences
-@cindex GIMPLE sequences
-
-GIMPLE sequences are the tuple equivalent of @code{STATEMENT_LIST}'s
-used in @code{GENERIC}. They are used to chain statements together, and
-when used in conjunction with sequence iterators, provide a
-framework for iterating through statements.
-
-GIMPLE sequences are of type struct @code{gimple_sequence}, but are more
-commonly passed by reference to functions dealing with sequences.
-The type for a sequence pointer is @code{gimple_seq} which is the same
-as struct @code{gimple_sequence} *. When declaring a local sequence,
-you can define a local variable of type struct @code{gimple_sequence}.
-When declaring a sequence allocated on the garbage collected
-heap, use the function @code{gimple_seq_alloc} documented below.
-
-There are convenience functions for iterating through sequences
-in the section entitled Sequence Iterators.
-
-Below is a list of functions to manipulate and query sequences.
-
-@deftypefn {GIMPLE function} void gimple_seq_add_stmt (gimple_seq *seq, gimple g)
-Link a gimple statement to the end of the sequence *@code{SEQ} if @code{G} is
-not @code{NULL}. If *@code{SEQ} is @code{NULL}, allocate a sequence before linking.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_seq_add_seq (gimple_seq *dest, gimple_seq src)
-Append sequence @code{SRC} to the end of sequence *@code{DEST} if @code{SRC} is not
-@code{NULL}. If *@code{DEST} is @code{NULL}, allocate a new sequence before
-appending.
-@end deftypefn
-
-@deftypefn {GIMPLE function} gimple_seq gimple_seq_deep_copy (gimple_seq src)
-Perform a deep copy of sequence @code{SRC} and return the result.
-@end deftypefn
-
-@deftypefn {GIMPLE function} gimple_seq gimple_seq_reverse (gimple_seq seq)
-Reverse the order of the statements in the sequence @code{SEQ}. Return
-@code{SEQ}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} gimple gimple_seq_first (gimple_seq s)
-Return the first statement in sequence @code{S}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} gimple gimple_seq_last (gimple_seq s)
-Return the last statement in sequence @code{S}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_seq_set_last (gimple_seq s, gimple last)
-Set the last statement in sequence @code{S} to the statement in @code{LAST}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_seq_set_first (gimple_seq s, gimple first)
-Set the first statement in sequence @code{S} to the statement in @code{FIRST}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_seq_init (gimple_seq s)
-Initialize sequence @code{S} to an empty sequence.
-@end deftypefn
-
-@deftypefn {GIMPLE function} gimple_seq gimple_seq_alloc (void)
-Allocate a new sequence in the garbage collected store and return
-it.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gimple_seq_copy (gimple_seq dest, gimple_seq src)
-Copy the sequence @code{SRC} into the sequence @code{DEST}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} bool gimple_seq_empty_p (gimple_seq s)
-Return true if the sequence @code{S} is empty.
-@end deftypefn
-
-@deftypefn {GIMPLE function} gimple_seq bb_seq (basic_block bb)
-Returns the sequence of statements in @code{BB}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void set_bb_seq (basic_block bb, gimple_seq seq)
-Sets the sequence of statements in @code{BB} to @code{SEQ}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} bool gimple_seq_singleton_p (gimple_seq seq)
-Determine whether @code{SEQ} contains exactly one statement.
-@end deftypefn
-
-@node Sequence iterators
-@section Sequence iterators
-@cindex Sequence iterators
-
-Sequence iterators are convenience constructs for iterating
-through statements in a sequence. Given a sequence @code{SEQ}, here is
-a typical use of gimple sequence iterators:
-
-@smallexample
-gimple_stmt_iterator gsi;
-
-for (gsi = gsi_start (seq); !gsi_end_p (gsi); gsi_next (&gsi))
- @{
- gimple g = gsi_stmt (gsi);
- /* Do something with gimple statement @code{G}. */
- @}
-@end smallexample
-
-Backward iterations are possible:
-
-@smallexample
- for (gsi = gsi_last (seq); !gsi_end_p (gsi); gsi_prev (&gsi))
-@end smallexample
-
-Forward and backward iterations on basic blocks are possible with
-@code{gsi_start_bb} and @code{gsi_last_bb}.
-
-In the documentation below we sometimes refer to enum
-@code{gsi_iterator_update}. The valid options for this enumeration are:
-
-@itemize @bullet
-@item @code{GSI_NEW_STMT}
-Only valid when a single statement is added. Move the iterator to it.
-
-@item @code{GSI_SAME_STMT}
-Leave the iterator at the same statement.
-
-@item @code{GSI_CONTINUE_LINKING}
-Move iterator to whatever position is suitable for linking other
-statements in the same direction.
-@end itemize
-
-Below is a list of the functions used to manipulate and use
-statement iterators.
-
-@deftypefn {GIMPLE function} gimple_stmt_iterator gsi_start (gimple_seq seq)
-Return a new iterator pointing to the sequence @code{SEQ}'s first
-statement. If @code{SEQ} is empty, the iterator's basic block is @code{NULL}.
-Use @code{gsi_start_bb} instead when the iterator needs to always have
-the correct basic block set.
-@end deftypefn
-
-@deftypefn {GIMPLE function} gimple_stmt_iterator gsi_start_bb (basic_block bb)
-Return a new iterator pointing to the first statement in basic
-block @code{BB}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} gimple_stmt_iterator gsi_last (gimple_seq seq)
-Return a new iterator initially pointing to the last statement of
-sequence @code{SEQ}. If @code{SEQ} is empty, the iterator's basic block is
-@code{NULL}. Use @code{gsi_last_bb} instead when the iterator needs to always
-have the correct basic block set.
-@end deftypefn
-
-@deftypefn {GIMPLE function} gimple_stmt_iterator gsi_last_bb (basic_block bb)
-Return a new iterator pointing to the last statement in basic
-block @code{BB}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} bool gsi_end_p (gimple_stmt_iterator i)
-Return @code{TRUE} if at the end of @code{I}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} bool gsi_one_before_end_p (gimple_stmt_iterator i)
-Return @code{TRUE} if we're one statement before the end of @code{I}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gsi_next (gimple_stmt_iterator *i)
-Advance the iterator to the next gimple statement.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gsi_prev (gimple_stmt_iterator *i)
-Advance the iterator to the previous gimple statement.
-@end deftypefn
-
-@deftypefn {GIMPLE function} gimple gsi_stmt (gimple_stmt_iterator i)
-Return the current stmt.
-@end deftypefn
-
-@deftypefn {GIMPLE function} gimple_stmt_iterator gsi_after_labels (basic_block bb)
-Return a block statement iterator that points to the first
-non-label statement in block @code{BB}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} {gimple *} gsi_stmt_ptr (gimple_stmt_iterator *i)
-Return a pointer to the current stmt.
-@end deftypefn
-
-@deftypefn {GIMPLE function} basic_block gsi_bb (gimple_stmt_iterator i)
-Return the basic block associated with this iterator.
-@end deftypefn
-
-@deftypefn {GIMPLE function} gimple_seq gsi_seq (gimple_stmt_iterator i)
-Return the sequence associated with this iterator.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gsi_remove (gimple_stmt_iterator *i, bool remove_eh_info)
-Remove the current stmt from the sequence. The iterator is
-updated to point to the next statement. When @code{REMOVE_EH_INFO} is
-true we remove the statement pointed to by iterator @code{I} from the @code{EH}
-tables. Otherwise we do not modify the @code{EH} tables. Generally,
-@code{REMOVE_EH_INFO} should be true when the statement is going to be
-removed from the @code{IL} and not reinserted elsewhere.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gsi_link_seq_before (gimple_stmt_iterator *i, gimple_seq seq, enum gsi_iterator_update mode)
-Links the sequence of statements @code{SEQ} before the statement pointed
-by iterator @code{I}. @code{MODE} indicates what to do with the iterator
-after insertion (see @code{enum gsi_iterator_update} above).
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gsi_link_before (gimple_stmt_iterator *i, gimple g, enum gsi_iterator_update mode)
-Links statement @code{G} before the statement pointed-to by iterator @code{I}.
-Updates iterator @code{I} according to @code{MODE}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gsi_link_seq_after (gimple_stmt_iterator *i, @
-gimple_seq seq, enum gsi_iterator_update mode)
-Links sequence @code{SEQ} after the statement pointed-to by iterator @code{I}.
-@code{MODE} is as in @code{gsi_insert_after}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gsi_link_after (gimple_stmt_iterator *i, @
-gimple g, enum gsi_iterator_update mode)
-Links statement @code{G} after the statement pointed-to by iterator @code{I}.
-@code{MODE} is as in @code{gsi_insert_after}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} gimple_seq gsi_split_seq_after (gimple_stmt_iterator i)
-Move all statements in the sequence after @code{I} to a new sequence.
-Return this new sequence.
-@end deftypefn
-
-@deftypefn {GIMPLE function} gimple_seq gsi_split_seq_before (gimple_stmt_iterator *i)
-Move all statements in the sequence before @code{I} to a new sequence.
-Return this new sequence.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gsi_replace (gimple_stmt_iterator *i, @
-gimple stmt, bool update_eh_info)
-Replace the statement pointed-to by @code{I} to @code{STMT}. If @code{UPDATE_EH_INFO}
-is true, the exception handling information of the original
-statement is moved to the new statement.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gsi_insert_before (gimple_stmt_iterator *i, @
-gimple stmt, enum gsi_iterator_update mode)
-Insert statement @code{STMT} before the statement pointed-to by iterator
-@code{I}, update @code{STMT}'s basic block and scan it for new operands. @code{MODE}
-specifies how to update iterator @code{I} after insertion (see enum
-@code{gsi_iterator_update}).
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gsi_insert_seq_before (gimple_stmt_iterator *i, @
-gimple_seq seq, enum gsi_iterator_update mode)
-Like @code{gsi_insert_before}, but for all the statements in @code{SEQ}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gsi_insert_after (gimple_stmt_iterator *i, @
-gimple stmt, enum gsi_iterator_update mode)
-Insert statement @code{STMT} after the statement pointed-to by iterator
-@code{I}, update @code{STMT}'s basic block and scan it for new operands. @code{MODE}
-specifies how to update iterator @code{I} after insertion (see enum
-@code{gsi_iterator_update}).
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gsi_insert_seq_after (gimple_stmt_iterator *i, @
-gimple_seq seq, enum gsi_iterator_update mode)
-Like @code{gsi_insert_after}, but for all the statements in @code{SEQ}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} gimple_stmt_iterator gsi_for_stmt (gimple stmt)
-Finds iterator for @code{STMT}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gsi_move_after (gimple_stmt_iterator *from, @
-gimple_stmt_iterator *to)
-Move the statement at @code{FROM} so it comes right after the statement
-at @code{TO}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gsi_move_before (gimple_stmt_iterator *from, @
-gimple_stmt_iterator *to)
-Move the statement at @code{FROM} so it comes right before the statement
-at @code{TO}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gsi_move_to_bb_end (gimple_stmt_iterator *from, @
-basic_block bb)
-Move the statement at @code{FROM} to the end of basic block @code{BB}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gsi_insert_on_edge (edge e, gimple stmt)
-Add @code{STMT} to the pending list of edge @code{E}. No actual insertion is
-made until a call to @code{gsi_commit_edge_inserts}() is made.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gsi_insert_seq_on_edge (edge e, gimple_seq seq)
-Add the sequence of statements in @code{SEQ} to the pending list of edge
-@code{E}. No actual insertion is made until a call to
-@code{gsi_commit_edge_inserts}() is made.
-@end deftypefn
-
-@deftypefn {GIMPLE function} basic_block gsi_insert_on_edge_immediate (edge e, gimple stmt)
-Similar to @code{gsi_insert_on_edge}+@code{gsi_commit_edge_inserts}. If a new
-block has to be created, it is returned.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gsi_commit_one_edge_insert (edge e, basic_block *new_bb)
-Commit insertions pending at edge @code{E}. If a new block is created,
-set @code{NEW_BB} to this block, otherwise set it to @code{NULL}.
-@end deftypefn
-
-@deftypefn {GIMPLE function} void gsi_commit_edge_inserts (void)
-This routine will commit all pending edge insertions, creating
-any new basic blocks which are necessary.
-@end deftypefn
-
-
-@node Adding a new GIMPLE statement code
-@section Adding a new GIMPLE statement code
-@cindex Adding a new GIMPLE statement code
-
-The first step in adding a new GIMPLE statement code, is
-modifying the file @code{gimple.def}, which contains all the GIMPLE
-codes. Then you must add a corresponding gimple subclass
-located in @code{gimple.h}. This in turn, will require you to add a
-corresponding @code{GTY} tag in @code{gsstruct.def}, and code to handle
-this tag in @code{gss_for_code} which is located in @code{gimple.cc}.
-
-In order for the garbage collector to know the size of the
-structure you created in @code{gimple.h}, you need to add a case to
-handle your new GIMPLE statement in @code{gimple_size} which is located
-in @code{gimple.cc}.
-
-You will probably want to create a function to build the new
-gimple statement in @code{gimple.cc}. The function should be called
-@code{gimple_build_@var{new-tuple-name}}, and should return the new tuple
-as a pointer to the appropriate gimple subclass.
-
-If your new statement requires accessors for any members or
-operands it may have, put simple inline accessors in
-@code{gimple.h} and any non-trivial accessors in @code{gimple.cc} with a
-corresponding prototype in @code{gimple.h}.
-
-You should add the new statement subclass to the class hierarchy diagram
-in @code{gimple.texi}.
-
-
-@node Statement and operand traversals
-@section Statement and operand traversals
-@cindex Statement and operand traversals
-
-There are two functions available for walking statements and
-sequences: @code{walk_gimple_stmt} and @code{walk_gimple_seq},
-accordingly, and a third function for walking the operands in a
-statement: @code{walk_gimple_op}.
-
-@deftypefn {GIMPLE function} tree walk_gimple_stmt (gimple_stmt_iterator *gsi, @
- walk_stmt_fn callback_stmt, walk_tree_fn callback_op, struct walk_stmt_info *wi)
-This function is used to walk the current statement in @code{GSI},
-optionally using traversal state stored in @code{WI}. If @code{WI} is @code{NULL}, no
-state is kept during the traversal.
-
-The callback @code{CALLBACK_STMT} is called. If @code{CALLBACK_STMT} returns
-true, it means that the callback function has handled all the
-operands of the statement and it is not necessary to walk its
-operands.
-
-If @code{CALLBACK_STMT} is @code{NULL} or it returns false, @code{CALLBACK_OP} is
-called on each operand of the statement via @code{walk_gimple_op}. If
-@code{walk_gimple_op} returns non-@code{NULL} for any operand, the remaining
-operands are not scanned.
-
-The return value is that returned by the last call to
-@code{walk_gimple_op}, or @code{NULL_TREE} if no @code{CALLBACK_OP} is specified.
-@end deftypefn
-
-
-@deftypefn {GIMPLE function} tree walk_gimple_op (gimple stmt, @
- walk_tree_fn callback_op, struct walk_stmt_info *wi)
-Use this function to walk the operands of statement @code{STMT}. Every
-operand is walked via @code{walk_tree} with optional state information
-in @code{WI}.
-
-@code{CALLBACK_OP} is called on each operand of @code{STMT} via @code{walk_tree}.
-Additional parameters to @code{walk_tree} must be stored in @code{WI}. For
-each operand @code{OP}, @code{walk_tree} is called as:
-
-@smallexample
-walk_tree (&@code{OP}, @code{CALLBACK_OP}, @code{WI}, @code{PSET})
-@end smallexample
-
-If @code{CALLBACK_OP} returns non-@code{NULL} for an operand, the remaining
-operands are not scanned. The return value is that returned by
-the last call to @code{walk_tree}, or @code{NULL_TREE} if no @code{CALLBACK_OP} is
-specified.
-@end deftypefn
-
-
-@deftypefn {GIMPLE function} tree walk_gimple_seq (gimple_seq seq, @
- walk_stmt_fn callback_stmt, walk_tree_fn callback_op, struct walk_stmt_info *wi)
-This function walks all the statements in the sequence @code{SEQ}
-calling @code{walk_gimple_stmt} on each one. @code{WI} is as in
-@code{walk_gimple_stmt}. If @code{walk_gimple_stmt} returns non-@code{NULL}, the walk
-is stopped and the value returned. Otherwise, all the statements
-are walked and @code{NULL_TREE} returned.
-@end deftypefn
+++ /dev/null
-@c Copyright (C) 2001 Free Software Foundation, Inc.
-@c This is part of the GCC manual.
-@c For copying conditions, see the file gcc.texi.
-
-@node GNU Project
-@unnumbered The GNU Project and GNU/Linux
-
-The GNU Project was launched in 1984 to develop a complete Unix-like
-operating system which is free software: the GNU system. (GNU is a
-recursive acronym for ``GNU's Not Unix''; it is pronounced
-``guh-NEW''@.) Variants of the GNU operating system, which use the
-kernel Linux, are now widely used; though these systems are often
-referred to as ``Linux'', they are more accurately called GNU/Linux
-systems.
-
-For more information, see:
-@smallexample
-@uref{https://www.gnu.org/}
-@uref{https://www.gnu.org/gnu/linux-and-gnu.html}
-@end smallexample
+++ /dev/null
-@c Copyright (C) 2002-2022 Free Software Foundation, Inc.
-@c This is part of the GCC manual.
-@c For copying conditions, see the file gcc.texi.
-
-@node Type Information
-@chapter Memory Management and Type Information
-@cindex GGC
-@findex GTY
-
-GCC uses some fairly sophisticated memory management techniques, which
-involve determining information about GCC's data structures from GCC's
-source code and using this information to perform garbage collection and
-implement precompiled headers.
-
-A full C++ parser would be too complicated for this task, so a limited
-subset of C++ is interpreted and special markers are used to determine
-what parts of the source to look at. All @code{struct}, @code{union}
-and @code{template} structure declarations that define data structures
-that are allocated under control of the garbage collector must be
-marked. All global variables that hold pointers to garbage-collected
-memory must also be marked. Finally, all global variables that need
-to be saved and restored by a precompiled header must be marked. (The
-precompiled header mechanism can only save static variables if they're
-scalar. Complex data structures must be allocated in garbage-collected
-memory to be saved in a precompiled header.)
-
-The full format of a marker is
-@smallexample
-GTY (([@var{option}] [(@var{param})], [@var{option}] [(@var{param})] @dots{}))
-@end smallexample
-@noindent
-but in most cases no options are needed. The outer double parentheses
-are still necessary, though: @code{GTY(())}. Markers can appear:
-
-@itemize @bullet
-@item
-In a structure definition, before the open brace;
-@item
-In a global variable declaration, after the keyword @code{static} or
-@code{extern}; and
-@item
-In a structure field definition, before the name of the field.
-@end itemize
-
-Here are some examples of marking simple data structures and globals.
-
-@smallexample
-struct GTY(()) @var{tag}
-@{
- @var{fields}@dots{}
-@};
-
-typedef struct GTY(()) @var{tag}
-@{
- @var{fields}@dots{}
-@} *@var{typename};
-
-static GTY(()) struct @var{tag} *@var{list}; /* @r{points to GC memory} */
-static GTY(()) int @var{counter}; /* @r{save counter in a PCH} */
-@end smallexample
-
-The parser understands simple typedefs such as
-@code{typedef struct @var{tag} *@var{name};} and
-@code{typedef int @var{name};}.
-These don't need to be marked.
-
-However, in combination with GTY, avoid using typedefs such as
-@code{typedef int_hash<@dots{}> @var{name};}
-for these generate infinite-recursion code.
-See @uref{https://gcc.gnu.org/PR103157,PR103157}.
-Instead, you may use
-@code{struct @var{name} : int_hash<@dots{}> @{@};},
-for example.
-
-Since @code{gengtype}'s understanding of C++ is limited, there are
-several constructs and declarations that are not supported inside
-classes/structures marked for automatic GC code generation. The
-following C++ constructs produce a @code{gengtype} error on
-structures/classes marked for automatic GC code generation:
-
-@itemize @bullet
-@item
-Type definitions inside classes/structures are not supported.
-@item
-Enumerations inside classes/structures are not supported.
-@end itemize
-
-If you have a class or structure using any of the above constructs,
-you need to mark that class as @code{GTY ((user))} and provide your
-own marking routines (see section @ref{User GC} for details).
-
-It is always valid to include function definitions inside classes.
-Those are always ignored by @code{gengtype}, as it only cares about
-data members.
-
-@menu
-* GTY Options:: What goes inside a @code{GTY(())}.
-* Inheritance and GTY:: Adding GTY to a class hierarchy.
-* User GC:: Adding user-provided GC marking routines.
-* GGC Roots:: Making global variables GGC roots.
-* Files:: How the generated files work.
-* Invoking the garbage collector:: How to invoke the garbage collector.
-* Troubleshooting:: When something does not work as expected.
-@end menu
-
-@node GTY Options
-@section The Inside of a @code{GTY(())}
-
-Sometimes the C code is not enough to fully describe the type
-structure. Extra information can be provided with @code{GTY} options
-and additional markers. Some options take a parameter, which may be
-either a string or a type name, depending on the parameter. If an
-option takes no parameter, it is acceptable either to omit the
-parameter entirely, or to provide an empty string as a parameter. For
-example, @code{@w{GTY ((skip))}} and @code{@w{GTY ((skip ("")))}} are
-equivalent.
-
-When the parameter is a string, often it is a fragment of C code. Four
-special escapes may be used in these strings, to refer to pieces of
-the data structure being marked:
-
-@cindex % in GTY option
-@table @code
-@item %h
-The current structure.
-@item %1
-The structure that immediately contains the current structure.
-@item %0
-The outermost structure that contains the current structure.
-@item %a
-A partial expression of the form @code{[i1][i2]@dots{}} that indexes
-the array item currently being marked.
-@end table
-
-For instance, suppose that you have a structure of the form
-@smallexample
-struct A @{
- @dots{}
-@};
-struct B @{
- struct A foo[12];
-@};
-@end smallexample
-@noindent
-and @code{b} is a variable of type @code{struct B}. When marking
-@samp{b.foo[11]}, @code{%h} would expand to @samp{b.foo[11]},
-@code{%0} and @code{%1} would both expand to @samp{b}, and @code{%a}
-would expand to @samp{[11]}.
-
-As in ordinary C, adjacent strings will be concatenated; this is
-helpful when you have a complicated expression.
-@smallexample
-@group
-GTY ((chain_next ("TREE_CODE (&%h.generic) == INTEGER_TYPE"
- " ? TYPE_NEXT_VARIANT (&%h.generic)"
- " : TREE_CHAIN (&%h.generic)")))
-@end group
-@end smallexample
-
-The available options are:
-
-@table @code
-@findex length
-@item length ("@var{expression}")
-
-There are two places the type machinery will need to be explicitly told
-the length of an array of non-atomic objects. The first case is when a
-structure ends in a variable-length array, like this:
-@smallexample
-struct GTY(()) rtvec_def @{
- int num_elem; /* @r{number of elements} */
- rtx GTY ((length ("%h.num_elem"))) elem[1];
-@};
-@end smallexample
-
-In this case, the @code{length} option is used to override the specified
-array length (which should usually be @code{1}). The parameter of the
-option is a fragment of C code that calculates the length.
-
-The second case is when a structure or a global variable contains a
-pointer to an array, like this:
-@smallexample
-struct gimple_omp_for_iter * GTY((length ("%h.collapse"))) iter;
-@end smallexample
-In this case, @code{iter} has been allocated by writing something like
-@smallexample
- x->iter = ggc_alloc_cleared_vec_gimple_omp_for_iter (collapse);
-@end smallexample
-and the @code{collapse} provides the length of the field.
-
-This second use of @code{length} also works on global variables, like:
-@verbatim
-static GTY((length("reg_known_value_size"))) rtx *reg_known_value;
-@end verbatim
-
-Note that the @code{length} option is only meant for use with arrays of
-non-atomic objects, that is, objects that contain pointers pointing to
-other GTY-managed objects. For other GC-allocated arrays and strings
-you should use @code{atomic} or @code{string_length}.
-
-@findex string_length
-@item string_length ("@var{expression}")
-
-In order to simplify production of PCH, a structure member that is a plain
-array of bytes (an optionally @code{const} and/or @code{unsigned} @code{char
-*}) is treated specially by the infrastructure. Even if such an array has not
-been allocated in GC-controlled memory, it will still be written properly into
-a PCH. The machinery responsible for this needs to know the length of the
-data; by default, the length is determined by calling @code{strlen} on the
-pointer. The @code{string_length} option specifies an alternate way to
-determine the length, such as by inspecting another struct member:
-
-@smallexample
-struct GTY(()) non_terminated_string @{
- size_t sz;
- const char * GTY((string_length ("%h.sz"))) data;
-@};
-@end smallexample
-
-@findex skip
-@item skip
-
-If @code{skip} is applied to a field, the type machinery will ignore it.
-This is somewhat dangerous; the only safe use is in a union when one
-field really isn't ever used.
-
-@findex callback
-@item callback
-
-@code{callback} should be applied to fields with pointer to function type
-and causes the field to be ignored similarly to @code{skip}, except when
-writing PCH and the field is non-NULL it will remember the field's address
-for relocation purposes if the process writing PCH has different load base
-from a process reading PCH.
-
-@findex for_user
-@item for_user
-
-Use this to mark types that need to be marked by user gc routines, but are not
-refered to in a template argument. So if you have some user gc type T1 and a
-non user gc type T2 you can give T2 the for_user option so that the marking
-functions for T1 can call non mangled functions to mark T2.
-
-@findex desc
-@findex tag
-@findex default
-@item desc ("@var{expression}")
-@itemx tag ("@var{constant}")
-@itemx default
-
-The type machinery needs to be told which field of a @code{union} is
-currently active. This is done by giving each field a constant
-@code{tag} value, and then specifying a discriminator using @code{desc}.
-The value of the expression given by @code{desc} is compared against
-each @code{tag} value, each of which should be different. If no
-@code{tag} is matched, the field marked with @code{default} is used if
-there is one, otherwise no field in the union will be marked.
-
-In the @code{desc} option, the ``current structure'' is the union that
-it discriminates. Use @code{%1} to mean the structure containing it.
-There are no escapes available to the @code{tag} option, since it is a
-constant.
-
-For example,
-@smallexample
-struct GTY(()) tree_binding
-@{
- struct tree_common common;
- union tree_binding_u @{
- tree GTY ((tag ("0"))) scope;
- struct cp_binding_level * GTY ((tag ("1"))) level;
- @} GTY ((desc ("BINDING_HAS_LEVEL_P ((tree)&%0)"))) xscope;
- tree value;
-@};
-@end smallexample
-
-In this example, the value of BINDING_HAS_LEVEL_P when applied to a
-@code{struct tree_binding *} is presumed to be 0 or 1. If 1, the type
-mechanism will treat the field @code{level} as being present and if 0,
-will treat the field @code{scope} as being present.
-
-The @code{desc} and @code{tag} options can also be used for inheritance
-to denote which subclass an instance is. See @ref{Inheritance and GTY}
-for more information.
-
-@findex cache
-@item cache
-
-When the @code{cache} option is applied to a global variable gt_cleare_cache is
-called on that variable between the mark and sweep phases of garbage
-collection. The gt_clear_cache function is free to mark blocks as used, or to
-clear pointers in the variable.
-
-@findex deletable
-@item deletable
-
-@code{deletable}, when applied to a global variable, indicates that when
-garbage collection runs, there's no need to mark anything pointed to
-by this variable, it can just be set to @code{NULL} instead. This is used
-to keep a list of free structures around for re-use.
-
-@findex maybe_undef
-@item maybe_undef
-
-When applied to a field, @code{maybe_undef} indicates that it's OK if
-the structure that this fields points to is never defined, so long as
-this field is always @code{NULL}. This is used to avoid requiring
-backends to define certain optional structures. It doesn't work with
-language frontends.
-
-@findex nested_ptr
-@item nested_ptr (@var{type}, "@var{to expression}", "@var{from expression}")
-
-The type machinery expects all pointers to point to the start of an
-object. Sometimes for abstraction purposes it's convenient to have
-a pointer which points inside an object. So long as it's possible to
-convert the original object to and from the pointer, such pointers
-can still be used. @var{type} is the type of the original object,
-the @var{to expression} returns the pointer given the original object,
-and the @var{from expression} returns the original object given
-the pointer. The pointer will be available using the @code{%h}
-escape.
-
-@findex chain_next
-@findex chain_prev
-@findex chain_circular
-@item chain_next ("@var{expression}")
-@itemx chain_prev ("@var{expression}")
-@itemx chain_circular ("@var{expression}")
-
-It's helpful for the type machinery to know if objects are often
-chained together in long lists; this lets it generate code that uses
-less stack space by iterating along the list instead of recursing down
-it. @code{chain_next} is an expression for the next item in the list,
-@code{chain_prev} is an expression for the previous item. For singly
-linked lists, use only @code{chain_next}; for doubly linked lists, use
-both. The machinery requires that taking the next item of the
-previous item gives the original item. @code{chain_circular} is similar
-to @code{chain_next}, but can be used for circular single linked lists.
-
-@findex reorder
-@item reorder ("@var{function name}")
-
-Some data structures depend on the relative ordering of pointers. If
-the precompiled header machinery needs to change that ordering, it
-will call the function referenced by the @code{reorder} option, before
-changing the pointers in the object that's pointed to by the field the
-option applies to. The function must take four arguments, with the
-signature @samp{@w{void *, void *, gt_pointer_operator, void *}}.
-The first parameter is a pointer to the structure that contains the
-object being updated, or the object itself if there is no containing
-structure. The second parameter is a cookie that should be ignored.
-The third parameter is a routine that, given a pointer, will update it
-to its correct new value. The fourth parameter is a cookie that must
-be passed to the second parameter.
-
-PCH cannot handle data structures that depend on the absolute values
-of pointers. @code{reorder} functions can be expensive. When
-possible, it is better to depend on properties of the data, like an ID
-number or the hash of a string instead.
-
-@findex atomic
-@item atomic
-
-The @code{atomic} option can only be used with pointers. It informs
-the GC machinery that the memory that the pointer points to does not
-contain any pointers, and hence it should be treated by the GC and PCH
-machinery as an ``atomic'' block of memory that does not need to be
-examined when scanning memory for pointers. In particular, the
-machinery will not scan that memory for pointers to mark them as
-reachable (when marking pointers for GC) or to relocate them (when
-writing a PCH file).
-
-The @code{atomic} option differs from the @code{skip} option.
-@code{atomic} keeps the memory under Garbage Collection, but makes the
-GC ignore the contents of the memory. @code{skip} is more drastic in
-that it causes the pointer and the memory to be completely ignored by
-the Garbage Collector. So, memory marked as @code{atomic} is
-automatically freed when no longer reachable, while memory marked as
-@code{skip} is not.
-
-The @code{atomic} option must be used with great care, because all
-sorts of problem can occur if used incorrectly, that is, if the memory
-the pointer points to does actually contain a pointer.
-
-Here is an example of how to use it:
-@smallexample
-struct GTY(()) my_struct @{
- int number_of_elements;
- unsigned int * GTY ((atomic)) elements;
-@};
-@end smallexample
-In this case, @code{elements} is a pointer under GC, and the memory it
-points to needs to be allocated using the Garbage Collector, and will
-be freed automatically by the Garbage Collector when it is no longer
-referenced. But the memory that the pointer points to is an array of
-@code{unsigned int} elements, and the GC must not try to scan it to
-find pointers to mark or relocate, which is why it is marked with the
-@code{atomic} option.
-
-Note that, currently, global variables cannot be marked with
-@code{atomic}; only fields of a struct can. This is a known
-limitation. It would be useful to be able to mark global pointers
-with @code{atomic} to make the PCH machinery aware of them so that
-they are saved and restored correctly to PCH files.
-
-@findex special
-@item special ("@var{name}")
-
-The @code{special} option is used to mark types that have to be dealt
-with by special case machinery. The parameter is the name of the
-special case. See @file{gengtype.cc} for further details. Avoid
-adding new special cases unless there is no other alternative.
-
-@findex user
-@item user
-
-The @code{user} option indicates that the code to mark structure
-fields is completely handled by user-provided routines. See section
-@ref{User GC} for details on what functions need to be provided.
-@end table
-
-@node Inheritance and GTY
-@section Support for inheritance
-gengtype has some support for simple class hierarchies. You can use
-this to have gengtype autogenerate marking routines, provided:
-
-@itemize @bullet
-@item
-There must be a concrete base class, with a discriminator expression
-that can be used to identify which subclass an instance is.
-@item
-Only single inheritance is used.
-@item
-None of the classes within the hierarchy are templates.
-@end itemize
-
-If your class hierarchy does not fit in this pattern, you must use
-@ref{User GC} instead.
-
-The base class and its discriminator must be identified using the ``desc''
-option. Each concrete subclass must use the ``tag'' option to identify
-which value of the discriminator it corresponds to.
-
-Every class in the hierarchy must have a @code{GTY(())} marker, as
-gengtype will only attempt to parse classes that have such a marker
-@footnote{Classes lacking such a marker will not be identified as being
-part of the hierarchy, and so the marking routines will not handle them,
-leading to a assertion failure within the marking routines due to an
-unknown tag value (assuming that assertions are enabled).}.
-
-@smallexample
-class GTY((desc("%h.kind"), tag("0"))) example_base
-@{
-public:
- int kind;
- tree a;
-@};
-
-class GTY((tag("1"))) some_subclass : public example_base
-@{
-public:
- tree b;
-@};
-
-class GTY((tag("2"))) some_other_subclass : public example_base
-@{
-public:
- tree c;
-@};
-@end smallexample
-
-The generated marking routines for the above will contain a ``switch''
-on ``kind'', visiting all appropriate fields. For example, if kind is
-2, it will cast to ``some_other_subclass'' and visit fields a, b, and c.
-
-@node User GC
-@section Support for user-provided GC marking routines
-@cindex user gc
-The garbage collector supports types for which no automatic marking
-code is generated. For these types, the user is required to provide
-three functions: one to act as a marker for garbage collection, and
-two functions to act as marker and pointer walker for pre-compiled
-headers.
-
-Given a structure @code{struct GTY((user)) my_struct}, the following functions
-should be defined to mark @code{my_struct}:
-
-@smallexample
-void gt_ggc_mx (my_struct *p)
-@{
- /* This marks field 'fld'. */
- gt_ggc_mx (p->fld);
-@}
-
-void gt_pch_nx (my_struct *p)
-@{
- /* This marks field 'fld'. */
- gt_pch_nx (tp->fld);
-@}
-
-void gt_pch_nx (my_struct *p, gt_pointer_operator op, void *cookie)
-@{
- /* For every field 'fld', call the given pointer operator. */
- op (&(tp->fld), NULL, cookie);
-@}
-@end smallexample
-
-In general, each marker @code{M} should call @code{M} for every
-pointer field in the structure. Fields that are not allocated in GC
-or are not pointers must be ignored.
-
-For embedded lists (e.g., structures with a @code{next} or @code{prev}
-pointer), the marker must follow the chain and mark every element in
-it.
-
-Note that the rules for the pointer walker @code{gt_pch_nx (my_struct
-*, gt_pointer_operator, void *)} are slightly different. In this
-case, the operation @code{op} must be applied to the @emph{address} of
-every pointer field.
-
-@subsection User-provided marking routines for template types
-When a template type @code{TP} is marked with @code{GTY}, all
-instances of that type are considered user-provided types. This means
-that the individual instances of @code{TP} do not need to be marked
-with @code{GTY}. The user needs to provide template functions to mark
-all the fields of the type.
-
-The following code snippets represent all the functions that need to
-be provided. Note that type @code{TP} may reference to more than one
-type. In these snippets, there is only one type @code{T}, but there
-could be more.
-
-@smallexample
-template<typename T>
-void gt_ggc_mx (TP<T> *tp)
-@{
- extern void gt_ggc_mx (T&);
-
- /* This marks field 'fld' of type 'T'. */
- gt_ggc_mx (tp->fld);
-@}
-
-template<typename T>
-void gt_pch_nx (TP<T> *tp)
-@{
- extern void gt_pch_nx (T&);
-
- /* This marks field 'fld' of type 'T'. */
- gt_pch_nx (tp->fld);
-@}
-
-template<typename T>
-void gt_pch_nx (TP<T *> *tp, gt_pointer_operator op, void *cookie)
-@{
- /* For every field 'fld' of 'tp' with type 'T *', call the given
- pointer operator. */
- op (&(tp->fld), NULL, cookie);
-@}
-
-template<typename T>
-void gt_pch_nx (TP<T> *tp, gt_pointer_operator, void *cookie)
-@{
- extern void gt_pch_nx (T *, gt_pointer_operator, void *);
-
- /* For every field 'fld' of 'tp' with type 'T', call the pointer
- walker for all the fields of T. */
- gt_pch_nx (&(tp->fld), op, cookie);
-@}
-@end smallexample
-
-Support for user-defined types is currently limited. The following
-restrictions apply:
-
-@enumerate
-@item Type @code{TP} and all the argument types @code{T} must be
-marked with @code{GTY}.
-
-@item Type @code{TP} can only have type names in its argument list.
-
-@item The pointer walker functions are different for @code{TP<T>} and
-@code{TP<T *>}. In the case of @code{TP<T>}, references to
-@code{T} must be handled by calling @code{gt_pch_nx} (which
-will, in turn, walk all the pointers inside fields of @code{T}).
-In the case of @code{TP<T *>}, references to @code{T *} must be
-handled by calling the @code{op} function on the address of the
-pointer (see the code snippets above).
-@end enumerate
-
-@node GGC Roots
-@section Marking Roots for the Garbage Collector
-@cindex roots, marking
-@cindex marking roots
-
-In addition to keeping track of types, the type machinery also locates
-the global variables (@dfn{roots}) that the garbage collector starts
-at. Roots must be declared using one of the following syntaxes:
-
-@itemize @bullet
-@item
-@code{extern GTY(([@var{options}])) @var{type} @var{name};}
-@item
-@code{static GTY(([@var{options}])) @var{type} @var{name};}
-@end itemize
-@noindent
-The syntax
-@itemize @bullet
-@item
-@code{GTY(([@var{options}])) @var{type} @var{name};}
-@end itemize
-@noindent
-is @emph{not} accepted. There should be an @code{extern} declaration
-of such a variable in a header somewhere---mark that, not the
-definition. Or, if the variable is only used in one file, make it
-@code{static}.
-
-@node Files
-@section Source Files Containing Type Information
-@cindex generated files
-@cindex files, generated
-
-Whenever you add @code{GTY} markers to a source file that previously
-had none, or create a new source file containing @code{GTY} markers,
-there are three things you need to do:
-
-@enumerate
-@item
-You need to add the file to the list of source files the type
-machinery scans. There are four cases:
-
-@enumerate a
-@item
-For a back-end file, this is usually done
-automatically; if not, you should add it to @code{target_gtfiles} in
-the appropriate port's entries in @file{config.gcc}.
-
-@item
-For files shared by all front ends, add the filename to the
-@code{GTFILES} variable in @file{Makefile.in}.
-
-@item
-For files that are part of one front end, add the filename to the
-@code{gtfiles} variable defined in the appropriate
-@file{config-lang.in}.
-Headers should appear before non-headers in this list.
-
-@item
-For files that are part of some but not all front ends, add the
-filename to the @code{gtfiles} variable of @emph{all} the front ends
-that use it.
-@end enumerate
-
-@item
-If the file was a header file, you'll need to check that it's included
-in the right place to be visible to the generated files. For a back-end
-header file, this should be done automatically. For a front-end header
-file, it needs to be included by the same file that includes
-@file{gtype-@var{lang}.h}. For other header files, it needs to be
-included in @file{gtype-desc.cc}, which is a generated file, so add it to
-@code{ifiles} in @code{open_base_file} in @file{gengtype.cc}.
-
-For source files that aren't header files, the machinery will generate a
-header file that should be included in the source file you just changed.
-The file will be called @file{gt-@var{path}.h} where @var{path} is the
-pathname relative to the @file{gcc} directory with slashes replaced by
-@verb{|-|}, so for example the header file to be included in
-@file{cp/parser.cc} is called @file{gt-cp-parser.h}. The
-generated header file should be included after everything else in the
-source file.
-
-@end enumerate
-
-For language frontends, there is another file that needs to be included
-somewhere. It will be called @file{gtype-@var{lang}.h}, where
-@var{lang} is the name of the subdirectory the language is contained in.
-
-Plugins can add additional root tables. Run the @code{gengtype}
-utility in plugin mode as @code{gengtype -P pluginout.h @var{source-dir}
-@var{file-list} @var{plugin*.c}} with your plugin files
-@var{plugin*.c} using @code{GTY} to generate the @var{pluginout.h} file.
-The GCC build tree is needed to be present in that mode.
-
-
-@node Invoking the garbage collector
-@section How to invoke the garbage collector
-@cindex garbage collector, invocation
-@findex ggc_collect
-
-The GCC garbage collector GGC is only invoked explicitly. In contrast
-with many other garbage collectors, it is not implicitly invoked by
-allocation routines when a lot of memory has been consumed. So the
-only way to have GGC reclaim storage is to call the @code{ggc_collect}
-function explicitly.
-With @var{mode} @code{GGC_COLLECT_FORCE} or otherwise (default
-@code{GGC_COLLECT_HEURISTIC}) when the internal heuristic decides to
-collect, this call is potentially an expensive operation, as it may
-have to scan the entire heap. Beware that local variables (on the GCC
-call stack) are not followed by such an invocation (as many other
-garbage collectors do): you should reference all your data from static
-or external @code{GTY}-ed variables, and it is advised to call
-@code{ggc_collect} with a shallow call stack. The GGC is an exact mark
-and sweep garbage collector (so it does not scan the call stack for
-pointers). In practice GCC passes don't often call @code{ggc_collect}
-themselves, because it is called by the pass manager between passes.
-
-At the time of the @code{ggc_collect} call all pointers in the GC-marked
-structures must be valid or @code{NULL}. In practice this means that
-there should not be uninitialized pointer fields in the structures even
-if your code never reads or writes those fields at a particular
-instance. One way to ensure this is to use cleared versions of
-allocators unless all the fields are initialized manually immediately
-after allocation.
-
-@node Troubleshooting
-@section Troubleshooting the garbage collector
-@cindex garbage collector, troubleshooting
-
-With the current garbage collector implementation, most issues should
-show up as GCC compilation errors. Some of the most commonly
-encountered issues are described below.
-
-@itemize @bullet
-@item Gengtype does not produce allocators for a @code{GTY}-marked type.
-Gengtype checks if there is at least one possible path from GC roots to
-at least one instance of each type before outputting allocators. If
-there is no such path, the @code{GTY} markers will be ignored and no
-allocators will be output. Solve this by making sure that there exists
-at least one such path. If creating it is unfeasible or raises a ``code
-smell'', consider if you really must use GC for allocating such type.
-
-@item Link-time errors about undefined @code{gt_ggc_r_foo_bar} and
-similarly-named symbols. Check if your @file{foo_bar} source file has
-@code{#include "gt-foo_bar.h"} as its very last line.
-
-@end itemize
+++ /dev/null
-@c Copyright (C) 1988-2022 Free Software Foundation, Inc.
-@c This is part of the GCC manual.
-@c For copying conditions, see the file gcc.texi.
-
-@node Header Dirs
-@chapter Standard Header File Directories
-
-@code{GCC_INCLUDE_DIR} means the same thing for native and cross. It is
-where GCC stores its private include files, and also where GCC
-stores the fixed include files. A cross compiled GCC runs
-@code{fixincludes} on the header files in @file{$(tooldir)/include}.
-(If the cross compilation header files need to be fixed, they must be
-installed before GCC is built. If the cross compilation header files
-are already suitable for GCC, nothing special need be done).
-
-@code{GPLUSPLUS_INCLUDE_DIR} means the same thing for native and cross. It
-is where @command{g++} looks first for header files. The C++ library
-installs only target independent header files in that directory.
-
-@code{LOCAL_INCLUDE_DIR} is used only by native compilers. GCC
-doesn't install anything there. It is normally
-@file{/usr/local/include}. This is where local additions to a packaged
-system should place header files.
-
-@code{CROSS_INCLUDE_DIR} is used only by cross compilers. GCC
-doesn't install anything there.
-
-@code{TOOL_INCLUDE_DIR} is used for both native and cross compilers. It
-is the place for other packages to install header files that GCC will
-use. For a cross-compiler, this is the equivalent of
-@file{/usr/include}. When you build a cross-compiler,
-@code{fixincludes} processes any header files in this directory.
+++ /dev/null
-@c Copyright (C) 1988-2022 Free Software Foundation, Inc.
-@c This is part of the GCC manual.
-@c For copying conditions, see the file gccint.texi.
-
-@node Host Config
-@chapter Host Configuration
-@cindex host configuration
-
-Most details about the machine and system on which the compiler is
-actually running are detected by the @command{configure} script. Some
-things are impossible for @command{configure} to detect; these are
-described in two ways, either by macros defined in a file named
-@file{xm-@var{machine}.h} or by hook functions in the file specified
-by the @var{out_host_hook_obj} variable in @file{config.gcc}. (The
-intention is that very few hosts will need a header file but nearly
-every fully supported host will need to override some hooks.)
-
-If you need to define only a few macros, and they have simple
-definitions, consider using the @code{xm_defines} variable in your
-@file{config.gcc} entry instead of creating a host configuration
-header. @xref{System Config}.
-
-@menu
-* Host Common:: Things every host probably needs implemented.
-* Filesystem:: Your host cannot have the letter `a' in filenames?
-* Host Misc:: Rare configuration options for hosts.
-@end menu
-
-@node Host Common
-@section Host Common
-@cindex host hooks
-@cindex host functions
-
-Some things are just not portable, even between similar operating systems,
-and are too difficult for autoconf to detect. They get implemented using
-hook functions in the file specified by the @var{host_hook_obj}
-variable in @file{config.gcc}.
-
-@deftypefn {Host Hook} void HOST_HOOKS_EXTRA_SIGNALS (void)
-This host hook is used to set up handling for extra signals. The most
-common thing to do in this hook is to detect stack overflow.
-@end deftypefn
-
-@deftypefn {Host Hook} {void *} HOST_HOOKS_GT_PCH_GET_ADDRESS (size_t @
- @var{size}, int @var{fd})
-This host hook returns the address of some space that is likely to be
-free in some subsequent invocation of the compiler. We intend to load
-the PCH data at this address such that the data need not be relocated.
-The area should be able to hold @var{size} bytes. If the host uses
-@code{mmap}, @var{fd} is an open file descriptor that can be used for
-probing.
-@end deftypefn
-
-@deftypefn {Host Hook} int HOST_HOOKS_GT_PCH_USE_ADDRESS (void * @var{address}, @
- size_t @var{size}, int @var{fd}, size_t @var{offset})
-This host hook is called when a PCH file is about to be loaded.
-We want to load @var{size} bytes from @var{fd} at @var{offset}
-into memory at @var{address}. The given address will be the result of
-a previous invocation of @code{HOST_HOOKS_GT_PCH_GET_ADDRESS}.
-Return @minus{}1 if we couldn't allocate @var{size} bytes at @var{address}.
-Return 0 if the memory is allocated but the data is not loaded. Return 1
-if the hook has performed everything.
-
-If the implementation uses reserved address space, free any reserved
-space beyond @var{size}, regardless of the return value. If no PCH will
-be loaded, this hook may be called with @var{size} zero, in which case
-all reserved address space should be freed.
-
-Do not try to handle values of @var{address} that could not have been
-returned by this executable; just return @minus{}1. Such values usually
-indicate an out-of-date PCH file (built by some other GCC executable),
-and such a PCH file won't work.
-@end deftypefn
-
-@deftypefn {Host Hook} size_t HOST_HOOKS_GT_PCH_ALLOC_GRANULARITY (void);
-This host hook returns the alignment required for allocating virtual
-memory. Usually this is the same as getpagesize, but on some hosts the
-alignment for reserving memory differs from the pagesize for committing
-memory.
-@end deftypefn
-
-@node Filesystem
-@section Host Filesystem
-@cindex configuration file
-@cindex @file{xm-@var{machine}.h}
-
-GCC needs to know a number of things about the semantics of the host
-machine's filesystem. Filesystems with Unix and MS-DOS semantics are
-automatically detected. For other systems, you can define the
-following macros in @file{xm-@var{machine}.h}.
-
-@ftable @code
-@item HAVE_DOS_BASED_FILE_SYSTEM
-This macro is automatically defined by @file{system.h} if the host
-file system obeys the semantics defined by MS-DOS instead of Unix.
-DOS file systems are case insensitive, file specifications may begin
-with a drive letter, and both forward slash and backslash (@samp{/}
-and @samp{\}) are directory separators.
-
-@item DIR_SEPARATOR
-@itemx DIR_SEPARATOR_2
-If defined, these macros expand to character constants specifying
-separators for directory names within a file specification.
-@file{system.h} will automatically give them appropriate values on
-Unix and MS-DOS file systems. If your file system is neither of
-these, define one or both appropriately in @file{xm-@var{machine}.h}.
-
-However, operating systems like VMS, where constructing a pathname is
-more complicated than just stringing together directory names
-separated by a special character, should not define either of these
-macros.
-
-@item PATH_SEPARATOR
-If defined, this macro should expand to a character constant
-specifying the separator for elements of search paths. The default
-value is a colon (@samp{:}). DOS-based systems usually, but not
-always, use semicolon (@samp{;}).
-
-@item VMS
-Define this macro if the host system is VMS@.
-
-@item HOST_OBJECT_SUFFIX
-Define this macro to be a C string representing the suffix for object
-files on your host machine. If you do not define this macro, GCC will
-use @samp{.o} as the suffix for object files.
-
-@item HOST_EXECUTABLE_SUFFIX
-Define this macro to be a C string representing the suffix for
-executable files on your host machine. If you do not define this macro,
-GCC will use the null string as the suffix for executable files.
-
-@item HOST_BIT_BUCKET
-A pathname defined by the host operating system, which can be opened as
-a file and written to, but all the information written is discarded.
-This is commonly known as a @dfn{bit bucket} or @dfn{null device}. If
-you do not define this macro, GCC will use @samp{/dev/null} as the bit
-bucket. If the host does not support a bit bucket, define this macro to
-an invalid filename.
-
-@item UPDATE_PATH_HOST_CANONICALIZE (@var{path})
-If defined, a C statement (sans semicolon) that performs host-dependent
-canonicalization when a path used in a compilation driver or
-preprocessor is canonicalized. @var{path} is a malloc-ed path to be
-canonicalized. If the C statement does canonicalize @var{path} into a
-different buffer, the old path should be freed and the new buffer should
-have been allocated with malloc.
-
-@item DUMPFILE_FORMAT
-Define this macro to be a C string representing the format to use for
-constructing the index part of debugging dump file names. The resultant
-string must fit in fifteen bytes. The full filename will be the
-concatenation of: the prefix of the assembler file name, the string
-resulting from applying this format to an index number, and a string
-unique to each dump file kind, e.g.@: @samp{rtl}.
-
-If you do not define this macro, GCC will use @samp{.%02d.}. You should
-define this macro if using the default will create an invalid file name.
-
-@item DELETE_IF_ORDINARY
-Define this macro to be a C statement (sans semicolon) that performs
-host-dependent removal of ordinary temp files in the compilation driver.
-
-If you do not define this macro, GCC will use the default version. You
-should define this macro if the default version does not reliably remove
-the temp file as, for example, on VMS which allows multiple versions
-of a file.
-
-@item HOST_LACKS_INODE_NUMBERS
-Define this macro if the host filesystem does not report meaningful inode
-numbers in struct stat.
-@end ftable
-
-@node Host Misc
-@section Host Misc
-@cindex configuration file
-@cindex @file{xm-@var{machine}.h}
-
-@ftable @code
-@item FATAL_EXIT_CODE
-A C expression for the status code to be returned when the compiler
-exits after serious errors. The default is the system-provided macro
-@samp{EXIT_FAILURE}, or @samp{1} if the system doesn't define that
-macro. Define this macro only if these defaults are incorrect.
-
-@item SUCCESS_EXIT_CODE
-A C expression for the status code to be returned when the compiler
-exits without serious errors. (Warnings are not serious errors.) The
-default is the system-provided macro @samp{EXIT_SUCCESS}, or @samp{0} if
-the system doesn't define that macro. Define this macro only if these
-defaults are incorrect.
-
-@item USE_C_ALLOCA
-Define this macro if GCC should use the C implementation of @code{alloca}
-provided by @file{libiberty.a}. This only affects how some parts of the
-compiler itself allocate memory. It does not change code generation.
-
-When GCC is built with a compiler other than itself, the C @code{alloca}
-is always used. This is because most other implementations have serious
-bugs. You should define this macro only on a system where no
-stack-based @code{alloca} can possibly work. For instance, if a system
-has a small limit on the size of the stack, GCC's builtin @code{alloca}
-will not work reliably.
-
-@item COLLECT2_HOST_INITIALIZATION
-If defined, a C statement (sans semicolon) that performs host-dependent
-initialization when @code{collect2} is being initialized.
-
-@item GCC_DRIVER_HOST_INITIALIZATION
-If defined, a C statement (sans semicolon) that performs host-dependent
-initialization when a compilation driver is being initialized.
-
-@item HOST_LONG_LONG_FORMAT
-If defined, the string used to indicate an argument of type @code{long
-long} to functions like @code{printf}. The default value is
-@code{"ll"}.
-
-@item HOST_LONG_FORMAT
-If defined, the string used to indicate an argument of type @code{long}
-to functions like @code{printf}. The default value is @code{"l"}.
-
-@item HOST_PTR_PRINTF
-If defined, the string used to indicate an argument of type @code{void *}
-to functions like @code{printf}. The default value is @code{"%p"}.
-@end ftable
-
-In addition, if @command{configure} generates an incorrect definition of
-any of the macros in @file{auto-host.h}, you can override that
-definition in a host configuration header. If you need to do this,
-first see if it is possible to fix @command{configure}.
+++ /dev/null
-@c Copyright (C) 2001-2022 Free Software Foundation, Inc.
-@c This is part of the GCC manual.
-@c For copying conditions, see the file gcc.texi.
-
-@node C Implementation
-@chapter C Implementation-Defined Behavior
-@cindex implementation-defined behavior, C language
-
-A conforming implementation of ISO C is required to document its
-choice of behavior in each of the areas that are designated
-``implementation defined''. The following lists all such areas,
-along with the section numbers from the ISO/IEC 9899:1990, ISO/IEC
-9899:1999 and ISO/IEC 9899:2011 standards. Some areas are only
-implementation-defined in one version of the standard.
-
-Some choices depend on the externally determined ABI for the platform
-(including standard character encodings) which GCC follows; these are
-listed as ``determined by ABI'' below. @xref{Compatibility, , Binary
-Compatibility}, and @uref{https://gcc.gnu.org/readings.html}. Some
-choices are documented in the preprocessor manual.
-@xref{Implementation-defined behavior, , Implementation-defined
-behavior, cpp, The C Preprocessor}. Some choices are made by the
-library and operating system (or other environment when compiling for
-a freestanding environment); refer to their documentation for details.
-
-@menu
-* Translation implementation::
-* Environment implementation::
-* Identifiers implementation::
-* Characters implementation::
-* Integers implementation::
-* Floating point implementation::
-* Arrays and pointers implementation::
-* Hints implementation::
-* Structures unions enumerations and bit-fields implementation::
-* Qualifiers implementation::
-* Declarators implementation::
-* Statements implementation::
-* Preprocessing directives implementation::
-* Library functions implementation::
-* Architecture implementation::
-* Locale-specific behavior implementation::
-@end menu
-
-@node Translation implementation
-@section Translation
-
-@itemize @bullet
-@item
-@cite{How a diagnostic is identified (C90 3.7, C99 and C11 3.10, C90,
-C99 and C11 5.1.1.3).}
-
-Diagnostics consist of all the output sent to stderr by GCC@.
-
-@item
-@cite{Whether each nonempty sequence of white-space characters other than
-new-line is retained or replaced by one space character in translation
-phase 3 (C90, C99 and C11 5.1.1.2).}
-
-@xref{Implementation-defined behavior, , Implementation-defined
-behavior, cpp, The C Preprocessor}.
-
-@end itemize
-
-@node Environment implementation
-@section Environment
-
-The behavior of most of these points are dependent on the implementation
-of the C library, and are not defined by GCC itself.
-
-@itemize @bullet
-@item
-@cite{The mapping between physical source file multibyte characters
-and the source character set in translation phase 1 (C90, C99 and C11
-5.1.1.2).}
-
-@xref{Implementation-defined behavior, , Implementation-defined
-behavior, cpp, The C Preprocessor}.
-
-@end itemize
-
-@node Identifiers implementation
-@section Identifiers
-
-@itemize @bullet
-@item
-@cite{Which additional multibyte characters may appear in identifiers
-and their correspondence to universal character names (C99 and C11 6.4.2).}
-
-@xref{Implementation-defined behavior, , Implementation-defined
-behavior, cpp, The C Preprocessor}.
-
-@item
-@cite{The number of significant initial characters in an identifier
-(C90 6.1.2, C90, C99 and C11 5.2.4.1, C99 and C11 6.4.2).}
-
-For internal names, all characters are significant. For external names,
-the number of significant characters are defined by the linker; for
-almost all targets, all characters are significant.
-
-@item
-@cite{Whether case distinctions are significant in an identifier with
-external linkage (C90 6.1.2).}
-
-This is a property of the linker. C99 and C11 require that case distinctions
-are always significant in identifiers with external linkage and
-systems without this property are not supported by GCC@.
-
-@end itemize
-
-@node Characters implementation
-@section Characters
-
-@itemize @bullet
-@item
-@cite{The number of bits in a byte (C90 3.4, C99 and C11 3.6).}
-
-Determined by ABI@.
-
-@item
-@cite{The values of the members of the execution character set (C90,
-C99 and C11 5.2.1).}
-
-Determined by ABI@.
-
-@item
-@cite{The unique value of the member of the execution character set produced
-for each of the standard alphabetic escape sequences (C90, C99 and C11
-5.2.2).}
-
-Determined by ABI@.
-
-@item
-@cite{The value of a @code{char} object into which has been stored any
-character other than a member of the basic execution character set
-(C90 6.1.2.5, C99 and C11 6.2.5).}
-
-Determined by ABI@.
-
-@item
-@cite{Which of @code{signed char} or @code{unsigned char} has the same
-range, representation, and behavior as ``plain'' @code{char} (C90
-6.1.2.5, C90 6.2.1.1, C99 and C11 6.2.5, C99 and C11 6.3.1.1).}
-
-@opindex fsigned-char
-@opindex funsigned-char
-Determined by ABI@. The options @option{-funsigned-char} and
-@option{-fsigned-char} change the default. @xref{C Dialect Options, ,
-Options Controlling C Dialect}.
-
-@item
-@cite{The mapping of members of the source character set (in character
-constants and string literals) to members of the execution character
-set (C90 6.1.3.4, C99 and C11 6.4.4.4, C90, C99 and C11 5.1.1.2).}
-
-Determined by ABI@.
-
-@item
-@cite{The value of an integer character constant containing more than one
-character or containing a character or escape sequence that does not map
-to a single-byte execution character (C90 6.1.3.4, C99 and C11 6.4.4.4).}
-
-@xref{Implementation-defined behavior, , Implementation-defined
-behavior, cpp, The C Preprocessor}.
-
-@item
-@cite{The value of a wide character constant containing more than one
-multibyte character or a single multibyte character that maps to
-multiple members of the extended execution character set, or
-containing a multibyte character or escape sequence not represented in
-the extended execution character set (C90 6.1.3.4, C99 and C11
-6.4.4.4).}
-
-@xref{Implementation-defined behavior, , Implementation-defined
-behavior, cpp, The C Preprocessor}.
-
-@item
-@cite{The current locale used to convert a wide character constant consisting
-of a single multibyte character that maps to a member of the extended
-execution character set into a corresponding wide character code (C90
-6.1.3.4, C99 and C11 6.4.4.4).}
-
-@xref{Implementation-defined behavior, , Implementation-defined
-behavior, cpp, The C Preprocessor}.
-
-@item
-@cite{Whether differently-prefixed wide string literal tokens can be
-concatenated and, if so, the treatment of the resulting multibyte
-character sequence (C11 6.4.5).}
-
-Such tokens may not be concatenated.
-
-@item
-@cite{The current locale used to convert a wide string literal into
-corresponding wide character codes (C90 6.1.4, C99 and C11 6.4.5).}
-
-@xref{Implementation-defined behavior, , Implementation-defined
-behavior, cpp, The C Preprocessor}.
-
-@item
-@cite{The value of a string literal containing a multibyte character or escape
-sequence not represented in the execution character set (C90 6.1.4,
-C99 and C11 6.4.5).}
-
-@xref{Implementation-defined behavior, , Implementation-defined
-behavior, cpp, The C Preprocessor}.
-
-@item
-@cite{The encoding of any of @code{wchar_t}, @code{char16_t}, and
-@code{char32_t} where the corresponding standard encoding macro
-(@code{__STDC_ISO_10646__}, @code{__STDC_UTF_16__}, or
-@code{__STDC_UTF_32__}) is not defined (C11 6.10.8.2).}
-
-@xref{Implementation-defined behavior, , Implementation-defined
-behavior, cpp, The C Preprocessor}. @code{char16_t} and
-@code{char32_t} literals are always encoded in UTF-16 and UTF-32
-respectively.
-
-@end itemize
-
-@node Integers implementation
-@section Integers
-
-@itemize @bullet
-@item
-@cite{Any extended integer types that exist in the implementation (C99
-and C11 6.2.5).}
-
-GCC does not support any extended integer types.
-@c The __mode__ attribute might create types of precisions not
-@c otherwise supported, but the syntax isn't right for use everywhere
-@c the standard type names might be used. Predefined typedefs should
-@c be used if any extended integer types are to be defined. The
-@c __int128_t and __uint128_t typedefs are not extended integer types
-@c as they are generally longer than the ABI-specified intmax_t.
-
-@item
-@cite{Whether signed integer types are represented using sign and magnitude,
-two's complement, or one's complement, and whether the extraordinary value
-is a trap representation or an ordinary value (C99 and C11 6.2.6.2).}
-
-GCC supports only two's complement integer types, and all bit patterns
-are ordinary values.
-
-@item
-@cite{The rank of any extended integer type relative to another extended
-integer type with the same precision (C99 and C11 6.3.1.1).}
-
-GCC does not support any extended integer types.
-@c If it did, there would only be one of each precision and signedness.
-
-@item
-@cite{The result of, or the signal raised by, converting an integer to a
-signed integer type when the value cannot be represented in an object of
-that type (C90 6.2.1.2, C99 and C11 6.3.1.3).}
-
-For conversion to a type of width @math{N}, the value is reduced
-modulo @math{2^N} to be within range of the type; no signal is raised.
-
-@item
-@cite{The results of some bitwise operations on signed integers (C90
-6.3, C99 and C11 6.5).}
-
-Bitwise operators act on the representation of the value including
-both the sign and value bits, where the sign bit is considered
-immediately above the highest-value value bit. Signed @samp{>>} acts
-on negative numbers by sign extension.
-
-As an extension to the C language, GCC does not use the latitude given in
-C99 and C11 only to treat certain aspects of signed @samp{<<} as undefined.
-However, @option{-fsanitize=shift} (and @option{-fsanitize=undefined}) will
-diagnose such cases. They are also diagnosed where constant
-expressions are required.
-
-@item
-@cite{The sign of the remainder on integer division (C90 6.3.5).}
-
-GCC always follows the C99 and C11 requirement that the result of division is
-truncated towards zero.
-
-@end itemize
-
-@node Floating point implementation
-@section Floating Point
-
-@itemize @bullet
-@item
-@cite{The accuracy of the floating-point operations and of the library
-functions in @code{<math.h>} and @code{<complex.h>} that return floating-point
-results (C90, C99 and C11 5.2.4.2.2).}
-
-The accuracy is unknown.
-
-@item
-@cite{The rounding behaviors characterized by non-standard values
-of @code{FLT_ROUNDS} @gol
-(C90, C99 and C11 5.2.4.2.2).}
-
-GCC does not use such values.
-
-@item
-@cite{The evaluation methods characterized by non-standard negative
-values of @code{FLT_EVAL_METHOD} (C99 and C11 5.2.4.2.2).}
-
-GCC does not use such values.
-
-@item
-@cite{The direction of rounding when an integer is converted to a
-floating-point number that cannot exactly represent the original
-value (C90 6.2.1.3, C99 and C11 6.3.1.4).}
-
-C99 Annex F is followed.
-
-@item
-@cite{The direction of rounding when a floating-point number is
-converted to a narrower floating-point number (C90 6.2.1.4, C99 and C11
-6.3.1.5).}
-
-C99 Annex F is followed.
-
-@item
-@cite{How the nearest representable value or the larger or smaller
-representable value immediately adjacent to the nearest representable
-value is chosen for certain floating constants (C90 6.1.3.1, C99 and C11
-6.4.4.2).}
-
-C99 Annex F is followed.
-
-@item
-@cite{Whether and how floating expressions are contracted when not
-disallowed by the @code{FP_CONTRACT} pragma (C99 and C11 6.5).}
-
-Expressions are currently only contracted if @option{-ffp-contract=fast},
-@option{-funsafe-math-optimizations} or @option{-ffast-math} are used.
-This is subject to change.
-
-@item
-@cite{The default state for the @code{FENV_ACCESS} pragma (C99 and C11
-7.6.1).}
-
-This pragma is not implemented, but the default is to ``off'' unless
-@option{-frounding-math} is used and @option{-fno-trapping-math} is not
-in which case it is ``on''.
-
-@item
-@cite{Additional floating-point exceptions, rounding modes, environments,
-and classifications, and their macro names (C99 and C11 7.6, C99 and
-C11 7.12).}
-
-This is dependent on the implementation of the C library, and is not
-defined by GCC itself.
-
-@item
-@cite{The default state for the @code{FP_CONTRACT} pragma (C99 and C11
-7.12.2).}
-
-This pragma is not implemented. Expressions are currently only
-contracted if @option{-ffp-contract=fast},
-@option{-funsafe-math-optimizations} or @option{-ffast-math} are used.
-This is subject to change.
-
-@item
-@cite{Whether the ``inexact'' floating-point exception can be raised
-when the rounded result actually does equal the mathematical result
-in an IEC 60559 conformant implementation (C99 F.9).}
-
-This is dependent on the implementation of the C library, and is not
-defined by GCC itself.
-
-@item
-@cite{Whether the ``underflow'' (and ``inexact'') floating-point
-exception can be raised when a result is tiny but not inexact in an
-IEC 60559 conformant implementation (C99 F.9).}
-
-This is dependent on the implementation of the C library, and is not
-defined by GCC itself.
-
-@end itemize
-
-@node Arrays and pointers implementation
-@section Arrays and Pointers
-
-@itemize @bullet
-@item
-@cite{The result of converting a pointer to an integer or
-vice versa (C90 6.3.4, C99 and C11 6.3.2.3).}
-
-A cast from pointer to integer discards most-significant bits if the
-pointer representation is larger than the integer type,
-sign-extends@footnote{Future versions of GCC may zero-extend, or use
-a target-defined @code{ptr_extend} pattern. Do not rely on sign extension.}
-if the pointer representation is smaller than the integer type, otherwise
-the bits are unchanged.
-@c ??? We've always claimed that pointers were unsigned entities.
-@c Shouldn't we therefore be doing zero-extension? If so, the bug
-@c is in convert_to_integer, where we call type_for_size and request
-@c a signed integral type. On the other hand, it might be most useful
-@c for the target if we extend according to POINTERS_EXTEND_UNSIGNED.
-
-A cast from integer to pointer discards most-significant bits if the
-pointer representation is smaller than the integer type, extends according
-to the signedness of the integer type if the pointer representation
-is larger than the integer type, otherwise the bits are unchanged.
-
-When casting from pointer to integer and back again, the resulting
-pointer must reference the same object as the original pointer, otherwise
-the behavior is undefined. That is, one may not use integer arithmetic to
-avoid the undefined behavior of pointer arithmetic as proscribed in
-C99 and C11 6.5.6/8.
-
-@item
-@cite{The size of the result of subtracting two pointers to elements
-of the same array (C90 6.3.6, C99 and C11 6.5.6).}
-
-The value is as specified in the standard and the type is determined
-by the ABI@.
-
-@end itemize
-
-@node Hints implementation
-@section Hints
-
-@itemize @bullet
-@item
-@cite{The extent to which suggestions made by using the @code{register}
-storage-class specifier are effective (C90 6.5.1, C99 and C11 6.7.1).}
-
-The @code{register} specifier affects code generation only in these ways:
-
-@itemize @bullet
-@item
-When used as part of the register variable extension, see
-@ref{Explicit Register Variables}.
-
-@item
-When @option{-O0} is in use, the compiler allocates distinct stack
-memory for all variables that do not have the @code{register}
-storage-class specifier; if @code{register} is specified, the variable
-may have a shorter lifespan than the code would indicate and may never
-be placed in memory.
-
-@item
-On some rare x86 targets, @code{setjmp} doesn't save the registers in
-all circumstances. In those cases, GCC doesn't allocate any variables
-in registers unless they are marked @code{register}.
-
-@end itemize
-
-@item
-@cite{The extent to which suggestions made by using the inline function
-specifier are effective (C99 and C11 6.7.4).}
-
-GCC will not inline any functions if the @option{-fno-inline} option is
-used or if @option{-O0} is used. Otherwise, GCC may still be unable to
-inline a function for many reasons; the @option{-Winline} option may be
-used to determine if a function has not been inlined and why not.
-
-@end itemize
-
-@node Structures unions enumerations and bit-fields implementation
-@section Structures, Unions, Enumerations, and Bit-Fields
-
-@itemize @bullet
-@item
-@cite{A member of a union object is accessed using a member of a
-different type (C90 6.3.2.3).}
-
-The relevant bytes of the representation of the object are treated as
-an object of the type used for the access. @xref{Type-punning}. This
-may be a trap representation.
-
-@item
-@cite{Whether a ``plain'' @code{int} bit-field is treated as a
-@code{signed int} bit-field or as an @code{unsigned int} bit-field
-(C90 6.5.2, C90 6.5.2.1, C99 and C11 6.7.2, C99 and C11 6.7.2.1).}
-
-@opindex funsigned-bitfields
-By default it is treated as @code{signed int} but this may be changed
-by the @option{-funsigned-bitfields} option.
-
-@item
-@cite{Allowable bit-field types other than @code{_Bool}, @code{signed int},
-and @code{unsigned int} (C99 and C11 6.7.2.1).}
-
-Other integer types, such as @code{long int}, and enumerated types are
-permitted even in strictly conforming mode.
-
-@item
-@cite{Whether atomic types are permitted for bit-fields (C11 6.7.2.1).}
-
-Atomic types are not permitted for bit-fields.
-
-@item
-@cite{Whether a bit-field can straddle a storage-unit boundary (C90
-6.5.2.1, C99 and C11 6.7.2.1).}
-
-Determined by ABI@.
-
-@item
-@cite{The order of allocation of bit-fields within a unit (C90
-6.5.2.1, C99 and C11 6.7.2.1).}
-
-Determined by ABI@.
-
-@item
-@cite{The alignment of non-bit-field members of structures (C90
-6.5.2.1, C99 and C11 6.7.2.1).}
-
-Determined by ABI@.
-
-@item
-@cite{The integer type compatible with each enumerated type (C90
-6.5.2.2, C99 and C11 6.7.2.2).}
-
-@opindex fshort-enums
-Normally, the type is @code{unsigned int} if there are no negative
-values in the enumeration, otherwise @code{int}. If
-@option{-fshort-enums} is specified, then if there are negative values
-it is the first of @code{signed char}, @code{short} and @code{int}
-that can represent all the values, otherwise it is the first of
-@code{unsigned char}, @code{unsigned short} and @code{unsigned int}
-that can represent all the values.
-@c On a few unusual targets with 64-bit int, this doesn't agree with
-@c the code and one of the types accessed via mode attributes (which
-@c are not currently considered extended integer types) may be used.
-@c If these types are made extended integer types, it would still be
-@c the case that -fshort-enums stops the implementation from
-@c conforming to C90 on those targets.
-
-On some targets, @option{-fshort-enums} is the default; this is
-determined by the ABI@.
-
-@end itemize
-
-@node Qualifiers implementation
-@section Qualifiers
-
-@itemize @bullet
-@item
-@cite{What constitutes an access to an object that has volatile-qualified
-type (C90 6.5.3, C99 and C11 6.7.3).}
-
-Such an object is normally accessed by pointers and used for accessing
-hardware. In most expressions, it is intuitively obvious what is a read
-and what is a write. For example
-
-@smallexample
-volatile int *dst = @var{somevalue};
-volatile int *src = @var{someothervalue};
-*dst = *src;
-@end smallexample
-
-@noindent
-will cause a read of the volatile object pointed to by @var{src} and store the
-value into the volatile object pointed to by @var{dst}. There is no
-guarantee that these reads and writes are atomic, especially for objects
-larger than @code{int}.
-
-However, if the volatile storage is not being modified, and the value of
-the volatile storage is not used, then the situation is less obvious.
-For example
-
-@smallexample
-volatile int *src = @var{somevalue};
-*src;
-@end smallexample
-
-According to the C standard, such an expression is an rvalue whose type
-is the unqualified version of its original type, i.e.@: @code{int}. Whether
-GCC interprets this as a read of the volatile object being pointed to or
-only as a request to evaluate the expression for its side effects depends
-on this type.
-
-If it is a scalar type, or on most targets an aggregate type whose only
-member object is of a scalar type, or a union type whose member objects
-are of scalar types, the expression is interpreted by GCC as a read of
-the volatile object; in the other cases, the expression is only evaluated
-for its side effects.
-
-When an object of an aggregate type, with the same size and alignment as a
-scalar type @code{S}, is the subject of a volatile access by an assignment
-expression or an atomic function, the access to it is performed as if the
-object's declared type were @code{volatile S}.
-
-@end itemize
-
-@node Declarators implementation
-@section Declarators
-
-@itemize @bullet
-@item
-@cite{The maximum number of declarators that may modify an arithmetic,
-structure or union type (C90 6.5.4).}
-
-GCC is only limited by available memory.
-
-@end itemize
-
-@node Statements implementation
-@section Statements
-
-@itemize @bullet
-@item
-@cite{The maximum number of @code{case} values in a @code{switch}
-statement (C90 6.6.4.2).}
-
-GCC is only limited by available memory.
-
-@end itemize
-
-@node Preprocessing directives implementation
-@section Preprocessing Directives
-
-@xref{Implementation-defined behavior, , Implementation-defined
-behavior, cpp, The C Preprocessor}, for details of these aspects of
-implementation-defined behavior.
-
-@itemize @bullet
-@item
-@cite{The locations within @code{#pragma} directives where header name
-preprocessing tokens are recognized (C11 6.4, C11 6.4.7).}
-
-@item
-@cite{How sequences in both forms of header names are mapped to headers
-or external source file names (C90 6.1.7, C99 and C11 6.4.7).}
-
-@item
-@cite{Whether the value of a character constant in a constant expression
-that controls conditional inclusion matches the value of the same character
-constant in the execution character set (C90 6.8.1, C99 and C11 6.10.1).}
-
-@item
-@cite{Whether the value of a single-character character constant in a
-constant expression that controls conditional inclusion may have a
-negative value (C90 6.8.1, C99 and C11 6.10.1).}
-
-@item
-@cite{The places that are searched for an included @samp{<>} delimited
-header, and how the places are specified or the header is
-identified (C90 6.8.2, C99 and C11 6.10.2).}
-
-@item
-@cite{How the named source file is searched for in an included @samp{""}
-delimited header (C90 6.8.2, C99 and C11 6.10.2).}
-
-@item
-@cite{The method by which preprocessing tokens (possibly resulting from
-macro expansion) in a @code{#include} directive are combined into a header
-name (C90 6.8.2, C99 and C11 6.10.2).}
-
-@item
-@cite{The nesting limit for @code{#include} processing (C90 6.8.2, C99
-and C11 6.10.2).}
-
-@item
-@cite{Whether the @samp{#} operator inserts a @samp{\} character before
-the @samp{\} character that begins a universal character name in a
-character constant or string literal (C99 and C11 6.10.3.2).}
-
-@item
-@cite{The behavior on each recognized non-@code{STDC #pragma}
-directive (C90 6.8.6, C99 and C11 6.10.6).}
-
-@xref{Pragmas, , Pragmas, cpp, The C Preprocessor}, for details of
-pragmas accepted by GCC on all targets. @xref{Pragmas, , Pragmas
-Accepted by GCC}, for details of target-specific pragmas.
-
-@item
-@cite{The definitions for @code{__DATE__} and @code{__TIME__} when
-respectively, the date and time of translation are not available (C90
-6.8.8, C99 6.10.8, C11 6.10.8.1).}
-
-@end itemize
-
-@node Library functions implementation
-@section Library Functions
-
-The behavior of most of these points are dependent on the implementation
-of the C library, and are not defined by GCC itself.
-
-@itemize @bullet
-@item
-@cite{The null pointer constant to which the macro @code{NULL} expands
-(C90 7.1.6, C99 7.17, C11 7.19).}
-
-In @code{<stddef.h>}, @code{NULL} expands to @code{((void *)0)}. GCC
-does not provide the other headers which define @code{NULL} and some
-library implementations may use other definitions in those headers.
-
-@end itemize
-
-@node Architecture implementation
-@section Architecture
-
-@itemize @bullet
-@item
-@cite{The values or expressions assigned to the macros specified in the
-headers @code{<float.h>}, @code{<limits.h>}, and @code{<stdint.h>}
-(C90, C99 and C11 5.2.4.2, C99 7.18.2, C99 7.18.3, C11 7.20.2, C11 7.20.3).}
-
-Determined by ABI@.
-
-@item
-@cite{The result of attempting to indirectly access an object with
-automatic or thread storage duration from a thread other than the one
-with which it is associated (C11 6.2.4).}
-
-Such accesses are supported, subject to the same requirements for
-synchronization for concurrent accesses as for concurrent accesses to
-any object.
-
-@item
-@cite{The number, order, and encoding of bytes in any object
-(when not explicitly specified in this International Standard) (C99
-and C11 6.2.6.1).}
-
-Determined by ABI@.
-
-@item
-@cite{Whether any extended alignments are supported and the contexts
-in which they are supported (C11 6.2.8).}
-
-Extended alignments up to @math{2^{28}} (bytes) are supported for
-objects of automatic storage duration. Alignments supported for
-objects of static and thread storage duration are determined by the
-ABI.
-
-@item
-@cite{Valid alignment values other than those returned by an _Alignof
-expression for fundamental types, if any (C11 6.2.8).}
-
-Valid alignments are powers of 2 up to and including @math{2^{28}}.
-
-@item
-@cite{The value of the result of the @code{sizeof} and @code{_Alignof}
-operators (C90 6.3.3.4, C99 and C11 6.5.3.4).}
-
-Determined by ABI@.
-
-@end itemize
-
-@node Locale-specific behavior implementation
-@section Locale-Specific Behavior
-
-The behavior of these points are dependent on the implementation
-of the C library, and are not defined by GCC itself.
+++ /dev/null
-@c Copyright (C) 2009-2022 Free Software Foundation, Inc.
-@c This is part of the GCC manual.
-@c For copying conditions, see the file gcc.texi.
-
-@node C++ Implementation
-@chapter C++ Implementation-Defined Behavior
-@cindex implementation-defined behavior, C++ language
-
-A conforming implementation of ISO C++ is required to document its
-choice of behavior in each of the areas that are designated
-``implementation defined''. The following lists all such areas,
-along with the section numbers from the ISO/IEC 14882:1998 and ISO/IEC
-14882:2003 standards. Some areas are only implementation-defined in
-one version of the standard.
-
-Some choices depend on the externally determined ABI for the platform
-(including standard character encodings) which GCC follows; these are
-listed as ``determined by ABI'' below. @xref{Compatibility, , Binary
-Compatibility}, and @uref{https://gcc.gnu.org/readings.html}. Some
-choices are documented in the preprocessor manual.
-@xref{Implementation-defined behavior, , Implementation-defined
-behavior, cpp, The C Preprocessor}. Some choices are documented in
-the corresponding document for the C language. @xref{C
-Implementation}. Some choices are made by the library and operating
-system (or other environment when compiling for a freestanding
-environment); refer to their documentation for details.
-
-@menu
-* Conditionally-supported behavior::
-* Exception handling::
-@end menu
-
-@node Conditionally-supported behavior
-@section Conditionally-Supported Behavior
-
-@cite{Each implementation shall include documentation that identifies
-all conditionally-supported constructs that it does not support (C++0x
-1.4).}
-
-@itemize @bullet
-@item
-@cite{Whether an argument of class type with a non-trivial copy
-constructor or destructor can be passed to ... (C++0x 5.2.2).}
-
-Such argument passing is supported, using the same
-pass-by-invisible-reference approach used for normal function
-arguments of such types.
-
-@end itemize
-
-@node Exception handling
-@section Exception Handling
-
-@itemize @bullet
-@item
-@cite{In the situation where no matching handler is found, it is
-implementation-defined whether or not the stack is unwound before
-std::terminate() is called (C++98 15.5.1).}
-
-The stack is not unwound before std::terminate is called.
-
-@end itemize
+++ /dev/null
-@ignore
-@c Set file name and title for man page.
-@setfilename gfdl
-@settitle GNU Free Documentation License
-@c man begin SEEALSO
-gpl(7), fsf-funding(7).
-@c man end
-@c man begin COPYRIGHT
-Copyright @copyright{} 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
-@uref{https://fsf.org/}
-
-Everyone is permitted to copy and distribute verbatim copies
-of this license document, but changing it is not allowed.
-@c This file is intended to be included within another document,
-@c hence no sectioning command or @node.
-@c man end
-@end ignore
-@c Special handling for inclusion in the install manual.
-@ifset gfdlhtml
-@ifnothtml
-@comment node-name, next, previous, up
-@node GNU Free Documentation License, Concept Index, Specific, Top
-@end ifnothtml
-@html
-<h1 align="center">Installing GCC: GNU Free Documentation License</h1>
-@end html
-@ifnothtml
-@unnumbered GNU Free Documentation License
-@end ifnothtml
-@end ifset
-@c man begin DESCRIPTION
-@ifclear gfdlhtml
-@comment For some cases, this default @node/@unnumbered is not applicable and
-@comment causes warnings. In those cases, the including file can set
-@comment nodefaultgnufreedocumentationlicensenode and provide it's own version.
-@comment F.i., when this file is included in an @raisesections context, the
-@comment including file can use an @unnumberedsec.
-@ifclear nodefaultgnufreedocumentationlicensenode
-@node GNU Free Documentation License
-@unnumbered GNU Free Documentation License
-@end ifclear
-@end ifclear
-
-@cindex FDL, GNU Free Documentation License
-@center Version 1.3, 3 November 2008
-
-@display
-Copyright @copyright{} 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
-@uref{https://fsf.org/}
-
-Everyone is permitted to copy and distribute verbatim copies
-of this license document, but changing it is not allowed.
-@end display
-
-@enumerate 0
-@item
-PREAMBLE
-
-The purpose of this License is to make a manual, textbook, or other
-functional and useful document @dfn{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.
-
-@item
-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
-@sc{ascii} without markup, Texinfo input format, La@TeX{} input
-format, @acronym{SGML} or @acronym{XML} using a publicly available
-@acronym{DTD}, and standard-conforming simple @acronym{HTML},
-PostScript or @acronym{PDF} designed for human modification. Examples
-of transparent image formats include @acronym{PNG}, @acronym{XCF} and
-@acronym{JPG}. Opaque formats include proprietary formats that can be
-read and edited only by proprietary word processors, @acronym{SGML} or
-@acronym{XML} for which the @acronym{DTD} and/or processing tools are
-not generally available, and the machine-generated @acronym{HTML},
-PostScript or @acronym{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.
-
-@item
-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.
-
-@item
-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.
-
-@item
-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.
-
-@item
-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.''
-
-@item
-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.
-
-@item
-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.
-
-@item
-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.
-
-@item
-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.
-
-@item
-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
-@uref{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.
-
-@item
-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.
-
-@end enumerate
-
-@page
-@unnumberedsec 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:
-
-@smallexample
-@group
- Copyright (C) @var{year} @var{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 group
-@end smallexample
-
-If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
-replace the ``with...Texts.'' line with this:
-
-@smallexample
-@group
- with the Invariant Sections being @var{list their titles}, with
- the Front-Cover Texts being @var{list}, and with the Back-Cover Texts
- being @var{list}.
-@end group
-@end smallexample
-
-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.
-
-@c Local Variables:
-@c ispell-local-pdict: "ispell-dict"
-@c End:
-
-@c man end
+++ /dev/null
-@ignore
-@c Set file name and title for man page.
-@setfilename fsf-funding
-@settitle Funding Free Software
-@c man begin SEEALSO
-gpl(7), gfdl(7).
-@c man end
-@end ignore
-@node Funding
-@c man begin DESCRIPTION
-@unnumbered Funding Free Software
-
-If you want to have more free software a few years from now, it makes
-sense for you to help encourage people to contribute funds for its
-development. The most effective approach known is to encourage
-commercial redistributors to donate.
-
-Users of free software systems can boost the pace of development by
-encouraging for-a-fee distributors to donate part of their selling price
-to free software developers---the Free Software Foundation, and others.
-
-The way to convince distributors to do this is to demand it and expect
-it from them. So when you compare distributors, judge them partly by
-how much they give to free software development. Show distributors
-they must compete to be the one who gives the most.
-
-To make this approach work, you must insist on numbers that you can
-compare, such as, ``We will donate ten dollars to the Frobnitz project
-for each disk sold.'' Don't be satisfied with a vague promise, such as
-``A portion of the profits are donated,'' since it doesn't give a basis
-for comparison.
-
-Even a precise fraction ``of the profits from this disk'' is not very
-meaningful, since creative accounting and unrelated business decisions
-can greatly alter what fraction of the sales price counts as profit.
-If the price you pay is $50, ten percent of the profit is probably
-less than a dollar; it might be a few cents, or nothing at all.
-
-Some redistributors do development work themselves. This is useful too;
-but to keep everyone honest, you need to inquire how much they do, and
-what kind. Some kinds of development make much more long-term
-difference than others. For example, maintaining a separate version of
-a program contributes very little; maintaining the standard version of a
-program for the whole community contributes much. Easy new ports
-contribute little, since someone else would surely do them; difficult
-ports such as adding a new CPU to the GNU Compiler Collection contribute more;
-major new features or packages contribute the most.
-
-By establishing the idea that supporting further development is ``the
-proper thing to do'' when distributing free software for a fee, we can
-assure a steady flow of resources into making more free software.
-@c man end
-
-@display
-@c man begin COPYRIGHT
-Copyright @copyright{} 1994 Free Software Foundation, Inc.
-Verbatim copying and redistribution of this section is permitted
-without royalty; alteration is not permitted.
-@c man end
-@end display
+++ /dev/null
-@c Copyright (C) 2001-2022 Free Software Foundation, Inc.
-@c This is part of the GCC manual.
-@c For copying conditions, see the file gcc.texi.
-
-@c Version number and development mode.
-@c version-GCC is @set to the base GCC version number.
-@c DEVELOPMENT is @set for an in-development version, @clear for a
-@c release version (corresponding to ``experimental''/anything else
-@c in gcc/DEV-PHASE).
-
-@include gcc-vers.texi
-
-@c Common macros to support generating man pages:
-
-@macro gcctabopt{body}
-@code{\body\}
-@end macro
-@macro gccoptlist{body}
-@smallexample
-\body\
-@end smallexample
-@end macro
-@c Makeinfo handles the above macro OK, TeX needs manual line breaks;
-@c they get lost at some point in handling the macro. But if @macro is
-@c used here rather than @alias, it produces double line breaks.
-@iftex
-@alias gol = *
-@end iftex
-@ifnottex
-@macro gol
-@end macro
-@end ifnottex
-
-@c For FSF printing, define FSFPRINT. Also update the ISBN and last
-@c printing date for the manual being printed.
-@c @set FSFPRINT
-@ifset FSFPRINT
-@smallbook
-@finalout
-@c Cause even numbered pages to be printed on the left hand side of
-@c the page and odd numbered pages to be printed on the right hand
-@c side of the page. Using this, you can print on both sides of a
-@c sheet of paper and have the text on the same part of the sheet.
-
-@c The text on right hand pages is pushed towards the right hand
-@c margin and the text on left hand pages is pushed toward the left
-@c hand margin.
-@c (To provide the reverse effect, set bindingoffset to -0.75in.)
-@tex
-\global\bindingoffset=0.75in
-\global\normaloffset =0.75in
-@end tex
-@end ifset
-
-@c Macro to generate a "For the N.N.N version" subtitle on the title
-@c page of TeX documentation. This macro should be used in the
-@c titlepage environment after the title and any other subtitles have
-@c been placed, and before any authors are placed.
-@macro versionsubtitle
-@ifclear DEVELOPMENT
-@subtitle For @sc{gcc} version @value{version-GCC}
-@end ifclear
-@ifset DEVELOPMENT
-@subtitle For @sc{gcc} version @value{version-GCC} (pre-release)
-@end ifset
-@ifset VERSION_PACKAGE
-@sp 1
-@subtitle @value{VERSION_PACKAGE}
-@end ifset
-@c Even if there are no authors, the second titlepage line should be
-@c forced to the bottom of the page.
-@vskip 0pt plus 1filll
-@end macro
+++ /dev/null
-@ignore
-@c Set file name and title for man page.
-@setfilename gpl
-@settitle GNU General Public License
-@c man begin SEEALSO
-gfdl(7), fsf-funding(7).
-@c man end
-@c man begin COPYRIGHT
-Copyright @copyright{} 2007 Free Software Foundation, Inc.
-
-Everyone is permitted to copy and distribute verbatim copies of this
-license document, but changing it is not allowed.
-@c man end
-@end ignore
-@node Copying
-@c man begin DESCRIPTION
-@unnumbered GNU General Public License
-@center Version 3, 29 June 2007
-
-@c This file is intended to be included in another file.
-
-@display
-Copyright @copyright{} 2007 Free Software Foundation, Inc. @url{https://fsf.org/}
-
-Everyone is permitted to copy and distribute verbatim copies of this
-license document, but changing it is not allowed.
-@end display
-
-@heading Preamble
-
-The GNU General Public License is a free, copyleft license for
-software and other kinds of works.
-
-The licenses for most software and other practical works are designed
-to take away your freedom to share and change the works. By contrast,
-the GNU General Public License is intended to guarantee your freedom
-to share and change all versions of a program--to make sure it remains
-free software for all its users. We, the Free Software Foundation,
-use the GNU General Public License for most of our software; it
-applies also to any other work released this way by its authors. You
-can apply it to your programs, too.
-
-When we speak of free software, we are referring to freedom, not
-price. Our General Public Licenses are designed to make sure that you
-have the freedom to distribute copies of free software (and charge for
-them if you wish), that you receive source code or can get it if you
-want it, that you can change the software or use pieces of it in new
-free programs, and that you know you can do these things.
-
-To protect your rights, we need to prevent others from denying you
-these rights or asking you to surrender the rights. Therefore, you
-have certain responsibilities if you distribute copies of the
-software, or if you modify it: responsibilities to respect the freedom
-of others.
-
-For example, if you distribute copies of such a program, whether
-gratis or for a fee, you must pass on to the recipients the same
-freedoms that you received. You must make sure that they, too,
-receive or can get the source code. And you must show them these
-terms so they know their rights.
-
-Developers that use the GNU GPL protect your rights with two steps:
-(1) assert copyright on the software, and (2) offer you this License
-giving you legal permission to copy, distribute and/or modify it.
-
-For the developers' and authors' protection, the GPL clearly explains
-that there is no warranty for this free software. For both users' and
-authors' sake, the GPL requires that modified versions be marked as
-changed, so that their problems will not be attributed erroneously to
-authors of previous versions.
-
-Some devices are designed to deny users access to install or run
-modified versions of the software inside them, although the
-manufacturer can do so. This is fundamentally incompatible with the
-aim of protecting users' freedom to change the software. The
-systematic pattern of such abuse occurs in the area of products for
-individuals to use, which is precisely where it is most unacceptable.
-Therefore, we have designed this version of the GPL to prohibit the
-practice for those products. If such problems arise substantially in
-other domains, we stand ready to extend this provision to those
-domains in future versions of the GPL, as needed to protect the
-freedom of users.
-
-Finally, every program is threatened constantly by software patents.
-States should not allow patents to restrict development and use of
-software on general-purpose computers, but in those that do, we wish
-to avoid the special danger that patents applied to a free program
-could make it effectively proprietary. To prevent this, the GPL
-assures that patents cannot be used to render the program non-free.
-
-The precise terms and conditions for copying, distribution and
-modification follow.
-
-@heading TERMS AND CONDITIONS
-
-@enumerate 0
-@item Definitions.
-
-``This License'' refers to version 3 of the GNU General Public License.
-
-``Copyright'' also means copyright-like laws that apply to other kinds
-of works, such as semiconductor masks.
-
-``The Program'' refers to any copyrightable work licensed under this
-License. Each licensee is addressed as ``you''. ``Licensees'' and
-``recipients'' may be individuals or organizations.
-
-To ``modify'' a work means to copy from or adapt all or part of the work
-in a fashion requiring copyright permission, other than the making of
-an exact copy. The resulting work is called a ``modified version'' of
-the earlier work or a work ``based on'' the earlier work.
-
-A ``covered work'' means either the unmodified Program or a work based
-on the Program.
-
-To ``propagate'' a work means to do anything with it that, without
-permission, would make you directly or secondarily liable for
-infringement under applicable copyright law, except executing it on a
-computer or modifying a private copy. Propagation includes copying,
-distribution (with or without modification), making available to the
-public, and in some countries other activities as well.
-
-To ``convey'' a work means any kind of propagation that enables other
-parties to make or receive copies. Mere interaction with a user
-through a computer network, with no transfer of a copy, is not
-conveying.
-
-An interactive user interface displays ``Appropriate Legal Notices'' to
-the extent that it includes a convenient and prominently visible
-feature that (1) displays an appropriate copyright notice, and (2)
-tells the user that there is no warranty for the work (except to the
-extent that warranties are provided), that licensees may convey the
-work under this License, and how to view a copy of this License. If
-the interface presents a list of user commands or options, such as a
-menu, a prominent item in the list meets this criterion.
-
-@item Source Code.
-
-The ``source code'' for a work means the preferred form of the work for
-making modifications to it. ``Object code'' means any non-source form
-of a work.
-
-A ``Standard Interface'' means an interface that either is an official
-standard defined by a recognized standards body, or, in the case of
-interfaces specified for a particular programming language, one that
-is widely used among developers working in that language.
-
-The ``System Libraries'' of an executable work include anything, other
-than the work as a whole, that (a) is included in the normal form of
-packaging a Major Component, but which is not part of that Major
-Component, and (b) serves only to enable use of the work with that
-Major Component, or to implement a Standard Interface for which an
-implementation is available to the public in source code form. A
-``Major Component'', in this context, means a major essential component
-(kernel, window system, and so on) of the specific operating system
-(if any) on which the executable work runs, or a compiler used to
-produce the work, or an object code interpreter used to run it.
-
-The ``Corresponding Source'' for a work in object code form means all
-the source code needed to generate, install, and (for an executable
-work) run the object code and to modify the work, including scripts to
-control those activities. However, it does not include the work's
-System Libraries, or general-purpose tools or generally available free
-programs which are used unmodified in performing those activities but
-which are not part of the work. For example, Corresponding Source
-includes interface definition files associated with source files for
-the work, and the source code for shared libraries and dynamically
-linked subprograms that the work is specifically designed to require,
-such as by intimate data communication or control flow between those
-subprograms and other parts of the work.
-
-The Corresponding Source need not include anything that users can
-regenerate automatically from other parts of the Corresponding Source.
-
-The Corresponding Source for a work in source code form is that same
-work.
-
-@item Basic Permissions.
-
-All rights granted under this License are granted for the term of
-copyright on the Program, and are irrevocable provided the stated
-conditions are met. This License explicitly affirms your unlimited
-permission to run the unmodified Program. The output from running a
-covered work is covered by this License only if the output, given its
-content, constitutes a covered work. This License acknowledges your
-rights of fair use or other equivalent, as provided by copyright law.
-
-You may make, run and propagate covered works that you do not convey,
-without conditions so long as your license otherwise remains in force.
-You may convey covered works to others for the sole purpose of having
-them make modifications exclusively for you, or provide you with
-facilities for running those works, provided that you comply with the
-terms of this License in conveying all material for which you do not
-control copyright. Those thus making or running the covered works for
-you must do so exclusively on your behalf, under your direction and
-control, on terms that prohibit them from making any copies of your
-copyrighted material outside their relationship with you.
-
-Conveying under any other circumstances is permitted solely under the
-conditions stated below. Sublicensing is not allowed; section 10
-makes it unnecessary.
-
-@item Protecting Users' Legal Rights From Anti-Circumvention Law.
-
-No covered work shall be deemed part of an effective technological
-measure under any applicable law fulfilling obligations under article
-11 of the WIPO copyright treaty adopted on 20 December 1996, or
-similar laws prohibiting or restricting circumvention of such
-measures.
-
-When you convey a covered work, you waive any legal power to forbid
-circumvention of technological measures to the extent such
-circumvention is effected by exercising rights under this License with
-respect to the covered work, and you disclaim any intention to limit
-operation or modification of the work as a means of enforcing, against
-the work's users, your or third parties' legal rights to forbid
-circumvention of technological measures.
-
-@item Conveying Verbatim Copies.
-
-You may convey verbatim copies of the Program's source code as you
-receive it, in any medium, provided that you conspicuously and
-appropriately publish on each copy an appropriate copyright notice;
-keep intact all notices stating that this License and any
-non-permissive terms added in accord with section 7 apply to the code;
-keep intact all notices of the absence of any warranty; and give all
-recipients a copy of this License along with the Program.
-
-You may charge any price or no price for each copy that you convey,
-and you may offer support or warranty protection for a fee.
-
-@item Conveying Modified Source Versions.
-
-You may convey a work based on the Program, or the modifications to
-produce it from the Program, in the form of source code under the
-terms of section 4, provided that you also meet all of these
-conditions:
-
-@enumerate a
-@item
-The work must carry prominent notices stating that you modified it,
-and giving a relevant date.
-
-@item
-The work must carry prominent notices stating that it is released
-under this License and any conditions added under section 7. This
-requirement modifies the requirement in section 4 to ``keep intact all
-notices''.
-
-@item
-You must license the entire work, as a whole, under this License to
-anyone who comes into possession of a copy. This License will
-therefore apply, along with any applicable section 7 additional terms,
-to the whole of the work, and all its parts, regardless of how they
-are packaged. This License gives no permission to license the work in
-any other way, but it does not invalidate such permission if you have
-separately received it.
-
-@item
-If the work has interactive user interfaces, each must display
-Appropriate Legal Notices; however, if the Program has interactive
-interfaces that do not display Appropriate Legal Notices, your work
-need not make them do so.
-@end enumerate
-
-A compilation of a covered work with other separate and independent
-works, which are not by their nature extensions of the covered work,
-and which are not combined with it such as to form a larger program,
-in or on a volume of a storage or distribution medium, is called an
-``aggregate'' if the compilation and its resulting copyright are not
-used to limit the access or legal rights of the compilation's users
-beyond what the individual works permit. Inclusion of a covered work
-in an aggregate does not cause this License to apply to the other
-parts of the aggregate.
-
-@item Conveying Non-Source Forms.
-
-You may convey a covered work in object code form under the terms of
-sections 4 and 5, provided that you also convey the machine-readable
-Corresponding Source under the terms of this License, in one of these
-ways:
-
-@enumerate a
-@item
-Convey the object code in, or embodied in, a physical product
-(including a physical distribution medium), accompanied by the
-Corresponding Source fixed on a durable physical medium customarily
-used for software interchange.
-
-@item
-Convey the object code in, or embodied in, a physical product
-(including a physical distribution medium), accompanied by a written
-offer, valid for at least three years and valid for as long as you
-offer spare parts or customer support for that product model, to give
-anyone who possesses the object code either (1) a copy of the
-Corresponding Source for all the software in the product that is
-covered by this License, on a durable physical medium customarily used
-for software interchange, for a price no more than your reasonable
-cost of physically performing this conveying of source, or (2) access
-to copy the Corresponding Source from a network server at no charge.
-
-@item
-Convey individual copies of the object code with a copy of the written
-offer to provide the Corresponding Source. This alternative is
-allowed only occasionally and noncommercially, and only if you
-received the object code with such an offer, in accord with subsection
-6b.
-
-@item
-Convey the object code by offering access from a designated place
-(gratis or for a charge), and offer equivalent access to the
-Corresponding Source in the same way through the same place at no
-further charge. You need not require recipients to copy the
-Corresponding Source along with the object code. If the place to copy
-the object code is a network server, the Corresponding Source may be
-on a different server (operated by you or a third party) that supports
-equivalent copying facilities, provided you maintain clear directions
-next to the object code saying where to find the Corresponding Source.
-Regardless of what server hosts the Corresponding Source, you remain
-obligated to ensure that it is available for as long as needed to
-satisfy these requirements.
-
-@item
-Convey the object code using peer-to-peer transmission, provided you
-inform other peers where the object code and Corresponding Source of
-the work are being offered to the general public at no charge under
-subsection 6d.
-
-@end enumerate
-
-A separable portion of the object code, whose source code is excluded
-from the Corresponding Source as a System Library, need not be
-included in conveying the object code work.
-
-A ``User Product'' is either (1) a ``consumer product'', which means any
-tangible personal property which is normally used for personal,
-family, or household purposes, or (2) anything designed or sold for
-incorporation into a dwelling. In determining whether a product is a
-consumer product, doubtful cases shall be resolved in favor of
-coverage. For a particular product received by a particular user,
-``normally used'' refers to a typical or common use of that class of
-product, regardless of the status of the particular user or of the way
-in which the particular user actually uses, or expects or is expected
-to use, the product. A product is a consumer product regardless of
-whether the product has substantial commercial, industrial or
-non-consumer uses, unless such uses represent the only significant
-mode of use of the product.
-
-``Installation Information'' for a User Product means any methods,
-procedures, authorization keys, or other information required to
-install and execute modified versions of a covered work in that User
-Product from a modified version of its Corresponding Source. The
-information must suffice to ensure that the continued functioning of
-the modified object code is in no case prevented or interfered with
-solely because modification has been made.
-
-If you convey an object code work under this section in, or with, or
-specifically for use in, a User Product, and the conveying occurs as
-part of a transaction in which the right of possession and use of the
-User Product is transferred to the recipient in perpetuity or for a
-fixed term (regardless of how the transaction is characterized), the
-Corresponding Source conveyed under this section must be accompanied
-by the Installation Information. But this requirement does not apply
-if neither you nor any third party retains the ability to install
-modified object code on the User Product (for example, the work has
-been installed in ROM).
-
-The requirement to provide Installation Information does not include a
-requirement to continue to provide support service, warranty, or
-updates for a work that has been modified or installed by the
-recipient, or for the User Product in which it has been modified or
-installed. Access to a network may be denied when the modification
-itself materially and adversely affects the operation of the network
-or violates the rules and protocols for communication across the
-network.
-
-Corresponding Source conveyed, and Installation Information provided,
-in accord with this section must be in a format that is publicly
-documented (and with an implementation available to the public in
-source code form), and must require no special password or key for
-unpacking, reading or copying.
-
-@item Additional Terms.
-
-``Additional permissions'' are terms that supplement the terms of this
-License by making exceptions from one or more of its conditions.
-Additional permissions that are applicable to the entire Program shall
-be treated as though they were included in this License, to the extent
-that they are valid under applicable law. If additional permissions
-apply only to part of the Program, that part may be used separately
-under those permissions, but the entire Program remains governed by
-this License without regard to the additional permissions.
-
-When you convey a copy of a covered work, you may at your option
-remove any additional permissions from that copy, or from any part of
-it. (Additional permissions may be written to require their own
-removal in certain cases when you modify the work.) You may place
-additional permissions on material, added by you to a covered work,
-for which you have or can give appropriate copyright permission.
-
-Notwithstanding any other provision of this License, for material you
-add to a covered work, you may (if authorized by the copyright holders
-of that material) supplement the terms of this License with terms:
-
-@enumerate a
-@item
-Disclaiming warranty or limiting liability differently from the terms
-of sections 15 and 16 of this License; or
-
-@item
-Requiring preservation of specified reasonable legal notices or author
-attributions in that material or in the Appropriate Legal Notices
-displayed by works containing it; or
-
-@item
-Prohibiting misrepresentation of the origin of that material, or
-requiring that modified versions of such material be marked in
-reasonable ways as different from the original version; or
-
-@item
-Limiting the use for publicity purposes of names of licensors or
-authors of the material; or
-
-@item
-Declining to grant rights under trademark law for use of some trade
-names, trademarks, or service marks; or
-
-@item
-Requiring indemnification of licensors and authors of that material by
-anyone who conveys the material (or modified versions of it) with
-contractual assumptions of liability to the recipient, for any
-liability that these contractual assumptions directly impose on those
-licensors and authors.
-@end enumerate
-
-All other non-permissive additional terms are considered ``further
-restrictions'' within the meaning of section 10. If the Program as you
-received it, or any part of it, contains a notice stating that it is
-governed by this License along with a term that is a further
-restriction, you may remove that term. If a license document contains
-a further restriction but permits relicensing or conveying under this
-License, you may add to a covered work material governed by the terms
-of that license document, provided that the further restriction does
-not survive such relicensing or conveying.
-
-If you add terms to a covered work in accord with this section, you
-must place, in the relevant source files, a statement of the
-additional terms that apply to those files, or a notice indicating
-where to find the applicable terms.
-
-Additional terms, permissive or non-permissive, may be stated in the
-form of a separately written license, or stated as exceptions; the
-above requirements apply either way.
-
-@item Termination.
-
-You may not propagate or modify a covered work except as expressly
-provided under this License. Any attempt otherwise to propagate or
-modify it is void, and will automatically terminate your rights under
-this License (including any patent licenses granted under the third
-paragraph of section 11).
-
-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, you do not qualify to receive new licenses for the same
-material under section 10.
-
-@item Acceptance Not Required for Having Copies.
-
-You are not required to accept this License in order to receive or run
-a copy of the Program. Ancillary propagation of a covered work
-occurring solely as a consequence of using peer-to-peer transmission
-to receive a copy likewise does not require acceptance. However,
-nothing other than this License grants you permission to propagate or
-modify any covered work. These actions infringe copyright if you do
-not accept this License. Therefore, by modifying or propagating a
-covered work, you indicate your acceptance of this License to do so.
-
-@item Automatic Licensing of Downstream Recipients.
-
-Each time you convey a covered work, the recipient automatically
-receives a license from the original licensors, to run, modify and
-propagate that work, subject to this License. You are not responsible
-for enforcing compliance by third parties with this License.
-
-An ``entity transaction'' is a transaction transferring control of an
-organization, or substantially all assets of one, or subdividing an
-organization, or merging organizations. If propagation of a covered
-work results from an entity transaction, each party to that
-transaction who receives a copy of the work also receives whatever
-licenses to the work the party's predecessor in interest had or could
-give under the previous paragraph, plus a right to possession of the
-Corresponding Source of the work from the predecessor in interest, if
-the predecessor has it or can get it with reasonable efforts.
-
-You may not impose any further restrictions on the exercise of the
-rights granted or affirmed under this License. For example, you may
-not impose a license fee, royalty, or other charge for exercise of
-rights granted under this License, and you may not initiate litigation
-(including a cross-claim or counterclaim in a lawsuit) alleging that
-any patent claim is infringed by making, using, selling, offering for
-sale, or importing the Program or any portion of it.
-
-@item Patents.
-
-A ``contributor'' is a copyright holder who authorizes use under this
-License of the Program or a work on which the Program is based. The
-work thus licensed is called the contributor's ``contributor version''.
-
-A contributor's ``essential patent claims'' are all patent claims owned
-or controlled by the contributor, whether already acquired or
-hereafter acquired, that would be infringed by some manner, permitted
-by this License, of making, using, or selling its contributor version,
-but do not include claims that would be infringed only as a
-consequence of further modification of the contributor version. For
-purposes of this definition, ``control'' includes the right to grant
-patent sublicenses in a manner consistent with the requirements of
-this License.
-
-Each contributor grants you a non-exclusive, worldwide, royalty-free
-patent license under the contributor's essential patent claims, to
-make, use, sell, offer for sale, import and otherwise run, modify and
-propagate the contents of its contributor version.
-
-In the following three paragraphs, a ``patent license'' is any express
-agreement or commitment, however denominated, not to enforce a patent
-(such as an express permission to practice a patent or covenant not to
-sue for patent infringement). To ``grant'' such a patent license to a
-party means to make such an agreement or commitment not to enforce a
-patent against the party.
-
-If you convey a covered work, knowingly relying on a patent license,
-and the Corresponding Source of the work is not available for anyone
-to copy, free of charge and under the terms of this License, through a
-publicly available network server or other readily accessible means,
-then you must either (1) cause the Corresponding Source to be so
-available, or (2) arrange to deprive yourself of the benefit of the
-patent license for this particular work, or (3) arrange, in a manner
-consistent with the requirements of this License, to extend the patent
-license to downstream recipients. ``Knowingly relying'' means you have
-actual knowledge that, but for the patent license, your conveying the
-covered work in a country, or your recipient's use of the covered work
-in a country, would infringe one or more identifiable patents in that
-country that you have reason to believe are valid.
-
-If, pursuant to or in connection with a single transaction or
-arrangement, you convey, or propagate by procuring conveyance of, a
-covered work, and grant a patent license to some of the parties
-receiving the covered work authorizing them to use, propagate, modify
-or convey a specific copy of the covered work, then the patent license
-you grant is automatically extended to all recipients of the covered
-work and works based on it.
-
-A patent license is ``discriminatory'' if it does not include within the
-scope of its coverage, prohibits the exercise of, or is conditioned on
-the non-exercise of one or more of the rights that are specifically
-granted under this License. You may not convey a covered work if you
-are a party to an arrangement with a third party that is in the
-business of distributing software, under which you make payment to the
-third party based on the extent of your activity of conveying the
-work, and under which the third party grants, to any of the parties
-who would receive the covered work from you, a discriminatory patent
-license (a) in connection with copies of the covered work conveyed by
-you (or copies made from those copies), or (b) primarily for and in
-connection with specific products or compilations that contain the
-covered work, unless you entered into that arrangement, or that patent
-license was granted, prior to 28 March 2007.
-
-Nothing in this License shall be construed as excluding or limiting
-any implied license or other defenses to infringement that may
-otherwise be available to you under applicable patent law.
-
-@item No Surrender of Others' Freedom.
-
-If conditions are imposed on you (whether by court order, agreement or
-otherwise) that contradict the conditions of this License, they do not
-excuse you from the conditions of this License. If you cannot convey
-a covered work so as to satisfy simultaneously your obligations under
-this License and any other pertinent obligations, then as a
-consequence you may not convey it at all. For example, if you agree
-to terms that obligate you to collect a royalty for further conveying
-from those to whom you convey the Program, the only way you could
-satisfy both those terms and this License would be to refrain entirely
-from conveying the Program.
-
-@item Use with the GNU Affero General Public License.
-
-Notwithstanding any other provision of this License, you have
-permission to link or combine any covered work with a work licensed
-under version 3 of the GNU Affero General Public License into a single
-combined work, and to convey the resulting work. The terms of this
-License will continue to apply to the part which is the covered work,
-but the special requirements of the GNU Affero General Public License,
-section 13, concerning interaction through a network will apply to the
-combination as such.
-
-@item Revised Versions of this License.
-
-The Free Software Foundation may publish revised and/or new versions
-of the GNU General Public 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.
-
-Each version is given a distinguishing version number. If the Program
-specifies that a certain numbered version of the GNU General Public
-License ``or any later version'' applies to it, you have the option of
-following the terms and conditions either of that numbered version or
-of any later version published by the Free Software Foundation. If
-the Program does not specify a version number of the GNU General
-Public License, you may choose any version ever published by the Free
-Software Foundation.
-
-If the Program specifies that a proxy can decide which future versions
-of the GNU General Public License can be used, that proxy's public
-statement of acceptance of a version permanently authorizes you to
-choose that version for the Program.
-
-Later license versions may give you additional or different
-permissions. However, no additional obligations are imposed on any
-author or copyright holder as a result of your choosing to follow a
-later version.
-
-@item Disclaimer of Warranty.
-
-THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
-APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
-HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM ``AS IS'' WITHOUT
-WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
-LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
-A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND
-PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE
-DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR
-CORRECTION.
-
-@item Limitation of Liability.
-
-IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
-WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR
-CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
-INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES
-ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT
-NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR
-LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM
-TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER
-PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
-
-@item Interpretation of Sections 15 and 16.
-
-If the disclaimer of warranty and limitation of liability provided
-above cannot be given local legal effect according to their terms,
-reviewing courts shall apply local law that most closely approximates
-an absolute waiver of all civil liability in connection with the
-Program, unless a warranty or assumption of liability accompanies a
-copy of the Program in return for a fee.
-
-@end enumerate
-
-@heading END OF TERMS AND CONDITIONS
-
-@heading How to Apply These Terms to Your New Programs
-
-If you develop a new program, and you want it to be of the greatest
-possible use to the public, the best way to achieve this is to make it
-free software which everyone can redistribute and change under these
-terms.
-
-To do so, attach the following notices to the program. It is safest
-to attach them to the start of each source file to most effectively
-state the exclusion of warranty; and each file should have at least
-the ``copyright'' line and a pointer to where the full notice is found.
-
-@smallexample
-@var{one line to give the program's name and a brief idea of what it does.}
-Copyright (C) @var{year} @var{name of author}
-
-This program is free software: you can redistribute it and/or modify
-it under the terms of the GNU General Public License as published by
-the Free Software Foundation, either version 3 of the License, or (at
-your option) any later version.
-
-This program is distributed in the hope that it will be useful, but
-WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
-General Public License for more details.
-
-You should have received a copy of the GNU General Public License
-along with this program. If not, see @url{https://www.gnu.org/licenses/}.
-@end smallexample
-
-Also add information on how to contact you by electronic and paper mail.
-
-If the program does terminal interaction, make it output a short
-notice like this when it starts in an interactive mode:
-
-@smallexample
-@var{program} Copyright (C) @var{year} @var{name of author}
-This program comes with ABSOLUTELY NO WARRANTY; for details type @samp{show w}.
-This is free software, and you are welcome to redistribute it
-under certain conditions; type @samp{show c} for details.
-@end smallexample
-
-The hypothetical commands @samp{show w} and @samp{show c} should show
-the appropriate parts of the General Public License. Of course, your
-program's commands might be different; for a GUI interface, you would
-use an ``about box''.
-
-You should also get your employer (if you work as a programmer) or school,
-if any, to sign a ``copyright disclaimer'' for the program, if necessary.
-For more information on this, and how to apply and follow the GNU GPL, see
-@url{https://www.gnu.org/licenses/}.
-
-The GNU General Public License does not permit incorporating your
-program into proprietary programs. If your program is a subroutine
-library, you may consider it more useful to permit linking proprietary
-applications with the library. If this is what you want to do, use
-the GNU Lesser General Public License instead of this License. But
-first, please read @url{https://www.gnu.org/licenses/why-not-lgpl.html}.
-@c man end
+++ /dev/null
-\input texinfo.tex @c -*-texinfo-*-
-@c @ifnothtml
-@c %**start of header
-@setfilename gccinstall.info
-@setchapternewpage odd
-@c %**end of header
-@c @end ifnothtml
-
-@include gcc-common.texi
-
-@c Specify title for specific html page
-@ifset indexhtml
-@settitle Installing GCC
-@end ifset
-@ifset specifichtml
-@settitle Host/Target specific installation notes for GCC
-@end ifset
-@ifset prerequisiteshtml
-@settitle Prerequisites for GCC
-@end ifset
-@ifset downloadhtml
-@settitle Downloading GCC
-@end ifset
-@ifset configurehtml
-@settitle Installing GCC: Configuration
-@end ifset
-@ifset buildhtml
-@settitle Installing GCC: Building
-@end ifset
-@ifset testhtml
-@settitle Installing GCC: Testing
-@end ifset
-@ifset finalinstallhtml
-@settitle Installing GCC: Final installation
-@end ifset
-@ifset binarieshtml
-@settitle Installing GCC: Binaries
-@end ifset
-@ifset gfdlhtml
-@settitle Installing GCC: GNU Free Documentation License
-@end ifset
-
-@c Copyright (C) 1988-2022 Free Software Foundation, Inc.
-@c *** Converted to texinfo by Dean Wakerley, dean@wakerley.com
-
-@c IMPORTANT: whenever you modify this file, run `install.texi2html' to
-@c test the generation of HTML documents for the gcc.gnu.org web pages.
-@c
-@c Do not use @footnote{} in this file as it breaks install.texi2html!
-
-@c Include everything if we're not making html
-@ifnothtml
-@set indexhtml
-@set specifichtml
-@set prerequisiteshtml
-@set downloadhtml
-@set configurehtml
-@set buildhtml
-@set testhtml
-@set finalinstallhtml
-@set binarieshtml
-@set gfdlhtml
-@end ifnothtml
-
-@c Part 2 Summary Description and Copyright
-@copying
-Copyright @copyright{} 1988-2022 Free Software Foundation, Inc.
-@sp 1
-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, the Front-Cover texts being (a) (see below), and
-with the Back-Cover Texts being (b) (see below). A copy of the
-license is included in the section entitled ``@uref{./gfdl.html,,GNU
-Free Documentation License}''.
-
-(a) The FSF's Front-Cover Text is:
-
- A GNU Manual
-
-(b) The FSF's Back-Cover Text is:
-
- You have freedom to copy and modify this GNU Manual, like GNU
- software. Copies published by the Free Software Foundation raise
- funds for GNU development.
-@end copying
-@ifinfo
-@insertcopying
-@end ifinfo
-@dircategory Software development
-@direntry
-* gccinstall: (gccinstall). Installing the GNU Compiler Collection.
-@end direntry
-
-@c Part 3 Titlepage and Copyright
-@titlepage
-@title Installing GCC
-@versionsubtitle
-
-@c The following two commands start the copyright page.
-@page
-@vskip 0pt plus 1filll
-@insertcopying
-@end titlepage
-
-@c Part 4 Top node, Master Menu, and/or Table of Contents
-@ifinfo
-@node Top, , , (dir)
-@comment node-name, next, Previous, up
-
-@menu
-* Installing GCC:: This document describes the generic installation
- procedure for GCC as well as detailing some target
- specific installation instructions.
-
-* Specific:: Host/target specific installation notes for GCC.
-* Binaries:: Where to get pre-compiled binaries.
-
-* GNU Free Documentation License:: How you can copy and share this manual.
-* Concept Index:: This index has two entries.
-@end menu
-@end ifinfo
-
-@iftex
-@contents
-@end iftex
-
-@c Part 5 The Body of the Document
-@c ***Installing GCC**********************************************************
-@ifnothtml
-@comment node-name, next, previous, up
-@node Installing GCC, Binaries, , Top
-@end ifnothtml
-@ifset indexhtml
-@ifnothtml
-@chapter Installing GCC
-@end ifnothtml
-
-The latest version of this document is always available at
-@uref{https://gcc.gnu.org/install/,,https://gcc.gnu.org/install/}.
-It refers to the current development sources, instructions for
-specific released versions are included with the sources.
-
-This document describes the generic installation procedure for GCC as well
-as detailing some target specific installation instructions.
-
-GCC includes several components that previously were separate distributions
-with their own installation instructions. This document supersedes all
-package-specific installation instructions.
-
-@emph{Before} starting the build/install procedure please check the
-@ifnothtml
-@ref{Specific, host/target specific installation notes}.
-@end ifnothtml
-@ifhtml
-@uref{specific.html,,host/target specific installation notes}.
-@end ifhtml
-We recommend you browse the entire generic installation instructions before
-you proceed.
-
-Lists of successful builds for released versions of GCC are
-available at @uref{https://gcc.gnu.org/buildstat.html}.
-These lists are updated as new information becomes available.
-
-The installation procedure itself is broken into five steps.
-
-@ifinfo
-@menu
-* Prerequisites::
-* Downloading the source::
-* Configuration::
-* Building::
-* Testing:: (optional)
-* Final install::
-@end menu
-@end ifinfo
-@ifhtml
-@enumerate
-@item
-@uref{prerequisites.html,,Prerequisites}
-@item
-@uref{download.html,,Downloading the source}
-@item
-@uref{configure.html,,Configuration}
-@item
-@uref{build.html,,Building}
-@item
-@uref{test.html,,Testing} (optional)
-@item
-@uref{finalinstall.html,,Final install}
-@end enumerate
-@end ifhtml
-
-Please note that GCC does not support @samp{make uninstall} and probably
-won't do so in the near future as this would open a can of worms. Instead,
-we suggest that you install GCC into a directory of its own and simply
-remove that directory when you do not need that specific version of GCC
-any longer, and, if shared libraries are installed there as well, no
-more binaries exist that use them.
-
-@html
-<hr />
-<p>
-@end html
-@ifhtml
-@uref{./index.html,,Return to the GCC Installation page}
-
-@insertcopying
-@end ifhtml
-@end ifset
-
-@c ***Prerequisites**************************************************
-@ifnothtml
-@comment node-name, next, previous, up
-@node Prerequisites, Downloading the source, , Installing GCC
-@end ifnothtml
-@ifset prerequisiteshtml
-@ifnothtml
-@chapter Prerequisites
-@end ifnothtml
-@cindex Prerequisites
-
-GCC requires that various tools and packages be available for use in the
-build procedure. Modifying GCC sources requires additional tools
-described below.
-
-@heading Tools/packages necessary for building GCC
-@table @asis
-@item ISO C++11 compiler
-Necessary to bootstrap GCC.
-
-Versions of GCC prior to 11 also allow bootstrapping with an ISO C++98
-compiler, versions of GCC prior to 4.8 also allow bootstrapping with a
-ISO C89 compiler, and versions of GCC prior to 3.4 also allow
-bootstrapping with a traditional (K&R) C compiler.
-
-To build all languages in a cross-compiler or other configuration where
-3-stage bootstrap is not performed, you need to start with an existing
-GCC binary (version 4.8 or later) because source code for language
-frontends other than C might use GCC extensions.
-
-@item C standard library and headers
-
-In order to build GCC, the C standard library and headers must be present
-for all target variants for which target libraries will be built (and not
-only the variant of the host C++ compiler).
-
-This affects the popular @samp{x86_64-pc-linux-gnu} platform (among
-other multilib targets), for which 64-bit (@samp{x86_64}) and 32-bit
-(@samp{i386}) libc headers are usually packaged separately. If you do a
-build of a native compiler on @samp{x86_64-pc-linux-gnu}, make sure you
-either have the 32-bit libc developer package properly installed (the exact
-name of the package depends on your distro) or you must build GCC as a
-64-bit only compiler by configuring with the option
-@option{--disable-multilib}. Otherwise, you may encounter an error such as
-@samp{fatal error: gnu/stubs-32.h: No such file}
-
-@item @anchor{GNAT-prerequisite}GNAT
-
-In order to build GNAT, the Ada compiler, you need a working GNAT
-compiler (GCC version 5.1 or later).
-
-This includes GNAT tools such as @command{gnatmake} and
-@command{gnatlink}, since the Ada front end is written in Ada and
-uses some GNAT-specific extensions.
-
-In order to build a cross compiler, it is strongly recommended to install
-the new compiler as native first, and then use it to build the cross
-compiler. Other native compiler versions may work but this is not guaranteed and
-will typically fail with hard to understand compilation errors during the
-build.
-
-Similarly, it is strongly recommended to use an older version of GNAT to build
-GNAT. More recent versions of GNAT than the version built are not guaranteed
-to work and will often fail during the build with compilation errors.
-
-Note that @command{configure} does not test whether the GNAT installation works
-and has a sufficiently recent version; if too old a GNAT version is
-installed and @option{--enable-languages=ada} is used, the build will fail.
-
-@env{ADA_INCLUDE_PATH} and @env{ADA_OBJECT_PATH} environment variables
-must not be set when building the Ada compiler, the Ada tools, or the
-Ada runtime libraries. You can check that your build environment is clean
-by verifying that @samp{gnatls -v} lists only one explicit path in each
-section.
-
-@item @anchor{GDC-prerequisite}GDC
-
-In order to build GDC, the D compiler, you need a working GDC
-compiler (GCC version 9.1 or later) and D runtime library,
-@samp{libphobos}, as the D front end is written in D.
-
-Versions of GDC prior to 12 can be built with an ISO C++11 compiler, which can
-then be installed and used to bootstrap newer versions of the D front end.
-
-It is strongly recommended to use an older version of GDC to build GDC. More
-recent versions of GDC than the version built are not guaranteed to work and
-will often fail during the build with compilation errors relating to
-deprecations or removed features.
-
-Note that @command{configure} does not test whether the GDC installation works
-and has a sufficiently recent version. Though the implementation of the D
-front end does not make use of any GDC-specific extensions, or novel features
-of the D language, if too old a GDC version is installed and
-@option{--enable-languages=d} is used, the build will fail.
-
-On some targets, @samp{libphobos} isn't enabled by default, but compiles
-and works if @option{--enable-libphobos} is used. Specifics are
-documented for affected targets.
-
-@item A ``working'' POSIX compatible shell, or GNU bash
-
-Necessary when running @command{configure} because some
-@command{/bin/sh} shells have bugs and may crash when configuring the
-target libraries. In other cases, @command{/bin/sh} or @command{ksh}
-have disastrous corner-case performance problems. This
-can cause target @command{configure} runs to literally take days to
-complete in some cases.
-
-So on some platforms @command{/bin/ksh} is sufficient, on others it
-isn't. See the host/target specific instructions for your platform, or
-use @command{bash} to be sure. Then set @env{CONFIG_SHELL} in your
-environment to your ``good'' shell prior to running
-@command{configure}/@command{make}.
-
-@command{zsh} is not a fully compliant POSIX shell and will not
-work when configuring GCC@.
-
-@item A POSIX or SVR4 awk
-
-Necessary for creating some of the generated source files for GCC@.
-If in doubt, use a recent GNU awk version, as some of the older ones
-are broken. GNU awk version 3.1.5 is known to work.
-
-@item GNU binutils
-
-Necessary in some circumstances, optional in others. See the
-host/target specific instructions for your platform for the exact
-requirements.
-
-Note binutils 2.35 or newer is required for LTO to work correctly
-with GNU libtool that includes doing a bootstrap with LTO enabled.
-
-@item gzip version 1.2.4 (or later) or
-@itemx bzip2 version 1.0.2 (or later)
-
-Necessary to uncompress GCC @command{tar} files when source code is
-obtained via HTTPS mirror sites.
-
-@item GNU make version 3.80 (or later)
-
-You must have GNU make installed to build GCC@.
-
-@item GNU tar version 1.14 (or later)
-
-Necessary (only on some platforms) to untar the source code. Many
-systems' @command{tar} programs will also work, only try GNU
-@command{tar} if you have problems.
-
-@item Perl version between 5.6.1 and 5.6.24
-
-Necessary when targeting Darwin, building @samp{libstdc++},
-and not using @option{--disable-symvers}.
-Necessary when targeting Solaris 2 with Solaris @command{ld} and not using
-@option{--disable-symvers}.
-
-Necessary when regenerating @file{Makefile} dependencies in libiberty.
-Necessary when regenerating @file{libiberty/functions.texi}.
-Necessary when generating manpages from Texinfo manuals.
-Used by various scripts to generate some files included in the source
-repository (mainly Unicode-related and rarely changing) from source
-tables.
-
-Used by @command{automake}.
-
-@end table
-
-Several support libraries are necessary to build GCC, some are required,
-others optional. While any sufficiently new version of required tools
-usually work, library requirements are generally stricter. Newer
-versions may work in some cases, but it's safer to use the exact
-versions documented. We appreciate bug reports about problems with
-newer versions, though. If your OS vendor provides packages for the
-support libraries then using those packages may be the simplest way to
-install the libraries.
-
-@table @asis
-@item GNU Multiple Precision Library (GMP) version 4.3.2 (or later)
-
-Necessary to build GCC@. If a GMP source distribution is found in a
-subdirectory of your GCC sources named @file{gmp}, it will be built
-together with GCC. Alternatively, if GMP is already installed but it
-is not in your library search path, you will have to configure with the
-@option{--with-gmp} configure option. See also @option{--with-gmp-lib}
-and @option{--with-gmp-include}.
-The in-tree build is only supported with the GMP version that
-download_prerequisites installs.
-
-@item MPFR Library version 3.1.0 (or later)
-
-Necessary to build GCC@. It can be downloaded from
-@uref{https://www.mpfr.org}. If an MPFR source distribution is found
-in a subdirectory of your GCC sources named @file{mpfr}, it will be
-built together with GCC. Alternatively, if MPFR is already installed
-but it is not in your default library search path, the
-@option{--with-mpfr} configure option should be used. See also
-@option{--with-mpfr-lib} and @option{--with-mpfr-include}.
-The in-tree build is only supported with the MPFR version that
-download_prerequisites installs.
-
-@item MPC Library version 1.0.1 (or later)
-
-Necessary to build GCC@. It can be downloaded from
-@uref{https://www.multiprecision.org/mpc/}. If an MPC source distribution
-is found in a subdirectory of your GCC sources named @file{mpc}, it
-will be built together with GCC. Alternatively, if MPC is already
-installed but it is not in your default library search path, the
-@option{--with-mpc} configure option should be used. See also
-@option{--with-mpc-lib} and @option{--with-mpc-include}.
-The in-tree build is only supported with the MPC version that
-download_prerequisites installs.
-
-@item isl Library version 0.15 or later.
-
-Necessary to build GCC with the Graphite loop optimizations.
-It can be downloaded from @uref{https://gcc.gnu.org/pub/gcc/infrastructure/}.
-If an isl source distribution is found
-in a subdirectory of your GCC sources named @file{isl}, it will be
-built together with GCC. Alternatively, the @option{--with-isl} configure
-option should be used if isl is not installed in your default library
-search path.
-
-@item zstd Library.
-
-Necessary to build GCC with zstd compression used for LTO bytecode.
-The library is searched in your default library patch search.
-Alternatively, the @option{--with-zstd} configure option should be used.
-
-@end table
-
-@heading Tools/packages necessary for modifying GCC
-@table @asis
-@item autoconf version 2.69
-@itemx GNU m4 version 1.4.6 (or later)
-
-Necessary when modifying @file{configure.ac}, @file{aclocal.m4}, etc.@:
-to regenerate @file{configure} and @file{config.in} files.
-
-@item automake version 1.15.1
-
-Necessary when modifying a @file{Makefile.am} file to regenerate its
-associated @file{Makefile.in}.
-
-Much of GCC does not use automake, so directly edit the @file{Makefile.in}
-file. Specifically this applies to the @file{gcc}, @file{intl},
-@file{libcpp}, @file{libiberty}, @file{libobjc} directories as well
-as any of their subdirectories.
-
-For directories that use automake, GCC requires the latest release in
-the 1.15 series, which is currently 1.15.1. When regenerating a directory
-to a newer version, please update all the directories using an older 1.15
-to the latest released version.
-
-@item gettext version 0.14.5 (or later)
-
-Needed to regenerate @file{gcc.pot}.
-
-@item gperf version 2.7.2 (or later)
-
-Necessary when modifying @command{gperf} input files, e.g.@:
-@file{gcc/cp/cfns.gperf} to regenerate its associated header file, e.g.@:
-@file{gcc/cp/cfns.h}.
-
-@item DejaGnu version 1.5.3 (or later)
-@itemx Expect
-@itemx Tcl
-@c Once Tcl 8.5 or higher is required, remove any obsolete
-@c compatibility workarounds:
-@c git grep 'compatibility with earlier Tcl releases'
-
-Necessary to run the GCC testsuite; see the section on testing for
-details.
-
-@item autogen version 5.5.4 (or later) and
-@itemx guile version 1.4.1 (or later)
-
-Necessary to regenerate @file{fixinc/fixincl.x} from
-@file{fixinc/inclhack.def} and @file{fixinc/*.tpl}.
-
-Necessary to run @samp{make check} for @file{fixinc}.
-
-Necessary to regenerate the top level @file{Makefile.in} file from
-@file{Makefile.tpl} and @file{Makefile.def}.
-
-@item Flex version 2.5.4 (or later)
-
-Necessary when modifying @file{*.l} files.
-
-Necessary to build GCC during development because the generated output
-files are not included in the version-controlled source repository.
-They are included in releases.
-
-@item Texinfo version 4.7 (or later)
-
-Necessary for running @command{makeinfo} when modifying @file{*.texi}
-files to test your changes.
-
-Necessary for running @command{make dvi} or @command{make pdf} to
-create printable documentation in DVI or PDF format. Texinfo version
-4.8 or later is required for @command{make pdf}.
-
-Necessary to build GCC documentation during development because the
-generated output files are not included in the repository. They are
-included in releases.
-
-@item @TeX{} (any working version)
-
-Necessary for running @command{texi2dvi} and @command{texi2pdf}, which
-are used when running @command{make dvi} or @command{make pdf} to create
-DVI or PDF files, respectively.
-
-@item Sphinx version 1.0 (or later)
-
-Necessary to regenerate @file{jit/docs/_build/texinfo} from the @file{.rst}
-files in the directories below @file{jit/docs}.
-
-@item git (any version)
-@itemx SSH (any version)
-
-Necessary to access the source repository. Public releases and weekly
-snapshots of the development sources are also available via HTTPS@.
-
-@item GNU diffutils version 2.7 (or later)
-
-Useful when submitting patches for the GCC source code.
-
-@item patch version 2.5.4 (or later)
-
-Necessary when applying patches, created with @command{diff}, to one's
-own sources.
-
-@end table
-
-@html
-<hr />
-<p>
-@end html
-@ifhtml
-@uref{./index.html,,Return to the GCC Installation page}
-@end ifhtml
-@end ifset
-
-@c ***Downloading the source**************************************************
-@ifnothtml
-@comment node-name, next, previous, up
-@node Downloading the source, Configuration, Prerequisites, Installing GCC
-@end ifnothtml
-@ifset downloadhtml
-@ifnothtml
-@chapter Downloading GCC
-@end ifnothtml
-@cindex Downloading GCC
-@cindex Downloading the Source
-
-GCC is distributed via @uref{https://gcc.gnu.org/git.html,,git} and via
-HTTPS as tarballs compressed with @command{gzip} or @command{bzip2}.
-
-Please refer to the @uref{https://gcc.gnu.org/releases.html,,releases web page}
-for information on how to obtain GCC@.
-
-The source distribution includes the C, C++, Objective-C, Fortran,
-and Ada (in the case of GCC 3.1 and later) compilers, as well as
-runtime libraries for C++, Objective-C, and Fortran.
-For previous versions these were downloadable as separate components such
-as the core GCC distribution, which included the C language front end and
-shared components, and language-specific distributions including the
-language front end and the language runtime (where appropriate).
-
-If you also intend to build binutils (either to upgrade an existing
-installation or for use in place of the corresponding tools of your
-OS), unpack the binutils distribution either in the same directory or
-a separate one. In the latter case, add symbolic links to any
-components of the binutils you intend to build alongside the compiler
-(@file{bfd}, @file{binutils}, @file{gas}, @file{gprof}, @file{ld},
-@file{opcodes}, @dots{}) to the directory containing the GCC sources.
-
-Likewise the GMP, MPFR and MPC libraries can be automatically built
-together with GCC. You may simply run the
-@command{contrib/download_prerequisites} script in the GCC source directory
-to set up everything.
-Otherwise unpack the GMP, MPFR and/or MPC source
-distributions in the directory containing the GCC sources and rename
-their directories to @file{gmp}, @file{mpfr} and @file{mpc},
-respectively (or use symbolic links with the same name).
-
-@html
-<hr />
-<p>
-@end html
-@ifhtml
-@uref{./index.html,,Return to the GCC Installation page}
-@end ifhtml
-@end ifset
-
-@c ***Configuration***********************************************************
-@ifnothtml
-@comment node-name, next, previous, up
-@node Configuration, Building, Downloading the source, Installing GCC
-@end ifnothtml
-@ifset configurehtml
-@ifnothtml
-@chapter Installing GCC: Configuration
-@end ifnothtml
-@cindex Configuration
-@cindex Installing GCC: Configuration
-
-Like most GNU software, GCC must be configured before it can be built.
-This document describes the recommended configuration procedure
-for both native and cross targets.
-
-We use @var{srcdir} to refer to the toplevel source directory for
-GCC; we use @var{objdir} to refer to the toplevel build/object directory.
-
-If you obtained the sources by cloning the repository, @var{srcdir}
-must refer to the top @file{gcc} directory, the one where the
-@file{MAINTAINERS} file can be found, and not its @file{gcc}
-subdirectory, otherwise the build will fail.
-
-If either @var{srcdir} or @var{objdir} is located on an automounted NFS
-file system, the shell's built-in @command{pwd} command will return
-temporary pathnames. Using these can lead to various sorts of build
-problems. To avoid this issue, set the @env{PWDCMD} environment
-variable to an automounter-aware @command{pwd} command, e.g.,
-@command{pawd} or @samp{amq -w}, during the configuration and build
-phases.
-
-First, we @strong{highly} recommend that GCC be built into a
-separate directory from the sources which does @strong{not} reside
-within the source tree. This is how we generally build GCC; building
-where @var{srcdir} == @var{objdir} should still work, but doesn't
-get extensive testing; building where @var{objdir} is a subdirectory
-of @var{srcdir} is unsupported.
-
-If you have previously built GCC in the same directory for a
-different target machine, do @samp{make distclean} to delete all files
-that might be invalid. One of the files this deletes is @file{Makefile};
-if @samp{make distclean} complains that @file{Makefile} does not exist
-or issues a message like ``don't know how to make distclean'' it probably
-means that the directory is already suitably clean. However, with the
-recommended method of building in a separate @var{objdir}, you should
-simply use a different @var{objdir} for each target.
-
-Second, when configuring a native system, either @command{cc} or
-@command{gcc} must be in your path or you must set @env{CC} in
-your environment before running configure. Otherwise the configuration
-scripts may fail.
-
-@ignore
-Note that the bootstrap compiler and the resulting GCC must be link
-compatible, else the bootstrap will fail with linker errors about
-incompatible object file formats. Several multilibed targets are
-affected by this requirement, see
-@ifnothtml
-@ref{Specific, host/target specific installation notes}.
-@end ifnothtml
-@ifhtml
-@uref{specific.html,,host/target specific installation notes}.
-@end ifhtml
-@end ignore
-
-To configure GCC:
-
-@smallexample
-% mkdir @var{objdir}
-% cd @var{objdir}
-% @var{srcdir}/configure [@var{options}] [@var{target}]
-@end smallexample
-
-@heading Distributor options
-
-If you will be distributing binary versions of GCC, with modifications
-to the source code, you should use the options described in this
-section to make clear that your version contains modifications.
-
-@table @code
-@item --with-pkgversion=@var{version}
-Specify a string that identifies your package. You may wish
-to include a build number or build date. This version string will be
-included in the output of @command{gcc --version}. This suffix does
-not replace the default version string, only the @samp{GCC} part.
-
-The default value is @samp{GCC}.
-
-@item --with-bugurl=@var{url}
-Specify the URL that users should visit if they wish to report a bug.
-You are of course welcome to forward bugs reported to you to the FSF,
-if you determine that they are not bugs in your modifications.
-
-The default value refers to the FSF's GCC bug tracker.
-
-@item --with-documentation-root-url=@var{url}
-Specify the URL root that contains GCC option documentation. The @var{url}
-should end with a @code{/} character.
-
-The default value is @uref{https://gcc.gnu.org/onlinedocs/,,https://gcc.gnu.org/onlinedocs/}.
-
-@item --with-changes-root-url=@var{url}
-Specify the URL root that contains information about changes in GCC
-releases like @code{gcc-@var{version}/changes.html}.
-The @var{url} should end with a @code{/} character.
-
-The default value is @uref{https://gcc.gnu.org/,,https://gcc.gnu.org/}.
-
-@end table
-
-@heading Host, Build and Target specification
-
-Specify the host, build and target machine configurations. You do this
-when you run the @file{configure} script.
-
-The @dfn{build} machine is the system which you are using, the
-@dfn{host} machine is the system where you want to run the resulting
-compiler (normally the build machine), and the @dfn{target} machine is
-the system for which you want the compiler to generate code.
-
-If you are building a compiler to produce code for the machine it runs
-on (a native compiler), you normally do not need to specify any operands
-to @file{configure}; it will try to guess the type of machine you are on
-and use that as the build, host and target machines. So you don't need
-to specify a configuration when building a native compiler unless
-@file{configure} cannot figure out what your configuration is or guesses
-wrong.
-
-In those cases, specify the build machine's @dfn{configuration name}
-with the @option{--host} option; the host and target will default to be
-the same as the host machine.
-
-Here is an example:
-
-@smallexample
-./configure --host=x86_64-pc-linux-gnu
-@end smallexample
-
-A configuration name may be canonical or it may be more or less
-abbreviated (@file{config.sub} script produces canonical versions).
-
-A canonical configuration name has three parts, separated by dashes.
-It looks like this: @samp{@var{cpu}-@var{company}-@var{system}}.
-
-Here are the possible CPU types:
-
-@quotation
-aarch64, aarch64_be, alpha, alpha64, amdgcn, arc, arceb, arm, armeb, avr, bfin,
-bpf, cris, csky, epiphany, fido, fr30, frv, ft32, h8300, hppa, hppa2.0,
-hppa64, i486, i686, ia64, iq2000, lm32, loongarch64, m32c, m32r, m32rle, m68k,
-mcore, microblaze, microblazeel, mips, mips64, mips64el, mips64octeon,
-mips64orion, mips64vr, mipsel, mipsisa32, mipsisa32r2, mipsisa64, mipsisa64r2,
-mipsisa64r2el, mipsisa64sb1, mipsisa64sr71k, mipstx39, mmix, mn10300, moxie,
-msp430, nds32be, nds32le, nios2, nvptx, or1k, pdp11, powerpc, powerpc64,
-powerpc64le, powerpcle, pru, riscv32, riscv32be, riscv64, riscv64be, rl78, rx,
-s390, s390x, sh, shle, sparc, sparc64, tic6x, v850,
-v850e, v850e1, vax, visium, x86_64, xstormy16, xtensa
-@end quotation
-
-Here is a list of system types:
-
-@quotation
-aix@var{version}, amdhsa, aout, cygwin, darwin@var{version},
-eabi, eabialtivec, eabisim, eabisimaltivec, elf, elf32,
-elfbare, elfoabi, freebsd@var{version}, gnu, hpux, hpux@var{version},
-kfreebsd-gnu, kopensolaris-gnu, linux-androideabi, linux-gnu,
-linux-gnu_altivec, linux-musl, linux-uclibc, lynxos, mingw32, mingw32crt,
-mmixware, msdosdjgpp, netbsd, netbsdelf@var{version}, nto-qnx, openbsd,
-rtems, solaris@var{version}, symbianelf, tpf, uclinux, uclinux_eabi, vms,
-vxworks, vxworksae, vxworksmils
-@end quotation
-
-@heading Options specification
-
-Use @var{options} to override several configure time options for
-GCC@. A list of supported @var{options} follows; @samp{configure
---help} may list other options, but those not listed below may not
-work and should not normally be used.
-
-Note that each @option{--enable} option has a corresponding
-@option{--disable} option and that each @option{--with} option has a
-corresponding @option{--without} option.
-
-@table @code
-@item --prefix=@var{dirname}
-Specify the toplevel installation
-directory. This is the recommended way to install the tools into a directory
-other than the default. The toplevel installation directory defaults to
-@file{/usr/local}.
-
-We @strong{highly} recommend against @var{dirname} being the same or a
-subdirectory of @var{objdir} or vice versa. If specifying a directory
-beneath a user's home directory tree, some shells will not expand
-@var{dirname} correctly if it contains the @samp{~} metacharacter; use
-@env{$HOME} instead.
-
-The following standard @command{autoconf} options are supported. Normally you
-should not need to use these options.
-@table @code
-@item --exec-prefix=@var{dirname}
-Specify the toplevel installation directory for architecture-dependent
-files. The default is @file{@var{prefix}}.
-
-@item --bindir=@var{dirname}
-Specify the installation directory for the executables called by users
-(such as @command{gcc} and @command{g++}). The default is
-@file{@var{exec-prefix}/bin}.
-
-@item --libdir=@var{dirname}
-Specify the installation directory for object code libraries and
-internal data files of GCC@. The default is @file{@var{exec-prefix}/lib}.
-
-@item --libexecdir=@var{dirname}
-Specify the installation directory for internal executables of GCC@.
-The default is @file{@var{exec-prefix}/libexec}.
-
-@item --with-slibdir=@var{dirname}
-Specify the installation directory for the shared libgcc library. The
-default is @file{@var{libdir}}.
-
-@item --datarootdir=@var{dirname}
-Specify the root of the directory tree for read-only architecture-independent
-data files referenced by GCC@. The default is @file{@var{prefix}/share}.
-
-@item --infodir=@var{dirname}
-Specify the installation directory for documentation in info format.
-The default is @file{@var{datarootdir}/info}.
-
-@item --datadir=@var{dirname}
-Specify the installation directory for some architecture-independent
-data files referenced by GCC@. The default is @file{@var{datarootdir}}.
-
-@item --docdir=@var{dirname}
-Specify the installation directory for documentation files (other
-than Info) for GCC@. The default is @file{@var{datarootdir}/doc}.
-
-@item --htmldir=@var{dirname}
-Specify the installation directory for HTML documentation files.
-The default is @file{@var{docdir}}.
-
-@item --pdfdir=@var{dirname}
-Specify the installation directory for PDF documentation files.
-The default is @file{@var{docdir}}.
-
-@item --mandir=@var{dirname}
-Specify the installation directory for manual pages. The default is
-@file{@var{datarootdir}/man}. (Note that the manual pages are only extracts
-from the full GCC manuals, which are provided in Texinfo format. The manpages
-are derived by an automatic conversion process from parts of the full
-manual.)
-
-@item --with-gxx-include-dir=@var{dirname}
-Specify
-the installation directory for G++ header files. The default depends
-on other configuration options, and differs between cross and native
-configurations.
-
-@item --with-specs=@var{specs}
-Specify additional command line driver SPECS.
-This can be useful if you need to turn on a non-standard feature by
-default without modifying the compiler's source code, for instance
-@option{--with-specs=%@{!fcommon:%@{!fno-common:-fno-common@}@}}.
-@ifnothtml
-@xref{Spec Files,, Specifying subprocesses and the switches to pass to them,
-gcc, Using the GNU Compiler Collection (GCC)},
-@end ifnothtml
-@ifhtml
-See ``Spec Files'' in the main manual
-@end ifhtml
-
-@end table
-
-@item --program-prefix=@var{prefix}
-GCC supports some transformations of the names of its programs when
-installing them. This option prepends @var{prefix} to the names of
-programs to install in @var{bindir} (see above). For example, specifying
-@option{--program-prefix=foo-} would result in @samp{gcc}
-being installed as @file{/usr/local/bin/foo-gcc}.
-
-@item --program-suffix=@var{suffix}
-Appends @var{suffix} to the names of programs to install in @var{bindir}
-(see above). For example, specifying @option{--program-suffix=-3.1}
-would result in @samp{gcc} being installed as
-@file{/usr/local/bin/gcc-3.1}.
-
-@item --program-transform-name=@var{pattern}
-Applies the @samp{sed} script @var{pattern} to be applied to the names
-of programs to install in @var{bindir} (see above). @var{pattern} has to
-consist of one or more basic @samp{sed} editing commands, separated by
-semicolons. For example, if you want the @samp{gcc} program name to be
-transformed to the installed program @file{/usr/local/bin/myowngcc} and
-the @samp{g++} program name to be transformed to
-@file{/usr/local/bin/gspecial++} without changing other program names,
-you could use the pattern
-@option{--program-transform-name='s/^gcc$/myowngcc/; s/^g++$/gspecial++/'}
-to achieve this effect.
-
-All three options can be combined and used together, resulting in more
-complex conversion patterns. As a basic rule, @var{prefix} (and
-@var{suffix}) are prepended (appended) before further transformations
-can happen with a special transformation script @var{pattern}.
-
-As currently implemented, this option only takes effect for native
-builds; cross compiler binaries' names are not transformed even when a
-transformation is explicitly asked for by one of these options.
-
-For native builds, some of the installed programs are also installed
-with the target alias in front of their name, as in
-@samp{i686-pc-linux-gnu-gcc}. All of the above transformations happen
-before the target alias is prepended to the name---so, specifying
-@option{--program-prefix=foo-} and @option{program-suffix=-3.1}, the
-resulting binary would be installed as
-@file{/usr/local/bin/i686-pc-linux-gnu-foo-gcc-3.1}.
-
-As a last shortcoming, none of the installed Ada programs are
-transformed yet, which will be fixed in some time.
-
-@item --with-local-prefix=@var{dirname}
-Specify the
-installation directory for local include files. The default is
-@file{/usr/local}. Specify this option if you want the compiler to
-search directory @file{@var{dirname}/include} for locally installed
-header files @emph{instead} of @file{/usr/local/include}.
-
-You should specify @option{--with-local-prefix} @strong{only} if your
-site has a different convention (not @file{/usr/local}) for where to put
-site-specific files.
-
-The default value for @option{--with-local-prefix} is @file{/usr/local}
-regardless of the value of @option{--prefix}. Specifying
-@option{--prefix} has no effect on which directory GCC searches for
-local header files. This may seem counterintuitive, but actually it is
-logical.
-
-The purpose of @option{--prefix} is to specify where to @emph{install
-GCC}. The local header files in @file{/usr/local/include}---if you put
-any in that directory---are not part of GCC@. They are part of other
-programs---perhaps many others. (GCC installs its own header files in
-another directory which is based on the @option{--prefix} value.)
-
-Both the local-prefix include directory and the GCC-prefix include
-directory are part of GCC's ``system include'' directories. Although these
-two directories are not fixed, they need to be searched in the proper
-order for the correct processing of the include_next directive. The
-local-prefix include directory is searched before the GCC-prefix
-include directory. Another characteristic of system include directories
-is that pedantic warnings are turned off for headers in these directories.
-
-Some autoconf macros add @option{-I @var{directory}} options to the
-compiler command line, to ensure that directories containing installed
-packages' headers are searched. When @var{directory} is one of GCC's
-system include directories, GCC will ignore the option so that system
-directories continue to be processed in the correct order. This
-may result in a search order different from what was specified but the
-directory will still be searched.
-
-GCC automatically searches for ordinary libraries using
-@env{GCC_EXEC_PREFIX}. Thus, when the same installation prefix is
-used for both GCC and packages, GCC will automatically search for
-both headers and libraries. This provides a configuration that is
-easy to use. GCC behaves in a manner similar to that when it is
-installed as a system compiler in @file{/usr}.
-
-Sites that need to install multiple versions of GCC may not want to
-use the above simple configuration. It is possible to use the
-@option{--program-prefix}, @option{--program-suffix} and
-@option{--program-transform-name} options to install multiple versions
-into a single directory, but it may be simpler to use different prefixes
-and the @option{--with-local-prefix} option to specify the location of the
-site-specific files for each version. It will then be necessary for
-users to specify explicitly the location of local site libraries
-(e.g., with @env{LIBRARY_PATH}).
-
-The same value can be used for both @option{--with-local-prefix} and
-@option{--prefix} provided it is not @file{/usr}. This can be used
-to avoid the default search of @file{/usr/local/include}.
-
-@strong{Do not} specify @file{/usr} as the @option{--with-local-prefix}!
-The directory you use for @option{--with-local-prefix} @strong{must not}
-contain any of the system's standard header files. If it did contain
-them, certain programs would be miscompiled (including GNU Emacs, on
-certain targets), because this would override and nullify the header
-file corrections made by the @command{fixincludes} script.
-
-Indications are that people who use this option use it based on mistaken
-ideas of what it is for. People use it as if it specified where to
-install part of GCC@. Perhaps they make this assumption because
-installing GCC creates the directory.
-
-@item --with-gcc-major-version-only
-Specifies that GCC should use only the major number rather than
-@var{major}.@var{minor}.@var{patchlevel} in filesystem paths.
-
-@item --with-native-system-header-dir=@var{dirname}
-Specifies that @var{dirname} is the directory that contains native system
-header files, rather than @file{/usr/include}. This option is most useful
-if you are creating a compiler that should be isolated from the system
-as much as possible. It is most commonly used with the
-@option{--with-sysroot} option and will cause GCC to search
-@var{dirname} inside the system root specified by that option.
-
-@item --enable-shared[=@var{package}[,@dots{}]]
-Build shared versions of libraries, if shared libraries are supported on
-the target platform. Unlike GCC 2.95.x and earlier, shared libraries
-are enabled by default on all platforms that support shared libraries.
-
-If a list of packages is given as an argument, build shared libraries
-only for the listed packages. For other packages, only static libraries
-will be built. Package names currently recognized in the GCC tree are
-@samp{libgcc} (also known as @samp{gcc}), @samp{libstdc++} (not
-@samp{libstdc++-v3}), @samp{libffi}, @samp{zlib}, @samp{boehm-gc},
-@samp{ada}, @samp{libada}, @samp{libgo}, @samp{libobjc}, and @samp{libphobos}.
-Note @samp{libiberty} does not support shared libraries at all.
-
-Use @option{--disable-shared} to build only static libraries. Note that
-@option{--disable-shared} does not accept a list of package names as
-argument, only @option{--enable-shared} does.
-
-Contrast with @option{--enable-host-shared}, which affects @emph{host}
-code.
-
-@item --enable-host-shared
-Specify that the @emph{host} code should be built into position-independent
-machine code (with -fPIC), allowing it to be used within shared libraries,
-but yielding a slightly slower compiler.
-
-This option is required when building the libgccjit.so library.
-
-Contrast with @option{--enable-shared}, which affects @emph{target}
-libraries.
-
-@item @anchor{with-gnu-as}--with-gnu-as
-Specify that the compiler should assume that the
-assembler it finds is the GNU assembler. However, this does not modify
-the rules to find an assembler and will result in confusion if the
-assembler found is not actually the GNU assembler. (Confusion may also
-result if the compiler finds the GNU assembler but has not been
-configured with @option{--with-gnu-as}.) If you have more than one
-assembler installed on your system, you may want to use this option in
-connection with @option{--with-as=@var{pathname}} or
-@option{--with-build-time-tools=@var{pathname}}.
-
-The following systems are the only ones where it makes a difference
-whether you use the GNU assembler. On any other system,
-@option{--with-gnu-as} has no effect.
-
-@itemize @bullet
-@item @samp{hppa1.0-@var{any}-@var{any}}
-@item @samp{hppa1.1-@var{any}-@var{any}}
-@item @samp{sparc-sun-solaris2.@var{any}}
-@item @samp{sparc64-@var{any}-solaris2.@var{any}}
-@end itemize
-
-@item @anchor{with-as}--with-as=@var{pathname}
-Specify that the compiler should use the assembler pointed to by
-@var{pathname}, rather than the one found by the standard rules to find
-an assembler, which are:
-@itemize @bullet
-@item
-Unless GCC is being built with a cross compiler, check the
-@file{@var{libexec}/gcc/@var{target}/@var{version}} directory.
-@var{libexec} defaults to @file{@var{exec-prefix}/libexec};
-@var{exec-prefix} defaults to @var{prefix}, which
-defaults to @file{/usr/local} unless overridden by the
-@option{--prefix=@var{pathname}} switch described above. @var{target}
-is the target system triple, such as @samp{sparc-sun-solaris2.7}, and
-@var{version} denotes the GCC version, such as 3.0.
-
-@item
-If the target system is the same that you are building on, check
-operating system specific directories (e.g.@: @file{/usr/ccs/bin} on
-Solaris 2).
-
-@item
-Check in the @env{PATH} for a tool whose name is prefixed by the
-target system triple.
-
-@item
-Check in the @env{PATH} for a tool whose name is not prefixed by the
-target system triple, if the host and target system triple are
-the same (in other words, we use a host tool if it can be used for
-the target as well).
-@end itemize
-
-You may want to use @option{--with-as} if no assembler
-is installed in the directories listed above, or if you have multiple
-assemblers installed and want to choose one that is not found by the
-above rules.
-
-@item @anchor{with-gnu-ld}--with-gnu-ld
-Same as @uref{#with-gnu-as,,@option{--with-gnu-as}}
-but for the linker.
-
-@item --with-ld=@var{pathname}
-Same as @uref{#with-as,,@option{--with-as}}
-but for the linker.
-
-@item --with-dsymutil=@var{pathname}
-Same as @uref{#with-as,,@option{--with-as}}
-but for the debug linker (only used on Darwin platforms so far).
-
-@item --with-tls=@var{dialect}
-Specify the default TLS dialect, for systems were there is a choice.
-For ARM targets, possible values for @var{dialect} are @code{gnu} or
-@code{gnu2}, which select between the original GNU dialect and the GNU TLS
-descriptor-based dialect.
-
-@item --enable-multiarch
-Specify whether to enable or disable multiarch support. The default is
-to check for glibc start files in a multiarch location, and enable it
-if the files are found. The auto detection is enabled for native builds,
-and for cross builds configured with @option{--with-sysroot}, and without
-@option{--with-native-system-header-dir}.
-More documentation about multiarch can be found at
-@uref{https://wiki.debian.org/Multiarch}.
-
-@item --enable-sjlj-exceptions
-Force use of the @code{setjmp}/@code{longjmp}-based scheme for exceptions.
-@samp{configure} ordinarily picks the correct value based on the platform.
-Only use this option if you are sure you need a different setting.
-
-@item --enable-vtable-verify
-Specify whether to enable or disable the vtable verification feature.
-Enabling this feature causes libstdc++ to be built with its virtual calls
-in verifiable mode. This means that, when linked with libvtv, every
-virtual call in libstdc++ will verify the vtable pointer through which the
-call will be made before actually making the call. If not linked with libvtv,
-the verifier will call stub functions (in libstdc++ itself) and do nothing.
-If vtable verification is disabled, then libstdc++ is not built with its
-virtual calls in verifiable mode at all. However the libvtv library will
-still be built (see @option{--disable-libvtv} to turn off building libvtv).
-@option{--disable-vtable-verify} is the default.
-
-@item --disable-gcov
-Specify that the run-time library used for coverage analysis
-and associated host tools should not be built.
-
-@item --disable-multilib
-Specify that multiple target
-libraries to support different target variants, calling
-conventions, etc.@: should not be built. The default is to build a
-predefined set of them.
-
-Some targets provide finer-grained control over which multilibs are built
-(e.g., @option{--disable-softfloat}):
-@table @code
-@item arm-*-*
-fpu, 26bit, underscore, interwork, biendian, nofmult.
-
-@item m68*-*-*
-softfloat, m68881, m68000, m68020.
-
-@item mips*-*-*
-single-float, biendian, softfloat.
-
-@item msp430-*-*
-no-exceptions
-
-@item powerpc*-*-*, rs6000*-*-*
-aix64, pthread, softfloat, powercpu, powerpccpu, powerpcos, biendian,
-sysv, aix.
-
-@end table
-
-@item --with-multilib-list=@var{list}
-@itemx --without-multilib-list
-Specify what multilibs to build. @var{list} is a comma separated list of
-values, possibly consisting of a single value. Currently only implemented
-for aarch64*-*-*, arm*-*-*, loongarch64-*-*, riscv*-*-*, sh*-*-* and
-x86-64-*-linux*. The accepted values and meaning for each target is given
-below.
-
-@table @code
-@item aarch64*-*-*
-@var{list} is a comma separated list of @code{ilp32}, and @code{lp64}
-to enable ILP32 and LP64 run-time libraries, respectively. If
-@var{list} is empty, then there will be no multilibs and only the
-default run-time library will be built. If @var{list} is
-@code{default} or --with-multilib-list= is not specified, then the
-default set of libraries is selected based on the value of
-@option{--target}.
-
-@item arm*-*-*
-@var{list} is a comma separated list of @code{aprofile} and
-@code{rmprofile} to build multilibs for A or R and M architecture
-profiles respectively. Note that, due to some limitation of the current
-multilib framework, using the combined @code{aprofile,rmprofile}
-multilibs selects in some cases a less optimal multilib than when using
-the multilib profile for the architecture targetted. The special value
-@code{default} is also accepted and is equivalent to omitting the
-option, i.e., only the default run-time library will be enabled.
-
-@var{list} may instead contain @code{@@name}, to use the multilib
-configuration Makefile fragment @file{name} in @file{gcc/config/arm} in
-the source tree (it is part of the corresponding sources, after all).
-It is recommended, but not required, that files used for this purpose to
-be named starting with @file{t-ml-}, to make their intended purpose
-self-evident, in line with GCC conventions. Such files enable custom,
-user-chosen multilib lists to be configured. Whether multiple such
-files can be used together depends on the contents of the supplied
-files. See @file{gcc/config/arm/t-multilib} and its supplementary
-@file{gcc/config/arm/t-*profile} files for an example of what such
-Makefile fragments might look like for this version of GCC. The macros
-expected to be defined in these fragments are not stable across GCC
-releases, so make sure they define the @code{MULTILIB}-related macros
-expected by the version of GCC you are building.
-@ifnothtml
-@xref{Target Fragment,, Target Makefile Fragments, gccint, GNU Compiler
-Collection (GCC) Internals}.
-@end ifnothtml
-@ifhtml
-See ``Target Makefile Fragments'' in the internals manual.
-@end ifhtml
-
-The table below gives the combination of ISAs, architectures, FPUs and
-floating-point ABIs for which multilibs are built for each predefined
-profile. The union of these options is considered when specifying both
-@code{aprofile} and @code{rmprofile}.
-
-@multitable @columnfractions .15 .28 .30
-@item Option @tab aprofile @tab rmprofile
-@item ISAs
-@tab @code{-marm} and @code{-mthumb}
-@tab @code{-mthumb}
-@item Architectures@*@*@*@*@*@*
-@tab default architecture@*
-@code{-march=armv7-a}@*
-@code{-march=armv7ve}@*
-@code{-march=armv8-a}@*@*@*
-@tab default architecture@*
-@code{-march=armv6s-m}@*
-@code{-march=armv7-m}@*
-@code{-march=armv7e-m}@*
-@code{-march=armv8-m.base}@*
-@code{-march=armv8-m.main}@*
-@code{-march=armv7}
-@item FPUs@*@*@*@*@*
-@tab none@*
-@code{-mfpu=vfpv3-d16}@*
-@code{-mfpu=neon}@*
-@code{-mfpu=vfpv4-d16}@*
-@code{-mfpu=neon-vfpv4}@*
-@code{-mfpu=neon-fp-armv8}
-@tab none@*
-@code{-mfpu=vfpv3-d16}@*
-@code{-mfpu=fpv4-sp-d16}@*
-@code{-mfpu=fpv5-sp-d16}@*
-@code{-mfpu=fpv5-d16}@*
-@item floating-point@/ ABIs@*@*
-@tab @code{-mfloat-abi=soft}@*
-@code{-mfloat-abi=softfp}@*
-@code{-mfloat-abi=hard}
-@tab @code{-mfloat-abi=soft}@*
-@code{-mfloat-abi=softfp}@*
-@code{-mfloat-abi=hard}
-@end multitable
-
-@item loongarch*-*-*
-@var{list} is a comma-separated list of the following ABI identifiers:
-@code{lp64d[/base]} @code{lp64f[/base]} @code{lp64d[/base]}, where the
-@code{/base} suffix may be omitted, to enable their respective run-time
-libraries. If @var{list} is empty or @code{default},
-or if @option{--with-multilib-list} is not specified, then the default ABI
-as specified by @option{--with-abi} or implied by @option{--target} is selected.
-
-@item riscv*-*-*
-@var{list} is a single ABI name. The target architecture must be either
-@code{rv32gc} or @code{rv64gc}. This will build a single multilib for the
-specified architecture and ABI pair. If @code{--with-multilib-list} is not
-given, then a default set of multilibs is selected based on the value of
-@option{--target}. This is usually a large set of multilibs.
-
-@item sh*-*-*
-@var{list} is a comma separated list of CPU names. These must be of the
-form @code{sh*} or @code{m*} (in which case they match the compiler option
-for that processor). The list should not contain any endian options -
-these are handled by @option{--with-endian}.
-
-If @var{list} is empty, then there will be no multilibs for extra
-processors. The multilib for the secondary endian remains enabled.
-
-As a special case, if an entry in the list starts with a @code{!}
-(exclamation point), then it is added to the list of excluded multilibs.
-Entries of this sort should be compatible with @samp{MULTILIB_EXCLUDES}
-(once the leading @code{!} has been stripped).
-
-If @option{--with-multilib-list} is not given, then a default set of
-multilibs is selected based on the value of @option{--target}. This is
-usually the complete set of libraries, but some targets imply a more
-specialized subset.
-
-Example 1: to configure a compiler for SH4A only, but supporting both
-endians, with little endian being the default:
-@smallexample
---with-cpu=sh4a --with-endian=little,big --with-multilib-list=
-@end smallexample
-
-Example 2: to configure a compiler for both SH4A and SH4AL-DSP, but with
-only little endian SH4AL:
-@smallexample
---with-cpu=sh4a --with-endian=little,big \
---with-multilib-list=sh4al,!mb/m4al
-@end smallexample
-
-@item x86-64-*-linux*
-@var{list} is a comma separated list of @code{m32}, @code{m64} and
-@code{mx32} to enable 32-bit, 64-bit and x32 run-time libraries,
-respectively. If @var{list} is empty, then there will be no multilibs
-and only the default run-time library will be enabled.
-
-If @option{--with-multilib-list} is not given, then only 32-bit and
-64-bit run-time libraries will be enabled.
-@end table
-
-@item --with-multilib-generator=@var{config}
-Specify what multilibs to build. @var{config} is a semicolon separated list of
-values, possibly consisting of a single value. Currently only implemented
-for riscv*-*-elf*. The accepted values and meanings are given below.
-
-
-Every config is constructed with four components: architecture string, ABI,
-reuse rule with architecture string and reuse rule with sub-extension.
-
-Example 1: Add multi-lib suppport for rv32i with ilp32.
-@smallexample
-rv32i-ilp32--
-@end smallexample
-
-Example 2: Add multi-lib suppport for rv32i with ilp32 and rv32imafd with ilp32.
-@smallexample
-rv32i-ilp32--;rv32imafd-ilp32--
-@end smallexample
-
-Example 3: Add multi-lib suppport for rv32i with ilp32; rv32im with ilp32 and
-rv32ic with ilp32 will reuse this multi-lib set.
-@smallexample
-rv32i-ilp32-rv32im-c
-@end smallexample
-
-Example 4: Add multi-lib suppport for rv64ima with lp64; rv64imaf with lp64,
-rv64imac with lp64 and rv64imafc with lp64 will reuse this multi-lib set.
-@smallexample
-rv64ima-lp64--f,c,fc
-@end smallexample
-
-@option{--with-multilib-generator} have an optional configuration argument
-@option{--cmodel=val} for code model, this option will expand with other
-config options, @var{val} is a comma separated list of possible code model,
-currently we support medlow and medany.
-
-Example 5: Add multi-lib suppport for rv64ima with lp64; rv64ima with lp64 and
-medlow code model
-@smallexample
-rv64ima-lp64--;--cmodel=medlow
-@end smallexample
-
-Example 6: Add multi-lib suppport for rv64ima with lp64; rv64ima with lp64 and
-medlow code model; rv64ima with lp64 and medany code model
-@smallexample
-rv64ima-lp64--;--cmodel=medlow,medany
-@end smallexample
-
-@item --with-endian=@var{endians}
-Specify what endians to use.
-Currently only implemented for sh*-*-*.
-
-@var{endians} may be one of the following:
-@table @code
-@item big
-Use big endian exclusively.
-@item little
-Use little endian exclusively.
-@item big,little
-Use big endian by default. Provide a multilib for little endian.
-@item little,big
-Use little endian by default. Provide a multilib for big endian.
-@end table
-
-@item --enable-threads
-Specify that the target
-supports threads. This affects the Objective-C compiler and runtime
-library, and exception handling for other languages like C++.
-On some systems, this is the default.
-
-In general, the best (and, in many cases, the only known) threading
-model available will be configured for use. Beware that on some
-systems, GCC has not been taught what threading models are generally
-available for the system. In this case, @option{--enable-threads} is an
-alias for @option{--enable-threads=single}.
-
-@item --disable-threads
-Specify that threading support should be disabled for the system.
-This is an alias for @option{--enable-threads=single}.
-
-@item --enable-threads=@var{lib}
-Specify that
-@var{lib} is the thread support library. This affects the Objective-C
-compiler and runtime library, and exception handling for other languages
-like C++. The possibilities for @var{lib} are:
-
-@table @code
-@item aix
-AIX thread support.
-@item dce
-DCE thread support.
-@item lynx
-LynxOS thread support.
-@item mipssde
-MIPS SDE thread support.
-@item no
-This is an alias for @samp{single}.
-@item posix
-Generic POSIX/Unix98 thread support.
-@item rtems
-RTEMS thread support.
-@item single
-Disable thread support, should work for all platforms.
-@item tpf
-TPF thread support.
-@item vxworks
-VxWorks thread support.
-@item win32
-Microsoft Win32 API thread support.
-@end table
-
-@item --enable-tls
-Specify that the target supports TLS (Thread Local Storage). Usually
-configure can correctly determine if TLS is supported. In cases where
-it guesses incorrectly, TLS can be explicitly enabled or disabled with
-@option{--enable-tls} or @option{--disable-tls}. This can happen if
-the assembler supports TLS but the C library does not, or if the
-assumptions made by the configure test are incorrect.
-
-@item --disable-tls
-Specify that the target does not support TLS.
-This is an alias for @option{--enable-tls=no}.
-
-@item --disable-tm-clone-registry
-Disable TM clone registry in libgcc. It is enabled in libgcc by default.
-This option helps to reduce code size for embedded targets which do
-not use transactional memory.
-
-@item --with-cpu=@var{cpu}
-@itemx --with-cpu-32=@var{cpu}
-@itemx --with-cpu-64=@var{cpu}
-Specify which cpu variant the compiler should generate code for by default.
-@var{cpu} will be used as the default value of the @option{-mcpu=} switch.
-This option is only supported on some targets, including ARC, ARM, i386, M68k,
-PowerPC, and SPARC@. It is mandatory for ARC@. The @option{--with-cpu-32} and
-@option{--with-cpu-64} options specify separate default CPUs for
-32-bit and 64-bit modes; these options are only supported for aarch64, i386,
-x86-64, PowerPC, and SPARC@.
-
-@item --with-schedule=@var{cpu}
-@itemx --with-arch=@var{cpu}
-@itemx --with-arch-32=@var{cpu}
-@itemx --with-arch-64=@var{cpu}
-@itemx --with-tune=@var{cpu}
-@itemx --with-tune-32=@var{cpu}
-@itemx --with-tune-64=@var{cpu}
-@itemx --with-abi=@var{abi}
-@itemx --with-fpu=@var{type}
-@itemx --with-float=@var{type}
-These configure options provide default values for the @option{-mschedule=},
-@option{-march=}, @option{-mtune=}, @option{-mabi=}, and @option{-mfpu=}
-options and for @option{-mhard-float} or @option{-msoft-float}. As with
-@option{--with-cpu}, which switches will be accepted and acceptable values
-of the arguments depend on the target.
-
-@item --with-mode=@var{mode}
-Specify if the compiler should default to @option{-marm} or @option{-mthumb}.
-This option is only supported on ARM targets.
-
-@item --with-stack-offset=@var{num}
-This option sets the default for the -mstack-offset=@var{num} option,
-and will thus generally also control the setting of this option for
-libraries. This option is only supported on Epiphany targets.
-
-@item --with-fpmath=@var{isa}
-This options sets @option{-mfpmath=sse} by default and specifies the default
-ISA for floating-point arithmetics. You can select either @samp{sse} which
-enables @option{-msse2} or @samp{avx} which enables @option{-mavx} by default.
-This option is only supported on i386 and x86-64 targets.
-
-@item --with-fp-32=@var{mode}
-On MIPS targets, set the default value for the @option{-mfp} option when using
-the o32 ABI. The possibilities for @var{mode} are:
-@table @code
-@item 32
-Use the o32 FP32 ABI extension, as with the @option{-mfp32} command-line
-option.
-@item xx
-Use the o32 FPXX ABI extension, as with the @option{-mfpxx} command-line
-option.
-@item 64
-Use the o32 FP64 ABI extension, as with the @option{-mfp64} command-line
-option.
-@end table
-In the absence of this configuration option the default is to use the o32
-FP32 ABI extension.
-
-@item --with-odd-spreg-32
-On MIPS targets, set the @option{-modd-spreg} option by default when using
-the o32 ABI.
-
-@item --without-odd-spreg-32
-On MIPS targets, set the @option{-mno-odd-spreg} option by default when using
-the o32 ABI. This is normally used in conjunction with
-@option{--with-fp-32=64} in order to target the o32 FP64A ABI extension.
-
-@item --with-nan=@var{encoding}
-On MIPS targets, set the default encoding convention to use for the
-special not-a-number (NaN) IEEE 754 floating-point data. The
-possibilities for @var{encoding} are:
-@table @code
-@item legacy
-Use the legacy encoding, as with the @option{-mnan=legacy} command-line
-option.
-@item 2008
-Use the 754-2008 encoding, as with the @option{-mnan=2008} command-line
-option.
-@end table
-To use this configuration option you must have an assembler version
-installed that supports the @option{-mnan=} command-line option too.
-In the absence of this configuration option the default convention is
-the legacy encoding, as when neither of the @option{-mnan=2008} and
-@option{-mnan=legacy} command-line options has been used.
-
-@item --with-divide=@var{type}
-Specify how the compiler should generate code for checking for
-division by zero. This option is only supported on the MIPS target.
-The possibilities for @var{type} are:
-@table @code
-@item traps
-Division by zero checks use conditional traps (this is the default on
-systems that support conditional traps).
-@item breaks
-Division by zero checks use the break instruction.
-@end table
-
-@item --with-compact-branches=@var{policy}
-Specify how the compiler should generate branch instructions.
-This option is only supported on the MIPS target.
-The possibilities for @var{type} are:
-@table @code
-@item optimal
-Cause a delay slot branch to be used if one is available in the
-current ISA and the delay slot is successfully filled. If the delay slot
-is not filled, a compact branch will be chosen if one is available.
-@item never
-Ensures that compact branch instructions will never be generated.
-@item always
-Ensures that a compact branch instruction will be generated if available.
-If a compact branch instruction is not available,
-a delay slot form of the branch will be used instead.
-This option is supported from MIPS Release 6 onwards.
-For pre-R6/microMIPS/MIPS16, this option is just same as never/optimal.
-@end table
-
-@c If you make --with-llsc the default for additional targets,
-@c update the --with-llsc description in the MIPS section below.
-
-@item --with-llsc
-On MIPS targets, make @option{-mllsc} the default when no
-@option{-mno-llsc} option is passed. This is the default for
-Linux-based targets, as the kernel will emulate them if the ISA does
-not provide them.
-
-@item --without-llsc
-On MIPS targets, make @option{-mno-llsc} the default when no
-@option{-mllsc} option is passed.
-
-@item --with-synci
-On MIPS targets, make @option{-msynci} the default when no
-@option{-mno-synci} option is passed.
-
-@item --without-synci
-On MIPS targets, make @option{-mno-synci} the default when no
-@option{-msynci} option is passed. This is the default.
-
-@item --with-lxc1-sxc1
-On MIPS targets, make @option{-mlxc1-sxc1} the default when no
-@option{-mno-lxc1-sxc1} option is passed. This is the default.
-
-@item --without-lxc1-sxc1
-On MIPS targets, make @option{-mno-lxc1-sxc1} the default when no
-@option{-mlxc1-sxc1} option is passed. The indexed load/store
-instructions are not directly a problem but can lead to unexpected
-behaviour when deployed in an application intended for a 32-bit address
-space but run on a 64-bit processor. The issue is seen because all
-known MIPS 64-bit Linux kernels execute o32 and n32 applications
-with 64-bit addressing enabled which affects the overflow behaviour
-of the indexed addressing mode. GCC will assume that ordinary
-32-bit arithmetic overflow behaviour is the same whether performed
-as an @code{addu} instruction or as part of the address calculation
-in @code{lwxc1} type instructions. This assumption holds true in a
-pure 32-bit environment and can hold true in a 64-bit environment if
-the address space is accurately set to be 32-bit for o32 and n32.
-
-@item --with-madd4
-On MIPS targets, make @option{-mmadd4} the default when no
-@option{-mno-madd4} option is passed. This is the default.
-
-@item --without-madd4
-On MIPS targets, make @option{-mno-madd4} the default when no
-@option{-mmadd4} option is passed. The @code{madd4} instruction
-family can be problematic when targeting a combination of cores that
-implement these instructions differently. There are two known cores
-that implement these as fused operations instead of unfused (where
-unfused is normally expected). Disabling these instructions is the
-only way to ensure compatible code is generated; this will incur
-a performance penalty.
-
-@item --with-mips-plt
-On MIPS targets, make use of copy relocations and PLTs.
-These features are extensions to the traditional
-SVR4-based MIPS ABIs and require support from GNU binutils
-and the runtime C library.
-
-@item --with-stack-clash-protection-guard-size=@var{size}
-On certain targets this option sets the default stack clash protection guard
-size as a power of two in bytes. On AArch64 @var{size} is required to be either
-12 (4KB) or 16 (64KB).
-
-@item --with-isa-spec=@var{ISA-spec-string}
-On RISC-V targets specify the default version of the RISC-V Unprivileged
-(formerly User-Level) ISA specification to produce code conforming to.
-The possibilities for @var{ISA-spec-string} are:
-@table @code
-@item 2.2
-Produce code conforming to version 2.2.
-@item 20190608
-Produce code conforming to version 20190608.
-@item 20191213
-Produce code conforming to version 20191213.
-@end table
-In the absence of this configuration option the default version is 20191213.
-
-@item --enable-__cxa_atexit
-Define if you want to use __cxa_atexit, rather than atexit, to
-register C++ destructors for local statics and global objects.
-This is essential for fully standards-compliant handling of
-destructors, but requires __cxa_atexit in libc. This option is currently
-only available on systems with GNU libc. When enabled, this will cause
-@option{-fuse-cxa-atexit} to be passed by default.
-
-@item --enable-gnu-indirect-function
-Define if you want to enable the @code{ifunc} attribute. This option is
-currently only available on systems with GNU libc on certain targets.
-
-@item --enable-target-optspace
-Specify that target
-libraries should be optimized for code space instead of code speed.
-This is the default for the m32r platform.
-
-@item --with-cpp-install-dir=@var{dirname}
-Specify that the user visible @command{cpp} program should be installed
-in @file{@var{prefix}/@var{dirname}/cpp}, in addition to @var{bindir}.
-
-@item --enable-comdat
-Enable COMDAT group support. This is primarily used to override the
-automatically detected value.
-
-@item --enable-initfini-array
-Force the use of sections @code{.init_array} and @code{.fini_array}
-(instead of @code{.init} and @code{.fini}) for constructors and
-destructors. Option @option{--disable-initfini-array} has the
-opposite effect. If neither option is specified, the configure script
-will try to guess whether the @code{.init_array} and
-@code{.fini_array} sections are supported and, if they are, use them.
-
-@item --enable-link-mutex
-When building GCC, use a mutex to avoid linking the compilers for
-multiple languages at the same time, to avoid thrashing on build
-systems with limited free memory. The default is not to use such a mutex.
-
-@item --enable-link-serialization
-When building GCC, use make dependencies to serialize linking the compilers for
-multiple languages, to avoid thrashing on build
-systems with limited free memory. The default is not to add such
-dependencies and thus with parallel make potentially link different
-compilers concurrently. If the argument is a positive integer, allow
-that number of concurrent link processes for the large binaries.
-
-@item --enable-maintainer-mode
-The build rules that regenerate the Autoconf and Automake output files as
-well as the GCC master message catalog @file{gcc.pot} are normally
-disabled. This is because it can only be rebuilt if the complete source
-tree is present. If you have changed the sources and want to rebuild the
-catalog, configuring with @option{--enable-maintainer-mode} will enable
-this. Note that you need a recent version of the @code{gettext} tools
-to do so.
-
-@item --disable-bootstrap
-For a native build, the default configuration is to perform
-a 3-stage bootstrap of the compiler when @samp{make} is invoked,
-testing that GCC can compile itself correctly. If you want to disable
-this process, you can configure with @option{--disable-bootstrap}.
-
-@item --enable-bootstrap
-In special cases, you may want to perform a 3-stage build
-even if the target and host triplets are different.
-This is possible when the host can run code compiled for
-the target (e.g.@: host is i686-linux, target is i486-linux).
-Starting from GCC 4.2, to do this you have to configure explicitly
-with @option{--enable-bootstrap}.
-
-@item --enable-generated-files-in-srcdir
-Neither the .c and .h files that are generated from Bison and flex nor the
-info manuals and man pages that are built from the .texi files are present
-in the repository development tree. When building GCC from that development tree,
-or from one of our snapshots, those generated files are placed in your
-build directory, which allows for the source to be in a readonly
-directory.
-
-If you configure with @option{--enable-generated-files-in-srcdir} then those
-generated files will go into the source directory. This is mainly intended
-for generating release or prerelease tarballs of the GCC sources, since it
-is not a requirement that the users of source releases to have flex, Bison,
-or makeinfo.
-
-@item --enable-version-specific-runtime-libs
-Specify
-that runtime libraries should be installed in the compiler specific
-subdirectory (@file{@var{libdir}/gcc}) rather than the usual places. In
-addition, @samp{libstdc++}'s include files will be installed into
-@file{@var{libdir}} unless you overruled it by using
-@option{--with-gxx-include-dir=@var{dirname}}. Using this option is
-particularly useful if you intend to use several versions of GCC in
-parallel. The default is @samp{yes} for @samp{libada}, and @samp{no} for
-the remaining libraries.
-
-@item @anchor{WithAixSoname}--with-aix-soname=@samp{aix}, @samp{svr4} or @samp{both}
-Traditional AIX shared library versioning (versioned @code{Shared Object}
-files as members of unversioned @code{Archive Library} files named
-@samp{lib.a}) causes numerous headaches for package managers. However,
-@code{Import Files} as members of @code{Archive Library} files allow for
-@strong{filename-based versioning} of shared libraries as seen on Linux/SVR4,
-where this is called the "SONAME". But as they prevent static linking,
-@code{Import Files} may be used with @code{Runtime Linking} only, where the
-linker does search for @samp{libNAME.so} before @samp{libNAME.a} library
-filenames with the @samp{-lNAME} linker flag.
-
-@anchor{AixLdCommand}For detailed information please refer to the AIX
-@uref{https://www.ibm.com/support/knowledgecenter/search/%22the%20ld%20command%2C%20also%20called%20the%20linkage%20editor%20or%20binder%22,,ld
-Command} reference.
-
-As long as shared library creation is enabled, upon:
-@table @code
-@item --with-aix-soname=aix
-@item --with-aix-soname=both
- A (traditional AIX) @code{Shared Archive Library} file is created:
- @itemize @bullet
- @item using the @samp{libNAME.a} filename scheme
- @item with the @code{Shared Object} file as archive member named
- @samp{libNAME.so.V} (except for @samp{libgcc_s}, where the @code{Shared
- Object} file is named @samp{shr.o} for backwards compatibility), which
- @itemize @minus
- @item is used for runtime loading from inside the @samp{libNAME.a} file
- @item is used for dynamic loading via
- @code{dlopen("libNAME.a(libNAME.so.V)", RTLD_MEMBER)}
- @item is used for shared linking
- @item is used for static linking, so no separate @code{Static Archive
- Library} file is needed
- @end itemize
- @end itemize
-@item --with-aix-soname=both
-@item --with-aix-soname=svr4
- A (second) @code{Shared Archive Library} file is created:
- @itemize @bullet
- @item using the @samp{libNAME.so.V} filename scheme
- @item with the @code{Shared Object} file as archive member named
- @samp{shr.o}, which
- @itemize @minus
- @item is created with the @code{-G linker flag}
- @item has the @code{F_LOADONLY} flag set
- @item is used for runtime loading from inside the @samp{libNAME.so.V} file
- @item is used for dynamic loading via @code{dlopen("libNAME.so.V(shr.o)",
- RTLD_MEMBER)}
- @end itemize
- @item with the @code{Import File} as archive member named @samp{shr.imp},
- which
- @itemize @minus
- @item refers to @samp{libNAME.so.V(shr.o)} as the "SONAME", to be recorded
- in the @code{Loader Section} of subsequent binaries
- @item indicates whether @samp{libNAME.so.V(shr.o)} is 32 or 64 bit
- @item lists all the public symbols exported by @samp{lib.so.V(shr.o)},
- eventually decorated with the @code{@samp{weak} Keyword}
- @item is necessary for shared linking against @samp{lib.so.V(shr.o)}
- @end itemize
- @end itemize
- A symbolic link using the @samp{libNAME.so} filename scheme is created:
- @itemize @bullet
- @item pointing to the @samp{libNAME.so.V} @code{Shared Archive Library} file
- @item to permit the @code{ld Command} to find @samp{lib.so.V(shr.imp)} via
- the @samp{-lNAME} argument (requires @code{Runtime Linking} to be enabled)
- @item to permit dynamic loading of @samp{lib.so.V(shr.o)} without the need
- to specify the version number via @code{dlopen("libNAME.so(shr.o)",
- RTLD_MEMBER)}
- @end itemize
-@end table
-
-As long as static library creation is enabled, upon:
-@table @code
-@item --with-aix-soname=svr4
- A @code{Static Archive Library} is created:
- @itemize @bullet
- @item using the @samp{libNAME.a} filename scheme
- @item with all the @code{Static Object} files as archive members, which
- @itemize @minus
- @item are used for static linking
- @end itemize
- @end itemize
-@end table
-
-While the aix-soname=@samp{svr4} option does not create @code{Shared Object}
-files as members of unversioned @code{Archive Library} files any more, package
-managers still are responsible to
-@uref{./specific.html#TransferAixShobj,,transfer} @code{Shared Object} files
-found as member of a previously installed unversioned @code{Archive Library}
-file into the newly installed @code{Archive Library} file with the same
-filename.
-
-@emph{WARNING:} Creating @code{Shared Object} files with @code{Runtime Linking}
-enabled may bloat the TOC, eventually leading to @code{TOC overflow} errors,
-requiring the use of either the @option{-Wl,-bbigtoc} linker flag (seen to
-break with the @code{GDB} debugger) or some of the TOC-related compiler flags,
-@ifnothtml
-@xref{RS/6000 and PowerPC Options,, RS/6000 and PowerPC Options, gcc,
-Using the GNU Compiler Collection (GCC)}.
-@end ifnothtml
-@ifhtml
-see ``RS/6000 and PowerPC Options'' in the main manual.
-@end ifhtml
-
-@option{--with-aix-soname} is currently supported by @samp{libgcc_s} only, so
-this option is still experimental and not for normal use yet.
-
-Default is the traditional behavior @option{--with-aix-soname=@samp{aix}}.
-
-@item --enable-languages=@var{lang1},@var{lang2},@dots{}
-Specify that only a particular subset of compilers and
-their runtime libraries should be built. For a list of valid values for
-@var{langN} you can issue the following command in the
-@file{gcc} directory of your GCC source tree:@*
-@smallexample
-grep ^language= */config-lang.in
-@end smallexample
-Currently, you can use any of the following:
-@code{all}, @code{default}, @code{ada}, @code{c}, @code{c++}, @code{d},
-@code{fortran}, @code{go}, @code{jit}, @code{lto}, @code{objc}, @code{obj-c++}.
-Building the Ada compiler has special requirements, see below.
-If you do not pass this flag, or specify the option @code{default}, then the
-default languages available in the @file{gcc} sub-tree will be configured.
-Ada, D, Go, Jit, and Objective-C++ are not default languages. LTO is not a
-default language, but is built by default because @option{--enable-lto} is
-enabled by default. The other languages are default languages. If
-@code{all} is specified, then all available languages are built. An
-exception is @code{jit} language, which requires
-@option{--enable-host-shared} to be included with @code{all}.
-
-@item --enable-stage1-languages=@var{lang1},@var{lang2},@dots{}
-Specify that a particular subset of compilers and their runtime
-libraries should be built with the system C compiler during stage 1 of
-the bootstrap process, rather than only in later stages with the
-bootstrapped C compiler. The list of valid values is the same as for
-@option{--enable-languages}, and the option @code{all} will select all
-of the languages enabled by @option{--enable-languages}. This option is
-primarily useful for GCC development; for instance, when a development
-version of the compiler cannot bootstrap due to compiler bugs, or when
-one is debugging front ends other than the C front end. When this
-option is used, one can then build the target libraries for the
-specified languages with the stage-1 compiler by using @command{make
-stage1-bubble all-target}, or run the testsuite on the stage-1 compiler
-for the specified languages using @command{make stage1-start check-gcc}.
-
-@item --disable-libada
-Specify that the run-time libraries and tools used by GNAT should not
-be built. This can be useful for debugging, or for compatibility with
-previous Ada build procedures, when it was required to explicitly
-do a @samp{make -C gcc gnatlib_and_tools}.
-
-@item --disable-libsanitizer
-Specify that the run-time libraries for the various sanitizers should
-not be built.
-
-@item --disable-libssp
-Specify that the run-time libraries for stack smashing protection
-should not be built or linked against. On many targets library support
-is provided by the C library instead.
-
-@item --disable-libquadmath
-Specify that the GCC quad-precision math library should not be built.
-On some systems, the library is required to be linkable when building
-the Fortran front end, unless @option{--disable-libquadmath-support}
-is used.
-
-@item --disable-libquadmath-support
-Specify that the Fortran front end and @code{libgfortran} do not add
-support for @code{libquadmath} on systems supporting it.
-
-@item --disable-libgomp
-Specify that the GNU Offloading and Multi Processing Runtime Library
-should not be built.
-
-@item --disable-libvtv
-Specify that the run-time libraries used by vtable verification
-should not be built.
-
-@item --with-dwarf2
-Specify that the compiler should
-use DWARF 2 debugging information as the default.
-
-@item --with-advance-toolchain=@var{at}
-On 64-bit PowerPC Linux systems, configure the compiler to use the
-header files, library files, and the dynamic linker from the Advance
-Toolchain release @var{at} instead of the default versions that are
-provided by the Linux distribution. In general, this option is
-intended for the developers of GCC, and it is not intended for general
-use.
-
-@item --enable-targets=all
-@itemx --enable-targets=@var{target_list}
-Some GCC targets, e.g.@: powerpc64-linux, build bi-arch compilers.
-These are compilers that are able to generate either 64-bit or 32-bit
-code. Typically, the corresponding 32-bit target, e.g.@:
-powerpc-linux for powerpc64-linux, only generates 32-bit code. This
-option enables the 32-bit target to be a bi-arch compiler, which is
-useful when you want a bi-arch compiler that defaults to 32-bit, and
-you are building a bi-arch or multi-arch binutils in a combined tree.
-On mips-linux, this will build a tri-arch compiler (ABI o32/n32/64),
-defaulted to o32.
-Currently, this option only affects sparc-linux, powerpc-linux, x86-linux,
-mips-linux and s390-linux.
-
-@item --enable-default-pie
-Turn on @option{-fPIE} and @option{-pie} by default.
-
-@item --enable-secureplt
-This option enables @option{-msecure-plt} by default for powerpc-linux.
-@ifnothtml
-@xref{RS/6000 and PowerPC Options,, RS/6000 and PowerPC Options, gcc,
-Using the GNU Compiler Collection (GCC)},
-@end ifnothtml
-@ifhtml
-See ``RS/6000 and PowerPC Options'' in the main manual
-@end ifhtml
-
-@item --enable-default-ssp
-Turn on @option{-fstack-protector-strong} by default.
-
-@item --enable-cld
-This option enables @option{-mcld} by default for 32-bit x86 targets.
-@ifnothtml
-@xref{i386 and x86-64 Options,, i386 and x86-64 Options, gcc,
-Using the GNU Compiler Collection (GCC)},
-@end ifnothtml
-@ifhtml
-See ``i386 and x86-64 Options'' in the main manual
-@end ifhtml
-
-@item --enable-large-address-aware
-The @option{--enable-large-address-aware} option arranges for MinGW
-executables to be linked using the @option{--large-address-aware}
-option, that enables the use of more than 2GB of memory. If GCC is
-configured with this option, its effects can be reversed by passing the
-@option{-Wl,--disable-large-address-aware} option to the so-configured
-compiler driver.
-
-@item --enable-win32-registry
-@itemx --enable-win32-registry=@var{key}
-@itemx --disable-win32-registry
-The @option{--enable-win32-registry} option enables Microsoft Windows-hosted GCC
-to look up installations paths in the registry using the following key:
-
-@smallexample
-@code{HKEY_LOCAL_MACHINE\SOFTWARE\Free Software Foundation\@var{key}}
-@end smallexample
-
-@var{key} defaults to GCC version number, and can be overridden by the
-@option{--enable-win32-registry=@var{key}} option. Vendors and distributors
-who use custom installers are encouraged to provide a different key,
-perhaps one comprised of vendor name and GCC version number, to
-avoid conflict with existing installations. This feature is enabled
-by default, and can be disabled by @option{--disable-win32-registry}
-option. This option has no effect on the other hosts.
-
-@item --nfp
-Specify that the machine does not have a floating point unit. This
-option only applies to @samp{m68k-sun-sunos@var{n}}. On any other
-system, @option{--nfp} has no effect.
-
-@item --enable-werror
-@itemx --disable-werror
-@itemx --enable-werror=yes
-@itemx --enable-werror=no
-When you specify this option, it controls whether certain files in the
-compiler are built with @option{-Werror} in bootstrap stage2 and later.
-If you don't specify it, @option{-Werror} is turned on for the main
-development trunk. However it defaults to off for release branches and
-final releases. The specific files which get @option{-Werror} are
-controlled by the Makefiles.
-
-@item --enable-checking
-@itemx --disable-checking
-@itemx --enable-checking=@var{list}
-This option controls performing internal consistency checks in the compiler.
-It does not change the generated code, but adds error checking of the
-requested complexity. This slows down the compiler and may only work
-properly if you are building the compiler with GCC@.
-
-When the option is not specified, the active set of checks depends on context.
-Namely, bootstrap stage 1 defaults to @samp{--enable-checking=yes}, builds
-from release branches or release archives default to
-@samp{--enable-checking=release}, and otherwise
-@samp{--enable-checking=yes,extra} is used. When the option is
-specified without a @var{list}, the result is the same as
-@samp{--enable-checking=yes}. Likewise, @samp{--disable-checking} is
-equivalent to @samp{--enable-checking=no}.
-
-The categories of checks available in @var{list} are @samp{yes} (most common
-checks @samp{assert,misc,gc,gimple,rtlflag,runtime,tree,types}), @samp{no}
-(no checks at all), @samp{all} (all but @samp{valgrind}), @samp{release}
-(cheapest checks @samp{assert,runtime}) or @samp{none} (same as @samp{no}).
-@samp{release} checks are always on and to disable them
-@samp{--disable-checking} or @samp{--enable-checking=no[,<other checks>]}
-must be explicitly requested. Disabling assertions makes the compiler and
-runtime slightly faster but increases the risk of undetected internal errors
-causing wrong code to be generated.
-
-Individual checks can be enabled with these flags: @samp{assert}, @samp{df},
-@samp{extra}, @samp{fold}, @samp{gc}, @samp{gcac}, @samp{gimple},
-@samp{misc}, @samp{rtl}, @samp{rtlflag}, @samp{runtime}, @samp{tree},
-@samp{types} and @samp{valgrind}. @samp{extra} extends @samp{misc}
-checking with extra checks that might affect code generation and should
-therefore not differ between stage1 and later stages in bootstrap.
-
-The @samp{valgrind} check requires the external @command{valgrind} simulator,
-available from @uref{https://valgrind.org}. The @samp{rtl} checks are
-expensive and the @samp{df}, @samp{gcac} and @samp{valgrind} checks are very
-expensive.
-
-@item --disable-stage1-checking
-@itemx --enable-stage1-checking
-@itemx --enable-stage1-checking=@var{list}
-This option affects only bootstrap build. If no @option{--enable-checking}
-option is specified the stage1 compiler is built with @samp{yes} checking
-enabled, otherwise the stage1 checking flags are the same as specified by
-@option{--enable-checking}. To build the stage1 compiler with
-different checking options use @option{--enable-stage1-checking}.
-The list of checking options is the same as for @option{--enable-checking}.
-If your system is too slow or too small to bootstrap a released compiler
-with checking for stage1 enabled, you can use @samp{--disable-stage1-checking}
-to disable checking for the stage1 compiler.
-
-@item --enable-coverage
-@itemx --enable-coverage=@var{level}
-With this option, the compiler is built to collect self coverage
-information, every time it is run. This is for internal development
-purposes, and only works when the compiler is being built with gcc. The
-@var{level} argument controls whether the compiler is built optimized or
-not, values are @samp{opt} and @samp{noopt}. For coverage analysis you
-want to disable optimization, for performance analysis you want to
-enable optimization. When coverage is enabled, the default level is
-without optimization.
-
-@item --enable-gather-detailed-mem-stats
-When this option is specified more detailed information on memory
-allocation is gathered. This information is printed when using
-@option{-fmem-report}.
-
-@item --enable-valgrind-annotations
-Mark selected memory related operations in the compiler when run under
-valgrind to suppress false positives.
-
-@item --enable-nls
-@itemx --disable-nls
-The @option{--enable-nls} option enables Native Language Support (NLS),
-which lets GCC output diagnostics in languages other than American
-English. Native Language Support is enabled by default if not doing a
-canadian cross build. The @option{--disable-nls} option disables NLS@.
-
-@item --with-included-gettext
-If NLS is enabled, the @option{--with-included-gettext} option causes the build
-procedure to prefer its copy of GNU @command{gettext}.
-
-@item --with-catgets
-If NLS is enabled, and if the host lacks @code{gettext} but has the
-inferior @code{catgets} interface, the GCC build procedure normally
-ignores @code{catgets} and instead uses GCC's copy of the GNU
-@code{gettext} library. The @option{--with-catgets} option causes the
-build procedure to use the host's @code{catgets} in this situation.
-
-@item --with-libiconv-prefix=@var{dir}
-Search for libiconv header files in @file{@var{dir}/include} and
-libiconv library files in @file{@var{dir}/lib}.
-
-@item --enable-obsolete
-Enable configuration for an obsoleted system. If you attempt to
-configure GCC for a system (build, host, or target) which has been
-obsoleted, and you do not specify this flag, configure will halt with an
-error message.
-
-All support for systems which have been obsoleted in one release of GCC
-is removed entirely in the next major release, unless someone steps
-forward to maintain the port.
-
-@item --enable-decimal-float
-@itemx --enable-decimal-float=yes
-@itemx --enable-decimal-float=no
-@itemx --enable-decimal-float=bid
-@itemx --enable-decimal-float=dpd
-@itemx --disable-decimal-float
-Enable (or disable) support for the C decimal floating point extension
-that is in the IEEE 754-2008 standard. This is enabled by default only
-on PowerPC, i386, and x86_64 GNU/Linux systems. Other systems may also
-support it, but require the user to specifically enable it. You can
-optionally control which decimal floating point format is used (either
-@samp{bid} or @samp{dpd}). The @samp{bid} (binary integer decimal)
-format is default on i386 and x86_64 systems, and the @samp{dpd}
-(densely packed decimal) format is default on PowerPC systems.
-
-@item --enable-fixed-point
-@itemx --disable-fixed-point
-Enable (or disable) support for C fixed-point arithmetic.
-This option is enabled by default for some targets (such as MIPS) which
-have hardware-support for fixed-point operations. On other targets, you
-may enable this option manually.
-
-@item --with-long-double-128
-Specify if @code{long double} type should be 128-bit by default on selected
-GNU/Linux architectures. If using @code{--without-long-double-128},
-@code{long double} will be by default 64-bit, the same as @code{double} type.
-When neither of these configure options are used, the default will be
-128-bit @code{long double} when built against GNU C Library 2.4 and later,
-64-bit @code{long double} otherwise.
-
-@item --with-long-double-format=ibm
-@itemx --with-long-double-format=ieee
-Specify whether @code{long double} uses the IBM extended double format
-or the IEEE 128-bit floating point format on PowerPC Linux systems.
-This configuration switch will only work on little endian PowerPC
-Linux systems and on big endian 64-bit systems where the default cpu
-is at least power7 (i.e.@: @option{--with-cpu=power7},
-@option{--with-cpu=power8}, or @option{--with-cpu=power9} is used).
-
-If you use the @option{--with-long-double-64} configuration option,
-the @option{--with-long-double-format=ibm} and
-@option{--with-long-double-format=ieee} options are ignored.
-
-The default @code{long double} format is to use IBM extended double.
-Until all of the libraries are converted to use IEEE 128-bit floating
-point, it is not recommended to use
-@option{--with-long-double-format=ieee}.
-
-@item --enable-fdpic
-On SH Linux systems, generate ELF FDPIC code.
-
-@item --with-gmp=@var{pathname}
-@itemx --with-gmp-include=@var{pathname}
-@itemx --with-gmp-lib=@var{pathname}
-@itemx --with-mpfr=@var{pathname}
-@itemx --with-mpfr-include=@var{pathname}
-@itemx --with-mpfr-lib=@var{pathname}
-@itemx --with-mpc=@var{pathname}
-@itemx --with-mpc-include=@var{pathname}
-@itemx --with-mpc-lib=@var{pathname}
-If you want to build GCC but do not have the GMP library, the MPFR
-library and/or the MPC library installed in a standard location and
-do not have their sources present in the GCC source tree then you
-can explicitly specify the directory where they are installed
-(@samp{--with-gmp=@var{gmpinstalldir}},
-@samp{--with-mpfr=@/@var{mpfrinstalldir}},
-@samp{--with-mpc=@/@var{mpcinstalldir}}). The
-@option{--with-gmp=@/@var{gmpinstalldir}} option is shorthand for
-@option{--with-gmp-lib=@/@var{gmpinstalldir}/lib} and
-@option{--with-gmp-include=@/@var{gmpinstalldir}/include}. Likewise the
-@option{--with-mpfr=@/@var{mpfrinstalldir}} option is shorthand for
-@option{--with-mpfr-lib=@/@var{mpfrinstalldir}/lib} and
-@option{--with-mpfr-include=@/@var{mpfrinstalldir}/include}, also the
-@option{--with-mpc=@/@var{mpcinstalldir}} option is shorthand for
-@option{--with-mpc-lib=@/@var{mpcinstalldir}/lib} and
-@option{--with-mpc-include=@/@var{mpcinstalldir}/include}. If these
-shorthand assumptions are not correct, you can use the explicit
-include and lib options directly. You might also need to ensure the
-shared libraries can be found by the dynamic linker when building and
-using GCC, for example by setting the runtime shared library path
-variable (@env{LD_LIBRARY_PATH} on GNU/Linux and Solaris systems).
-
-These flags are applicable to the host platform only. When building
-a cross compiler, they will not be used to configure target libraries.
-
-@item --with-isl=@var{pathname}
-@itemx --with-isl-include=@var{pathname}
-@itemx --with-isl-lib=@var{pathname}
-If you do not have the isl library installed in a standard location and you
-want to build GCC, you can explicitly specify the directory where it is
-installed (@samp{--with-isl=@/@var{islinstalldir}}). The
-@option{--with-isl=@/@var{islinstalldir}} option is shorthand for
-@option{--with-isl-lib=@/@var{islinstalldir}/lib} and
-@option{--with-isl-include=@/@var{islinstalldir}/include}. If this
-shorthand assumption is not correct, you can use the explicit
-include and lib options directly.
-
-These flags are applicable to the host platform only. When building
-a cross compiler, they will not be used to configure target libraries.
-
-@item --with-stage1-ldflags=@var{flags}
-This option may be used to set linker flags to be used when linking
-stage 1 of GCC. These are also used when linking GCC if configured with
-@option{--disable-bootstrap}. If @option{--with-stage1-libs} is not set to a
-value, then the default is @samp{-static-libstdc++ -static-libgcc}, if
-supported.
-
-@item --with-stage1-libs=@var{libs}
-This option may be used to set libraries to be used when linking stage 1
-of GCC. These are also used when linking GCC if configured with
-@option{--disable-bootstrap}.
-
-@item --with-boot-ldflags=@var{flags}
-This option may be used to set linker flags to be used when linking
-stage 2 and later when bootstrapping GCC. If --with-boot-libs
-is not is set to a value, then the default is
-@samp{-static-libstdc++ -static-libgcc}.
-
-@item --with-boot-libs=@var{libs}
-This option may be used to set libraries to be used when linking stage 2
-and later when bootstrapping GCC.
-
-@item --with-debug-prefix-map=@var{map}
-Convert source directory names using @option{-fdebug-prefix-map} when
-building runtime libraries. @samp{@var{map}} is a space-separated
-list of maps of the form @samp{@var{old}=@var{new}}.
-
-@item --enable-linker-build-id
-Tells GCC to pass @option{--build-id} option to the linker for all final
-links (links performed without the @option{-r} or @option{--relocatable}
-option), if the linker supports it. If you specify
-@option{--enable-linker-build-id}, but your linker does not
-support @option{--build-id} option, a warning is issued and the
-@option{--enable-linker-build-id} option is ignored. The default is off.
-
-@item --with-linker-hash-style=@var{choice}
-Tells GCC to pass @option{--hash-style=@var{choice}} option to the
-linker for all final links. @var{choice} can be one of
-@samp{sysv}, @samp{gnu}, and @samp{both} where @samp{sysv} is the default.
-
-@item --enable-gnu-unique-object
-@itemx --disable-gnu-unique-object
-Tells GCC to use the gnu_unique_object relocation for C++ template
-static data members and inline function local statics. Enabled by
-default for a toolchain with an assembler that accepts it and
-GLIBC 2.11 or above, otherwise disabled.
-
-@item --with-diagnostics-color=@var{choice}
-Tells GCC to use @var{choice} as the default for @option{-fdiagnostics-color=}
-option (if not used explicitly on the command line). @var{choice}
-can be one of @samp{never}, @samp{auto}, @samp{always}, and @samp{auto-if-env}
-where @samp{auto} is the default. @samp{auto-if-env} makes
-@option{-fdiagnostics-color=auto} the default if @env{GCC_COLORS}
-is present and non-empty in the environment of the compiler, and
-@option{-fdiagnostics-color=never} otherwise.
-
-@item --with-diagnostics-urls=@var{choice}
-Tells GCC to use @var{choice} as the default for @option{-fdiagnostics-urls=}
-option (if not used explicitly on the command line). @var{choice}
-can be one of @samp{never}, @samp{auto}, @samp{always}, and @samp{auto-if-env}
-where @samp{auto} is the default. @samp{auto-if-env} makes
-@option{-fdiagnostics-urls=auto} the default if @env{GCC_URLS}
-or @env{TERM_URLS} is present and non-empty in the environment of the
-compiler, and @option{-fdiagnostics-urls=never} otherwise.
-
-@item --enable-lto
-@itemx --disable-lto
-Enable support for link-time optimization (LTO). This is enabled by
-default, and may be disabled using @option{--disable-lto}.
-
-@item --enable-linker-plugin-configure-flags=FLAGS
-@itemx --enable-linker-plugin-flags=FLAGS
-By default, linker plugins (such as the LTO plugin) are built for the
-host system architecture. For the case that the linker has a
-different (but run-time compatible) architecture, these flags can be
-specified to build plugins that are compatible to the linker. For
-example, if you are building GCC for a 64-bit x86_64
-(@samp{x86_64-pc-linux-gnu}) host system, but have a 32-bit x86
-GNU/Linux (@samp{i686-pc-linux-gnu}) linker executable (which is
-executable on the former system), you can configure GCC as follows for
-getting compatible linker plugins:
-
-@smallexample
-% @var{srcdir}/configure \
- --host=x86_64-pc-linux-gnu \
- --enable-linker-plugin-configure-flags=--host=i686-pc-linux-gnu \
- --enable-linker-plugin-flags='CC=gcc\ -m32\ -Wl,-rpath,[...]/i686-pc-linux-gnu/lib'
-@end smallexample
-
-@item --with-plugin-ld=@var{pathname}
-Enable an alternate linker to be used at link-time optimization (LTO)
-link time when @option{-fuse-linker-plugin} is enabled.
-This linker should have plugin support such as gold starting with
-version 2.20 or GNU ld starting with version 2.21.
-See @option{-fuse-linker-plugin} for details.
-
-@item --enable-canonical-system-headers
-@itemx --disable-canonical-system-headers
-Enable system header path canonicalization for @file{libcpp}. This can
-produce shorter header file paths in diagnostics and dependency output
-files, but these changed header paths may conflict with some compilation
-environments. Enabled by default, and may be disabled using
-@option{--disable-canonical-system-headers}.
-
-@item --with-glibc-version=@var{major}.@var{minor}
-Tell GCC that when the GNU C Library (glibc) is used on the target it
-will be version @var{major}.@var{minor} or later. Normally this can
-be detected from the C library's header files, but this option may be
-needed when bootstrapping a cross toolchain without the header files
-available for building the initial bootstrap compiler.
-
-If GCC is configured with some multilibs that use glibc and some that
-do not, this option applies only to the multilibs that use glibc.
-However, such configurations may not work well as not all the relevant
-configuration in GCC is on a per-multilib basis.
-
-@item --enable-as-accelerator-for=@var{target}
-Build as offload target compiler. Specify offload host triple by @var{target}.
-
-@item --enable-offload-targets=@var{target1}[=@var{path1}],@dots{},@var{targetN}[=@var{pathN}]
-Enable offloading to targets @var{target1}, @dots{}, @var{targetN}.
-Offload compilers are expected to be already installed. Default search
-path for them is @file{@var{exec-prefix}}, but it can be changed by
-specifying paths @var{path1}, @dots{}, @var{pathN}.
-
-@smallexample
-% @var{srcdir}/configure \
- --enable-offload-targets=amdgcn-amdhsa,nvptx-none
-@end smallexample
-
-@item --enable-offload-defaulted
-
-Tell GCC that configured but not installed offload compilers and libgomp
-plugins are silently ignored. Useful for distribution compilers where
-those are in separate optional packages and where the presence or absence
-of those optional packages should determine the actual supported offloading
-target set rather than the GCC configure-time selection.
-
-@item --enable-cet
-@itemx --disable-cet
-Enable building target run-time libraries with control-flow
-instrumentation, see @option{-fcf-protection} option. When
-@code{--enable-cet} is specified target libraries are configured
-to add @option{-fcf-protection} and, if needed, other target
-specific options to a set of building options.
-
-@code{--enable-cet=auto} is default. CET is enabled on Linux/x86 if
-target binutils supports @code{Intel CET} instructions and disabled
-otherwise. In this case, the target libraries are configured to get
-additional @option{-fcf-protection} option.
-
-@item --with-riscv-attribute=@samp{yes}, @samp{no} or @samp{default}
-Generate RISC-V attribute by default, in order to record extra build
-information in object.
-
-The option is disabled by default. It is enabled on RISC-V/ELF (bare-metal)
-target if target binutils supported.
-
-@item --enable-s390-excess-float-precision
-@itemx --disable-s390-excess-float-precision
-On s390(x) targets, enable treatment of float expressions with double precision
-when in standards-compliant mode (e.g., when @code{--std=c99} or
-@code{-fexcess-precision=standard} are given).
-
-For a native build and cross compiles that have target headers, the option's
-default is derived from glibc's behavior. When glibc clamps float_t to double,
-GCC follows and enables the option. For other cross compiles, the default is
-disabled.
-
-@item --with-zstd=@var{pathname}
-@itemx --with-zstd-include=@var{pathname}
-@itemx --with-zstd-lib=@var{pathname}
-If you do not have the @code{zstd} library installed in a standard
-location and you want to build GCC, you can explicitly specify the
-directory where it is installed (@samp{--with-zstd=@/@var{zstdinstalldir}}).
-The @option{--with-zstd=@/@var{zstdinstalldir}} option is shorthand for
-@option{--with-zstd-lib=@/@var{zstdinstalldir}/lib} and
-@option{--with-zstd-include=@/@var{zstdinstalldir}/include}. If this
-shorthand assumption is not correct, you can use the explicit
-include and lib options directly.
-
-These flags are applicable to the host platform only. When building
-a cross compiler, they will not be used to configure target libraries.
-@end table
-
-@subheading Cross-Compiler-Specific Options
-The following options only apply to building cross compilers.
-
-@table @code
-@item --with-toolexeclibdir=@var{dir}
-Specify the installation directory for libraries built with a cross compiler.
-The default is @option{$@{gcc_tooldir@}/lib}.
-
-@item --with-sysroot
-@itemx --with-sysroot=@var{dir}
-Tells GCC to consider @var{dir} as the root of a tree that contains
-(a subset of) the root filesystem of the target operating system.
-Target system headers, libraries and run-time object files will be
-searched for in there. More specifically, this acts as if
-@option{--sysroot=@var{dir}} was added to the default options of the built
-compiler. The specified directory is not copied into the
-install tree, unlike the options @option{--with-headers} and
-@option{--with-libs} that this option obsoletes. The default value,
-in case @option{--with-sysroot} is not given an argument, is
-@option{$@{gcc_tooldir@}/sys-root}. If the specified directory is a
-subdirectory of @option{$@{exec_prefix@}}, then it will be found relative to
-the GCC binaries if the installation tree is moved.
-
-This option affects the system root for the compiler used to build
-target libraries (which runs on the build system) and the compiler newly
-installed with @code{make install}; it does not affect the compiler which is
-used to build GCC itself.
-
-If you specify the @option{--with-native-system-header-dir=@var{dirname}}
-option then the compiler will search that directory within @var{dirname} for
-native system headers rather than the default @file{/usr/include}.
-
-@item --with-build-sysroot
-@itemx --with-build-sysroot=@var{dir}
-Tells GCC to consider @var{dir} as the system root (see
-@option{--with-sysroot}) while building target libraries, instead of
-the directory specified with @option{--with-sysroot}. This option is
-only useful when you are already using @option{--with-sysroot}. You
-can use @option{--with-build-sysroot} when you are configuring with
-@option{--prefix} set to a directory that is different from the one in
-which you are installing GCC and your target libraries.
-
-This option affects the system root for the compiler used to build
-target libraries (which runs on the build system); it does not affect
-the compiler which is used to build GCC itself.
-
-If you specify the @option{--with-native-system-header-dir=@var{dirname}}
-option then the compiler will search that directory within @var{dirname} for
-native system headers rather than the default @file{/usr/include}.
-
-@item --with-headers
-@itemx --with-headers=@var{dir}
-Deprecated in favor of @option{--with-sysroot}.
-Specifies that target headers are available when building a cross compiler.
-The @var{dir} argument specifies a directory which has the target include
-files. These include files will be copied into the @file{gcc} install
-directory. @emph{This option with the @var{dir} argument is required} when
-building a cross compiler, if @file{@var{prefix}/@var{target}/sys-include}
-doesn't pre-exist. If @file{@var{prefix}/@var{target}/sys-include} does
-pre-exist, the @var{dir} argument may be omitted. @command{fixincludes}
-will be run on these files to make them compatible with GCC@.
-
-@item --without-headers
-Tells GCC not use any target headers from a libc when building a cross
-compiler. When crossing to GNU/Linux, you need the headers so GCC
-can build the exception handling for libgcc.
-
-@item --with-libs
-@itemx --with-libs="@var{dir1} @var{dir2} @dots{} @var{dirN}"
-Deprecated in favor of @option{--with-sysroot}.
-Specifies a list of directories which contain the target runtime
-libraries. These libraries will be copied into the @file{gcc} install
-directory. If the directory list is omitted, this option has no
-effect.
-
-@item --with-newlib
-Specifies that @samp{newlib} is
-being used as the target C library. This causes @code{__eprintf} to be
-omitted from @file{libgcc.a} on the assumption that it will be provided by
-@samp{newlib}.
-
-@html
-<a name="avr"></a>
-@end html
-@item --with-avrlibc
-Only supported for the AVR target. Specifies that @samp{AVR-Libc} is
-being used as the target C@tie{} library. This causes float support
-functions like @code{__addsf3} to be omitted from @file{libgcc.a} on
-the assumption that it will be provided by @file{libm.a}. For more
-technical details, cf. @uref{https://gcc.gnu.org/PR54461,,PR54461}.
-It is not supported for
-RTEMS configurations, which currently use newlib. The option is
-supported since version 4.7.2 and is the default in 4.8.0 and newer.
-
-@item --with-double=@{32|64|32,64|64,32@}
-@itemx --with-long-double=@{32|64|32,64|64,32|double@}
-Only supported for the AVR target since version@tie{}10.
-Specify the default layout available for the C/C++ @samp{double}
-and @samp{long double} type, respectively. The following rules apply:
-@itemize
-@item
-The first value after the @samp{=} specifies the default layout (in bits)
-of the type and also the default for the @option{-mdouble=} resp.
-@option{-mlong-double=} compiler option.
-@item
-If more than one value is specified, respective multilib variants are
-available, and @option{-mdouble=} resp. @option{-mlong-double=} acts
-as a multilib option.
-@item
-If @option{--with-long-double=double} is specified, @samp{double} and
-@samp{long double} will have the same layout.
-@item
-The defaults are @option{--with-long-double=64,32} and
-@option{--with-double=32,64}. The default @samp{double} layout imposed by
-the latter is compatible with older versions of the compiler that implement
-@samp{double} as a 32-bit type, which does not comply to the language standard.
-@end itemize
-Not all combinations of @option{--with-double=} and
-@option{--with-long-double=} are valid. For example, the combination
-@option{--with-double=32,64} @option{--with-long-double=32} will be
-rejected because the first option specifies the availability of
-multilibs for @samp{double}, whereas the second option implies
-that @samp{long double} --- and hence also @samp{double} --- is always
-32@tie{}bits wide.
-
-@item --with-double-comparison=@{tristate|bool|libf7@}
-Only supported for the AVR target since version@tie{}10.
-Specify what result format is returned by library functions that
-compare 64-bit floating point values (@code{DFmode}).
-The GCC default is @samp{tristate}. If the floating point
-implementation returns a boolean instead, set it to @samp{bool}.
-
-@item --with-libf7=@{libgcc|math|math-symbols|no@}
-Only supported for the AVR target since version@tie{}10.
-Specify to which degree code from LibF7 is included in libgcc.
-LibF7 is an ad-hoc, AVR-specific, 64-bit floating point emulation
-written in C and (inline) assembly. @samp{libgcc} adds support
-for functions that one would usually expect in libgcc like double addition,
-double comparisons and double conversions. @samp{math} also adds routines
-that one would expect in @file{libm.a}, but with @code{__} (two underscores)
-prepended to the symbol names as specified by @file{math.h}.
-@samp{math-symbols} also defines weak aliases for the functions
-declared in @file{math.h}. However, @code{--with-libf7} won't
-install no @file{math.h} header file whatsoever, this file must come
-from elsewhere. This option sets @option{--with-double-comparison}
-to @samp{bool}.
-
-@item --with-nds32-lib=@var{library}
-Specifies that @var{library} setting is used for building @file{libgcc.a}.
-Currently, the valid @var{library} is @samp{newlib} or @samp{mculib}.
-This option is only supported for the NDS32 target.
-
-@item --with-build-time-tools=@var{dir}
-Specifies where to find the set of target tools (assembler, linker, etc.)
-that will be used while building GCC itself. This option can be useful
-if the directory layouts are different between the system you are building
-GCC on, and the system where you will deploy it.
-
-For example, on an @samp{ia64-hp-hpux} system, you may have the GNU
-assembler and linker in @file{/usr/bin}, and the native tools in a
-different path, and build a toolchain that expects to find the
-native tools in @file{/usr/bin}.
-
-When you use this option, you should ensure that @var{dir} includes
-@command{ar}, @command{as}, @command{ld}, @command{nm},
-@command{ranlib} and @command{strip} if necessary, and possibly
-@command{objdump}. Otherwise, GCC may use an inconsistent set of
-tools.
-@end table
-
-@subsubheading Overriding @command{configure} test results
-
-Sometimes, it might be necessary to override the result of some
-@command{configure} test, for example in order to ease porting to a new
-system or work around a bug in a test. The toplevel @command{configure}
-script provides three variables for this:
-
-@table @code
-
-@item build_configargs
-@cindex @code{build_configargs}
-The contents of this variable is passed to all build @command{configure}
-scripts.
-
-@item host_configargs
-@cindex @code{host_configargs}
-The contents of this variable is passed to all host @command{configure}
-scripts.
-
-@item target_configargs
-@cindex @code{target_configargs}
-The contents of this variable is passed to all target @command{configure}
-scripts.
-
-@end table
-
-In order to avoid shell and @command{make} quoting issues for complex
-overrides, you can pass a setting for @env{CONFIG_SITE} and set
-variables in the site file.
-
-@subheading Objective-C-Specific Options
-
-The following options apply to the build of the Objective-C runtime library.
-
-@table @code
-@item --enable-objc-gc
-Specify that an additional variant of the GNU Objective-C runtime library
-is built, using an external build of the Boehm-Demers-Weiser garbage
-collector (@uref{https://www.hboehm.info/gc/}). This library needs to be
-available for each multilib variant, unless configured with
-@option{--enable-objc-gc=@samp{auto}} in which case the build of the
-additional runtime library is skipped when not available and the build
-continues.
-
-@item --with-target-bdw-gc=@var{list}
-@itemx --with-target-bdw-gc-include=@var{list}
-@itemx --with-target-bdw-gc-lib=@var{list}
-Specify search directories for the garbage collector header files and
-libraries. @var{list} is a comma separated list of key value pairs of the
-form @samp{@var{multilibdir}=@var{path}}, where the default multilib key
-is named as @samp{.} (dot), or is omitted (e.g.@:
-@samp{--with-target-bdw-gc=/opt/bdw-gc,32=/opt-bdw-gc32}).
-
-The options @option{--with-target-bdw-gc-include} and
-@option{--with-target-bdw-gc-lib} must always be specified together
-for each multilib variant and they take precedence over
-@option{--with-target-bdw-gc}. If @option{--with-target-bdw-gc-include}
-is missing values for a multilib, then the value for the default
-multilib is used (e.g.@: @samp{--with-target-bdw-gc-include=/opt/bdw-gc/include}
-@samp{--with-target-bdw-gc-lib=/opt/bdw-gc/lib64,32=/opt-bdw-gc/lib32}).
-If none of these options are specified, the library is assumed in
-default locations.
-@end table
-
-@subheading D-Specific Options
-
-The following options apply to the build of the D runtime library.
-
-@table @code
-@item --enable-libphobos-checking
-@itemx --disable-libphobos-checking
-@itemx --enable-libphobos-checking=@var{list}
-This option controls whether run-time checks and contracts are compiled into
-the D runtime library. When the option is not specified, the library is built
-with @samp{release} checking. When the option is specified without a
-@var{list}, the result is the same as @samp{--enable-libphobos-checking=yes}.
-Likewise, @samp{--disable-libphobos-checking} is equivalent to
-@samp{--enable-libphobos-checking=no}.
-
-The categories of checks available in @var{list} are @samp{yes} (compiles
-libphobos with @option{-fno-release}), @samp{no} (compiles libphobos with
-@option{-frelease}), @samp{all} (same as @samp{yes}), @samp{none} or
-@samp{release} (same as @samp{no}).
-
-Individual checks available in @var{list} are @samp{assert} (compiles libphobos
-with an extra option @option{-fassert}).
-
-@item --with-libphobos-druntime-only
-@itemx --with-libphobos-druntime-only=@var{choice}
-Specify whether to build only the core D runtime library (druntime), or both
-the core and standard library (phobos) into libphobos. This is useful for
-targets that have full support in druntime, but no or incomplete support
-in phobos. @var{choice} can be one of @samp{auto}, @samp{yes}, and @samp{no}
-where @samp{auto} is the default.
-
-When the option is not specified, the default choice @samp{auto} means that it
-is inferred whether the target has support for the phobos standard library.
-When the option is specified without a @var{choice}, the result is the same as
-@samp{--with-libphobos-druntime-only=yes}.
-
-@item --with-target-system-zlib
-Use installed @samp{zlib} rather than that included with GCC@. This needs
-to be available for each multilib variant, unless configured with
-@option{--with-target-system-zlib=@samp{auto}} in which case the GCC@ included
-@samp{zlib} is only used when the system installed library is not available.
-@end table
-
-@html
-<hr />
-<p>
-@end html
-@ifhtml
-@uref{./index.html,,Return to the GCC Installation page}
-@end ifhtml
-@end ifset
-
-@c ***Building****************************************************************
-@ifnothtml
-@comment node-name, next, previous, up
-@node Building, Testing, Configuration, Installing GCC
-@end ifnothtml
-@ifset buildhtml
-@ifnothtml
-@chapter Building
-@end ifnothtml
-@cindex Installing GCC: Building
-
-Now that GCC is configured, you are ready to build the compiler and
-runtime libraries.
-
-Some commands executed when making the compiler may fail (return a
-nonzero status) and be ignored by @command{make}. These failures, which
-are often due to files that were not found, are expected, and can safely
-be ignored.
-
-It is normal to have compiler warnings when compiling certain files.
-Unless you are a GCC developer, you can generally ignore these warnings
-unless they cause compilation to fail. Developers should attempt to fix
-any warnings encountered, however they can temporarily continue past
-warnings-as-errors by specifying the configure flag
-@option{--disable-werror}.
-
-On certain old systems, defining certain environment variables such as
-@env{CC} can interfere with the functioning of @command{make}.
-
-If you encounter seemingly strange errors when trying to build the
-compiler in a directory other than the source directory, it could be
-because you have previously configured the compiler in the source
-directory. Make sure you have done all the necessary preparations.
-
-If you build GCC on a BSD system using a directory stored in an old System
-V file system, problems may occur in running @command{fixincludes} if the
-System V file system doesn't support symbolic links. These problems
-result in a failure to fix the declaration of @code{size_t} in
-@file{sys/types.h}. If you find that @code{size_t} is a signed type and
-that type mismatches occur, this could be the cause.
-
-The solution is not to use such a directory for building GCC@.
-
-Similarly, when building from the source repository or snapshots, or if you modify
-@file{*.l} files, you need the Flex lexical analyzer generator
-installed. If you do not modify @file{*.l} files, releases contain
-the Flex-generated files and you do not need Flex installed to build
-them. There is still one Flex-based lexical analyzer (part of the
-build machinery, not of GCC itself) that is used even if you only
-build the C front end.
-
-When building from the source repository or snapshots, or if you modify Texinfo
-documentation, you need version 4.7 or later of Texinfo installed if you
-want Info documentation to be regenerated. Releases contain Info
-documentation pre-built for the unmodified documentation in the release.
-
-@section Building a native compiler
-
-For a native build, the default configuration is to perform
-a 3-stage bootstrap of the compiler when @samp{make} is invoked.
-This will build the entire GCC system and ensure that it compiles
-itself correctly. It can be disabled with the @option{--disable-bootstrap}
-parameter to @samp{configure}, but bootstrapping is suggested because
-the compiler will be tested more completely and could also have
-better performance.
-
-The bootstrapping process will complete the following steps:
-
-@itemize @bullet
-@item
-Build tools necessary to build the compiler.
-
-@item
-Perform a 3-stage bootstrap of the compiler. This includes building
-three times the target tools for use by the compiler such as binutils
-(bfd, binutils, gas, gprof, ld, and opcodes) if they have been
-individually linked or moved into the top level GCC source tree before
-configuring.
-
-@item
-Perform a comparison test of the stage2 and stage3 compilers.
-
-@item
-Build runtime libraries using the stage3 compiler from the previous step.
-
-@end itemize
-
-If you are short on disk space you might consider @samp{make
-bootstrap-lean} instead. The sequence of compilation is the
-same described above, but object files from the stage1 and
-stage2 of the 3-stage bootstrap of the compiler are deleted as
-soon as they are no longer needed.
-
-If you wish to use non-default GCC flags when compiling the stage2
-and stage3 compilers, set @code{BOOT_CFLAGS} on the command line when
-doing @samp{make}. For example, if you want to save additional space
-during the bootstrap and in the final installation as well, you can
-build the compiler binaries without debugging information as in the
-following example. This will save roughly 40% of disk space both for
-the bootstrap and the final installation. (Libraries will still contain
-debugging information.)
-
-@smallexample
-make BOOT_CFLAGS='-O' bootstrap
-@end smallexample
-
-You can place non-default optimization flags into @code{BOOT_CFLAGS}; they
-are less well tested here than the default of @samp{-g -O2}, but should
-still work. In a few cases, you may find that you need to specify special
-flags such as @option{-msoft-float} here to complete the bootstrap; or,
-if the native compiler miscompiles the stage1 compiler, you may need
-to work around this, by choosing @code{BOOT_CFLAGS} to avoid the parts
-of the stage1 compiler that were miscompiled, or by using @samp{make
-bootstrap4} to increase the number of stages of bootstrap.
-
-@code{BOOT_CFLAGS} does not apply to bootstrapped target libraries.
-Since these are always compiled with the compiler currently being
-bootstrapped, you can use @code{CFLAGS_FOR_TARGET} to modify their
-compilation flags, as for non-bootstrapped target libraries.
-Again, if the native compiler miscompiles the stage1 compiler, you may
-need to work around this by avoiding non-working parts of the stage1
-compiler. Use @code{STAGE1_TFLAGS} to this end.
-
-If you used the flag @option{--enable-languages=@dots{}} to restrict
-the compilers to be built, only those you've actually enabled will be
-built. This will of course only build those runtime libraries, for
-which the particular compiler has been built. Please note,
-that re-defining @env{LANGUAGES} when calling @samp{make}
-@strong{does not} work anymore!
-
-If the comparison of stage2 and stage3 fails, this normally indicates
-that the stage2 compiler has compiled GCC incorrectly, and is therefore
-a potentially serious bug which you should investigate and report. (On
-a few systems, meaningful comparison of object files is impossible; they
-always appear ``different''. If you encounter this problem, you will
-need to disable comparison in the @file{Makefile}.)
-
-If you do not want to bootstrap your compiler, you can configure with
-@option{--disable-bootstrap}. In particular cases, you may want to
-bootstrap your compiler even if the target system is not the same as
-the one you are building on: for example, you could build a
-@code{powerpc-unknown-linux-gnu} toolchain on a
-@code{powerpc64-unknown-linux-gnu} host. In this case, pass
-@option{--enable-bootstrap} to the configure script.
-
-@code{BUILD_CONFIG} can be used to bring in additional customization
-to the build. It can be set to a whitespace-separated list of names.
-For each such @code{NAME}, top-level @file{config/@code{NAME}.mk} will
-be included by the top-level @file{Makefile}, bringing in any settings
-it contains. The default @code{BUILD_CONFIG} can be set using the
-configure option @option{--with-build-config=@code{NAME}...}. Some
-examples of supported build configurations are:
-
-@table @asis
-@item @samp{bootstrap-O1}
-Removes any @option{-O}-started option from @code{BOOT_CFLAGS}, and adds
-@option{-O1} to it. @samp{BUILD_CONFIG=bootstrap-O1} is equivalent to
-@samp{BOOT_CFLAGS='-g -O1'}.
-
-@item @samp{bootstrap-O3}
-@itemx @samp{bootstrap-Og}
-Analogous to @code{bootstrap-O1}.
-
-@item @samp{bootstrap-lto}
-Enables Link-Time Optimization for host tools during bootstrapping.
-@samp{BUILD_CONFIG=bootstrap-lto} is equivalent to adding
-@option{-flto} to @samp{BOOT_CFLAGS}. This option assumes that the host
-supports the linker plugin (e.g.@: GNU ld version 2.21 or later or GNU gold
-version 2.21 or later).
-
-@item @samp{bootstrap-lto-noplugin}
-This option is similar to @code{bootstrap-lto}, but is intended for
-hosts that do not support the linker plugin. Without the linker plugin
-static libraries are not compiled with link-time optimizations. Since
-the GCC middle end and back end are in @file{libbackend.a} this means
-that only the front end is actually LTO optimized.
-
-@item @samp{bootstrap-lto-lean}
-This option is similar to @code{bootstrap-lto}, but is intended for
-faster build by only using LTO in the final bootstrap stage.
-With @samp{make profiledbootstrap} the LTO frontend
-is trained only on generator files.
-
-@item @samp{bootstrap-debug}
-Verifies that the compiler generates the same executable code, whether
-or not it is asked to emit debug information. To this end, this
-option builds stage2 host programs without debug information, and uses
-@file{contrib/compare-debug} to compare them with the stripped stage3
-object files. If @code{BOOT_CFLAGS} is overridden so as to not enable
-debug information, stage2 will have it, and stage3 won't. This option
-is enabled by default when GCC bootstrapping is enabled, if
-@code{strip} can turn object files compiled with and without debug
-info into identical object files. In addition to better test
-coverage, this option makes default bootstraps faster and leaner.
-
-@item @samp{bootstrap-debug-big}
-Rather than comparing stripped object files, as in
-@code{bootstrap-debug}, this option saves internal compiler dumps
-during stage2 and stage3 and compares them as well, which helps catch
-additional potential problems, but at a great cost in terms of disk
-space. It can be specified in addition to @samp{bootstrap-debug}.
-
-@item @samp{bootstrap-debug-lean}
-This option saves disk space compared with @code{bootstrap-debug-big},
-but at the expense of some recompilation. Instead of saving the dumps
-of stage2 and stage3 until the final compare, it uses
-@option{-fcompare-debug} to generate, compare and remove the dumps
-during stage3, repeating the compilation that already took place in
-stage2, whose dumps were not saved.
-
-@item @samp{bootstrap-debug-lib}
-This option tests executable code invariance over debug information
-generation on target libraries, just like @code{bootstrap-debug-lean}
-tests it on host programs. It builds stage3 libraries with
-@option{-fcompare-debug}, and it can be used along with any of the
-@code{bootstrap-debug} options above.
-
-There aren't @code{-lean} or @code{-big} counterparts to this option
-because most libraries are only build in stage3, so bootstrap compares
-would not get significant coverage. Moreover, the few libraries built
-in stage2 are used in stage3 host programs, so we wouldn't want to
-compile stage2 libraries with different options for comparison purposes.
-
-@item @samp{bootstrap-debug-ckovw}
-Arranges for error messages to be issued if the compiler built on any
-stage is run without the option @option{-fcompare-debug}. This is
-useful to verify the full @option{-fcompare-debug} testing coverage. It
-must be used along with @code{bootstrap-debug-lean} and
-@code{bootstrap-debug-lib}.
-
-@item @samp{bootstrap-cet}
-This option enables Intel CET for host tools during bootstrapping.
-@samp{BUILD_CONFIG=bootstrap-cet} is equivalent to adding
-@option{-fcf-protection} to @samp{BOOT_CFLAGS}. This option
-assumes that the host supports Intel CET (e.g.@: GNU assembler version
-2.30 or later).
-
-@item @samp{bootstrap-time}
-Arranges for the run time of each program started by the GCC driver,
-built in any stage, to be logged to @file{time.log}, in the top level of
-the build tree.
-
-@item @samp{bootstrap-asan}
-Compiles GCC itself using Address Sanitization in order to catch invalid memory
-accesses within the GCC code.
-
-@item @samp{bootstrap-hwasan}
-Compiles GCC itself using HWAddress Sanitization in order to catch invalid
-memory accesses within the GCC code. This option is only available on AArch64
-systems that are running Linux kernel version 5.4 or later.
-
-@end table
-
-@section Building a cross compiler
-
-When building a cross compiler, it is not generally possible to do a
-3-stage bootstrap of the compiler. This makes for an interesting problem
-as parts of GCC can only be built with GCC@.
-
-To build a cross compiler, we recommend first building and installing a
-native compiler. You can then use the native GCC compiler to build the
-cross compiler. The installed native compiler needs to be GCC version
-2.95 or later.
-
-Assuming you have already installed a native copy of GCC and configured
-your cross compiler, issue the command @command{make}, which performs the
-following steps:
-
-@itemize @bullet
-@item
-Build host tools necessary to build the compiler.
-
-@item
-Build target tools for use by the compiler such as binutils (bfd,
-binutils, gas, gprof, ld, and opcodes)
-if they have been individually linked or moved into the top level GCC source
-tree before configuring.
-
-@item
-Build the compiler (single stage only).
-
-@item
-Build runtime libraries using the compiler from the previous step.
-@end itemize
-
-Note that if an error occurs in any step the make process will exit.
-
-If you are not building GNU binutils in the same source tree as GCC,
-you will need a cross-assembler and cross-linker installed before
-configuring GCC@. Put them in the directory
-@file{@var{prefix}/@var{target}/bin}. Here is a table of the tools
-you should put in this directory:
-
-@table @file
-@item as
-This should be the cross-assembler.
-
-@item ld
-This should be the cross-linker.
-
-@item ar
-This should be the cross-archiver: a program which can manipulate
-archive files (linker libraries) in the target machine's format.
-
-@item ranlib
-This should be a program to construct a symbol table in an archive file.
-@end table
-
-The installation of GCC will find these programs in that directory,
-and copy or link them to the proper place to for the cross-compiler to
-find them when run later.
-
-The easiest way to provide these files is to build the Binutils package.
-Configure it with the same @option{--host} and @option{--target}
-options that you use for configuring GCC, then build and install
-them. They install their executables automatically into the proper
-directory. Alas, they do not support all the targets that GCC
-supports.
-
-If you are not building a C library in the same source tree as GCC,
-you should also provide the target libraries and headers before
-configuring GCC, specifying the directories with
-@option{--with-sysroot} or @option{--with-headers} and
-@option{--with-libs}. Many targets also require ``start files'' such
-as @file{crt0.o} and
-@file{crtn.o} which are linked into each executable. There may be several
-alternatives for @file{crt0.o}, for use with profiling or other
-compilation options. Check your target's definition of
-@code{STARTFILE_SPEC} to find out what start files it uses.
-
-@section Building in parallel
-
-GNU Make 3.80 and above, which is necessary to build GCC, support
-building in parallel. To activate this, you can use @samp{make -j 2}
-instead of @samp{make}. You can also specify a bigger number, and
-in most cases using a value greater than the number of processors in
-your machine will result in fewer and shorter I/O latency hits, thus
-improving overall throughput; this is especially true for slow drives
-and network filesystems.
-
-@section Building the Ada compiler
-
-@ifnothtml
-@ref{GNAT-prerequisite}.
-@end ifnothtml
-@ifhtml
-@uref{prerequisites.html#GNAT-prerequisite,,GNAT prerequisites}.
-@end ifhtml
-
-@section Building the D compiler
-
-@ifnothtml
-@ref{GDC-prerequisite}.
-@end ifnothtml
-@ifhtml
-@uref{prerequisites.html#GDC-prerequisite,,GDC prerequisites}.
-@end ifhtml
-
-@section Building with profile feedback
-
-It is possible to use profile feedback to optimize the compiler itself. This
-should result in a faster compiler binary. Experiments done on x86 using gcc
-3.3 showed approximately 7 percent speedup on compiling C programs. To
-bootstrap the compiler with profile feedback, use @code{make profiledbootstrap}.
-
-When @samp{make profiledbootstrap} is run, it will first build a @code{stage1}
-compiler. This compiler is used to build a @code{stageprofile} compiler
-instrumented to collect execution counts of instruction and branch
-probabilities. Training run is done by building @code{stagetrain}
-compiler. Finally a @code{stagefeedback} compiler is built
-using the information collected.
-
-Unlike standard bootstrap, several additional restrictions apply. The
-compiler used to build @code{stage1} needs to support a 64-bit integral type.
-It is recommended to only use GCC for this.
-
-On Linux/x86_64 hosts with some restrictions (no virtualization) it is
-also possible to do autofdo build with @samp{make
-autoprofiledback}. This uses Linux perf to sample branches in the
-binary and then rebuild it with feedback derived from the profile.
-Linux perf and the @code{autofdo} toolkit needs to be installed for
-this.
-
-Only the profile from the current build is used, so when an error
-occurs it is recommended to clean before restarting. Otherwise
-the code quality may be much worse.
-
-@html
-<hr />
-<p>
-@end html
-@ifhtml
-@uref{./index.html,,Return to the GCC Installation page}
-@end ifhtml
-@end ifset
-
-@c ***Testing*****************************************************************
-@ifnothtml
-@comment node-name, next, previous, up
-@node Testing, Final install, Building, Installing GCC
-@end ifnothtml
-@ifset testhtml
-@ifnothtml
-@chapter Installing GCC: Testing
-@end ifnothtml
-@cindex Testing
-@cindex Installing GCC: Testing
-@cindex Testsuite
-
-Before you install GCC, we encourage you to run the testsuites and to
-compare your results with results from a similar configuration that have
-been submitted to the
-@uref{https://gcc.gnu.org/ml/gcc-testresults/,,gcc-testresults mailing list}.
-Some of these archived results are linked from the build status lists
-at @uref{https://gcc.gnu.org/buildstat.html}, although not everyone who
-reports a successful build runs the testsuites and submits the results.
-This step is optional and may require you to download additional software,
-but it can give you confidence in your new GCC installation or point out
-problems before you install and start using your new GCC@.
-
-First, you must have @uref{download.html,,downloaded the testsuites}.
-These are part of the full distribution, but if you downloaded the
-``core'' compiler plus any front ends, you must download the testsuites
-separately.
-
-Second, you must have the testing tools installed. This includes
-@uref{https://www.gnu.org/software/dejagnu/,,DejaGnu}, Tcl, and Expect;
-the DejaGnu site has links to these.
-Some optional tests also require Python3 and pytest module.
-
-If the directories where @command{runtest} and @command{expect} were
-installed are not in the @env{PATH}, you may need to set the following
-environment variables appropriately, as in the following example (which
-assumes that DejaGnu has been installed under @file{/usr/local}):
-
-@smallexample
-TCL_LIBRARY = /usr/local/share/tcl8.0
-DEJAGNULIBS = /usr/local/share/dejagnu
-@end smallexample
-
-(On systems such as Cygwin, these paths are required to be actual
-paths, not mounts or links; presumably this is due to some lack of
-portability in the DejaGnu code.)
-
-
-Finally, you can run the testsuite (which may take a long time):
-@smallexample
-cd @var{objdir}; make -k check
-@end smallexample
-
-This will test various components of GCC, such as compiler
-front ends and runtime libraries. While running the testsuite, DejaGnu
-might emit some harmless messages resembling
-@samp{WARNING: Couldn't find the global config file.} or
-@samp{WARNING: Couldn't find tool init file} that can be ignored.
-
-If you are testing a cross-compiler, you may want to run the testsuite
-on a simulator as described at @uref{https://gcc.gnu.org/simtest-howto.html}.
-
-@section How can you run the testsuite on selected tests?
-
-In order to run sets of tests selectively, there are targets
-@samp{make check-gcc} and language specific @samp{make check-c},
-@samp{make check-c++}, @samp{make check-d} @samp{make check-fortran},
-@samp{make check-ada}, @samp{make check-objc}, @samp{make check-obj-c++},
-@samp{make check-lto}
-in the @file{gcc} subdirectory of the object directory. You can also
-just run @samp{make check} in a subdirectory of the object directory.
-
-
-A more selective way to just run all @command{gcc} execute tests in the
-testsuite is to use
-
-@smallexample
-make check-gcc RUNTESTFLAGS="execute.exp @var{other-options}"
-@end smallexample
-
-Likewise, in order to run only the @command{g++} ``old-deja'' tests in
-the testsuite with filenames matching @samp{9805*}, you would use
-
-@smallexample
-make check-g++ RUNTESTFLAGS="old-deja.exp=9805* @var{other-options}"
-@end smallexample
-
-The file-matching expression following @var{filename}@command{.exp=} is treated
-as a series of whitespace-delimited glob expressions so that multiple patterns
-may be passed, although any whitespace must either be escaped or surrounded by
-single quotes if multiple expressions are desired. For example,
-
-@smallexample
-make check-g++ RUNTESTFLAGS="old-deja.exp=9805*\ virtual2.c @var{other-options}"
-make check-g++ RUNTESTFLAGS="'old-deja.exp=9805* virtual2.c' @var{other-options}"
-@end smallexample
-
-The @file{*.exp} files are located in the testsuite directories of the GCC
-source, the most important ones being @file{compile.exp},
-@file{execute.exp}, @file{dg.exp} and @file{old-deja.exp}.
-To get a list of the possible @file{*.exp} files, pipe the
-output of @samp{make check} into a file and look at the
-@samp{Running @dots{} .exp} lines.
-
-@section Passing options and running multiple testsuites
-
-You can pass multiple options to the testsuite using the
-@samp{--target_board} option of DejaGNU, either passed as part of
-@samp{RUNTESTFLAGS}, or directly to @command{runtest} if you prefer to
-work outside the makefiles. For example,
-
-@smallexample
-make check-g++ RUNTESTFLAGS="--target_board=unix/-O3/-fmerge-constants"
-@end smallexample
-
-will run the standard @command{g++} testsuites (``unix'' is the target name
-for a standard native testsuite situation), passing
-@samp{-O3 -fmerge-constants} to the compiler on every test, i.e.,
-slashes separate options.
-
-You can run the testsuites multiple times using combinations of options
-with a syntax similar to the brace expansion of popular shells:
-
-@smallexample
-@dots{}"--target_board=arm-sim\@{-mhard-float,-msoft-float\@}\@{-O1,-O2,-O3,\@}"
-@end smallexample
-
-(Note the empty option caused by the trailing comma in the final group.)
-The following will run each testsuite eight times using the @samp{arm-sim}
-target, as if you had specified all possible combinations yourself:
-
-@smallexample
---target_board='arm-sim/-mhard-float/-O1 \
- arm-sim/-mhard-float/-O2 \
- arm-sim/-mhard-float/-O3 \
- arm-sim/-mhard-float \
- arm-sim/-msoft-float/-O1 \
- arm-sim/-msoft-float/-O2 \
- arm-sim/-msoft-float/-O3 \
- arm-sim/-msoft-float'
-@end smallexample
-
-They can be combined as many times as you wish, in arbitrary ways. This
-list:
-
-@smallexample
-@dots{}"--target_board=unix/-Wextra\@{-O3,-fno-strength\@}\@{-fomit-frame,\@}"
-@end smallexample
-
-will generate four combinations, all involving @samp{-Wextra}.
-
-The disadvantage to this method is that the testsuites are run in serial,
-which is a waste on multiprocessor systems. For users with GNU Make and
-a shell which performs brace expansion, you can run the testsuites in
-parallel by having the shell perform the combinations and @command{make}
-do the parallel runs. Instead of using @samp{--target_board}, use a
-special makefile target:
-
-@smallexample
-make -j@var{N} check-@var{testsuite}//@var{test-target}/@var{option1}/@var{option2}/@dots{}
-@end smallexample
-
-For example,
-
-@smallexample
-make -j3 check-gcc//sh-hms-sim/@{-m1,-m2,-m3,-m3e,-m4@}/@{,-nofpu@}
-@end smallexample
-
-will run three concurrent ``make-gcc'' testsuites, eventually testing all
-ten combinations as described above. Note that this is currently only
-supported in the @file{gcc} subdirectory. (To see how this works, try
-typing @command{echo} before the example given here.)
-
-
-@section How to interpret test results
-
-The result of running the testsuite are various @file{*.sum} and @file{*.log}
-files in the testsuite subdirectories. The @file{*.log} files contain a
-detailed log of the compiler invocations and the corresponding
-results, the @file{*.sum} files summarize the results. These summaries
-contain status codes for all tests:
-
-@itemize @bullet
-@item
-PASS: the test passed as expected
-@item
-XPASS: the test unexpectedly passed
-@item
-FAIL: the test unexpectedly failed
-@item
-XFAIL: the test failed as expected
-@item
-UNSUPPORTED: the test is not supported on this platform
-@item
-ERROR: the testsuite detected an error
-@item
-WARNING: the testsuite detected a possible problem
-@end itemize
-
-It is normal for some tests to report unexpected failures. At the
-current time the testing harness does not allow fine grained control
-over whether or not a test is expected to fail. This problem should
-be fixed in future releases.
-
-
-@section Submitting test results
-
-If you want to report the results to the GCC project, use the
-@file{contrib/test_summary} shell script. Start it in the @var{objdir} with
-
-@smallexample
-@var{srcdir}/contrib/test_summary -p your_commentary.txt \
- -m gcc-testresults@@gcc.gnu.org |sh
-@end smallexample
-
-This script uses the @command{Mail} program to send the results, so
-make sure it is in your @env{PATH}. The file @file{your_commentary.txt} is
-prepended to the testsuite summary and should contain any special
-remarks you have on your results or your build environment. Please
-do not edit the testsuite result block or the subject line, as these
-messages may be automatically processed.
-
-@html
-<hr />
-<p>
-@end html
-@ifhtml
-@uref{./index.html,,Return to the GCC Installation page}
-@end ifhtml
-@end ifset
-
-@c ***Final install***********************************************************
-@ifnothtml
-@comment node-name, next, previous, up
-@node Final install, , Testing, Installing GCC
-@end ifnothtml
-@ifset finalinstallhtml
-@ifnothtml
-@chapter Installing GCC: Final installation
-@end ifnothtml
-
-Now that GCC has been built (and optionally tested), you can install it with
-@smallexample
-cd @var{objdir} && make install
-@end smallexample
-
-We strongly recommend to install into a target directory where there is
-no previous version of GCC present. Also, the GNAT runtime should not
-be stripped, as this would break certain features of the debugger that
-depend on this debugging information (catching Ada exceptions for
-instance).
-
-That step completes the installation of GCC; user level binaries can
-be found in @file{@var{prefix}/bin} where @var{prefix} is the value
-you specified with the @option{--prefix} to configure (or
-@file{/usr/local} by default). (If you specified @option{--bindir},
-that directory will be used instead; otherwise, if you specified
-@option{--exec-prefix}, @file{@var{exec-prefix}/bin} will be used.)
-Headers for the C++ library are installed in
-@file{@var{prefix}/include}; libraries in @file{@var{libdir}}
-(normally @file{@var{prefix}/lib}); internal parts of the compiler in
-@file{@var{libdir}/gcc} and @file{@var{libexecdir}/gcc}; documentation
-in info format in @file{@var{infodir}} (normally
-@file{@var{prefix}/info}).
-
-When installing cross-compilers, GCC's executables
-are not only installed into @file{@var{bindir}}, that
-is, @file{@var{exec-prefix}/bin}, but additionally into
-@file{@var{exec-prefix}/@var{target-alias}/bin}, if that directory
-exists. Typically, such @dfn{tooldirs} hold target-specific
-binutils, including assembler and linker.
-
-Installation into a temporary staging area or into a @command{chroot}
-jail can be achieved with the command
-
-@smallexample
-make DESTDIR=@var{path-to-rootdir} install
-@end smallexample
-
-@noindent
-where @var{path-to-rootdir} is the absolute path of
-a directory relative to which all installation paths will be
-interpreted. Note that the directory specified by @code{DESTDIR}
-need not exist yet; it will be created if necessary.
-
-There is a subtle point with tooldirs and @code{DESTDIR}:
-If you relocate a cross-compiler installation with
-e.g.@: @samp{DESTDIR=@var{rootdir}}, then the directory
-@file{@var{rootdir}/@var{exec-prefix}/@var{target-alias}/bin} will
-be filled with duplicated GCC executables only if it already exists,
-it will not be created otherwise. This is regarded as a feature,
-not as a bug, because it gives slightly more control to the packagers
-using the @code{DESTDIR} feature.
-
-You can install stripped programs and libraries with
-
-@smallexample
-make install-strip
-@end smallexample
-
-If you are bootstrapping a released version of GCC then please
-quickly review the build status page for your release, available from
-@uref{https://gcc.gnu.org/buildstat.html}.
-If your system is not listed for the version of GCC that you built,
-send a note to
-@email{gcc@@gcc.gnu.org} indicating
-that you successfully built and installed GCC@.
-Include the following information:
-
-@itemize @bullet
-@item
-Output from running @file{@var{srcdir}/config.guess}. Do not send
-that file itself, just the one-line output from running it.
-
-@item
-The output of @samp{gcc -v} for your newly installed @command{gcc}.
-This tells us which version of GCC you built and the options you passed to
-configure.
-
-@item
-Whether you enabled all languages or a subset of them. If you used a
-full distribution then this information is part of the configure
-options in the output of @samp{gcc -v}, but if you downloaded the
-``core'' compiler plus additional front ends then it isn't apparent
-which ones you built unless you tell us about it.
-
-@item
-If the build was for GNU/Linux, also include:
-@itemize @bullet
-@item
-The distribution name and version (e.g., Red Hat 7.1 or Debian 2.2.3);
-this information should be available from @file{/etc/issue}.
-
-@item
-The version of the Linux kernel, available from @samp{uname --version}
-or @samp{uname -a}.
-
-@item
-The version of glibc you used; for RPM-based systems like Red Hat,
-Mandrake, and SuSE type @samp{rpm -q glibc} to get the glibc version,
-and on systems like Debian and Progeny use @samp{dpkg -l libc6}.
-@end itemize
-For other systems, you can include similar information if you think it is
-relevant.
-
-@item
-Any other information that you think would be useful to people building
-GCC on the same configuration. The new entry in the build status list
-will include a link to the archived copy of your message.
-@end itemize
-
-We'd also like to know if the
-@ifnothtml
-@ref{Specific, host/target specific installation notes}
-@end ifnothtml
-@ifhtml
-@uref{specific.html,,host/target specific installation notes}
-@end ifhtml
-didn't include your host/target information or if that information is
-incomplete or out of date. Send a note to
-@email{gcc@@gcc.gnu.org} detailing how the information should be changed.
-
-If you find a bug, please report it following the
-@uref{../bugs/,,bug reporting guidelines}.
-
-If you want to print the GCC manuals, do @samp{cd @var{objdir}; make
-dvi}. You will need to have @command{texi2dvi} (version at least 4.7)
-and @TeX{} installed. This creates a number of @file{.dvi} files in
-subdirectories of @file{@var{objdir}}; these may be converted for
-printing with programs such as @command{dvips}. Alternately, by using
-@samp{make pdf} in place of @samp{make dvi}, you can create documentation
-in the form of @file{.pdf} files; this requires @command{texi2pdf}, which
-is included with Texinfo version 4.8 and later. You can also
-@uref{https://shop.fsf.org/,,buy printed manuals from the
-Free Software Foundation}, though such manuals may not be for the most
-recent version of GCC@.
-
-If you would like to generate online HTML documentation, do @samp{cd
-@var{objdir}; make html} and HTML will be generated for the gcc manuals in
-@file{@var{objdir}/gcc/HTML}.
-
-@html
-<hr />
-<p>
-@end html
-@ifhtml
-@uref{./index.html,,Return to the GCC Installation page}
-@end ifhtml
-@end ifset
-
-@c ***Binaries****************************************************************
-@ifnothtml
-@comment node-name, next, previous, up
-@node Binaries, Specific, Installing GCC, Top
-@end ifnothtml
-@ifset binarieshtml
-@ifnothtml
-@chapter Installing GCC: Binaries
-@end ifnothtml
-@cindex Binaries
-@cindex Installing GCC: Binaries
-
-We are often asked about pre-compiled versions of GCC@. While we cannot
-provide these for all platforms, below you'll find links to binaries for
-various platforms where creating them by yourself is not easy due to various
-reasons.
-
-Please note that we did not create these binaries, nor do we
-support them. If you have any problems installing them, please
-contact their makers.
-
-@itemize
-@item
-AIX:
-@itemize
-@item
-@uref{http://www.perzl.org/aix/,,AIX Open Source Packages (AIX5L AIX 6.1
-AIX 7.1)}.
-@end itemize
-
-@item
-DOS---@uref{http://www.delorie.com/djgpp/,,DJGPP}.
-
-@item
-HP-UX:
-@itemize
-@item
-@uref{http://hpux.connect.org.uk/,,HP-UX Porting Center};
-@end itemize
-
-@item
-Solaris 2 (SPARC, Intel):
-@itemize
-@item
-@uref{https://www.opencsw.org/,,OpenCSW}
-@end itemize
-
-@item
-macOS:
-@itemize
-@item
-The @uref{https://brew.sh,,Homebrew} package manager;
-@item
-@uref{https://www.macports.org,,MacPorts}.
-@end itemize
-
-@item
-Microsoft Windows:
-@itemize
-@item
-The @uref{https://sourceware.org/cygwin/,,Cygwin} project;
-@item
-The @uref{https://osdn.net/projects/mingw/,,MinGW} and
-@uref{https://www.mingw-w64.org/,,mingw-w64} projects.
-@end itemize
-
-@item
-@uref{http://www.openpkg.org/,,OpenPKG} offers binaries for quite a
-number of platforms.
-
-@item
-The @uref{https://gcc.gnu.org/wiki/GFortranBinaries,,GFortran Wiki} has
-links to GNU Fortran binaries for several platforms.
-@end itemize
-
-@html
-<hr />
-<p>
-@end html
-@ifhtml
-@uref{./index.html,,Return to the GCC Installation page}
-@end ifhtml
-@end ifset
-
-@c ***Specific****************************************************************
-@ifnothtml
-@comment node-name, next, previous, up
-@node Specific, GNU Free Documentation License, Binaries, Top
-@end ifnothtml
-@ifset specifichtml
-@ifnothtml
-@chapter Host/target specific installation notes for GCC
-@end ifnothtml
-@cindex Specific
-@cindex Specific installation notes
-@cindex Target specific installation
-@cindex Host specific installation
-@cindex Target specific installation notes
-
-Please read this document carefully @emph{before} installing the
-GNU Compiler Collection on your machine.
-
-Note that this list of install notes is @emph{not} a list of supported
-hosts or targets. Not all supported hosts and targets are listed
-here, only the ones that require host-specific or target-specific
-information have to.
-
-@ifhtml
-@itemize
-@item
-@uref{#aarch64-x-x,,aarch64*-*-*}
-@item
-@uref{#alpha-x-x,,alpha*-*-*}
-@item
-@uref{#amdgcn-x-amdhsa,,amdgcn-*-amdhsa}
-@item
-@uref{#amd64-x-solaris2,,amd64-*-solaris2*}
-@item
-@uref{#arc-x-elf32,,arc-*-elf32}
-@item
-@uref{#arc-linux-uclibc,,arc-linux-uclibc}
-@item
-@uref{#arm-x-eabi,,arm-*-eabi}
-@item
-@uref{#avr,,avr}
-@item
-@uref{#bfin,,Blackfin}
-@item
-@uref{#cris,,cris}
-@item
-@uref{#dos,,DOS}
-@item
-@uref{#epiphany-x-elf,,epiphany-*-elf}
-@item
-@uref{#ft32-x-elf,,ft32-*-elf}
-@item
-@uref{#x-x-freebsd,,*-*-freebsd*}
-@item
-@uref{#h8300-hms,,h8300-hms}
-@item
-@uref{#hppa-hp-hpux,,hppa*-hp-hpux*}
-@item
-@uref{#hppa-hp-hpux10,,hppa*-hp-hpux10}
-@item
-@uref{#hppa-hp-hpux11,,hppa*-hp-hpux11}
-@item
-@uref{#x-x-linux-gnu,,*-*-linux-gnu}
-@item
-@uref{#ix86-x-linux,,i?86-*-linux*}
-@item
-@uref{#ix86-x-solaris2,,i?86-*-solaris2*}
-@item
-@uref{#ia64-x-linux,,ia64-*-linux}
-@item
-@uref{#ia64-x-hpux,,ia64-*-hpux*}
-@item
-@uref{#x-ibm-aix,,*-ibm-aix*}
-@item
-@uref{#iq2000-x-elf,,iq2000-*-elf}
-@item
-@uref{#loongarch,,loongarch}
-@item
-@uref{#lm32-x-elf,,lm32-*-elf}
-@item
-@uref{#lm32-x-uclinux,,lm32-*-uclinux}
-@item
-@uref{#m32c-x-elf,,m32c-*-elf}
-@item
-@uref{#m32r-x-elf,,m32r-*-elf}
-@item
-@uref{#m68k-x-x,,m68k-*-*}
-@item
-@uref{#m68k-x-uclinux,,m68k-*-uclinux}
-@item
-@uref{#microblaze-x-elf,,microblaze-*-elf}
-@item
-@uref{#mips-x-x,,mips-*-*}
-@item
-@uref{#moxie-x-elf,,moxie-*-elf}
-@item
-@uref{#msp430-x-elf,,msp430-*-elf}
-@item
-@uref{#nds32le-x-elf,,nds32le-*-elf}
-@item
-@uref{#nds32be-x-elf,,nds32be-*-elf}
-@item
-@uref{#nvptx-x-none,,nvptx-*-none}
-@item
-@uref{#or1k-x-elf,,or1k-*-elf}
-@item
-@uref{#or1k-x-linux,,or1k-*-linux}
-@item
-@uref{#powerpc-x-x,,powerpc*-*-*}
-@item
-@uref{#powerpc-x-darwin,,powerpc-*-darwin*}
-@item
-@uref{#powerpc-x-elf,,powerpc-*-elf}
-@item
-@uref{#powerpc-x-linux-gnu,,powerpc*-*-linux-gnu*}
-@item
-@uref{#powerpc-x-netbsd,,powerpc-*-netbsd*}
-@item
-@uref{#powerpc-x-eabisim,,powerpc-*-eabisim}
-@item
-@uref{#powerpc-x-eabi,,powerpc-*-eabi}
-@item
-@uref{#powerpcle-x-elf,,powerpcle-*-elf}
-@item
-@uref{#powerpcle-x-eabisim,,powerpcle-*-eabisim}
-@item
-@uref{#powerpcle-x-eabi,,powerpcle-*-eabi}
-@item
-@uref{#riscv32-x-elf,,riscv32-*-elf}
-@item
-@uref{#riscv32-x-linux,,riscv32-*-linux}
-@item
-@uref{#riscv64-x-elf,,riscv64-*-elf}
-@item
-@uref{#riscv64-x-linux,,riscv64-*-linux}
-@item
-@uref{#rl78-x-elf,,rl78-*-elf}
-@item
-@uref{#rx-x-elf,,rx-*-elf}
-@item
-@uref{#s390-x-linux,,s390-*-linux*}
-@item
-@uref{#s390x-x-linux,,s390x-*-linux*}
-@item
-@uref{#s390x-ibm-tpf,,s390x-ibm-tpf*}
-@item
-@uref{#x-x-solaris2,,*-*-solaris2*}
-@item
-@uref{#sparc-x-x,,sparc*-*-*}
-@item
-@uref{#sparc-sun-solaris2,,sparc-sun-solaris2*}
-@item
-@uref{#sparc-x-linux,,sparc-*-linux*}
-@item
-@uref{#sparc64-x-solaris2,,sparc64-*-solaris2*}
-@item
-@uref{#sparcv9-x-solaris2,,sparcv9-*-solaris2*}
-@item
-@uref{#c6x-x-x,,c6x-*-*}
-@item
-@uref{#visium-x-elf, visium-*-elf}
-@item
-@uref{#x-x-vxworks,,*-*-vxworks*}
-@item
-@uref{#x86-64-x-x,,x86_64-*-*, amd64-*-*}
-@item
-@uref{#x86-64-x-solaris2,,x86_64-*-solaris2*}
-@item
-@uref{#xtensa-x-elf,,xtensa*-*-elf}
-@item
-@uref{#xtensa-x-linux,,xtensa*-*-linux*}
-@item
-@uref{#windows,,Microsoft Windows}
-@item
-@uref{#x-x-cygwin,,*-*-cygwin}
-@item
-@uref{#x-x-mingw32,,*-*-mingw32}
-@item
-@uref{#os2,,OS/2}
-@item
-@uref{#older,,Older systems}
-@end itemize
-
-@itemize
-@item
-@uref{#elf,,all ELF targets} (SVR4, Solaris 2, etc.)
-@end itemize
-@end ifhtml
-
-
-@html
-<!-- -------- host/target specific issues start here ---------------- -->
-<hr />
-@end html
-@anchor{aarch64-x-x}
-@heading aarch64*-*-*
-Binutils pre 2.24 does not have support for selecting @option{-mabi} and
-does not support ILP32. If it is used to build GCC 4.9 or later, GCC will
-not support option @option{-mabi=ilp32}.
-
-To enable a workaround for the Cortex-A53 erratum number 835769 by default
-(for all CPUs regardless of -mcpu option given) at configure time use the
-@option{--enable-fix-cortex-a53-835769} option. This will enable the fix by
-default and can be explicitly disabled during compilation by passing the
-@option{-mno-fix-cortex-a53-835769} option. Conversely,
-@option{--disable-fix-cortex-a53-835769} will disable the workaround by
-default. The workaround is disabled by default if neither of
-@option{--enable-fix-cortex-a53-835769} or
-@option{--disable-fix-cortex-a53-835769} is given at configure time.
-
-To enable a workaround for the Cortex-A53 erratum number 843419 by default
-(for all CPUs regardless of -mcpu option given) at configure time use the
-@option{--enable-fix-cortex-a53-843419} option. This workaround is applied at
-link time. Enabling the workaround will cause GCC to pass the relevant option
-to the linker. It can be explicitly disabled during compilation by passing the
-@option{-mno-fix-cortex-a53-843419} option. Conversely,
-@option{--disable-fix-cortex-a53-843419} will disable the workaround by default.
-The workaround is disabled by default if neither of
-@option{--enable-fix-cortex-a53-843419} or
-@option{--disable-fix-cortex-a53-843419} is given at configure time.
-
-To enable Branch Target Identification Mechanism and Return Address Signing by
-default at configure time use the @option{--enable-standard-branch-protection}
-option. This is equivalent to having @option{-mbranch-protection=standard}
-during compilation. This can be explicitly disabled during compilation by
-passing the @option{-mbranch-protection=none} option which turns off all
-types of branch protections. Conversely,
-@option{--disable-standard-branch-protection} will disable both the
-protections by default. This mechanism is turned off by default if neither
-of the options are given at configure time.
-
-@html
-<hr />
-@end html
-@anchor{alpha-x-x}
-@heading alpha*-*-*
-This section contains general configuration information for all
-Alpha-based platforms using ELF@. In addition to reading this
-section, please read all other sections that match your target.
-
-@html
-<hr />
-@end html
-@anchor{amd64-x-solaris2}
-@heading amd64-*-solaris2*
-This is a synonym for @samp{x86_64-*-solaris2*}.
-
-@html
-<hr />
-@end html
-@anchor{amdgcn-x-amdhsa}
-@heading amdgcn-*-amdhsa
-AMD GCN GPU target.
-
-Instead of GNU Binutils, you will need to install LLVM 13.0.1, or later, and copy
-@file{bin/llvm-mc} to @file{amdgcn-amdhsa/bin/as},
-@file{bin/lld} to @file{amdgcn-amdhsa/bin/ld},
-@file{bin/llvm-nm} to @file{amdgcn-amdhsa/bin/nm}, and
-@file{bin/llvm-ar} to both @file{bin/amdgcn-amdhsa-ar} and
-@file{bin/amdgcn-amdhsa-ranlib}.
-
-Use Newlib (3.2.0, or newer).
-
-To run the binaries, install the HSA Runtime from the
-@uref{https://rocm.github.io,,ROCm Platform}, and use
-@file{libexec/gcc/amdhsa-amdhsa/@var{version}/gcn-run} to launch them
-on the GPU.
-
-@html
-<hr />
-@end html
-@anchor{arc-x-elf32}
-@heading arc-*-elf32
-
-Use @samp{configure --target=arc-elf32 --with-cpu=@var{cpu} --enable-languages="c,c++"}
-to configure GCC, with @var{cpu} being one of @samp{arc600}, @samp{arc601},
-or @samp{arc700}@.
-
-@html
-<hr />
-@end html
-@anchor{arc-linux-uclibc}
-@heading arc-linux-uclibc
-
-Use @samp{configure --target=arc-linux-uclibc --with-cpu=arc700 --enable-languages="c,c++"} to configure GCC@.
-
-@html
-<hr />
-@end html
-@anchor{arm-x-eabi}
-@heading arm-*-eabi
-ARM-family processors.
-
-Building the Ada frontend commonly fails (an infinite loop executing
-@code{xsinfo}) if the host compiler is GNAT 4.8. Host compilers built from the
-GNAT 4.6, 4.9 or 5 release branches are known to succeed.
-
-@html
-<hr />
-@end html
-@anchor{avr}
-@heading avr
-ATMEL AVR-family micro controllers. These are used in embedded
-applications. There are no standard Unix configurations.
-@ifnothtml
-@xref{AVR Options,, AVR Options, gcc, Using the GNU Compiler
-Collection (GCC)},
-@end ifnothtml
-@ifhtml
-See ``AVR Options'' in the main manual
-@end ifhtml
-for the list of supported MCU types.
-
-Use @samp{configure --target=avr --enable-languages="c"} to configure GCC@.
-
-Further installation notes and other useful information about AVR tools
-can also be obtained from:
-
-@itemize @bullet
-@item
-@uref{http://www.nongnu.org/avr/,,http://www.nongnu.org/avr/}
-@item
-@uref{http://www.amelek.gda.pl/avr/,,http://www.amelek.gda.pl/avr/}
-@end itemize
-
-The following error:
-@smallexample
-Error: register required
-@end smallexample
-
-indicates that you should upgrade to a newer version of the binutils.
-
-@html
-<hr />
-@end html
-@anchor{bfin}
-@heading Blackfin
-The Blackfin processor, an Analog Devices DSP.
-@ifnothtml
-@xref{Blackfin Options,, Blackfin Options, gcc, Using the GNU Compiler
-Collection (GCC)},
-@end ifnothtml
-@ifhtml
-See ``Blackfin Options'' in the main manual
-@end ifhtml
-
-More information, and a version of binutils with support for this processor,
-are available at @uref{https://sourceforge.net/projects/adi-toolchain/}.
-
-@html
-<hr />
-@end html
-@anchor{cris}
-@heading CRIS
-CRIS is a CPU architecture in Axis Communications systems-on-a-chip, for
-example the ETRAX series. These are used in embedded applications.
-
-@ifnothtml
-@xref{CRIS Options,, CRIS Options, gcc, Using the GNU Compiler
-Collection (GCC)},
-@end ifnothtml
-@ifhtml
-See ``CRIS Options'' in the main manual
-@end ifhtml
-for a list of CRIS-specific options.
-
-Use @samp{configure --target=cris-elf} to configure GCC@ for building
-a cross-compiler for CRIS.
-@html
-<hr />
-@end html
-@anchor{dos}
-@heading DOS
-Please have a look at the @uref{binaries.html,,binaries page}.
-
-You cannot install GCC by itself on MSDOS; it will not compile under
-any MSDOS compiler except itself. You need to get the complete
-compilation package DJGPP, which includes binaries as well as sources,
-and includes all the necessary compilation tools and libraries.
-
-@html
-<hr />
-@end html
-@anchor{epiphany-x-elf}
-@heading epiphany-*-elf
-Adapteva Epiphany.
-This configuration is intended for embedded systems.
-
-@html
-<hr />
-@end html
-@anchor{x-x-freebsd}
-@heading *-*-freebsd*
-In order to better utilize FreeBSD base system functionality and match
-the configuration of the system compiler, GCC 4.5 and above as well as
-GCC 4.4 past 2010-06-20 leverage SSP support in libc (which is present
-on FreeBSD 7 or later) and the use of @code{__cxa_atexit} by default
-(on FreeBSD 6 or later). The use of @code{dl_iterate_phdr} inside
-@file{libgcc_s.so.1} and boehm-gc (on FreeBSD 7 or later) is enabled
-by GCC 4.5 and above.
-
-We support FreeBSD using the ELF file format with DWARF 2 debugging
-for all CPU architectures. There are
-no known issues with mixing object files and libraries with different
-debugging formats. Otherwise, this release of GCC should now match
-more of the configuration used in the stock FreeBSD configuration of
-GCC@. In particular, @option{--enable-threads} is now configured by
-default. However, as a general user, do not attempt to replace the
-system compiler with this release. Known to bootstrap and check with
-good results on FreeBSD 7.2-STABLE@. In the past, known to bootstrap
-and check with good results on FreeBSD 3.0, 3.4, 4.0, 4.2, 4.3, 4.4,
-4.5, 4.8, 4.9 and 5-CURRENT@.
-
-The version of binutils installed in @file{/usr/bin} probably works
-with this release of GCC@. Bootstrapping against the latest GNU
-binutils and/or the version found in @file{/usr/ports/devel/binutils} has
-been known to enable additional features and improve overall testsuite
-results. However, it is currently known that boehm-gc may not configure
-properly on FreeBSD prior to the FreeBSD 7.0 release with GNU binutils
-after 2.16.1.
-
-@html
-<hr />
-@end html
-@anchor{ft32-x-elf}
-@heading ft32-*-elf
-The FT32 processor.
-This configuration is intended for embedded systems.
-
-@html
-<hr />
-@end html
-@anchor{h8300-hms}
-@heading h8300-hms
-Renesas H8/300 series of processors.
-
-Please have a look at the @uref{binaries.html,,binaries page}.
-
-The calling convention and structure layout has changed in release 2.6.
-All code must be recompiled. The calling convention now passes the
-first three arguments in function calls in registers. Structures are no
-longer a multiple of 2 bytes.
-
-@html
-<hr />
-@end html
-@anchor{hppa-hp-hpux}
-@heading hppa*-hp-hpux*
-Support for HP-UX version 9 and older was discontinued in GCC 3.4.
-
-We require using gas/binutils on all hppa platforms. Version 2.19 or
-later is recommended.
-
-It may be helpful to configure GCC with the
-@uref{./configure.html#with-gnu-as,,@option{--with-gnu-as}} and
-@option{--with-as=@dots{}} options to ensure that GCC can find GAS@.
-
-The HP assembler should not be used with GCC. It is rarely tested and may
-not work. It shouldn't be used with any languages other than C due to its
-many limitations.
-
-Specifically, @option{-g} does not work (HP-UX uses a peculiar debugging
-format which GCC does not know about). It also inserts timestamps
-into each object file it creates, causing the 3-stage comparison test to
-fail during a bootstrap. You should be able to continue by saying
-@samp{make all-host all-target} after getting the failure from @samp{make}.
-
-Various GCC features are not supported. For example, it does not support weak
-symbols or alias definitions. As a result, explicit template instantiations
-are required when using C++. This makes it difficult if not impossible to
-build many C++ applications.
-
-There are two default scheduling models for instructions. These are
-PROCESSOR_7100LC and PROCESSOR_8000. They are selected from the pa-risc
-architecture specified for the target machine when configuring.
-PROCESSOR_8000 is the default. PROCESSOR_7100LC is selected when
-the target is a @samp{hppa1*} machine.
-
-The PROCESSOR_8000 model is not well suited to older processors. Thus,
-it is important to completely specify the machine architecture when
-configuring if you want a model other than PROCESSOR_8000. The macro
-TARGET_SCHED_DEFAULT can be defined in BOOT_CFLAGS if a different
-default scheduling model is desired.
-
-As of GCC 4.0, GCC uses the UNIX 95 namespace for HP-UX 10.10
-through 11.00, and the UNIX 98 namespace for HP-UX 11.11 and later.
-This namespace change might cause problems when bootstrapping with
-an earlier version of GCC or the HP compiler as essentially the same
-namespace is required for an entire build. This problem can be avoided
-in a number of ways. With HP cc, @env{UNIX_STD} can be set to @samp{95}
-or @samp{98}. Another way is to add an appropriate set of predefines
-to @env{CC}. The description for the @option{munix=} option contains
-a list of the predefines used with each standard.
-
-More specific information to @samp{hppa*-hp-hpux*} targets follows.
-
-@html
-<hr />
-@end html
-@anchor{hppa-hp-hpux10}
-@heading hppa*-hp-hpux10
-For hpux10.20, we @emph{highly} recommend you pick up the latest sed patch
-@code{PHCO_19798} from HP@.
-
-The C++ ABI has changed incompatibly in GCC 4.0. COMDAT subspaces are
-used for one-only code and data. This resolves many of the previous
-problems in using C++ on this target. However, the ABI is not compatible
-with the one implemented under HP-UX 11 using secondary definitions.
-
-@html
-<hr />
-@end html
-@anchor{hppa-hp-hpux11}
-@heading hppa*-hp-hpux11
-GCC 3.0 and up support HP-UX 11. GCC 2.95.x is not supported and cannot
-be used to compile GCC 3.0 and up.
-
-The libffi library haven't been ported to 64-bit HP-UX@ and doesn't build.
-
-Refer to @uref{binaries.html,,binaries} for information about obtaining
-precompiled GCC binaries for HP-UX@. Precompiled binaries must be obtained
-to build the Ada language as it cannot be bootstrapped using C@. Ada is
-only available for the 32-bit PA-RISC runtime.
-
-Starting with GCC 3.4 an ISO C compiler is required to bootstrap. The
-bundled compiler supports only traditional C; you will need either HP's
-unbundled compiler, or a binary distribution of GCC@.
-
-It is possible to build GCC 3.3 starting with the bundled HP compiler,
-but the process requires several steps. GCC 3.3 can then be used to
-build later versions.
-
-There are several possible approaches to building the distribution.
-Binutils can be built first using the HP tools. Then, the GCC
-distribution can be built. The second approach is to build GCC
-first using the HP tools, then build binutils, then rebuild GCC@.
-There have been problems with various binary distributions, so it
-is best not to start from a binary distribution.
-
-On 64-bit capable systems, there are two distinct targets. Different
-installation prefixes must be used if both are to be installed on
-the same system. The @samp{hppa[1-2]*-hp-hpux11*} target generates code
-for the 32-bit PA-RISC runtime architecture and uses the HP linker.
-The @samp{hppa64-hp-hpux11*} target generates 64-bit code for the
-PA-RISC 2.0 architecture.
-
-The script config.guess now selects the target type based on the compiler
-detected during configuration. You must define @env{PATH} or @env{CC} so
-that configure finds an appropriate compiler for the initial bootstrap.
-When @env{CC} is used, the definition should contain the options that are
-needed whenever @env{CC} is used.
-
-Specifically, options that determine the runtime architecture must be
-in @env{CC} to correctly select the target for the build. It is also
-convenient to place many other compiler options in @env{CC}. For example,
-@env{CC="cc -Ac +DA2.0W -Wp,-H16376 -D_CLASSIC_TYPES -D_HPUX_SOURCE"}
-can be used to bootstrap the GCC 3.3 branch with the HP compiler in
-64-bit K&R/bundled mode. The @option{+DA2.0W} option will result in
-the automatic selection of the @samp{hppa64-hp-hpux11*} target. The
-macro definition table of cpp needs to be increased for a successful
-build with the HP compiler. _CLASSIC_TYPES and _HPUX_SOURCE need to
-be defined when building with the bundled compiler, or when using the
-@option{-Ac} option. These defines aren't necessary with @option{-Ae}.
-
-It is best to explicitly configure the @samp{hppa64-hp-hpux11*} target
-with the @option{--with-ld=@dots{}} option. This overrides the standard
-search for ld. The two linkers supported on this target require different
-commands. The default linker is determined during configuration. As a
-result, it's not possible to switch linkers in the middle of a GCC build.
-This has been reported to sometimes occur in unified builds of binutils
-and GCC@.
-
-A recent linker patch must be installed for the correct operation of
-GCC 3.3 and later. @code{PHSS_26559} and @code{PHSS_24304} are the
-oldest linker patches that are known to work. They are for HP-UX
-11.00 and 11.11, respectively. @code{PHSS_24303}, the companion to
-@code{PHSS_24304}, might be usable but it hasn't been tested. These
-patches have been superseded. Consult the HP patch database to obtain
-the currently recommended linker patch for your system.
-
-The patches are necessary for the support of weak symbols on the
-32-bit port, and for the running of initializers and finalizers. Weak
-symbols are implemented using SOM secondary definition symbols. Prior
-to HP-UX 11, there are bugs in the linker support for secondary symbols.
-The patches correct a problem of linker core dumps creating shared
-libraries containing secondary symbols, as well as various other
-linking issues involving secondary symbols.
-
-GCC 3.3 uses the ELF DT_INIT_ARRAY and DT_FINI_ARRAY capabilities to
-run initializers and finalizers on the 64-bit port. The 32-bit port
-uses the linker @option{+init} and @option{+fini} options for the same
-purpose. The patches correct various problems with the +init/+fini
-options, including program core dumps. Binutils 2.14 corrects a
-problem on the 64-bit port resulting from HP's non-standard use of
-the .init and .fini sections for array initializers and finalizers.
-
-Although the HP and GNU linkers are both supported for the
-@samp{hppa64-hp-hpux11*} target, it is strongly recommended that the
-HP linker be used for link editing on this target.
-
-At this time, the GNU linker does not support the creation of long
-branch stubs. As a result, it cannot successfully link binaries
-containing branch offsets larger than 8 megabytes. In addition,
-there are problems linking shared libraries, linking executables
-with @option{-static}, and with dwarf2 unwind and exception support.
-It also doesn't provide stubs for internal calls to global functions
-in shared libraries, so these calls cannot be overloaded.
-
-The HP dynamic loader does not support GNU symbol versioning, so symbol
-versioning is not supported. It may be necessary to disable symbol
-versioning with @option{--disable-symvers} when using GNU ld.
-
-POSIX threads are the default. The optional DCE thread library is not
-supported, so @option{--enable-threads=dce} does not work.
-
-@html
-<hr />
-@end html
-@anchor{x-x-linux-gnu}
-@heading *-*-linux-gnu
-The @code{.init_array} and @code{.fini_array} sections are enabled
-unconditionally which requires at least glibc 2.1 and binutils 2.12.
-
-Versions of libstdc++-v3 starting with 3.2.1 require bug fixes present
-in glibc 2.2.5 and later. More information is available in the
-libstdc++-v3 documentation.
-
-@html
-<hr />
-@end html
-@anchor{ix86-x-linux}
-@heading i?86-*-linux*
-As of GCC 3.3, binutils 2.13.1 or later is required for this platform.
-See @uref{https://gcc.gnu.org/PR10877,,bug 10877} for more information.
-
-If you receive Signal 11 errors when building on GNU/Linux, then it is
-possible you have a hardware problem. Further information on this can be
-found on @uref{https://www.bitwizard.nl/sig11/,,www.bitwizard.nl}.
-
-@html
-<hr />
-@end html
-@anchor{ix86-x-solaris2}
-@heading i?86-*-solaris2*
-Use this for Solaris 11.3 or later on x86 and x86-64 systems. Starting
-with GCC 4.7, there is also a 64-bit @samp{amd64-*-solaris2*} or
-@samp{x86_64-*-solaris2*} configuration that corresponds to
-@samp{sparcv9-sun-solaris2*}.
-
-It is recommended that you configure GCC to use the GNU assembler. The
-versions included in Solaris 11.3, from GNU binutils 2.23.1 or
-newer (available as @file{/usr/bin/gas} and
-@file{/usr/gnu/bin/as}), work fine. The current version, from GNU
-binutils 2.34, is known to work. Recent versions of the Solaris assembler in
-@file{/usr/bin/as} work almost as well, though.
-
-For linking, the Solaris linker is preferred. If you want to use the GNU
-linker instead, the version in Solaris 11.3, from GNU binutils 2.23.1 or
-newer (in @file{/usr/gnu/bin/ld} and @file{/usr/bin/gld}), works,
-as does the latest version, from GNU binutils 2.34.
-
-To use GNU @command{as}, configure with the options
-@option{--with-gnu-as --with-as=@//usr/@/gnu/@/bin/@/as}. It may be necessary
-to configure with @option{--without-gnu-ld --with-ld=@//usr/@/ccs/@/bin/@/ld} to
-guarantee use of Solaris @command{ld}.
-@c FIXME: why --without-gnu-ld --with-ld?
-
-@html
-<hr />
-@end html
-@anchor{ia64-x-linux}
-@heading ia64-*-linux
-IA-64 processor (also known as IPF, or Itanium Processor Family)
-running GNU/Linux.
-
-If you are using the installed system libunwind library with
-@option{--with-system-libunwind}, then you must use libunwind 0.98 or
-later.
-
-@html
-<hr />
-@end html
-@anchor{ia64-x-hpux}
-@heading ia64-*-hpux*
-Building GCC on this target requires the GNU Assembler. The bundled HP
-assembler will not work. To prevent GCC from using the wrong assembler,
-the option @option{--with-gnu-as} may be necessary.
-
-The GCC libunwind library has not been ported to HPUX@. This means that for
-GCC versions 3.2.3 and earlier, @option{--enable-libunwind-exceptions}
-is required to build GCC@. For GCC 3.3 and later, this is the default.
-For gcc 3.4.3 and later, @option{--enable-libunwind-exceptions} is
-removed and the system libunwind library will always be used.
-
-@html
-<hr />
-<!-- rs6000-ibm-aix*, powerpc-ibm-aix* -->
-@end html
-@anchor{x-ibm-aix}
-@heading *-ibm-aix*
-Support for AIX version 3 and older was discontinued in GCC 3.4.
-Support for AIX version 4.2 and older was discontinued in GCC 4.5.
-
-``out of memory'' bootstrap failures may indicate a problem with
-process resource limits (ulimit). Hard limits are configured in the
-@file{/etc/security/limits} system configuration file.
-
-GCC 4.9 and above require a C++ compiler for bootstrap. IBM VAC++ / xlC
-cannot bootstrap GCC. xlc can bootstrap an older version of GCC and
-G++ can bootstrap recent releases of GCC.
-
-GCC can bootstrap with recent versions of IBM XLC, but bootstrapping
-with an earlier release of GCC is recommended. Bootstrapping with XLC
-requires a larger data segment, which can be enabled through the
-@var{LDR_CNTRL} environment variable, e.g.,
-
-@smallexample
-% LDR_CNTRL=MAXDATA=0x50000000
-% export LDR_CNTRL
-@end smallexample
-
-One can start with a pre-compiled version of GCC to build from
-sources. One may delete GCC's ``fixed'' header files when starting
-with a version of GCC built for an earlier release of AIX.
-
-To speed up the configuration phases of bootstrapping and installing GCC,
-one may use GNU Bash instead of AIX @command{/bin/sh}, e.g.,
-
-@smallexample
-% CONFIG_SHELL=/opt/freeware/bin/bash
-% export CONFIG_SHELL
-@end smallexample
-
-and then proceed as described in @uref{build.html,,the build
-instructions}, where we strongly recommend specifying an absolute path
-to invoke @var{srcdir}/configure.
-
-Because GCC on AIX is built as a 32-bit executable by default,
-(although it can generate 64-bit programs) the GMP and MPFR libraries
-required by gfortran must be 32-bit libraries. Building GMP and MPFR
-as static archive libraries works better than shared libraries.
-
-Errors involving @code{alloca} when building GCC generally are due
-to an incorrect definition of @code{CC} in the Makefile or mixing files
-compiled with the native C compiler and GCC@. During the stage1 phase of
-the build, the native AIX compiler @strong{must} be invoked as @command{cc}
-(not @command{xlc}). Once @command{configure} has been informed of
-@command{xlc}, one needs to use @samp{make distclean} to remove the
-configure cache files and ensure that @env{CC} environment variable
-does not provide a definition that will confuse @command{configure}.
-If this error occurs during stage2 or later, then the problem most likely
-is the version of Make (see above).
-
-The native @command{as} and @command{ld} are recommended for
-bootstrapping on AIX@. The GNU Assembler, GNU Linker, and GNU
-Binutils version 2.20 is the minimum level that supports bootstrap on
-AIX 5@. The GNU Assembler has not been updated to support AIX 6@ or
-AIX 7. The native AIX tools do interoperate with GCC@.
-
-AIX 7.1 added partial support for DWARF debugging, but full support
-requires AIX 7.1 TL03 SP7 that supports additional DWARF sections and
-fixes a bug in the assembler. AIX 7.1 TL03 SP5 distributed a version
-of libm.a missing important symbols; a fix for IV77796 will be
-included in SP6.
-
-AIX 5.3 TL10, AIX 6.1 TL05 and AIX 7.1 TL00 introduced an AIX
-assembler change that sometimes produces corrupt assembly files
-causing AIX linker errors. The bug breaks GCC bootstrap on AIX and
-can cause compilation failures with existing GCC installations. An
-AIX iFix for AIX 5.3 is available (APAR IZ98385 for AIX 5.3 TL10, APAR
-IZ98477 for AIX 5.3 TL11 and IZ98134 for AIX 5.3 TL12). AIX 5.3 TL11 SP8,
-AIX 5.3 TL12 SP5, AIX 6.1 TL04 SP11, AIX 6.1 TL05 SP7, AIX 6.1 TL06 SP6,
-AIX 6.1 TL07 and AIX 7.1 TL01 should include the fix.
-
-Building @file{libstdc++.a} requires a fix for an AIX Assembler bug
-APAR IY26685 (AIX 4.3) or APAR IY25528 (AIX 5.1). It also requires a
-fix for another AIX Assembler bug and a co-dependent AIX Archiver fix
-referenced as APAR IY53606 (AIX 5.2) or as APAR IY54774 (AIX 5.1)
-
-@anchor{TransferAixShobj}
-@samp{libstdc++} in GCC 3.4 increments the major version number of the
-shared object and GCC installation places the @file{libstdc++.a}
-shared library in a common location which will overwrite the and GCC
-3.3 version of the shared library. Applications either need to be
-re-linked against the new shared library or the GCC 3.1 and GCC 3.3
-versions of the @samp{libstdc++} shared object needs to be available
-to the AIX runtime loader. The GCC 3.1 @samp{libstdc++.so.4}, if
-present, and GCC 3.3 @samp{libstdc++.so.5} shared objects can be
-installed for runtime dynamic loading using the following steps to set
-the @samp{F_LOADONLY} flag in the shared object for @emph{each}
-multilib @file{libstdc++.a} installed:
-
-Extract the shared objects from the currently installed
-@file{libstdc++.a} archive:
-@smallexample
-% ar -x libstdc++.a libstdc++.so.4 libstdc++.so.5
-@end smallexample
-
-Enable the @samp{F_LOADONLY} flag so that the shared object will be
-available for runtime dynamic loading, but not linking:
-@smallexample
-% strip -e libstdc++.so.4 libstdc++.so.5
-@end smallexample
-
-Archive the runtime-only shared object in the GCC 3.4
-@file{libstdc++.a} archive:
-@smallexample
-% ar -q libstdc++.a libstdc++.so.4 libstdc++.so.5
-@end smallexample
-
-Eventually, the
-@uref{./configure.html#WithAixSoname,,@option{--with-aix-soname=svr4}}
-configure option may drop the need for this procedure for libraries that
-support it.
-
-Linking executables and shared libraries may produce warnings of
-duplicate symbols. The assembly files generated by GCC for AIX always
-have included multiple symbol definitions for certain global variable
-and function declarations in the original program. The warnings should
-not prevent the linker from producing a correct library or runnable
-executable.
-
-AIX 4.3 utilizes a ``large format'' archive to support both 32-bit and
-64-bit object modules. The routines provided in AIX 4.3.0 and AIX 4.3.1
-to parse archive libraries did not handle the new format correctly.
-These routines are used by GCC and result in error messages during
-linking such as ``not a COFF file''. The version of the routines shipped
-with AIX 4.3.1 should work for a 32-bit environment. The @option{-g}
-option of the archive command may be used to create archives of 32-bit
-objects using the original ``small format''. A correct version of the
-routines is shipped with AIX 4.3.2 and above.
-
-Some versions of the AIX binder (linker) can fail with a relocation
-overflow severe error when the @option{-bbigtoc} option is used to link
-GCC-produced object files into an executable that overflows the TOC@. A fix
-for APAR IX75823 (OVERFLOW DURING LINK WHEN USING GCC AND -BBIGTOC) is
-available from IBM Customer Support and from its
-@uref{https://techsupport.services.ibm.com/,,techsupport.services.ibm.com}
-website as PTF U455193.
-
-The AIX 4.3.2.1 linker (bos.rte.bind_cmds Level 4.3.2.1) will dump core
-with a segmentation fault when invoked by any version of GCC@. A fix for
-APAR IX87327 is available from IBM Customer Support and from its
-@uref{https://techsupport.services.ibm.com/,,techsupport.services.ibm.com}
-website as PTF U461879. This fix is incorporated in AIX 4.3.3 and above.
-
-The initial assembler shipped with AIX 4.3.0 generates incorrect object
-files. A fix for APAR IX74254 (64BIT DISASSEMBLED OUTPUT FROM COMPILER FAILS
-TO ASSEMBLE/BIND) is available from IBM Customer Support and from its
-@uref{https://techsupport.services.ibm.com/,,techsupport.services.ibm.com}
-website as PTF U453956. This fix is incorporated in AIX 4.3.1 and above.
-
-AIX provides National Language Support (NLS)@. Compilers and assemblers
-use NLS to support locale-specific representations of various data
-formats including floating-point numbers (e.g., @samp{.} vs @samp{,} for
-separating decimal fractions). There have been problems reported where
-GCC does not produce the same floating-point formats that the assembler
-expects. If one encounters this problem, set the @env{LANG}
-environment variable to @samp{C} or @samp{En_US}.
-
-A default can be specified with the @option{-mcpu=@var{cpu_type}}
-switch and using the configure option @option{--with-cpu-@var{cpu_type}}.
-
-@html
-<hr />
-@end html
-@anchor{iq2000-x-elf}
-@heading iq2000-*-elf
-Vitesse IQ2000 processors. These are used in embedded
-applications. There are no standard Unix configurations.
-
-@html
-<hr />
-@end html
-@anchor{lm32-x-elf}
-@heading lm32-*-elf
-Lattice Mico32 processor.
-This configuration is intended for embedded systems.
-
-@html
-<hr />
-@end html
-@anchor{lm32-x-uclinux}
-@heading lm32-*-uclinux
-Lattice Mico32 processor.
-This configuration is intended for embedded systems running uClinux.
-
-@html
-<hr />
-@end html
-@anchor{loongarch}
-@heading LoongArch
-LoongArch processor.
-The following LoongArch targets are available:
-@table @code
-@item loongarch64-linux-gnu*
-LoongArch processor running GNU/Linux. This target triplet may be coupled
-with a small set of possible suffixes to identify their default ABI type:
-@table @code
-@item f64
-Uses @code{lp64d/base} ABI by default.
-@item f32
-Uses @code{lp64f/base} ABI by default.
-@item sf
-Uses @code{lp64s/base} ABI by default.
-@end table
-
-@item loongarch64-linux-gnu
-Same as @code{loongarch64-linux-gnuf64}, but may be used with
-@option{--with-abi=*} to configure the default ABI type.
-@end table
-
-More information about LoongArch can be found at
-@uref{https://github.com/loongson/LoongArch-Documentation}.
-
-@html
-<hr />
-@end html
-@anchor{m32c-x-elf}
-@heading m32c-*-elf
-Renesas M32C processor.
-This configuration is intended for embedded systems.
-
-@html
-<hr />
-@end html
-@anchor{m32r-x-elf}
-@heading m32r-*-elf
-Renesas M32R processor.
-This configuration is intended for embedded systems.
-
-@html
-<hr />
-@end html
-@anchor{m68k-x-x}
-@heading m68k-*-*
-By default,
-@samp{m68k-*-elf*}, @samp{m68k-*-rtems}, @samp{m68k-*-uclinux} and
-@samp{m68k-*-linux}
-build libraries for both M680x0 and ColdFire processors. If you only
-need the M680x0 libraries, you can omit the ColdFire ones by passing
-@option{--with-arch=m68k} to @command{configure}. Alternatively, you
-can omit the M680x0 libraries by passing @option{--with-arch=cf} to
-@command{configure}. These targets default to 5206 or 5475 code as
-appropriate for the target system when
-configured with @option{--with-arch=cf} and 68020 code otherwise.
-
-The @samp{m68k-*-netbsd} and
-@samp{m68k-*-openbsd} targets also support the @option{--with-arch}
-option. They will generate ColdFire CFV4e code when configured with
-@option{--with-arch=cf} and 68020 code otherwise.
-
-You can override the default processors listed above by configuring
-with @option{--with-cpu=@var{target}}. This @var{target} can either
-be a @option{-mcpu} argument or one of the following values:
-@samp{m68000}, @samp{m68010}, @samp{m68020}, @samp{m68030},
-@samp{m68040}, @samp{m68060}, @samp{m68020-40} and @samp{m68020-60}.
-
-GCC requires at least binutils version 2.17 on these targets.
-
-@html
-<hr />
-@end html
-@anchor{m68k-x-uclinux}
-@heading m68k-*-uclinux
-GCC 4.3 changed the uClinux configuration so that it uses the
-@samp{m68k-linux-gnu} ABI rather than the @samp{m68k-elf} ABI.
-It also added improved support for C++ and flat shared libraries,
-both of which were ABI changes.
-
-@html
-<hr />
-@end html
-@anchor{microblaze-x-elf}
-@heading microblaze-*-elf
-Xilinx MicroBlaze processor.
-This configuration is intended for embedded systems.
-
-@html
-<hr />
-@end html
-@anchor{mips-x-x}
-@heading mips-*-*
-If on a MIPS system you get an error message saying ``does not have gp
-sections for all it's [sic] sectons [sic]'', don't worry about it. This
-happens whenever you use GAS with the MIPS linker, but there is not
-really anything wrong, and it is okay to use the output file. You can
-stop such warnings by installing the GNU linker.
-
-It would be nice to extend GAS to produce the gp tables, but they are
-optional, and there should not be a warning about their absence.
-
-The libstdc++ atomic locking routines for MIPS targets requires MIPS II
-and later. A patch went in just after the GCC 3.3 release to
-make @samp{mips*-*-*} use the generic implementation instead. You can also
-configure for @samp{mipsel-elf} as a workaround. The
-@samp{mips*-*-linux*} target continues to use the MIPS II routines. More
-work on this is expected in future releases.
-
-@c If you make --with-llsc the default for another target, please also
-@c update the description of the --with-llsc option.
-
-The built-in @code{__sync_*} functions are available on MIPS II and
-later systems and others that support the @samp{ll}, @samp{sc} and
-@samp{sync} instructions. This can be overridden by passing
-@option{--with-llsc} or @option{--without-llsc} when configuring GCC.
-Since the Linux kernel emulates these instructions if they are
-missing, the default for @samp{mips*-*-linux*} targets is
-@option{--with-llsc}. The @option{--with-llsc} and
-@option{--without-llsc} configure options may be overridden at compile
-time by passing the @option{-mllsc} or @option{-mno-llsc} options to
-the compiler.
-
-MIPS systems check for division by zero (unless
-@option{-mno-check-zero-division} is passed to the compiler) by
-generating either a conditional trap or a break instruction. Using
-trap results in smaller code, but is only supported on MIPS II and
-later. Also, some versions of the Linux kernel have a bug that
-prevents trap from generating the proper signal (@code{SIGFPE}). To enable
-the use of break, use the @option{--with-divide=breaks}
-@command{configure} option when configuring GCC@. The default is to
-use traps on systems that support them.
-
-@html
-<hr />
-@end html
-@anchor{moxie-x-elf}
-@heading moxie-*-elf
-The moxie processor.
-
-@html
-<hr />
-@end html
-@anchor{msp430-x-elf}
-@heading msp430-*-elf*
-TI MSP430 processor.
-This configuration is intended for embedded systems.
-
-@samp{msp430-*-elf} is the standard configuration with most GCC
-features enabled by default.
-
-@samp{msp430-*-elfbare} is tuned for a bare-metal environment, and disables
-features related to shared libraries and other functionality not used for
-this device. This reduces code and data usage of the GCC libraries, resulting
-in a minimal run-time environment by default.
-
-Features disabled by default include:
-@itemize
-@item transactional memory
-@item __cxa_atexit
-@end itemize
-
-@html
-<hr />
-@end html
-@anchor{nds32le-x-elf}
-@heading nds32le-*-elf
-Andes NDS32 target in little endian mode.
-
-@html
-<hr />
-@end html
-@anchor{nds32be-x-elf}
-@heading nds32be-*-elf
-Andes NDS32 target in big endian mode.
-
-@html
-<hr />
-@end html
-@anchor{nvptx-x-none}
-@heading nvptx-*-none
-Nvidia PTX target.
-
-Instead of GNU binutils, you will need to install
-@uref{https://github.com/MentorEmbedded/nvptx-tools/,,nvptx-tools}.
-Tell GCC where to find it:
-@option{--with-build-time-tools=[install-nvptx-tools]/nvptx-none/bin}.
-
-You will need newlib 3.1.0 or later. It can be
-automatically built together with GCC@. For this, add a symbolic link
-to nvptx-newlib's @file{newlib} directory to the directory containing
-the GCC sources.
-
-Use the @option{--disable-sjlj-exceptions} and
-@option{--enable-newlib-io-long-long} options when configuring.
-
-The @option{--with-arch} option may be specified to override the
-default value for the @option{-march} option, and to also build
-corresponding target libraries.
-The default is @option{--with-arch=sm_30}.
-
-For example, if @option{--with-arch=sm_70} is specified,
-@option{-march=sm_30} and @option{-march=sm_70} target libraries are
-built, and code generation defaults to @option{-march=sm_70}.
-
-@html
-<hr />
-@end html
-@anchor{or1k-x-elf}
-@heading or1k-*-elf
-The OpenRISC 1000 32-bit processor with delay slots.
-This configuration is intended for embedded systems.
-
-@html
-<hr />
-@end html
-@anchor{or1k-x-linux}
-@heading or1k-*-linux
-The OpenRISC 1000 32-bit processor with delay slots.
-
-@html
-<hr />
-@end html
-@anchor{powerpc-x-x}
-@heading powerpc-*-*
-You can specify a default version for the @option{-mcpu=@var{cpu_type}}
-switch by using the configure option @option{--with-cpu-@var{cpu_type}}.
-
-You will need GNU binutils 2.20 or newer.
-
-@html
-<hr />
-@end html
-@anchor{powerpc-x-darwin}
-@heading powerpc-*-darwin*
-PowerPC running Darwin (Mac OS X kernel).
-
-Pre-installed versions of Mac OS X may not include any developer tools,
-meaning that you will not be able to build GCC from source. Tool
-binaries are available at
-@uref{https://opensource.apple.com}.
-
-This version of GCC requires at least cctools-590.36. The
-cctools-590.36 package referenced from
-@uref{https://gcc.gnu.org/ml/gcc/2006-03/msg00507.html} will not work
-on systems older than 10.3.9 (aka darwin7.9.0).
-
-@html
-<hr />
-@end html
-@anchor{powerpc-x-elf}
-@heading powerpc-*-elf
-PowerPC system in big endian mode, running System V.4.
-
-@html
-<hr />
-@end html
-@anchor{powerpc-x-linux-gnu}
-@heading powerpc*-*-linux-gnu*
-PowerPC system in big endian mode running Linux.
-
-@html
-<hr />
-@end html
-@anchor{powerpc-x-netbsd}
-@heading powerpc-*-netbsd*
-PowerPC system in big endian mode running NetBSD@.
-
-@html
-<hr />
-@end html
-@anchor{powerpc-x-eabisim}
-@heading powerpc-*-eabisim
-Embedded PowerPC system in big endian mode for use in running under the
-PSIM simulator.
-
-@html
-<hr />
-@end html
-@anchor{powerpc-x-eabi}
-@heading powerpc-*-eabi
-Embedded PowerPC system in big endian mode.
-
-@html
-<hr />
-@end html
-@anchor{powerpcle-x-elf}
-@heading powerpcle-*-elf
-PowerPC system in little endian mode, running System V.4.
-
-@html
-<hr />
-@end html
-@anchor{powerpcle-x-eabisim}
-@heading powerpcle-*-eabisim
-Embedded PowerPC system in little endian mode for use in running under
-the PSIM simulator.
-
-@html
-<hr />
-@end html
-@anchor{powerpcle-x-eabi}
-@heading powerpcle-*-eabi
-Embedded PowerPC system in little endian mode.
-
-@html
-<hr />
-@end html
-@anchor{rl78-x-elf}
-@heading rl78-*-elf
-The Renesas RL78 processor.
-This configuration is intended for embedded systems.
-
-@html
-<hr />
-@end html
-@anchor{riscv32-x-elf}
-@heading riscv32-*-elf
-The RISC-V RV32 instruction set.
-This configuration is intended for embedded systems.
-This (and all other RISC-V) targets require the binutils 2.30 release.
-
-@html
-<hr />
-@end html
-@anchor{riscv32-x-linux}
-@heading riscv32-*-linux
-The RISC-V RV32 instruction set running GNU/Linux.
-This (and all other RISC-V) targets require the binutils 2.30 release.
-
-@html
-<hr />
-@end html
-@anchor{riscv64-x-elf}
-@heading riscv64-*-elf
-The RISC-V RV64 instruction set.
-This configuration is intended for embedded systems.
-This (and all other RISC-V) targets require the binutils 2.30 release.
-
-@html
-<hr />
-@end html
-@anchor{riscv64-x-linux}
-@heading riscv64-*-linux
-The RISC-V RV64 instruction set running GNU/Linux.
-This (and all other RISC-V) targets require the binutils 2.30 release.
-
-@html
-<hr />
-@end html
-@anchor{rx-x-elf}
-@heading rx-*-elf
-The Renesas RX processor.
-
-@html
-<hr />
-@end html
-@anchor{s390-x-linux}
-@heading s390-*-linux*
-S/390 system running GNU/Linux for S/390@.
-
-@html
-<hr />
-@end html
-@anchor{s390x-x-linux}
-@heading s390x-*-linux*
-zSeries system (64-bit) running GNU/Linux for zSeries@.
-
-@html
-<hr />
-@end html
-@anchor{s390x-ibm-tpf}
-@heading s390x-ibm-tpf*
-zSeries system (64-bit) running TPF@. This platform is
-supported as cross-compilation target only.
-
-@html
-<hr />
-@end html
-@c Please use Solaris 2 to refer to all release of Solaris, starting
-@c with 2.0 until 2.6, 7, 8, etc. Solaris 1 was a marketing name for
-@c SunOS 4 releases which we don't use to avoid confusion. Solaris
-@c alone is too unspecific and must be avoided.
-@anchor{x-x-solaris2}
-@heading *-*-solaris2*
-Support for Solaris 10 has been removed in GCC 10. Support for Solaris
-9 has been removed in GCC 5. Support for Solaris 8 has been removed in
-GCC 4.8. Support for Solaris 7 has been removed in GCC 4.6.
-
-Solaris 11.3 provides GCC 4.5.2, 4.7.3, and 4.8.2 as
-@command{/usr/gcc/4.5/bin/gcc} or similar. Newer Solaris versions
-provide one or more of GCC 5, 7, and 9. Alternatively,
-you can install a pre-built GCC to bootstrap and install GCC. See the
-@uref{binaries.html,,binaries page} for details.
-
-The Solaris 2 @command{/bin/sh} will often fail to configure
-@samp{libstdc++-v3}. We therefore recommend using the
-following initial sequence of commands
-
-@smallexample
-% CONFIG_SHELL=/bin/ksh
-% export CONFIG_SHELL
-@end smallexample
-
-@noindent
-and proceed as described in @uref{configure.html,,the configure instructions}.
-In addition we strongly recommend specifying an absolute path to invoke
-@command{@var{srcdir}/configure}.
-
-In Solaris 11, you need to check for @code{system/header},
-@code{system/linker}, and @code{developer/assembler} packages.
-
-Trying to use the linker and other tools in
-@file{/usr/ucb} to install GCC has been observed to cause trouble.
-For example, the linker may hang indefinitely. The fix is to remove
-@file{/usr/ucb} from your @env{PATH}.
-
-The build process works more smoothly with the legacy Solaris tools so, if you
-have @file{/usr/xpg4/bin} in your @env{PATH}, we recommend that you place
-@file{/usr/bin} before @file{/usr/xpg4/bin} for the duration of the build.
-
-We recommend the use of the Solaris assembler or the GNU assembler, in
-conjunction with the Solaris linker. The GNU @command{as}
-versions included in Solaris 11.3,
-from GNU binutils 2.23.1 or newer (in @file{/usr/bin/gas} and
-@file{/usr/gnu/bin/as}), are known to work.
-The current version, from GNU binutils 2.34,
-is known to work as well. Note that your mileage may vary
-if you use a combination of the GNU tools and the Solaris tools: while the
-combination GNU @command{as} + Solaris @command{ld} should reasonably work,
-the reverse combination Solaris @command{as} + GNU @command{ld} may fail to
-build or cause memory corruption at runtime in some cases for C++ programs.
-@c FIXME: still?
-GNU @command{ld} usually works as well. Again, the current
-version (2.34) is known to work, but generally lacks platform specific
-features, so better stay with Solaris @command{ld}. To use the LTO linker
-plugin (@option{-fuse-linker-plugin}) with GNU @command{ld}, GNU
-binutils @emph{must} be configured with @option{--enable-largefile}.
-
-To enable symbol versioning in @samp{libstdc++} with the Solaris linker,
-you need to have any version of GNU @command{c++filt}, which is part of
-GNU binutils. @samp{libstdc++} symbol versioning will be disabled if no
-appropriate version is found. Solaris @command{c++filt} from the Solaris
-Studio compilers does @emph{not} work.
-
-In order to build the GNU D compiler, GDC, a working @samp{libphobos} is
-needed. That library wasn't built by default in GCC 9--11 on SPARC, or
-on x86 when the Solaris assembler is used, but can be enabled by
-configuring with @option{--enable-libphobos}. Also, GDC 9.4.0 is
-required on x86, while GDC 9.3.0 is known to work on SPARC.
-
-The versions of the GNU Multiple Precision Library (GMP), the MPFR
-library and the MPC library bundled with Solaris 11.3 and later are
-usually recent enough to match GCC's requirements. There are two
-caveats:
-
-@itemize @bullet
-@item
-While the version of the GMP library in Solaris 11.3 works with GCC, you
-need to configure with @option{--with-gmp-include=/usr/include/gmp}.
-
-@item
-The version of the MPFR libary included in Solaris 11.3 is too old; you
-need to provide a more recent one.
-
-@end itemize
-
-@html
-<hr />
-@end html
-@anchor{sparc-x-x}
-@heading sparc*-*-*
-This section contains general configuration information for all
-SPARC-based platforms. In addition to reading this section, please
-read all other sections that match your target.
-
-Newer versions of the GNU Multiple Precision Library (GMP), the MPFR
-library and the MPC library are known to be miscompiled by earlier
-versions of GCC on these platforms. We therefore recommend the use
-of the exact versions of these libraries listed as minimal versions
-in @uref{prerequisites.html,,the prerequisites}.
-
-@html
-<hr />
-@end html
-@anchor{sparc-sun-solaris2}
-@heading sparc-sun-solaris2*
-When GCC is configured to use GNU binutils 2.14 or later, the binaries
-produced are smaller than the ones produced using Solaris native tools;
-this difference is quite significant for binaries containing debugging
-information.
-
-Starting with Solaris 7, the operating system is capable of executing
-64-bit SPARC V9 binaries. GCC 3.1 and later properly supports
-this; the @option{-m64} option enables 64-bit code generation.
-However, if all you want is code tuned for the UltraSPARC CPU, you
-should try the @option{-mtune=ultrasparc} option instead, which produces
-code that, unlike full 64-bit code, can still run on non-UltraSPARC
-machines.
-
-When configuring the GNU Multiple Precision Library (GMP), the MPFR
-library or the MPC library on a Solaris 7 or later system, the canonical
-target triplet must be specified as the @command{build} parameter on the
-configure line. This target triplet can be obtained by invoking @command{./config.guess} in the toplevel source directory of GCC (and
-not that of GMP or MPFR or MPC). For example on a Solaris 11 system:
-
-@smallexample
-% ./configure --build=sparc-sun-solaris2.11 --prefix=xxx
-@end smallexample
-
-@html
-<hr />
-@end html
-@anchor{sparc-x-linux}
-@heading sparc-*-linux*
-
-@html
-<hr />
-@end html
-@anchor{sparc64-x-solaris2}
-@heading sparc64-*-solaris2*
-When configuring a 64-bit-default GCC on Solaris/SPARC, you must use a
-build compiler that generates 64-bit code, either by default or by
-specifying @samp{CC='gcc -m64' CXX='gcc-m64'} to @command{configure}.
-Additionally, you @emph{must} pass @option{--build=sparc64-sun-solaris2.11}
-or @option{--build=sparcv9-sun-solaris2.11} because @file{config.guess}
-misdetects this situation, which can cause build failures.
-
-When configuring the GNU Multiple Precision Library (GMP), the MPFR
-library or the MPC library, the canonical target triplet must be specified
-as the @command{build} parameter on the configure line. For example
-on a Solaris 11 system:
-
-@smallexample
-% ./configure --build=sparc64-sun-solaris2.11 --prefix=xxx
-@end smallexample
-
-@html
-<hr />
-@end html
-@anchor{sparcv9-x-solaris2}
-@heading sparcv9-*-solaris2*
-This is a synonym for @samp{sparc64-*-solaris2*}.
-
-@html
-<hr />
-@end html
-@anchor{c6x-x-x}
-@heading c6x-*-*
-The C6X family of processors. This port requires binutils-2.22 or newer.
-
-@html
-<hr />
-@end html
-@anchor{visium-x-elf}
-@heading visium-*-elf
-CDS VISIUMcore processor.
-This configuration is intended for embedded systems.
-
-@html
-<hr />
-@end html
-@anchor{x-x-vxworks}
-@heading *-*-vxworks*
-Support for VxWorks is in flux. At present GCC supports @emph{only} the
-very recent VxWorks 5.5 (aka Tornado 2.2) release, and only on PowerPC@.
-We welcome patches for other architectures supported by VxWorks 5.5.
-Support for VxWorks AE would also be welcome; we believe this is merely
-a matter of writing an appropriate ``configlette'' (see below). We are
-not interested in supporting older, a.out or COFF-based, versions of
-VxWorks in GCC 3.
-
-VxWorks comes with an older version of GCC installed in
-@file{@var{$WIND_BASE}/host}; we recommend you do not overwrite it.
-Choose an installation @var{prefix} entirely outside @var{$WIND_BASE}.
-Before running @command{configure}, create the directories @file{@var{prefix}}
-and @file{@var{prefix}/bin}. Link or copy the appropriate assembler,
-linker, etc.@: into @file{@var{prefix}/bin}, and set your @var{PATH} to
-include that directory while running both @command{configure} and
-@command{make}.
-
-You must give @command{configure} the
-@option{--with-headers=@var{$WIND_BASE}/target/h} switch so that it can
-find the VxWorks system headers. Since VxWorks is a cross compilation
-target only, you must also specify @option{--target=@var{target}}.
-@command{configure} will attempt to create the directory
-@file{@var{prefix}/@var{target}/sys-include} and copy files into it;
-make sure the user running @command{configure} has sufficient privilege
-to do so.
-
-GCC's exception handling runtime requires a special ``configlette''
-module, @file{contrib/gthr_supp_vxw_5x.c}. Follow the instructions in
-that file to add the module to your kernel build. (Future versions of
-VxWorks will incorporate this module.)
-
-@html
-<hr />
-@end html
-@anchor{x86-64-x-x}
-@heading x86_64-*-*, amd64-*-*
-GCC supports the x86-64 architecture implemented by the AMD64 processor
-(amd64-*-* is an alias for x86_64-*-*) on GNU/Linux, FreeBSD and NetBSD@.
-On GNU/Linux the default is a bi-arch compiler which is able to generate
-both 64-bit x86-64 and 32-bit x86 code (via the @option{-m32} switch).
-
-@html
-<hr />
-@end html
-@anchor{x86-64-x-solaris2}
-@heading x86_64-*-solaris2*
-GCC also supports the x86-64 architecture implemented by the AMD64
-processor (@samp{amd64-*-*} is an alias for @samp{x86_64-*-*}) on
-Solaris 10 or later. Unlike other systems, without special options a
-bi-arch compiler is built which generates 32-bit code by default, but
-can generate 64-bit x86-64 code with the @option{-m64} switch. Since
-GCC 4.7, there is also a configuration that defaults to 64-bit code, but
-can generate 32-bit code with @option{-m32}. To configure and build
-this way, you have to provide all support libraries like @file{libgmp}
-as 64-bit code, configure with @option{--target=x86_64-pc-solaris2.11}
-and @samp{CC=gcc -m64}.
-
-@html
-<hr />
-@end html
-@anchor{xtensa-x-elf}
-@heading xtensa*-*-elf
-This target is intended for embedded Xtensa systems using the
-@samp{newlib} C library. It uses ELF but does not support shared
-objects. Designed-defined instructions specified via the
-Tensilica Instruction Extension (TIE) language are only supported
-through inline assembly.
-
-The Xtensa configuration information must be specified prior to
-building GCC@. The @file{include/xtensa-config.h} header
-file contains the configuration information. If you created your
-own Xtensa configuration with the Xtensa Processor Generator, the
-downloaded files include a customized copy of this header file,
-which you can use to replace the default header file.
-
-@html
-<hr />
-@end html
-@anchor{xtensa-x-linux}
-@heading xtensa*-*-linux*
-This target is for Xtensa systems running GNU/Linux. It supports ELF
-shared objects and the GNU C library (glibc). It also generates
-position-independent code (PIC) regardless of whether the
-@option{-fpic} or @option{-fPIC} options are used. In other
-respects, this target is the same as the
-@uref{#xtensa*-*-elf,,@samp{xtensa*-*-elf}} target.
-
-@html
-<hr />
-@end html
-@anchor{windows}
-@heading Microsoft Windows
-
-@subheading Intel 16-bit versions
-The 16-bit versions of Microsoft Windows, such as Windows 3.1, are not
-supported.
-
-However, the 32-bit port has limited support for Microsoft
-Windows 3.11 in the Win32s environment, as a target only. See below.
-
-@subheading Intel 32-bit versions
-The 32-bit versions of Windows, including Windows 95, Windows NT, Windows
-XP, and Windows Vista, are supported by several different target
-platforms. These targets differ in which Windows subsystem they target
-and which C libraries are used.
-
-@itemize
-@item Cygwin @uref{#x-x-cygwin,,*-*-cygwin}: Cygwin provides a user-space
-Linux API emulation layer in the Win32 subsystem.
-@item MinGW @uref{#x-x-mingw32,,*-*-mingw32}: MinGW is a native GCC port for
-the Win32 subsystem that provides a subset of POSIX.
-@item MKS i386-pc-mks: NuTCracker from MKS. See
-@uref{https://www.mkssoftware.com} for more information.
-@end itemize
-
-@subheading Intel 64-bit versions
-GCC contains support for x86-64 using the mingw-w64
-runtime library, available from @uref{https://www.mingw-w64.org/downloads/}.
-This library should be used with the target triple x86_64-pc-mingw32.
-
-@subheading Windows CE
-Windows CE is supported as a target only on Hitachi
-SuperH (sh-wince-pe), and MIPS (mips-wince-pe).
-
-@subheading Other Windows Platforms
-GCC no longer supports Windows NT on the Alpha or PowerPC.
-
-GCC no longer supports the Windows POSIX subsystem. However, it does
-support the Interix subsystem. See above.
-
-Old target names including *-*-winnt and *-*-windowsnt are no longer used.
-
-PW32 (i386-pc-pw32) support was never completed, and the project seems to
-be inactive. See @uref{http://pw32.sourceforge.net/} for more information.
-
-UWIN support has been removed due to a lack of maintenance.
-
-@html
-<hr />
-@end html
-@anchor{x-x-cygwin}
-@heading *-*-cygwin
-Ports of GCC are included with the
-@uref{http://www.cygwin.com/,,Cygwin environment}.
-
-GCC will build under Cygwin without modification; it does not build
-with Microsoft's C++ compiler and there are no plans to make it do so.
-
-The Cygwin native compiler can be configured to target any 32-bit x86
-cpu architecture desired; the default is i686-pc-cygwin. It should be
-used with as up-to-date a version of binutils as possible; use either
-the latest official GNU binutils release in the Cygwin distribution,
-or version 2.20 or above if building your own.
-
-@html
-<hr />
-@end html
-@anchor{x-x-mingw32}
-@heading *-*-mingw32
-GCC will build with and support only MinGW runtime 3.12 and later.
-Earlier versions of headers are incompatible with the new default semantics
-of @code{extern inline} in @code{-std=c99} and @code{-std=gnu99} modes.
-
-To support emitting DWARF debugging info you need to use GNU binutils
-version 2.16 or above containing support for the @code{.secrel32}
-assembler pseudo-op.
-
-@html
-<hr />
-@end html
-@anchor{older}
-@heading Older systems
-GCC contains support files for many older (1980s and early
-1990s) Unix variants. For the most part, support for these systems
-has not been deliberately removed, but it has not been maintained for
-several years and may suffer from bitrot.
-
-Starting with GCC 3.1, each release has a list of ``obsoleted'' systems.
-Support for these systems is still present in that release, but
-@command{configure} will fail unless the @option{--enable-obsolete}
-option is given. Unless a maintainer steps forward, support for these
-systems will be removed from the next release of GCC@.
-
-Support for old systems as hosts for GCC can cause problems if the
-workarounds for compiler, library and operating system bugs affect the
-cleanliness or maintainability of the rest of GCC@. In some cases, to
-bring GCC up on such a system, if still possible with current GCC, may
-require first installing an old version of GCC which did work on that
-system, and using it to compile a more recent GCC, to avoid bugs in the
-vendor compiler. Old releases of GCC 1 and GCC 2 are available in the
-@file{old-releases} directory on the @uref{../mirrors.html,,GCC mirror
-sites}. Header bugs may generally be avoided using
-@command{fixincludes}, but bugs or deficiencies in libraries and the
-operating system may still cause problems.
-
-Support for older systems as targets for cross-compilation is less
-problematic than support for them as hosts for GCC; if an enthusiast
-wishes to make such a target work again (including resurrecting any of
-the targets that never worked with GCC 2, starting from the last
-version before they were removed), patches
-@uref{../contribute.html,,following the usual requirements} would be
-likely to be accepted, since they should not affect the support for more
-modern targets.
-
-For some systems, old versions of GNU binutils may also be useful,
-and are available from @file{pub/binutils/old-releases} on
-@uref{https://sourceware.org/mirrors.html,,sourceware.org mirror sites}.
-
-Some of the information on specific systems above relates to
-such older systems, but much of the information
-about GCC on such systems (which may no longer be applicable to
-current GCC) is to be found in the GCC texinfo manual.
-
-@html
-<hr />
-@end html
-@anchor{elf}
-@heading all ELF targets (SVR4, Solaris 2, etc.)
-C++ support is significantly better on ELF targets if you use the
-@uref{./configure.html#with-gnu-ld,,GNU linker}; duplicate copies of
-inlines, vtables and template instantiations will be discarded
-automatically.
-
-
-@html
-<hr />
-<p>
-@end html
-@ifhtml
-@uref{./index.html,,Return to the GCC Installation page}
-@end ifhtml
-@end ifset
-
-@c ***GFDL********************************************************************
-@ifset gfdlhtml
-@include fdl.texi
-@html
-<hr />
-<p>
-@end html
-@ifhtml
-@uref{./index.html,,Return to the GCC Installation page}
-@end ifhtml
-@end ifset
-
-@c ***************************************************************************
-@c Part 6 The End of the Document
-@ifinfo
-@comment node-name, next, previous, up
-@node Concept Index, , GNU Free Documentation License, Top
-@end ifinfo
-
-@ifinfo
-@unnumbered Concept Index
-
-@printindex cp
-
-@contents
-@end ifinfo
-@bye
+++ /dev/null
-@c Copyright (C) 1988-2022 Free Software Foundation, Inc.
-@c This is part of the GCC manual.
-@c For copying conditions, see the file gcc.texi.
-
-@node Interface
-@chapter Interfacing to GCC Output
-@cindex interfacing to GCC output
-@cindex run-time conventions
-@cindex function call conventions
-@cindex conventions, run-time
-
-GCC is normally configured to use the same function calling convention
-normally in use on the target system. This is done with the
-machine-description macros described (@pxref{Target Macros}).
-
-@cindex unions, returning
-@cindex structures, returning
-@cindex returning structures and unions
-However, returning of structure and union values is done differently on
-some target machines. As a result, functions compiled with PCC
-returning such types cannot be called from code compiled with GCC,
-and vice versa. This does not cause trouble often because few Unix
-library routines return structures or unions.
-
-GCC code returns structures and unions that are 1, 2, 4 or 8 bytes
-long in the same registers used for @code{int} or @code{double} return
-values. (GCC typically allocates variables of such types in
-registers also.) Structures and unions of other sizes are returned by
-storing them into an address passed by the caller (usually in a
-register). The target hook @code{TARGET_STRUCT_VALUE_RTX}
-tells GCC where to pass this address.
-
-By contrast, PCC on most target machines returns structures and unions
-of any size by copying the data into an area of static storage, and then
-returning the address of that storage as if it were a pointer value.
-The caller must copy the data from that memory area to the place where
-the value is wanted. This is slower than the method used by GCC, and
-fails to be reentrant.
-
-On some target machines, such as RISC machines and the 80386, the
-standard system convention is to pass to the subroutine the address of
-where to return the value. On these machines, GCC has been
-configured to be compatible with the standard compiler, when this method
-is used. It may not be compatible for structures of 1, 2, 4 or 8 bytes.
-
-@cindex argument passing
-@cindex passing arguments
-GCC uses the system's standard convention for passing arguments. On
-some machines, the first few arguments are passed in registers; in
-others, all are passed on the stack. It would be possible to use
-registers for argument passing on any machine, and this would probably
-result in a significant speedup. But the result would be complete
-incompatibility with code that follows the standard convention. So this
-change is practical only if you are switching to GCC as the sole C
-compiler for the system. We may implement register argument passing on
-certain machines once we have a complete GNU system so that we can
-compile the libraries with GCC@.
-
-On some machines (particularly the SPARC), certain types of arguments
-are passed ``by invisible reference''. This means that the value is
-stored in memory, and the address of the memory location is passed to
-the subroutine.
-
-@cindex @code{longjmp} and automatic variables
-If you use @code{longjmp}, beware of automatic variables. ISO C says that
-automatic variables that are not declared @code{volatile} have undefined
-values after a @code{longjmp}. And this is all GCC promises to do,
-because it is very difficult to restore register variables correctly, and
-one of GCC's features is that it can put variables in registers without
-your asking it to.
+++ /dev/null
-@c Copyright (C) 1988-2022 Free Software Foundation, Inc.
-@c This is part of the GCC manual.
-@c For copying conditions, see the file gcc.texi.
-
-@ignore
-@c man begin INCLUDE
-@include gcc-vers.texi
-@c man end
-
-@c man begin COPYRIGHT
-Copyright @copyright{} 1988-2022 Free Software Foundation, Inc.
-
-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 the
-Invariant Sections being ``GNU General Public License'' and ``Funding
-Free Software'', the Front-Cover texts being (a) (see below), and with
-the Back-Cover Texts being (b) (see below). A copy of the license is
-included in the gfdl(7) man page.
-
-(a) The FSF's Front-Cover Text is:
-
- A GNU Manual
-
-(b) The FSF's Back-Cover Text is:
-
- You have freedom to copy and modify this GNU Manual, like GNU
- software. Copies published by the Free Software Foundation raise
- funds for GNU development.
-@c man end
-@c Set file name and title for the man page.
-@setfilename gcc
-@settitle GNU project C and C++ compiler
-@c man begin SYNOPSIS
-gcc [@option{-c}|@option{-S}|@option{-E}] [@option{-std=}@var{standard}]
- [@option{-g}] [@option{-pg}] [@option{-O}@var{level}]
- [@option{-W}@var{warn}@dots{}] [@option{-Wpedantic}]
- [@option{-I}@var{dir}@dots{}] [@option{-L}@var{dir}@dots{}]
- [@option{-D}@var{macro}[=@var{defn}]@dots{}] [@option{-U}@var{macro}]
- [@option{-f}@var{option}@dots{}] [@option{-m}@var{machine-option}@dots{}]
- [@option{-o} @var{outfile}] [@@@var{file}] @var{infile}@dots{}
-
-Only the most useful options are listed here; see below for the
-remainder. @command{g++} accepts mostly the same options as @command{gcc}.
-@c man end
-@c man begin SEEALSO
-gpl(7), gfdl(7), fsf-funding(7),
-cpp(1), gcov(1), as(1), ld(1), gdb(1)
-and the Info entries for @file{gcc}, @file{cpp}, @file{as},
-@file{ld}, @file{binutils} and @file{gdb}.
-@c man end
-@c man begin BUGS
-For instructions on reporting bugs, see
-@w{@value{BUGURL}}.
-@c man end
-@c man begin AUTHOR
-See the Info entry for @command{gcc}, or
-@w{@uref{https://gcc.gnu.org/onlinedocs/gcc/Contributors.html}},
-for contributors to GCC@.
-@c man end
-@end ignore
-
-@node Invoking GCC
-@chapter GCC Command Options
-@cindex GCC command options
-@cindex command options
-@cindex options, GCC command
-
-@c man begin DESCRIPTION
-When you invoke GCC, it normally does preprocessing, compilation,
-assembly and linking. The ``overall options'' allow you to stop this
-process at an intermediate stage. For example, the @option{-c} option
-says not to run the linker. Then the output consists of object files
-output by the assembler.
-@xref{Overall Options,,Options Controlling the Kind of Output}.
-
-Other options are passed on to one or more stages of processing. Some options
-control the preprocessor and others the compiler itself. Yet other
-options control the assembler and linker; most of these are not
-documented here, since you rarely need to use any of them.
-
-@cindex C compilation options
-Most of the command-line options that you can use with GCC are useful
-for C programs; when an option is only useful with another language
-(usually C++), the explanation says so explicitly. If the description
-for a particular option does not mention a source language, you can use
-that option with all supported languages.
-
-@cindex cross compiling
-@cindex specifying machine version
-@cindex specifying compiler version and target machine
-@cindex compiler version, specifying
-@cindex target machine, specifying
-The usual way to run GCC is to run the executable called @command{gcc}, or
-@command{@var{machine}-gcc} when cross-compiling, or
-@command{@var{machine}-gcc-@var{version}} to run a specific version of GCC.
-When you compile C++ programs, you should invoke GCC as @command{g++}
-instead. @xref{Invoking G++,,Compiling C++ Programs},
-for information about the differences in behavior between @command{gcc}
-and @command{g++} when compiling C++ programs.
-
-@cindex grouping options
-@cindex options, grouping
-The @command{gcc} program accepts options and file names as operands. Many
-options have multi-letter names; therefore multiple single-letter options
-may @emph{not} be grouped: @option{-dv} is very different from @w{@samp{-d
--v}}.
-
-@cindex order of options
-@cindex options, order
-You can mix options and other arguments. For the most part, the order
-you use doesn't matter. Order does matter when you use several
-options of the same kind; for example, if you specify @option{-L} more
-than once, the directories are searched in the order specified. Also,
-the placement of the @option{-l} option is significant.
-
-Many options have long names starting with @samp{-f} or with
-@samp{-W}---for example,
-@option{-fmove-loop-invariants}, @option{-Wformat} and so on. Most of
-these have both positive and negative forms; the negative form of
-@option{-ffoo} is @option{-fno-foo}. This manual documents
-only one of these two forms, whichever one is not the default.
-
-Some options take one or more arguments typically separated either
-by a space or by the equals sign (@samp{=}) from the option name.
-Unless documented otherwise, an argument can be either numeric or
-a string. Numeric arguments must typically be small unsigned decimal
-or hexadecimal integers. Hexadecimal arguments must begin with
-the @samp{0x} prefix. Arguments to options that specify a size
-threshold of some sort may be arbitrarily large decimal or hexadecimal
-integers followed by a byte size suffix designating a multiple of bytes
-such as @code{kB} and @code{KiB} for kilobyte and kibibyte, respectively,
-@code{MB} and @code{MiB} for megabyte and mebibyte, @code{GB} and
-@code{GiB} for gigabyte and gigibyte, and so on. Such arguments are
-designated by @var{byte-size} in the following text. Refer to the NIST,
-IEC, and other relevant national and international standards for the full
-listing and explanation of the binary and decimal byte size prefixes.
-
-@c man end
-
-@xref{Option Index}, for an index to GCC's options.
-
-@menu
-* Option Summary:: Brief list of all options, without explanations.
-* Overall Options:: Controlling the kind of output:
- an executable, object files, assembler files,
- or preprocessed source.
-* Invoking G++:: Compiling C++ programs.
-* C Dialect Options:: Controlling the variant of C language compiled.
-* C++ Dialect Options:: Variations on C++.
-* Objective-C and Objective-C++ Dialect Options:: Variations on Objective-C
- and Objective-C++.
-* Diagnostic Message Formatting Options:: Controlling how diagnostics should
- be formatted.
-* Warning Options:: How picky should the compiler be?
-* Static Analyzer Options:: More expensive warnings.
-* Debugging Options:: Producing debuggable code.
-* Optimize Options:: How much optimization?
-* Instrumentation Options:: Enabling profiling and extra run-time error checking.
-* Preprocessor Options:: Controlling header files and macro definitions.
- Also, getting dependency information for Make.
-* Assembler Options:: Passing options to the assembler.
-* Link Options:: Specifying libraries and so on.
-* Directory Options:: Where to find header files and libraries.
- Where to find the compiler executable files.
-* Code Gen Options:: Specifying conventions for function calls, data layout
- and register usage.
-* Developer Options:: Printing GCC configuration info, statistics, and
- debugging dumps.
-* Submodel Options:: Target-specific options, such as compiling for a
- specific processor variant.
-* Spec Files:: How to pass switches to sub-processes.
-* Environment Variables:: Env vars that affect GCC.
-* Precompiled Headers:: Compiling a header once, and using it many times.
-* C++ Modules:: Experimental C++20 module system.
-@end menu
-
-@c man begin OPTIONS
-
-@node Option Summary
-@section Option Summary
-
-Here is a summary of all the options, grouped by type. Explanations are
-in the following sections.
-
-@table @emph
-@item Overall Options
-@xref{Overall Options,,Options Controlling the Kind of Output}.
-@gccoptlist{-c -S -E -o @var{file} @gol
--dumpbase @var{dumpbase} -dumpbase-ext @var{auxdropsuf} @gol
--dumpdir @var{dumppfx} -x @var{language} @gol
--v -### --help@r{[}=@var{class}@r{[},@dots{}@r{]]} --target-help --version @gol
--pass-exit-codes -pipe -specs=@var{file} -wrapper @gol
-@@@var{file} -ffile-prefix-map=@var{old}=@var{new} @gol
--fplugin=@var{file} -fplugin-arg-@var{name}=@var{arg} @gol
--fdump-ada-spec@r{[}-slim@r{]} -fada-spec-parent=@var{unit} -fdump-go-spec=@var{file}}
-
-@item C Language Options
-@xref{C Dialect Options,,Options Controlling C Dialect}.
-@gccoptlist{-ansi -std=@var{standard} -aux-info @var{filename} @gol
--fno-asm @gol
--fno-builtin -fno-builtin-@var{function} -fcond-mismatch @gol
--ffreestanding -fgimple -fgnu-tm -fgnu89-inline -fhosted @gol
--flax-vector-conversions -fms-extensions @gol
--foffload=@var{arg} -foffload-options=@var{arg} @gol
--fopenacc -fopenacc-dim=@var{geom} @gol
--fopenmp -fopenmp-simd @gol
--fpermitted-flt-eval-methods=@var{standard} @gol
--fplan9-extensions -fsigned-bitfields -funsigned-bitfields @gol
--fsigned-char -funsigned-char -fstrict-flex-arrays[=@var{n}] @gol
--fsso-struct=@var{endianness}}
-
-@item C++ Language Options
-@xref{C++ Dialect Options,,Options Controlling C++ Dialect}.
-@gccoptlist{-fabi-version=@var{n} -fno-access-control @gol
--faligned-new=@var{n} -fargs-in-order=@var{n} -fchar8_t -fcheck-new @gol
--fconstexpr-depth=@var{n} -fconstexpr-cache-depth=@var{n} @gol
--fconstexpr-loop-limit=@var{n} -fconstexpr-ops-limit=@var{n} @gol
--fno-elide-constructors @gol
--fno-enforce-eh-specs @gol
--fno-gnu-keywords @gol
--fno-implicit-templates @gol
--fno-implicit-inline-templates @gol
--fno-implement-inlines @gol
--fmodule-header@r{[}=@var{kind}@r{]} -fmodule-only -fmodules-ts @gol
--fmodule-implicit-inline @gol
--fno-module-lazy @gol
--fmodule-mapper=@var{specification} @gol
--fmodule-version-ignore @gol
--fms-extensions @gol
--fnew-inheriting-ctors @gol
--fnew-ttp-matching @gol
--fno-nonansi-builtins -fnothrow-opt -fno-operator-names @gol
--fno-optional-diags -fpermissive @gol
--fno-pretty-templates @gol
--fno-rtti -fsized-deallocation @gol
--ftemplate-backtrace-limit=@var{n} @gol
--ftemplate-depth=@var{n} @gol
--fno-threadsafe-statics -fuse-cxa-atexit @gol
--fno-weak -nostdinc++ @gol
--fvisibility-inlines-hidden @gol
--fvisibility-ms-compat @gol
--fext-numeric-literals @gol
--flang-info-include-translate@r{[}=@var{header}@r{]} @gol
--flang-info-include-translate-not @gol
--flang-info-module-cmi@r{[}=@var{module}@r{]} @gol
--stdlib=@var{libstdc++,libc++} @gol
--Wabi-tag -Wcatch-value -Wcatch-value=@var{n} @gol
--Wno-class-conversion -Wclass-memaccess @gol
--Wcomma-subscript -Wconditionally-supported @gol
--Wno-conversion-null -Wctad-maybe-unsupported @gol
--Wctor-dtor-privacy -Wdangling-reference @gol
--Wno-delete-incomplete @gol
--Wdelete-non-virtual-dtor -Wno-deprecated-array-compare @gol
--Wdeprecated-copy -Wdeprecated-copy-dtor @gol
--Wno-deprecated-enum-enum-conversion -Wno-deprecated-enum-float-conversion @gol
--Weffc++ -Wno-exceptions -Wextra-semi -Wno-inaccessible-base @gol
--Wno-inherited-variadic-ctor -Wno-init-list-lifetime @gol
--Winvalid-imported-macros @gol
--Wno-invalid-offsetof -Wno-literal-suffix @gol
--Wmismatched-new-delete -Wmismatched-tags @gol
--Wmultiple-inheritance -Wnamespaces -Wnarrowing @gol
--Wnoexcept -Wnoexcept-type -Wnon-virtual-dtor @gol
--Wpessimizing-move -Wno-placement-new -Wplacement-new=@var{n} @gol
--Wrange-loop-construct -Wredundant-move -Wredundant-tags @gol
--Wreorder -Wregister @gol
--Wstrict-null-sentinel -Wno-subobject-linkage -Wtemplates @gol
--Wno-non-template-friend -Wold-style-cast @gol
--Woverloaded-virtual -Wno-pmf-conversions -Wself-move -Wsign-promo @gol
--Wsized-deallocation -Wsuggest-final-methods @gol
--Wsuggest-final-types -Wsuggest-override @gol
--Wno-terminate -Wuseless-cast -Wno-vexing-parse @gol
--Wvirtual-inheritance @gol
--Wno-virtual-move-assign -Wvolatile -Wzero-as-null-pointer-constant}
-
-@item Objective-C and Objective-C++ Language Options
-@xref{Objective-C and Objective-C++ Dialect Options,,Options Controlling
-Objective-C and Objective-C++ Dialects}.
-@gccoptlist{-fconstant-string-class=@var{class-name} @gol
--fgnu-runtime -fnext-runtime @gol
--fno-nil-receivers @gol
--fobjc-abi-version=@var{n} @gol
--fobjc-call-cxx-cdtors @gol
--fobjc-direct-dispatch @gol
--fobjc-exceptions @gol
--fobjc-gc @gol
--fobjc-nilcheck @gol
--fobjc-std=objc1 @gol
--fno-local-ivars @gol
--fivar-visibility=@r{[}public@r{|}protected@r{|}private@r{|}package@r{]} @gol
--freplace-objc-classes @gol
--fzero-link @gol
--gen-decls @gol
--Wassign-intercept -Wno-property-assign-default @gol
--Wno-protocol -Wobjc-root-class -Wselector @gol
--Wstrict-selector-match @gol
--Wundeclared-selector}
-
-@item Diagnostic Message Formatting Options
-@xref{Diagnostic Message Formatting Options,,Options to Control Diagnostic Messages Formatting}.
-@gccoptlist{-fmessage-length=@var{n} @gol
--fdiagnostics-plain-output @gol
--fdiagnostics-show-location=@r{[}once@r{|}every-line@r{]} @gol
--fdiagnostics-color=@r{[}auto@r{|}never@r{|}always@r{]} @gol
--fdiagnostics-urls=@r{[}auto@r{|}never@r{|}always@r{]} @gol
--fdiagnostics-format=@r{[}text@r{|}sarif-stderr@r{|}sarif-file@r{|}json@r{|}json-stderr@r{|}json-file@r{]} @gol
--fno-diagnostics-show-option -fno-diagnostics-show-caret @gol
--fno-diagnostics-show-labels -fno-diagnostics-show-line-numbers @gol
--fno-diagnostics-show-cwe @gol
--fno-diagnostics-show-rule @gol
--fdiagnostics-minimum-margin-width=@var{width} @gol
--fdiagnostics-parseable-fixits -fdiagnostics-generate-patch @gol
--fdiagnostics-show-template-tree -fno-elide-type @gol
--fdiagnostics-path-format=@r{[}none@r{|}separate-events@r{|}inline-events@r{]} @gol
--fdiagnostics-show-path-depths @gol
--fno-show-column @gol
--fdiagnostics-column-unit=@r{[}display@r{|}byte@r{]} @gol
--fdiagnostics-column-origin=@var{origin} @gol
--fdiagnostics-escape-format=@r{[}unicode@r{|}bytes@r{]}}
-
-@item Warning Options
-@xref{Warning Options,,Options to Request or Suppress Warnings}.
-@gccoptlist{-fsyntax-only -fmax-errors=@var{n} -Wpedantic @gol
--pedantic-errors @gol
--w -Wextra -Wall -Wabi=@var{n} @gol
--Waddress -Wno-address-of-packed-member -Waggregate-return @gol
--Walloc-size-larger-than=@var{byte-size} -Walloc-zero @gol
--Walloca -Walloca-larger-than=@var{byte-size} @gol
--Wno-aggressive-loop-optimizations @gol
--Warith-conversion @gol
--Warray-bounds -Warray-bounds=@var{n} -Warray-compare @gol
--Wno-attributes -Wattribute-alias=@var{n} -Wno-attribute-alias @gol
--Wno-attribute-warning @gol
--Wbidi-chars=@r{[}none@r{|}unpaired@r{|}any@r{|}ucn@r{]} @gol
--Wbool-compare -Wbool-operation @gol
--Wno-builtin-declaration-mismatch @gol
--Wno-builtin-macro-redefined -Wc90-c99-compat -Wc99-c11-compat @gol
--Wc11-c2x-compat @gol
--Wc++-compat -Wc++11-compat -Wc++14-compat -Wc++17-compat @gol
--Wc++20-compat @gol
--Wno-c++11-extensions -Wno-c++14-extensions -Wno-c++17-extensions @gol
--Wno-c++20-extensions -Wno-c++23-extensions @gol
--Wcast-align -Wcast-align=strict -Wcast-function-type -Wcast-qual @gol
--Wchar-subscripts @gol
--Wclobbered -Wcomment @gol
--Wconversion -Wno-coverage-mismatch -Wno-cpp @gol
--Wdangling-else -Wdangling-pointer -Wdangling-pointer=@var{n} @gol
--Wdate-time @gol
--Wno-deprecated -Wno-deprecated-declarations -Wno-designated-init @gol
--Wdisabled-optimization @gol
--Wno-discarded-array-qualifiers -Wno-discarded-qualifiers @gol
--Wno-div-by-zero -Wdouble-promotion @gol
--Wduplicated-branches -Wduplicated-cond @gol
--Wempty-body -Wno-endif-labels -Wenum-compare -Wenum-conversion @gol
--Wenum-int-mismatch @gol
--Werror -Werror=* -Wexpansion-to-defined -Wfatal-errors @gol
--Wfloat-conversion -Wfloat-equal -Wformat -Wformat=2 @gol
--Wno-format-contains-nul -Wno-format-extra-args @gol
--Wformat-nonliteral -Wformat-overflow=@var{n} @gol
--Wformat-security -Wformat-signedness -Wformat-truncation=@var{n} @gol
--Wformat-y2k -Wframe-address @gol
--Wframe-larger-than=@var{byte-size} -Wno-free-nonheap-object @gol
--Wno-if-not-aligned -Wno-ignored-attributes @gol
--Wignored-qualifiers -Wno-incompatible-pointer-types @gol
--Wimplicit -Wimplicit-fallthrough -Wimplicit-fallthrough=@var{n} @gol
--Wno-implicit-function-declaration -Wno-implicit-int @gol
--Winfinite-recursion @gol
--Winit-self -Winline -Wno-int-conversion -Wint-in-bool-context @gol
--Wno-int-to-pointer-cast -Wno-invalid-memory-model @gol
--Winvalid-pch -Winvalid-utf8 -Wno-unicode -Wjump-misses-init @gol
--Wlarger-than=@var{byte-size} -Wlogical-not-parentheses -Wlogical-op @gol
--Wlong-long -Wno-lto-type-mismatch -Wmain -Wmaybe-uninitialized @gol
--Wmemset-elt-size -Wmemset-transposed-args @gol
--Wmisleading-indentation -Wmissing-attributes -Wmissing-braces @gol
--Wmissing-field-initializers -Wmissing-format-attribute @gol
--Wmissing-include-dirs -Wmissing-noreturn -Wno-missing-profile @gol
--Wno-multichar -Wmultistatement-macros -Wnonnull -Wnonnull-compare @gol
--Wnormalized=@r{[}none@r{|}id@r{|}nfc@r{|}nfkc@r{]} @gol
--Wnull-dereference -Wno-odr @gol
--Wopenacc-parallelism @gol
--Wopenmp-simd @gol
--Wno-overflow -Woverlength-strings -Wno-override-init-side-effects @gol
--Wpacked -Wno-packed-bitfield-compat -Wpacked-not-aligned -Wpadded @gol
--Wparentheses -Wno-pedantic-ms-format @gol
--Wpointer-arith -Wno-pointer-compare -Wno-pointer-to-int-cast @gol
--Wno-pragmas -Wno-prio-ctor-dtor -Wredundant-decls @gol
--Wrestrict -Wno-return-local-addr -Wreturn-type @gol
--Wno-scalar-storage-order -Wsequence-point @gol
--Wshadow -Wshadow=global -Wshadow=local -Wshadow=compatible-local @gol
--Wno-shadow-ivar @gol
--Wno-shift-count-negative -Wno-shift-count-overflow -Wshift-negative-value @gol
--Wno-shift-overflow -Wshift-overflow=@var{n} @gol
--Wsign-compare -Wsign-conversion @gol
--Wno-sizeof-array-argument @gol
--Wsizeof-array-div @gol
--Wsizeof-pointer-div -Wsizeof-pointer-memaccess @gol
--Wstack-protector -Wstack-usage=@var{byte-size} -Wstrict-aliasing @gol
--Wstrict-aliasing=n -Wstrict-overflow -Wstrict-overflow=@var{n} @gol
--Wstring-compare @gol
--Wno-stringop-overflow -Wno-stringop-overread @gol
--Wno-stringop-truncation @gol
--Wsuggest-attribute=@r{[}pure@r{|}const@r{|}noreturn@r{|}format@r{|}malloc@r{]} @gol
--Wswitch -Wno-switch-bool -Wswitch-default -Wswitch-enum @gol
--Wno-switch-outside-range -Wno-switch-unreachable -Wsync-nand @gol
--Wsystem-headers -Wtautological-compare -Wtrampolines -Wtrigraphs @gol
--Wtrivial-auto-var-init -Wtsan -Wtype-limits -Wundef @gol
--Wuninitialized -Wunknown-pragmas @gol
--Wunsuffixed-float-constants -Wunused @gol
--Wunused-but-set-parameter -Wunused-but-set-variable @gol
--Wunused-const-variable -Wunused-const-variable=@var{n} @gol
--Wunused-function -Wunused-label -Wunused-local-typedefs @gol
--Wunused-macros @gol
--Wunused-parameter -Wno-unused-result @gol
--Wunused-value -Wunused-variable @gol
--Wno-varargs -Wvariadic-macros @gol
--Wvector-operation-performance @gol
--Wvla -Wvla-larger-than=@var{byte-size} -Wno-vla-larger-than @gol
--Wvolatile-register-var -Wwrite-strings @gol
--Wxor-used-as-pow @gol
--Wzero-length-bounds}
-
-@item Static Analyzer Options
-@gccoptlist{
--fanalyzer @gol
--fanalyzer-call-summaries @gol
--fanalyzer-checker=@var{name} @gol
--fno-analyzer-feasibility @gol
--fanalyzer-fine-grained @gol
--fno-analyzer-state-merge @gol
--fno-analyzer-state-purge @gol
--fanalyzer-transitivity @gol
--fno-analyzer-undo-inlining @gol
--fanalyzer-verbose-edges @gol
--fanalyzer-verbose-state-changes @gol
--fanalyzer-verbosity=@var{level} @gol
--fdump-analyzer @gol
--fdump-analyzer-callgraph @gol
--fdump-analyzer-exploded-graph @gol
--fdump-analyzer-exploded-nodes @gol
--fdump-analyzer-exploded-nodes-2 @gol
--fdump-analyzer-exploded-nodes-3 @gol
--fdump-analyzer-exploded-paths @gol
--fdump-analyzer-feasibility @gol
--fdump-analyzer-json @gol
--fdump-analyzer-state-purge @gol
--fdump-analyzer-stderr @gol
--fdump-analyzer-supergraph @gol
--fdump-analyzer-untracked @gol
--Wno-analyzer-double-fclose @gol
--Wno-analyzer-double-free @gol
--Wno-analyzer-exposure-through-output-file @gol
--Wno-analyzer-exposure-through-uninit-copy @gol
--Wno-analyzer-fd-access-mode-mismatch @gol
--Wno-analyzer-fd-double-close @gol
--Wno-analyzer-fd-leak @gol
--Wno-analyzer-fd-use-after-close @gol
--Wno-analyzer-fd-use-without-check @gol
--Wno-analyzer-file-leak @gol
--Wno-analyzer-free-of-non-heap @gol
--Wno-analyzer-imprecise-fp-arithmetic @gol
--Wno-analyzer-jump-through-null @gol
--Wno-analyzer-malloc-leak @gol
--Wno-analyzer-mismatching-deallocation @gol
--Wno-analyzer-null-argument @gol
--Wno-analyzer-null-dereference @gol
--Wno-analyzer-out-of-bounds @gol
--Wno-analyzer-possible-null-argument @gol
--Wno-analyzer-possible-null-dereference @gol
--Wno-analyzer-putenv-of-auto-var @gol
--Wno-analyzer-shift-count-negative @gol
--Wno-analyzer-shift-count-overflow @gol
--Wno-analyzer-stale-setjmp-buffer @gol
--Wno-analyzer-tainted-allocation-size @gol
--Wno-analyzer-tainted-array-index @gol
--Wno-analyzer-tainted-divisor @gol
--Wno-analyzer-tainted-offset @gol
--Wno-analyzer-tainted-size @gol
--Wanalyzer-too-complex @gol
--Wno-analyzer-unsafe-call-within-signal-handler @gol
--Wno-analyzer-use-after-free @gol
--Wno-analyzer-use-of-pointer-in-stale-stack-frame @gol
--Wno-analyzer-use-of-uninitialized-value @gol
--Wno-analyzer-va-arg-type-mismatch @gol
--Wno-analyzer-va-list-exhausted @gol
--Wno-analyzer-va-list-leak @gol
--Wno-analyzer-va-list-use-after-va-end @gol
--Wno-analyzer-write-to-const @gol
--Wno-analyzer-write-to-string-literal @gol
-}
-
-@item C and Objective-C-only Warning Options
-@gccoptlist{-Wbad-function-cast -Wmissing-declarations @gol
--Wmissing-parameter-type -Wmissing-prototypes -Wnested-externs @gol
--Wold-style-declaration -Wold-style-definition @gol
--Wstrict-prototypes -Wtraditional -Wtraditional-conversion @gol
--Wdeclaration-after-statement -Wpointer-sign}
-
-@item Debugging Options
-@xref{Debugging Options,,Options for Debugging Your Program}.
-@gccoptlist{-g -g@var{level} -gdwarf -gdwarf-@var{version} @gol
--gbtf -gctf -gctf@var{level} @gol
--ggdb -grecord-gcc-switches -gno-record-gcc-switches @gol
--gstrict-dwarf -gno-strict-dwarf @gol
--gas-loc-support -gno-as-loc-support @gol
--gas-locview-support -gno-as-locview-support @gol
--gcolumn-info -gno-column-info -gdwarf32 -gdwarf64 @gol
--gstatement-frontiers -gno-statement-frontiers @gol
--gvariable-location-views -gno-variable-location-views @gol
--ginternal-reset-location-views -gno-internal-reset-location-views @gol
--ginline-points -gno-inline-points @gol
--gvms -gz@r{[}=@var{type}@r{]} @gol
--gsplit-dwarf -gdescribe-dies -gno-describe-dies @gol
--fdebug-prefix-map=@var{old}=@var{new} -fdebug-types-section @gol
--fno-eliminate-unused-debug-types @gol
--femit-struct-debug-baseonly -femit-struct-debug-reduced @gol
--femit-struct-debug-detailed@r{[}=@var{spec-list}@r{]} @gol
--fno-eliminate-unused-debug-symbols -femit-class-debug-always @gol
--fno-merge-debug-strings -fno-dwarf2-cfi-asm @gol
--fvar-tracking -fvar-tracking-assignments}
-
-@item Optimization Options
-@xref{Optimize Options,,Options that Control Optimization}.
-@gccoptlist{-faggressive-loop-optimizations @gol
--falign-functions[=@var{n}[:@var{m}:[@var{n2}[:@var{m2}]]]] @gol
--falign-jumps[=@var{n}[:@var{m}:[@var{n2}[:@var{m2}]]]] @gol
--falign-labels[=@var{n}[:@var{m}:[@var{n2}[:@var{m2}]]]] @gol
--falign-loops[=@var{n}[:@var{m}:[@var{n2}[:@var{m2}]]]] @gol
--fno-allocation-dce -fallow-store-data-races @gol
--fassociative-math -fauto-profile -fauto-profile[=@var{path}] @gol
--fauto-inc-dec -fbranch-probabilities @gol
--fcaller-saves @gol
--fcombine-stack-adjustments -fconserve-stack @gol
--fcompare-elim -fcprop-registers -fcrossjumping @gol
--fcse-follow-jumps -fcse-skip-blocks -fcx-fortran-rules @gol
--fcx-limited-range @gol
--fdata-sections -fdce -fdelayed-branch @gol
--fdelete-null-pointer-checks -fdevirtualize -fdevirtualize-speculatively @gol
--fdevirtualize-at-ltrans -fdse @gol
--fearly-inlining -fipa-sra -fexpensive-optimizations -ffat-lto-objects @gol
--ffast-math -ffinite-math-only -ffloat-store -fexcess-precision=@var{style} @gol
--ffinite-loops @gol
--fforward-propagate -ffp-contract=@var{style} -ffunction-sections @gol
--fgcse -fgcse-after-reload -fgcse-las -fgcse-lm -fgraphite-identity @gol
--fgcse-sm -fhoist-adjacent-loads -fif-conversion @gol
--fif-conversion2 -findirect-inlining @gol
--finline-functions -finline-functions-called-once -finline-limit=@var{n} @gol
--finline-small-functions -fipa-modref -fipa-cp -fipa-cp-clone @gol
--fipa-bit-cp -fipa-vrp -fipa-pta -fipa-profile -fipa-pure-const @gol
--fipa-reference -fipa-reference-addressable @gol
--fipa-stack-alignment -fipa-icf -fira-algorithm=@var{algorithm} @gol
--flive-patching=@var{level} @gol
--fira-region=@var{region} -fira-hoist-pressure @gol
--fira-loop-pressure -fno-ira-share-save-slots @gol
--fno-ira-share-spill-slots @gol
--fisolate-erroneous-paths-dereference -fisolate-erroneous-paths-attribute @gol
--fivopts -fkeep-inline-functions -fkeep-static-functions @gol
--fkeep-static-consts -flimit-function-alignment -flive-range-shrinkage @gol
--floop-block -floop-interchange -floop-strip-mine @gol
--floop-unroll-and-jam -floop-nest-optimize @gol
--floop-parallelize-all -flra-remat -flto -flto-compression-level @gol
--flto-partition=@var{alg} -fmerge-all-constants @gol
--fmerge-constants -fmodulo-sched -fmodulo-sched-allow-regmoves @gol
--fmove-loop-invariants -fmove-loop-stores -fno-branch-count-reg @gol
--fno-defer-pop -fno-fp-int-builtin-inexact -fno-function-cse @gol
--fno-guess-branch-probability -fno-inline -fno-math-errno -fno-peephole @gol
--fno-peephole2 -fno-printf-return-value -fno-sched-interblock @gol
--fno-sched-spec -fno-signed-zeros @gol
--fno-toplevel-reorder -fno-trapping-math -fno-zero-initialized-in-bss @gol
--fomit-frame-pointer -foptimize-sibling-calls @gol
--fpartial-inlining -fpeel-loops -fpredictive-commoning @gol
--fprefetch-loop-arrays @gol
--fprofile-correction @gol
--fprofile-use -fprofile-use=@var{path} -fprofile-partial-training @gol
--fprofile-values -fprofile-reorder-functions @gol
--freciprocal-math -free -frename-registers -freorder-blocks @gol
--freorder-blocks-algorithm=@var{algorithm} @gol
--freorder-blocks-and-partition -freorder-functions @gol
--frerun-cse-after-loop -freschedule-modulo-scheduled-loops @gol
--frounding-math -fsave-optimization-record @gol
--fsched2-use-superblocks -fsched-pressure @gol
--fsched-spec-load -fsched-spec-load-dangerous @gol
--fsched-stalled-insns-dep[=@var{n}] -fsched-stalled-insns[=@var{n}] @gol
--fsched-group-heuristic -fsched-critical-path-heuristic @gol
--fsched-spec-insn-heuristic -fsched-rank-heuristic @gol
--fsched-last-insn-heuristic -fsched-dep-count-heuristic @gol
--fschedule-fusion @gol
--fschedule-insns -fschedule-insns2 -fsection-anchors @gol
--fselective-scheduling -fselective-scheduling2 @gol
--fsel-sched-pipelining -fsel-sched-pipelining-outer-loops @gol
--fsemantic-interposition -fshrink-wrap -fshrink-wrap-separate @gol
--fsignaling-nans @gol
--fsingle-precision-constant -fsplit-ivs-in-unroller -fsplit-loops@gol
--fsplit-paths @gol
--fsplit-wide-types -fsplit-wide-types-early -fssa-backprop -fssa-phiopt @gol
--fstdarg-opt -fstore-merging -fstrict-aliasing -fipa-strict-aliasing @gol
--fthread-jumps -ftracer -ftree-bit-ccp @gol
--ftree-builtin-call-dce -ftree-ccp -ftree-ch @gol
--ftree-coalesce-vars -ftree-copy-prop -ftree-dce -ftree-dominator-opts @gol
--ftree-dse -ftree-forwprop -ftree-fre -fcode-hoisting @gol
--ftree-loop-if-convert -ftree-loop-im @gol
--ftree-phiprop -ftree-loop-distribution -ftree-loop-distribute-patterns @gol
--ftree-loop-ivcanon -ftree-loop-linear -ftree-loop-optimize @gol
--ftree-loop-vectorize @gol
--ftree-parallelize-loops=@var{n} -ftree-pre -ftree-partial-pre -ftree-pta @gol
--ftree-reassoc -ftree-scev-cprop -ftree-sink -ftree-slsr -ftree-sra @gol
--ftree-switch-conversion -ftree-tail-merge @gol
--ftree-ter -ftree-vectorize -ftree-vrp -ftrivial-auto-var-init @gol
--funconstrained-commons -funit-at-a-time -funroll-all-loops @gol
--funroll-loops -funsafe-math-optimizations -funswitch-loops @gol
--fipa-ra -fvariable-expansion-in-unroller -fvect-cost-model -fvpt @gol
--fweb -fwhole-program -fwpa -fuse-linker-plugin -fzero-call-used-regs @gol
---param @var{name}=@var{value}
--O -O0 -O1 -O2 -O3 -Os -Ofast -Og -Oz}
-
-@item Program Instrumentation Options
-@xref{Instrumentation Options,,Program Instrumentation Options}.
-@gccoptlist{-p -pg -fprofile-arcs --coverage -ftest-coverage @gol
--fprofile-abs-path @gol
--fprofile-dir=@var{path} -fprofile-generate -fprofile-generate=@var{path} @gol
--fprofile-info-section -fprofile-info-section=@var{name} @gol
--fprofile-note=@var{path} -fprofile-prefix-path=@var{path} @gol
--fprofile-update=@var{method} -fprofile-filter-files=@var{regex} @gol
--fprofile-exclude-files=@var{regex} @gol
--fprofile-reproducible=@r{[}multithreaded@r{|}parallel-runs@r{|}serial@r{]} @gol
--fsanitize=@var{style} -fsanitize-recover -fsanitize-recover=@var{style} @gol
--fsanitize-trap -fsanitize-trap=@var{style} @gol
--fasan-shadow-offset=@var{number} -fsanitize-sections=@var{s1},@var{s2},... @gol
--fsanitize-undefined-trap-on-error -fbounds-check @gol
--fcf-protection=@r{[}full@r{|}branch@r{|}return@r{|}none@r{|}check@r{]} @gol
--fharden-compares -fharden-conditional-branches @gol
--fstack-protector -fstack-protector-all -fstack-protector-strong @gol
--fstack-protector-explicit -fstack-check @gol
--fstack-limit-register=@var{reg} -fstack-limit-symbol=@var{sym} @gol
--fno-stack-limit -fsplit-stack @gol
--fvtable-verify=@r{[}std@r{|}preinit@r{|}none@r{]} @gol
--fvtv-counts -fvtv-debug @gol
--finstrument-functions -finstrument-functions-once @gol
--finstrument-functions-exclude-function-list=@var{sym},@var{sym},@dots{} @gol
--finstrument-functions-exclude-file-list=@var{file},@var{file},@dots{}} @gol
--fprofile-prefix-map=@var{old}=@var{new}
-
-@item Preprocessor Options
-@xref{Preprocessor Options,,Options Controlling the Preprocessor}.
-@gccoptlist{-A@var{question}=@var{answer} @gol
--A-@var{question}@r{[}=@var{answer}@r{]} @gol
--C -CC -D@var{macro}@r{[}=@var{defn}@r{]} @gol
--dD -dI -dM -dN -dU @gol
--fdebug-cpp -fdirectives-only -fdollars-in-identifiers @gol
--fexec-charset=@var{charset} -fextended-identifiers @gol
--finput-charset=@var{charset} -flarge-source-files @gol
--fmacro-prefix-map=@var{old}=@var{new} -fmax-include-depth=@var{depth} @gol
--fno-canonical-system-headers -fpch-deps -fpch-preprocess @gol
--fpreprocessed -ftabstop=@var{width} -ftrack-macro-expansion @gol
--fwide-exec-charset=@var{charset} -fworking-directory @gol
--H -imacros @var{file} -include @var{file} @gol
--M -MD -MF -MG -MM -MMD -MP -MQ -MT -Mno-modules @gol
--no-integrated-cpp -P -pthread -remap @gol
--traditional -traditional-cpp -trigraphs @gol
--U@var{macro} -undef @gol
--Wp,@var{option} -Xpreprocessor @var{option}}
-
-@item Assembler Options
-@xref{Assembler Options,,Passing Options to the Assembler}.
-@gccoptlist{-Wa,@var{option} -Xassembler @var{option}}
-
-@item Linker Options
-@xref{Link Options,,Options for Linking}.
-@gccoptlist{@var{object-file-name} -fuse-ld=@var{linker} -l@var{library} @gol
--nostartfiles -nodefaultlibs -nolibc -nostdlib -nostdlib++ @gol
--e @var{entry} --entry=@var{entry} @gol
--pie -pthread -r -rdynamic @gol
--s -static -static-pie -static-libgcc -static-libstdc++ @gol
--static-libasan -static-libtsan -static-liblsan -static-libubsan @gol
--shared -shared-libgcc -symbolic @gol
--T @var{script} -Wl,@var{option} -Xlinker @var{option} @gol
--u @var{symbol} -z @var{keyword}}
-
-@item Directory Options
-@xref{Directory Options,,Options for Directory Search}.
-@gccoptlist{-B@var{prefix} -I@var{dir} -I- @gol
--idirafter @var{dir} @gol
--imacros @var{file} -imultilib @var{dir} @gol
--iplugindir=@var{dir} -iprefix @var{file} @gol
--iquote @var{dir} -isysroot @var{dir} -isystem @var{dir} @gol
--iwithprefix @var{dir} -iwithprefixbefore @var{dir} @gol
--L@var{dir} -no-canonical-prefixes --no-sysroot-suffix @gol
--nostdinc -nostdinc++ --sysroot=@var{dir}}
-
-@item Code Generation Options
-@xref{Code Gen Options,,Options for Code Generation Conventions}.
-@gccoptlist{-fcall-saved-@var{reg} -fcall-used-@var{reg} @gol
--ffixed-@var{reg} -fexceptions @gol
--fnon-call-exceptions -fdelete-dead-exceptions -funwind-tables @gol
--fasynchronous-unwind-tables @gol
--fno-gnu-unique @gol
--finhibit-size-directive -fcommon -fno-ident @gol
--fpcc-struct-return -fpic -fPIC -fpie -fPIE -fno-plt @gol
--fno-jump-tables -fno-bit-tests @gol
--frecord-gcc-switches @gol
--freg-struct-return -fshort-enums -fshort-wchar @gol
--fverbose-asm -fpack-struct[=@var{n}] @gol
--fleading-underscore -ftls-model=@var{model} @gol
--fstack-reuse=@var{reuse_level} @gol
--ftrampolines -ftrapv -fwrapv @gol
--fvisibility=@r{[}default@r{|}internal@r{|}hidden@r{|}protected@r{]} @gol
--fstrict-volatile-bitfields -fsync-libcalls}
-
-@item Developer Options
-@xref{Developer Options,,GCC Developer Options}.
-@gccoptlist{-d@var{letters} -dumpspecs -dumpmachine -dumpversion @gol
--dumpfullversion -fcallgraph-info@r{[}=su,da@r{]}
--fchecking -fchecking=@var{n}
--fdbg-cnt-list @gol -fdbg-cnt=@var{counter-value-list} @gol
--fdisable-ipa-@var{pass_name} @gol
--fdisable-rtl-@var{pass_name} @gol
--fdisable-rtl-@var{pass-name}=@var{range-list} @gol
--fdisable-tree-@var{pass_name} @gol
--fdisable-tree-@var{pass-name}=@var{range-list} @gol
--fdump-debug -fdump-earlydebug @gol
--fdump-noaddr -fdump-unnumbered -fdump-unnumbered-links @gol
--fdump-final-insns@r{[}=@var{file}@r{]} @gol
--fdump-ipa-all -fdump-ipa-cgraph -fdump-ipa-inline @gol
--fdump-lang-all @gol
--fdump-lang-@var{switch} @gol
--fdump-lang-@var{switch}-@var{options} @gol
--fdump-lang-@var{switch}-@var{options}=@var{filename} @gol
--fdump-passes @gol
--fdump-rtl-@var{pass} -fdump-rtl-@var{pass}=@var{filename} @gol
--fdump-statistics @gol
--fdump-tree-all @gol
--fdump-tree-@var{switch} @gol
--fdump-tree-@var{switch}-@var{options} @gol
--fdump-tree-@var{switch}-@var{options}=@var{filename} @gol
--fcompare-debug@r{[}=@var{opts}@r{]} -fcompare-debug-second @gol
--fenable-@var{kind}-@var{pass} @gol
--fenable-@var{kind}-@var{pass}=@var{range-list} @gol
--fira-verbose=@var{n} @gol
--flto-report -flto-report-wpa -fmem-report-wpa @gol
--fmem-report -fpre-ipa-mem-report -fpost-ipa-mem-report @gol
--fopt-info -fopt-info-@var{options}@r{[}=@var{file}@r{]} @gol
--fmultiflags -fprofile-report @gol
--frandom-seed=@var{string} -fsched-verbose=@var{n} @gol
--fsel-sched-verbose -fsel-sched-dump-cfg -fsel-sched-pipelining-verbose @gol
--fstats -fstack-usage -ftime-report -ftime-report-details @gol
--fvar-tracking-assignments-toggle -gtoggle @gol
--print-file-name=@var{library} -print-libgcc-file-name @gol
--print-multi-directory -print-multi-lib -print-multi-os-directory @gol
--print-prog-name=@var{program} -print-search-dirs -Q @gol
--print-sysroot -print-sysroot-headers-suffix @gol
--save-temps -save-temps=cwd -save-temps=obj -time@r{[}=@var{file}@r{]}}
-
-@item Machine-Dependent Options
-@xref{Submodel Options,,Machine-Dependent Options}.
-@c This list is ordered alphanumerically by subsection name.
-@c Try and put the significant identifier (CPU or system) first,
-@c so users have a clue at guessing where the ones they want will be.
-
-@emph{AArch64 Options}
-@gccoptlist{-mabi=@var{name} -mbig-endian -mlittle-endian @gol
--mgeneral-regs-only @gol
--mcmodel=tiny -mcmodel=small -mcmodel=large @gol
--mstrict-align -mno-strict-align @gol
--momit-leaf-frame-pointer @gol
--mtls-dialect=desc -mtls-dialect=traditional @gol
--mtls-size=@var{size} @gol
--mfix-cortex-a53-835769 -mfix-cortex-a53-843419 @gol
--mlow-precision-recip-sqrt -mlow-precision-sqrt -mlow-precision-div @gol
--mpc-relative-literal-loads @gol
--msign-return-address=@var{scope} @gol
--mbranch-protection=@var{none}|@var{standard}|@var{pac-ret}[+@var{leaf}
-+@var{b-key}]|@var{bti} @gol
--mharden-sls=@var{opts} @gol
--march=@var{name} -mcpu=@var{name} -mtune=@var{name} @gol
--moverride=@var{string} -mverbose-cost-dump @gol
--mstack-protector-guard=@var{guard} -mstack-protector-guard-reg=@var{sysreg} @gol
--mstack-protector-guard-offset=@var{offset} -mtrack-speculation @gol
--moutline-atomics }
-
-@emph{Adapteva Epiphany Options}
-@gccoptlist{-mhalf-reg-file -mprefer-short-insn-regs @gol
--mbranch-cost=@var{num} -mcmove -mnops=@var{num} -msoft-cmpsf @gol
--msplit-lohi -mpost-inc -mpost-modify -mstack-offset=@var{num} @gol
--mround-nearest -mlong-calls -mshort-calls -msmall16 @gol
--mfp-mode=@var{mode} -mvect-double -max-vect-align=@var{num} @gol
--msplit-vecmove-early -m1reg-@var{reg}}
-
-@emph{AMD GCN Options}
-@gccoptlist{-march=@var{gpu} -mtune=@var{gpu} -mstack-size=@var{bytes}}
-
-@emph{ARC Options}
-@gccoptlist{-mbarrel-shifter -mjli-always @gol
--mcpu=@var{cpu} -mA6 -mARC600 -mA7 -mARC700 @gol
--mdpfp -mdpfp-compact -mdpfp-fast -mno-dpfp-lrsr @gol
--mea -mno-mpy -mmul32x16 -mmul64 -matomic @gol
--mnorm -mspfp -mspfp-compact -mspfp-fast -msimd -msoft-float -mswap @gol
--mcrc -mdsp-packa -mdvbf -mlock -mmac-d16 -mmac-24 -mrtsc -mswape @gol
--mtelephony -mxy -misize -mannotate-align -marclinux -marclinux_prof @gol
--mlong-calls -mmedium-calls -msdata -mirq-ctrl-saved @gol
--mrgf-banked-regs -mlpc-width=@var{width} -G @var{num} @gol
--mvolatile-cache -mtp-regno=@var{regno} @gol
--malign-call -mauto-modify-reg -mbbit-peephole -mno-brcc @gol
--mcase-vector-pcrel -mcompact-casesi -mno-cond-exec -mearly-cbranchsi @gol
--mexpand-adddi -mindexed-loads -mlra -mlra-priority-none @gol
--mlra-priority-compact -mlra-priority-noncompact -mmillicode @gol
--mmixed-code -mq-class -mRcq -mRcw -msize-level=@var{level} @gol
--mtune=@var{cpu} -mmultcost=@var{num} -mcode-density-frame @gol
--munalign-prob-threshold=@var{probability} -mmpy-option=@var{multo} @gol
--mdiv-rem -mcode-density -mll64 -mfpu=@var{fpu} -mrf16 -mbranch-index}
-
-@emph{ARM Options}
-@gccoptlist{-mapcs-frame -mno-apcs-frame @gol
--mabi=@var{name} @gol
--mapcs-stack-check -mno-apcs-stack-check @gol
--mapcs-reentrant -mno-apcs-reentrant @gol
--mgeneral-regs-only @gol
--msched-prolog -mno-sched-prolog @gol
--mlittle-endian -mbig-endian @gol
--mbe8 -mbe32 @gol
--mfloat-abi=@var{name} @gol
--mfp16-format=@var{name}
--mthumb-interwork -mno-thumb-interwork @gol
--mcpu=@var{name} -march=@var{name} -mfpu=@var{name} @gol
--mtune=@var{name} -mprint-tune-info @gol
--mstructure-size-boundary=@var{n} @gol
--mabort-on-noreturn @gol
--mlong-calls -mno-long-calls @gol
--msingle-pic-base -mno-single-pic-base @gol
--mpic-register=@var{reg} @gol
--mnop-fun-dllimport @gol
--mpoke-function-name @gol
--mthumb -marm -mflip-thumb @gol
--mtpcs-frame -mtpcs-leaf-frame @gol
--mcaller-super-interworking -mcallee-super-interworking @gol
--mtp=@var{name} -mtls-dialect=@var{dialect} @gol
--mword-relocations @gol
--mfix-cortex-m3-ldrd @gol
--mfix-cortex-a57-aes-1742098 @gol
--mfix-cortex-a72-aes-1655431 @gol
--munaligned-access @gol
--mneon-for-64bits @gol
--mslow-flash-data @gol
--masm-syntax-unified @gol
--mrestrict-it @gol
--mverbose-cost-dump @gol
--mpure-code @gol
--mcmse @gol
--mfix-cmse-cve-2021-35465 @gol
--mstack-protector-guard=@var{guard} -mstack-protector-guard-offset=@var{offset} @gol
--mfdpic}
-
-@emph{AVR Options}
-@gccoptlist{-mmcu=@var{mcu} -mabsdata -maccumulate-args @gol
--mbranch-cost=@var{cost} @gol
--mcall-prologues -mgas-isr-prologues -mint8 @gol
--mdouble=@var{bits} -mlong-double=@var{bits} @gol
--mn_flash=@var{size} -mno-interrupts @gol
--mmain-is-OS_task -mrelax -mrmw -mstrict-X -mtiny-stack @gol
--mfract-convert-truncate @gol
--mshort-calls -nodevicelib -nodevicespecs @gol
--Waddr-space-convert -Wmisspelled-isr}
-
-@emph{Blackfin Options}
-@gccoptlist{-mcpu=@var{cpu}@r{[}-@var{sirevision}@r{]} @gol
--msim -momit-leaf-frame-pointer -mno-omit-leaf-frame-pointer @gol
--mspecld-anomaly -mno-specld-anomaly -mcsync-anomaly -mno-csync-anomaly @gol
--mlow-64k -mno-low64k -mstack-check-l1 -mid-shared-library @gol
--mno-id-shared-library -mshared-library-id=@var{n} @gol
--mleaf-id-shared-library -mno-leaf-id-shared-library @gol
--msep-data -mno-sep-data -mlong-calls -mno-long-calls @gol
--mfast-fp -minline-plt -mmulticore -mcorea -mcoreb -msdram @gol
--micplb}
-
-@emph{C6X Options}
-@gccoptlist{-mbig-endian -mlittle-endian -march=@var{cpu} @gol
--msim -msdata=@var{sdata-type}}
-
-@emph{CRIS Options}
-@gccoptlist{-mcpu=@var{cpu} -march=@var{cpu}
--mtune=@var{cpu} -mmax-stack-frame=@var{n} @gol
--metrax4 -metrax100 -mpdebug -mcc-init -mno-side-effects @gol
--mstack-align -mdata-align -mconst-align @gol
--m32-bit -m16-bit -m8-bit -mno-prologue-epilogue @gol
--melf -maout -sim -sim2 @gol
--mmul-bug-workaround -mno-mul-bug-workaround}
-
-@emph{C-SKY Options}
-@gccoptlist{-march=@var{arch} -mcpu=@var{cpu} @gol
--mbig-endian -EB -mlittle-endian -EL @gol
--mhard-float -msoft-float -mfpu=@var{fpu} -mdouble-float -mfdivdu @gol
--mfloat-abi=@var{name} @gol
--melrw -mistack -mmp -mcp -mcache -msecurity -mtrust @gol
--mdsp -medsp -mvdsp @gol
--mdiv -msmart -mhigh-registers -manchor @gol
--mpushpop -mmultiple-stld -mconstpool -mstack-size -mccrt @gol
--mbranch-cost=@var{n} -mcse-cc -msched-prolog -msim}
-
-@emph{Darwin Options}
-@gccoptlist{-all_load -allowable_client -arch -arch_errors_fatal @gol
--arch_only -bind_at_load -bundle -bundle_loader @gol
--client_name -compatibility_version -current_version @gol
--dead_strip @gol
--dependency-file -dylib_file -dylinker_install_name @gol
--dynamic -dynamiclib -exported_symbols_list @gol
--filelist -flat_namespace -force_cpusubtype_ALL @gol
--force_flat_namespace -headerpad_max_install_names @gol
--iframework @gol
--image_base -init -install_name -keep_private_externs @gol
--multi_module -multiply_defined -multiply_defined_unused @gol
--noall_load -no_dead_strip_inits_and_terms @gol
--nofixprebinding -nomultidefs -noprebind -noseglinkedit @gol
--pagezero_size -prebind -prebind_all_twolevel_modules @gol
--private_bundle -read_only_relocs -sectalign @gol
--sectobjectsymbols -whyload -seg1addr @gol
--sectcreate -sectobjectsymbols -sectorder @gol
--segaddr -segs_read_only_addr -segs_read_write_addr @gol
--seg_addr_table -seg_addr_table_filename -seglinkedit @gol
--segprot -segs_read_only_addr -segs_read_write_addr @gol
--single_module -static -sub_library -sub_umbrella @gol
--twolevel_namespace -umbrella -undefined @gol
--unexported_symbols_list -weak_reference_mismatches @gol
--whatsloaded -F -gused -gfull -mmacosx-version-min=@var{version} @gol
--mkernel -mone-byte-bool}
-
-@emph{DEC Alpha Options}
-@gccoptlist{-mno-fp-regs -msoft-float @gol
--mieee -mieee-with-inexact -mieee-conformant @gol
--mfp-trap-mode=@var{mode} -mfp-rounding-mode=@var{mode} @gol
--mtrap-precision=@var{mode} -mbuild-constants @gol
--mcpu=@var{cpu-type} -mtune=@var{cpu-type} @gol
--mbwx -mmax -mfix -mcix @gol
--mfloat-vax -mfloat-ieee @gol
--mexplicit-relocs -msmall-data -mlarge-data @gol
--msmall-text -mlarge-text @gol
--mmemory-latency=@var{time}}
-
-@emph{eBPF Options}
-@gccoptlist{-mbig-endian -mlittle-endian -mkernel=@var{version}
--mframe-limit=@var{bytes} -mxbpf -mco-re -mno-co-re
--mjmpext -mjmp32 -malu32 -mcpu=@var{version}}
-
-@emph{FR30 Options}
-@gccoptlist{-msmall-model -mno-lsim}
-
-@emph{FT32 Options}
-@gccoptlist{-msim -mlra -mnodiv -mft32b -mcompress -mnopm}
-
-@emph{FRV Options}
-@gccoptlist{-mgpr-32 -mgpr-64 -mfpr-32 -mfpr-64 @gol
--mhard-float -msoft-float @gol
--malloc-cc -mfixed-cc -mdword -mno-dword @gol
--mdouble -mno-double @gol
--mmedia -mno-media -mmuladd -mno-muladd @gol
--mfdpic -minline-plt -mgprel-ro -multilib-library-pic @gol
--mlinked-fp -mlong-calls -malign-labels @gol
--mlibrary-pic -macc-4 -macc-8 @gol
--mpack -mno-pack -mno-eflags -mcond-move -mno-cond-move @gol
--moptimize-membar -mno-optimize-membar @gol
--mscc -mno-scc -mcond-exec -mno-cond-exec @gol
--mvliw-branch -mno-vliw-branch @gol
--mmulti-cond-exec -mno-multi-cond-exec -mnested-cond-exec @gol
--mno-nested-cond-exec -mtomcat-stats @gol
--mTLS -mtls @gol
--mcpu=@var{cpu}}
-
-@emph{GNU/Linux Options}
-@gccoptlist{-mglibc -muclibc -mmusl -mbionic -mandroid @gol
--tno-android-cc -tno-android-ld}
-
-@emph{H8/300 Options}
-@gccoptlist{-mrelax -mh -ms -mn -mexr -mno-exr -mint32 -malign-300}
-
-@emph{HPPA Options}
-@gccoptlist{-march=@var{architecture-type} @gol
--mcaller-copies -mdisable-fpregs -mdisable-indexing @gol
--mfast-indirect-calls -mgas -mgnu-ld -mhp-ld @gol
--mfixed-range=@var{register-range} @gol
--mjump-in-delay -mlinker-opt -mlong-calls @gol
--mlong-load-store -mno-disable-fpregs @gol
--mno-disable-indexing -mno-fast-indirect-calls -mno-gas @gol
--mno-jump-in-delay -mno-long-load-store @gol
--mno-portable-runtime -mno-soft-float @gol
--mno-space-regs -msoft-float -mpa-risc-1-0 @gol
--mpa-risc-1-1 -mpa-risc-2-0 -mportable-runtime @gol
--mschedule=@var{cpu-type} -mspace-regs -msio -mwsio @gol
--munix=@var{unix-std} -nolibdld -static -threads}
-
-@emph{IA-64 Options}
-@gccoptlist{-mbig-endian -mlittle-endian -mgnu-as -mgnu-ld -mno-pic @gol
--mvolatile-asm-stop -mregister-names -msdata -mno-sdata @gol
--mconstant-gp -mauto-pic -mfused-madd @gol
--minline-float-divide-min-latency @gol
--minline-float-divide-max-throughput @gol
--mno-inline-float-divide @gol
--minline-int-divide-min-latency @gol
--minline-int-divide-max-throughput @gol
--mno-inline-int-divide @gol
--minline-sqrt-min-latency -minline-sqrt-max-throughput @gol
--mno-inline-sqrt @gol
--mdwarf2-asm -mearly-stop-bits @gol
--mfixed-range=@var{register-range} -mtls-size=@var{tls-size} @gol
--mtune=@var{cpu-type} -milp32 -mlp64 @gol
--msched-br-data-spec -msched-ar-data-spec -msched-control-spec @gol
--msched-br-in-data-spec -msched-ar-in-data-spec -msched-in-control-spec @gol
--msched-spec-ldc -msched-spec-control-ldc @gol
--msched-prefer-non-data-spec-insns -msched-prefer-non-control-spec-insns @gol
--msched-stop-bits-after-every-cycle -msched-count-spec-in-critical-path @gol
--msel-sched-dont-check-control-spec -msched-fp-mem-deps-zero-cost @gol
--msched-max-memory-insns-hard-limit -msched-max-memory-insns=@var{max-insns}}
-
-@emph{LM32 Options}
-@gccoptlist{-mbarrel-shift-enabled -mdivide-enabled -mmultiply-enabled @gol
--msign-extend-enabled -muser-enabled}
-
-@emph{LoongArch Options}
-@gccoptlist{-march=@var{cpu-type} -mtune=@var{cpu-type} -mabi=@var{base-abi-type} @gol
--mfpu=@var{fpu-type} -msoft-float -msingle-float -mdouble-float @gol
--mbranch-cost=@var{n} -mcheck-zero-division -mno-check-zero-division @gol
--mcond-move-int -mno-cond-move-int @gol
--mcond-move-float -mno-cond-move-float @gol
--memcpy -mno-memcpy -mstrict-align -mno-strict-align @gol
--mmax-inline-memcpy-size=@var{n} @gol
--mexplicit-relocs -mno-explicit-relocs @gol
--mdirect-extern-access -mno-direct-extern-access @gol
--mcmodel=@var{code-model}}
-
-@emph{M32R/D Options}
-@gccoptlist{-m32r2 -m32rx -m32r @gol
--mdebug @gol
--malign-loops -mno-align-loops @gol
--missue-rate=@var{number} @gol
--mbranch-cost=@var{number} @gol
--mmodel=@var{code-size-model-type} @gol
--msdata=@var{sdata-type} @gol
--mno-flush-func -mflush-func=@var{name} @gol
--mno-flush-trap -mflush-trap=@var{number} @gol
--G @var{num}}
-
-@emph{M32C Options}
-@gccoptlist{-mcpu=@var{cpu} -msim -memregs=@var{number}}
-
-@emph{M680x0 Options}
-@gccoptlist{-march=@var{arch} -mcpu=@var{cpu} -mtune=@var{tune} @gol
--m68000 -m68020 -m68020-40 -m68020-60 -m68030 -m68040 @gol
--m68060 -mcpu32 -m5200 -m5206e -m528x -m5307 -m5407 @gol
--mcfv4e -mbitfield -mno-bitfield -mc68000 -mc68020 @gol
--mnobitfield -mrtd -mno-rtd -mdiv -mno-div -mshort @gol
--mno-short -mhard-float -m68881 -msoft-float -mpcrel @gol
--malign-int -mstrict-align -msep-data -mno-sep-data @gol
--mshared-library-id=n -mid-shared-library -mno-id-shared-library @gol
--mxgot -mno-xgot -mlong-jump-table-offsets}
-
-@emph{MCore Options}
-@gccoptlist{-mhardlit -mno-hardlit -mdiv -mno-div -mrelax-immediates @gol
--mno-relax-immediates -mwide-bitfields -mno-wide-bitfields @gol
--m4byte-functions -mno-4byte-functions -mcallgraph-data @gol
--mno-callgraph-data -mslow-bytes -mno-slow-bytes -mno-lsim @gol
--mlittle-endian -mbig-endian -m210 -m340 -mstack-increment}
-
-@emph{MeP Options}
-@gccoptlist{-mabsdiff -mall-opts -maverage -mbased=@var{n} -mbitops @gol
--mc=@var{n} -mclip -mconfig=@var{name} -mcop -mcop32 -mcop64 -mivc2 @gol
--mdc -mdiv -meb -mel -mio-volatile -ml -mleadz -mm -mminmax @gol
--mmult -mno-opts -mrepeat -ms -msatur -msdram -msim -msimnovec -mtf @gol
--mtiny=@var{n}}
-
-@emph{MicroBlaze Options}
-@gccoptlist{-msoft-float -mhard-float -msmall-divides -mcpu=@var{cpu} @gol
--mmemcpy -mxl-soft-mul -mxl-soft-div -mxl-barrel-shift @gol
--mxl-pattern-compare -mxl-stack-check -mxl-gp-opt -mno-clearbss @gol
--mxl-multiply-high -mxl-float-convert -mxl-float-sqrt @gol
--mbig-endian -mlittle-endian -mxl-reorder -mxl-mode-@var{app-model} @gol
--mpic-data-is-text-relative}
-
-@emph{MIPS Options}
-@gccoptlist{-EL -EB -march=@var{arch} -mtune=@var{arch} @gol
--mips1 -mips2 -mips3 -mips4 -mips32 -mips32r2 -mips32r3 -mips32r5 @gol
--mips32r6 -mips64 -mips64r2 -mips64r3 -mips64r5 -mips64r6 @gol
--mips16 -mno-mips16 -mflip-mips16 @gol
--minterlink-compressed -mno-interlink-compressed @gol
--minterlink-mips16 -mno-interlink-mips16 @gol
--mabi=@var{abi} -mabicalls -mno-abicalls @gol
--mshared -mno-shared -mplt -mno-plt -mxgot -mno-xgot @gol
--mgp32 -mgp64 -mfp32 -mfpxx -mfp64 -mhard-float -msoft-float @gol
--mno-float -msingle-float -mdouble-float @gol
--modd-spreg -mno-odd-spreg @gol
--mabs=@var{mode} -mnan=@var{encoding} @gol
--mdsp -mno-dsp -mdspr2 -mno-dspr2 @gol
--mmcu -mmno-mcu @gol
--meva -mno-eva @gol
--mvirt -mno-virt @gol
--mxpa -mno-xpa @gol
--mcrc -mno-crc @gol
--mginv -mno-ginv @gol
--mmicromips -mno-micromips @gol
--mmsa -mno-msa @gol
--mloongson-mmi -mno-loongson-mmi @gol
--mloongson-ext -mno-loongson-ext @gol
--mloongson-ext2 -mno-loongson-ext2 @gol
--mfpu=@var{fpu-type} @gol
--msmartmips -mno-smartmips @gol
--mpaired-single -mno-paired-single -mdmx -mno-mdmx @gol
--mips3d -mno-mips3d -mmt -mno-mt -mllsc -mno-llsc @gol
--mlong64 -mlong32 -msym32 -mno-sym32 @gol
--G@var{num} -mlocal-sdata -mno-local-sdata @gol
--mextern-sdata -mno-extern-sdata -mgpopt -mno-gopt @gol
--membedded-data -mno-embedded-data @gol
--muninit-const-in-rodata -mno-uninit-const-in-rodata @gol
--mcode-readable=@var{setting} @gol
--msplit-addresses -mno-split-addresses @gol
--mexplicit-relocs -mno-explicit-relocs @gol
--mcheck-zero-division -mno-check-zero-division @gol
--mdivide-traps -mdivide-breaks @gol
--mload-store-pairs -mno-load-store-pairs @gol
--munaligned-access -mno-unaligned-access @gol
--mmemcpy -mno-memcpy -mlong-calls -mno-long-calls @gol
--mmad -mno-mad -mimadd -mno-imadd -mfused-madd -mno-fused-madd -nocpp @gol
--mfix-24k -mno-fix-24k @gol
--mfix-r4000 -mno-fix-r4000 -mfix-r4400 -mno-fix-r4400 @gol
--mfix-r5900 -mno-fix-r5900 @gol
--mfix-r10000 -mno-fix-r10000 -mfix-rm7000 -mno-fix-rm7000 @gol
--mfix-vr4120 -mno-fix-vr4120 @gol
--mfix-vr4130 -mno-fix-vr4130 -mfix-sb1 -mno-fix-sb1 @gol
--mflush-func=@var{func} -mno-flush-func @gol
--mbranch-cost=@var{num} -mbranch-likely -mno-branch-likely @gol
--mcompact-branches=@var{policy} @gol
--mfp-exceptions -mno-fp-exceptions @gol
--mvr4130-align -mno-vr4130-align -msynci -mno-synci @gol
--mlxc1-sxc1 -mno-lxc1-sxc1 -mmadd4 -mno-madd4 @gol
--mrelax-pic-calls -mno-relax-pic-calls -mmcount-ra-address @gol
--mframe-header-opt -mno-frame-header-opt}
-
-@emph{MMIX Options}
-@gccoptlist{-mlibfuncs -mno-libfuncs -mepsilon -mno-epsilon -mabi=gnu @gol
--mabi=mmixware -mzero-extend -mknuthdiv -mtoplevel-symbols @gol
--melf -mbranch-predict -mno-branch-predict -mbase-addresses @gol
--mno-base-addresses -msingle-exit -mno-single-exit}
-
-@emph{MN10300 Options}
-@gccoptlist{-mmult-bug -mno-mult-bug @gol
--mno-am33 -mam33 -mam33-2 -mam34 @gol
--mtune=@var{cpu-type} @gol
--mreturn-pointer-on-d0 @gol
--mno-crt0 -mrelax -mliw -msetlb}
-
-@emph{Moxie Options}
-@gccoptlist{-meb -mel -mmul.x -mno-crt0}
-
-@emph{MSP430 Options}
-@gccoptlist{-msim -masm-hex -mmcu= -mcpu= -mlarge -msmall -mrelax @gol
--mwarn-mcu @gol
--mcode-region= -mdata-region= @gol
--msilicon-errata= -msilicon-errata-warn= @gol
--mhwmult= -minrt -mtiny-printf -mmax-inline-shift=}
-
-@emph{NDS32 Options}
-@gccoptlist{-mbig-endian -mlittle-endian @gol
--mreduced-regs -mfull-regs @gol
--mcmov -mno-cmov @gol
--mext-perf -mno-ext-perf @gol
--mext-perf2 -mno-ext-perf2 @gol
--mext-string -mno-ext-string @gol
--mv3push -mno-v3push @gol
--m16bit -mno-16bit @gol
--misr-vector-size=@var{num} @gol
--mcache-block-size=@var{num} @gol
--march=@var{arch} @gol
--mcmodel=@var{code-model} @gol
--mctor-dtor -mrelax}
-
-@emph{Nios II Options}
-@gccoptlist{-G @var{num} -mgpopt=@var{option} -mgpopt -mno-gpopt @gol
--mgprel-sec=@var{regexp} -mr0rel-sec=@var{regexp} @gol
--mel -meb @gol
--mno-bypass-cache -mbypass-cache @gol
--mno-cache-volatile -mcache-volatile @gol
--mno-fast-sw-div -mfast-sw-div @gol
--mhw-mul -mno-hw-mul -mhw-mulx -mno-hw-mulx -mno-hw-div -mhw-div @gol
--mcustom-@var{insn}=@var{N} -mno-custom-@var{insn} @gol
--mcustom-fpu-cfg=@var{name} @gol
--mhal -msmallc -msys-crt0=@var{name} -msys-lib=@var{name} @gol
--march=@var{arch} -mbmx -mno-bmx -mcdx -mno-cdx}
-
-@emph{Nvidia PTX Options}
-@gccoptlist{-m64 -mmainkernel -moptimize}
-
-@emph{OpenRISC Options}
-@gccoptlist{-mboard=@var{name} -mnewlib -mhard-mul -mhard-div @gol
--msoft-mul -msoft-div @gol
--msoft-float -mhard-float -mdouble-float -munordered-float @gol
--mcmov -mror -mrori -msext -msfimm -mshftimm @gol
--mcmodel=@var{code-model}}
-
-@emph{PDP-11 Options}
-@gccoptlist{-mfpu -msoft-float -mac0 -mno-ac0 -m40 -m45 -m10 @gol
--mint32 -mno-int16 -mint16 -mno-int32 @gol
--msplit -munix-asm -mdec-asm -mgnu-asm -mlra}
-
-@emph{picoChip Options}
-@gccoptlist{-mae=@var{ae_type} -mvliw-lookahead=@var{N} @gol
--msymbol-as-address -mno-inefficient-warnings}
-
-@emph{PowerPC Options}
-See RS/6000 and PowerPC Options.
-
-@emph{PRU Options}
-@gccoptlist{-mmcu=@var{mcu} -minrt -mno-relax -mloop @gol
--mabi=@var{variant} @gol}
-
-@emph{RISC-V Options}
-@gccoptlist{-mbranch-cost=@var{N-instruction} @gol
--mplt -mno-plt @gol
--mabi=@var{ABI-string} @gol
--mfdiv -mno-fdiv @gol
--mdiv -mno-div @gol
--misa-spec=@var{ISA-spec-string} @gol
--march=@var{ISA-string} @gol
--mtune=@var{processor-string} @gol
--mpreferred-stack-boundary=@var{num} @gol
--msmall-data-limit=@var{N-bytes} @gol
--msave-restore -mno-save-restore @gol
--mshorten-memrefs -mno-shorten-memrefs @gol
--mstrict-align -mno-strict-align @gol
--mcmodel=medlow -mcmodel=medany @gol
--mexplicit-relocs -mno-explicit-relocs @gol
--mrelax -mno-relax @gol
--mriscv-attribute -mno-riscv-attribute @gol
--malign-data=@var{type} @gol
--mbig-endian -mlittle-endian @gol
--mstack-protector-guard=@var{guard} -mstack-protector-guard-reg=@var{reg} @gol
--mstack-protector-guard-offset=@var{offset}}
--mcsr-check -mno-csr-check @gol
-
-@emph{RL78 Options}
-@gccoptlist{-msim -mmul=none -mmul=g13 -mmul=g14 -mallregs @gol
--mcpu=g10 -mcpu=g13 -mcpu=g14 -mg10 -mg13 -mg14 @gol
--m64bit-doubles -m32bit-doubles -msave-mduc-in-interrupts}
-
-@emph{RS/6000 and PowerPC Options}
-@gccoptlist{-mcpu=@var{cpu-type} @gol
--mtune=@var{cpu-type} @gol
--mcmodel=@var{code-model} @gol
--mpowerpc64 @gol
--maltivec -mno-altivec @gol
--mpowerpc-gpopt -mno-powerpc-gpopt @gol
--mpowerpc-gfxopt -mno-powerpc-gfxopt @gol
--mmfcrf -mno-mfcrf -mpopcntb -mno-popcntb -mpopcntd -mno-popcntd @gol
--mfprnd -mno-fprnd @gol
--mcmpb -mno-cmpb -mhard-dfp -mno-hard-dfp @gol
--mfull-toc -mminimal-toc -mno-fp-in-toc -mno-sum-in-toc @gol
--m64 -m32 -mxl-compat -mno-xl-compat -mpe @gol
--malign-power -malign-natural @gol
--msoft-float -mhard-float -mmultiple -mno-multiple @gol
--mupdate -mno-update @gol
--mavoid-indexed-addresses -mno-avoid-indexed-addresses @gol
--mfused-madd -mno-fused-madd -mbit-align -mno-bit-align @gol
--mstrict-align -mno-strict-align -mrelocatable @gol
--mno-relocatable -mrelocatable-lib -mno-relocatable-lib @gol
--mtoc -mno-toc -mlittle -mlittle-endian -mbig -mbig-endian @gol
--mdynamic-no-pic -mswdiv -msingle-pic-base @gol
--mprioritize-restricted-insns=@var{priority} @gol
--msched-costly-dep=@var{dependence_type} @gol
--minsert-sched-nops=@var{scheme} @gol
--mcall-aixdesc -mcall-eabi -mcall-freebsd @gol
--mcall-linux -mcall-netbsd -mcall-openbsd @gol
--mcall-sysv -mcall-sysv-eabi -mcall-sysv-noeabi @gol
--mtraceback=@var{traceback_type} @gol
--maix-struct-return -msvr4-struct-return @gol
--mabi=@var{abi-type} -msecure-plt -mbss-plt @gol
--mlongcall -mno-longcall -mpltseq -mno-pltseq @gol
--mblock-move-inline-limit=@var{num} @gol
--mblock-compare-inline-limit=@var{num} @gol
--mblock-compare-inline-loop-limit=@var{num} @gol
--mno-block-ops-unaligned-vsx @gol
--mstring-compare-inline-limit=@var{num} @gol
--misel -mno-isel @gol
--mvrsave -mno-vrsave @gol
--mmulhw -mno-mulhw @gol
--mdlmzb -mno-dlmzb @gol
--mprototype -mno-prototype @gol
--msim -mmvme -mads -myellowknife -memb -msdata @gol
--msdata=@var{opt} -mreadonly-in-sdata -mvxworks -G @var{num} @gol
--mrecip -mrecip=@var{opt} -mno-recip -mrecip-precision @gol
--mno-recip-precision @gol
--mveclibabi=@var{type} -mfriz -mno-friz @gol
--mpointers-to-nested-functions -mno-pointers-to-nested-functions @gol
--msave-toc-indirect -mno-save-toc-indirect @gol
--mpower8-fusion -mno-mpower8-fusion -mpower8-vector -mno-power8-vector @gol
--mcrypto -mno-crypto -mhtm -mno-htm @gol
--mquad-memory -mno-quad-memory @gol
--mquad-memory-atomic -mno-quad-memory-atomic @gol
--mcompat-align-parm -mno-compat-align-parm @gol
--mfloat128 -mno-float128 -mfloat128-hardware -mno-float128-hardware @gol
--mgnu-attribute -mno-gnu-attribute @gol
--mstack-protector-guard=@var{guard} -mstack-protector-guard-reg=@var{reg} @gol
--mstack-protector-guard-offset=@var{offset} -mprefixed -mno-prefixed @gol
--mpcrel -mno-pcrel -mmma -mno-mmma -mrop-protect -mno-rop-protect @gol
--mprivileged -mno-privileged}
-
-@emph{RX Options}
-@gccoptlist{-m64bit-doubles -m32bit-doubles -fpu -nofpu@gol
--mcpu=@gol
--mbig-endian-data -mlittle-endian-data @gol
--msmall-data @gol
--msim -mno-sim@gol
--mas100-syntax -mno-as100-syntax@gol
--mrelax@gol
--mmax-constant-size=@gol
--mint-register=@gol
--mpid@gol
--mallow-string-insns -mno-allow-string-insns@gol
--mjsr@gol
--mno-warn-multiple-fast-interrupts@gol
--msave-acc-in-interrupts}
-
-@emph{S/390 and zSeries Options}
-@gccoptlist{-mtune=@var{cpu-type} -march=@var{cpu-type} @gol
--mhard-float -msoft-float -mhard-dfp -mno-hard-dfp @gol
--mlong-double-64 -mlong-double-128 @gol
--mbackchain -mno-backchain -mpacked-stack -mno-packed-stack @gol
--msmall-exec -mno-small-exec -mmvcle -mno-mvcle @gol
--m64 -m31 -mdebug -mno-debug -mesa -mzarch @gol
--mhtm -mvx -mzvector @gol
--mtpf-trace -mno-tpf-trace -mtpf-trace-skip -mno-tpf-trace-skip @gol
--mfused-madd -mno-fused-madd @gol
--mwarn-framesize -mwarn-dynamicstack -mstack-size -mstack-guard @gol
--mhotpatch=@var{halfwords},@var{halfwords}}
-
-@emph{Score Options}
-@gccoptlist{-meb -mel @gol
--mnhwloop @gol
--muls @gol
--mmac @gol
--mscore5 -mscore5u -mscore7 -mscore7d}
-
-@emph{SH Options}
-@gccoptlist{-m1 -m2 -m2e @gol
--m2a-nofpu -m2a-single-only -m2a-single -m2a @gol
--m3 -m3e @gol
--m4-nofpu -m4-single-only -m4-single -m4 @gol
--m4a-nofpu -m4a-single-only -m4a-single -m4a -m4al @gol
--mb -ml -mdalign -mrelax @gol
--mbigtable -mfmovd -mrenesas -mno-renesas -mnomacsave @gol
--mieee -mno-ieee -mbitops -misize -minline-ic_invalidate -mpadstruct @gol
--mprefergot -musermode -multcost=@var{number} -mdiv=@var{strategy} @gol
--mdivsi3_libfunc=@var{name} -mfixed-range=@var{register-range} @gol
--maccumulate-outgoing-args @gol
--matomic-model=@var{atomic-model} @gol
--mbranch-cost=@var{num} -mzdcbranch -mno-zdcbranch @gol
--mcbranch-force-delay-slot @gol
--mfused-madd -mno-fused-madd -mfsca -mno-fsca -mfsrra -mno-fsrra @gol
--mpretend-cmove -mtas}
-
-@emph{Solaris 2 Options}
-@gccoptlist{-mclear-hwcap -mno-clear-hwcap -mimpure-text -mno-impure-text @gol
--pthreads}
-
-@emph{SPARC Options}
-@gccoptlist{-mcpu=@var{cpu-type} @gol
--mtune=@var{cpu-type} @gol
--mcmodel=@var{code-model} @gol
--mmemory-model=@var{mem-model} @gol
--m32 -m64 -mapp-regs -mno-app-regs @gol
--mfaster-structs -mno-faster-structs -mflat -mno-flat @gol
--mfpu -mno-fpu -mhard-float -msoft-float @gol
--mhard-quad-float -msoft-quad-float @gol
--mstack-bias -mno-stack-bias @gol
--mstd-struct-return -mno-std-struct-return @gol
--munaligned-doubles -mno-unaligned-doubles @gol
--muser-mode -mno-user-mode @gol
--mv8plus -mno-v8plus -mvis -mno-vis @gol
--mvis2 -mno-vis2 -mvis3 -mno-vis3 @gol
--mvis4 -mno-vis4 -mvis4b -mno-vis4b @gol
--mcbcond -mno-cbcond -mfmaf -mno-fmaf -mfsmuld -mno-fsmuld @gol
--mpopc -mno-popc -msubxc -mno-subxc @gol
--mfix-at697f -mfix-ut699 -mfix-ut700 -mfix-gr712rc @gol
--mlra -mno-lra}
-
-@emph{System V Options}
-@gccoptlist{-Qy -Qn -YP,@var{paths} -Ym,@var{dir}}
-
-@emph{V850 Options}
-@gccoptlist{-mlong-calls -mno-long-calls -mep -mno-ep @gol
--mprolog-function -mno-prolog-function -mspace @gol
--mtda=@var{n} -msda=@var{n} -mzda=@var{n} @gol
--mapp-regs -mno-app-regs @gol
--mdisable-callt -mno-disable-callt @gol
--mv850e2v3 -mv850e2 -mv850e1 -mv850es @gol
--mv850e -mv850 -mv850e3v5 @gol
--mloop @gol
--mrelax @gol
--mlong-jumps @gol
--msoft-float @gol
--mhard-float @gol
--mgcc-abi @gol
--mrh850-abi @gol
--mbig-switch}
-
-@emph{VAX Options}
-@gccoptlist{-mg -mgnu -munix -mlra}
-
-@emph{Visium Options}
-@gccoptlist{-mdebug -msim -mfpu -mno-fpu -mhard-float -msoft-float @gol
--mcpu=@var{cpu-type} -mtune=@var{cpu-type} -msv-mode -muser-mode}
-
-@emph{VMS Options}
-@gccoptlist{-mvms-return-codes -mdebug-main=@var{prefix} -mmalloc64 @gol
--mpointer-size=@var{size}}
-
-@emph{VxWorks Options}
-@gccoptlist{-mrtp -non-static -Bstatic -Bdynamic @gol
--Xbind-lazy -Xbind-now}
-
-@emph{x86 Options}
-@gccoptlist{-mtune=@var{cpu-type} -march=@var{cpu-type} @gol
--mtune-ctrl=@var{feature-list} -mdump-tune-features -mno-default @gol
--mfpmath=@var{unit} @gol
--masm=@var{dialect} -mno-fancy-math-387 @gol
--mno-fp-ret-in-387 -m80387 -mhard-float -msoft-float @gol
--mno-wide-multiply -mrtd -malign-double @gol
--mpreferred-stack-boundary=@var{num} @gol
--mincoming-stack-boundary=@var{num} @gol
--mcld -mcx16 -msahf -mmovbe -mcrc32 -mmwait @gol
--mrecip -mrecip=@var{opt} @gol
--mvzeroupper -mprefer-avx128 -mprefer-vector-width=@var{opt} @gol
--mmove-max=@var{bits} -mstore-max=@var{bits} @gol
--mmmx -msse -msse2 -msse3 -mssse3 -msse4.1 -msse4.2 -msse4 -mavx @gol
--mavx2 -mavx512f -mavx512pf -mavx512er -mavx512cd -mavx512vl @gol
--mavx512bw -mavx512dq -mavx512ifma -mavx512vbmi -msha -maes @gol
--mpclmul -mfsgsbase -mrdrnd -mf16c -mfma -mpconfig -mwbnoinvd @gol
--mptwrite -mprefetchwt1 -mclflushopt -mclwb -mxsavec -mxsaves @gol
--msse4a -m3dnow -m3dnowa -mpopcnt -mabm -mbmi -mtbm -mfma4 -mxop @gol
--madx -mlzcnt -mbmi2 -mfxsr -mxsave -mxsaveopt -mrtm -mhle -mlwp @gol
--mmwaitx -mclzero -mpku -mthreads -mgfni -mvaes -mwaitpkg @gol
--mshstk -mmanual-endbr -mcet-switch -mforce-indirect-call @gol
--mavx512vbmi2 -mavx512bf16 -menqcmd @gol
--mvpclmulqdq -mavx512bitalg -mmovdiri -mmovdir64b -mavx512vpopcntdq @gol
--mavx5124fmaps -mavx512vnni -mavx5124vnniw -mprfchw -mrdpid @gol
--mrdseed -msgx -mavx512vp2intersect -mserialize -mtsxldtrk@gol
--mamx-tile -mamx-int8 -mamx-bf16 -muintr -mhreset -mavxvnni@gol
--mavx512fp16 -mavxifma -mavxvnniint8 -mavxneconvert -mcmpccxadd -mamx-fp16 @gol
--mprefetchi -mraoint @gol
--mcldemote -mms-bitfields -mno-align-stringops -minline-all-stringops @gol
--minline-stringops-dynamically -mstringop-strategy=@var{alg} @gol
--mkl -mwidekl @gol
--mmemcpy-strategy=@var{strategy} -mmemset-strategy=@var{strategy} @gol
--mpush-args -maccumulate-outgoing-args -m128bit-long-double @gol
--m96bit-long-double -mlong-double-64 -mlong-double-80 -mlong-double-128 @gol
--mregparm=@var{num} -msseregparm @gol
--mveclibabi=@var{type} -mvect8-ret-in-mem @gol
--mpc32 -mpc64 -mpc80 -mstackrealign @gol
--momit-leaf-frame-pointer -mno-red-zone -mno-tls-direct-seg-refs @gol
--mcmodel=@var{code-model} -mabi=@var{name} -maddress-mode=@var{mode} @gol
--m32 -m64 -mx32 -m16 -miamcu -mlarge-data-threshold=@var{num} @gol
--msse2avx -mfentry -mrecord-mcount -mnop-mcount -m8bit-idiv @gol
--minstrument-return=@var{type} -mfentry-name=@var{name} -mfentry-section=@var{name} @gol
--mavx256-split-unaligned-load -mavx256-split-unaligned-store @gol
--malign-data=@var{type} -mstack-protector-guard=@var{guard} @gol
--mstack-protector-guard-reg=@var{reg} @gol
--mstack-protector-guard-offset=@var{offset} @gol
--mstack-protector-guard-symbol=@var{symbol} @gol
--mgeneral-regs-only -mcall-ms2sysv-xlogues -mrelax-cmpxchg-loop @gol
--mindirect-branch=@var{choice} -mfunction-return=@var{choice} @gol
--mindirect-branch-register -mharden-sls=@var{choice} @gol
--mindirect-branch-cs-prefix -mneeded -mno-direct-extern-access}
-
-@emph{x86 Windows Options}
-@gccoptlist{-mconsole -mcygwin -mno-cygwin -mdll @gol
--mnop-fun-dllimport -mthread @gol
--municode -mwin32 -mwindows -fno-set-stack-executable}
-
-@emph{Xstormy16 Options}
-@gccoptlist{-msim}
-
-@emph{Xtensa Options}
-@gccoptlist{-mconst16 -mno-const16 @gol
--mfused-madd -mno-fused-madd @gol
--mforce-no-pic @gol
--mserialize-volatile -mno-serialize-volatile @gol
--mtext-section-literals -mno-text-section-literals @gol
--mauto-litpools -mno-auto-litpools @gol
--mtarget-align -mno-target-align @gol
--mlongcalls -mno-longcalls @gol
--mabi=@var{abi-type} @gol
--mextra-l32r-costs=@var{cycles}}
-
-@emph{zSeries Options}
-See S/390 and zSeries Options.
-@end table
-
-
-@node Overall Options
-@section Options Controlling the Kind of Output
-
-Compilation can involve up to four stages: preprocessing, compilation
-proper, assembly and linking, always in that order. GCC is capable of
-preprocessing and compiling several files either into several
-assembler input files, or into one assembler input file; then each
-assembler input file produces an object file, and linking combines all
-the object files (those newly compiled, and those specified as input)
-into an executable file.
-
-@cindex file name suffix
-For any given input file, the file name suffix determines what kind of
-compilation is done:
-
-@table @gcctabopt
-@item @var{file}.c
-C source code that must be preprocessed.
-
-@item @var{file}.i
-C source code that should not be preprocessed.
-
-@item @var{file}.ii
-C++ source code that should not be preprocessed.
-
-@item @var{file}.m
-Objective-C source code. Note that you must link with the @file{libobjc}
-library to make an Objective-C program work.
-
-@item @var{file}.mi
-Objective-C source code that should not be preprocessed.
-
-@item @var{file}.mm
-@itemx @var{file}.M
-Objective-C++ source code. Note that you must link with the @file{libobjc}
-library to make an Objective-C++ program work. Note that @samp{.M} refers
-to a literal capital M@.
-
-@item @var{file}.mii
-Objective-C++ source code that should not be preprocessed.
-
-@item @var{file}.h
-C, C++, Objective-C or Objective-C++ header file to be turned into a
-precompiled header (default), or C, C++ header file to be turned into an
-Ada spec (via the @option{-fdump-ada-spec} switch).
-
-@item @var{file}.cc
-@itemx @var{file}.cp
-@itemx @var{file}.cxx
-@itemx @var{file}.cpp
-@itemx @var{file}.CPP
-@itemx @var{file}.c++
-@itemx @var{file}.C
-C++ source code that must be preprocessed. Note that in @samp{.cxx},
-the last two letters must both be literally @samp{x}. Likewise,
-@samp{.C} refers to a literal capital C@.
-
-@item @var{file}.mm
-@itemx @var{file}.M
-Objective-C++ source code that must be preprocessed.
-
-@item @var{file}.mii
-Objective-C++ source code that should not be preprocessed.
-
-@item @var{file}.hh
-@itemx @var{file}.H
-@itemx @var{file}.hp
-@itemx @var{file}.hxx
-@itemx @var{file}.hpp
-@itemx @var{file}.HPP
-@itemx @var{file}.h++
-@itemx @var{file}.tcc
-C++ header file to be turned into a precompiled header or Ada spec.
-
-@item @var{file}.f
-@itemx @var{file}.for
-@itemx @var{file}.ftn
-Fixed form Fortran source code that should not be preprocessed.
-
-@item @var{file}.F
-@itemx @var{file}.FOR
-@itemx @var{file}.fpp
-@itemx @var{file}.FPP
-@itemx @var{file}.FTN
-Fixed form Fortran source code that must be preprocessed (with the traditional
-preprocessor).
-
-@item @var{file}.f90
-@itemx @var{file}.f95
-@itemx @var{file}.f03
-@itemx @var{file}.f08
-Free form Fortran source code that should not be preprocessed.
-
-@item @var{file}.F90
-@itemx @var{file}.F95
-@itemx @var{file}.F03
-@itemx @var{file}.F08
-Free form Fortran source code that must be preprocessed (with the
-traditional preprocessor).
-
-@item @var{file}.go
-Go source code.
-
-@item @var{file}.d
-D source code.
-
-@item @var{file}.di
-D interface file.
-
-@item @var{file}.dd
-D documentation code (Ddoc).
-
-@item @var{file}.ads
-Ada source code file that contains a library unit declaration (a
-declaration of a package, subprogram, or generic, or a generic
-instantiation), or a library unit renaming declaration (a package,
-generic, or subprogram renaming declaration). Such files are also
-called @dfn{specs}.
-
-@item @var{file}.adb
-Ada source code file containing a library unit body (a subprogram or
-package body). Such files are also called @dfn{bodies}.
-
-@c GCC also knows about some suffixes for languages not yet included:
-@c Ratfor:
-@c @var{file}.r
-
-@item @var{file}.s
-Assembler code.
-
-@item @var{file}.S
-@itemx @var{file}.sx
-Assembler code that must be preprocessed.
-
-@item @var{other}
-An object file to be fed straight into linking.
-Any file name with no recognized suffix is treated this way.
-@end table
-
-@opindex x
-You can specify the input language explicitly with the @option{-x} option:
-
-@table @gcctabopt
-@item -x @var{language}
-Specify explicitly the @var{language} for the following input files
-(rather than letting the compiler choose a default based on the file
-name suffix). This option applies to all following input files until
-the next @option{-x} option. Possible values for @var{language} are:
-@smallexample
-c c-header cpp-output
-c++ c++-header c++-system-header c++-user-header c++-cpp-output
-objective-c objective-c-header objective-c-cpp-output
-objective-c++ objective-c++-header objective-c++-cpp-output
-assembler assembler-with-cpp
-ada
-d
-f77 f77-cpp-input f95 f95-cpp-input
-go
-@end smallexample
-
-@item -x none
-Turn off any specification of a language, so that subsequent files are
-handled according to their file name suffixes (as they are if @option{-x}
-has not been used at all).
-@end table
-
-If you only want some of the stages of compilation, you can use
-@option{-x} (or filename suffixes) to tell @command{gcc} where to start, and
-one of the options @option{-c}, @option{-S}, or @option{-E} to say where
-@command{gcc} is to stop. Note that some combinations (for example,
-@samp{-x cpp-output -E}) instruct @command{gcc} to do nothing at all.
-
-@table @gcctabopt
-@item -c
-@opindex c
-Compile or assemble the source files, but do not link. The linking
-stage simply is not done. The ultimate output is in the form of an
-object file for each source file.
-
-By default, the object file name for a source file is made by replacing
-the suffix @samp{.c}, @samp{.i}, @samp{.s}, etc., with @samp{.o}.
-
-Unrecognized input files, not requiring compilation or assembly, are
-ignored.
-
-@item -S
-@opindex S
-Stop after the stage of compilation proper; do not assemble. The output
-is in the form of an assembler code file for each non-assembler input
-file specified.
-
-By default, the assembler file name for a source file is made by
-replacing the suffix @samp{.c}, @samp{.i}, etc., with @samp{.s}.
-
-Input files that don't require compilation are ignored.
-
-@item -E
-@opindex E
-Stop after the preprocessing stage; do not run the compiler proper. The
-output is in the form of preprocessed source code, which is sent to the
-standard output.
-
-Input files that don't require preprocessing are ignored.
-
-@cindex output file option
-@item -o @var{file}
-@opindex o
-Place the primary output in file @var{file}. This applies to whatever
-sort of output is being produced, whether it be an executable file, an
-object file, an assembler file or preprocessed C code.
-
-If @option{-o} is not specified, the default is to put an executable
-file in @file{a.out}, the object file for
-@file{@var{source}.@var{suffix}} in @file{@var{source}.o}, its
-assembler file in @file{@var{source}.s}, a precompiled header file in
-@file{@var{source}.@var{suffix}.gch}, and all preprocessed C source on
-standard output.
-
-Though @option{-o} names only the primary output, it also affects the
-naming of auxiliary and dump outputs. See the examples below. Unless
-overridden, both auxiliary outputs and dump outputs are placed in the
-same directory as the primary output. In auxiliary outputs, the suffix
-of the input file is replaced with that of the auxiliary output file
-type; in dump outputs, the suffix of the dump file is appended to the
-input file suffix. In compilation commands, the base name of both
-auxiliary and dump outputs is that of the primary output; in compile and
-link commands, the primary output name, minus the executable suffix, is
-combined with the input file name. If both share the same base name,
-disregarding the suffix, the result of the combination is that base
-name, otherwise, they are concatenated, separated by a dash.
-
-@smallexample
-gcc -c foo.c ...
-@end smallexample
-
-will use @file{foo.o} as the primary output, and place aux outputs and
-dumps next to it, e.g., aux file @file{foo.dwo} for
-@option{-gsplit-dwarf}, and dump file @file{foo.c.???r.final} for
-@option{-fdump-rtl-final}.
-
-If a non-linker output file is explicitly specified, aux and dump files
-by default take the same base name:
-
-@smallexample
-gcc -c foo.c -o dir/foobar.o ...
-@end smallexample
-
-will name aux outputs @file{dir/foobar.*} and dump outputs
-@file{dir/foobar.c.*}.
-
-A linker output will instead prefix aux and dump outputs:
-
-@smallexample
-gcc foo.c bar.c -o dir/foobar ...
-@end smallexample
-
-will generally name aux outputs @file{dir/foobar-foo.*} and
-@file{dir/foobar-bar.*}, and dump outputs @file{dir/foobar-foo.c.*} and
-@file{dir/foobar-bar.c.*}.
-
-The one exception to the above is when the executable shares the base
-name with the single input:
-
-@smallexample
-gcc foo.c -o dir/foo ...
-@end smallexample
-
-in which case aux outputs are named @file{dir/foo.*} and dump outputs
-named @file{dir/foo.c.*}.
-
-The location and the names of auxiliary and dump outputs can be adjusted
-by the options @option{-dumpbase}, @option{-dumpbase-ext},
-@option{-dumpdir}, @option{-save-temps=cwd}, and
-@option{-save-temps=obj}.
-
-
-@item -dumpbase @var{dumpbase}
-@opindex dumpbase
-This option sets the base name for auxiliary and dump output files. It
-does not affect the name of the primary output file. Intermediate
-outputs, when preserved, are not regarded as primary outputs, but as
-auxiliary outputs:
-
-@smallexample
-gcc -save-temps -S foo.c
-@end smallexample
-
-saves the (no longer) temporary preprocessed file in @file{foo.i}, and
-then compiles to the (implied) output file @file{foo.s}, whereas:
-
-@smallexample
-gcc -save-temps -dumpbase save-foo -c foo.c
-@end smallexample
-
-preprocesses to in @file{save-foo.i}, compiles to @file{save-foo.s} (now
-an intermediate, thus auxiliary output), and then assembles to the
-(implied) output file @file{foo.o}.
-
-Absent this option, dump and aux files take their names from the input
-file, or from the (non-linker) output file, if one is explicitly
-specified: dump output files (e.g. those requested by @option{-fdump-*}
-options) with the input name suffix, and aux output files (those
-requested by other non-dump options, e.g. @code{-save-temps},
-@code{-gsplit-dwarf}, @code{-fcallgraph-info}) without it.
-
-Similar suffix differentiation of dump and aux outputs can be attained
-for explicitly-given @option{-dumpbase basename.suf} by also specifying
-@option{-dumpbase-ext .suf}.
-
-If @var{dumpbase} is explicitly specified with any directory component,
-any @var{dumppfx} specification (e.g. @option{-dumpdir} or
-@option{-save-temps=*}) is ignored, and instead of appending to it,
-@var{dumpbase} fully overrides it:
-
-@smallexample
-gcc foo.c -c -o dir/foo.o -dumpbase alt/foo \
- -dumpdir pfx- -save-temps=cwd ...
-@end smallexample
-
-creates auxiliary and dump outputs named @file{alt/foo.*}, disregarding
-@file{dir/} in @option{-o}, the @file{./} prefix implied by
-@option{-save-temps=cwd}, and @file{pfx-} in @option{-dumpdir}.
-
-When @option{-dumpbase} is specified in a command that compiles multiple
-inputs, or that compiles and then links, it may be combined with
-@var{dumppfx}, as specified under @option{-dumpdir}. Then, each input
-file is compiled using the combined @var{dumppfx}, and default values
-for @var{dumpbase} and @var{auxdropsuf} are computed for each input
-file:
-
-@smallexample
-gcc foo.c bar.c -c -dumpbase main ...
-@end smallexample
-
-creates @file{foo.o} and @file{bar.o} as primary outputs, and avoids
-overwriting the auxiliary and dump outputs by using the @var{dumpbase}
-as a prefix, creating auxiliary and dump outputs named @file{main-foo.*}
-and @file{main-bar.*}.
-
-An empty string specified as @var{dumpbase} avoids the influence of the
-output basename in the naming of auxiliary and dump outputs during
-compilation, computing default values :
-
-@smallexample
-gcc -c foo.c -o dir/foobar.o -dumpbase '' ...
-@end smallexample
-
-will name aux outputs @file{dir/foo.*} and dump outputs
-@file{dir/foo.c.*}. Note how their basenames are taken from the input
-name, but the directory still defaults to that of the output.
-
-The empty-string dumpbase does not prevent the use of the output
-basename for outputs during linking:
-
-@smallexample
-gcc foo.c bar.c -o dir/foobar -dumpbase '' -flto ...
-@end smallexample
-
-The compilation of the source files will name auxiliary outputs
-@file{dir/foo.*} and @file{dir/bar.*}, and dump outputs
-@file{dir/foo.c.*} and @file{dir/bar.c.*}. LTO recompilation during
-linking will use @file{dir/foobar.} as the prefix for dumps and
-auxiliary files.
-
-
-@item -dumpbase-ext @var{auxdropsuf}
-@opindex dumpbase-ext
-When forming the name of an auxiliary (but not a dump) output file, drop
-trailing @var{auxdropsuf} from @var{dumpbase} before appending any
-suffixes. If not specified, this option defaults to the suffix of a
-default @var{dumpbase}, i.e., the suffix of the input file when
-@option{-dumpbase} is not present in the command line, or @var{dumpbase}
-is combined with @var{dumppfx}.
-
-@smallexample
-gcc foo.c -c -o dir/foo.o -dumpbase x-foo.c -dumpbase-ext .c ...
-@end smallexample
-
-creates @file{dir/foo.o} as the main output, and generates auxiliary
-outputs in @file{dir/x-foo.*}, taking the location of the primary
-output, and dropping the @file{.c} suffix from the @var{dumpbase}. Dump
-outputs retain the suffix: @file{dir/x-foo.c.*}.
-
-This option is disregarded if it does not match the suffix of a
-specified @var{dumpbase}, except as an alternative to the executable
-suffix when appending the linker output base name to @var{dumppfx}, as
-specified below:
-
-@smallexample
-gcc foo.c bar.c -o main.out -dumpbase-ext .out ...
-@end smallexample
-
-creates @file{main.out} as the primary output, and avoids overwriting
-the auxiliary and dump outputs by using the executable name minus
-@var{auxdropsuf} as a prefix, creating auxiliary outputs named
-@file{main-foo.*} and @file{main-bar.*} and dump outputs named
-@file{main-foo.c.*} and @file{main-bar.c.*}.
-
-
-@item -dumpdir @var{dumppfx}
-@opindex dumpdir
-When forming the name of an auxiliary or dump output file, use
-@var{dumppfx} as a prefix:
-
-@smallexample
-gcc -dumpdir pfx- -c foo.c ...
-@end smallexample
-
-creates @file{foo.o} as the primary output, and auxiliary outputs named
-@file{pfx-foo.*}, combining the given @var{dumppfx} with the default
-@var{dumpbase} derived from the default primary output, derived in turn
-from the input name. Dump outputs also take the input name suffix:
-@file{pfx-foo.c.*}.
-
-If @var{dumppfx} is to be used as a directory name, it must end with a
-directory separator:
-
-@smallexample
-gcc -dumpdir dir/ -c foo.c -o obj/bar.o ...
-@end smallexample
-
-creates @file{obj/bar.o} as the primary output, and auxiliary outputs
-named @file{dir/bar.*}, combining the given @var{dumppfx} with the
-default @var{dumpbase} derived from the primary output name. Dump
-outputs also take the input name suffix: @file{dir/bar.c.*}.
-
-It defaults to the location of the output file, unless the output
-file is a special file like @code{/dev/null}. Options
-@option{-save-temps=cwd} and @option{-save-temps=obj} override this
-default, just like an explicit @option{-dumpdir} option. In case
-multiple such options are given, the last one prevails:
-
-@smallexample
-gcc -dumpdir pfx- -c foo.c -save-temps=obj ...
-@end smallexample
-
-outputs @file{foo.o}, with auxiliary outputs named @file{foo.*} because
-@option{-save-temps=*} overrides the @var{dumppfx} given by the earlier
-@option{-dumpdir} option. It does not matter that @option{=obj} is the
-default for @option{-save-temps}, nor that the output directory is
-implicitly the current directory. Dump outputs are named
-@file{foo.c.*}.
-
-When compiling from multiple input files, if @option{-dumpbase} is
-specified, @var{dumpbase}, minus a @var{auxdropsuf} suffix, and a dash
-are appended to (or override, if containing any directory components) an
-explicit or defaulted @var{dumppfx}, so that each of the multiple
-compilations gets differently-named aux and dump outputs.
-
-@smallexample
-gcc foo.c bar.c -c -dumpdir dir/pfx- -dumpbase main ...
-@end smallexample
-
-outputs auxiliary dumps to @file{dir/pfx-main-foo.*} and
-@file{dir/pfx-main-bar.*}, appending @var{dumpbase}- to @var{dumppfx}.
-Dump outputs retain the input file suffix: @file{dir/pfx-main-foo.c.*}
-and @file{dir/pfx-main-bar.c.*}, respectively. Contrast with the
-single-input compilation:
-
-@smallexample
-gcc foo.c -c -dumpdir dir/pfx- -dumpbase main ...
-@end smallexample
-
-that, applying @option{-dumpbase} to a single source, does not compute
-and append a separate @var{dumpbase} per input file. Its auxiliary and
-dump outputs go in @file{dir/pfx-main.*}.
-
-When compiling and then linking from multiple input files, a defaulted
-or explicitly specified @var{dumppfx} also undergoes the @var{dumpbase}-
-transformation above (e.g. the compilation of @file{foo.c} and
-@file{bar.c} above, but without @option{-c}). If neither
-@option{-dumpdir} nor @option{-dumpbase} are given, the linker output
-base name, minus @var{auxdropsuf}, if specified, or the executable
-suffix otherwise, plus a dash is appended to the default @var{dumppfx}
-instead. Note, however, that unlike earlier cases of linking:
-
-@smallexample
-gcc foo.c bar.c -dumpdir dir/pfx- -o main ...
-@end smallexample
-
-does not append the output name @file{main} to @var{dumppfx}, because
-@option{-dumpdir} is explicitly specified. The goal is that the
-explicitly-specified @var{dumppfx} may contain the specified output name
-as part of the prefix, if desired; only an explicitly-specified
-@option{-dumpbase} would be combined with it, in order to avoid simply
-discarding a meaningful option.
-
-When compiling and then linking from a single input file, the linker
-output base name will only be appended to the default @var{dumppfx} as
-above if it does not share the base name with the single input file
-name. This has been covered in single-input linking cases above, but
-not with an explicit @option{-dumpdir} that inhibits the combination,
-even if overridden by @option{-save-temps=*}:
-
-@smallexample
-gcc foo.c -dumpdir alt/pfx- -o dir/main.exe -save-temps=cwd ...
-@end smallexample
-
-Auxiliary outputs are named @file{foo.*}, and dump outputs
-@file{foo.c.*}, in the current working directory as ultimately requested
-by @option{-save-temps=cwd}.
-
-Summing it all up for an intuitive though slightly imprecise data flow:
-the primary output name is broken into a directory part and a basename
-part; @var{dumppfx} is set to the former, unless overridden by
-@option{-dumpdir} or @option{-save-temps=*}, and @var{dumpbase} is set
-to the latter, unless overriden by @option{-dumpbase}. If there are
-multiple inputs or linking, this @var{dumpbase} may be combined with
-@var{dumppfx} and taken from each input file. Auxiliary output names
-for each input are formed by combining @var{dumppfx}, @var{dumpbase}
-minus suffix, and the auxiliary output suffix; dump output names are
-only different in that the suffix from @var{dumpbase} is retained.
-
-When it comes to auxiliary and dump outputs created during LTO
-recompilation, a combination of @var{dumppfx} and @var{dumpbase}, as
-given or as derived from the linker output name but not from inputs,
-even in cases in which this combination would not otherwise be used as
-such, is passed down with a trailing period replacing the compiler-added
-dash, if any, as a @option{-dumpdir} option to @command{lto-wrapper};
-being involved in linking, this program does not normally get any
-@option{-dumpbase} and @option{-dumpbase-ext}, and it ignores them.
-
-When running sub-compilers, @command{lto-wrapper} appends LTO stage
-names to the received @var{dumppfx}, ensures it contains a directory
-component so that it overrides any @option{-dumpdir}, and passes that as
-@option{-dumpbase} to sub-compilers.
-
-@item -v
-@opindex v
-Print (on standard error output) the commands executed to run the stages
-of compilation. Also print the version number of the compiler driver
-program and of the preprocessor and the compiler proper.
-
-@item -###
-@opindex ###
-Like @option{-v} except the commands are not executed and arguments
-are quoted unless they contain only alphanumeric characters or @code{./-_}.
-This is useful for shell scripts to capture the driver-generated command lines.
-
-@item --help
-@opindex help
-Print (on the standard output) a description of the command-line options
-understood by @command{gcc}. If the @option{-v} option is also specified
-then @option{--help} is also passed on to the various processes
-invoked by @command{gcc}, so that they can display the command-line options
-they accept. If the @option{-Wextra} option has also been specified
-(prior to the @option{--help} option), then command-line options that
-have no documentation associated with them are also displayed.
-
-@item --target-help
-@opindex target-help
-Print (on the standard output) a description of target-specific command-line
-options for each tool. For some targets extra target-specific
-information may also be printed.
-
-@item --help=@{@var{class}@r{|[}^@r{]}@var{qualifier}@}@r{[},@dots{}@r{]}
-Print (on the standard output) a description of the command-line
-options understood by the compiler that fit into all specified classes
-and qualifiers. These are the supported classes:
-
-@table @asis
-@item @samp{optimizers}
-Display all of the optimization options supported by the
-compiler.
-
-@item @samp{warnings}
-Display all of the options controlling warning messages
-produced by the compiler.
-
-@item @samp{target}
-Display target-specific options. Unlike the
-@option{--target-help} option however, target-specific options of the
-linker and assembler are not displayed. This is because those
-tools do not currently support the extended @option{--help=} syntax.
-
-@item @samp{params}
-Display the values recognized by the @option{--param}
-option.
-
-@item @var{language}
-Display the options supported for @var{language}, where
-@var{language} is the name of one of the languages supported in this
-version of GCC@. If an option is supported by all languages, one needs
-to select @samp{common} class.
-
-@item @samp{common}
-Display the options that are common to all languages.
-@end table
-
-These are the supported qualifiers:
-
-@table @asis
-@item @samp{undocumented}
-Display only those options that are undocumented.
-
-@item @samp{joined}
-Display options taking an argument that appears after an equal
-sign in the same continuous piece of text, such as:
-@samp{--help=target}.
-
-@item @samp{separate}
-Display options taking an argument that appears as a separate word
-following the original option, such as: @samp{-o output-file}.
-@end table
-
-Thus for example to display all the undocumented target-specific
-switches supported by the compiler, use:
-
-@smallexample
---help=target,undocumented
-@end smallexample
-
-The sense of a qualifier can be inverted by prefixing it with the
-@samp{^} character, so for example to display all binary warning
-options (i.e., ones that are either on or off and that do not take an
-argument) that have a description, use:
-
-@smallexample
---help=warnings,^joined,^undocumented
-@end smallexample
-
-The argument to @option{--help=} should not consist solely of inverted
-qualifiers.
-
-Combining several classes is possible, although this usually
-restricts the output so much that there is nothing to display. One
-case where it does work, however, is when one of the classes is
-@var{target}. For example, to display all the target-specific
-optimization options, use:
-
-@smallexample
---help=target,optimizers
-@end smallexample
-
-The @option{--help=} option can be repeated on the command line. Each
-successive use displays its requested class of options, skipping
-those that have already been displayed. If @option{--help} is also
-specified anywhere on the command line then this takes precedence
-over any @option{--help=} option.
-
-If the @option{-Q} option appears on the command line before the
-@option{--help=} option, then the descriptive text displayed by
-@option{--help=} is changed. Instead of describing the displayed
-options, an indication is given as to whether the option is enabled,
-disabled or set to a specific value (assuming that the compiler
-knows this at the point where the @option{--help=} option is used).
-
-Here is a truncated example from the ARM port of @command{gcc}:
-
-@smallexample
- % gcc -Q -mabi=2 --help=target -c
- The following options are target specific:
- -mabi= 2
- -mabort-on-noreturn [disabled]
- -mapcs [disabled]
-@end smallexample
-
-The output is sensitive to the effects of previous command-line
-options, so for example it is possible to find out which optimizations
-are enabled at @option{-O2} by using:
-
-@smallexample
--Q -O2 --help=optimizers
-@end smallexample
-
-Alternatively you can discover which binary optimizations are enabled
-by @option{-O3} by using:
-
-@smallexample
-gcc -c -Q -O3 --help=optimizers > /tmp/O3-opts
-gcc -c -Q -O2 --help=optimizers > /tmp/O2-opts
-diff /tmp/O2-opts /tmp/O3-opts | grep enabled
-@end smallexample
-
-@item --version
-@opindex version
-Display the version number and copyrights of the invoked GCC@.
-
-@item -pass-exit-codes
-@opindex pass-exit-codes
-Normally the @command{gcc} program exits with the code of 1 if any
-phase of the compiler returns a non-success return code. If you specify
-@option{-pass-exit-codes}, the @command{gcc} program instead returns with
-the numerically highest error produced by any phase returning an error
-indication. The C, C++, and Fortran front ends return 4 if an internal
-compiler error is encountered.
-
-@item -pipe
-@opindex pipe
-Use pipes rather than temporary files for communication between the
-various stages of compilation. This fails to work on some systems where
-the assembler is unable to read from a pipe; but the GNU assembler has
-no trouble.
-
-@item -specs=@var{file}
-@opindex specs
-Process @var{file} after the compiler reads in the standard @file{specs}
-file, in order to override the defaults which the @command{gcc} driver
-program uses when determining what switches to pass to @command{cc1},
-@command{cc1plus}, @command{as}, @command{ld}, etc. More than one
-@option{-specs=@var{file}} can be specified on the command line, and they
-are processed in order, from left to right. @xref{Spec Files}, for
-information about the format of the @var{file}.
-
-@item -wrapper
-@opindex wrapper
-Invoke all subcommands under a wrapper program. The name of the
-wrapper program and its parameters are passed as a comma separated
-list.
-
-@smallexample
-gcc -c t.c -wrapper gdb,--args
-@end smallexample
-
-@noindent
-This invokes all subprograms of @command{gcc} under
-@samp{gdb --args}, thus the invocation of @command{cc1} is
-@samp{gdb --args cc1 @dots{}}.
-
-@item -ffile-prefix-map=@var{old}=@var{new}
-@opindex ffile-prefix-map
-When compiling files residing in directory @file{@var{old}}, record
-any references to them in the result of the compilation as if the
-files resided in directory @file{@var{new}} instead. Specifying this
-option is equivalent to specifying all the individual
-@option{-f*-prefix-map} options. This can be used to make reproducible
-builds that are location independent. See also
-@option{-fmacro-prefix-map}, @option{-fdebug-prefix-map} and
-@option{-fprofile-prefix-map}.
-
-@item -fplugin=@var{name}.so
-@opindex fplugin
-Load the plugin code in file @var{name}.so, assumed to be a
-shared object to be dlopen'd by the compiler. The base name of
-the shared object file is used to identify the plugin for the
-purposes of argument parsing (See
-@option{-fplugin-arg-@var{name}-@var{key}=@var{value}} below).
-Each plugin should define the callback functions specified in the
-Plugins API.
-
-@item -fplugin-arg-@var{name}-@var{key}=@var{value}
-@opindex fplugin-arg
-Define an argument called @var{key} with a value of @var{value}
-for the plugin called @var{name}.
-
-@item -fdump-ada-spec@r{[}-slim@r{]}
-@opindex fdump-ada-spec
-For C and C++ source and include files, generate corresponding Ada specs.
-@xref{Generating Ada Bindings for C and C++ headers,,, gnat_ugn,
-GNAT User's Guide}, which provides detailed documentation on this feature.
-
-@item -fada-spec-parent=@var{unit}
-@opindex fada-spec-parent
-In conjunction with @option{-fdump-ada-spec@r{[}-slim@r{]}} above, generate
-Ada specs as child units of parent @var{unit}.
-
-@item -fdump-go-spec=@var{file}
-@opindex fdump-go-spec
-For input files in any language, generate corresponding Go
-declarations in @var{file}. This generates Go @code{const},
-@code{type}, @code{var}, and @code{func} declarations which may be a
-useful way to start writing a Go interface to code written in some
-other language.
-
-@include @value{srcdir}/../libiberty/at-file.texi
-@end table
-
-@node Invoking G++
-@section Compiling C++ Programs
-
-@cindex suffixes for C++ source
-@cindex C++ source file suffixes
-C++ source files conventionally use one of the suffixes @samp{.C},
-@samp{.cc}, @samp{.cpp}, @samp{.CPP}, @samp{.c++}, @samp{.cp}, or
-@samp{.cxx}; C++ header files often use @samp{.hh}, @samp{.hpp},
-@samp{.H}, or (for shared template code) @samp{.tcc}; and
-preprocessed C++ files use the suffix @samp{.ii}. GCC recognizes
-files with these names and compiles them as C++ programs even if you
-call the compiler the same way as for compiling C programs (usually
-with the name @command{gcc}).
-
-@findex g++
-@findex c++
-However, the use of @command{gcc} does not add the C++ library.
-@command{g++} is a program that calls GCC and automatically specifies linking
-against the C++ library. It treats @samp{.c},
-@samp{.h} and @samp{.i} files as C++ source files instead of C source
-files unless @option{-x} is used. This program is also useful when
-precompiling a C header file with a @samp{.h} extension for use in C++
-compilations. On many systems, @command{g++} is also installed with
-the name @command{c++}.
-
-@cindex invoking @command{g++}
-When you compile C++ programs, you may specify many of the same
-command-line options that you use for compiling programs in any
-language; or command-line options meaningful for C and related
-languages; or options that are meaningful only for C++ programs.
-@xref{C Dialect Options,,Options Controlling C Dialect}, for
-explanations of options for languages related to C@.
-@xref{C++ Dialect Options,,Options Controlling C++ Dialect}, for
-explanations of options that are meaningful only for C++ programs.
-
-@node C Dialect Options
-@section Options Controlling C Dialect
-@cindex dialect options
-@cindex language dialect options
-@cindex options, dialect
-
-The following options control the dialect of C (or languages derived
-from C, such as C++, Objective-C and Objective-C++) that the compiler
-accepts:
-
-@table @gcctabopt
-@cindex ANSI support
-@cindex ISO support
-@item -ansi
-@opindex ansi
-In C mode, this is equivalent to @option{-std=c90}. In C++ mode, it is
-equivalent to @option{-std=c++98}.
-
-This turns off certain features of GCC that are incompatible with ISO
-C90 (when compiling C code), or of standard C++ (when compiling C++ code),
-such as the @code{asm} and @code{typeof} keywords, and
-predefined macros such as @code{unix} and @code{vax} that identify the
-type of system you are using. It also enables the undesirable and
-rarely used ISO trigraph feature. For the C compiler,
-it disables recognition of C++ style @samp{//} comments as well as
-the @code{inline} keyword.
-
-The alternate keywords @code{__asm__}, @code{__extension__},
-@code{__inline__} and @code{__typeof__} continue to work despite
-@option{-ansi}. You would not want to use them in an ISO C program, of
-course, but it is useful to put them in header files that might be included
-in compilations done with @option{-ansi}. Alternate predefined macros
-such as @code{__unix__} and @code{__vax__} are also available, with or
-without @option{-ansi}.
-
-The @option{-ansi} option does not cause non-ISO programs to be
-rejected gratuitously. For that, @option{-Wpedantic} is required in
-addition to @option{-ansi}. @xref{Warning Options}.
-
-The macro @code{__STRICT_ANSI__} is predefined when the @option{-ansi}
-option is used. Some header files may notice this macro and refrain
-from declaring certain functions or defining certain macros that the
-ISO standard doesn't call for; this is to avoid interfering with any
-programs that might use these names for other things.
-
-Functions that are normally built in but do not have semantics
-defined by ISO C (such as @code{alloca} and @code{ffs}) are not built-in
-functions when @option{-ansi} is used. @xref{Other Builtins,,Other
-built-in functions provided by GCC}, for details of the functions
-affected.
-
-@item -std=
-@opindex std
-Determine the language standard. @xref{Standards,,Language Standards
-Supported by GCC}, for details of these standard versions. This option
-is currently only supported when compiling C or C++.
-
-The compiler can accept several base standards, such as @samp{c90} or
-@samp{c++98}, and GNU dialects of those standards, such as
-@samp{gnu90} or @samp{gnu++98}. When a base standard is specified, the
-compiler accepts all programs following that standard plus those
-using GNU extensions that do not contradict it. For example,
-@option{-std=c90} turns off certain features of GCC that are
-incompatible with ISO C90, such as the @code{asm} and @code{typeof}
-keywords, but not other GNU extensions that do not have a meaning in
-ISO C90, such as omitting the middle term of a @code{?:}
-expression. On the other hand, when a GNU dialect of a standard is
-specified, all features supported by the compiler are enabled, even when
-those features change the meaning of the base standard. As a result, some
-strict-conforming programs may be rejected. The particular standard
-is used by @option{-Wpedantic} to identify which features are GNU
-extensions given that version of the standard. For example
-@option{-std=gnu90 -Wpedantic} warns about C++ style @samp{//}
-comments, while @option{-std=gnu99 -Wpedantic} does not.
-
-A value for this option must be provided; possible values are
-
-@table @samp
-@item c90
-@itemx c89
-@itemx iso9899:1990
-Support all ISO C90 programs (certain GNU extensions that conflict
-with ISO C90 are disabled). Same as @option{-ansi} for C code.
-
-@item iso9899:199409
-ISO C90 as modified in amendment 1.
-
-@item c99
-@itemx c9x
-@itemx iso9899:1999
-@itemx iso9899:199x
-ISO C99. This standard is substantially completely supported, modulo
-bugs and floating-point issues
-(mainly but not entirely relating to optional C99 features from
-Annexes F and G). See
-@w{@uref{https://gcc.gnu.org/c99status.html}} for more information. The
-names @samp{c9x} and @samp{iso9899:199x} are deprecated.
-
-@item c11
-@itemx c1x
-@itemx iso9899:2011
-ISO C11, the 2011 revision of the ISO C standard. This standard is
-substantially completely supported, modulo bugs, floating-point issues
-(mainly but not entirely relating to optional C11 features from
-Annexes F and G) and the optional Annexes K (Bounds-checking
-interfaces) and L (Analyzability). The name @samp{c1x} is deprecated.
-
-@item c17
-@itemx c18
-@itemx iso9899:2017
-@itemx iso9899:2018
-ISO C17, the 2017 revision of the ISO C standard
-(published in 2018). This standard is
-same as C11 except for corrections of defects (all of which are also
-applied with @option{-std=c11}) and a new value of
-@code{__STDC_VERSION__}, and so is supported to the same extent as C11.
-
-@item c2x
-The next version of the ISO C standard, still under development. The
-support for this version is experimental and incomplete.
-
-@item gnu90
-@itemx gnu89
-GNU dialect of ISO C90 (including some C99 features).
-
-@item gnu99
-@itemx gnu9x
-GNU dialect of ISO C99. The name @samp{gnu9x} is deprecated.
-
-@item gnu11
-@itemx gnu1x
-GNU dialect of ISO C11.
-The name @samp{gnu1x} is deprecated.
-
-@item gnu17
-@itemx gnu18
-GNU dialect of ISO C17. This is the default for C code.
-
-@item gnu2x
-The next version of the ISO C standard, still under development, plus
-GNU extensions. The support for this version is experimental and
-incomplete.
-
-@item c++98
-@itemx c++03
-The 1998 ISO C++ standard plus the 2003 technical corrigendum and some
-additional defect reports. Same as @option{-ansi} for C++ code.
-
-@item gnu++98
-@itemx gnu++03
-GNU dialect of @option{-std=c++98}.
-
-@item c++11
-@itemx c++0x
-The 2011 ISO C++ standard plus amendments.
-The name @samp{c++0x} is deprecated.
-
-@item gnu++11
-@itemx gnu++0x
-GNU dialect of @option{-std=c++11}.
-The name @samp{gnu++0x} is deprecated.
-
-@item c++14
-@itemx c++1y
-The 2014 ISO C++ standard plus amendments.
-The name @samp{c++1y} is deprecated.
-
-@item gnu++14
-@itemx gnu++1y
-GNU dialect of @option{-std=c++14}.
-The name @samp{gnu++1y} is deprecated.
-
-@item c++17
-@itemx c++1z
-The 2017 ISO C++ standard plus amendments.
-The name @samp{c++1z} is deprecated.
-
-@item gnu++17
-@itemx gnu++1z
-GNU dialect of @option{-std=c++17}.
-This is the default for C++ code.
-The name @samp{gnu++1z} is deprecated.
-
-@item c++20
-@itemx c++2a
-The 2020 ISO C++ standard plus amendments.
-Support is experimental, and could change in incompatible ways in
-future releases.
-The name @samp{c++2a} is deprecated.
-
-@item gnu++20
-@itemx gnu++2a
-GNU dialect of @option{-std=c++20}.
-Support is experimental, and could change in incompatible ways in
-future releases.
-The name @samp{gnu++2a} is deprecated.
-
-@item c++2b
-@itemx c++23
-The next revision of the ISO C++ standard, planned for
-2023. Support is highly experimental, and will almost certainly
-change in incompatible ways in future releases.
-
-@item gnu++2b
-@itemx gnu++23
-GNU dialect of @option{-std=c++2b}. Support is highly experimental,
-and will almost certainly change in incompatible ways in future
-releases.
-@end table
-
-@item -aux-info @var{filename}
-@opindex aux-info
-Output to the given filename prototyped declarations for all functions
-declared and/or defined in a translation unit, including those in header
-files. This option is silently ignored in any language other than C@.
-
-Besides declarations, the file indicates, in comments, the origin of
-each declaration (source file and line), whether the declaration was
-implicit, prototyped or unprototyped (@samp{I}, @samp{N} for new or
-@samp{O} for old, respectively, in the first character after the line
-number and the colon), and whether it came from a declaration or a
-definition (@samp{C} or @samp{F}, respectively, in the following
-character). In the case of function definitions, a K&R-style list of
-arguments followed by their declarations is also provided, inside
-comments, after the declaration.
-
-@item -fno-asm
-@opindex fno-asm
-@opindex fasm
-Do not recognize @code{asm}, @code{inline} or @code{typeof} as a
-keyword, so that code can use these words as identifiers. You can use
-the keywords @code{__asm__}, @code{__inline__} and @code{__typeof__}
-instead. In C, @option{-ansi} implies @option{-fno-asm}.
-
-In C++, @code{inline} is a standard keyword and is not affected by
-this switch. You may want to use the @option{-fno-gnu-keywords} flag
-instead, which disables @code{typeof} but not @code{asm} and
-@code{inline}. In C99 mode (@option{-std=c99} or @option{-std=gnu99}),
-this switch only affects the @code{asm} and @code{typeof} keywords,
-since @code{inline} is a standard keyword in ISO C99. In C2X mode
-(@option{-std=c2x} or @option{-std=gnu2x}), this switch only affects
-the @code{asm} keyword, since @code{typeof} is a standard keyword in
-ISO C2X.
-
-@item -fno-builtin
-@itemx -fno-builtin-@var{function}
-@opindex fno-builtin
-@opindex fbuiltin
-@cindex built-in functions
-Don't recognize built-in functions that do not begin with
-@samp{__builtin_} as prefix. @xref{Other Builtins,,Other built-in
-functions provided by GCC}, for details of the functions affected,
-including those which are not built-in functions when @option{-ansi} or
-@option{-std} options for strict ISO C conformance are used because they
-do not have an ISO standard meaning.
-
-GCC normally generates special code to handle certain built-in functions
-more efficiently; for instance, calls to @code{alloca} may become single
-instructions which adjust the stack directly, and calls to @code{memcpy}
-may become inline copy loops. The resulting code is often both smaller
-and faster, but since the function calls no longer appear as such, you
-cannot set a breakpoint on those calls, nor can you change the behavior
-of the functions by linking with a different library. In addition,
-when a function is recognized as a built-in function, GCC may use
-information about that function to warn about problems with calls to
-that function, or to generate more efficient code, even if the
-resulting code still contains calls to that function. For example,
-warnings are given with @option{-Wformat} for bad calls to
-@code{printf} when @code{printf} is built in and @code{strlen} is
-known not to modify global memory.
-
-With the @option{-fno-builtin-@var{function}} option
-only the built-in function @var{function} is
-disabled. @var{function} must not begin with @samp{__builtin_}. If a
-function is named that is not built-in in this version of GCC, this
-option is ignored. There is no corresponding
-@option{-fbuiltin-@var{function}} option; if you wish to enable
-built-in functions selectively when using @option{-fno-builtin} or
-@option{-ffreestanding}, you may define macros such as:
-
-@smallexample
-#define abs(n) __builtin_abs ((n))
-#define strcpy(d, s) __builtin_strcpy ((d), (s))
-@end smallexample
-
-@item -fcond-mismatch
-@opindex fcond-mismatch
-Allow conditional expressions with mismatched types in the second and
-third arguments. The value of such an expression is void. This option
-is not supported for C++.
-
-@item -ffreestanding
-@opindex ffreestanding
-@cindex hosted environment
-
-Assert that compilation targets a freestanding environment. This
-implies @option{-fno-builtin}. A freestanding environment
-is one in which the standard library may not exist, and program startup may
-not necessarily be at @code{main}. The most obvious example is an OS kernel.
-This is equivalent to @option{-fno-hosted}.
-
-@xref{Standards,,Language Standards Supported by GCC}, for details of
-freestanding and hosted environments.
-
-@item -fgimple
-@opindex fgimple
-
-Enable parsing of function definitions marked with @code{__GIMPLE}.
-This is an experimental feature that allows unit testing of GIMPLE
-passes.
-
-@item -fgnu-tm
-@opindex fgnu-tm
-When the option @option{-fgnu-tm} is specified, the compiler
-generates code for the Linux variant of Intel's current Transactional
-Memory ABI specification document (Revision 1.1, May 6 2009). This is
-an experimental feature whose interface may change in future versions
-of GCC, as the official specification changes. Please note that not
-all architectures are supported for this feature.
-
-For more information on GCC's support for transactional memory,
-@xref{Enabling libitm,,The GNU Transactional Memory Library,libitm,GNU
-Transactional Memory Library}.
-
-Note that the transactional memory feature is not supported with
-non-call exceptions (@option{-fnon-call-exceptions}).
-
-@item -fgnu89-inline
-@opindex fgnu89-inline
-The option @option{-fgnu89-inline} tells GCC to use the traditional
-GNU semantics for @code{inline} functions when in C99 mode.
-@xref{Inline,,An Inline Function is As Fast As a Macro}.
-Using this option is roughly equivalent to adding the
-@code{gnu_inline} function attribute to all inline functions
-(@pxref{Function Attributes}).
-
-The option @option{-fno-gnu89-inline} explicitly tells GCC to use the
-C99 semantics for @code{inline} when in C99 or gnu99 mode (i.e., it
-specifies the default behavior).
-This option is not supported in @option{-std=c90} or
-@option{-std=gnu90} mode.
-
-The preprocessor macros @code{__GNUC_GNU_INLINE__} and
-@code{__GNUC_STDC_INLINE__} may be used to check which semantics are
-in effect for @code{inline} functions. @xref{Common Predefined
-Macros,,,cpp,The C Preprocessor}.
-
-@item -fhosted
-@opindex fhosted
-@cindex hosted environment
-
-Assert that compilation targets a hosted environment. This implies
-@option{-fbuiltin}. A hosted environment is one in which the
-entire standard library is available, and in which @code{main} has a return
-type of @code{int}. Examples are nearly everything except a kernel.
-This is equivalent to @option{-fno-freestanding}.
-
-@item -flax-vector-conversions
-@opindex flax-vector-conversions
-Allow implicit conversions between vectors with differing numbers of
-elements and/or incompatible element types. This option should not be
-used for new code.
-
-@item -fms-extensions
-@opindex fms-extensions
-Accept some non-standard constructs used in Microsoft header files.
-
-In C++ code, this allows member names in structures to be similar
-to previous types declarations.
-
-@smallexample
-typedef int UOW;
-struct ABC @{
- UOW UOW;
-@};
-@end smallexample
-
-Some cases of unnamed fields in structures and unions are only
-accepted with this option. @xref{Unnamed Fields,,Unnamed struct/union
-fields within structs/unions}, for details.
-
-Note that this option is off for all targets except for x86
-targets using ms-abi.
-
-@item -foffload=disable
-@itemx -foffload=default
-@itemx -foffload=@var{target-list}
-@opindex foffload
-@cindex Offloading targets
-@cindex OpenACC offloading targets
-@cindex OpenMP offloading targets
-Specify for which OpenMP and OpenACC offload targets code should be generated.
-The default behavior, equivalent to @option{-foffload=default}, is to generate
-code for all supported offload targets. The @option{-foffload=disable} form
-generates code only for the host fallback, while
-@option{-foffload=@var{target-list}} generates code only for the specified
-comma-separated list of offload targets.
-
-Offload targets are specified in GCC's internal target-triplet format. You can
-run the compiler with @option{-v} to show the list of configured offload targets
-under @code{OFFLOAD_TARGET_NAMES}.
-
-@item -foffload-options=@var{options}
-@itemx -foffload-options=@var{target-triplet-list}=@var{options}
-@opindex foffload-options
-@cindex Offloading options
-@cindex OpenACC offloading options
-@cindex OpenMP offloading options
-
-With @option{-foffload-options=@var{options}}, GCC passes the specified
-@var{options} to the compilers for all enabled offloading targets. You can
-specify options that apply only to a specific target or targets by using
-the @option{-foffload-options=@var{target-list}=@var{options}} form. The
-@var{target-list} is a comma-separated list in the same format as for the
-@option{-foffload=} option.
-
-Typical command lines are
-
-@smallexample
--foffload-options=-lgfortran -foffload-options=-lm
--foffload-options="-lgfortran -lm" -foffload-options=nvptx-none=-latomic
--foffload-options=amdgcn-amdhsa=-march=gfx906 -foffload-options=-lm
-@end smallexample
-
-@item -fopenacc
-@opindex fopenacc
-@cindex OpenACC accelerator programming
-Enable handling of OpenACC directives @code{#pragma acc} in C/C++ and
-@code{!$acc} in Fortran. When @option{-fopenacc} is specified, the
-compiler generates accelerated code according to the OpenACC Application
-Programming Interface v2.6 @w{@uref{https://www.openacc.org}}. This option
-implies @option{-pthread}, and thus is only supported on targets that
-have support for @option{-pthread}.
-
-@item -fopenacc-dim=@var{geom}
-@opindex fopenacc-dim
-@cindex OpenACC accelerator programming
-Specify default compute dimensions for parallel offload regions that do
-not explicitly specify. The @var{geom} value is a triple of
-':'-separated sizes, in order 'gang', 'worker' and, 'vector'. A size
-can be omitted, to use a target-specific default value.
-
-@item -fopenmp
-@opindex fopenmp
-@cindex OpenMP parallel
-Enable handling of OpenMP directives @code{#pragma omp} in C/C++,
-@code{[[omp::directive(...)]]} and @code{[[omp::sequence(...)]]} in C++ and
-@code{!$omp} in Fortran. When @option{-fopenmp} is specified, the
-compiler generates parallel code according to the OpenMP Application
-Program Interface v4.5 @w{@uref{https://www.openmp.org}}. This option
-implies @option{-pthread}, and thus is only supported on targets that
-have support for @option{-pthread}. @option{-fopenmp} implies
-@option{-fopenmp-simd}.
-
-@item -fopenmp-simd
-@opindex fopenmp-simd
-@cindex OpenMP SIMD
-@cindex SIMD
-Enable handling of OpenMP's @code{simd}, @code{declare simd},
-@code{declare reduction}, @code{assume}, @code{ordered}, @code{scan},
-@code{loop} directives and combined or composite directives with
-@code{simd} as constituent with @code{#pragma omp} in C/C++,
-@code{[[omp::directive(...)]]} and @code{[[omp::sequence(...)]]} in C++
-and @code{!$omp} in Fortran. Other OpenMP directives are ignored.
-
-@item -fpermitted-flt-eval-methods=@var{style}
-@opindex fpermitted-flt-eval-methods
-@opindex fpermitted-flt-eval-methods=c11
-@opindex fpermitted-flt-eval-methods=ts-18661-3
-ISO/IEC TS 18661-3 defines new permissible values for
-@code{FLT_EVAL_METHOD} that indicate that operations and constants with
-a semantic type that is an interchange or extended format should be
-evaluated to the precision and range of that type. These new values are
-a superset of those permitted under C99/C11, which does not specify the
-meaning of other positive values of @code{FLT_EVAL_METHOD}. As such, code
-conforming to C11 may not have been written expecting the possibility of
-the new values.
-
-@option{-fpermitted-flt-eval-methods} specifies whether the compiler
-should allow only the values of @code{FLT_EVAL_METHOD} specified in C99/C11,
-or the extended set of values specified in ISO/IEC TS 18661-3.
-
-@var{style} is either @code{c11} or @code{ts-18661-3} as appropriate.
-
-The default when in a standards compliant mode (@option{-std=c11} or similar)
-is @option{-fpermitted-flt-eval-methods=c11}. The default when in a GNU
-dialect (@option{-std=gnu11} or similar) is
-@option{-fpermitted-flt-eval-methods=ts-18661-3}.
-
-@item -fplan9-extensions
-@opindex fplan9-extensions
-Accept some non-standard constructs used in Plan 9 code.
-
-This enables @option{-fms-extensions}, permits passing pointers to
-structures with anonymous fields to functions that expect pointers to
-elements of the type of the field, and permits referring to anonymous
-fields declared using a typedef. @xref{Unnamed Fields,,Unnamed
-struct/union fields within structs/unions}, for details. This is only
-supported for C, not C++.
-
-@item -fsigned-bitfields
-@itemx -funsigned-bitfields
-@itemx -fno-signed-bitfields
-@itemx -fno-unsigned-bitfields
-@opindex fsigned-bitfields
-@opindex funsigned-bitfields
-@opindex fno-signed-bitfields
-@opindex fno-unsigned-bitfields
-These options control whether a bit-field is signed or unsigned, when the
-declaration does not use either @code{signed} or @code{unsigned}. By
-default, such a bit-field is signed, because this is consistent: the
-basic integer types such as @code{int} are signed types.
-
-@item -fsigned-char
-@opindex fsigned-char
-Let the type @code{char} be signed, like @code{signed char}.
-
-Note that this is equivalent to @option{-fno-unsigned-char}, which is
-the negative form of @option{-funsigned-char}. Likewise, the option
-@option{-fno-signed-char} is equivalent to @option{-funsigned-char}.
-
-@item -funsigned-char
-@opindex funsigned-char
-Let the type @code{char} be unsigned, like @code{unsigned char}.
-
-Each kind of machine has a default for what @code{char} should
-be. It is either like @code{unsigned char} by default or like
-@code{signed char} by default.
-
-Ideally, a portable program should always use @code{signed char} or
-@code{unsigned char} when it depends on the signedness of an object.
-But many programs have been written to use plain @code{char} and
-expect it to be signed, or expect it to be unsigned, depending on the
-machines they were written for. This option, and its inverse, let you
-make such a program work with the opposite default.
-
-The type @code{char} is always a distinct type from each of
-@code{signed char} or @code{unsigned char}, even though its behavior
-is always just like one of those two.
-
-@item -fstrict-flex-arrays
-@opindex fstrict-flex-arrays
-@opindex fno-strict-flex-arrays
-Control when to treat the trailing array of a structure as a flexible array
-member for the purpose of accessing the elements of such an array.
-The positive form is equivalent to @option{-fstrict-flex-arrays=3}, which is the
-strictest. A trailing array is treated as a flexible array member only when it
-is declared as a flexible array member per C99 standard onwards.
-The negative form is equivalent to @option{-fstrict-flex-arrays=0}, which is the
-least strict. All trailing arrays of structures are treated as flexible array
-members.
-
-@item -fstrict-flex-arrays=@var{level}
-@opindex fstrict-flex-arrays=@var{level}
-Control when to treat the trailing array of a structure as a flexible array
-member for the purpose of accessing the elements of such an array. The value
-of @var{level} controls the level of strictness.
-
-The possible values of @var{level} are the same as for the
-@code{strict_flex_array} attribute (@pxref{Variable Attributes}).
-
-You can control this behavior for a specific trailing array field of a
-structure by using the variable attribute @code{strict_flex_array} attribute
-(@pxref{Variable Attributes}).
-
-@item -fsso-struct=@var{endianness}
-@opindex fsso-struct
-Set the default scalar storage order of structures and unions to the
-specified endianness. The accepted values are @samp{big-endian},
-@samp{little-endian} and @samp{native} for the native endianness of
-the target (the default). This option is not supported for C++.
-
-@strong{Warning:} the @option{-fsso-struct} switch causes GCC to generate
-code that is not binary compatible with code generated without it if the
-specified endianness is not the native endianness of the target.
-@end table
-
-@node C++ Dialect Options
-@section Options Controlling C++ Dialect
-
-@cindex compiler options, C++
-@cindex C++ options, command-line
-@cindex options, C++
-This section describes the command-line options that are only meaningful
-for C++ programs. You can also use most of the GNU compiler options
-regardless of what language your program is in. For example, you
-might compile a file @file{firstClass.C} like this:
-
-@smallexample
-g++ -g -fstrict-enums -O -c firstClass.C
-@end smallexample
-
-@noindent
-In this example, only @option{-fstrict-enums} is an option meant
-only for C++ programs; you can use the other options with any
-language supported by GCC@.
-
-Some options for compiling C programs, such as @option{-std}, are also
-relevant for C++ programs.
-@xref{C Dialect Options,,Options Controlling C Dialect}.
-
-Here is a list of options that are @emph{only} for compiling C++ programs:
-
-@table @gcctabopt
-
-@item -fabi-version=@var{n}
-@opindex fabi-version
-Use version @var{n} of the C++ ABI@. The default is version 0.
-
-Version 0 refers to the version conforming most closely to
-the C++ ABI specification. Therefore, the ABI obtained using version 0
-will change in different versions of G++ as ABI bugs are fixed.
-
-Version 1 is the version of the C++ ABI that first appeared in G++ 3.2.
-
-Version 2 is the version of the C++ ABI that first appeared in G++
-3.4, and was the default through G++ 4.9.
-
-Version 3 corrects an error in mangling a constant address as a
-template argument.
-
-Version 4, which first appeared in G++ 4.5, implements a standard
-mangling for vector types.
-
-Version 5, which first appeared in G++ 4.6, corrects the mangling of
-attribute const/volatile on function pointer types, decltype of a
-plain decl, and use of a function parameter in the declaration of
-another parameter.
-
-Version 6, which first appeared in G++ 4.7, corrects the promotion
-behavior of C++11 scoped enums and the mangling of template argument
-packs, const/static_cast, prefix ++ and --, and a class scope function
-used as a template argument.
-
-Version 7, which first appeared in G++ 4.8, that treats nullptr_t as a
-builtin type and corrects the mangling of lambdas in default argument
-scope.
-
-Version 8, which first appeared in G++ 4.9, corrects the substitution
-behavior of function types with function-cv-qualifiers.
-
-Version 9, which first appeared in G++ 5.2, corrects the alignment of
-@code{nullptr_t}.
-
-Version 10, which first appeared in G++ 6.1, adds mangling of
-attributes that affect type identity, such as ia32 calling convention
-attributes (e.g.@: @samp{stdcall}).
-
-Version 11, which first appeared in G++ 7, corrects the mangling of
-sizeof... expressions and operator names. For multiple entities with
-the same name within a function, that are declared in different scopes,
-the mangling now changes starting with the twelfth occurrence. It also
-implies @option{-fnew-inheriting-ctors}.
-
-Version 12, which first appeared in G++ 8, corrects the calling
-conventions for empty classes on the x86_64 target and for classes
-with only deleted copy/move constructors. It accidentally changes the
-calling convention for classes with a deleted copy constructor and a
-trivial move constructor.
-
-Version 13, which first appeared in G++ 8.2, fixes the accidental
-change in version 12.
-
-Version 14, which first appeared in G++ 10, corrects the mangling of
-the nullptr expression.
-
-Version 15, which first appeared in G++ 10.3, corrects G++ 10 ABI
-tag regression.
-
-Version 16, which first appeared in G++ 11, changes the mangling of
-@code{__alignof__} to be distinct from that of @code{alignof}, and
-dependent operator names.
-
-Version 17, which first appeared in G++ 12, fixes layout of classes
-that inherit from aggregate classes with default member initializers
-in C++14 and up.
-
-Version 18, which first appeard in G++ 13, fixes manglings of lambdas
-that have additional context.
-
-See also @option{-Wabi}.
-
-@item -fabi-compat-version=@var{n}
-@opindex fabi-compat-version
-On targets that support strong aliases, G++
-works around mangling changes by creating an alias with the correct
-mangled name when defining a symbol with an incorrect mangled name.
-This switch specifies which ABI version to use for the alias.
-
-With @option{-fabi-version=0} (the default), this defaults to 13 (GCC 8.2
-compatibility). If another ABI version is explicitly selected, this
-defaults to 0. For compatibility with GCC versions 3.2 through 4.9,
-use @option{-fabi-compat-version=2}.
-
-If this option is not provided but @option{-Wabi=@var{n}} is, that
-version is used for compatibility aliases. If this option is provided
-along with @option{-Wabi} (without the version), the version from this
-option is used for the warning.
-
-@item -fno-access-control
-@opindex fno-access-control
-@opindex faccess-control
-Turn off all access checking. This switch is mainly useful for working
-around bugs in the access control code.
-
-@item -faligned-new
-@opindex faligned-new
-Enable support for C++17 @code{new} of types that require more
-alignment than @code{void* ::operator new(std::size_t)} provides. A
-numeric argument such as @code{-faligned-new=32} can be used to
-specify how much alignment (in bytes) is provided by that function,
-but few users will need to override the default of
-@code{alignof(std::max_align_t)}.
-
-This flag is enabled by default for @option{-std=c++17}.
-
-@item -fchar8_t
-@itemx -fno-char8_t
-@opindex fchar8_t
-@opindex fno-char8_t
-Enable support for @code{char8_t} as adopted for C++20. This includes
-the addition of a new @code{char8_t} fundamental type, changes to the
-types of UTF-8 string and character literals, new signatures for
-user-defined literals, associated standard library updates, and new
-@code{__cpp_char8_t} and @code{__cpp_lib_char8_t} feature test macros.
-
-This option enables functions to be overloaded for ordinary and UTF-8
-strings:
-
-@smallexample
-int f(const char *); // #1
-int f(const char8_t *); // #2
-int v1 = f("text"); // Calls #1
-int v2 = f(u8"text"); // Calls #2
-@end smallexample
-
-@noindent
-and introduces new signatures for user-defined literals:
-
-@smallexample
-int operator""_udl1(char8_t);
-int v3 = u8'x'_udl1;
-int operator""_udl2(const char8_t*, std::size_t);
-int v4 = u8"text"_udl2;
-template<typename T, T...> int operator""_udl3();
-int v5 = u8"text"_udl3;
-@end smallexample
-
-@noindent
-The change to the types of UTF-8 string and character literals introduces
-incompatibilities with ISO C++11 and later standards. For example, the
-following code is well-formed under ISO C++11, but is ill-formed when
-@option{-fchar8_t} is specified.
-
-@smallexample
-char ca[] = u8"xx"; // error: char-array initialized from wide
- // string
-const char *cp = u8"xx";// error: invalid conversion from
- // `const char8_t*' to `const char*'
-int f(const char*);
-auto v = f(u8"xx"); // error: invalid conversion from
- // `const char8_t*' to `const char*'
-std::string s@{u8"xx"@}; // error: no matching function for call to
- // `std::basic_string<char>::basic_string()'
-using namespace std::literals;
-s = u8"xx"s; // error: conversion from
- // `basic_string<char8_t>' to non-scalar
- // type `basic_string<char>' requested
-@end smallexample
-
-@item -fcheck-new
-@opindex fcheck-new
-Check that the pointer returned by @code{operator new} is non-null
-before attempting to modify the storage allocated. This check is
-normally unnecessary because the C++ standard specifies that
-@code{operator new} only returns @code{0} if it is declared
-@code{throw()}, in which case the compiler always checks the
-return value even without this option. In all other cases, when
-@code{operator new} has a non-empty exception specification, memory
-exhaustion is signalled by throwing @code{std::bad_alloc}. See also
-@samp{new (nothrow)}.
-
-@item -fconcepts
-@itemx -fconcepts-ts
-@opindex fconcepts
-@opindex fconcepts-ts
-Enable support for the C++ Concepts feature for constraining template
-arguments. With @option{-std=c++20} and above, Concepts are part of
-the language standard, so @option{-fconcepts} defaults to on.
-
-Some constructs that were allowed by the earlier C++ Extensions for
-Concepts Technical Specification, ISO 19217 (2015), but didn't make it
-into the standard, can additionally be enabled by
-@option{-fconcepts-ts}.
-
-@item -fconstexpr-depth=@var{n}
-@opindex fconstexpr-depth
-Set the maximum nested evaluation depth for C++11 constexpr functions
-to @var{n}. A limit is needed to detect endless recursion during
-constant expression evaluation. The minimum specified by the standard
-is 512.
-
-@item -fconstexpr-cache-depth=@var{n}
-@opindex fconstexpr-cache-depth
-Set the maximum level of nested evaluation depth for C++11 constexpr
-functions that will be cached to @var{n}. This is a heuristic that
-trades off compilation speed (when the cache avoids repeated
-calculations) against memory consumption (when the cache grows very
-large from highly recursive evaluations). The default is 8. Very few
-users are likely to want to adjust it, but if your code does heavy
-constexpr calculations you might want to experiment to find which
-value works best for you.
-
-@item -fconstexpr-fp-except
-@opindex fconstexpr-fp-except
-Annex F of the C standard specifies that IEC559 floating point
-exceptions encountered at compile time should not stop compilation.
-C++ compilers have historically not followed this guidance, instead
-treating floating point division by zero as non-constant even though
-it has a well defined value. This flag tells the compiler to give
-Annex F priority over other rules saying that a particular operation
-is undefined.
-
-@smallexample
-constexpr float inf = 1./0.; // OK with -fconstexpr-fp-except
-@end smallexample
-
-@item -fconstexpr-loop-limit=@var{n}
-@opindex fconstexpr-loop-limit
-Set the maximum number of iterations for a loop in C++14 constexpr functions
-to @var{n}. A limit is needed to detect infinite loops during
-constant expression evaluation. The default is 262144 (1<<18).
-
-@item -fconstexpr-ops-limit=@var{n}
-@opindex fconstexpr-ops-limit
-Set the maximum number of operations during a single constexpr evaluation.
-Even when number of iterations of a single loop is limited with the above limit,
-if there are several nested loops and each of them has many iterations but still
-smaller than the above limit, or if in a body of some loop or even outside
-of a loop too many expressions need to be evaluated, the resulting constexpr
-evaluation might take too long.
-The default is 33554432 (1<<25).
-
-@item -fcoroutines
-@opindex fcoroutines
-Enable support for the C++ coroutines extension (experimental).
-
-@item -fno-elide-constructors
-@opindex fno-elide-constructors
-@opindex felide-constructors
-The C++ standard allows an implementation to omit creating a temporary
-that is only used to initialize another object of the same type.
-Specifying this option disables that optimization, and forces G++ to
-call the copy constructor in all cases. This option also causes G++
-to call trivial member functions which otherwise would be expanded inline.
-
-In C++17, the compiler is required to omit these temporaries, but this
-option still affects trivial member functions.
-
-@item -fno-enforce-eh-specs
-@opindex fno-enforce-eh-specs
-@opindex fenforce-eh-specs
-Don't generate code to check for violation of exception specifications
-at run time. This option violates the C++ standard, but may be useful
-for reducing code size in production builds, much like defining
-@code{NDEBUG}. This does not give user code permission to throw
-exceptions in violation of the exception specifications; the compiler
-still optimizes based on the specifications, so throwing an
-unexpected exception results in undefined behavior at run time.
-
-@item -fextern-tls-init
-@itemx -fno-extern-tls-init
-@opindex fextern-tls-init
-@opindex fno-extern-tls-init
-The C++11 and OpenMP standards allow @code{thread_local} and
-@code{threadprivate} variables to have dynamic (runtime)
-initialization. To support this, any use of such a variable goes
-through a wrapper function that performs any necessary initialization.
-When the use and definition of the variable are in the same
-translation unit, this overhead can be optimized away, but when the
-use is in a different translation unit there is significant overhead
-even if the variable doesn't actually need dynamic initialization. If
-the programmer can be sure that no use of the variable in a
-non-defining TU needs to trigger dynamic initialization (either
-because the variable is statically initialized, or a use of the
-variable in the defining TU will be executed before any uses in
-another TU), they can avoid this overhead with the
-@option{-fno-extern-tls-init} option.
-
-On targets that support symbol aliases, the default is
-@option{-fextern-tls-init}. On targets that do not support symbol
-aliases, the default is @option{-fno-extern-tls-init}.
-
-@item -ffold-simple-inlines
-@itemx -fno-fold-simple-inlines
-@opindex ffold-simple-inlines
-@opindex fno-fold-simple-inlines
-Permit the C++ frontend to fold calls to @code{std::move}, @code{std::forward},
-@code{std::addressof} and @code{std::as_const}. In contrast to inlining, this
-means no debug information will be generated for such calls. Since these
-functions are rarely interesting to debug, this flag is enabled by default
-unless @option{-fno-inline} is active.
-
-@item -fno-gnu-keywords
-@opindex fno-gnu-keywords
-@opindex fgnu-keywords
-Do not recognize @code{typeof} as a keyword, so that code can use this
-word as an identifier. You can use the keyword @code{__typeof__} instead.
-This option is implied by the strict ISO C++ dialects: @option{-ansi},
-@option{-std=c++98}, @option{-std=c++11}, etc.
-
-@item -fimplicit-constexpr
-@opindex fimplicit-constexpr
-Make inline functions implicitly constexpr, if they satisfy the
-requirements for a constexpr function. This option can be used in
-C++14 mode or later. This can result in initialization changing from
-dynamic to static and other optimizations.
-
-@item -fno-implicit-templates
-@opindex fno-implicit-templates
-@opindex fimplicit-templates
-Never emit code for non-inline templates that are instantiated
-implicitly (i.e.@: by use); only emit code for explicit instantiations.
-If you use this option, you must take care to structure your code to
-include all the necessary explicit instantiations to avoid getting
-undefined symbols at link time.
-@xref{Template Instantiation}, for more information.
-
-@item -fno-implicit-inline-templates
-@opindex fno-implicit-inline-templates
-@opindex fimplicit-inline-templates
-Don't emit code for implicit instantiations of inline templates, either.
-The default is to handle inlines differently so that compiles with and
-without optimization need the same set of explicit instantiations.
-
-@item -fno-implement-inlines
-@opindex fno-implement-inlines
-@opindex fimplement-inlines
-To save space, do not emit out-of-line copies of inline functions
-controlled by @code{#pragma implementation}. This causes linker
-errors if these functions are not inlined everywhere they are called.
-
-@item -fmodules-ts
-@itemx -fno-modules-ts
-@opindex fmodules-ts
-@opindex fno-modules-ts
-Enable support for C++20 modules (@pxref{C++ Modules}). The
-@option{-fno-modules-ts} is usually not needed, as that is the
-default. Even though this is a C++20 feature, it is not currently
-implicitly enabled by selecting that standard version.
-
-@item -fmodule-header
-@itemx -fmodule-header=user
-@itemx -fmodule-header=system
-@opindex fmodule-header
-Compile a header file to create an importable header unit.
-
-@item -fmodule-implicit-inline
-@opindex fmodule-implicit-inline
-Member functions defined in their class definitions are not implicitly
-inline for modular code. This is different to traditional C++
-behavior, for good reasons. However, it may result in a difficulty
-during code porting. This option makes such function definitions
-implicitly inline. It does however generate an ABI incompatibility,
-so you must use it everywhere or nowhere. (Such definitions outside
-of a named module remain implicitly inline, regardless.)
-
-@item -fno-module-lazy
-@opindex fno-module-lazy
-@opindex fmodule-lazy
-Disable lazy module importing and module mapper creation.
-
-@item -fmodule-mapper=@r{[}@var{hostname}@r{]}:@var{port}@r{[}?@var{ident}@r{]}
-@itemx -fmodule-mapper=|@var{program}@r{[}?@var{ident}@r{]} @var{args...}
-@itemx -fmodule-mapper==@var{socket}@r{[}?@var{ident}@r{]}
-@itemx -fmodule-mapper=<>@r{[}@var{inout}@r{]}@r{[}?@var{ident}@r{]}
-@itemx -fmodule-mapper=<@var{in}>@var{out}@r{[}?@var{ident}@r{]}
-@itemx -fmodule-mapper=@var{file}@r{[}?@var{ident}@r{]}
-@vindex CXX_MODULE_MAPPER @r{environment variable}
-@opindex fmodule-mapper
-An oracle to query for module name to filename mappings. If
-unspecified the @env{CXX_MODULE_MAPPER} environment variable is used,
-and if that is unset, an in-process default is provided.
-
-@item -fmodule-only
-@opindex fmodule-only
-Only emit the Compiled Module Interface, inhibiting any object file.
-
-@item -fms-extensions
-@opindex fms-extensions
-Disable Wpedantic warnings about constructs used in MFC, such as implicit
-int and getting a pointer to member function via non-standard syntax.
-
-@item -fnew-inheriting-ctors
-@opindex fnew-inheriting-ctors
-Enable the P0136 adjustment to the semantics of C++11 constructor
-inheritance. This is part of C++17 but also considered to be a Defect
-Report against C++11 and C++14. This flag is enabled by default
-unless @option{-fabi-version=10} or lower is specified.
-
-@item -fnew-ttp-matching
-@opindex fnew-ttp-matching
-Enable the P0522 resolution to Core issue 150, template template
-parameters and default arguments: this allows a template with default
-template arguments as an argument for a template template parameter
-with fewer template parameters. This flag is enabled by default for
-@option{-std=c++17}.
-
-@item -fno-nonansi-builtins
-@opindex fno-nonansi-builtins
-@opindex fnonansi-builtins
-Disable built-in declarations of functions that are not mandated by
-ANSI/ISO C@. These include @code{ffs}, @code{alloca}, @code{_exit},
-@code{index}, @code{bzero}, @code{conjf}, and other related functions.
-
-@item -fnothrow-opt
-@opindex fnothrow-opt
-Treat a @code{throw()} exception specification as if it were a
-@code{noexcept} specification to reduce or eliminate the text size
-overhead relative to a function with no exception specification. If
-the function has local variables of types with non-trivial
-destructors, the exception specification actually makes the
-function smaller because the EH cleanups for those variables can be
-optimized away. The semantic effect is that an exception thrown out of
-a function with such an exception specification results in a call
-to @code{terminate} rather than @code{unexpected}.
-
-@item -fno-operator-names
-@opindex fno-operator-names
-@opindex foperator-names
-Do not treat the operator name keywords @code{and}, @code{bitand},
-@code{bitor}, @code{compl}, @code{not}, @code{or} and @code{xor} as
-synonyms as keywords.
-
-@item -fno-optional-diags
-@opindex fno-optional-diags
-@opindex foptional-diags
-Disable diagnostics that the standard says a compiler does not need to
-issue. Currently, the only such diagnostic issued by G++ is the one for
-a name having multiple meanings within a class.
-
-@item -fpermissive
-@opindex fpermissive
-Downgrade some diagnostics about nonconformant code from errors to
-warnings. Thus, using @option{-fpermissive} allows some
-nonconforming code to compile.
-
-@item -fno-pretty-templates
-@opindex fno-pretty-templates
-@opindex fpretty-templates
-When an error message refers to a specialization of a function
-template, the compiler normally prints the signature of the
-template followed by the template arguments and any typedefs or
-typenames in the signature (e.g.@: @code{void f(T) [with T = int]}
-rather than @code{void f(int)}) so that it's clear which template is
-involved. When an error message refers to a specialization of a class
-template, the compiler omits any template arguments that match
-the default template arguments for that template. If either of these
-behaviors make it harder to understand the error message rather than
-easier, you can use @option{-fno-pretty-templates} to disable them.
-
-@item -fno-rtti
-@opindex fno-rtti
-@opindex frtti
-Disable generation of information about every class with virtual
-functions for use by the C++ run-time type identification features
-(@code{dynamic_cast} and @code{typeid}). If you don't use those parts
-of the language, you can save some space by using this flag. Note that
-exception handling uses the same information, but G++ generates it as
-needed. The @code{dynamic_cast} operator can still be used for casts that
-do not require run-time type information, i.e.@: casts to @code{void *} or to
-unambiguous base classes.
-
-Mixing code compiled with @option{-frtti} with that compiled with
-@option{-fno-rtti} may not work. For example, programs may
-fail to link if a class compiled with @option{-fno-rtti} is used as a base
-for a class compiled with @option{-frtti}.
-
-@item -fsized-deallocation
-@opindex fsized-deallocation
-Enable the built-in global declarations
-@smallexample
-void operator delete (void *, std::size_t) noexcept;
-void operator delete[] (void *, std::size_t) noexcept;
-@end smallexample
-as introduced in C++14. This is useful for user-defined replacement
-deallocation functions that, for example, use the size of the object
-to make deallocation faster. Enabled by default under
-@option{-std=c++14} and above. The flag @option{-Wsized-deallocation}
-warns about places that might want to add a definition.
-
-@item -fstrict-enums
-@opindex fstrict-enums
-Allow the compiler to optimize using the assumption that a value of
-enumerated type can only be one of the values of the enumeration (as
-defined in the C++ standard; basically, a value that can be
-represented in the minimum number of bits needed to represent all the
-enumerators). This assumption may not be valid if the program uses a
-cast to convert an arbitrary integer value to the enumerated type.
-
-@item -fstrong-eval-order
-@opindex fstrong-eval-order
-Evaluate member access, array subscripting, and shift expressions in
-left-to-right order, and evaluate assignment in right-to-left order,
-as adopted for C++17. Enabled by default with @option{-std=c++17}.
-@option{-fstrong-eval-order=some} enables just the ordering of member
-access and shift expressions, and is the default without
-@option{-std=c++17}.
-
-@item -ftemplate-backtrace-limit=@var{n}
-@opindex ftemplate-backtrace-limit
-Set the maximum number of template instantiation notes for a single
-warning or error to @var{n}. The default value is 10.
-
-@item -ftemplate-depth=@var{n}
-@opindex ftemplate-depth
-Set the maximum instantiation depth for template classes to @var{n}.
-A limit on the template instantiation depth is needed to detect
-endless recursions during template class instantiation. ANSI/ISO C++
-conforming programs must not rely on a maximum depth greater than 17
-(changed to 1024 in C++11). The default value is 900, as the compiler
-can run out of stack space before hitting 1024 in some situations.
-
-@item -fno-threadsafe-statics
-@opindex fno-threadsafe-statics
-@opindex fthreadsafe-statics
-Do not emit the extra code to use the routines specified in the C++
-ABI for thread-safe initialization of local statics. You can use this
-option to reduce code size slightly in code that doesn't need to be
-thread-safe.
-
-@item -fuse-cxa-atexit
-@opindex fuse-cxa-atexit
-Register destructors for objects with static storage duration with the
-@code{__cxa_atexit} function rather than the @code{atexit} function.
-This option is required for fully standards-compliant handling of static
-destructors, but only works if your C library supports
-@code{__cxa_atexit}.
-
-@item -fno-use-cxa-get-exception-ptr
-@opindex fno-use-cxa-get-exception-ptr
-@opindex fuse-cxa-get-exception-ptr
-Don't use the @code{__cxa_get_exception_ptr} runtime routine. This
-causes @code{std::uncaught_exception} to be incorrect, but is necessary
-if the runtime routine is not available.
-
-@item -fvisibility-inlines-hidden
-@opindex fvisibility-inlines-hidden
-This switch declares that the user does not attempt to compare
-pointers to inline functions or methods where the addresses of the two functions
-are taken in different shared objects.
-
-The effect of this is that GCC may, effectively, mark inline methods with
-@code{__attribute__ ((visibility ("hidden")))} so that they do not
-appear in the export table of a DSO and do not require a PLT indirection
-when used within the DSO@. Enabling this option can have a dramatic effect
-on load and link times of a DSO as it massively reduces the size of the
-dynamic export table when the library makes heavy use of templates.
-
-The behavior of this switch is not quite the same as marking the
-methods as hidden directly, because it does not affect static variables
-local to the function or cause the compiler to deduce that
-the function is defined in only one shared object.
-
-You may mark a method as having a visibility explicitly to negate the
-effect of the switch for that method. For example, if you do want to
-compare pointers to a particular inline method, you might mark it as
-having default visibility. Marking the enclosing class with explicit
-visibility has no effect.
-
-Explicitly instantiated inline methods are unaffected by this option
-as their linkage might otherwise cross a shared library boundary.
-@xref{Template Instantiation}.
-
-@item -fvisibility-ms-compat
-@opindex fvisibility-ms-compat
-This flag attempts to use visibility settings to make GCC's C++
-linkage model compatible with that of Microsoft Visual Studio.
-
-The flag makes these changes to GCC's linkage model:
-
-@enumerate
-@item
-It sets the default visibility to @code{hidden}, like
-@option{-fvisibility=hidden}.
-
-@item
-Types, but not their members, are not hidden by default.
-
-@item
-The One Definition Rule is relaxed for types without explicit
-visibility specifications that are defined in more than one
-shared object: those declarations are permitted if they are
-permitted when this option is not used.
-@end enumerate
-
-In new code it is better to use @option{-fvisibility=hidden} and
-export those classes that are intended to be externally visible.
-Unfortunately it is possible for code to rely, perhaps accidentally,
-on the Visual Studio behavior.
-
-Among the consequences of these changes are that static data members
-of the same type with the same name but defined in different shared
-objects are different, so changing one does not change the other;
-and that pointers to function members defined in different shared
-objects may not compare equal. When this flag is given, it is a
-violation of the ODR to define types with the same name differently.
-
-@item -fno-weak
-@opindex fno-weak
-@opindex fweak
-Do not use weak symbol support, even if it is provided by the linker.
-By default, G++ uses weak symbols if they are available. This
-option exists only for testing, and should not be used by end-users;
-it results in inferior code and has no benefits. This option may
-be removed in a future release of G++.
-
-@item -fext-numeric-literals @r{(C++ and Objective-C++ only)}
-@opindex fext-numeric-literals
-@opindex fno-ext-numeric-literals
-Accept imaginary, fixed-point, or machine-defined
-literal number suffixes as GNU extensions.
-When this option is turned off these suffixes are treated
-as C++11 user-defined literal numeric suffixes.
-This is on by default for all pre-C++11 dialects and all GNU dialects:
-@option{-std=c++98}, @option{-std=gnu++98}, @option{-std=gnu++11},
-@option{-std=gnu++14}.
-This option is off by default
-for ISO C++11 onwards (@option{-std=c++11}, ...).
-
-@item -nostdinc++
-@opindex nostdinc++
-Do not search for header files in the standard directories specific to
-C++, but do still search the other standard directories. (This option
-is used when building the C++ library.)
-
-@item -flang-info-include-translate
-@itemx -flang-info-include-translate-not
-@itemx -flang-info-include-translate=@var{header}
-@opindex flang-info-include-translate
-@opindex flang-info-include-translate-not
-Inform of include translation events. The first will note accepted
-include translations, the second will note declined include
-translations. The @var{header} form will inform of include
-translations relating to that specific header. If @var{header} is of
-the form @code{"user"} or @code{<system>} it will be resolved to a
-specific user or system header using the include path.
-
-@item -flang-info-module-cmi
-@itemx -flang-info-module-cmi=@var{module}
-@opindex flang-info-module-cmi
-Inform of Compiled Module Interface pathnames. The first will note
-all read CMI pathnames. The @var{module} form will not reading a
-specific module's CMI. @var{module} may be a named module or a
-header-unit (the latter indicated by either being a pathname containing
-directory separators or enclosed in @code{<>} or @code{""}).
-
-@item -stdlib=@var{libstdc++,libc++}
-@opindex stdlib
-When G++ is configured to support this option, it allows specification of
-alternate C++ runtime libraries. Two options are available: @var{libstdc++}
-(the default, native C++ runtime for G++) and @var{libc++} which is the
-C++ runtime installed on some operating systems (e.g. Darwin versions from
-Darwin11 onwards). The option switches G++ to use the headers from the
-specified library and to emit @code{-lstdc++} or @code{-lc++} respectively,
-when a C++ runtime is required for linking.
-@end table
-
-In addition, these warning options have meanings only for C++ programs:
-
-@table @gcctabopt
-@item -Wabi-tag @r{(C++ and Objective-C++ only)}
-@opindex Wabi-tag
-Warn when a type with an ABI tag is used in a context that does not
-have that ABI tag. See @ref{C++ Attributes} for more information
-about ABI tags.
-
-@item -Wcomma-subscript @r{(C++ and Objective-C++ only)}
-@opindex Wcomma-subscript
-@opindex Wno-comma-subscript
-Warn about uses of a comma expression within a subscripting expression.
-This usage was deprecated in C++20 and is going to be removed in C++23.
-However, a comma expression wrapped in @code{( )} is not deprecated. Example:
-
-@smallexample
-@group
-void f(int *a, int b, int c) @{
- a[b,c]; // deprecated in C++20, invalid in C++23
- a[(b,c)]; // OK
-@}
-@end group
-@end smallexample
-
-In C++23 it is valid to have comma separated expressions in a subscript
-when an overloaded subscript operator is found and supports the right
-number and types of arguments. G++ will accept the formerly valid syntax
-for code that is not valid in C++23 but used to be valid but deprecated
-in C++20 with a pedantic warning that can be disabled with
-@option{-Wno-comma-subscript}.
-
-Enabled by default with @option{-std=c++20} unless @option{-Wno-deprecated},
-and with @option{-std=c++23} regardless of @option{-Wno-deprecated}.
-
-@item -Wctad-maybe-unsupported @r{(C++ and Objective-C++ only)}
-@opindex Wctad-maybe-unsupported
-@opindex Wno-ctad-maybe-unsupported
-Warn when performing class template argument deduction (CTAD) on a type with
-no explicitly written deduction guides. This warning will point out cases
-where CTAD succeeded only because the compiler synthesized the implicit
-deduction guides, which might not be what the programmer intended. Certain
-style guides allow CTAD only on types that specifically "opt-in"; i.e., on
-types that are designed to support CTAD. This warning can be suppressed with
-the following pattern:
-
-@smallexample
-struct allow_ctad_t; // any name works
-template <typename T> struct S @{
- S(T) @{ @}
-@};
-S(allow_ctad_t) -> S<void>; // guide with incomplete parameter type will never be considered
-@end smallexample
-
-@item -Wctor-dtor-privacy @r{(C++ and Objective-C++ only)}
-@opindex Wctor-dtor-privacy
-@opindex Wno-ctor-dtor-privacy
-Warn when a class seems unusable because all the constructors or
-destructors in that class are private, and it has neither friends nor
-public static member functions. Also warn if there are no non-private
-methods, and there's at least one private member function that isn't
-a constructor or destructor.
-
-@item -Wdangling-reference @r{(C++ and Objective-C++ only)}
-@opindex Wdangling-reference
-@opindex Wno-dangling-reference
-Warn when a reference is bound to a temporary whose lifetime has ended.
-For example:
-
-@smallexample
-int n = 1;
-const int& r = std::max(n - 1, n + 1); // r is dangling
-@end smallexample
-
-In the example above, two temporaries are created, one for each
-argument, and a reference to one of the temporaries is returned.
-However, both temporaries are destroyed at the end of the full
-expression, so the reference @code{r} is dangling. This warning
-also detects dangling references in member initializer lists:
-
-@smallexample
-const int& f(const int& i) @{ return i; @}
-struct S @{
- const int &r; // r is dangling
- S() : r(f(10)) @{ @}
-@};
-@end smallexample
-
-Member functions are checked as well, but only their object argument:
-
-@smallexample
-struct S @{
- const S& self () @{ return *this; @}
-@};
-const S& s = S().self(); // s is dangling
-@end smallexample
-
-Certain functions are safe in this respect, for example @code{std::use_facet}:
-they take and return a reference, but they don't return one of its arguments,
-which can fool the warning. Such functions can be excluded from the warning
-by wrapping them in a @code{#pragma}:
-
-@smallexample
-#pragma GCC diagnostic push
-#pragma GCC diagnostic ignored "-Wdangling-reference"
-const T& foo (const T&) @{ @dots{} @}
-#pragma GCC diagnostic pop
-@end smallexample
-
-This warning is enabled by @option{-Wall}.
-
-@item -Wdelete-non-virtual-dtor @r{(C++ and Objective-C++ only)}
-@opindex Wdelete-non-virtual-dtor
-@opindex Wno-delete-non-virtual-dtor
-Warn when @code{delete} is used to destroy an instance of a class that
-has virtual functions and non-virtual destructor. It is unsafe to delete
-an instance of a derived class through a pointer to a base class if the
-base class does not have a virtual destructor. This warning is enabled
-by @option{-Wall}.
-
-@item -Wdeprecated-copy @r{(C++ and Objective-C++ only)}
-@opindex Wdeprecated-copy
-@opindex Wno-deprecated-copy
-Warn that the implicit declaration of a copy constructor or copy
-assignment operator is deprecated if the class has a user-provided
-copy constructor or copy assignment operator, in C++11 and up. This
-warning is enabled by @option{-Wextra}. With
-@option{-Wdeprecated-copy-dtor}, also deprecate if the class has a
-user-provided destructor.
-
-@item -Wno-deprecated-enum-enum-conversion @r{(C++ and Objective-C++ only)}
-@opindex Wdeprecated-enum-enum-conversion
-@opindex Wno-deprecated-enum-enum-conversion
-Disable the warning about the case when the usual arithmetic conversions
-are applied on operands where one is of enumeration type and the other is
-of a different enumeration type. This conversion was deprecated in C++20.
-For example:
-
-@smallexample
-enum E1 @{ e @};
-enum E2 @{ f @};
-int k = f - e;
-@end smallexample
-
-@option{-Wdeprecated-enum-enum-conversion} is enabled by default with
-@option{-std=c++20}. In pre-C++20 dialects, this warning can be enabled
-by @option{-Wenum-conversion}.
-
-@item -Wno-deprecated-enum-float-conversion @r{(C++ and Objective-C++ only)}
-@opindex Wdeprecated-enum-float-conversion
-@opindex Wno-deprecated-enum-float-conversion
-Disable the warning about the case when the usual arithmetic conversions
-are applied on operands where one is of enumeration type and the other is
-of a floating-point type. This conversion was deprecated in C++20. For
-example:
-
-@smallexample
-enum E1 @{ e @};
-enum E2 @{ f @};
-bool b = e <= 3.7;
-@end smallexample
-
-@option{-Wdeprecated-enum-float-conversion} is enabled by default with
-@option{-std=c++20}. In pre-C++20 dialects, this warning can be enabled
-by @option{-Wenum-conversion}.
-
-@item -Wno-init-list-lifetime @r{(C++ and Objective-C++ only)}
-@opindex Winit-list-lifetime
-@opindex Wno-init-list-lifetime
-Do not warn about uses of @code{std::initializer_list} that are likely
-to result in dangling pointers. Since the underlying array for an
-@code{initializer_list} is handled like a normal C++ temporary object,
-it is easy to inadvertently keep a pointer to the array past the end
-of the array's lifetime. For example:
-
-@itemize @bullet
-@item
-If a function returns a temporary @code{initializer_list}, or a local
-@code{initializer_list} variable, the array's lifetime ends at the end
-of the return statement, so the value returned has a dangling pointer.
-
-@item
-If a new-expression creates an @code{initializer_list}, the array only
-lives until the end of the enclosing full-expression, so the
-@code{initializer_list} in the heap has a dangling pointer.
-
-@item
-When an @code{initializer_list} variable is assigned from a
-brace-enclosed initializer list, the temporary array created for the
-right side of the assignment only lives until the end of the
-full-expression, so at the next statement the @code{initializer_list}
-variable has a dangling pointer.
-
-@smallexample
-// li's initial underlying array lives as long as li
-std::initializer_list<int> li = @{ 1,2,3 @};
-// assignment changes li to point to a temporary array
-li = @{ 4, 5 @};
-// now the temporary is gone and li has a dangling pointer
-int i = li.begin()[0] // undefined behavior
-@end smallexample
-
-@item
-When a list constructor stores the @code{begin} pointer from the
-@code{initializer_list} argument, this doesn't extend the lifetime of
-the array, so if a class variable is constructed from a temporary
-@code{initializer_list}, the pointer is left dangling by the end of
-the variable declaration statement.
-
-@end itemize
-
-@item -Winvalid-imported-macros
-@opindex Winvalid-imported-macros
-@opindex Wno-invalid-imported-macros
-Verify all imported macro definitions are valid at the end of
-compilation. This is not enabled by default, as it requires
-additional processing to determine. It may be useful when preparing
-sets of header-units to ensure consistent macros.
-
-@item -Wno-literal-suffix @r{(C++ and Objective-C++ only)}
-@opindex Wliteral-suffix
-@opindex Wno-literal-suffix
-Do not warn when a string or character literal is followed by a
-ud-suffix which does not begin with an underscore. As a conforming
-extension, GCC treats such suffixes as separate preprocessing tokens
-in order to maintain backwards compatibility with code that uses
-formatting macros from @code{<inttypes.h>}. For example:
-
-@smallexample
-#define __STDC_FORMAT_MACROS
-#include <inttypes.h>
-#include <stdio.h>
-
-int main() @{
- int64_t i64 = 123;
- printf("My int64: %" PRId64"\n", i64);
-@}
-@end smallexample
-
-In this case, @code{PRId64} is treated as a separate preprocessing token.
-
-This option also controls warnings when a user-defined literal
-operator is declared with a literal suffix identifier that doesn't
-begin with an underscore. Literal suffix identifiers that don't begin
-with an underscore are reserved for future standardization.
-
-These warnings are enabled by default.
-
-@item -Wno-narrowing @r{(C++ and Objective-C++ only)}
-@opindex Wnarrowing
-@opindex Wno-narrowing
-For C++11 and later standards, narrowing conversions are diagnosed by default,
-as required by the standard. A narrowing conversion from a constant produces
-an error, and a narrowing conversion from a non-constant produces a warning,
-but @option{-Wno-narrowing} suppresses the diagnostic.
-Note that this does not affect the meaning of well-formed code;
-narrowing conversions are still considered ill-formed in SFINAE contexts.
-
-With @option{-Wnarrowing} in C++98, warn when a narrowing
-conversion prohibited by C++11 occurs within
-@samp{@{ @}}, e.g.
-
-@smallexample
-int i = @{ 2.2 @}; // error: narrowing from double to int
-@end smallexample
-
-This flag is included in @option{-Wall} and @option{-Wc++11-compat}.
-
-@item -Wnoexcept @r{(C++ and Objective-C++ only)}
-@opindex Wnoexcept
-@opindex Wno-noexcept
-Warn when a noexcept-expression evaluates to false because of a call
-to a function that does not have a non-throwing exception
-specification (i.e. @code{throw()} or @code{noexcept}) but is known by
-the compiler to never throw an exception.
-
-@item -Wnoexcept-type @r{(C++ and Objective-C++ only)}
-@opindex Wnoexcept-type
-@opindex Wno-noexcept-type
-Warn if the C++17 feature making @code{noexcept} part of a function
-type changes the mangled name of a symbol relative to C++14. Enabled
-by @option{-Wabi} and @option{-Wc++17-compat}.
-
-As an example:
-
-@smallexample
-template <class T> void f(T t) @{ t(); @};
-void g() noexcept;
-void h() @{ f(g); @}
-@end smallexample
-
-@noindent
-In C++14, @code{f} calls @code{f<void(*)()>}, but in
-C++17 it calls @code{f<void(*)()noexcept>}.
-
-@item -Wclass-memaccess @r{(C++ and Objective-C++ only)}
-@opindex Wclass-memaccess
-@opindex Wno-class-memaccess
-Warn when the destination of a call to a raw memory function such as
-@code{memset} or @code{memcpy} is an object of class type, and when writing
-into such an object might bypass the class non-trivial or deleted constructor
-or copy assignment, violate const-correctness or encapsulation, or corrupt
-virtual table pointers. Modifying the representation of such objects may
-violate invariants maintained by member functions of the class. For example,
-the call to @code{memset} below is undefined because it modifies a non-trivial
-class object and is, therefore, diagnosed. The safe way to either initialize
-or clear the storage of objects of such types is by using the appropriate
-constructor or assignment operator, if one is available.
-@smallexample
-std::string str = "abc";
-memset (&str, 0, sizeof str);
-@end smallexample
-The @option{-Wclass-memaccess} option is enabled by @option{-Wall}.
-Explicitly casting the pointer to the class object to @code{void *} or
-to a type that can be safely accessed by the raw memory function suppresses
-the warning.
-
-@item -Wnon-virtual-dtor @r{(C++ and Objective-C++ only)}
-@opindex Wnon-virtual-dtor
-@opindex Wno-non-virtual-dtor
-Warn when a class has virtual functions and an accessible non-virtual
-destructor itself or in an accessible polymorphic base class, in which
-case it is possible but unsafe to delete an instance of a derived
-class through a pointer to the class itself or base class. This
-warning is automatically enabled if @option{-Weffc++} is specified.
-
-@item -Wregister @r{(C++ and Objective-C++ only)}
-@opindex Wregister
-@opindex Wno-register
-Warn on uses of the @code{register} storage class specifier, except
-when it is part of the GNU @ref{Explicit Register Variables} extension.
-The use of the @code{register} keyword as storage class specifier has
-been deprecated in C++11 and removed in C++17.
-Enabled by default with @option{-std=c++17}.
-
-@item -Wreorder @r{(C++ and Objective-C++ only)}
-@opindex Wreorder
-@opindex Wno-reorder
-@cindex reordering, warning
-@cindex warning for reordering of member initializers
-Warn when the order of member initializers given in the code does not
-match the order in which they must be executed. For instance:
-
-@smallexample
-struct A @{
- int i;
- int j;
- A(): j (0), i (1) @{ @}
-@};
-@end smallexample
-
-@noindent
-The compiler rearranges the member initializers for @code{i}
-and @code{j} to match the declaration order of the members, emitting
-a warning to that effect. This warning is enabled by @option{-Wall}.
-
-@item -Wno-pessimizing-move @r{(C++ and Objective-C++ only)}
-@opindex Wpessimizing-move
-@opindex Wno-pessimizing-move
-This warning warns when a call to @code{std::move} prevents copy
-elision. A typical scenario when copy elision can occur is when returning in
-a function with a class return type, when the expression being returned is the
-name of a non-volatile automatic object, and is not a function parameter, and
-has the same type as the function return type.
-
-@smallexample
-struct T @{
-@dots{}
-@};
-T fn()
-@{
- T t;
- @dots{}
- return std::move (t);
-@}
-@end smallexample
-
-But in this example, the @code{std::move} call prevents copy elision.
-
-This warning is enabled by @option{-Wall}.
-
-@item -Wno-redundant-move @r{(C++ and Objective-C++ only)}
-@opindex Wredundant-move
-@opindex Wno-redundant-move
-This warning warns about redundant calls to @code{std::move}; that is, when
-a move operation would have been performed even without the @code{std::move}
-call. This happens because the compiler is forced to treat the object as if
-it were an rvalue in certain situations such as returning a local variable,
-where copy elision isn't applicable. Consider:
-
-@smallexample
-struct T @{
-@dots{}
-@};
-T fn(T t)
-@{
- @dots{}
- return std::move (t);
-@}
-@end smallexample
-
-Here, the @code{std::move} call is redundant. Because G++ implements Core
-Issue 1579, another example is:
-
-@smallexample
-struct T @{ // convertible to U
-@dots{}
-@};
-struct U @{
-@dots{}
-@};
-U fn()
-@{
- T t;
- @dots{}
- return std::move (t);
-@}
-@end smallexample
-In this example, copy elision isn't applicable because the type of the
-expression being returned and the function return type differ, yet G++
-treats the return value as if it were designated by an rvalue.
-
-This warning is enabled by @option{-Wextra}.
-
-@item -Wrange-loop-construct @r{(C++ and Objective-C++ only)}
-@opindex Wrange-loop-construct
-@opindex Wno-range-loop-construct
-This warning warns when a C++ range-based for-loop is creating an unnecessary
-copy. This can happen when the range declaration is not a reference, but
-probably should be. For example:
-
-@smallexample
-struct S @{ char arr[128]; @};
-void fn () @{
- S arr[5];
- for (const auto x : arr) @{ @dots{} @}
-@}
-@end smallexample
-
-It does not warn when the type being copied is a trivially-copyable type whose
-size is less than 64 bytes.
-
-This warning also warns when a loop variable in a range-based for-loop is
-initialized with a value of a different type resulting in a copy. For example:
-
-@smallexample
-void fn() @{
- int arr[10];
- for (const double &x : arr) @{ @dots{} @}
-@}
-@end smallexample
-
-In the example above, in every iteration of the loop a temporary value of
-type @code{double} is created and destroyed, to which the reference
-@code{const double &} is bound.
-
-This warning is enabled by @option{-Wall}.
-
-@item -Wredundant-tags @r{(C++ and Objective-C++ only)}
-@opindex Wredundant-tags
-@opindex Wno-redundant-tags
-Warn about redundant class-key and enum-key in references to class types
-and enumerated types in contexts where the key can be eliminated without
-causing an ambiguity. For example:
-
-@smallexample
-struct foo;
-struct foo *p; // warn that keyword struct can be eliminated
-@end smallexample
-
-@noindent
-On the other hand, in this example there is no warning:
-
-@smallexample
-struct foo;
-void foo (); // "hides" struct foo
-void bar (struct foo&); // no warning, keyword struct is necessary
-@end smallexample
-
-@item -Wno-subobject-linkage @r{(C++ and Objective-C++ only)}
-@opindex Wsubobject-linkage
-@opindex Wno-subobject-linkage
-Do not warn
-if a class type has a base or a field whose type uses the anonymous
-namespace or depends on a type with no linkage. If a type A depends on
-a type B with no or internal linkage, defining it in multiple
-translation units would be an ODR violation because the meaning of B
-is different in each translation unit. If A only appears in a single
-translation unit, the best way to silence the warning is to give it
-internal linkage by putting it in an anonymous namespace as well. The
-compiler doesn't give this warning for types defined in the main .C
-file, as those are unlikely to have multiple definitions.
-@option{-Wsubobject-linkage} is enabled by default.
-
-@item -Weffc++ @r{(C++ and Objective-C++ only)}
-@opindex Weffc++
-@opindex Wno-effc++
-Warn about violations of the following style guidelines from Scott Meyers'
-@cite{Effective C++} series of books:
-
-@itemize @bullet
-@item
-Define a copy constructor and an assignment operator for classes
-with dynamically-allocated memory.
-
-@item
-Prefer initialization to assignment in constructors.
-
-@item
-Have @code{operator=} return a reference to @code{*this}.
-
-@item
-Don't try to return a reference when you must return an object.
-
-@item
-Distinguish between prefix and postfix forms of increment and
-decrement operators.
-
-@item
-Never overload @code{&&}, @code{||}, or @code{,}.
-
-@end itemize
-
-This option also enables @option{-Wnon-virtual-dtor}, which is also
-one of the effective C++ recommendations. However, the check is
-extended to warn about the lack of virtual destructor in accessible
-non-polymorphic bases classes too.
-
-When selecting this option, be aware that the standard library
-headers do not obey all of these guidelines; use @samp{grep -v}
-to filter out those warnings.
-
-@item -Wno-exceptions @r{(C++ and Objective-C++ only)}
-@opindex Wexceptions
-@opindex Wno-exceptions
-Disable the warning about the case when an exception handler is shadowed by
-another handler, which can point out a wrong ordering of exception handlers.
-
-@item -Wstrict-null-sentinel @r{(C++ and Objective-C++ only)}
-@opindex Wstrict-null-sentinel
-@opindex Wno-strict-null-sentinel
-Warn about the use of an uncasted @code{NULL} as sentinel. When
-compiling only with GCC this is a valid sentinel, as @code{NULL} is defined
-to @code{__null}. Although it is a null pointer constant rather than a
-null pointer, it is guaranteed to be of the same size as a pointer.
-But this use is not portable across different compilers.
-
-@item -Wno-non-template-friend @r{(C++ and Objective-C++ only)}
-@opindex Wno-non-template-friend
-@opindex Wnon-template-friend
-Disable warnings when non-template friend functions are declared
-within a template. In very old versions of GCC that predate implementation
-of the ISO standard, declarations such as
-@samp{friend int foo(int)}, where the name of the friend is an unqualified-id,
-could be interpreted as a particular specialization of a template
-function; the warning exists to diagnose compatibility problems,
-and is enabled by default.
-
-@item -Wold-style-cast @r{(C++ and Objective-C++ only)}
-@opindex Wold-style-cast
-@opindex Wno-old-style-cast
-Warn if an old-style (C-style) cast to a non-void type is used within
-a C++ program. The new-style casts (@code{dynamic_cast},
-@code{static_cast}, @code{reinterpret_cast}, and @code{const_cast}) are
-less vulnerable to unintended effects and much easier to search for.
-
-@item -Woverloaded-virtual @r{(C++ and Objective-C++ only)}
-@itemx -Woverloaded-virtual=@var{n}
-@opindex Woverloaded-virtual
-@opindex Wno-overloaded-virtual
-@cindex overloaded virtual function, warning
-@cindex warning for overloaded virtual function
-Warn when a function declaration hides virtual functions from a
-base class. For example, in:
-
-@smallexample
-struct A @{
- virtual void f();
-@};
-
-struct B: public A @{
- void f(int); // does not override
-@};
-@end smallexample
-
-the @code{A} class version of @code{f} is hidden in @code{B}, and code
-like:
-
-@smallexample
-B* b;
-b->f();
-@end smallexample
-
-@noindent
-fails to compile.
-
-The optional level suffix controls the behavior when all the
-declarations in the derived class override virtual functions in the
-base class, even if not all of the base functions are overridden:
-
-@smallexample
-struct C @{
- virtual void f();
- virtual void f(int);
-@};
-
-struct D: public C @{
- void f(int); // does override
-@}
-@end smallexample
-
-This pattern is less likely to be a mistake; if D is only used
-virtually, the user might have decided that the base class semantics
-for some of the overloads are fine.
-
-At level 1, this case does not warn; at level 2, it does.
-@option{-Woverloaded-virtual} by itself selects level 2. Level 1 is
-included in @option{-Wall}.
-
-@item -Wno-pmf-conversions @r{(C++ and Objective-C++ only)}
-@opindex Wno-pmf-conversions
-@opindex Wpmf-conversions
-Disable the diagnostic for converting a bound pointer to member function
-to a plain pointer.
-
-@item -Wsign-promo @r{(C++ and Objective-C++ only)}
-@opindex Wsign-promo
-@opindex Wno-sign-promo
-Warn when overload resolution chooses a promotion from unsigned or
-enumerated type to a signed type, over a conversion to an unsigned type of
-the same size. Previous versions of G++ tried to preserve
-unsignedness, but the standard mandates the current behavior.
-
-@item -Wtemplates @r{(C++ and Objective-C++ only)}
-@opindex Wtemplates
-@opindex Wno-templates
-Warn when a primary template declaration is encountered. Some coding
-rules disallow templates, and this may be used to enforce that rule.
-The warning is inactive inside a system header file, such as the STL, so
-one can still use the STL. One may also instantiate or specialize
-templates.
-
-@item -Wmismatched-new-delete @r{(C++ and Objective-C++ only)}
-@opindex Wmismatched-new-delete
-@opindex Wno-mismatched-new-delete
-Warn for mismatches between calls to @code{operator new} or @code{operator
-delete} and the corresponding call to the allocation or deallocation function.
-This includes invocations of C++ @code{operator delete} with pointers
-returned from either mismatched forms of @code{operator new}, or from other
-functions that allocate objects for which the @code{operator delete} isn't
-a suitable deallocator, as well as calls to other deallocation functions
-with pointers returned from @code{operator new} for which the deallocation
-function isn't suitable.
-
-For example, the @code{delete} expression in the function below is diagnosed
-because it doesn't match the array form of the @code{new} expression
-the pointer argument was returned from. Similarly, the call to @code{free}
-is also diagnosed.
-
-@smallexample
-void f ()
-@{
- int *a = new int[n];
- delete a; // warning: mismatch in array forms of expressions
-
- char *p = new char[n];
- free (p); // warning: mismatch between new and free
-@}
-@end smallexample
-
-The related option @option{-Wmismatched-dealloc} diagnoses mismatches
-involving allocation and deallocation functions other than @code{operator
-new} and @code{operator delete}.
-
-@option{-Wmismatched-new-delete} is included in @option{-Wall}.
-
-@item -Wmismatched-tags @r{(C++ and Objective-C++ only)}
-@opindex Wmismatched-tags
-@opindex Wno-mismatched-tags
-Warn for declarations of structs, classes, and class templates and their
-specializations with a class-key that does not match either the definition
-or the first declaration if no definition is provided.
-
-For example, the declaration of @code{struct Object} in the argument list
-of @code{draw} triggers the warning. To avoid it, either remove the redundant
-class-key @code{struct} or replace it with @code{class} to match its definition.
-@smallexample
-class Object @{
-public:
- virtual ~Object () = 0;
-@};
-void draw (struct Object*);
-@end smallexample
-
-It is not wrong to declare a class with the class-key @code{struct} as
-the example above shows. The @option{-Wmismatched-tags} option is intended
-to help achieve a consistent style of class declarations. In code that is
-intended to be portable to Windows-based compilers the warning helps prevent
-unresolved references due to the difference in the mangling of symbols
-declared with different class-keys. The option can be used either on its
-own or in conjunction with @option{-Wredundant-tags}.
-
-@item -Wmultiple-inheritance @r{(C++ and Objective-C++ only)}
-@opindex Wmultiple-inheritance
-@opindex Wno-multiple-inheritance
-Warn when a class is defined with multiple direct base classes. Some
-coding rules disallow multiple inheritance, and this may be used to
-enforce that rule. The warning is inactive inside a system header file,
-such as the STL, so one can still use the STL. One may also define
-classes that indirectly use multiple inheritance.
-
-@item -Wvirtual-inheritance
-@opindex Wvirtual-inheritance
-@opindex Wno-virtual-inheritance
-Warn when a class is defined with a virtual direct base class. Some
-coding rules disallow multiple inheritance, and this may be used to
-enforce that rule. The warning is inactive inside a system header file,
-such as the STL, so one can still use the STL. One may also define
-classes that indirectly use virtual inheritance.
-
-@item -Wno-virtual-move-assign
-@opindex Wvirtual-move-assign
-@opindex Wno-virtual-move-assign
-Suppress warnings about inheriting from a virtual base with a
-non-trivial C++11 move assignment operator. This is dangerous because
-if the virtual base is reachable along more than one path, it is
-moved multiple times, which can mean both objects end up in the
-moved-from state. If the move assignment operator is written to avoid
-moving from a moved-from object, this warning can be disabled.
-
-@item -Wnamespaces
-@opindex Wnamespaces
-@opindex Wno-namespaces
-Warn when a namespace definition is opened. Some coding rules disallow
-namespaces, and this may be used to enforce that rule. The warning is
-inactive inside a system header file, such as the STL, so one can still
-use the STL. One may also use using directives and qualified names.
-
-@item -Wno-terminate @r{(C++ and Objective-C++ only)}
-@opindex Wterminate
-@opindex Wno-terminate
-Disable the warning about a throw-expression that will immediately
-result in a call to @code{terminate}.
-
-@item -Wno-vexing-parse @r{(C++ and Objective-C++ only)}
-@opindex Wvexing-parse
-@opindex Wno-vexing-parse
-Warn about the most vexing parse syntactic ambiguity. This warns about
-the cases when a declaration looks like a variable definition, but the
-C++ language requires it to be interpreted as a function declaration.
-For instance:
-
-@smallexample
-void f(double a) @{
- int i(); // extern int i (void);
- int n(int(a)); // extern int n (int);
-@}
-@end smallexample
-
-Another example:
-
-@smallexample
-struct S @{ S(int); @};
-void f(double a) @{
- S x(int(a)); // extern struct S x (int);
- S y(int()); // extern struct S y (int (*) (void));
- S z(); // extern struct S z (void);
-@}
-@end smallexample
-
-The warning will suggest options how to deal with such an ambiguity; e.g.,
-it can suggest removing the parentheses or using braces instead.
-
-This warning is enabled by default.
-
-@item -Wno-class-conversion @r{(C++ and Objective-C++ only)}
-@opindex Wno-class-conversion
-@opindex Wclass-conversion
-Do not warn when a conversion function converts an
-object to the same type, to a base class of that type, or to void; such
-a conversion function will never be called.
-
-@item -Wvolatile @r{(C++ and Objective-C++ only)}
-@opindex Wvolatile
-@opindex Wno-volatile
-Warn about deprecated uses of the @code{volatile} qualifier. This includes
-postfix and prefix @code{++} and @code{--} expressions of
-@code{volatile}-qualified types, using simple assignments where the left
-operand is a @code{volatile}-qualified non-class type for their value,
-compound assignments where the left operand is a @code{volatile}-qualified
-non-class type, @code{volatile}-qualified function return type,
-@code{volatile}-qualified parameter type, and structured bindings of a
-@code{volatile}-qualified type. This usage was deprecated in C++20.
-
-Enabled by default with @option{-std=c++20}.
-
-@item -Wzero-as-null-pointer-constant @r{(C++ and Objective-C++ only)}
-@opindex Wzero-as-null-pointer-constant
-@opindex Wno-zero-as-null-pointer-constant
-Warn when a literal @samp{0} is used as null pointer constant. This can
-be useful to facilitate the conversion to @code{nullptr} in C++11.
-
-@item -Waligned-new
-@opindex Waligned-new
-@opindex Wno-aligned-new
-Warn about a new-expression of a type that requires greater alignment
-than the @code{alignof(std::max_align_t)} but uses an allocation
-function without an explicit alignment parameter. This option is
-enabled by @option{-Wall}.
-
-Normally this only warns about global allocation functions, but
-@option{-Waligned-new=all} also warns about class member allocation
-functions.
-
-@item -Wno-placement-new
-@itemx -Wplacement-new=@var{n}
-@opindex Wplacement-new
-@opindex Wno-placement-new
-Warn about placement new expressions with undefined behavior, such as
-constructing an object in a buffer that is smaller than the type of
-the object. For example, the placement new expression below is diagnosed
-because it attempts to construct an array of 64 integers in a buffer only
-64 bytes large.
-@smallexample
-char buf [64];
-new (buf) int[64];
-@end smallexample
-This warning is enabled by default.
-
-@table @gcctabopt
-@item -Wplacement-new=1
-This is the default warning level of @option{-Wplacement-new}. At this
-level the warning is not issued for some strictly undefined constructs that
-GCC allows as extensions for compatibility with legacy code. For example,
-the following @code{new} expression is not diagnosed at this level even
-though it has undefined behavior according to the C++ standard because
-it writes past the end of the one-element array.
-@smallexample
-struct S @{ int n, a[1]; @};
-S *s = (S *)malloc (sizeof *s + 31 * sizeof s->a[0]);
-new (s->a)int [32]();
-@end smallexample
-
-@item -Wplacement-new=2
-At this level, in addition to diagnosing all the same constructs as at level
-1, a diagnostic is also issued for placement new expressions that construct
-an object in the last member of structure whose type is an array of a single
-element and whose size is less than the size of the object being constructed.
-While the previous example would be diagnosed, the following construct makes
-use of the flexible member array extension to avoid the warning at level 2.
-@smallexample
-struct S @{ int n, a[]; @};
-S *s = (S *)malloc (sizeof *s + 32 * sizeof s->a[0]);
-new (s->a)int [32]();
-@end smallexample
-
-@end table
-
-@item -Wcatch-value
-@itemx -Wcatch-value=@var{n} @r{(C++ and Objective-C++ only)}
-@opindex Wcatch-value
-@opindex Wno-catch-value
-Warn about catch handlers that do not catch via reference.
-With @option{-Wcatch-value=1} (or @option{-Wcatch-value} for short)
-warn about polymorphic class types that are caught by value.
-With @option{-Wcatch-value=2} warn about all class types that are caught
-by value. With @option{-Wcatch-value=3} warn about all types that are
-not caught by reference. @option{-Wcatch-value} is enabled by @option{-Wall}.
-
-@item -Wconditionally-supported @r{(C++ and Objective-C++ only)}
-@opindex Wconditionally-supported
-@opindex Wno-conditionally-supported
-Warn for conditionally-supported (C++11 [intro.defs]) constructs.
-
-@item -Wno-delete-incomplete @r{(C++ and Objective-C++ only)}
-@opindex Wdelete-incomplete
-@opindex Wno-delete-incomplete
-Do not warn when deleting a pointer to incomplete type, which may cause
-undefined behavior at runtime. This warning is enabled by default.
-
-@item -Wextra-semi @r{(C++, Objective-C++ only)}
-@opindex Wextra-semi
-@opindex Wno-extra-semi
-Warn about redundant semicolons after in-class function definitions.
-
-@item -Wno-inaccessible-base @r{(C++, Objective-C++ only)}
-@opindex Winaccessible-base
-@opindex Wno-inaccessible-base
-This option controls warnings
-when a base class is inaccessible in a class derived from it due to
-ambiguity. The warning is enabled by default.
-Note that the warning for ambiguous virtual
-bases is enabled by the @option{-Wextra} option.
-@smallexample
-@group
-struct A @{ int a; @};
-
-struct B : A @{ @};
-
-struct C : B, A @{ @};
-@end group
-@end smallexample
-
-@item -Wno-inherited-variadic-ctor
-@opindex Winherited-variadic-ctor
-@opindex Wno-inherited-variadic-ctor
-Suppress warnings about use of C++11 inheriting constructors when the
-base class inherited from has a C variadic constructor; the warning is
-on by default because the ellipsis is not inherited.
-
-@item -Wno-invalid-offsetof @r{(C++ and Objective-C++ only)}
-@opindex Wno-invalid-offsetof
-@opindex Winvalid-offsetof
-Suppress warnings from applying the @code{offsetof} macro to a non-POD
-type. According to the 2014 ISO C++ standard, applying @code{offsetof}
-to a non-standard-layout type is undefined. In existing C++ implementations,
-however, @code{offsetof} typically gives meaningful results.
-This flag is for users who are aware that they are
-writing nonportable code and who have deliberately chosen to ignore the
-warning about it.
-
-The restrictions on @code{offsetof} may be relaxed in a future version
-of the C++ standard.
-
-@item -Wsized-deallocation @r{(C++ and Objective-C++ only)}
-@opindex Wsized-deallocation
-@opindex Wno-sized-deallocation
-Warn about a definition of an unsized deallocation function
-@smallexample
-void operator delete (void *) noexcept;
-void operator delete[] (void *) noexcept;
-@end smallexample
-without a definition of the corresponding sized deallocation function
-@smallexample
-void operator delete (void *, std::size_t) noexcept;
-void operator delete[] (void *, std::size_t) noexcept;
-@end smallexample
-or vice versa. Enabled by @option{-Wextra} along with
-@option{-fsized-deallocation}.
-
-@item -Wsuggest-final-types
-@opindex Wno-suggest-final-types
-@opindex Wsuggest-final-types
-Warn about types with virtual methods where code quality would be improved
-if the type were declared with the C++11 @code{final} specifier,
-or, if possible,
-declared in an anonymous namespace. This allows GCC to more aggressively
-devirtualize the polymorphic calls. This warning is more effective with
-link-time optimization,
-where the information about the class hierarchy graph is
-more complete.
-
-@item -Wsuggest-final-methods
-@opindex Wno-suggest-final-methods
-@opindex Wsuggest-final-methods
-Warn about virtual methods where code quality would be improved if the method
-were declared with the C++11 @code{final} specifier,
-or, if possible, its type were
-declared in an anonymous namespace or with the @code{final} specifier.
-This warning is
-more effective with link-time optimization, where the information about the
-class hierarchy graph is more complete. It is recommended to first consider
-suggestions of @option{-Wsuggest-final-types} and then rebuild with new
-annotations.
-
-@item -Wsuggest-override
-@opindex Wsuggest-override
-@opindex Wno-suggest-override
-Warn about overriding virtual functions that are not marked with the
-@code{override} keyword.
-
-@item -Wuse-after-free
-@itemx -Wuse-after-free=@var{n}
-@opindex Wuse-after-free
-@opindex Wno-use-after-free
-Warn about uses of pointers to dynamically allocated objects that have
-been rendered indeterminate by a call to a deallocation function.
-The warning is enabled at all optimization levels but may yield different
-results with optimization than without.
-
-@table @gcctabopt
-@item -Wuse-after-free=1
-At level 1 the warning attempts to diagnose only unconditional uses
-of pointers made indeterminate by a deallocation call or a successful
-call to @code{realloc}, regardless of whether or not the call resulted
-in an actual reallocatio of memory. This includes double-@code{free}
-calls as well as uses in arithmetic and relational expressions. Although
-undefined, uses of indeterminate pointers in equality (or inequality)
-expressions are not diagnosed at this level.
-@item -Wuse-after-free=2
-At level 2, in addition to unconditional uses, the warning also diagnoses
-conditional uses of pointers made indeterminate by a deallocation call.
-As at level 2, uses in equality (or inequality) expressions are not
-diagnosed. For example, the second call to @code{free} in the following
-function is diagnosed at this level:
-@smallexample
-struct A @{ int refcount; void *data; @};
-
-void release (struct A *p)
-@{
- int refcount = --p->refcount;
- free (p);
- if (refcount == 0)
- free (p->data); // warning: p may be used after free
-@}
-@end smallexample
-@item -Wuse-after-free=3
-At level 3, the warning also diagnoses uses of indeterminate pointers in
-equality expressions. All uses of indeterminate pointers are undefined
-but equality tests sometimes appear after calls to @code{realloc} as
-an attempt to determine whether the call resulted in relocating the object
-to a different address. They are diagnosed at a separate level to aid
-legacy code gradually transition to safe alternatives. For example,
-the equality test in the function below is diagnosed at this level:
-@smallexample
-void adjust_pointers (int**, int);
-
-void grow (int **p, int n)
-@{
- int **q = (int**)realloc (p, n *= 2);
- if (q == p)
- return;
- adjust_pointers ((int**)q, n);
-@}
-@end smallexample
-To avoid the warning at this level, store offsets into allocated memory
-instead of pointers. This approach obviates needing to adjust the stored
-pointers after reallocation.
-@end table
-
-@option{-Wuse-after-free=2} is included in @option{-Wall}.
-
-@item -Wuseless-cast @r{(C++ and Objective-C++ only)}
-@opindex Wuseless-cast
-@opindex Wno-useless-cast
-Warn when an expression is cast to its own type. This warning does not
-occur when a class object is converted to a non-reference type as that
-is a way to create a temporary:
-
-@smallexample
-struct S @{ @};
-void g (S&&);
-void f (S&& arg)
-@{
- g (S(arg)); // make arg prvalue so that it can bind to S&&
-@}
-@end smallexample
-
-@item -Wno-conversion-null @r{(C++ and Objective-C++ only)}
-@opindex Wconversion-null
-@opindex Wno-conversion-null
-Do not warn for conversions between @code{NULL} and non-pointer
-types. @option{-Wconversion-null} is enabled by default.
-
-@end table
-
-@node Objective-C and Objective-C++ Dialect Options
-@section Options Controlling Objective-C and Objective-C++ Dialects
-
-@cindex compiler options, Objective-C and Objective-C++
-@cindex Objective-C and Objective-C++ options, command-line
-@cindex options, Objective-C and Objective-C++
-(NOTE: This manual does not describe the Objective-C and Objective-C++
-languages themselves. @xref{Standards,,Language Standards
-Supported by GCC}, for references.)
-
-This section describes the command-line options that are only meaningful
-for Objective-C and Objective-C++ programs. You can also use most of
-the language-independent GNU compiler options.
-For example, you might compile a file @file{some_class.m} like this:
-
-@smallexample
-gcc -g -fgnu-runtime -O -c some_class.m
-@end smallexample
-
-@noindent
-In this example, @option{-fgnu-runtime} is an option meant only for
-Objective-C and Objective-C++ programs; you can use the other options with
-any language supported by GCC@.
-
-Note that since Objective-C is an extension of the C language, Objective-C
-compilations may also use options specific to the C front-end (e.g.,
-@option{-Wtraditional}). Similarly, Objective-C++ compilations may use
-C++-specific options (e.g., @option{-Wabi}).
-
-Here is a list of options that are @emph{only} for compiling Objective-C
-and Objective-C++ programs:
-
-@table @gcctabopt
-@item -fconstant-string-class=@var{class-name}
-@opindex fconstant-string-class
-Use @var{class-name} as the name of the class to instantiate for each
-literal string specified with the syntax @code{@@"@dots{}"}. The default
-class name is @code{NXConstantString} if the GNU runtime is being used, and
-@code{NSConstantString} if the NeXT runtime is being used (see below). The
-@option{-fconstant-cfstrings} option, if also present, overrides the
-@option{-fconstant-string-class} setting and cause @code{@@"@dots{}"} literals
-to be laid out as constant CoreFoundation strings.
-
-@item -fgnu-runtime
-@opindex fgnu-runtime
-Generate object code compatible with the standard GNU Objective-C
-runtime. This is the default for most types of systems.
-
-@item -fnext-runtime
-@opindex fnext-runtime
-Generate output compatible with the NeXT runtime. This is the default
-for NeXT-based systems, including Darwin and Mac OS X@. The macro
-@code{__NEXT_RUNTIME__} is predefined if (and only if) this option is
-used.
-
-@item -fno-nil-receivers
-@opindex fno-nil-receivers
-@opindex fnil-receivers
-Assume that all Objective-C message dispatches (@code{[receiver
-message:arg]}) in this translation unit ensure that the receiver is
-not @code{nil}. This allows for more efficient entry points in the
-runtime to be used. This option is only available in conjunction with
-the NeXT runtime and ABI version 0 or 1.
-
-@item -fobjc-abi-version=@var{n}
-@opindex fobjc-abi-version
-Use version @var{n} of the Objective-C ABI for the selected runtime.
-This option is currently supported only for the NeXT runtime. In that
-case, Version 0 is the traditional (32-bit) ABI without support for
-properties and other Objective-C 2.0 additions. Version 1 is the
-traditional (32-bit) ABI with support for properties and other
-Objective-C 2.0 additions. Version 2 is the modern (64-bit) ABI. If
-nothing is specified, the default is Version 0 on 32-bit target
-machines, and Version 2 on 64-bit target machines.
-
-@item -fobjc-call-cxx-cdtors
-@opindex fobjc-call-cxx-cdtors
-For each Objective-C class, check if any of its instance variables is a
-C++ object with a non-trivial default constructor. If so, synthesize a
-special @code{- (id) .cxx_construct} instance method which runs
-non-trivial default constructors on any such instance variables, in order,
-and then return @code{self}. Similarly, check if any instance variable
-is a C++ object with a non-trivial destructor, and if so, synthesize a
-special @code{- (void) .cxx_destruct} method which runs
-all such default destructors, in reverse order.
-
-The @code{- (id) .cxx_construct} and @code{- (void) .cxx_destruct}
-methods thusly generated only operate on instance variables
-declared in the current Objective-C class, and not those inherited
-from superclasses. It is the responsibility of the Objective-C
-runtime to invoke all such methods in an object's inheritance
-hierarchy. The @code{- (id) .cxx_construct} methods are invoked
-by the runtime immediately after a new object instance is allocated;
-the @code{- (void) .cxx_destruct} methods are invoked immediately
-before the runtime deallocates an object instance.
-
-As of this writing, only the NeXT runtime on Mac OS X 10.4 and later has
-support for invoking the @code{- (id) .cxx_construct} and
-@code{- (void) .cxx_destruct} methods.
-
-@item -fobjc-direct-dispatch
-@opindex fobjc-direct-dispatch
-Allow fast jumps to the message dispatcher. On Darwin this is
-accomplished via the comm page.
-
-@item -fobjc-exceptions
-@opindex fobjc-exceptions
-Enable syntactic support for structured exception handling in
-Objective-C, similar to what is offered by C++. This option
-is required to use the Objective-C keywords @code{@@try},
-@code{@@throw}, @code{@@catch}, @code{@@finally} and
-@code{@@synchronized}. This option is available with both the GNU
-runtime and the NeXT runtime (but not available in conjunction with
-the NeXT runtime on Mac OS X 10.2 and earlier).
-
-@item -fobjc-gc
-@opindex fobjc-gc
-Enable garbage collection (GC) in Objective-C and Objective-C++
-programs. This option is only available with the NeXT runtime; the
-GNU runtime has a different garbage collection implementation that
-does not require special compiler flags.
-
-@item -fobjc-nilcheck
-@opindex fobjc-nilcheck
-For the NeXT runtime with version 2 of the ABI, check for a nil
-receiver in method invocations before doing the actual method call.
-This is the default and can be disabled using
-@option{-fno-objc-nilcheck}. Class methods and super calls are never
-checked for nil in this way no matter what this flag is set to.
-Currently this flag does nothing when the GNU runtime, or an older
-version of the NeXT runtime ABI, is used.
-
-@item -fobjc-std=objc1
-@opindex fobjc-std
-Conform to the language syntax of Objective-C 1.0, the language
-recognized by GCC 4.0. This only affects the Objective-C additions to
-the C/C++ language; it does not affect conformance to C/C++ standards,
-which is controlled by the separate C/C++ dialect option flags. When
-this option is used with the Objective-C or Objective-C++ compiler,
-any Objective-C syntax that is not recognized by GCC 4.0 is rejected.
-This is useful if you need to make sure that your Objective-C code can
-be compiled with older versions of GCC@.
-
-@item -freplace-objc-classes
-@opindex freplace-objc-classes
-Emit a special marker instructing @command{ld(1)} not to statically link in
-the resulting object file, and allow @command{dyld(1)} to load it in at
-run time instead. This is used in conjunction with the Fix-and-Continue
-debugging mode, where the object file in question may be recompiled and
-dynamically reloaded in the course of program execution, without the need
-to restart the program itself. Currently, Fix-and-Continue functionality
-is only available in conjunction with the NeXT runtime on Mac OS X 10.3
-and later.
-
-@item -fzero-link
-@opindex fzero-link
-When compiling for the NeXT runtime, the compiler ordinarily replaces calls
-to @code{objc_getClass("@dots{}")} (when the name of the class is known at
-compile time) with static class references that get initialized at load time,
-which improves run-time performance. Specifying the @option{-fzero-link} flag
-suppresses this behavior and causes calls to @code{objc_getClass("@dots{}")}
-to be retained. This is useful in Zero-Link debugging mode, since it allows
-for individual class implementations to be modified during program execution.
-The GNU runtime currently always retains calls to @code{objc_get_class("@dots{}")}
-regardless of command-line options.
-
-@item -fno-local-ivars
-@opindex fno-local-ivars
-@opindex flocal-ivars
-By default instance variables in Objective-C can be accessed as if
-they were local variables from within the methods of the class they're
-declared in. This can lead to shadowing between instance variables
-and other variables declared either locally inside a class method or
-globally with the same name. Specifying the @option{-fno-local-ivars}
-flag disables this behavior thus avoiding variable shadowing issues.
-
-@item -fivar-visibility=@r{[}public@r{|}protected@r{|}private@r{|}package@r{]}
-@opindex fivar-visibility
-Set the default instance variable visibility to the specified option
-so that instance variables declared outside the scope of any access
-modifier directives default to the specified visibility.
-
-@item -gen-decls
-@opindex gen-decls
-Dump interface declarations for all classes seen in the source file to a
-file named @file{@var{sourcename}.decl}.
-
-@item -Wassign-intercept @r{(Objective-C and Objective-C++ only)}
-@opindex Wassign-intercept
-@opindex Wno-assign-intercept
-Warn whenever an Objective-C assignment is being intercepted by the
-garbage collector.
-
-@item -Wno-property-assign-default @r{(Objective-C and Objective-C++ only)}
-@opindex Wproperty-assign-default
-@opindex Wno-property-assign-default
-Do not warn if a property for an Objective-C object has no assign
-semantics specified.
-
-@item -Wno-protocol @r{(Objective-C and Objective-C++ only)}
-@opindex Wno-protocol
-@opindex Wprotocol
-If a class is declared to implement a protocol, a warning is issued for
-every method in the protocol that is not implemented by the class. The
-default behavior is to issue a warning for every method not explicitly
-implemented in the class, even if a method implementation is inherited
-from the superclass. If you use the @option{-Wno-protocol} option, then
-methods inherited from the superclass are considered to be implemented,
-and no warning is issued for them.
-
-@item -Wobjc-root-class @r{(Objective-C and Objective-C++ only)}
-@opindex Wobjc-root-class
-Warn if a class interface lacks a superclass. Most classes will inherit
-from @code{NSObject} (or @code{Object}) for example. When declaring
-classes intended to be root classes, the warning can be suppressed by
-marking their interfaces with @code{__attribute__((objc_root_class))}.
-
-@item -Wselector @r{(Objective-C and Objective-C++ only)}
-@opindex Wselector
-@opindex Wno-selector
-Warn if multiple methods of different types for the same selector are
-found during compilation. The check is performed on the list of methods
-in the final stage of compilation. Additionally, a check is performed
-for each selector appearing in a @code{@@selector(@dots{})}
-expression, and a corresponding method for that selector has been found
-during compilation. Because these checks scan the method table only at
-the end of compilation, these warnings are not produced if the final
-stage of compilation is not reached, for example because an error is
-found during compilation, or because the @option{-fsyntax-only} option is
-being used.
-
-@item -Wstrict-selector-match @r{(Objective-C and Objective-C++ only)}
-@opindex Wstrict-selector-match
-@opindex Wno-strict-selector-match
-Warn if multiple methods with differing argument and/or return types are
-found for a given selector when attempting to send a message using this
-selector to a receiver of type @code{id} or @code{Class}. When this flag
-is off (which is the default behavior), the compiler omits such warnings
-if any differences found are confined to types that share the same size
-and alignment.
-
-@item -Wundeclared-selector @r{(Objective-C and Objective-C++ only)}
-@opindex Wundeclared-selector
-@opindex Wno-undeclared-selector
-Warn if a @code{@@selector(@dots{})} expression referring to an
-undeclared selector is found. A selector is considered undeclared if no
-method with that name has been declared before the
-@code{@@selector(@dots{})} expression, either explicitly in an
-@code{@@interface} or @code{@@protocol} declaration, or implicitly in
-an @code{@@implementation} section. This option always performs its
-checks as soon as a @code{@@selector(@dots{})} expression is found,
-while @option{-Wselector} only performs its checks in the final stage of
-compilation. This also enforces the coding style convention
-that methods and selectors must be declared before being used.
-
-@item -print-objc-runtime-info
-@opindex print-objc-runtime-info
-Generate C header describing the largest structure that is passed by
-value, if any.
-
-@end table
-
-@node Diagnostic Message Formatting Options
-@section Options to Control Diagnostic Messages Formatting
-@cindex options to control diagnostics formatting
-@cindex diagnostic messages
-@cindex message formatting
-
-Traditionally, diagnostic messages have been formatted irrespective of
-the output device's aspect (e.g.@: its width, @dots{}). You can use the
-options described below
-to control the formatting algorithm for diagnostic messages,
-e.g.@: how many characters per line, how often source location
-information should be reported. Note that some language front ends may not
-honor these options.
-
-@table @gcctabopt
-@item -fmessage-length=@var{n}
-@opindex fmessage-length
-Try to format error messages so that they fit on lines of about
-@var{n} characters. If @var{n} is zero, then no line-wrapping is
-done; each error message appears on a single line. This is the
-default for all front ends.
-
-Note - this option also affects the display of the @samp{#error} and
-@samp{#warning} pre-processor directives, and the @samp{deprecated}
-function/type/variable attribute. It does not however affect the
-@samp{pragma GCC warning} and @samp{pragma GCC error} pragmas.
-
-@item -fdiagnostics-plain-output
-This option requests that diagnostic output look as plain as possible, which
-may be useful when running @command{dejagnu} or other utilities that need to
-parse diagnostics output and prefer that it remain more stable over time.
-@option{-fdiagnostics-plain-output} is currently equivalent to the following
-options:
-@gccoptlist{-fno-diagnostics-show-caret @gol
--fno-diagnostics-show-line-numbers @gol
--fdiagnostics-color=never @gol
--fdiagnostics-urls=never @gol
--fdiagnostics-path-format=separate-events}
-In the future, if GCC changes the default appearance of its diagnostics, the
-corresponding option to disable the new behavior will be added to this list.
-
-@item -fdiagnostics-show-location=once
-@opindex fdiagnostics-show-location
-Only meaningful in line-wrapping mode. Instructs the diagnostic messages
-reporter to emit source location information @emph{once}; that is, in
-case the message is too long to fit on a single physical line and has to
-be wrapped, the source location won't be emitted (as prefix) again,
-over and over, in subsequent continuation lines. This is the default
-behavior.
-
-@item -fdiagnostics-show-location=every-line
-Only meaningful in line-wrapping mode. Instructs the diagnostic
-messages reporter to emit the same source location information (as
-prefix) for physical lines that result from the process of breaking
-a message which is too long to fit on a single line.
-
-@item -fdiagnostics-color[=@var{WHEN}]
-@itemx -fno-diagnostics-color
-@opindex fdiagnostics-color
-@cindex highlight, color
-@vindex GCC_COLORS @r{environment variable}
-Use color in diagnostics. @var{WHEN} is @samp{never}, @samp{always},
-or @samp{auto}. The default depends on how the compiler has been configured,
-it can be any of the above @var{WHEN} options or also @samp{never}
-if @env{GCC_COLORS} environment variable isn't present in the environment,
-and @samp{auto} otherwise.
-@samp{auto} makes GCC use color only when the standard error is a terminal,
-and when not executing in an emacs shell.
-The forms @option{-fdiagnostics-color} and @option{-fno-diagnostics-color} are
-aliases for @option{-fdiagnostics-color=always} and
-@option{-fdiagnostics-color=never}, respectively.
-
-The colors are defined by the environment variable @env{GCC_COLORS}.
-Its value is a colon-separated list of capabilities and Select Graphic
-Rendition (SGR) substrings. SGR commands are interpreted by the
-terminal or terminal emulator. (See the section in the documentation
-of your text terminal for permitted values and their meanings as
-character attributes.) These substring values are integers in decimal
-representation and can be concatenated with semicolons.
-Common values to concatenate include
-@samp{1} for bold,
-@samp{4} for underline,
-@samp{5} for blink,
-@samp{7} for inverse,
-@samp{39} for default foreground color,
-@samp{30} to @samp{37} for foreground colors,
-@samp{90} to @samp{97} for 16-color mode foreground colors,
-@samp{38;5;0} to @samp{38;5;255}
-for 88-color and 256-color modes foreground colors,
-@samp{49} for default background color,
-@samp{40} to @samp{47} for background colors,
-@samp{100} to @samp{107} for 16-color mode background colors,
-and @samp{48;5;0} to @samp{48;5;255}
-for 88-color and 256-color modes background colors.
-
-The default @env{GCC_COLORS} is
-@smallexample
-error=01;31:warning=01;35:note=01;36:range1=32:range2=34:locus=01:\
-quote=01:path=01;36:fixit-insert=32:fixit-delete=31:\
-diff-filename=01:diff-hunk=32:diff-delete=31:diff-insert=32:\
-type-diff=01;32:fnname=01;32:targs=35
-@end smallexample
-@noindent
-where @samp{01;31} is bold red, @samp{01;35} is bold magenta,
-@samp{01;36} is bold cyan, @samp{32} is green, @samp{34} is blue,
-@samp{01} is bold, and @samp{31} is red.
-Setting @env{GCC_COLORS} to the empty string disables colors.
-Supported capabilities are as follows.
-
-@table @code
-@item error=
-@vindex error GCC_COLORS @r{capability}
-SGR substring for error: markers.
-
-@item warning=
-@vindex warning GCC_COLORS @r{capability}
-SGR substring for warning: markers.
-
-@item note=
-@vindex note GCC_COLORS @r{capability}
-SGR substring for note: markers.
-
-@item path=
-@vindex path GCC_COLORS @r{capability}
-SGR substring for colorizing paths of control-flow events as printed
-via @option{-fdiagnostics-path-format=}, such as the identifiers of
-individual events and lines indicating interprocedural calls and returns.
-
-@item range1=
-@vindex range1 GCC_COLORS @r{capability}
-SGR substring for first additional range.
-
-@item range2=
-@vindex range2 GCC_COLORS @r{capability}
-SGR substring for second additional range.
-
-@item locus=
-@vindex locus GCC_COLORS @r{capability}
-SGR substring for location information, @samp{file:line} or
-@samp{file:line:column} etc.
-
-@item quote=
-@vindex quote GCC_COLORS @r{capability}
-SGR substring for information printed within quotes.
-
-@item fnname=
-@vindex fnname GCC_COLORS @r{capability}
-SGR substring for names of C++ functions.
-
-@item targs=
-@vindex targs GCC_COLORS @r{capability}
-SGR substring for C++ function template parameter bindings.
-
-@item fixit-insert=
-@vindex fixit-insert GCC_COLORS @r{capability}
-SGR substring for fix-it hints suggesting text to
-be inserted or replaced.
-
-@item fixit-delete=
-@vindex fixit-delete GCC_COLORS @r{capability}
-SGR substring for fix-it hints suggesting text to
-be deleted.
-
-@item diff-filename=
-@vindex diff-filename GCC_COLORS @r{capability}
-SGR substring for filename headers within generated patches.
-
-@item diff-hunk=
-@vindex diff-hunk GCC_COLORS @r{capability}
-SGR substring for the starts of hunks within generated patches.
-
-@item diff-delete=
-@vindex diff-delete GCC_COLORS @r{capability}
-SGR substring for deleted lines within generated patches.
-
-@item diff-insert=
-@vindex diff-insert GCC_COLORS @r{capability}
-SGR substring for inserted lines within generated patches.
-
-@item type-diff=
-@vindex type-diff GCC_COLORS @r{capability}
-SGR substring for highlighting mismatching types within template
-arguments in the C++ frontend.
-@end table
-
-@item -fdiagnostics-urls[=@var{WHEN}]
-@opindex fdiagnostics-urls
-@cindex urls
-@vindex GCC_URLS @r{environment variable}
-@vindex TERM_URLS @r{environment variable}
-Use escape sequences to embed URLs in diagnostics. For example, when
-@option{-fdiagnostics-show-option} emits text showing the command-line
-option controlling a diagnostic, embed a URL for documentation of that
-option.
-
-@var{WHEN} is @samp{never}, @samp{always}, or @samp{auto}.
-@samp{auto} makes GCC use URL escape sequences only when the standard error
-is a terminal, and when not executing in an emacs shell or any graphical
-terminal which is known to be incompatible with this feature, see below.
-
-The default depends on how the compiler has been configured.
-It can be any of the above @var{WHEN} options.
-
-GCC can also be configured (via the
-@option{--with-diagnostics-urls=auto-if-env} configure-time option)
-so that the default is affected by environment variables.
-Under such a configuration, GCC defaults to using @samp{auto}
-if either @env{GCC_URLS} or @env{TERM_URLS} environment variables are
-present and non-empty in the environment of the compiler, or @samp{never}
-if neither are.
-
-However, even with @option{-fdiagnostics-urls=always} the behavior is
-dependent on those environment variables:
-If @env{GCC_URLS} is set to empty or @samp{no}, do not embed URLs in
-diagnostics. If set to @samp{st}, URLs use ST escape sequences.
-If set to @samp{bel}, the default, URLs use BEL escape sequences.
-Any other non-empty value enables the feature.
-If @env{GCC_URLS} is not set, use @env{TERM_URLS} as a fallback.
-Note: ST is an ANSI escape sequence, string terminator @samp{ESC \},
-BEL is an ASCII character, CTRL-G that usually sounds like a beep.
-
-At this time GCC tries to detect also a few terminals that are known to
-not implement the URL feature, and have bugs or at least had bugs in
-some versions that are still in use, where the URL escapes are likely
-to misbehave, i.e. print garbage on the screen.
-That list is currently xfce4-terminal, certain known to be buggy
-gnome-terminal versions, the linux console, and mingw.
-This check can be skipped with the @option{-fdiagnostics-urls=always}.
-
-@item -fno-diagnostics-show-option
-@opindex fno-diagnostics-show-option
-@opindex fdiagnostics-show-option
-By default, each diagnostic emitted includes text indicating the
-command-line option that directly controls the diagnostic (if such an
-option is known to the diagnostic machinery). Specifying the
-@option{-fno-diagnostics-show-option} flag suppresses that behavior.
-
-@item -fno-diagnostics-show-caret
-@opindex fno-diagnostics-show-caret
-@opindex fdiagnostics-show-caret
-By default, each diagnostic emitted includes the original source line
-and a caret @samp{^} indicating the column. This option suppresses this
-information. The source line is truncated to @var{n} characters, if
-the @option{-fmessage-length=n} option is given. When the output is done
-to the terminal, the width is limited to the width given by the
-@env{COLUMNS} environment variable or, if not set, to the terminal width.
-
-@item -fno-diagnostics-show-labels
-@opindex fno-diagnostics-show-labels
-@opindex fdiagnostics-show-labels
-By default, when printing source code (via @option{-fdiagnostics-show-caret}),
-diagnostics can label ranges of source code with pertinent information, such
-as the types of expressions:
-
-@smallexample
- printf ("foo %s bar", long_i + long_j);
- ~^ ~~~~~~~~~~~~~~~
- | |
- char * long int
-@end smallexample
-
-This option suppresses the printing of these labels (in the example above,
-the vertical bars and the ``char *'' and ``long int'' text).
-
-@item -fno-diagnostics-show-cwe
-@opindex fno-diagnostics-show-cwe
-@opindex fdiagnostics-show-cwe
-Diagnostic messages can optionally have an associated
-@uref{https://cwe.mitre.org/index.html, CWE} identifier.
-GCC itself only provides such metadata for some of the @option{-fanalyzer}
-diagnostics. GCC plugins may also provide diagnostics with such metadata.
-By default, if this information is present, it will be printed with
-the diagnostic. This option suppresses the printing of this metadata.
-
-@item -fno-diagnostics-show-rules
-@opindex fno-diagnostics-show-rules
-@opindex fdiagnostics-show-rules
-Diagnostic messages can optionally have rules associated with them, such
-as from a coding standard, or a specification.
-GCC itself does not do this for any of its diagnostics, but plugins may do so.
-By default, if this information is present, it will be printed with
-the diagnostic. This option suppresses the printing of this metadata.
-
-@item -fno-diagnostics-show-line-numbers
-@opindex fno-diagnostics-show-line-numbers
-@opindex fdiagnostics-show-line-numbers
-By default, when printing source code (via @option{-fdiagnostics-show-caret}),
-a left margin is printed, showing line numbers. This option suppresses this
-left margin.
-
-@item -fdiagnostics-minimum-margin-width=@var{width}
-@opindex fdiagnostics-minimum-margin-width
-This option controls the minimum width of the left margin printed by
-@option{-fdiagnostics-show-line-numbers}. It defaults to 6.
-
-@item -fdiagnostics-parseable-fixits
-@opindex fdiagnostics-parseable-fixits
-Emit fix-it hints in a machine-parseable format, suitable for consumption
-by IDEs. For each fix-it, a line will be printed after the relevant
-diagnostic, starting with the string ``fix-it:''. For example:
-
-@smallexample
-fix-it:"test.c":@{45:3-45:21@}:"gtk_widget_show_all"
-@end smallexample
-
-The location is expressed as a half-open range, expressed as a count of
-bytes, starting at byte 1 for the initial column. In the above example,
-bytes 3 through 20 of line 45 of ``test.c'' are to be replaced with the
-given string:
-
-@smallexample
-00000000011111111112222222222
-12345678901234567890123456789
- gtk_widget_showall (dlg);
- ^^^^^^^^^^^^^^^^^^
- gtk_widget_show_all
-@end smallexample
-
-The filename and replacement string escape backslash as ``\\", tab as ``\t'',
-newline as ``\n'', double quotes as ``\"'', non-printable characters as octal
-(e.g. vertical tab as ``\013'').
-
-An empty replacement string indicates that the given range is to be removed.
-An empty range (e.g. ``45:3-45:3'') indicates that the string is to
-be inserted at the given position.
-
-@item -fdiagnostics-generate-patch
-@opindex fdiagnostics-generate-patch
-Print fix-it hints to stderr in unified diff format, after any diagnostics
-are printed. For example:
-
-@smallexample
---- test.c
-+++ test.c
-@@ -42,5 +42,5 @@
-
- void show_cb(GtkDialog *dlg)
- @{
-- gtk_widget_showall(dlg);
-+ gtk_widget_show_all(dlg);
- @}
-
-@end smallexample
-
-The diff may or may not be colorized, following the same rules
-as for diagnostics (see @option{-fdiagnostics-color}).
-
-@item -fdiagnostics-show-template-tree
-@opindex fdiagnostics-show-template-tree
-
-In the C++ frontend, when printing diagnostics showing mismatching
-template types, such as:
-
-@smallexample
- could not convert 'std::map<int, std::vector<double> >()'
- from 'map<[...],vector<double>>' to 'map<[...],vector<float>>
-@end smallexample
-
-the @option{-fdiagnostics-show-template-tree} flag enables printing a
-tree-like structure showing the common and differing parts of the types,
-such as:
-
-@smallexample
- map<
- [...],
- vector<
- [double != float]>>
-@end smallexample
-
-The parts that differ are highlighted with color (``double'' and
-``float'' in this case).
-
-@item -fno-elide-type
-@opindex fno-elide-type
-@opindex felide-type
-By default when the C++ frontend prints diagnostics showing mismatching
-template types, common parts of the types are printed as ``[...]'' to
-simplify the error message. For example:
-
-@smallexample
- could not convert 'std::map<int, std::vector<double> >()'
- from 'map<[...],vector<double>>' to 'map<[...],vector<float>>
-@end smallexample
-
-Specifying the @option{-fno-elide-type} flag suppresses that behavior.
-This flag also affects the output of the
-@option{-fdiagnostics-show-template-tree} flag.
-
-@item -fdiagnostics-path-format=@var{KIND}
-@opindex fdiagnostics-path-format
-Specify how to print paths of control-flow events for diagnostics that
-have such a path associated with them.
-
-@var{KIND} is @samp{none}, @samp{separate-events}, or @samp{inline-events},
-the default.
-
-@samp{none} means to not print diagnostic paths.
-
-@samp{separate-events} means to print a separate ``note'' diagnostic for
-each event within the diagnostic. For example:
-
-@smallexample
-test.c:29:5: error: passing NULL as argument 1 to 'PyList_Append' which requires a non-NULL parameter
-test.c:25:10: note: (1) when 'PyList_New' fails, returning NULL
-test.c:27:3: note: (2) when 'i < count'
-test.c:29:5: note: (3) when calling 'PyList_Append', passing NULL from (1) as argument 1
-@end smallexample
-
-@samp{inline-events} means to print the events ``inline'' within the source
-code. This view attempts to consolidate the events into runs of
-sufficiently-close events, printing them as labelled ranges within the source.
-
-For example, the same events as above might be printed as:
-
-@smallexample
- 'test': events 1-3
- |
- | 25 | list = PyList_New(0);
- | | ^~~~~~~~~~~~~
- | | |
- | | (1) when 'PyList_New' fails, returning NULL
- | 26 |
- | 27 | for (i = 0; i < count; i++) @{
- | | ~~~
- | | |
- | | (2) when 'i < count'
- | 28 | item = PyLong_FromLong(random());
- | 29 | PyList_Append(list, item);
- | | ~~~~~~~~~~~~~~~~~~~~~~~~~
- | | |
- | | (3) when calling 'PyList_Append', passing NULL from (1) as argument 1
- |
-@end smallexample
-
-Interprocedural control flow is shown by grouping the events by stack frame,
-and using indentation to show how stack frames are nested, pushed, and popped.
-
-For example:
-
-@smallexample
- 'test': events 1-2
- |
- | 133 | @{
- | | ^
- | | |
- | | (1) entering 'test'
- | 134 | boxed_int *obj = make_boxed_int (i);
- | | ~~~~~~~~~~~~~~~~~~
- | | |
- | | (2) calling 'make_boxed_int'
- |
- +--> 'make_boxed_int': events 3-4
- |
- | 120 | @{
- | | ^
- | | |
- | | (3) entering 'make_boxed_int'
- | 121 | boxed_int *result = (boxed_int *)wrapped_malloc (sizeof (boxed_int));
- | | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- | | |
- | | (4) calling 'wrapped_malloc'
- |
- +--> 'wrapped_malloc': events 5-6
- |
- | 7 | @{
- | | ^
- | | |
- | | (5) entering 'wrapped_malloc'
- | 8 | return malloc (size);
- | | ~~~~~~~~~~~~~
- | | |
- | | (6) calling 'malloc'
- |
- <-------------+
- |
- 'test': event 7
- |
- | 138 | free_boxed_int (obj);
- | | ^~~~~~~~~~~~~~~~~~~~
- | | |
- | | (7) calling 'free_boxed_int'
- |
-(etc)
-@end smallexample
-
-@item -fdiagnostics-show-path-depths
-@opindex fdiagnostics-show-path-depths
-This option provides additional information when printing control-flow paths
-associated with a diagnostic.
-
-If this is option is provided then the stack depth will be printed for
-each run of events within @option{-fdiagnostics-path-format=inline-events}.
-If provided with @option{-fdiagnostics-path-format=separate-events}, then
-the stack depth and function declaration will be appended when printing
-each event.
-
-This is intended for use by GCC developers and plugin developers when
-debugging diagnostics that report interprocedural control flow.
-
-@item -fno-show-column
-@opindex fno-show-column
-@opindex fshow-column
-Do not print column numbers in diagnostics. This may be necessary if
-diagnostics are being scanned by a program that does not understand the
-column numbers, such as @command{dejagnu}.
-
-@item -fdiagnostics-column-unit=@var{UNIT}
-@opindex fdiagnostics-column-unit
-Select the units for the column number. This affects traditional diagnostics
-(in the absence of @option{-fno-show-column}), as well as JSON format
-diagnostics if requested.
-
-The default @var{UNIT}, @samp{display}, considers the number of display
-columns occupied by each character. This may be larger than the number
-of bytes required to encode the character, in the case of tab
-characters, or it may be smaller, in the case of multibyte characters.
-For example, the character ``GREEK SMALL LETTER PI (U+03C0)'' occupies one
-display column, and its UTF-8 encoding requires two bytes; the character
-``SLIGHTLY SMILING FACE (U+1F642)'' occupies two display columns, and
-its UTF-8 encoding requires four bytes.
-
-Setting @var{UNIT} to @samp{byte} changes the column number to the raw byte
-count in all cases, as was traditionally output by GCC prior to version 11.1.0.
-
-@item -fdiagnostics-column-origin=@var{ORIGIN}
-@opindex fdiagnostics-column-origin
-Select the origin for column numbers, i.e. the column number assigned to the
-first column. The default value of 1 corresponds to traditional GCC
-behavior and to the GNU style guide. Some utilities may perform better with an
-origin of 0; any non-negative value may be specified.
-
-@item -fdiagnostics-escape-format=@var{FORMAT}
-@opindex fdiagnostics-escape-format
-When GCC prints pertinent source lines for a diagnostic it normally attempts
-to print the source bytes directly. However, some diagnostics relate to encoding
-issues in the source file, such as malformed UTF-8, or issues with Unicode
-normalization. These diagnostics are flagged so that GCC will escape bytes
-that are not printable ASCII when printing their pertinent source lines.
-
-This option controls how such bytes should be escaped.
-
-The default @var{FORMAT}, @samp{unicode} displays Unicode characters that
-are not printable ASCII in the form @samp{<U+XXXX>}, and bytes that do not
-correspond to a Unicode character validly-encoded in UTF-8-encoded will be
-displayed as hexadecimal in the form @samp{<XX>}.
-
-For example, a source line containing the string @samp{before} followed by the
-Unicode character U+03C0 (``GREEK SMALL LETTER PI'', with UTF-8 encoding
-0xCF 0x80) followed by the byte 0xBF (a stray UTF-8 trailing byte), followed by
-the string @samp{after} will be printed for such a diagnostic as:
-
-@smallexample
- before<U+03C0><BF>after
-@end smallexample
-
-Setting @var{FORMAT} to @samp{bytes} will display all non-printable-ASCII bytes
-in the form @samp{<XX>}, thus showing the underlying encoding of non-ASCII
-Unicode characters. For the example above, the following will be printed:
-
-@smallexample
- before<CF><80><BF>after
-@end smallexample
-
-@item -fdiagnostics-format=@var{FORMAT}
-@opindex fdiagnostics-format
-Select a different format for printing diagnostics.
-@var{FORMAT} is @samp{text}, @samp{sarif-stderr}, @samp{sarif-file},
-@samp{json}, @samp{json-stderr}, or @samp{json-file}.
-
-The default is @samp{text}.
-
-The @samp{sarif-stderr} and @samp{sarif-file} formats both emit
-diagnostics in SARIF Version 2.1.0 format, either to stderr, or to a file
-named @file{@var{source}.sarif}, respectively.
-
-The @samp{json} format is a synonym for @samp{json-stderr}.
-The @samp{json-stderr} and @samp{json-file} formats are identical, apart from
-where the JSON is emitted to - with the former, the JSON is emitted to stderr,
-whereas with @samp{json-file} it is written to @file{@var{source}.gcc.json}.
-
-The emitted JSON consists of a top-level JSON array containing JSON objects
-representing the diagnostics. The JSON is emitted as one line, without
-formatting; the examples below have been formatted for clarity.
-
-Diagnostics can have child diagnostics. For example, this error and note:
-
-@smallexample
-misleading-indentation.c:15:3: warning: this 'if' clause does not
- guard... [-Wmisleading-indentation]
- 15 | if (flag)
- | ^~
-misleading-indentation.c:17:5: note: ...this statement, but the latter
- is misleadingly indented as if it were guarded by the 'if'
- 17 | y = 2;
- | ^
-@end smallexample
-
-@noindent
-might be printed in JSON form (after formatting) like this:
-
-@smallexample
-[
- @{
- "kind": "warning",
- "locations": [
- @{
- "caret": @{
- "display-column": 3,
- "byte-column": 3,
- "column": 3,
- "file": "misleading-indentation.c",
- "line": 15
- @},
- "finish": @{
- "display-column": 4,
- "byte-column": 4,
- "column": 4,
- "file": "misleading-indentation.c",
- "line": 15
- @}
- @}
- ],
- "message": "this \u2018if\u2019 clause does not guard...",
- "option": "-Wmisleading-indentation",
- "option_url": "https://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html#index-Wmisleading-indentation",
- "children": [
- @{
- "kind": "note",
- "locations": [
- @{
- "caret": @{
- "display-column": 5,
- "byte-column": 5,
- "column": 5,
- "file": "misleading-indentation.c",
- "line": 17
- @}
- @}
- ],
- "escape-source": false,
- "message": "...this statement, but the latter is @dots{}"
- @}
- ]
- "escape-source": false,
- "column-origin": 1,
- @}
-]
-@end smallexample
-
-@noindent
-where the @code{note} is a child of the @code{warning}.
-
-A diagnostic has a @code{kind}. If this is @code{warning}, then there is
-an @code{option} key describing the command-line option controlling the
-warning.
-
-A diagnostic can contain zero or more locations. Each location has an
-optional @code{label} string and up to three positions within it: a
-@code{caret} position and optional @code{start} and @code{finish} positions.
-A position is described by a @code{file} name, a @code{line} number, and
-three numbers indicating a column position:
-@itemize @bullet
-
-@item
-@code{display-column} counts display columns, accounting for tabs and
-multibyte characters.
-
-@item
-@code{byte-column} counts raw bytes.
-
-@item
-@code{column} is equal to one of
-the previous two, as dictated by the @option{-fdiagnostics-column-unit}
-option.
-
-@end itemize
-All three columns are relative to the origin specified by
-@option{-fdiagnostics-column-origin}, which is typically equal to 1 but may
-be set, for instance, to 0 for compatibility with other utilities that
-number columns from 0. The column origin is recorded in the JSON output in
-the @code{column-origin} tag. In the remaining examples below, the extra
-column number outputs have been omitted for brevity.
-
-For example, this error:
-
-@smallexample
-bad-binary-ops.c:64:23: error: invalid operands to binary + (have 'S' @{aka
- 'struct s'@} and 'T' @{aka 'struct t'@})
- 64 | return callee_4a () + callee_4b ();
- | ~~~~~~~~~~~~ ^ ~~~~~~~~~~~~
- | | |
- | | T @{aka struct t@}
- | S @{aka struct s@}
-@end smallexample
-
-@noindent
-has three locations. Its primary location is at the ``+'' token at column
-23. It has two secondary locations, describing the left and right-hand sides
-of the expression, which have labels. It might be printed in JSON form as:
-
-@smallexample
- @{
- "children": [],
- "kind": "error",
- "locations": [
- @{
- "caret": @{
- "column": 23, "file": "bad-binary-ops.c", "line": 64
- @}
- @},
- @{
- "caret": @{
- "column": 10, "file": "bad-binary-ops.c", "line": 64
- @},
- "finish": @{
- "column": 21, "file": "bad-binary-ops.c", "line": 64
- @},
- "label": "S @{aka struct s@}"
- @},
- @{
- "caret": @{
- "column": 25, "file": "bad-binary-ops.c", "line": 64
- @},
- "finish": @{
- "column": 36, "file": "bad-binary-ops.c", "line": 64
- @},
- "label": "T @{aka struct t@}"
- @}
- ],
- "escape-source": false,
- "message": "invalid operands to binary + @dots{}"
- @}
-@end smallexample
-
-If a diagnostic contains fix-it hints, it has a @code{fixits} array,
-consisting of half-open intervals, similar to the output of
-@option{-fdiagnostics-parseable-fixits}. For example, this diagnostic
-with a replacement fix-it hint:
-
-@smallexample
-demo.c:8:15: error: 'struct s' has no member named 'colour'; did you
- mean 'color'?
- 8 | return ptr->colour;
- | ^~~~~~
- | color
-@end smallexample
-
-@noindent
-might be printed in JSON form as:
-
-@smallexample
- @{
- "children": [],
- "fixits": [
- @{
- "next": @{
- "column": 21,
- "file": "demo.c",
- "line": 8
- @},
- "start": @{
- "column": 15,
- "file": "demo.c",
- "line": 8
- @},
- "string": "color"
- @}
- ],
- "kind": "error",
- "locations": [
- @{
- "caret": @{
- "column": 15,
- "file": "demo.c",
- "line": 8
- @},
- "finish": @{
- "column": 20,
- "file": "demo.c",
- "line": 8
- @}
- @}
- ],
- "escape-source": false,
- "message": "\u2018struct s\u2019 has no member named @dots{}"
- @}
-@end smallexample
-
-@noindent
-where the fix-it hint suggests replacing the text from @code{start} up
-to but not including @code{next} with @code{string}'s value. Deletions
-are expressed via an empty value for @code{string}, insertions by
-having @code{start} equal @code{next}.
-
-If the diagnostic has a path of control-flow events associated with it,
-it has a @code{path} array of objects representing the events. Each
-event object has a @code{description} string, a @code{location} object,
-along with a @code{function} string and a @code{depth} number for
-representing interprocedural paths. The @code{function} represents the
-current function at that event, and the @code{depth} represents the
-stack depth relative to some baseline: the higher, the more frames are
-within the stack.
-
-For example, the intraprocedural example shown for
-@option{-fdiagnostics-path-format=} might have this JSON for its path:
-
-@smallexample
- "path": [
- @{
- "depth": 0,
- "description": "when 'PyList_New' fails, returning NULL",
- "function": "test",
- "location": @{
- "column": 10,
- "file": "test.c",
- "line": 25
- @}
- @},
- @{
- "depth": 0,
- "description": "when 'i < count'",
- "function": "test",
- "location": @{
- "column": 3,
- "file": "test.c",
- "line": 27
- @}
- @},
- @{
- "depth": 0,
- "description": "when calling 'PyList_Append', passing NULL from (1) as argument 1",
- "function": "test",
- "location": @{
- "column": 5,
- "file": "test.c",
- "line": 29
- @}
- @}
- ]
-@end smallexample
-
-Diagnostics have a boolean attribute @code{escape-source}, hinting whether
-non-ASCII bytes should be escaped when printing the pertinent lines of
-source code (@code{true} for diagnostics involving source encoding issues).
-
-@end table
-
-@node Warning Options
-@section Options to Request or Suppress Warnings
-@cindex options to control warnings
-@cindex warning messages
-@cindex messages, warning
-@cindex suppressing warnings
-
-Warnings are diagnostic messages that report constructions that
-are not inherently erroneous but that are risky or suggest there
-may have been an error.
-
-The following language-independent options do not enable specific
-warnings but control the kinds of diagnostics produced by GCC@.
-
-@table @gcctabopt
-@cindex syntax checking
-@item -fsyntax-only
-@opindex fsyntax-only
-Check the code for syntax errors, but don't do anything beyond that.
-
-@item -fmax-errors=@var{n}
-@opindex fmax-errors
-Limits the maximum number of error messages to @var{n}, at which point
-GCC bails out rather than attempting to continue processing the source
-code. If @var{n} is 0 (the default), there is no limit on the number
-of error messages produced. If @option{-Wfatal-errors} is also
-specified, then @option{-Wfatal-errors} takes precedence over this
-option.
-
-@item -w
-@opindex w
-Inhibit all warning messages.
-
-@item -Werror
-@opindex Werror
-@opindex Wno-error
-Make all warnings into errors.
-
-@item -Werror=
-@opindex Werror=
-@opindex Wno-error=
-Make the specified warning into an error. The specifier for a warning
-is appended; for example @option{-Werror=switch} turns the warnings
-controlled by @option{-Wswitch} into errors. This switch takes a
-negative form, to be used to negate @option{-Werror} for specific
-warnings; for example @option{-Wno-error=switch} makes
-@option{-Wswitch} warnings not be errors, even when @option{-Werror}
-is in effect.
-
-The warning message for each controllable warning includes the
-option that controls the warning. That option can then be used with
-@option{-Werror=} and @option{-Wno-error=} as described above.
-(Printing of the option in the warning message can be disabled using the
-@option{-fno-diagnostics-show-option} flag.)
-
-Note that specifying @option{-Werror=}@var{foo} automatically implies
-@option{-W}@var{foo}. However, @option{-Wno-error=}@var{foo} does not
-imply anything.
-
-@item -Wfatal-errors
-@opindex Wfatal-errors
-@opindex Wno-fatal-errors
-This option causes the compiler to abort compilation on the first error
-occurred rather than trying to keep going and printing further error
-messages.
-
-@end table
-
-You can request many specific warnings with options beginning with
-@samp{-W}, for example @option{-Wimplicit} to request warnings on
-implicit declarations. Each of these specific warning options also
-has a negative form beginning @samp{-Wno-} to turn off warnings; for
-example, @option{-Wno-implicit}. This manual lists only one of the
-two forms, whichever is not the default. For further
-language-specific options also refer to @ref{C++ Dialect Options} and
-@ref{Objective-C and Objective-C++ Dialect Options}.
-Additional warnings can be produced by enabling the static analyzer;
-@xref{Static Analyzer Options}.
-
-Some options, such as @option{-Wall} and @option{-Wextra}, turn on other
-options, such as @option{-Wunused}, which may turn on further options,
-such as @option{-Wunused-value}. The combined effect of positive and
-negative forms is that more specific options have priority over less
-specific ones, independently of their position in the command-line. For
-options of the same specificity, the last one takes effect. Options
-enabled or disabled via pragmas (@pxref{Diagnostic Pragmas}) take effect
-as if they appeared at the end of the command-line.
-
-When an unrecognized warning option is requested (e.g.,
-@option{-Wunknown-warning}), GCC emits a diagnostic stating
-that the option is not recognized. However, if the @option{-Wno-} form
-is used, the behavior is slightly different: no diagnostic is
-produced for @option{-Wno-unknown-warning} unless other diagnostics
-are being produced. This allows the use of new @option{-Wno-} options
-with old compilers, but if something goes wrong, the compiler
-warns that an unrecognized option is present.
-
-The effectiveness of some warnings depends on optimizations also being
-enabled. For example @option{-Wsuggest-final-types} is more effective
-with link-time optimization and some instances of other warnings may
-not be issued at all unless optimization is enabled. While optimization
-in general improves the efficacy of control and data flow sensitive
-warnings, in some cases it may also cause false positives.
-
-@table @gcctabopt
-@item -Wpedantic
-@itemx -pedantic
-@opindex pedantic
-@opindex Wpedantic
-@opindex Wno-pedantic
-Issue all the warnings demanded by strict ISO C and ISO C++;
-reject all programs that use forbidden extensions, and some other
-programs that do not follow ISO C and ISO C++. For ISO C, follows the
-version of the ISO C standard specified by any @option{-std} option used.
-
-Valid ISO C and ISO C++ programs should compile properly with or without
-this option (though a rare few require @option{-ansi} or a
-@option{-std} option specifying the required version of ISO C)@. However,
-without this option, certain GNU extensions and traditional C and C++
-features are supported as well. With this option, they are rejected.
-
-@option{-Wpedantic} does not cause warning messages for use of the
-alternate keywords whose names begin and end with @samp{__}. This alternate
-format can also be used to disable warnings for non-ISO @samp{__intN} types,
-i.e. @samp{__intN__}.
-Pedantic warnings are also disabled in the expression that follows
-@code{__extension__}. However, only system header files should use
-these escape routes; application programs should avoid them.
-@xref{Alternate Keywords}.
-
-Some users try to use @option{-Wpedantic} to check programs for strict ISO
-C conformance. They soon find that it does not do quite what they want:
-it finds some non-ISO practices, but not all---only those for which
-ISO C @emph{requires} a diagnostic, and some others for which
-diagnostics have been added.
-
-A feature to report any failure to conform to ISO C might be useful in
-some instances, but would require considerable additional work and would
-be quite different from @option{-Wpedantic}. We don't have plans to
-support such a feature in the near future.
-
-Where the standard specified with @option{-std} represents a GNU
-extended dialect of C, such as @samp{gnu90} or @samp{gnu99}, there is a
-corresponding @dfn{base standard}, the version of ISO C on which the GNU
-extended dialect is based. Warnings from @option{-Wpedantic} are given
-where they are required by the base standard. (It does not make sense
-for such warnings to be given only for features not in the specified GNU
-C dialect, since by definition the GNU dialects of C include all
-features the compiler supports with the given option, and there would be
-nothing to warn about.)
-
-@item -pedantic-errors
-@opindex pedantic-errors
-Give an error whenever the @dfn{base standard} (see @option{-Wpedantic})
-requires a diagnostic, in some cases where there is undefined behavior
-at compile-time and in some other cases that do not prevent compilation
-of programs that are valid according to the standard. This is not
-equivalent to @option{-Werror=pedantic}, since there are errors enabled
-by this option and not enabled by the latter and vice versa.
-
-@item -Wall
-@opindex Wall
-@opindex Wno-all
-This enables all the warnings about constructions that some users
-consider questionable, and that are easy to avoid (or modify to
-prevent the warning), even in conjunction with macros. This also
-enables some language-specific warnings described in @ref{C++ Dialect
-Options} and @ref{Objective-C and Objective-C++ Dialect Options}.
-
-@option{-Wall} turns on the following warning flags:
-
-@gccoptlist{-Waddress @gol
--Warray-bounds=1 @r{(only with} @option{-O2}@r{)} @gol
--Warray-compare @gol
--Warray-parameter=2 @r{(C and Objective-C only)} @gol
--Wbool-compare @gol
--Wbool-operation @gol
--Wc++11-compat -Wc++14-compat @gol
--Wcatch-value @r{(C++ and Objective-C++ only)} @gol
--Wchar-subscripts @gol
--Wcomment @gol
--Wdangling-pointer=2 @gol
--Wduplicate-decl-specifier @r{(C and Objective-C only)} @gol
--Wenum-compare @r{(in C/ObjC; this is on by default in C++)} @gol
--Wenum-int-mismatch @r{(C and Objective-C only)} @gol
--Wformat @gol
--Wformat-overflow @gol
--Wformat-truncation @gol
--Wint-in-bool-context @gol
--Wimplicit @r{(C and Objective-C only)} @gol
--Wimplicit-int @r{(C and Objective-C only)} @gol
--Wimplicit-function-declaration @r{(C and Objective-C only)} @gol
--Winit-self @r{(only for C++)} @gol
--Wlogical-not-parentheses @gol
--Wmain @r{(only for C/ObjC and unless} @option{-ffreestanding}@r{)} @gol
--Wmaybe-uninitialized @gol
--Wmemset-elt-size @gol
--Wmemset-transposed-args @gol
--Wmisleading-indentation @r{(only for C/C++)} @gol
--Wmismatched-dealloc @gol
--Wmismatched-new-delete @r{(only for C/C++)} @gol
--Wmissing-attributes @gol
--Wmissing-braces @r{(only for C/ObjC)} @gol
--Wmultistatement-macros @gol
--Wnarrowing @r{(only for C++)} @gol
--Wnonnull @gol
--Wnonnull-compare @gol
--Wopenmp-simd @gol
--Wparentheses @gol
--Wpessimizing-move @r{(only for C++)} @gol
--Wpointer-sign @gol
--Wrange-loop-construct @r{(only for C++)} @gol
--Wreorder @gol
--Wrestrict @gol
--Wreturn-type @gol
--Wself-move @r{(only for C++)} @gol
--Wsequence-point @gol
--Wsign-compare @r{(only in C++)} @gol
--Wsizeof-array-div @gol
--Wsizeof-pointer-div @gol
--Wsizeof-pointer-memaccess @gol
--Wstrict-aliasing @gol
--Wstrict-overflow=1 @gol
--Wswitch @gol
--Wtautological-compare @gol
--Wtrigraphs @gol
--Wuninitialized @gol
--Wunknown-pragmas @gol
--Wunused-function @gol
--Wunused-label @gol
--Wunused-value @gol
--Wunused-variable @gol
--Wuse-after-free=3 @gol
--Wvla-parameter @r{(C and Objective-C only)} @gol
--Wvolatile-register-var @gol
--Wzero-length-bounds}
-
-Note that some warning flags are not implied by @option{-Wall}. Some of
-them warn about constructions that users generally do not consider
-questionable, but which occasionally you might wish to check for;
-others warn about constructions that are necessary or hard to avoid in
-some cases, and there is no simple way to modify the code to suppress
-the warning. Some of them are enabled by @option{-Wextra} but many of
-them must be enabled individually.
-
-@item -Wextra
-@opindex W
-@opindex Wextra
-@opindex Wno-extra
-This enables some extra warning flags that are not enabled by
-@option{-Wall}. (This option used to be called @option{-W}. The older
-name is still supported, but the newer name is more descriptive.)
-
-@gccoptlist{-Wclobbered @gol
--Wcast-function-type @gol
--Wdeprecated-copy @r{(C++ only)} @gol
--Wempty-body @gol
--Wenum-conversion @r{(C only)} @gol
--Wignored-qualifiers @gol
--Wimplicit-fallthrough=3 @gol
--Wmissing-field-initializers @gol
--Wmissing-parameter-type @r{(C only)} @gol
--Wold-style-declaration @r{(C only)} @gol
--Woverride-init @gol
--Wsign-compare @r{(C only)} @gol
--Wstring-compare @gol
--Wredundant-move @r{(only for C++)} @gol
--Wtype-limits @gol
--Wuninitialized @gol
--Wshift-negative-value @r{(in C++11 to C++17 and in C99 and newer)} @gol
--Wunused-parameter @r{(only with} @option{-Wunused} @r{or} @option{-Wall}@r{)} @gol
--Wunused-but-set-parameter @r{(only with} @option{-Wunused} @r{or} @option{-Wall}@r{)}}
-
-
-The option @option{-Wextra} also prints warning messages for the
-following cases:
-
-@itemize @bullet
-
-@item
-A pointer is compared against integer zero with @code{<}, @code{<=},
-@code{>}, or @code{>=}.
-
-@item
-(C++ only) An enumerator and a non-enumerator both appear in a
-conditional expression.
-
-@item
-(C++ only) Ambiguous virtual bases.
-
-@item
-(C++ only) Subscripting an array that has been declared @code{register}.
-
-@item
-(C++ only) Taking the address of a variable that has been declared
-@code{register}.
-
-@item
-(C++ only) A base class is not initialized in the copy constructor
-of a derived class.
-
-@end itemize
-
-@item -Wabi @r{(C, Objective-C, C++ and Objective-C++ only)}
-@opindex Wabi
-@opindex Wno-abi
-
-Warn about code affected by ABI changes. This includes code that may
-not be compatible with the vendor-neutral C++ ABI as well as the psABI
-for the particular target.
-
-Since G++ now defaults to updating the ABI with each major release,
-normally @option{-Wabi} warns only about C++ ABI compatibility
-problems if there is a check added later in a release series for an
-ABI issue discovered since the initial release. @option{-Wabi} warns
-about more things if an older ABI version is selected (with
-@option{-fabi-version=@var{n}}).
-
-@option{-Wabi} can also be used with an explicit version number to
-warn about C++ ABI compatibility with a particular @option{-fabi-version}
-level, e.g.@: @option{-Wabi=2} to warn about changes relative to
-@option{-fabi-version=2}.
-
-If an explicit version number is provided and
-@option{-fabi-compat-version} is not specified, the version number
-from this option is used for compatibility aliases. If no explicit
-version number is provided with this option, but
-@option{-fabi-compat-version} is specified, that version number is
-used for C++ ABI warnings.
-
-Although an effort has been made to warn about
-all such cases, there are probably some cases that are not warned about,
-even though G++ is generating incompatible code. There may also be
-cases where warnings are emitted even though the code that is generated
-is compatible.
-
-You should rewrite your code to avoid these warnings if you are
-concerned about the fact that code generated by G++ may not be binary
-compatible with code generated by other compilers.
-
-Known incompatibilities in @option{-fabi-version=2} (which was the
-default from GCC 3.4 to 4.9) include:
-
-@itemize @bullet
-
-@item
-A template with a non-type template parameter of reference type was
-mangled incorrectly:
-@smallexample
-extern int N;
-template <int &> struct S @{@};
-void n (S<N>) @{2@}
-@end smallexample
-
-This was fixed in @option{-fabi-version=3}.
-
-@item
-SIMD vector types declared using @code{__attribute ((vector_size))} were
-mangled in a non-standard way that does not allow for overloading of
-functions taking vectors of different sizes.
-
-The mangling was changed in @option{-fabi-version=4}.
-
-@item
-@code{__attribute ((const))} and @code{noreturn} were mangled as type
-qualifiers, and @code{decltype} of a plain declaration was folded away.
-
-These mangling issues were fixed in @option{-fabi-version=5}.
-
-@item
-Scoped enumerators passed as arguments to a variadic function are
-promoted like unscoped enumerators, causing @code{va_arg} to complain.
-On most targets this does not actually affect the parameter passing
-ABI, as there is no way to pass an argument smaller than @code{int}.
-
-Also, the ABI changed the mangling of template argument packs,
-@code{const_cast}, @code{static_cast}, prefix increment/decrement, and
-a class scope function used as a template argument.
-
-These issues were corrected in @option{-fabi-version=6}.
-
-@item
-Lambdas in default argument scope were mangled incorrectly, and the
-ABI changed the mangling of @code{nullptr_t}.
-
-These issues were corrected in @option{-fabi-version=7}.
-
-@item
-When mangling a function type with function-cv-qualifiers, the
-un-qualified function type was incorrectly treated as a substitution
-candidate.
-
-This was fixed in @option{-fabi-version=8}, the default for GCC 5.1.
-
-@item
-@code{decltype(nullptr)} incorrectly had an alignment of 1, leading to
-unaligned accesses. Note that this did not affect the ABI of a
-function with a @code{nullptr_t} parameter, as parameters have a
-minimum alignment.
-
-This was fixed in @option{-fabi-version=9}, the default for GCC 5.2.
-
-@item
-Target-specific attributes that affect the identity of a type, such as
-ia32 calling conventions on a function type (stdcall, regparm, etc.),
-did not affect the mangled name, leading to name collisions when
-function pointers were used as template arguments.
-
-This was fixed in @option{-fabi-version=10}, the default for GCC 6.1.
-
-@end itemize
-
-This option also enables warnings about psABI-related changes.
-The known psABI changes at this point include:
-
-@itemize @bullet
-
-@item
-For SysV/x86-64, unions with @code{long double} members are
-passed in memory as specified in psABI. Prior to GCC 4.4, this was not
-the case. For example:
-
-@smallexample
-union U @{
- long double ld;
- int i;
-@};
-@end smallexample
-
-@noindent
-@code{union U} is now always passed in memory.
-
-@end itemize
-
-@item -Wchar-subscripts
-@opindex Wchar-subscripts
-@opindex Wno-char-subscripts
-Warn if an array subscript has type @code{char}. This is a common cause
-of error, as programmers often forget that this type is signed on some
-machines.
-This warning is enabled by @option{-Wall}.
-
-@item -Wno-coverage-mismatch
-@opindex Wno-coverage-mismatch
-@opindex Wcoverage-mismatch
-Warn if feedback profiles do not match when using the
-@option{-fprofile-use} option.
-If a source file is changed between compiling with @option{-fprofile-generate}
-and with @option{-fprofile-use}, the files with the profile feedback can fail
-to match the source file and GCC cannot use the profile feedback
-information. By default, this warning is enabled and is treated as an
-error. @option{-Wno-coverage-mismatch} can be used to disable the
-warning or @option{-Wno-error=coverage-mismatch} can be used to
-disable the error. Disabling the error for this warning can result in
-poorly optimized code and is useful only in the
-case of very minor changes such as bug fixes to an existing code-base.
-Completely disabling the warning is not recommended.
-
-@item -Wno-coverage-invalid-line-number
-@opindex Wno-coverage-invalid-line-number
-@opindex Wcoverage-invalid-line-number
-Warn in case a function ends earlier than it begins due
-to an invalid linenum macros. The warning is emitted only
-with @option{--coverage} enabled.
-
-By default, this warning is enabled and is treated as an
-error. @option{-Wno-coverage-invalid-line-number} can be used to disable the
-warning or @option{-Wno-error=coverage-invalid-line-number} can be used to
-disable the error.
-
-@item -Wno-cpp @r{(C, Objective-C, C++, Objective-C++ and Fortran only)}
-@opindex Wno-cpp
-@opindex Wcpp
-Suppress warning messages emitted by @code{#warning} directives.
-
-@item -Wdouble-promotion @r{(C, C++, Objective-C and Objective-C++ only)}
-@opindex Wdouble-promotion
-@opindex Wno-double-promotion
-Give a warning when a value of type @code{float} is implicitly
-promoted to @code{double}. CPUs with a 32-bit ``single-precision''
-floating-point unit implement @code{float} in hardware, but emulate
-@code{double} in software. On such a machine, doing computations
-using @code{double} values is much more expensive because of the
-overhead required for software emulation.
-
-It is easy to accidentally do computations with @code{double} because
-floating-point literals are implicitly of type @code{double}. For
-example, in:
-@smallexample
-@group
-float area(float radius)
-@{
- return 3.14159 * radius * radius;
-@}
-@end group
-@end smallexample
-the compiler performs the entire computation with @code{double}
-because the floating-point literal is a @code{double}.
-
-@item -Wduplicate-decl-specifier @r{(C and Objective-C only)}
-@opindex Wduplicate-decl-specifier
-@opindex Wno-duplicate-decl-specifier
-Warn if a declaration has duplicate @code{const}, @code{volatile},
-@code{restrict} or @code{_Atomic} specifier. This warning is enabled by
-@option{-Wall}.
-
-@item -Wformat
-@itemx -Wformat=@var{n}
-@opindex Wformat
-@opindex Wno-format
-@opindex ffreestanding
-@opindex fno-builtin
-@opindex Wformat=
-Check calls to @code{printf} and @code{scanf}, etc., to make sure that
-the arguments supplied have types appropriate to the format string
-specified, and that the conversions specified in the format string make
-sense. This includes standard functions, and others specified by format
-attributes (@pxref{Function Attributes}), in the @code{printf},
-@code{scanf}, @code{strftime} and @code{strfmon} (an X/Open extension,
-not in the C standard) families (or other target-specific families).
-Which functions are checked without format attributes having been
-specified depends on the standard version selected, and such checks of
-functions without the attribute specified are disabled by
-@option{-ffreestanding} or @option{-fno-builtin}.
-
-The formats are checked against the format features supported by GNU
-libc version 2.2. These include all ISO C90 and C99 features, as well
-as features from the Single Unix Specification and some BSD and GNU
-extensions. Other library implementations may not support all these
-features; GCC does not support warning about features that go beyond a
-particular library's limitations. However, if @option{-Wpedantic} is used
-with @option{-Wformat}, warnings are given about format features not
-in the selected standard version (but not for @code{strfmon} formats,
-since those are not in any version of the C standard). @xref{C Dialect
-Options,,Options Controlling C Dialect}.
-
-@table @gcctabopt
-@item -Wformat=1
-@itemx -Wformat
-@opindex Wformat
-@opindex Wformat=1
-Option @option{-Wformat} is equivalent to @option{-Wformat=1}, and
-@option{-Wno-format} is equivalent to @option{-Wformat=0}. Since
-@option{-Wformat} also checks for null format arguments for several
-functions, @option{-Wformat} also implies @option{-Wnonnull}. Some
-aspects of this level of format checking can be disabled by the
-options: @option{-Wno-format-contains-nul},
-@option{-Wno-format-extra-args}, and @option{-Wno-format-zero-length}.
-@option{-Wformat} is enabled by @option{-Wall}.
-
-@item -Wformat=2
-@opindex Wformat=2
-Enable @option{-Wformat} plus additional format checks. Currently
-equivalent to @option{-Wformat -Wformat-nonliteral -Wformat-security
--Wformat-y2k}.
-@end table
-
-@item -Wno-format-contains-nul
-@opindex Wno-format-contains-nul
-@opindex Wformat-contains-nul
-If @option{-Wformat} is specified, do not warn about format strings that
-contain NUL bytes.
-
-@item -Wno-format-extra-args
-@opindex Wno-format-extra-args
-@opindex Wformat-extra-args
-If @option{-Wformat} is specified, do not warn about excess arguments to a
-@code{printf} or @code{scanf} format function. The C standard specifies
-that such arguments are ignored.
-
-Where the unused arguments lie between used arguments that are
-specified with @samp{$} operand number specifications, normally
-warnings are still given, since the implementation could not know what
-type to pass to @code{va_arg} to skip the unused arguments. However,
-in the case of @code{scanf} formats, this option suppresses the
-warning if the unused arguments are all pointers, since the Single
-Unix Specification says that such unused arguments are allowed.
-
-@item -Wformat-overflow
-@itemx -Wformat-overflow=@var{level}
-@opindex Wformat-overflow
-@opindex Wno-format-overflow
-Warn about calls to formatted input/output functions such as @code{sprintf}
-and @code{vsprintf} that might overflow the destination buffer. When the
-exact number of bytes written by a format directive cannot be determined
-at compile-time it is estimated based on heuristics that depend on the
-@var{level} argument and on optimization. While enabling optimization
-will in most cases improve the accuracy of the warning, it may also
-result in false positives.
-
-@table @gcctabopt
-@item -Wformat-overflow
-@itemx -Wformat-overflow=1
-@opindex Wformat-overflow
-@opindex Wno-format-overflow
-Level @var{1} of @option{-Wformat-overflow} enabled by @option{-Wformat}
-employs a conservative approach that warns only about calls that most
-likely overflow the buffer. At this level, numeric arguments to format
-directives with unknown values are assumed to have the value of one, and
-strings of unknown length to be empty. Numeric arguments that are known
-to be bounded to a subrange of their type, or string arguments whose output
-is bounded either by their directive's precision or by a finite set of
-string literals, are assumed to take on the value within the range that
-results in the most bytes on output. For example, the call to @code{sprintf}
-below is diagnosed because even with both @var{a} and @var{b} equal to zero,
-the terminating NUL character (@code{'\0'}) appended by the function
-to the destination buffer will be written past its end. Increasing
-the size of the buffer by a single byte is sufficient to avoid the
-warning, though it may not be sufficient to avoid the overflow.
-
-@smallexample
-void f (int a, int b)
-@{
- char buf [13];
- sprintf (buf, "a = %i, b = %i\n", a, b);
-@}
-@end smallexample
-
-@item -Wformat-overflow=2
-Level @var{2} warns also about calls that might overflow the destination
-buffer given an argument of sufficient length or magnitude. At level
-@var{2}, unknown numeric arguments are assumed to have the minimum
-representable value for signed types with a precision greater than 1, and
-the maximum representable value otherwise. Unknown string arguments whose
-length cannot be assumed to be bounded either by the directive's precision,
-or by a finite set of string literals they may evaluate to, or the character
-array they may point to, are assumed to be 1 character long.
-
-At level @var{2}, the call in the example above is again diagnosed, but
-this time because with @var{a} equal to a 32-bit @code{INT_MIN} the first
-@code{%i} directive will write some of its digits beyond the end of
-the destination buffer. To make the call safe regardless of the values
-of the two variables, the size of the destination buffer must be increased
-to at least 34 bytes. GCC includes the minimum size of the buffer in
-an informational note following the warning.
-
-An alternative to increasing the size of the destination buffer is to
-constrain the range of formatted values. The maximum length of string
-arguments can be bounded by specifying the precision in the format
-directive. When numeric arguments of format directives can be assumed
-to be bounded by less than the precision of their type, choosing
-an appropriate length modifier to the format specifier will reduce
-the required buffer size. For example, if @var{a} and @var{b} in the
-example above can be assumed to be within the precision of
-the @code{short int} type then using either the @code{%hi} format
-directive or casting the argument to @code{short} reduces the maximum
-required size of the buffer to 24 bytes.
-
-@smallexample
-void f (int a, int b)
-@{
- char buf [23];
- sprintf (buf, "a = %hi, b = %i\n", a, (short)b);
-@}
-@end smallexample
-@end table
-
-@item -Wno-format-zero-length
-@opindex Wno-format-zero-length
-@opindex Wformat-zero-length
-If @option{-Wformat} is specified, do not warn about zero-length formats.
-The C standard specifies that zero-length formats are allowed.
-
-@item -Wformat-nonliteral
-@opindex Wformat-nonliteral
-@opindex Wno-format-nonliteral
-If @option{-Wformat} is specified, also warn if the format string is not a
-string literal and so cannot be checked, unless the format function
-takes its format arguments as a @code{va_list}.
-
-@item -Wformat-security
-@opindex Wformat-security
-@opindex Wno-format-security
-If @option{-Wformat} is specified, also warn about uses of format
-functions that represent possible security problems. At present, this
-warns about calls to @code{printf} and @code{scanf} functions where the
-format string is not a string literal and there are no format arguments,
-as in @code{printf (foo);}. This may be a security hole if the format
-string came from untrusted input and contains @samp{%n}. (This is
-currently a subset of what @option{-Wformat-nonliteral} warns about, but
-in future warnings may be added to @option{-Wformat-security} that are not
-included in @option{-Wformat-nonliteral}.)
-
-@item -Wformat-signedness
-@opindex Wformat-signedness
-@opindex Wno-format-signedness
-If @option{-Wformat} is specified, also warn if the format string
-requires an unsigned argument and the argument is signed and vice versa.
-
-@item -Wformat-truncation
-@itemx -Wformat-truncation=@var{level}
-@opindex Wformat-truncation
-@opindex Wno-format-truncation
-Warn about calls to formatted input/output functions such as @code{snprintf}
-and @code{vsnprintf} that might result in output truncation. When the exact
-number of bytes written by a format directive cannot be determined at
-compile-time it is estimated based on heuristics that depend on
-the @var{level} argument and on optimization. While enabling optimization
-will in most cases improve the accuracy of the warning, it may also result
-in false positives. Except as noted otherwise, the option uses the same
-logic @option{-Wformat-overflow}.
-
-@table @gcctabopt
-@item -Wformat-truncation
-@itemx -Wformat-truncation=1
-@opindex Wformat-truncation
-@opindex Wno-format-truncation
-Level @var{1} of @option{-Wformat-truncation} enabled by @option{-Wformat}
-employs a conservative approach that warns only about calls to bounded
-functions whose return value is unused and that will most likely result
-in output truncation.
-
-@item -Wformat-truncation=2
-Level @var{2} warns also about calls to bounded functions whose return
-value is used and that might result in truncation given an argument of
-sufficient length or magnitude.
-@end table
-
-@item -Wformat-y2k
-@opindex Wformat-y2k
-@opindex Wno-format-y2k
-If @option{-Wformat} is specified, also warn about @code{strftime}
-formats that may yield only a two-digit year.
-
-@item -Wnonnull
-@opindex Wnonnull
-@opindex Wno-nonnull
-Warn about passing a null pointer for arguments marked as
-requiring a non-null value by the @code{nonnull} function attribute.
-
-@option{-Wnonnull} is included in @option{-Wall} and @option{-Wformat}. It
-can be disabled with the @option{-Wno-nonnull} option.
-
-@item -Wnonnull-compare
-@opindex Wnonnull-compare
-@opindex Wno-nonnull-compare
-Warn when comparing an argument marked with the @code{nonnull}
-function attribute against null inside the function.
-
-@option{-Wnonnull-compare} is included in @option{-Wall}. It
-can be disabled with the @option{-Wno-nonnull-compare} option.
-
-@item -Wnull-dereference
-@opindex Wnull-dereference
-@opindex Wno-null-dereference
-Warn if the compiler detects paths that trigger erroneous or
-undefined behavior due to dereferencing a null pointer. This option
-is only active when @option{-fdelete-null-pointer-checks} is active,
-which is enabled by optimizations in most targets. The precision of
-the warnings depends on the optimization options used.
-
-@item -Winfinite-recursion
-@opindex Winfinite-recursion
-@opindex Wno-infinite-recursion
-Warn about infinitely recursive calls. The warning is effective at all
-optimization levels but requires optimization in order to detect infinite
-recursion in calls between two or more functions.
-@option{-Winfinite-recursion} is included in @option{-Wall}.
-
-@item -Winit-self @r{(C, C++, Objective-C and Objective-C++ only)}
-@opindex Winit-self
-@opindex Wno-init-self
-Warn about uninitialized variables that are initialized with themselves.
-Note this option can only be used with the @option{-Wuninitialized} option.
-
-For example, GCC warns about @code{i} being uninitialized in the
-following snippet only when @option{-Winit-self} has been specified:
-@smallexample
-@group
-int f()
-@{
- int i = i;
- return i;
-@}
-@end group
-@end smallexample
-
-This warning is enabled by @option{-Wall} in C++.
-
-@item -Wno-implicit-int @r{(C and Objective-C only)}
-@opindex Wimplicit-int
-@opindex Wno-implicit-int
-This option controls warnings when a declaration does not specify a type.
-This warning is enabled by default in C99 and later dialects of C,
-and also by @option{-Wall}.
-
-@item -Wno-implicit-function-declaration @r{(C and Objective-C only)}
-@opindex Wimplicit-function-declaration
-@opindex Wno-implicit-function-declaration
-This option controls warnings when a function is used before being declared.
-This warning is enabled by default in C99 and later dialects of C,
-and also by @option{-Wall}.
-The warning is made into an error by @option{-pedantic-errors}.
-
-@item -Wimplicit @r{(C and Objective-C only)}
-@opindex Wimplicit
-@opindex Wno-implicit
-Same as @option{-Wimplicit-int} and @option{-Wimplicit-function-declaration}.
-This warning is enabled by @option{-Wall}.
-
-@item -Wimplicit-fallthrough
-@opindex Wimplicit-fallthrough
-@opindex Wno-implicit-fallthrough
-@option{-Wimplicit-fallthrough} is the same as @option{-Wimplicit-fallthrough=3}
-and @option{-Wno-implicit-fallthrough} is the same as
-@option{-Wimplicit-fallthrough=0}.
-
-@item -Wimplicit-fallthrough=@var{n}
-@opindex Wimplicit-fallthrough=
-Warn when a switch case falls through. For example:
-
-@smallexample
-@group
-switch (cond)
- @{
- case 1:
- a = 1;
- break;
- case 2:
- a = 2;
- case 3:
- a = 3;
- break;
- @}
-@end group
-@end smallexample
-
-This warning does not warn when the last statement of a case cannot
-fall through, e.g. when there is a return statement or a call to function
-declared with the noreturn attribute. @option{-Wimplicit-fallthrough=}
-also takes into account control flow statements, such as ifs, and only
-warns when appropriate. E.g.@:
-
-@smallexample
-@group
-switch (cond)
- @{
- case 1:
- if (i > 3) @{
- bar (5);
- break;
- @} else if (i < 1) @{
- bar (0);
- @} else
- return;
- default:
- @dots{}
- @}
-@end group
-@end smallexample
-
-Since there are occasions where a switch case fall through is desirable,
-GCC provides an attribute, @code{__attribute__ ((fallthrough))}, that is
-to be used along with a null statement to suppress this warning that
-would normally occur:
-
-@smallexample
-@group
-switch (cond)
- @{
- case 1:
- bar (0);
- __attribute__ ((fallthrough));
- default:
- @dots{}
- @}
-@end group
-@end smallexample
-
-C++17 provides a standard way to suppress the @option{-Wimplicit-fallthrough}
-warning using @code{[[fallthrough]];} instead of the GNU attribute. In C++11
-or C++14 users can use @code{[[gnu::fallthrough]];}, which is a GNU extension.
-Instead of these attributes, it is also possible to add a fallthrough comment
-to silence the warning. The whole body of the C or C++ style comment should
-match the given regular expressions listed below. The option argument @var{n}
-specifies what kind of comments are accepted:
-
-@itemize @bullet
-
-@item @option{-Wimplicit-fallthrough=0} disables the warning altogether.
-
-@item @option{-Wimplicit-fallthrough=1} matches @code{.*} regular
-expression, any comment is used as fallthrough comment.
-
-@item @option{-Wimplicit-fallthrough=2} case insensitively matches
-@code{.*falls?[ \t-]*thr(ough|u).*} regular expression.
-
-@item @option{-Wimplicit-fallthrough=3} case sensitively matches one of the
-following regular expressions:
-
-@itemize @bullet
-
-@item @code{-fallthrough}
-
-@item @code{@@fallthrough@@}
-
-@item @code{lint -fallthrough[ \t]*}
-
-@item @code{[ \t.!]*(ELSE,? |INTENTIONAL(LY)? )?@*FALL(S | |-)?THR(OUGH|U)[ \t.!]*(-[^\n\r]*)?}
-
-@item @code{[ \t.!]*(Else,? |Intentional(ly)? )?@*Fall((s | |-)[Tt]|t)hr(ough|u)[ \t.!]*(-[^\n\r]*)?}
-
-@item @code{[ \t.!]*([Ee]lse,? |[Ii]ntentional(ly)? )?@*fall(s | |-)?thr(ough|u)[ \t.!]*(-[^\n\r]*)?}
-
-@end itemize
-
-@item @option{-Wimplicit-fallthrough=4} case sensitively matches one of the
-following regular expressions:
-
-@itemize @bullet
-
-@item @code{-fallthrough}
-
-@item @code{@@fallthrough@@}
-
-@item @code{lint -fallthrough[ \t]*}
-
-@item @code{[ \t]*FALLTHR(OUGH|U)[ \t]*}
-
-@end itemize
-
-@item @option{-Wimplicit-fallthrough=5} doesn't recognize any comments as
-fallthrough comments, only attributes disable the warning.
-
-@end itemize
-
-The comment needs to be followed after optional whitespace and other comments
-by @code{case} or @code{default} keywords or by a user label that precedes some
-@code{case} or @code{default} label.
-
-@smallexample
-@group
-switch (cond)
- @{
- case 1:
- bar (0);
- /* FALLTHRU */
- default:
- @dots{}
- @}
-@end group
-@end smallexample
-
-The @option{-Wimplicit-fallthrough=3} warning is enabled by @option{-Wextra}.
-
-@item -Wno-if-not-aligned @r{(C, C++, Objective-C and Objective-C++ only)}
-@opindex Wif-not-aligned
-@opindex Wno-if-not-aligned
-Control if warnings triggered by the @code{warn_if_not_aligned} attribute
-should be issued. These warnings are enabled by default.
-
-@item -Wignored-qualifiers @r{(C and C++ only)}
-@opindex Wignored-qualifiers
-@opindex Wno-ignored-qualifiers
-Warn if the return type of a function has a type qualifier
-such as @code{const}. For ISO C such a type qualifier has no effect,
-since the value returned by a function is not an lvalue.
-For C++, the warning is only emitted for scalar types or @code{void}.
-ISO C prohibits qualified @code{void} return types on function
-definitions, so such return types always receive a warning
-even without this option.
-
-This warning is also enabled by @option{-Wextra}.
-
-@item -Wno-ignored-attributes @r{(C and C++ only)}
-@opindex Wignored-attributes
-@opindex Wno-ignored-attributes
-This option controls warnings when an attribute is ignored.
-This is different from the
-@option{-Wattributes} option in that it warns whenever the compiler decides
-to drop an attribute, not that the attribute is either unknown, used in a
-wrong place, etc. This warning is enabled by default.
-
-@item -Wmain
-@opindex Wmain
-@opindex Wno-main
-Warn if the type of @code{main} is suspicious. @code{main} should be
-a function with external linkage, returning int, taking either zero
-arguments, two, or three arguments of appropriate types. This warning
-is enabled by default in C++ and is enabled by either @option{-Wall}
-or @option{-Wpedantic}.
-
-@item -Wmisleading-indentation @r{(C and C++ only)}
-@opindex Wmisleading-indentation
-@opindex Wno-misleading-indentation
-Warn when the indentation of the code does not reflect the block structure.
-Specifically, a warning is issued for @code{if}, @code{else}, @code{while}, and
-@code{for} clauses with a guarded statement that does not use braces,
-followed by an unguarded statement with the same indentation.
-
-In the following example, the call to ``bar'' is misleadingly indented as
-if it were guarded by the ``if'' conditional.
-
-@smallexample
- if (some_condition ())
- foo ();
- bar (); /* Gotcha: this is not guarded by the "if". */
-@end smallexample
-
-In the case of mixed tabs and spaces, the warning uses the
-@option{-ftabstop=} option to determine if the statements line up
-(defaulting to 8).
-
-The warning is not issued for code involving multiline preprocessor logic
-such as the following example.
-
-@smallexample
- if (flagA)
- foo (0);
-#if SOME_CONDITION_THAT_DOES_NOT_HOLD
- if (flagB)
-#endif
- foo (1);
-@end smallexample
-
-The warning is not issued after a @code{#line} directive, since this
-typically indicates autogenerated code, and no assumptions can be made
-about the layout of the file that the directive references.
-
-This warning is enabled by @option{-Wall} in C and C++.
-
-@item -Wmissing-attributes
-@opindex Wmissing-attributes
-@opindex Wno-missing-attributes
-Warn when a declaration of a function is missing one or more attributes
-that a related function is declared with and whose absence may adversely
-affect the correctness or efficiency of generated code. For example,
-the warning is issued for declarations of aliases that use attributes
-to specify less restrictive requirements than those of their targets.
-This typically represents a potential optimization opportunity.
-By contrast, the @option{-Wattribute-alias=2} option controls warnings
-issued when the alias is more restrictive than the target, which could
-lead to incorrect code generation.
-Attributes considered include @code{alloc_align}, @code{alloc_size},
-@code{cold}, @code{const}, @code{hot}, @code{leaf}, @code{malloc},
-@code{nonnull}, @code{noreturn}, @code{nothrow}, @code{pure},
-@code{returns_nonnull}, and @code{returns_twice}.
-
-In C++, the warning is issued when an explicit specialization of a primary
-template declared with attribute @code{alloc_align}, @code{alloc_size},
-@code{assume_aligned}, @code{format}, @code{format_arg}, @code{malloc},
-or @code{nonnull} is declared without it. Attributes @code{deprecated},
-@code{error}, and @code{warning} suppress the warning.
-(@pxref{Function Attributes}).
-
-You can use the @code{copy} attribute to apply the same
-set of attributes to a declaration as that on another declaration without
-explicitly enumerating the attributes. This attribute can be applied
-to declarations of functions (@pxref{Common Function Attributes}),
-variables (@pxref{Common Variable Attributes}), or types
-(@pxref{Common Type Attributes}).
-
-@option{-Wmissing-attributes} is enabled by @option{-Wall}.
-
-For example, since the declaration of the primary function template
-below makes use of both attribute @code{malloc} and @code{alloc_size}
-the declaration of the explicit specialization of the template is
-diagnosed because it is missing one of the attributes.
-
-@smallexample
-template <class T>
-T* __attribute__ ((malloc, alloc_size (1)))
-allocate (size_t);
-
-template <>
-void* __attribute__ ((malloc)) // missing alloc_size
-allocate<void> (size_t);
-@end smallexample
-
-@item -Wmissing-braces
-@opindex Wmissing-braces
-@opindex Wno-missing-braces
-Warn if an aggregate or union initializer is not fully bracketed. In
-the following example, the initializer for @code{a} is not fully
-bracketed, but that for @code{b} is fully bracketed.
-
-@smallexample
-int a[2][2] = @{ 0, 1, 2, 3 @};
-int b[2][2] = @{ @{ 0, 1 @}, @{ 2, 3 @} @};
-@end smallexample
-
-This warning is enabled by @option{-Wall}.
-
-@item -Wmissing-include-dirs @r{(C, C++, Objective-C, Objective-C++ and Fortran only)}
-@opindex Wmissing-include-dirs
-@opindex Wno-missing-include-dirs
-Warn if a user-supplied include directory does not exist. This opions is disabled
-by default for C, C++, Objective-C and Objective-C++. For Fortran, it is partially
-enabled by default by warning for -I and -J, only.
-
-@item -Wno-missing-profile
-@opindex Wmissing-profile
-@opindex Wno-missing-profile
-This option controls warnings if feedback profiles are missing when using the
-@option{-fprofile-use} option.
-This option diagnoses those cases where a new function or a new file is added
-between compiling with @option{-fprofile-generate} and with
-@option{-fprofile-use}, without regenerating the profiles.
-In these cases, the profile feedback data files do not contain any
-profile feedback information for
-the newly added function or file respectively. Also, in the case when profile
-count data (.gcda) files are removed, GCC cannot use any profile feedback
-information. In all these cases, warnings are issued to inform you that a
-profile generation step is due.
-Ignoring the warning can result in poorly optimized code.
-@option{-Wno-missing-profile} can be used to
-disable the warning, but this is not recommended and should be done only
-when non-existent profile data is justified.
-
-@item -Wmismatched-dealloc
-@opindex Wmismatched-dealloc
-@opindex Wno-mismatched-dealloc
-
-Warn for calls to deallocation functions with pointer arguments returned
-from from allocations functions for which the former isn't a suitable
-deallocator. A pair of functions can be associated as matching allocators
-and deallocators by use of attribute @code{malloc}. Unless disabled by
-the @option{-fno-builtin} option the standard functions @code{calloc},
-@code{malloc}, @code{realloc}, and @code{free}, as well as the corresponding
-forms of C++ @code{operator new} and @code{operator delete} are implicitly
-associated as matching allocators and deallocators. In the following
-example @code{mydealloc} is the deallocator for pointers returned from
-@code{myalloc}.
-
-@smallexample
-void mydealloc (void*);
-
-__attribute__ ((malloc (mydealloc, 1))) void*
-myalloc (size_t);
-
-void f (void)
-@{
- void *p = myalloc (32);
- // @dots{}use p@dots{}
- free (p); // warning: not a matching deallocator for myalloc
- mydealloc (p); // ok
-@}
-@end smallexample
-
-In C++, the related option @option{-Wmismatched-new-delete} diagnoses
-mismatches involving either @code{operator new} or @code{operator delete}.
-
-Option @option{-Wmismatched-dealloc} is included in @option{-Wall}.
-
-@item -Wmultistatement-macros
-@opindex Wmultistatement-macros
-@opindex Wno-multistatement-macros
-Warn about unsafe multiple statement macros that appear to be guarded
-by a clause such as @code{if}, @code{else}, @code{for}, @code{switch}, or
-@code{while}, in which only the first statement is actually guarded after
-the macro is expanded.
-
-For example:
-
-@smallexample
-#define DOIT x++; y++
-if (c)
- DOIT;
-@end smallexample
-
-will increment @code{y} unconditionally, not just when @code{c} holds.
-The can usually be fixed by wrapping the macro in a do-while loop:
-@smallexample
-#define DOIT do @{ x++; y++; @} while (0)
-if (c)
- DOIT;
-@end smallexample
-
-This warning is enabled by @option{-Wall} in C and C++.
-
-@item -Wparentheses
-@opindex Wparentheses
-@opindex Wno-parentheses
-Warn if parentheses are omitted in certain contexts, such
-as when there is an assignment in a context where a truth value
-is expected, or when operators are nested whose precedence people
-often get confused about.
-
-Also warn if a comparison like @code{x<=y<=z} appears; this is
-equivalent to @code{(x<=y ? 1 : 0) <= z}, which is a different
-interpretation from that of ordinary mathematical notation.
-
-Also warn for dangerous uses of the GNU extension to
-@code{?:} with omitted middle operand. When the condition
-in the @code{?}: operator is a boolean expression, the omitted value is
-always 1. Often programmers expect it to be a value computed
-inside the conditional expression instead.
-
-For C++ this also warns for some cases of unnecessary parentheses in
-declarations, which can indicate an attempt at a function call instead
-of a declaration:
-@smallexample
-@{
- // Declares a local variable called mymutex.
- std::unique_lock<std::mutex> (mymutex);
- // User meant std::unique_lock<std::mutex> lock (mymutex);
-@}
-@end smallexample
-
-This warning is enabled by @option{-Wall}.
-
-@item -Wno-self-move @r{(C++ and Objective-C++ only)}
-@opindex Wself-move
-@opindex Wno-self-move
-This warning warns when a value is moved to itself with @code{std::move}.
-Such a @code{std::move} typically has no effect.
-
-@smallexample
-struct T @{
-@dots{}
-@};
-void fn()
-@{
- T t;
- @dots{}
- t = std::move (t);
-@}
-@end smallexample
-
-This warning is enabled by @option{-Wall}.
-
-@item -Wsequence-point
-@opindex Wsequence-point
-@opindex Wno-sequence-point
-Warn about code that may have undefined semantics because of violations
-of sequence point rules in the C and C++ standards.
-
-The C and C++ standards define the order in which expressions in a C/C++
-program are evaluated in terms of @dfn{sequence points}, which represent
-a partial ordering between the execution of parts of the program: those
-executed before the sequence point, and those executed after it. These
-occur after the evaluation of a full expression (one which is not part
-of a larger expression), after the evaluation of the first operand of a
-@code{&&}, @code{||}, @code{? :} or @code{,} (comma) operator, before a
-function is called (but after the evaluation of its arguments and the
-expression denoting the called function), and in certain other places.
-Other than as expressed by the sequence point rules, the order of
-evaluation of subexpressions of an expression is not specified. All
-these rules describe only a partial order rather than a total order,
-since, for example, if two functions are called within one expression
-with no sequence point between them, the order in which the functions
-are called is not specified. However, the standards committee have
-ruled that function calls do not overlap.
-
-It is not specified when between sequence points modifications to the
-values of objects take effect. Programs whose behavior depends on this
-have undefined behavior; the C and C++ standards specify that ``Between
-the previous and next sequence point an object shall have its stored
-value modified at most once by the evaluation of an expression.
-Furthermore, the prior value shall be read only to determine the value
-to be stored.''. If a program breaks these rules, the results on any
-particular implementation are entirely unpredictable.
-
-Examples of code with undefined behavior are @code{a = a++;}, @code{a[n]
-= b[n++]} and @code{a[i++] = i;}. Some more complicated cases are not
-diagnosed by this option, and it may give an occasional false positive
-result, but in general it has been found fairly effective at detecting
-this sort of problem in programs.
-
-The C++17 standard will define the order of evaluation of operands in
-more cases: in particular it requires that the right-hand side of an
-assignment be evaluated before the left-hand side, so the above
-examples are no longer undefined. But this option will still warn
-about them, to help people avoid writing code that is undefined in C
-and earlier revisions of C++.
-
-The standard is worded confusingly, therefore there is some debate
-over the precise meaning of the sequence point rules in subtle cases.
-Links to discussions of the problem, including proposed formal
-definitions, may be found on the GCC readings page, at
-@uref{https://gcc.gnu.org/@/readings.html}.
-
-This warning is enabled by @option{-Wall} for C and C++.
-
-@item -Wno-return-local-addr
-@opindex Wno-return-local-addr
-@opindex Wreturn-local-addr
-Do not warn about returning a pointer (or in C++, a reference) to a
-variable that goes out of scope after the function returns.
-
-@item -Wreturn-type
-@opindex Wreturn-type
-@opindex Wno-return-type
-Warn whenever a function is defined with a return type that defaults
-to @code{int}. Also warn about any @code{return} statement with no
-return value in a function whose return type is not @code{void}
-(falling off the end of the function body is considered returning
-without a value).
-
-For C only, warn about a @code{return} statement with an expression in a
-function whose return type is @code{void}, unless the expression type is
-also @code{void}. As a GNU extension, the latter case is accepted
-without a warning unless @option{-Wpedantic} is used. Attempting
-to use the return value of a non-@code{void} function other than @code{main}
-that flows off the end by reaching the closing curly brace that terminates
-the function is undefined.
-
-Unlike in C, in C++, flowing off the end of a non-@code{void} function other
-than @code{main} results in undefined behavior even when the value of
-the function is not used.
-
-This warning is enabled by default in C++ and by @option{-Wall} otherwise.
-
-@item -Wno-shift-count-negative
-@opindex Wshift-count-negative
-@opindex Wno-shift-count-negative
-Controls warnings if a shift count is negative.
-This warning is enabled by default.
-
-@item -Wno-shift-count-overflow
-@opindex Wshift-count-overflow
-@opindex Wno-shift-count-overflow
-Controls warnings if a shift count is greater than or equal to the bit width
-of the type. This warning is enabled by default.
-
-@item -Wshift-negative-value
-@opindex Wshift-negative-value
-@opindex Wno-shift-negative-value
-Warn if left shifting a negative value. This warning is enabled by
-@option{-Wextra} in C99 (and newer) and C++11 to C++17 modes.
-
-@item -Wno-shift-overflow
-@itemx -Wshift-overflow=@var{n}
-@opindex Wshift-overflow
-@opindex Wno-shift-overflow
-These options control warnings about left shift overflows.
-
-@table @gcctabopt
-@item -Wshift-overflow=1
-This is the warning level of @option{-Wshift-overflow} and is enabled
-by default in C99 and C++11 modes (and newer). This warning level does
-not warn about left-shifting 1 into the sign bit. (However, in C, such
-an overflow is still rejected in contexts where an integer constant expression
-is required.) No warning is emitted in C++20 mode (and newer), as signed left
-shifts always wrap.
-
-@item -Wshift-overflow=2
-This warning level also warns about left-shifting 1 into the sign bit,
-unless C++14 mode (or newer) is active.
-@end table
-
-@item -Wswitch
-@opindex Wswitch
-@opindex Wno-switch
-Warn whenever a @code{switch} statement has an index of enumerated type
-and lacks a @code{case} for one or more of the named codes of that
-enumeration. (The presence of a @code{default} label prevents this
-warning.) @code{case} labels outside the enumeration range also
-provoke warnings when this option is used (even if there is a
-@code{default} label).
-This warning is enabled by @option{-Wall}.
-
-@item -Wswitch-default
-@opindex Wswitch-default
-@opindex Wno-switch-default
-Warn whenever a @code{switch} statement does not have a @code{default}
-case.
-
-@item -Wswitch-enum
-@opindex Wswitch-enum
-@opindex Wno-switch-enum
-Warn whenever a @code{switch} statement has an index of enumerated type
-and lacks a @code{case} for one or more of the named codes of that
-enumeration. @code{case} labels outside the enumeration range also
-provoke warnings when this option is used. The only difference
-between @option{-Wswitch} and this option is that this option gives a
-warning about an omitted enumeration code even if there is a
-@code{default} label.
-
-@item -Wno-switch-bool
-@opindex Wswitch-bool
-@opindex Wno-switch-bool
-Do not warn when a @code{switch} statement has an index of boolean type
-and the case values are outside the range of a boolean type.
-It is possible to suppress this warning by casting the controlling
-expression to a type other than @code{bool}. For example:
-@smallexample
-@group
-switch ((int) (a == 4))
- @{
- @dots{}
- @}
-@end group
-@end smallexample
-This warning is enabled by default for C and C++ programs.
-
-@item -Wno-switch-outside-range
-@opindex Wswitch-outside-range
-@opindex Wno-switch-outside-range
-This option controls warnings when a @code{switch} case has a value
-that is outside of its
-respective type range. This warning is enabled by default for
-C and C++ programs.
-
-@item -Wno-switch-unreachable
-@opindex Wswitch-unreachable
-@opindex Wno-switch-unreachable
-Do not warn when a @code{switch} statement contains statements between the
-controlling expression and the first case label, which will never be
-executed. For example:
-@smallexample
-@group
-switch (cond)
- @{
- i = 15;
- @dots{}
- case 5:
- @dots{}
- @}
-@end group
-@end smallexample
-@option{-Wswitch-unreachable} does not warn if the statement between the
-controlling expression and the first case label is just a declaration:
-@smallexample
-@group
-switch (cond)
- @{
- int i;
- @dots{}
- case 5:
- i = 5;
- @dots{}
- @}
-@end group
-@end smallexample
-This warning is enabled by default for C and C++ programs.
-
-@item -Wsync-nand @r{(C and C++ only)}
-@opindex Wsync-nand
-@opindex Wno-sync-nand
-Warn when @code{__sync_fetch_and_nand} and @code{__sync_nand_and_fetch}
-built-in functions are used. These functions changed semantics in GCC 4.4.
-
-@item -Wtrivial-auto-var-init
-@opindex Wtrivial-auto-var-init
-@opindex Wno-trivial-auto-var-init
-Warn when @code{-ftrivial-auto-var-init} cannot initialize the automatic
-variable. A common situation is an automatic variable that is declared
-between the controlling expression and the first case label of a @code{switch}
-statement.
-
-@item -Wunused-but-set-parameter
-@opindex Wunused-but-set-parameter
-@opindex Wno-unused-but-set-parameter
-Warn whenever a function parameter is assigned to, but otherwise unused
-(aside from its declaration).
-
-To suppress this warning use the @code{unused} attribute
-(@pxref{Variable Attributes}).
-
-This warning is also enabled by @option{-Wunused} together with
-@option{-Wextra}.
-
-@item -Wunused-but-set-variable
-@opindex Wunused-but-set-variable
-@opindex Wno-unused-but-set-variable
-Warn whenever a local variable is assigned to, but otherwise unused
-(aside from its declaration).
-This warning is enabled by @option{-Wall}.
-
-To suppress this warning use the @code{unused} attribute
-(@pxref{Variable Attributes}).
-
-This warning is also enabled by @option{-Wunused}, which is enabled
-by @option{-Wall}.
-
-@item -Wunused-function
-@opindex Wunused-function
-@opindex Wno-unused-function
-Warn whenever a static function is declared but not defined or a
-non-inline static function is unused.
-This warning is enabled by @option{-Wall}.
-
-@item -Wunused-label
-@opindex Wunused-label
-@opindex Wno-unused-label
-Warn whenever a label is declared but not used.
-This warning is enabled by @option{-Wall}.
-
-To suppress this warning use the @code{unused} attribute
-(@pxref{Variable Attributes}).
-
-@item -Wunused-local-typedefs @r{(C, Objective-C, C++ and Objective-C++ only)}
-@opindex Wunused-local-typedefs
-@opindex Wno-unused-local-typedefs
-Warn when a typedef locally defined in a function is not used.
-This warning is enabled by @option{-Wall}.
-
-@item -Wunused-parameter
-@opindex Wunused-parameter
-@opindex Wno-unused-parameter
-Warn whenever a function parameter is unused aside from its declaration.
-
-To suppress this warning use the @code{unused} attribute
-(@pxref{Variable Attributes}).
-
-@item -Wno-unused-result
-@opindex Wunused-result
-@opindex Wno-unused-result
-Do not warn if a caller of a function marked with attribute
-@code{warn_unused_result} (@pxref{Function Attributes}) does not use
-its return value. The default is @option{-Wunused-result}.
-
-@item -Wunused-variable
-@opindex Wunused-variable
-@opindex Wno-unused-variable
-Warn whenever a local or static variable is unused aside from its
-declaration. This option implies @option{-Wunused-const-variable=1} for C,
-but not for C++. This warning is enabled by @option{-Wall}.
-
-To suppress this warning use the @code{unused} attribute
-(@pxref{Variable Attributes}).
-
-@item -Wunused-const-variable
-@itemx -Wunused-const-variable=@var{n}
-@opindex Wunused-const-variable
-@opindex Wno-unused-const-variable
-Warn whenever a constant static variable is unused aside from its declaration.
-@option{-Wunused-const-variable=1} is enabled by @option{-Wunused-variable}
-for C, but not for C++. In C this declares variable storage, but in C++ this
-is not an error since const variables take the place of @code{#define}s.
-
-To suppress this warning use the @code{unused} attribute
-(@pxref{Variable Attributes}).
-
-@table @gcctabopt
-@item -Wunused-const-variable=1
-This is the warning level that is enabled by @option{-Wunused-variable} for
-C. It warns only about unused static const variables defined in the main
-compilation unit, but not about static const variables declared in any
-header included.
-
-@item -Wunused-const-variable=2
-This warning level also warns for unused constant static variables in
-headers (excluding system headers). This is the warning level of
-@option{-Wunused-const-variable} and must be explicitly requested since
-in C++ this isn't an error and in C it might be harder to clean up all
-headers included.
-@end table
-
-@item -Wunused-value
-@opindex Wunused-value
-@opindex Wno-unused-value
-Warn whenever a statement computes a result that is explicitly not
-used. To suppress this warning cast the unused expression to
-@code{void}. This includes an expression-statement or the left-hand
-side of a comma expression that contains no side effects. For example,
-an expression such as @code{x[i,j]} causes a warning, while
-@code{x[(void)i,j]} does not.
-
-This warning is enabled by @option{-Wall}.
-
-@item -Wunused
-@opindex Wunused
-@opindex Wno-unused
-All the above @option{-Wunused} options combined.
-
-In order to get a warning about an unused function parameter, you must
-either specify @option{-Wextra -Wunused} (note that @option{-Wall} implies
-@option{-Wunused}), or separately specify @option{-Wunused-parameter}.
-
-@item -Wuninitialized
-@opindex Wuninitialized
-@opindex Wno-uninitialized
-Warn if an object with automatic or allocated storage duration is used
-without having been initialized. In C++, also warn if a non-static
-reference or non-static @code{const} member appears in a class without
-constructors.
-
-In addition, passing a pointer (or in C++, a reference) to an uninitialized
-object to a @code{const}-qualified argument of a built-in function known to
-read the object is also diagnosed by this warning.
-(@option{-Wmaybe-uninitialized} is issued for ordinary functions.)
-
-If you want to warn about code that uses the uninitialized value of the
-variable in its own initializer, use the @option{-Winit-self} option.
-
-These warnings occur for individual uninitialized elements of
-structure, union or array variables as well as for variables that are
-uninitialized as a whole. They do not occur for variables or elements
-declared @code{volatile}. Because these warnings depend on
-optimization, the exact variables or elements for which there are
-warnings depend on the precise optimization options and version of GCC
-used.
-
-Note that there may be no warning about a variable that is used only
-to compute a value that itself is never used, because such
-computations may be deleted by data flow analysis before the warnings
-are printed.
-
-In C++, this warning also warns about using uninitialized objects in
-member-initializer-lists. For example, GCC warns about @code{b} being
-uninitialized in the following snippet:
-
-@smallexample
-struct A @{
- int a;
- int b;
- A() : a(b) @{ @}
-@};
-@end smallexample
-
-@item -Wno-invalid-memory-model
-@opindex Winvalid-memory-model
-@opindex Wno-invalid-memory-model
-This option controls warnings
-for invocations of @ref{__atomic Builtins}, @ref{__sync Builtins},
-and the C11 atomic generic functions with a memory consistency argument
-that is either invalid for the operation or outside the range of values
-of the @code{memory_order} enumeration. For example, since the
-@code{__atomic_store} and @code{__atomic_store_n} built-ins are only
-defined for the relaxed, release, and sequentially consistent memory
-orders the following code is diagnosed:
-
-@smallexample
-void store (int *i)
-@{
- __atomic_store_n (i, 0, memory_order_consume);
-@}
-@end smallexample
-
-@option{-Winvalid-memory-model} is enabled by default.
-
-@item -Wmaybe-uninitialized
-@opindex Wmaybe-uninitialized
-@opindex Wno-maybe-uninitialized
-For an object with automatic or allocated storage duration, if there exists
-a path from the function entry to a use of the object that is initialized,
-but there exist some other paths for which the object is not initialized,
-the compiler emits a warning if it cannot prove the uninitialized paths
-are not executed at run time.
-
-In addition, passing a pointer (or in C++, a reference) to an uninitialized
-object to a @code{const}-qualified function argument is also diagnosed by
-this warning. (@option{-Wuninitialized} is issued for built-in functions
-known to read the object.) Annotating the function with attribute
-@code{access (none)} indicates that the argument isn't used to access
-the object and avoids the warning (@pxref{Common Function Attributes}).
-
-These warnings are only possible in optimizing compilation, because otherwise
-GCC does not keep track of the state of variables.
-
-These warnings are made optional because GCC may not be able to determine when
-the code is correct in spite of appearing to have an error. Here is one
-example of how this can happen:
-
-@smallexample
-@group
-@{
- int x;
- switch (y)
- @{
- case 1: x = 1;
- break;
- case 2: x = 4;
- break;
- case 3: x = 5;
- @}
- foo (x);
-@}
-@end group
-@end smallexample
-
-@noindent
-If the value of @code{y} is always 1, 2 or 3, then @code{x} is
-always initialized, but GCC doesn't know this. To suppress the
-warning, you need to provide a default case with assert(0) or
-similar code.
-
-@cindex @code{longjmp} warnings
-This option also warns when a non-volatile automatic variable might be
-changed by a call to @code{longjmp}.
-The compiler sees only the calls to @code{setjmp}. It cannot know
-where @code{longjmp} will be called; in fact, a signal handler could
-call it at any point in the code. As a result, you may get a warning
-even when there is in fact no problem because @code{longjmp} cannot
-in fact be called at the place that would cause a problem.
-
-Some spurious warnings can be avoided if you declare all the functions
-you use that never return as @code{noreturn}. @xref{Function
-Attributes}.
-
-This warning is enabled by @option{-Wall} or @option{-Wextra}.
-
-@item -Wunknown-pragmas
-@opindex Wunknown-pragmas
-@opindex Wno-unknown-pragmas
-@cindex warning for unknown pragmas
-@cindex unknown pragmas, warning
-@cindex pragmas, warning of unknown
-Warn when a @code{#pragma} directive is encountered that is not understood by
-GCC@. If this command-line option is used, warnings are even issued
-for unknown pragmas in system header files. This is not the case if
-the warnings are only enabled by the @option{-Wall} command-line option.
-
-@item -Wno-pragmas
-@opindex Wno-pragmas
-@opindex Wpragmas
-Do not warn about misuses of pragmas, such as incorrect parameters,
-invalid syntax, or conflicts between pragmas. See also
-@option{-Wunknown-pragmas}.
-
-@item -Wno-prio-ctor-dtor
-@opindex Wno-prio-ctor-dtor
-@opindex Wprio-ctor-dtor
-Do not warn if a priority from 0 to 100 is used for constructor or destructor.
-The use of constructor and destructor attributes allow you to assign a
-priority to the constructor/destructor to control its order of execution
-before @code{main} is called or after it returns. The priority values must be
-greater than 100 as the compiler reserves priority values between 0--100 for
-the implementation.
-
-@item -Wstrict-aliasing
-@opindex Wstrict-aliasing
-@opindex Wno-strict-aliasing
-This option is only active when @option{-fstrict-aliasing} is active.
-It warns about code that might break the strict aliasing rules that the
-compiler is using for optimization. The warning does not catch all
-cases, but does attempt to catch the more common pitfalls. It is
-included in @option{-Wall}.
-It is equivalent to @option{-Wstrict-aliasing=3}
-
-@item -Wstrict-aliasing=n
-@opindex Wstrict-aliasing=n
-This option is only active when @option{-fstrict-aliasing} is active.
-It warns about code that might break the strict aliasing rules that the
-compiler is using for optimization.
-Higher levels correspond to higher accuracy (fewer false positives).
-Higher levels also correspond to more effort, similar to the way @option{-O}
-works.
-@option{-Wstrict-aliasing} is equivalent to @option{-Wstrict-aliasing=3}.
-
-Level 1: Most aggressive, quick, least accurate.
-Possibly useful when higher levels
-do not warn but @option{-fstrict-aliasing} still breaks the code, as it has very few
-false negatives. However, it has many false positives.
-Warns for all pointer conversions between possibly incompatible types,
-even if never dereferenced. Runs in the front end only.
-
-Level 2: Aggressive, quick, not too precise.
-May still have many false positives (not as many as level 1 though),
-and few false negatives (but possibly more than level 1).
-Unlike level 1, it only warns when an address is taken. Warns about
-incomplete types. Runs in the front end only.
-
-Level 3 (default for @option{-Wstrict-aliasing}):
-Should have very few false positives and few false
-negatives. Slightly slower than levels 1 or 2 when optimization is enabled.
-Takes care of the common pun+dereference pattern in the front end:
-@code{*(int*)&some_float}.
-If optimization is enabled, it also runs in the back end, where it deals
-with multiple statement cases using flow-sensitive points-to information.
-Only warns when the converted pointer is dereferenced.
-Does not warn about incomplete types.
-
-@item -Wstrict-overflow
-@itemx -Wstrict-overflow=@var{n}
-@opindex Wstrict-overflow
-@opindex Wno-strict-overflow
-This option is only active when signed overflow is undefined.
-It warns about cases where the compiler optimizes based on the
-assumption that signed overflow does not occur. Note that it does not
-warn about all cases where the code might overflow: it only warns
-about cases where the compiler implements some optimization. Thus
-this warning depends on the optimization level.
-
-An optimization that assumes that signed overflow does not occur is
-perfectly safe if the values of the variables involved are such that
-overflow never does, in fact, occur. Therefore this warning can
-easily give a false positive: a warning about code that is not
-actually a problem. To help focus on important issues, several
-warning levels are defined. No warnings are issued for the use of
-undefined signed overflow when estimating how many iterations a loop
-requires, in particular when determining whether a loop will be
-executed at all.
-
-@table @gcctabopt
-@item -Wstrict-overflow=1
-Warn about cases that are both questionable and easy to avoid. For
-example the compiler simplifies
-@code{x + 1 > x} to @code{1}. This level of
-@option{-Wstrict-overflow} is enabled by @option{-Wall}; higher levels
-are not, and must be explicitly requested.
-
-@item -Wstrict-overflow=2
-Also warn about other cases where a comparison is simplified to a
-constant. For example: @code{abs (x) >= 0}. This can only be
-simplified when signed integer overflow is undefined, because
-@code{abs (INT_MIN)} overflows to @code{INT_MIN}, which is less than
-zero. @option{-Wstrict-overflow} (with no level) is the same as
-@option{-Wstrict-overflow=2}.
-
-@item -Wstrict-overflow=3
-Also warn about other cases where a comparison is simplified. For
-example: @code{x + 1 > 1} is simplified to @code{x > 0}.
-
-@item -Wstrict-overflow=4
-Also warn about other simplifications not covered by the above cases.
-For example: @code{(x * 10) / 5} is simplified to @code{x * 2}.
-
-@item -Wstrict-overflow=5
-Also warn about cases where the compiler reduces the magnitude of a
-constant involved in a comparison. For example: @code{x + 2 > y} is
-simplified to @code{x + 1 >= y}. This is reported only at the
-highest warning level because this simplification applies to many
-comparisons, so this warning level gives a very large number of
-false positives.
-@end table
-
-@item -Wstring-compare
-@opindex Wstring-compare
-@opindex Wno-string-compare
-Warn for calls to @code{strcmp} and @code{strncmp} whose result is
-determined to be either zero or non-zero in tests for such equality
-owing to the length of one argument being greater than the size of
-the array the other argument is stored in (or the bound in the case
-of @code{strncmp}). Such calls could be mistakes. For example,
-the call to @code{strcmp} below is diagnosed because its result is
-necessarily non-zero irrespective of the contents of the array @code{a}.
-
-@smallexample
-extern char a[4];
-void f (char *d)
-@{
- strcpy (d, "string");
- @dots{}
- if (0 == strcmp (a, d)) // cannot be true
- puts ("a and d are the same");
-@}
-@end smallexample
-
-@option{-Wstring-compare} is enabled by @option{-Wextra}.
-
-@item -Wno-stringop-overflow
-@item -Wstringop-overflow
-@itemx -Wstringop-overflow=@var{type}
-@opindex Wstringop-overflow
-@opindex Wno-stringop-overflow
-Warn for calls to string manipulation functions such as @code{memcpy} and
-@code{strcpy} that are determined to overflow the destination buffer. The
-optional argument is one greater than the type of Object Size Checking to
-perform to determine the size of the destination. @xref{Object Size Checking}.
-The argument is meaningful only for functions that operate on character arrays
-but not for raw memory functions like @code{memcpy} which always make use
-of Object Size type-0. The option also warns for calls that specify a size
-in excess of the largest possible object or at most @code{SIZE_MAX / 2} bytes.
-The option produces the best results with optimization enabled but can detect
-a small subset of simple buffer overflows even without optimization in
-calls to the GCC built-in functions like @code{__builtin_memcpy} that
-correspond to the standard functions. In any case, the option warns about
-just a subset of buffer overflows detected by the corresponding overflow
-checking built-ins. For example, the option issues a warning for
-the @code{strcpy} call below because it copies at least 5 characters
-(the string @code{"blue"} including the terminating NUL) into the buffer
-of size 4.
-
-@smallexample
-enum Color @{ blue, purple, yellow @};
-const char* f (enum Color clr)
-@{
- static char buf [4];
- const char *str;
- switch (clr)
- @{
- case blue: str = "blue"; break;
- case purple: str = "purple"; break;
- case yellow: str = "yellow"; break;
- @}
-
- return strcpy (buf, str); // warning here
-@}
-@end smallexample
-
-Option @option{-Wstringop-overflow=2} is enabled by default.
-
-@table @gcctabopt
-@item -Wstringop-overflow
-@itemx -Wstringop-overflow=1
-@opindex Wstringop-overflow
-@opindex Wno-stringop-overflow
-The @option{-Wstringop-overflow=1} option uses type-zero Object Size Checking
-to determine the sizes of destination objects. At this setting the option
-does not warn for writes past the end of subobjects of larger objects accessed
-by pointers unless the size of the largest surrounding object is known. When
-the destination may be one of several objects it is assumed to be the largest
-one of them. On Linux systems, when optimization is enabled at this setting
-the option warns for the same code as when the @code{_FORTIFY_SOURCE} macro
-is defined to a non-zero value.
-
-@item -Wstringop-overflow=2
-The @option{-Wstringop-overflow=2} option uses type-one Object Size Checking
-to determine the sizes of destination objects. At this setting the option
-warns about overflows when writing to members of the largest complete
-objects whose exact size is known. However, it does not warn for excessive
-writes to the same members of unknown objects referenced by pointers since
-they may point to arrays containing unknown numbers of elements. This is
-the default setting of the option.
-
-@item -Wstringop-overflow=3
-The @option{-Wstringop-overflow=3} option uses type-two Object Size Checking
-to determine the sizes of destination objects. At this setting the option
-warns about overflowing the smallest object or data member. This is the
-most restrictive setting of the option that may result in warnings for safe
-code.
-
-@item -Wstringop-overflow=4
-The @option{-Wstringop-overflow=4} option uses type-three Object Size Checking
-to determine the sizes of destination objects. At this setting the option
-warns about overflowing any data members, and when the destination is
-one of several objects it uses the size of the largest of them to decide
-whether to issue a warning. Similarly to @option{-Wstringop-overflow=3} this
-setting of the option may result in warnings for benign code.
-@end table
-
-@item -Wno-stringop-overread
-@opindex Wstringop-overread
-@opindex Wno-stringop-overread
-Warn for calls to string manipulation functions such as @code{memchr}, or
-@code{strcpy} that are determined to read past the end of the source
-sequence.
-
-Option @option{-Wstringop-overread} is enabled by default.
-
-@item -Wno-stringop-truncation
-@opindex Wstringop-truncation
-@opindex Wno-stringop-truncation
-Do not warn for calls to bounded string manipulation functions
-such as @code{strncat},
-@code{strncpy}, and @code{stpncpy} that may either truncate the copied string
-or leave the destination unchanged.
-
-In the following example, the call to @code{strncat} specifies a bound that
-is less than the length of the source string. As a result, the copy of
-the source will be truncated and so the call is diagnosed. To avoid the
-warning use @code{bufsize - strlen (buf) - 1)} as the bound.
-
-@smallexample
-void append (char *buf, size_t bufsize)
-@{
- strncat (buf, ".txt", 3);
-@}
-@end smallexample
-
-As another example, the following call to @code{strncpy} results in copying
-to @code{d} just the characters preceding the terminating NUL, without
-appending the NUL to the end. Assuming the result of @code{strncpy} is
-necessarily a NUL-terminated string is a common mistake, and so the call
-is diagnosed. To avoid the warning when the result is not expected to be
-NUL-terminated, call @code{memcpy} instead.
-
-@smallexample
-void copy (char *d, const char *s)
-@{
- strncpy (d, s, strlen (s));
-@}
-@end smallexample
-
-In the following example, the call to @code{strncpy} specifies the size
-of the destination buffer as the bound. If the length of the source
-string is equal to or greater than this size the result of the copy will
-not be NUL-terminated. Therefore, the call is also diagnosed. To avoid
-the warning, specify @code{sizeof buf - 1} as the bound and set the last
-element of the buffer to @code{NUL}.
-
-@smallexample
-void copy (const char *s)
-@{
- char buf[80];
- strncpy (buf, s, sizeof buf);
- @dots{}
-@}
-@end smallexample
-
-In situations where a character array is intended to store a sequence
-of bytes with no terminating @code{NUL} such an array may be annotated
-with attribute @code{nonstring} to avoid this warning. Such arrays,
-however, are not suitable arguments to functions that expect
-@code{NUL}-terminated strings. To help detect accidental misuses of
-such arrays GCC issues warnings unless it can prove that the use is
-safe. @xref{Common Variable Attributes}.
-
-@item -Wsuggest-attribute=@r{[}pure@r{|}const@r{|}noreturn@r{|}format@r{|}cold@r{|}malloc@r{]}
-@opindex Wsuggest-attribute=
-@opindex Wno-suggest-attribute=
-Warn for cases where adding an attribute may be beneficial. The
-attributes currently supported are listed below.
-
-@table @gcctabopt
-@item -Wsuggest-attribute=pure
-@itemx -Wsuggest-attribute=const
-@itemx -Wsuggest-attribute=noreturn
-@itemx -Wmissing-noreturn
-@itemx -Wsuggest-attribute=malloc
-@opindex Wsuggest-attribute=pure
-@opindex Wno-suggest-attribute=pure
-@opindex Wsuggest-attribute=const
-@opindex Wno-suggest-attribute=const
-@opindex Wsuggest-attribute=noreturn
-@opindex Wno-suggest-attribute=noreturn
-@opindex Wmissing-noreturn
-@opindex Wno-missing-noreturn
-@opindex Wsuggest-attribute=malloc
-@opindex Wno-suggest-attribute=malloc
-
-Warn about functions that might be candidates for attributes
-@code{pure}, @code{const} or @code{noreturn} or @code{malloc}. The compiler
-only warns for functions visible in other compilation units or (in the case of
-@code{pure} and @code{const}) if it cannot prove that the function returns
-normally. A function returns normally if it doesn't contain an infinite loop or
-return abnormally by throwing, calling @code{abort} or trapping. This analysis
-requires option @option{-fipa-pure-const}, which is enabled by default at
-@option{-O} and higher. Higher optimization levels improve the accuracy
-of the analysis.
-
-@item -Wsuggest-attribute=format
-@itemx -Wmissing-format-attribute
-@opindex Wsuggest-attribute=format
-@opindex Wmissing-format-attribute
-@opindex Wno-suggest-attribute=format
-@opindex Wno-missing-format-attribute
-@opindex Wformat
-@opindex Wno-format
-
-Warn about function pointers that might be candidates for @code{format}
-attributes. Note these are only possible candidates, not absolute ones.
-GCC guesses that function pointers with @code{format} attributes that
-are used in assignment, initialization, parameter passing or return
-statements should have a corresponding @code{format} attribute in the
-resulting type. I.e.@: the left-hand side of the assignment or
-initialization, the type of the parameter variable, or the return type
-of the containing function respectively should also have a @code{format}
-attribute to avoid the warning.
-
-GCC also warns about function definitions that might be
-candidates for @code{format} attributes. Again, these are only
-possible candidates. GCC guesses that @code{format} attributes
-might be appropriate for any function that calls a function like
-@code{vprintf} or @code{vscanf}, but this might not always be the
-case, and some functions for which @code{format} attributes are
-appropriate may not be detected.
-
-@item -Wsuggest-attribute=cold
-@opindex Wsuggest-attribute=cold
-@opindex Wno-suggest-attribute=cold
-
-Warn about functions that might be candidates for @code{cold} attribute. This
-is based on static detection and generally only warns about functions which
-always leads to a call to another @code{cold} function such as wrappers of
-C++ @code{throw} or fatal error reporting functions leading to @code{abort}.
-@end table
-
-@item -Walloc-zero
-@opindex Wno-alloc-zero
-@opindex Walloc-zero
-Warn about calls to allocation functions decorated with attribute
-@code{alloc_size} that specify zero bytes, including those to the built-in
-forms of the functions @code{aligned_alloc}, @code{alloca}, @code{calloc},
-@code{malloc}, and @code{realloc}. Because the behavior of these functions
-when called with a zero size differs among implementations (and in the case
-of @code{realloc} has been deprecated) relying on it may result in subtle
-portability bugs and should be avoided.
-
-@item -Walloc-size-larger-than=@var{byte-size}
-@opindex Walloc-size-larger-than=
-@opindex Wno-alloc-size-larger-than
-Warn about calls to functions decorated with attribute @code{alloc_size}
-that attempt to allocate objects larger than the specified number of bytes,
-or where the result of the size computation in an integer type with infinite
-precision would exceed the value of @samp{PTRDIFF_MAX} on the target.
-@option{-Walloc-size-larger-than=}@samp{PTRDIFF_MAX} is enabled by default.
-Warnings controlled by the option can be disabled either by specifying
-@var{byte-size} of @samp{SIZE_MAX} or more or by
-@option{-Wno-alloc-size-larger-than}.
-@xref{Function Attributes}.
-
-@item -Wno-alloc-size-larger-than
-@opindex Wno-alloc-size-larger-than
-Disable @option{-Walloc-size-larger-than=} warnings. The option is
-equivalent to @option{-Walloc-size-larger-than=}@samp{SIZE_MAX} or
-larger.
-
-@item -Walloca
-@opindex Wno-alloca
-@opindex Walloca
-This option warns on all uses of @code{alloca} in the source.
-
-@item -Walloca-larger-than=@var{byte-size}
-@opindex Walloca-larger-than=
-@opindex Wno-alloca-larger-than
-This option warns on calls to @code{alloca} with an integer argument whose
-value is either zero, or that is not bounded by a controlling predicate
-that limits its value to at most @var{byte-size}. It also warns for calls
-to @code{alloca} where the bound value is unknown. Arguments of non-integer
-types are considered unbounded even if they appear to be constrained to
-the expected range.
-
-For example, a bounded case of @code{alloca} could be:
-
-@smallexample
-void func (size_t n)
-@{
- void *p;
- if (n <= 1000)
- p = alloca (n);
- else
- p = malloc (n);
- f (p);
-@}
-@end smallexample
-
-In the above example, passing @code{-Walloca-larger-than=1000} would not
-issue a warning because the call to @code{alloca} is known to be at most
-1000 bytes. However, if @code{-Walloca-larger-than=500} were passed,
-the compiler would emit a warning.
-
-Unbounded uses, on the other hand, are uses of @code{alloca} with no
-controlling predicate constraining its integer argument. For example:
-
-@smallexample
-void func ()
-@{
- void *p = alloca (n);
- f (p);
-@}
-@end smallexample
-
-If @code{-Walloca-larger-than=500} were passed, the above would trigger
-a warning, but this time because of the lack of bounds checking.
-
-Note, that even seemingly correct code involving signed integers could
-cause a warning:
-
-@smallexample
-void func (signed int n)
-@{
- if (n < 500)
- @{
- p = alloca (n);
- f (p);
- @}
-@}
-@end smallexample
-
-In the above example, @var{n} could be negative, causing a larger than
-expected argument to be implicitly cast into the @code{alloca} call.
-
-This option also warns when @code{alloca} is used in a loop.
-
-@option{-Walloca-larger-than=}@samp{PTRDIFF_MAX} is enabled by default
-but is usually only effective when @option{-ftree-vrp} is active (default
-for @option{-O2} and above).
-
-See also @option{-Wvla-larger-than=}@samp{byte-size}.
-
-@item -Wno-alloca-larger-than
-@opindex Wno-alloca-larger-than
-Disable @option{-Walloca-larger-than=} warnings. The option is
-equivalent to @option{-Walloca-larger-than=}@samp{SIZE_MAX} or larger.
-
-@item -Warith-conversion
-@opindex Warith-conversion
-@opindex Wno-arith-conversion
-Do warn about implicit conversions from arithmetic operations even
-when conversion of the operands to the same type cannot change their
-values. This affects warnings from @option{-Wconversion},
-@option{-Wfloat-conversion}, and @option{-Wsign-conversion}.
-
-@smallexample
-@group
-void f (char c, int i)
-@{
- c = c + i; // warns with @option{-Wconversion}
- c = c + 1; // only warns with @option{-Warith-conversion}
-@}
-@end group
-@end smallexample
-
-@item -Warray-bounds
-@itemx -Warray-bounds=@var{n}
-@opindex Wno-array-bounds
-@opindex Warray-bounds
-Warn about out of bounds subscripts or offsets into arrays. This warning
-is enabled by @option{-Wall}. It is more effective when @option{-ftree-vrp}
-is active (the default for @option{-O2} and above) but a subset of instances
-are issued even without optimization.
-
-@table @gcctabopt
-@item -Warray-bounds=1
-This is the default warning level of @option{-Warray-bounds} and is enabled
-by @option{-Wall}; higher levels are not, and must be explicitly requested.
-
-@item -Warray-bounds=2
-This warning level also warns about out of bounds accesses to trailing
-struct members of one-element array types (@pxref{Zero Length}) and about
-the intermediate results of pointer arithmetic that may yield out of bounds
-values. This warning level may give a larger number of false positives and
-is deactivated by default.
-@end table
-
-@item -Warray-compare
-@opindex Warray-compare
-@opindex Wno-array-compare
-Warn about equality and relational comparisons between two operands of array
-type. This comparison was deprecated in C++20. For example:
-
-@smallexample
-int arr1[5];
-int arr2[5];
-bool same = arr1 == arr2;
-@end smallexample
-
-@option{-Warray-compare} is enabled by @option{-Wall}.
-
-@item -Warray-parameter
-@itemx -Warray-parameter=@var{n}
-@opindex Wno-array-parameter
-Warn about redeclarations of functions involving arguments of array or
-pointer types of inconsistent kinds or forms, and enable the detection
-of out-of-bounds accesses to such parameters by warnings such as
-@option{-Warray-bounds}.
-
-If the first function declaration uses the array form the bound specified
-in the array is assumed to be the minimum number of elements expected to
-be provided in calls to the function and the maximum number of elements
-accessed by it. Failing to provide arguments of sufficient size or accessing
-more than the maximum number of elements may be diagnosed by warnings such
-as @option{-Warray-bounds}. At level 1 the warning diagnoses inconsistencies
-involving array parameters declared using the @code{T[static N]} form.
-
-For example, the warning triggers for the following redeclarations because
-the first one allows an array of any size to be passed to @code{f} while
-the second one with the keyword @code{static} specifies that the array
-argument must have at least four elements.
-
-@smallexample
-void f (int[static 4]);
-void f (int[]); // warning (inconsistent array form)
-
-void g (void)
-@{
- int *p = (int *)malloc (4);
- f (p); // warning (array too small)
- @dots{}
-@}
-@end smallexample
-
-At level 2 the warning also triggers for redeclarations involving any other
-inconsistency in array or pointer argument forms denoting array sizes.
-Pointers and arrays of unspecified bound are considered equivalent and do
-not trigger a warning.
-
-@smallexample
-void g (int*);
-void g (int[]); // no warning
-void g (int[8]); // warning (inconsistent array bound)
-@end smallexample
-
-@option{-Warray-parameter=2} is included in @option{-Wall}. The
-@option{-Wvla-parameter} option triggers warnings for similar inconsistencies
-involving Variable Length Array arguments.
-
-@item -Wattribute-alias=@var{n}
-@itemx -Wno-attribute-alias
-@opindex Wattribute-alias
-@opindex Wno-attribute-alias
-Warn about declarations using the @code{alias} and similar attributes whose
-target is incompatible with the type of the alias.
-@xref{Function Attributes,,Declaring Attributes of Functions}.
-
-@table @gcctabopt
-@item -Wattribute-alias=1
-The default warning level of the @option{-Wattribute-alias} option diagnoses
-incompatibilities between the type of the alias declaration and that of its
-target. Such incompatibilities are typically indicative of bugs.
-
-@item -Wattribute-alias=2
-
-At this level @option{-Wattribute-alias} also diagnoses cases where
-the attributes of the alias declaration are more restrictive than the
-attributes applied to its target. These mismatches can potentially
-result in incorrect code generation. In other cases they may be
-benign and could be resolved simply by adding the missing attribute to
-the target. For comparison, see the @option{-Wmissing-attributes}
-option, which controls diagnostics when the alias declaration is less
-restrictive than the target, rather than more restrictive.
-
-Attributes considered include @code{alloc_align}, @code{alloc_size},
-@code{cold}, @code{const}, @code{hot}, @code{leaf}, @code{malloc},
-@code{nonnull}, @code{noreturn}, @code{nothrow}, @code{pure},
-@code{returns_nonnull}, and @code{returns_twice}.
-@end table
-
-@option{-Wattribute-alias} is equivalent to @option{-Wattribute-alias=1}.
-This is the default. You can disable these warnings with either
-@option{-Wno-attribute-alias} or @option{-Wattribute-alias=0}.
-
-@item -Wbidi-chars=@r{[}none@r{|}unpaired@r{|}any@r{|}ucn@r{]}
-@opindex Wbidi-chars=
-@opindex Wbidi-chars
-@opindex Wno-bidi-chars
-Warn about possibly misleading UTF-8 bidirectional control characters in
-comments, string literals, character constants, and identifiers. Such
-characters can change left-to-right writing direction into right-to-left
-(and vice versa), which can cause confusion between the logical order and
-visual order. This may be dangerous; for instance, it may seem that a piece
-of code is not commented out, whereas it in fact is.
-
-There are three levels of warning supported by GCC@. The default is
-@option{-Wbidi-chars=unpaired}, which warns about improperly terminated
-bidi contexts. @option{-Wbidi-chars=none} turns the warning off.
-@option{-Wbidi-chars=any} warns about any use of bidirectional control
-characters.
-
-By default, this warning does not warn about UCNs. It is, however, possible
-to turn on such checking by using @option{-Wbidi-chars=unpaired,ucn} or
-@option{-Wbidi-chars=any,ucn}. Using @option{-Wbidi-chars=ucn} is valid,
-and is equivalent to @option{-Wbidi-chars=unpaired,ucn}, if no previous
-@option{-Wbidi-chars=any} was specified.
-
-@item -Wbool-compare
-@opindex Wno-bool-compare
-@opindex Wbool-compare
-Warn about boolean expression compared with an integer value different from
-@code{true}/@code{false}. For instance, the following comparison is
-always false:
-@smallexample
-int n = 5;
-@dots{}
-if ((n > 1) == 2) @{ @dots{} @}
-@end smallexample
-This warning is enabled by @option{-Wall}.
-
-@item -Wbool-operation
-@opindex Wno-bool-operation
-@opindex Wbool-operation
-Warn about suspicious operations on expressions of a boolean type. For
-instance, bitwise negation of a boolean is very likely a bug in the program.
-For C, this warning also warns about incrementing or decrementing a boolean,
-which rarely makes sense. (In C++, decrementing a boolean is always invalid.
-Incrementing a boolean is invalid in C++17, and deprecated otherwise.)
-
-This warning is enabled by @option{-Wall}.
-
-@item -Wduplicated-branches
-@opindex Wno-duplicated-branches
-@opindex Wduplicated-branches
-Warn when an if-else has identical branches. This warning detects cases like
-@smallexample
-if (p != NULL)
- return 0;
-else
- return 0;
-@end smallexample
-It doesn't warn when both branches contain just a null statement. This warning
-also warn for conditional operators:
-@smallexample
- int i = x ? *p : *p;
-@end smallexample
-
-@item -Wduplicated-cond
-@opindex Wno-duplicated-cond
-@opindex Wduplicated-cond
-Warn about duplicated conditions in an if-else-if chain. For instance,
-warn for the following code:
-@smallexample
-if (p->q != NULL) @{ @dots{} @}
-else if (p->q != NULL) @{ @dots{} @}
-@end smallexample
-
-@item -Wframe-address
-@opindex Wno-frame-address
-@opindex Wframe-address
-Warn when the @samp{__builtin_frame_address} or @samp{__builtin_return_address}
-is called with an argument greater than 0. Such calls may return indeterminate
-values or crash the program. The warning is included in @option{-Wall}.
-
-@item -Wno-discarded-qualifiers @r{(C and Objective-C only)}
-@opindex Wno-discarded-qualifiers
-@opindex Wdiscarded-qualifiers
-Do not warn if type qualifiers on pointers are being discarded.
-Typically, the compiler warns if a @code{const char *} variable is
-passed to a function that takes a @code{char *} parameter. This option
-can be used to suppress such a warning.
-
-@item -Wno-discarded-array-qualifiers @r{(C and Objective-C only)}
-@opindex Wno-discarded-array-qualifiers
-@opindex Wdiscarded-array-qualifiers
-Do not warn if type qualifiers on arrays which are pointer targets
-are being discarded. Typically, the compiler warns if a
-@code{const int (*)[]} variable is passed to a function that
-takes a @code{int (*)[]} parameter. This option can be used to
-suppress such a warning.
-
-@item -Wno-incompatible-pointer-types @r{(C and Objective-C only)}
-@opindex Wno-incompatible-pointer-types
-@opindex Wincompatible-pointer-types
-Do not warn when there is a conversion between pointers that have incompatible
-types. This warning is for cases not covered by @option{-Wno-pointer-sign},
-which warns for pointer argument passing or assignment with different
-signedness.
-
-@item -Wno-int-conversion @r{(C and Objective-C only)}
-@opindex Wno-int-conversion
-@opindex Wint-conversion
-Do not warn about incompatible integer to pointer and pointer to integer
-conversions. This warning is about implicit conversions; for explicit
-conversions the warnings @option{-Wno-int-to-pointer-cast} and
-@option{-Wno-pointer-to-int-cast} may be used.
-
-@item -Wzero-length-bounds
-@opindex Wzero-length-bounds
-@opindex Wzero-length-bounds
-Warn about accesses to elements of zero-length array members that might
-overlap other members of the same object. Declaring interior zero-length
-arrays is discouraged because accesses to them are undefined. See
-@xref{Zero Length}.
-
-For example, the first two stores in function @code{bad} are diagnosed
-because the array elements overlap the subsequent members @code{b} and
-@code{c}. The third store is diagnosed by @option{-Warray-bounds}
-because it is beyond the bounds of the enclosing object.
-
-@smallexample
-struct X @{ int a[0]; int b, c; @};
-struct X x;
-
-void bad (void)
-@{
- x.a[0] = 0; // -Wzero-length-bounds
- x.a[1] = 1; // -Wzero-length-bounds
- x.a[2] = 2; // -Warray-bounds
-@}
-@end smallexample
-
-Option @option{-Wzero-length-bounds} is enabled by @option{-Warray-bounds}.
-
-@item -Wno-div-by-zero
-@opindex Wno-div-by-zero
-@opindex Wdiv-by-zero
-Do not warn about compile-time integer division by zero. Floating-point
-division by zero is not warned about, as it can be a legitimate way of
-obtaining infinities and NaNs.
-
-@item -Wsystem-headers
-@opindex Wsystem-headers
-@opindex Wno-system-headers
-@cindex warnings from system headers
-@cindex system headers, warnings from
-Print warning messages for constructs found in system header files.
-Warnings from system headers are normally suppressed, on the assumption
-that they usually do not indicate real problems and would only make the
-compiler output harder to read. Using this command-line option tells
-GCC to emit warnings from system headers as if they occurred in user
-code. However, note that using @option{-Wall} in conjunction with this
-option does @emph{not} warn about unknown pragmas in system
-headers---for that, @option{-Wunknown-pragmas} must also be used.
-
-@item -Wtautological-compare
-@opindex Wtautological-compare
-@opindex Wno-tautological-compare
-Warn if a self-comparison always evaluates to true or false. This
-warning detects various mistakes such as:
-@smallexample
-int i = 1;
-@dots{}
-if (i > i) @{ @dots{} @}
-@end smallexample
-
-This warning also warns about bitwise comparisons that always evaluate
-to true or false, for instance:
-@smallexample
-if ((a & 16) == 10) @{ @dots{} @}
-@end smallexample
-will always be false.
-
-This warning is enabled by @option{-Wall}.
-
-@item -Wtrampolines
-@opindex Wtrampolines
-@opindex Wno-trampolines
-Warn about trampolines generated for pointers to nested functions.
-A trampoline is a small piece of data or code that is created at run
-time on the stack when the address of a nested function is taken, and is
-used to call the nested function indirectly. For some targets, it is
-made up of data only and thus requires no special treatment. But, for
-most targets, it is made up of code and thus requires the stack to be
-made executable in order for the program to work properly.
-
-@item -Wfloat-equal
-@opindex Wfloat-equal
-@opindex Wno-float-equal
-Warn if floating-point values are used in equality comparisons.
-
-The idea behind this is that sometimes it is convenient (for the
-programmer) to consider floating-point values as approximations to
-infinitely precise real numbers. If you are doing this, then you need
-to compute (by analyzing the code, or in some other way) the maximum or
-likely maximum error that the computation introduces, and allow for it
-when performing comparisons (and when producing output, but that's a
-different problem). In particular, instead of testing for equality, you
-should check to see whether the two values have ranges that overlap; and
-this is done with the relational operators, so equality comparisons are
-probably mistaken.
-
-@item -Wtraditional @r{(C and Objective-C only)}
-@opindex Wtraditional
-@opindex Wno-traditional
-Warn about certain constructs that behave differently in traditional and
-ISO C@. Also warn about ISO C constructs that have no traditional C
-equivalent, and/or problematic constructs that should be avoided.
-
-@itemize @bullet
-@item
-Macro parameters that appear within string literals in the macro body.
-In traditional C macro replacement takes place within string literals,
-but in ISO C it does not.
-
-@item
-In traditional C, some preprocessor directives did not exist.
-Traditional preprocessors only considered a line to be a directive
-if the @samp{#} appeared in column 1 on the line. Therefore
-@option{-Wtraditional} warns about directives that traditional C
-understands but ignores because the @samp{#} does not appear as the
-first character on the line. It also suggests you hide directives like
-@code{#pragma} not understood by traditional C by indenting them. Some
-traditional implementations do not recognize @code{#elif}, so this option
-suggests avoiding it altogether.
-
-@item
-A function-like macro that appears without arguments.
-
-@item
-The unary plus operator.
-
-@item
-The @samp{U} integer constant suffix, or the @samp{F} or @samp{L} floating-point
-constant suffixes. (Traditional C does support the @samp{L} suffix on integer
-constants.) Note, these suffixes appear in macros defined in the system
-headers of most modern systems, e.g.@: the @samp{_MIN}/@samp{_MAX} macros in @code{<limits.h>}.
-Use of these macros in user code might normally lead to spurious
-warnings, however GCC's integrated preprocessor has enough context to
-avoid warning in these cases.
-
-@item
-A function declared external in one block and then used after the end of
-the block.
-
-@item
-A @code{switch} statement has an operand of type @code{long}.
-
-@item
-A non-@code{static} function declaration follows a @code{static} one.
-This construct is not accepted by some traditional C compilers.
-
-@item
-The ISO type of an integer constant has a different width or
-signedness from its traditional type. This warning is only issued if
-the base of the constant is ten. I.e.@: hexadecimal or octal values, which
-typically represent bit patterns, are not warned about.
-
-@item
-Usage of ISO string concatenation is detected.
-
-@item
-Initialization of automatic aggregates.
-
-@item
-Identifier conflicts with labels. Traditional C lacks a separate
-namespace for labels.
-
-@item
-Initialization of unions. If the initializer is zero, the warning is
-omitted. This is done under the assumption that the zero initializer in
-user code appears conditioned on e.g.@: @code{__STDC__} to avoid missing
-initializer warnings and relies on default initialization to zero in the
-traditional C case.
-
-@item
-Conversions by prototypes between fixed/floating-point values and vice
-versa. The absence of these prototypes when compiling with traditional
-C causes serious problems. This is a subset of the possible
-conversion warnings; for the full set use @option{-Wtraditional-conversion}.
-
-@item
-Use of ISO C style function definitions. This warning intentionally is
-@emph{not} issued for prototype declarations or variadic functions
-because these ISO C features appear in your code when using
-libiberty's traditional C compatibility macros, @code{PARAMS} and
-@code{VPARAMS}. This warning is also bypassed for nested functions
-because that feature is already a GCC extension and thus not relevant to
-traditional C compatibility.
-@end itemize
-
-@item -Wtraditional-conversion @r{(C and Objective-C only)}
-@opindex Wtraditional-conversion
-@opindex Wno-traditional-conversion
-Warn if a prototype causes a type conversion that is different from what
-would happen to the same argument in the absence of a prototype. This
-includes conversions of fixed point to floating and vice versa, and
-conversions changing the width or signedness of a fixed-point argument
-except when the same as the default promotion.
-
-@item -Wdeclaration-after-statement @r{(C and Objective-C only)}
-@opindex Wdeclaration-after-statement
-@opindex Wno-declaration-after-statement
-Warn when a declaration is found after a statement in a block. This
-construct, known from C++, was introduced with ISO C99 and is by default
-allowed in GCC@. It is not supported by ISO C90. @xref{Mixed Labels and Declarations}.
-
-@item -Wshadow
-@opindex Wshadow
-@opindex Wno-shadow
-Warn whenever a local variable or type declaration shadows another
-variable, parameter, type, class member (in C++), or instance variable
-(in Objective-C) or whenever a built-in function is shadowed. Note
-that in C++, the compiler warns if a local variable shadows an
-explicit typedef, but not if it shadows a struct/class/enum.
-If this warning is enabled, it includes also all instances of
-local shadowing. This means that @option{-Wno-shadow=local}
-and @option{-Wno-shadow=compatible-local} are ignored when
-@option{-Wshadow} is used.
-Same as @option{-Wshadow=global}.
-
-@item -Wno-shadow-ivar @r{(Objective-C only)}
-@opindex Wno-shadow-ivar
-@opindex Wshadow-ivar
-Do not warn whenever a local variable shadows an instance variable in an
-Objective-C method.
-
-@item -Wshadow=global
-@opindex Wshadow=global
-Warn for any shadowing.
-Same as @option{-Wshadow}.
-
-@item -Wshadow=local
-@opindex Wshadow=local
-Warn when a local variable shadows another local variable or parameter.
-
-@item -Wshadow=compatible-local
-@opindex Wshadow=compatible-local
-Warn when a local variable shadows another local variable or parameter
-whose type is compatible with that of the shadowing variable. In C++,
-type compatibility here means the type of the shadowing variable can be
-converted to that of the shadowed variable. The creation of this flag
-(in addition to @option{-Wshadow=local}) is based on the idea that when
-a local variable shadows another one of incompatible type, it is most
-likely intentional, not a bug or typo, as shown in the following example:
-
-@smallexample
-@group
-for (SomeIterator i = SomeObj.begin(); i != SomeObj.end(); ++i)
-@{
- for (int i = 0; i < N; ++i)
- @{
- ...
- @}
- ...
-@}
-@end group
-@end smallexample
-
-Since the two variable @code{i} in the example above have incompatible types,
-enabling only @option{-Wshadow=compatible-local} does not emit a warning.
-Because their types are incompatible, if a programmer accidentally uses one
-in place of the other, type checking is expected to catch that and emit an
-error or warning. Use of this flag instead of @option{-Wshadow=local} can
-possibly reduce the number of warnings triggered by intentional shadowing.
-Note that this also means that shadowing @code{const char *i} by
-@code{char *i} does not emit a warning.
-
-This warning is also enabled by @option{-Wshadow=local}.
-
-@item -Wlarger-than=@var{byte-size}
-@opindex Wlarger-than=
-@opindex Wlarger-than-@var{byte-size}
-Warn whenever an object is defined whose size exceeds @var{byte-size}.
-@option{-Wlarger-than=}@samp{PTRDIFF_MAX} is enabled by default.
-Warnings controlled by the option can be disabled either by specifying
-@var{byte-size} of @samp{SIZE_MAX} or more or by @option{-Wno-larger-than}.
-
-Also warn for calls to bounded functions such as @code{memchr} or
-@code{strnlen} that specify a bound greater than the largest possible
-object, which is @samp{PTRDIFF_MAX} bytes by default. These warnings
-can only be disabled by @option{-Wno-larger-than}.
-
-@item -Wno-larger-than
-@opindex Wno-larger-than
-Disable @option{-Wlarger-than=} warnings. The option is equivalent
-to @option{-Wlarger-than=}@samp{SIZE_MAX} or larger.
-
-@item -Wframe-larger-than=@var{byte-size}
-@opindex Wframe-larger-than=
-@opindex Wno-frame-larger-than
-Warn if the size of a function frame exceeds @var{byte-size}.
-The computation done to determine the stack frame size is approximate
-and not conservative.
-The actual requirements may be somewhat greater than @var{byte-size}
-even if you do not get a warning. In addition, any space allocated
-via @code{alloca}, variable-length arrays, or related constructs
-is not included by the compiler when determining
-whether or not to issue a warning.
-@option{-Wframe-larger-than=}@samp{PTRDIFF_MAX} is enabled by default.
-Warnings controlled by the option can be disabled either by specifying
-@var{byte-size} of @samp{SIZE_MAX} or more or by
-@option{-Wno-frame-larger-than}.
-
-@item -Wno-frame-larger-than
-@opindex Wno-frame-larger-than
-Disable @option{-Wframe-larger-than=} warnings. The option is equivalent
-to @option{-Wframe-larger-than=}@samp{SIZE_MAX} or larger.
-
-@item -Wfree-nonheap-object
-@opindex Wfree-nonheap-object
-@opindex Wno-free-nonheap-object
-Warn when attempting to deallocate an object that was either not allocated
-on the heap, or by using a pointer that was not returned from a prior call
-to the corresponding allocation function. For example, because the call
-to @code{stpcpy} returns a pointer to the terminating nul character and
-not to the beginning of the object, the call to @code{free} below is
-diagnosed.
-
-@smallexample
-void f (char *p)
-@{
- p = stpcpy (p, "abc");
- // ...
- free (p); // warning
-@}
-@end smallexample
-
-@option{-Wfree-nonheap-object} is included in @option{-Wall}.
-
-@item -Wstack-usage=@var{byte-size}
-@opindex Wstack-usage
-@opindex Wno-stack-usage
-Warn if the stack usage of a function might exceed @var{byte-size}.
-The computation done to determine the stack usage is conservative.
-Any space allocated via @code{alloca}, variable-length arrays, or related
-constructs is included by the compiler when determining whether or not to
-issue a warning.
-
-The message is in keeping with the output of @option{-fstack-usage}.
-
-@itemize
-@item
-If the stack usage is fully static but exceeds the specified amount, it's:
-
-@smallexample
- warning: stack usage is 1120 bytes
-@end smallexample
-@item
-If the stack usage is (partly) dynamic but bounded, it's:
-
-@smallexample
- warning: stack usage might be 1648 bytes
-@end smallexample
-@item
-If the stack usage is (partly) dynamic and not bounded, it's:
-
-@smallexample
- warning: stack usage might be unbounded
-@end smallexample
-@end itemize
-
-@option{-Wstack-usage=}@samp{PTRDIFF_MAX} is enabled by default.
-Warnings controlled by the option can be disabled either by specifying
-@var{byte-size} of @samp{SIZE_MAX} or more or by
-@option{-Wno-stack-usage}.
-
-@item -Wno-stack-usage
-@opindex Wno-stack-usage
-Disable @option{-Wstack-usage=} warnings. The option is equivalent
-to @option{-Wstack-usage=}@samp{SIZE_MAX} or larger.
-
-@item -Wunsafe-loop-optimizations
-@opindex Wunsafe-loop-optimizations
-@opindex Wno-unsafe-loop-optimizations
-Warn if the loop cannot be optimized because the compiler cannot
-assume anything on the bounds of the loop indices. With
-@option{-funsafe-loop-optimizations} warn if the compiler makes
-such assumptions.
-
-@item -Wno-pedantic-ms-format @r{(MinGW targets only)}
-@opindex Wno-pedantic-ms-format
-@opindex Wpedantic-ms-format
-When used in combination with @option{-Wformat}
-and @option{-pedantic} without GNU extensions, this option
-disables the warnings about non-ISO @code{printf} / @code{scanf} format
-width specifiers @code{I32}, @code{I64}, and @code{I} used on Windows targets,
-which depend on the MS runtime.
-
-@item -Wpointer-arith
-@opindex Wpointer-arith
-@opindex Wno-pointer-arith
-Warn about anything that depends on the ``size of'' a function type or
-of @code{void}. GNU C assigns these types a size of 1, for
-convenience in calculations with @code{void *} pointers and pointers
-to functions. In C++, warn also when an arithmetic operation involves
-@code{NULL}. This warning is also enabled by @option{-Wpedantic}.
-
-@item -Wno-pointer-compare
-@opindex Wpointer-compare
-@opindex Wno-pointer-compare
-Do not warn if a pointer is compared with a zero character constant.
-This usually
-means that the pointer was meant to be dereferenced. For example:
-
-@smallexample
-const char *p = foo ();
-if (p == '\0')
- return 42;
-@end smallexample
-
-Note that the code above is invalid in C++11.
-
-This warning is enabled by default.
-
-@item -Wtsan
-@opindex Wtsan
-@opindex Wno-tsan
-Warn about unsupported features in ThreadSanitizer.
-
-ThreadSanitizer does not support @code{std::atomic_thread_fence} and
-can report false positives.
-
-This warning is enabled by default.
-
-@item -Wtype-limits
-@opindex Wtype-limits
-@opindex Wno-type-limits
-Warn if a comparison is always true or always false due to the limited
-range of the data type, but do not warn for constant expressions. For
-example, warn if an unsigned variable is compared against zero with
-@code{<} or @code{>=}. This warning is also enabled by
-@option{-Wextra}.
-
-@item -Wabsolute-value @r{(C and Objective-C only)}
-@opindex Wabsolute-value
-@opindex Wno-absolute-value
-Warn for calls to standard functions that compute the absolute value
-of an argument when a more appropriate standard function is available.
-For example, calling @code{abs(3.14)} triggers the warning because the
-appropriate function to call to compute the absolute value of a double
-argument is @code{fabs}. The option also triggers warnings when the
-argument in a call to such a function has an unsigned type. This
-warning can be suppressed with an explicit type cast and it is also
-enabled by @option{-Wextra}.
-
-@include cppwarnopts.texi
-
-@item -Wbad-function-cast @r{(C and Objective-C only)}
-@opindex Wbad-function-cast
-@opindex Wno-bad-function-cast
-Warn when a function call is cast to a non-matching type.
-For example, warn if a call to a function returning an integer type
-is cast to a pointer type.
-
-@item -Wc90-c99-compat @r{(C and Objective-C only)}
-@opindex Wc90-c99-compat
-@opindex Wno-c90-c99-compat
-Warn about features not present in ISO C90, but present in ISO C99.
-For instance, warn about use of variable length arrays, @code{long long}
-type, @code{bool} type, compound literals, designated initializers, and so
-on. This option is independent of the standards mode. Warnings are disabled
-in the expression that follows @code{__extension__}.
-
-@item -Wc99-c11-compat @r{(C and Objective-C only)}
-@opindex Wc99-c11-compat
-@opindex Wno-c99-c11-compat
-Warn about features not present in ISO C99, but present in ISO C11.
-For instance, warn about use of anonymous structures and unions,
-@code{_Atomic} type qualifier, @code{_Thread_local} storage-class specifier,
-@code{_Alignas} specifier, @code{Alignof} operator, @code{_Generic} keyword,
-and so on. This option is independent of the standards mode. Warnings are
-disabled in the expression that follows @code{__extension__}.
-
-@item -Wc11-c2x-compat @r{(C and Objective-C only)}
-@opindex Wc11-c2x-compat
-@opindex Wno-c11-c2x-compat
-Warn about features not present in ISO C11, but present in ISO C2X.
-For instance, warn about omitting the string in @code{_Static_assert},
-use of @samp{[[]]} syntax for attributes, use of decimal
-floating-point types, and so on. This option is independent of the
-standards mode. Warnings are disabled in the expression that follows
-@code{__extension__}.
-
-@item -Wc++-compat @r{(C and Objective-C only)}
-@opindex Wc++-compat
-@opindex Wno-c++-compat
-Warn about ISO C constructs that are outside of the common subset of
-ISO C and ISO C++, e.g.@: request for implicit conversion from
-@code{void *} to a pointer to non-@code{void} type.
-
-@item -Wc++11-compat @r{(C++ and Objective-C++ only)}
-@opindex Wc++11-compat
-@opindex Wno-c++11-compat
-Warn about C++ constructs whose meaning differs between ISO C++ 1998
-and ISO C++ 2011, e.g., identifiers in ISO C++ 1998 that are keywords
-in ISO C++ 2011. This warning turns on @option{-Wnarrowing} and is
-enabled by @option{-Wall}.
-
-@item -Wc++14-compat @r{(C++ and Objective-C++ only)}
-@opindex Wc++14-compat
-@opindex Wno-c++14-compat
-Warn about C++ constructs whose meaning differs between ISO C++ 2011
-and ISO C++ 2014. This warning is enabled by @option{-Wall}.
-
-@item -Wc++17-compat @r{(C++ and Objective-C++ only)}
-@opindex Wc++17-compat
-@opindex Wno-c++17-compat
-Warn about C++ constructs whose meaning differs between ISO C++ 2014
-and ISO C++ 2017. This warning is enabled by @option{-Wall}.
-
-@item -Wc++20-compat @r{(C++ and Objective-C++ only)}
-@opindex Wc++20-compat
-@opindex Wno-c++20-compat
-Warn about C++ constructs whose meaning differs between ISO C++ 2017
-and ISO C++ 2020. This warning is enabled by @option{-Wall}.
-
-@item -Wno-c++11-extensions @r{(C++ and Objective-C++ only)}
-@opindex Wc++11-extensions
-@opindex Wno-c++11-extensions
-Do not warn about C++11 constructs in code being compiled using
-an older C++ standard. Even without this option, some C++11 constructs
-will only be diagnosed if @option{-Wpedantic} is used.
-
-@item -Wno-c++14-extensions @r{(C++ and Objective-C++ only)}
-@opindex Wc++14-extensions
-@opindex Wno-c++14-extensions
-Do not warn about C++14 constructs in code being compiled using
-an older C++ standard. Even without this option, some C++14 constructs
-will only be diagnosed if @option{-Wpedantic} is used.
-
-@item -Wno-c++17-extensions @r{(C++ and Objective-C++ only)}
-@opindex Wc++17-extensions
-@opindex Wno-c++17-extensions
-Do not warn about C++17 constructs in code being compiled using
-an older C++ standard. Even without this option, some C++17 constructs
-will only be diagnosed if @option{-Wpedantic} is used.
-
-@item -Wno-c++20-extensions @r{(C++ and Objective-C++ only)}
-@opindex Wc++20-extensions
-@opindex Wno-c++20-extensions
-Do not warn about C++20 constructs in code being compiled using
-an older C++ standard. Even without this option, some C++20 constructs
-will only be diagnosed if @option{-Wpedantic} is used.
-
-@item -Wno-c++23-extensions @r{(C++ and Objective-C++ only)}
-@opindex Wc++23-extensions
-@opindex Wno-c++23-extensions
-Do not warn about C++23 constructs in code being compiled using
-an older C++ standard. Even without this option, some C++23 constructs
-will only be diagnosed if @option{-Wpedantic} is used.
-
-@item -Wcast-qual
-@opindex Wcast-qual
-@opindex Wno-cast-qual
-Warn whenever a pointer is cast so as to remove a type qualifier from
-the target type. For example, warn if a @code{const char *} is cast
-to an ordinary @code{char *}.
-
-Also warn when making a cast that introduces a type qualifier in an
-unsafe way. For example, casting @code{char **} to @code{const char **}
-is unsafe, as in this example:
-
-@smallexample
- /* p is char ** value. */
- const char **q = (const char **) p;
- /* Assignment of readonly string to const char * is OK. */
- *q = "string";
- /* Now char** pointer points to read-only memory. */
- **p = 'b';
-@end smallexample
-
-@item -Wcast-align
-@opindex Wcast-align
-@opindex Wno-cast-align
-Warn whenever a pointer is cast such that the required alignment of the
-target is increased. For example, warn if a @code{char *} is cast to
-an @code{int *} on machines where integers can only be accessed at
-two- or four-byte boundaries.
-
-@item -Wcast-align=strict
-@opindex Wcast-align=strict
-Warn whenever a pointer is cast such that the required alignment of the
-target is increased. For example, warn if a @code{char *} is cast to
-an @code{int *} regardless of the target machine.
-
-@item -Wcast-function-type
-@opindex Wcast-function-type
-@opindex Wno-cast-function-type
-Warn when a function pointer is cast to an incompatible function pointer.
-In a cast involving function types with a variable argument list only
-the types of initial arguments that are provided are considered.
-Any parameter of pointer-type matches any other pointer-type. Any benign
-differences in integral types are ignored, like @code{int} vs.@: @code{long}
-on ILP32 targets. Likewise type qualifiers are ignored. The function
-type @code{void (*) (void)} is special and matches everything, which can
-be used to suppress this warning.
-In a cast involving pointer to member types this warning warns whenever
-the type cast is changing the pointer to member type.
-This warning is enabled by @option{-Wextra}.
-
-@item -Wwrite-strings
-@opindex Wwrite-strings
-@opindex Wno-write-strings
-When compiling C, give string constants the type @code{const
-char[@var{length}]} so that copying the address of one into a
-non-@code{const} @code{char *} pointer produces a warning. These
-warnings help you find at compile time code that can try to write
-into a string constant, but only if you have been very careful about
-using @code{const} in declarations and prototypes. Otherwise, it is
-just a nuisance. This is why we did not make @option{-Wall} request
-these warnings.
-
-When compiling C++, warn about the deprecated conversion from string
-literals to @code{char *}. This warning is enabled by default for C++
-programs.
-
-@item -Wclobbered
-@opindex Wclobbered
-@opindex Wno-clobbered
-Warn for variables that might be changed by @code{longjmp} or
-@code{vfork}. This warning is also enabled by @option{-Wextra}.
-
-@item -Wconversion
-@opindex Wconversion
-@opindex Wno-conversion
-Warn for implicit conversions that may alter a value. This includes
-conversions between real and integer, like @code{abs (x)} when
-@code{x} is @code{double}; conversions between signed and unsigned,
-like @code{unsigned ui = -1}; and conversions to smaller types, like
-@code{sqrtf (M_PI)}. Do not warn for explicit casts like @code{abs
-((int) x)} and @code{ui = (unsigned) -1}, or if the value is not
-changed by the conversion like in @code{abs (2.0)}. Warnings about
-conversions between signed and unsigned integers can be disabled by
-using @option{-Wno-sign-conversion}.
-
-For C++, also warn for confusing overload resolution for user-defined
-conversions; and conversions that never use a type conversion
-operator: conversions to @code{void}, the same type, a base class or a
-reference to them. Warnings about conversions between signed and
-unsigned integers are disabled by default in C++ unless
-@option{-Wsign-conversion} is explicitly enabled.
-
-Warnings about conversion from arithmetic on a small type back to that
-type are only given with @option{-Warith-conversion}.
-
-@item -Wdangling-else
-@opindex Wdangling-else
-@opindex Wno-dangling-else
-Warn about constructions where there may be confusion to which
-@code{if} statement an @code{else} branch belongs. Here is an example of
-such a case:
-
-@smallexample
-@group
-@{
- if (a)
- if (b)
- foo ();
- else
- bar ();
-@}
-@end group
-@end smallexample
-
-In C/C++, every @code{else} branch belongs to the innermost possible
-@code{if} statement, which in this example is @code{if (b)}. This is
-often not what the programmer expected, as illustrated in the above
-example by indentation the programmer chose. When there is the
-potential for this confusion, GCC issues a warning when this flag
-is specified. To eliminate the warning, add explicit braces around
-the innermost @code{if} statement so there is no way the @code{else}
-can belong to the enclosing @code{if}. The resulting code
-looks like this:
-
-@smallexample
-@group
-@{
- if (a)
- @{
- if (b)
- foo ();
- else
- bar ();
- @}
-@}
-@end group
-@end smallexample
-
-This warning is enabled by @option{-Wparentheses}.
-
-@item -Wdangling-pointer
-@itemx -Wdangling-pointer=@var{n}
-@opindex Wdangling-pointer
-@opindex Wno-dangling-pointer
-Warn about uses of pointers (or C++ references) to objects with automatic
-storage duration after their lifetime has ended. This includes local
-variables declared in nested blocks, compound literals and other unnamed
-temporary objects. In addition, warn about storing the address of such
-objects in escaped pointers. The warning is enabled at all optimization
-levels but may yield different results with optimization than without.
-
-@table @gcctabopt
-@item -Wdangling-pointer=1
-At level 1 the warning diagnoses only unconditional uses of dangling pointers.
-For example
-@smallexample
-int f (int c1, int c2, x)
-@{
- char *p = strchr ((char[])@{ c1, c2 @}, c3);
- return p ? *p : 'x'; // warning: dangling pointer to a compound literal
-@}
-@end smallexample
-In the following function the store of the address of the local variable
-@code{x} in the escaped pointer @code{*p} also triggers the warning.
-@smallexample
-void g (int **p)
-@{
- int x = 7;
- *p = &x; // warning: storing the address of a local variable in *p
-@}
-@end smallexample
-
-@item -Wdangling-pointer=2
-At level 2, in addition to unconditional uses the warning also diagnoses
-conditional uses of dangling pointers.
-
-For example, because the array @var{a} in the following function is out of
-scope when the pointer @var{s} that was set to point is used, the warning
-triggers at this level.
-
-@smallexample
-void f (char *s)
-@{
- if (!s)
- @{
- char a[12] = "tmpname";
- s = a;
- @}
- strcat (s, ".tmp"); // warning: dangling pointer to a may be used
- ...
-@}
-@end smallexample
-@end table
-
-@option{-Wdangling-pointer=2} is included in @option{-Wall}.
-
-@item -Wdate-time
-@opindex Wdate-time
-@opindex Wno-date-time
-Warn when macros @code{__TIME__}, @code{__DATE__} or @code{__TIMESTAMP__}
-are encountered as they might prevent bit-wise-identical reproducible
-compilations.
-
-@item -Wempty-body
-@opindex Wempty-body
-@opindex Wno-empty-body
-Warn if an empty body occurs in an @code{if}, @code{else} or @code{do
-while} statement. This warning is also enabled by @option{-Wextra}.
-
-@item -Wno-endif-labels
-@opindex Wendif-labels
-@opindex Wno-endif-labels
-Do not warn about stray tokens after @code{#else} and @code{#endif}.
-
-@item -Wenum-compare
-@opindex Wenum-compare
-@opindex Wno-enum-compare
-Warn about a comparison between values of different enumerated types.
-In C++ enumerated type mismatches in conditional expressions are also
-diagnosed and the warning is enabled by default. In C this warning is
-enabled by @option{-Wall}.
-
-@item -Wenum-conversion
-@opindex Wenum-conversion
-@opindex Wno-enum-conversion
-Warn when a value of enumerated type is implicitly converted to a
-different enumerated type. This warning is enabled by @option{-Wextra}
-in C@.
-
-@item -Wenum-int-mismatch @r{(C and Objective-C only)}
-@opindex Wenum-int-mismatch
-@opindex Wno-enum-int-mismatch
-Warn about mismatches between an enumerated type and an integer type in
-declarations. For example:
-
-@smallexample
-enum E @{ l = -1, z = 0, g = 1 @};
-int foo(void);
-enum E foo(void);
-@end smallexample
-
-In C, an enumerated type is compatible with @code{char}, a signed
-integer type, or an unsigned integer type. However, since the choice
-of the underlying type of an enumerated type is implementation-defined,
-such mismatches may cause portability issues. In C++, such mismatches
-are an error. In C, this warning is enabled by @option{-Wall} and
-@option{-Wc++-compat}.
-
-@item -Wjump-misses-init @r{(C, Objective-C only)}
-@opindex Wjump-misses-init
-@opindex Wno-jump-misses-init
-Warn if a @code{goto} statement or a @code{switch} statement jumps
-forward across the initialization of a variable, or jumps backward to a
-label after the variable has been initialized. This only warns about
-variables that are initialized when they are declared. This warning is
-only supported for C and Objective-C; in C++ this sort of branch is an
-error in any case.
-
-@option{-Wjump-misses-init} is included in @option{-Wc++-compat}. It
-can be disabled with the @option{-Wno-jump-misses-init} option.
-
-@item -Wsign-compare
-@opindex Wsign-compare
-@opindex Wno-sign-compare
-@cindex warning for comparison of signed and unsigned values
-@cindex comparison of signed and unsigned values, warning
-@cindex signed and unsigned values, comparison warning
-Warn when a comparison between signed and unsigned values could produce
-an incorrect result when the signed value is converted to unsigned.
-In C++, this warning is also enabled by @option{-Wall}. In C, it is
-also enabled by @option{-Wextra}.
-
-@item -Wsign-conversion
-@opindex Wsign-conversion
-@opindex Wno-sign-conversion
-Warn for implicit conversions that may change the sign of an integer
-value, like assigning a signed integer expression to an unsigned
-integer variable. An explicit cast silences the warning. In C, this
-option is enabled also by @option{-Wconversion}.
-
-@item -Wfloat-conversion
-@opindex Wfloat-conversion
-@opindex Wno-float-conversion
-Warn for implicit conversions that reduce the precision of a real value.
-This includes conversions from real to integer, and from higher precision
-real to lower precision real values. This option is also enabled by
-@option{-Wconversion}.
-
-@item -Wno-scalar-storage-order
-@opindex Wno-scalar-storage-order
-@opindex Wscalar-storage-order
-Do not warn on suspicious constructs involving reverse scalar storage order.
-
-@item -Wsizeof-array-div
-@opindex Wsizeof-array-div
-@opindex Wno-sizeof-array-div
-Warn about divisions of two sizeof operators when the first one is applied
-to an array and the divisor does not equal the size of the array element.
-In such a case, the computation will not yield the number of elements in the
-array, which is likely what the user intended. This warning warns e.g. about
-@smallexample
-int fn ()
-@{
- int arr[10];
- return sizeof (arr) / sizeof (short);
-@}
-@end smallexample
-
-This warning is enabled by @option{-Wall}.
-
-@item -Wsizeof-pointer-div
-@opindex Wsizeof-pointer-div
-@opindex Wno-sizeof-pointer-div
-Warn for suspicious divisions of two sizeof expressions that divide
-the pointer size by the element size, which is the usual way to compute
-the array size but won't work out correctly with pointers. This warning
-warns e.g.@: about @code{sizeof (ptr) / sizeof (ptr[0])} if @code{ptr} is
-not an array, but a pointer. This warning is enabled by @option{-Wall}.
-
-@item -Wsizeof-pointer-memaccess
-@opindex Wsizeof-pointer-memaccess
-@opindex Wno-sizeof-pointer-memaccess
-Warn for suspicious length parameters to certain string and memory built-in
-functions if the argument uses @code{sizeof}. This warning triggers for
-example for @code{memset (ptr, 0, sizeof (ptr));} if @code{ptr} is not
-an array, but a pointer, and suggests a possible fix, or about
-@code{memcpy (&foo, ptr, sizeof (&foo));}. @option{-Wsizeof-pointer-memaccess}
-also warns about calls to bounded string copy functions like @code{strncat}
-or @code{strncpy} that specify as the bound a @code{sizeof} expression of
-the source array. For example, in the following function the call to
-@code{strncat} specifies the size of the source string as the bound. That
-is almost certainly a mistake and so the call is diagnosed.
-@smallexample
-void make_file (const char *name)
-@{
- char path[PATH_MAX];
- strncpy (path, name, sizeof path - 1);
- strncat (path, ".text", sizeof ".text");
- @dots{}
-@}
-@end smallexample
-
-The @option{-Wsizeof-pointer-memaccess} option is enabled by @option{-Wall}.
-
-@item -Wno-sizeof-array-argument
-@opindex Wsizeof-array-argument
-@opindex Wno-sizeof-array-argument
-Do not warn when the @code{sizeof} operator is applied to a parameter that is
-declared as an array in a function definition. This warning is enabled by
-default for C and C++ programs.
-
-@item -Wmemset-elt-size
-@opindex Wmemset-elt-size
-@opindex Wno-memset-elt-size
-Warn for suspicious calls to the @code{memset} built-in function, if the
-first argument references an array, and the third argument is a number
-equal to the number of elements, but not equal to the size of the array
-in memory. This indicates that the user has omitted a multiplication by
-the element size. This warning is enabled by @option{-Wall}.
-
-@item -Wmemset-transposed-args
-@opindex Wmemset-transposed-args
-@opindex Wno-memset-transposed-args
-Warn for suspicious calls to the @code{memset} built-in function where
-the second argument is not zero and the third argument is zero. For
-example, the call @code{memset (buf, sizeof buf, 0)} is diagnosed because
-@code{memset (buf, 0, sizeof buf)} was meant instead. The diagnostic
-is only emitted if the third argument is a literal zero. Otherwise, if
-it is an expression that is folded to zero, or a cast of zero to some
-type, it is far less likely that the arguments have been mistakenly
-transposed and no warning is emitted. This warning is enabled
-by @option{-Wall}.
-
-@item -Waddress
-@opindex Waddress
-@opindex Wno-address
-Warn about suspicious uses of address expressions. These include comparing
-the address of a function or a declared object to the null pointer constant
-such as in
-@smallexample
-void f (void);
-void g (void)
-@{
- if (!f) // warning: expression evaluates to false
- abort ();
-@}
-@end smallexample
-comparisons of a pointer to a string literal, such as in
-@smallexample
-void f (const char *x)
-@{
- if (x == "abc") // warning: expression evaluates to false
- puts ("equal");
-@}
-@end smallexample
-and tests of the results of pointer addition or subtraction for equality
-to null, such as in
-@smallexample
-void f (const int *p, int i)
-@{
- return p + i == NULL;
-@}
-@end smallexample
-Such uses typically indicate a programmer error: the address of most
-functions and objects necessarily evaluates to true (the exception are
-weak symbols), so their use in a conditional might indicate missing
-parentheses in a function call or a missing dereference in an array
-expression. The subset of the warning for object pointers can be
-suppressed by casting the pointer operand to an integer type such
-as @code{intptr_t} or @code{uintptr_t}.
-Comparisons against string literals result in unspecified behavior
-and are not portable, and suggest the intent was to call @code{strcmp}.
-The warning is suppressed if the suspicious expression is the result
-of macro expansion.
-@option{-Waddress} warning is enabled by @option{-Wall}.
-
-@item -Wno-address-of-packed-member
-@opindex Waddress-of-packed-member
-@opindex Wno-address-of-packed-member
-Do not warn when the address of packed member of struct or union is taken,
-which usually results in an unaligned pointer value. This is
-enabled by default.
-
-@item -Wlogical-op
-@opindex Wlogical-op
-@opindex Wno-logical-op
-Warn about suspicious uses of logical operators in expressions.
-This includes using logical operators in contexts where a
-bit-wise operator is likely to be expected. Also warns when
-the operands of a logical operator are the same:
-@smallexample
-extern int a;
-if (a < 0 && a < 0) @{ @dots{} @}
-@end smallexample
-
-@item -Wlogical-not-parentheses
-@opindex Wlogical-not-parentheses
-@opindex Wno-logical-not-parentheses
-Warn about logical not used on the left hand side operand of a comparison.
-This option does not warn if the right operand is considered to be a boolean
-expression. Its purpose is to detect suspicious code like the following:
-@smallexample
-int a;
-@dots{}
-if (!a > 1) @{ @dots{} @}
-@end smallexample
-
-It is possible to suppress the warning by wrapping the LHS into
-parentheses:
-@smallexample
-if ((!a) > 1) @{ @dots{} @}
-@end smallexample
-
-This warning is enabled by @option{-Wall}.
-
-@item -Waggregate-return
-@opindex Waggregate-return
-@opindex Wno-aggregate-return
-Warn if any functions that return structures or unions are defined or
-called. (In languages where you can return an array, this also elicits
-a warning.)
-
-@item -Wno-aggressive-loop-optimizations
-@opindex Wno-aggressive-loop-optimizations
-@opindex Waggressive-loop-optimizations
-Warn if in a loop with constant number of iterations the compiler detects
-undefined behavior in some statement during one or more of the iterations.
-
-@item -Wno-attributes
-@opindex Wno-attributes
-@opindex Wattributes
-Do not warn if an unexpected @code{__attribute__} is used, such as
-unrecognized attributes, function attributes applied to variables,
-etc. This does not stop errors for incorrect use of supported
-attributes.
-
-Additionally, using @option{-Wno-attributes=}, it is possible to suppress
-warnings about unknown scoped attributes (in C++11 and C2X). For example,
-@option{-Wno-attributes=vendor::attr} disables warning about the following
-declaration:
-
-@smallexample
-[[vendor::attr]] void f();
-@end smallexample
-
-It is also possible to disable warning about all attributes in a namespace
-using @option{-Wno-attributes=vendor::} which prevents warning about both
-of these declarations:
-
-@smallexample
-[[vendor::safe]] void f();
-[[vendor::unsafe]] void f2();
-@end smallexample
-
-Note that @option{-Wno-attributes=} does not imply @option{-Wno-attributes}.
-
-@item -Wno-builtin-declaration-mismatch
-@opindex Wno-builtin-declaration-mismatch
-@opindex Wbuiltin-declaration-mismatch
-Warn if a built-in function is declared with an incompatible signature
-or as a non-function, or when a built-in function declared with a type
-that does not include a prototype is called with arguments whose promoted
-types do not match those expected by the function. When @option{-Wextra}
-is specified, also warn when a built-in function that takes arguments is
-declared without a prototype. The @option{-Wbuiltin-declaration-mismatch}
-warning is enabled by default. To avoid the warning include the appropriate
-header to bring the prototypes of built-in functions into scope.
-
-For example, the call to @code{memset} below is diagnosed by the warning
-because the function expects a value of type @code{size_t} as its argument
-but the type of @code{32} is @code{int}. With @option{-Wextra},
-the declaration of the function is diagnosed as well.
-@smallexample
-extern void* memset ();
-void f (void *d)
-@{
- memset (d, '\0', 32);
-@}
-@end smallexample
-
-@item -Wno-builtin-macro-redefined
-@opindex Wno-builtin-macro-redefined
-@opindex Wbuiltin-macro-redefined
-Do not warn if certain built-in macros are redefined. This suppresses
-warnings for redefinition of @code{__TIMESTAMP__}, @code{__TIME__},
-@code{__DATE__}, @code{__FILE__}, and @code{__BASE_FILE__}.
-
-@item -Wstrict-prototypes @r{(C and Objective-C only)}
-@opindex Wstrict-prototypes
-@opindex Wno-strict-prototypes
-Warn if a function is declared or defined without specifying the
-argument types. (An old-style function definition is permitted without
-a warning if preceded by a declaration that specifies the argument
-types.)
-
-@item -Wold-style-declaration @r{(C and Objective-C only)}
-@opindex Wold-style-declaration
-@opindex Wno-old-style-declaration
-Warn for obsolescent usages, according to the C Standard, in a
-declaration. For example, warn if storage-class specifiers like
-@code{static} are not the first things in a declaration. This warning
-is also enabled by @option{-Wextra}.
-
-@item -Wold-style-definition @r{(C and Objective-C only)}
-@opindex Wold-style-definition
-@opindex Wno-old-style-definition
-Warn if an old-style function definition is used. A warning is given
-even if there is a previous prototype. A definition using @samp{()}
-is not considered an old-style definition in C2X mode, because it is
-equivalent to @samp{(void)} in that case, but is considered an
-old-style definition for older standards.
-
-@item -Wmissing-parameter-type @r{(C and Objective-C only)}
-@opindex Wmissing-parameter-type
-@opindex Wno-missing-parameter-type
-A function parameter is declared without a type specifier in K&R-style
-functions:
-
-@smallexample
-void foo(bar) @{ @}
-@end smallexample
-
-This warning is also enabled by @option{-Wextra}.
-
-@item -Wmissing-prototypes @r{(C and Objective-C only)}
-@opindex Wmissing-prototypes
-@opindex Wno-missing-prototypes
-Warn if a global function is defined without a previous prototype
-declaration. This warning is issued even if the definition itself
-provides a prototype. Use this option to detect global functions
-that do not have a matching prototype declaration in a header file.
-This option is not valid for C++ because all function declarations
-provide prototypes and a non-matching declaration declares an
-overload rather than conflict with an earlier declaration.
-Use @option{-Wmissing-declarations} to detect missing declarations in C++.
-
-@item -Wmissing-declarations
-@opindex Wmissing-declarations
-@opindex Wno-missing-declarations
-Warn if a global function is defined without a previous declaration.
-Do so even if the definition itself provides a prototype.
-Use this option to detect global functions that are not declared in
-header files. In C, no warnings are issued for functions with previous
-non-prototype declarations; use @option{-Wmissing-prototypes} to detect
-missing prototypes. In C++, no warnings are issued for function templates,
-or for inline functions, or for functions in anonymous namespaces.
-
-@item -Wmissing-field-initializers
-@opindex Wmissing-field-initializers
-@opindex Wno-missing-field-initializers
-@opindex W
-@opindex Wextra
-@opindex Wno-extra
-Warn if a structure's initializer has some fields missing. For
-example, the following code causes such a warning, because
-@code{x.h} is implicitly zero:
-
-@smallexample
-struct s @{ int f, g, h; @};
-struct s x = @{ 3, 4 @};
-@end smallexample
-
-This option does not warn about designated initializers, so the following
-modification does not trigger a warning:
-
-@smallexample
-struct s @{ int f, g, h; @};
-struct s x = @{ .f = 3, .g = 4 @};
-@end smallexample
-
-In C this option does not warn about the universal zero initializer
-@samp{@{ 0 @}}:
-
-@smallexample
-struct s @{ int f, g, h; @};
-struct s x = @{ 0 @};
-@end smallexample
-
-Likewise, in C++ this option does not warn about the empty @{ @}
-initializer, for example:
-
-@smallexample
-struct s @{ int f, g, h; @};
-s x = @{ @};
-@end smallexample
-
-This warning is included in @option{-Wextra}. To get other @option{-Wextra}
-warnings without this one, use @option{-Wextra -Wno-missing-field-initializers}.
-
-@item -Wno-missing-requires
-@opindex Wmissing-requires
-@opindex Wno-missing-requires
-
-By default, the compiler warns about a concept-id appearing as a C++20 simple-requirement:
-
-@smallexample
-bool satisfied = requires @{ C<T> @};
-@end smallexample
-
-Here @samp{satisfied} will be true if @samp{C<T>} is a valid
-expression, which it is for all T. Presumably the user meant to write
-
-@smallexample
-bool satisfied = requires @{ requires C<T> @};
-@end smallexample
-
-so @samp{satisfied} is only true if concept @samp{C} is satisfied for
-type @samp{T}.
-
-This warning can be disabled with @option{-Wno-missing-requires}.
-
-@item -Wno-missing-template-keyword
-@opindex Wmissing-template-keyword
-@opindex Wno-missing-template-keyword
-
-The member access tokens ., -> and :: must be followed by the @code{template}
-keyword if the parent object is dependent and the member being named is a
-template.
-
-@smallexample
-template <class X>
-void DoStuff (X x)
-@{
- x.template DoSomeOtherStuff<X>(); // Good.
- x.DoMoreStuff<X>(); // Warning, x is dependent.
-@}
-@end smallexample
-
-In rare cases it is possible to get false positives. To silence this, wrap
-the expression in parentheses. For example, the following is treated as a
-template, even where m and N are integers:
-
-@smallexample
-void NotATemplate (my_class t)
-@{
- int N = 5;
-
- bool test = t.m < N > (0); // Treated as a template.
- test = (t.m < N) > (0); // Same meaning, but not treated as a template.
-@}
-@end smallexample
-
-This warning can be disabled with @option{-Wno-missing-template-keyword}.
-
-@item -Wno-multichar
-@opindex Wno-multichar
-@opindex Wmultichar
-Do not warn if a multicharacter constant (@samp{'FOOF'}) is used.
-Usually they indicate a typo in the user's code, as they have
-implementation-defined values, and should not be used in portable code.
-
-@item -Wnormalized=@r{[}none@r{|}id@r{|}nfc@r{|}nfkc@r{]}
-@opindex Wnormalized=
-@opindex Wnormalized
-@opindex Wno-normalized
-@cindex NFC
-@cindex NFKC
-@cindex character set, input normalization
-In ISO C and ISO C++, two identifiers are different if they are
-different sequences of characters. However, sometimes when characters
-outside the basic ASCII character set are used, you can have two
-different character sequences that look the same. To avoid confusion,
-the ISO 10646 standard sets out some @dfn{normalization rules} which
-when applied ensure that two sequences that look the same are turned into
-the same sequence. GCC can warn you if you are using identifiers that
-have not been normalized; this option controls that warning.
-
-There are four levels of warning supported by GCC@. The default is
-@option{-Wnormalized=nfc}, which warns about any identifier that is
-not in the ISO 10646 ``C'' normalized form, @dfn{NFC}. NFC is the
-recommended form for most uses. It is equivalent to
-@option{-Wnormalized}.
-
-Unfortunately, there are some characters allowed in identifiers by
-ISO C and ISO C++ that, when turned into NFC, are not allowed in
-identifiers. That is, there's no way to use these symbols in portable
-ISO C or C++ and have all your identifiers in NFC@.
-@option{-Wnormalized=id} suppresses the warning for these characters.
-It is hoped that future versions of the standards involved will correct
-this, which is why this option is not the default.
-
-You can switch the warning off for all characters by writing
-@option{-Wnormalized=none} or @option{-Wno-normalized}. You should
-only do this if you are using some other normalization scheme (like
-``D''), because otherwise you can easily create bugs that are
-literally impossible to see.
-
-Some characters in ISO 10646 have distinct meanings but look identical
-in some fonts or display methodologies, especially once formatting has
-been applied. For instance @code{\u207F}, ``SUPERSCRIPT LATIN SMALL
-LETTER N'', displays just like a regular @code{n} that has been
-placed in a superscript. ISO 10646 defines the @dfn{NFKC}
-normalization scheme to convert all these into a standard form as
-well, and GCC warns if your code is not in NFKC if you use
-@option{-Wnormalized=nfkc}. This warning is comparable to warning
-about every identifier that contains the letter O because it might be
-confused with the digit 0, and so is not the default, but may be
-useful as a local coding convention if the programming environment
-cannot be fixed to display these characters distinctly.
-
-@item -Wno-attribute-warning
-@opindex Wno-attribute-warning
-@opindex Wattribute-warning
-Do not warn about usage of functions (@pxref{Function Attributes})
-declared with @code{warning} attribute. By default, this warning is
-enabled. @option{-Wno-attribute-warning} can be used to disable the
-warning or @option{-Wno-error=attribute-warning} can be used to
-disable the error when compiled with @option{-Werror} flag.
-
-@item -Wno-deprecated
-@opindex Wno-deprecated
-@opindex Wdeprecated
-Do not warn about usage of deprecated features. @xref{Deprecated Features}.
-
-@item -Wno-deprecated-declarations
-@opindex Wno-deprecated-declarations
-@opindex Wdeprecated-declarations
-Do not warn about uses of functions (@pxref{Function Attributes}),
-variables (@pxref{Variable Attributes}), and types (@pxref{Type
-Attributes}) marked as deprecated by using the @code{deprecated}
-attribute.
-
-@item -Wno-overflow
-@opindex Wno-overflow
-@opindex Woverflow
-Do not warn about compile-time overflow in constant expressions.
-
-@item -Wno-odr
-@opindex Wno-odr
-@opindex Wodr
-Warn about One Definition Rule violations during link-time optimization.
-Enabled by default.
-
-@item -Wopenacc-parallelism
-@opindex Wopenacc-parallelism
-@opindex Wno-openacc-parallelism
-@cindex OpenACC accelerator programming
-Warn about potentially suboptimal choices related to OpenACC parallelism.
-
-@item -Wopenmp-simd
-@opindex Wopenmp-simd
-@opindex Wno-openmp-simd
-Warn if the vectorizer cost model overrides the OpenMP
-simd directive set by user. The @option{-fsimd-cost-model=unlimited}
-option can be used to relax the cost model.
-
-@item -Woverride-init @r{(C and Objective-C only)}
-@opindex Woverride-init
-@opindex Wno-override-init
-@opindex W
-@opindex Wextra
-@opindex Wno-extra
-Warn if an initialized field without side effects is overridden when
-using designated initializers (@pxref{Designated Inits, , Designated
-Initializers}).
-
-This warning is included in @option{-Wextra}. To get other
-@option{-Wextra} warnings without this one, use @option{-Wextra
--Wno-override-init}.
-
-@item -Wno-override-init-side-effects @r{(C and Objective-C only)}
-@opindex Woverride-init-side-effects
-@opindex Wno-override-init-side-effects
-Do not warn if an initialized field with side effects is overridden when
-using designated initializers (@pxref{Designated Inits, , Designated
-Initializers}). This warning is enabled by default.
-
-@item -Wpacked
-@opindex Wpacked
-@opindex Wno-packed
-Warn if a structure is given the packed attribute, but the packed
-attribute has no effect on the layout or size of the structure.
-Such structures may be mis-aligned for little benefit. For
-instance, in this code, the variable @code{f.x} in @code{struct bar}
-is misaligned even though @code{struct bar} does not itself
-have the packed attribute:
-
-@smallexample
-@group
-struct foo @{
- int x;
- char a, b, c, d;
-@} __attribute__((packed));
-struct bar @{
- char z;
- struct foo f;
-@};
-@end group
-@end smallexample
-
-@item -Wnopacked-bitfield-compat
-@opindex Wpacked-bitfield-compat
-@opindex Wno-packed-bitfield-compat
-The 4.1, 4.2 and 4.3 series of GCC ignore the @code{packed} attribute
-on bit-fields of type @code{char}. This was fixed in GCC 4.4 but
-the change can lead to differences in the structure layout. GCC
-informs you when the offset of such a field has changed in GCC 4.4.
-For example there is no longer a 4-bit padding between field @code{a}
-and @code{b} in this structure:
-
-@smallexample
-struct foo
-@{
- char a:4;
- char b:8;
-@} __attribute__ ((packed));
-@end smallexample
-
-This warning is enabled by default. Use
-@option{-Wno-packed-bitfield-compat} to disable this warning.
-
-@item -Wpacked-not-aligned @r{(C, C++, Objective-C and Objective-C++ only)}
-@opindex Wpacked-not-aligned
-@opindex Wno-packed-not-aligned
-Warn if a structure field with explicitly specified alignment in a
-packed struct or union is misaligned. For example, a warning will
-be issued on @code{struct S}, like, @code{warning: alignment 1 of
-'struct S' is less than 8}, in this code:
-
-@smallexample
-@group
-struct __attribute__ ((aligned (8))) S8 @{ char a[8]; @};
-struct __attribute__ ((packed)) S @{
- struct S8 s8;
-@};
-@end group
-@end smallexample
-
-This warning is enabled by @option{-Wall}.
-
-@item -Wpadded
-@opindex Wpadded
-@opindex Wno-padded
-Warn if padding is included in a structure, either to align an element
-of the structure or to align the whole structure. Sometimes when this
-happens it is possible to rearrange the fields of the structure to
-reduce the padding and so make the structure smaller.
-
-@item -Wredundant-decls
-@opindex Wredundant-decls
-@opindex Wno-redundant-decls
-Warn if anything is declared more than once in the same scope, even in
-cases where multiple declaration is valid and changes nothing.
-
-@item -Wrestrict
-@opindex Wrestrict
-@opindex Wno-restrict
-Warn when an object referenced by a @code{restrict}-qualified parameter
-(or, in C++, a @code{__restrict}-qualified parameter) is aliased by another
-argument, or when copies between such objects overlap. For example,
-the call to the @code{strcpy} function below attempts to truncate the string
-by replacing its initial characters with the last four. However, because
-the call writes the terminating NUL into @code{a[4]}, the copies overlap and
-the call is diagnosed.
-
-@smallexample
-void foo (void)
-@{
- char a[] = "abcd1234";
- strcpy (a, a + 4);
- @dots{}
-@}
-@end smallexample
-The @option{-Wrestrict} option detects some instances of simple overlap
-even without optimization but works best at @option{-O2} and above. It
-is included in @option{-Wall}.
-
-@item -Wnested-externs @r{(C and Objective-C only)}
-@opindex Wnested-externs
-@opindex Wno-nested-externs
-Warn if an @code{extern} declaration is encountered within a function.
-
-@item -Winline
-@opindex Winline
-@opindex Wno-inline
-Warn if a function that is declared as inline cannot be inlined.
-Even with this option, the compiler does not warn about failures to
-inline functions declared in system headers.
-
-The compiler uses a variety of heuristics to determine whether or not
-to inline a function. For example, the compiler takes into account
-the size of the function being inlined and the amount of inlining
-that has already been done in the current function. Therefore,
-seemingly insignificant changes in the source program can cause the
-warnings produced by @option{-Winline} to appear or disappear.
-
-@item -Winterference-size
-@opindex Winterference-size
-Warn about use of C++17 @code{std::hardware_destructive_interference_size}
-without specifying its value with @option{--param destructive-interference-size}.
-Also warn about questionable values for that option.
-
-This variable is intended to be used for controlling class layout, to
-avoid false sharing in concurrent code:
-
-@smallexample
-struct independent_fields @{
- alignas(std::hardware_destructive_interference_size) std::atomic<int> one;
- alignas(std::hardware_destructive_interference_size) std::atomic<int> two;
-@};
-@end smallexample
-
-Here @samp{one} and @samp{two} are intended to be far enough apart
-that stores to one won't require accesses to the other to reload the
-cache line.
-
-By default, @option{--param destructive-interference-size} and
-@option{--param constructive-interference-size} are set based on the
-current @option{-mtune} option, typically to the L1 cache line size
-for the particular target CPU, sometimes to a range if tuning for a
-generic target. So all translation units that depend on ABI
-compatibility for the use of these variables must be compiled with
-the same @option{-mtune} (or @option{-mcpu}).
-
-If ABI stability is important, such as if the use is in a header for a
-library, you should probably not use the hardware interference size
-variables at all. Alternatively, you can force a particular value
-with @option{--param}.
-
-If you are confident that your use of the variable does not affect ABI
-outside a single build of your project, you can turn off the warning
-with @option{-Wno-interference-size}.
-
-@item -Wint-in-bool-context
-@opindex Wint-in-bool-context
-@opindex Wno-int-in-bool-context
-Warn for suspicious use of integer values where boolean values are expected,
-such as conditional expressions (?:) using non-boolean integer constants in
-boolean context, like @code{if (a <= b ? 2 : 3)}. Or left shifting of signed
-integers in boolean context, like @code{for (a = 0; 1 << a; a++);}. Likewise
-for all kinds of multiplications regardless of the data type.
-This warning is enabled by @option{-Wall}.
-
-@item -Wno-int-to-pointer-cast
-@opindex Wno-int-to-pointer-cast
-@opindex Wint-to-pointer-cast
-Suppress warnings from casts to pointer type of an integer of a
-different size. In C++, casting to a pointer type of smaller size is
-an error. @option{Wint-to-pointer-cast} is enabled by default.
-
-
-@item -Wno-pointer-to-int-cast @r{(C and Objective-C only)}
-@opindex Wno-pointer-to-int-cast
-@opindex Wpointer-to-int-cast
-Suppress warnings from casts from a pointer to an integer type of a
-different size.
-
-@item -Winvalid-pch
-@opindex Winvalid-pch
-@opindex Wno-invalid-pch
-Warn if a precompiled header (@pxref{Precompiled Headers}) is found in
-the search path but cannot be used.
-
-@item -Winvalid-utf8
-@opindex Winvalid-utf8
-@opindex Wno-invalid-utf8
-Warn if an invalid UTF-8 character is found.
-This warning is on by default for C++23 if @option{-finput-charset=UTF-8}
-is used and turned into error with @option{-pedantic-errors}.
-
-@item -Wno-unicode
-@opindex Wunicode
-@opindex Wno-unicode
-Don't diagnose invalid forms of delimited or named escape sequences which are
-treated as separate tokens. @option{Wunicode} is enabled by default.
-
-@item -Wlong-long
-@opindex Wlong-long
-@opindex Wno-long-long
-Warn if @code{long long} type is used. This is enabled by either
-@option{-Wpedantic} or @option{-Wtraditional} in ISO C90 and C++98
-modes. To inhibit the warning messages, use @option{-Wno-long-long}.
-
-@item -Wvariadic-macros
-@opindex Wvariadic-macros
-@opindex Wno-variadic-macros
-Warn if variadic macros are used in ISO C90 mode, or if the GNU
-alternate syntax is used in ISO C99 mode. This is enabled by either
-@option{-Wpedantic} or @option{-Wtraditional}. To inhibit the warning
-messages, use @option{-Wno-variadic-macros}.
-
-@item -Wno-varargs
-@opindex Wvarargs
-@opindex Wno-varargs
-Do not warn upon questionable usage of the macros used to handle variable
-arguments like @code{va_start}. These warnings are enabled by default.
-
-@item -Wvector-operation-performance
-@opindex Wvector-operation-performance
-@opindex Wno-vector-operation-performance
-Warn if vector operation is not implemented via SIMD capabilities of the
-architecture. Mainly useful for the performance tuning.
-Vector operation can be implemented @code{piecewise}, which means that the
-scalar operation is performed on every vector element;
-@code{in parallel}, which means that the vector operation is implemented
-using scalars of wider type, which normally is more performance efficient;
-and @code{as a single scalar}, which means that vector fits into a
-scalar type.
-
-@item -Wvla
-@opindex Wvla
-@opindex Wno-vla
-Warn if a variable-length array is used in the code.
-@option{-Wno-vla} prevents the @option{-Wpedantic} warning of
-the variable-length array.
-
-@item -Wvla-larger-than=@var{byte-size}
-@opindex Wvla-larger-than=
-@opindex Wno-vla-larger-than
-If this option is used, the compiler warns for declarations of
-variable-length arrays whose size is either unbounded, or bounded
-by an argument that allows the array size to exceed @var{byte-size}
-bytes. This is similar to how @option{-Walloca-larger-than=}@var{byte-size}
-works, but with variable-length arrays.
-
-Note that GCC may optimize small variable-length arrays of a known
-value into plain arrays, so this warning may not get triggered for
-such arrays.
-
-@option{-Wvla-larger-than=}@samp{PTRDIFF_MAX} is enabled by default but
-is typically only effective when @option{-ftree-vrp} is active (default
-for @option{-O2} and above).
-
-See also @option{-Walloca-larger-than=@var{byte-size}}.
-
-@item -Wno-vla-larger-than
-@opindex Wno-vla-larger-than
-Disable @option{-Wvla-larger-than=} warnings. The option is equivalent
-to @option{-Wvla-larger-than=}@samp{SIZE_MAX} or larger.
-
-@item -Wvla-parameter
-@opindex Wno-vla-parameter
-Warn about redeclarations of functions involving arguments of Variable
-Length Array types of inconsistent kinds or forms, and enable the detection
-of out-of-bounds accesses to such parameters by warnings such as
-@option{-Warray-bounds}.
-
-If the first function declaration uses the VLA form the bound specified
-in the array is assumed to be the minimum number of elements expected to
-be provided in calls to the function and the maximum number of elements
-accessed by it. Failing to provide arguments of sufficient size or
-accessing more than the maximum number of elements may be diagnosed.
-
-For example, the warning triggers for the following redeclarations because
-the first one allows an array of any size to be passed to @code{f} while
-the second one specifies that the array argument must have at least @code{n}
-elements. In addition, calling @code{f} with the associated VLA bound
-parameter in excess of the actual VLA bound triggers a warning as well.
-
-@smallexample
-void f (int n, int[n]);
-void f (int, int[]); // warning: argument 2 previously declared as a VLA
-
-void g (int n)
-@{
- if (n > 4)
- return;
- int a[n];
- f (sizeof a, a); // warning: access to a by f may be out of bounds
- @dots{}
-@}
-
-@end smallexample
-
-@option{-Wvla-parameter} is included in @option{-Wall}. The
-@option{-Warray-parameter} option triggers warnings for similar problems
-involving ordinary array arguments.
-
-@item -Wvolatile-register-var
-@opindex Wvolatile-register-var
-@opindex Wno-volatile-register-var
-Warn if a register variable is declared volatile. The volatile
-modifier does not inhibit all optimizations that may eliminate reads
-and/or writes to register variables. This warning is enabled by
-@option{-Wall}.
-
-@item -Wxor-used-as-pow @r{(C, C++, Objective-C and Objective-C++ only)}
-@opindex Wxor-used-as-pow
-@opindex Wno-xor-used-as-pow
-Warn about uses of @code{^}, the exclusive or operator, where it appears
-the user meant exponentiation. Specifically, the warning occurs when the
-left-hand side is the decimal constant 2 or 10 and the right-hand side
-is also a decimal constant.
-
-In C and C++, @code{^} means exclusive or, whereas in some other languages
-(e.g. TeX and some versions of BASIC) it means exponentiation.
-
-This warning is enabled by default. It can be silenced by converting one
-of the operands to hexadecimal.
-
-@item -Wdisabled-optimization
-@opindex Wdisabled-optimization
-@opindex Wno-disabled-optimization
-Warn if a requested optimization pass is disabled. This warning does
-not generally indicate that there is anything wrong with your code; it
-merely indicates that GCC's optimizers are unable to handle the code
-effectively. Often, the problem is that your code is too big or too
-complex; GCC refuses to optimize programs when the optimization
-itself is likely to take inordinate amounts of time.
-
-@item -Wpointer-sign @r{(C and Objective-C only)}
-@opindex Wpointer-sign
-@opindex Wno-pointer-sign
-Warn for pointer argument passing or assignment with different signedness.
-This option is only supported for C and Objective-C@. It is implied by
-@option{-Wall} and by @option{-Wpedantic}, which can be disabled with
-@option{-Wno-pointer-sign}.
-
-@item -Wstack-protector
-@opindex Wstack-protector
-@opindex Wno-stack-protector
-This option is only active when @option{-fstack-protector} is active. It
-warns about functions that are not protected against stack smashing.
-
-@item -Woverlength-strings
-@opindex Woverlength-strings
-@opindex Wno-overlength-strings
-Warn about string constants that are longer than the ``minimum
-maximum'' length specified in the C standard. Modern compilers
-generally allow string constants that are much longer than the
-standard's minimum limit, but very portable programs should avoid
-using longer strings.
-
-The limit applies @emph{after} string constant concatenation, and does
-not count the trailing NUL@. In C90, the limit was 509 characters; in
-C99, it was raised to 4095. C++98 does not specify a normative
-minimum maximum, so we do not diagnose overlength strings in C++@.
-
-This option is implied by @option{-Wpedantic}, and can be disabled with
-@option{-Wno-overlength-strings}.
-
-@item -Wunsuffixed-float-constants @r{(C and Objective-C only)}
-@opindex Wunsuffixed-float-constants
-@opindex Wno-unsuffixed-float-constants
-
-Issue a warning for any floating constant that does not have
-a suffix. When used together with @option{-Wsystem-headers} it
-warns about such constants in system header files. This can be useful
-when preparing code to use with the @code{FLOAT_CONST_DECIMAL64} pragma
-from the decimal floating-point extension to C99.
-
-@item -Wno-lto-type-mismatch
-@opindex Wlto-type-mismatch
-@opindex Wno-lto-type-mismatch
-
-During the link-time optimization, do not warn about type mismatches in
-global declarations from different compilation units.
-Requires @option{-flto} to be enabled. Enabled by default.
-
-@item -Wno-designated-init @r{(C and Objective-C only)}
-@opindex Wdesignated-init
-@opindex Wno-designated-init
-Suppress warnings when a positional initializer is used to initialize
-a structure that has been marked with the @code{designated_init}
-attribute.
-
-@end table
-
-@node Static Analyzer Options
-@section Options That Control Static Analysis
-
-@table @gcctabopt
-@item -fanalyzer
-@opindex analyzer
-@opindex fanalyzer
-@opindex fno-analyzer
-This option enables an static analysis of program flow which looks
-for ``interesting'' interprocedural paths through the
-code, and issues warnings for problems found on them.
-
-This analysis is much more expensive than other GCC warnings.
-
-Enabling this option effectively enables the following warnings:
-
-@gccoptlist{ @gol
--Wanalyzer-allocation-size @gol
--Wanalyzer-double-fclose @gol
--Wanalyzer-double-free @gol
--Wanalyzer-exposure-through-output-file @gol
--Wanalyzer-exposure-through-uninit-copy @gol
--Wanalyzer-fd-access-mode-mismatch @gol
--Wanalyzer-fd-double-close @gol
--Wanalyzer-fd-leak @gol
--Wanalyzer-fd-use-after-close @gol
--Wanalyzer-fd-use-without-check @gol
--Wanalyzer-file-leak @gol
--Wanalyzer-free-of-non-heap @gol
--Wanalyzer-imprecise-fp-arithmetic @gol
--Wanalyzer-jump-through-null @gol
--Wanalyzer-malloc-leak @gol
--Wanalyzer-mismatching-deallocation @gol
--Wanalyzer-null-argument @gol
--Wanalyzer-null-dereference @gol
--Wanalyzer-out-of-bounds @gol
--Wanalyzer-possible-null-argument @gol
--Wanalyzer-possible-null-dereference @gol
--Wanalyzer-putenv-of-auto-var @gol
--Wanalyzer-shift-count-negative @gol
--Wanalyzer-shift-count-overflow @gol
--Wanalyzer-stale-setjmp-buffer @gol
--Wanalyzer-unsafe-call-within-signal-handler @gol
--Wanalyzer-use-after-free @gol
--Wanalyzer-use-of-pointer-in-stale-stack-frame @gol
--Wanalyzer-use-of-uninitialized-value @gol
--Wanalyzer-va-arg-type-mismatch @gol
--Wanalyzer-va-list-exhausted @gol
--Wanalyzer-va-list-leak @gol
--Wanalyzer-va-list-use-after-va-end @gol
--Wanalyzer-write-to-const @gol
--Wanalyzer-write-to-string-literal @gol
-}
-@ignore
--Wanalyzer-tainted-allocation-size @gol
--Wanalyzer-tainted-array-index @gol
--Wanalyzer-tainted-divisor @gol
--Wanalyzer-tainted-offset @gol
--Wanalyzer-tainted-size @gol
-@end ignore
-
-This option is only available if GCC was configured with analyzer
-support enabled.
-
-@item -Wanalyzer-too-complex
-@opindex Wanalyzer-too-complex
-@opindex Wno-analyzer-too-complex
-If @option{-fanalyzer} is enabled, the analyzer uses various heuristics
-to attempt to explore the control flow and data flow in the program,
-but these can be defeated by sufficiently complicated code.
-
-By default, the analysis silently stops if the code is too
-complicated for the analyzer to fully explore and it reaches an internal
-limit. The @option{-Wanalyzer-too-complex} option warns if this occurs.
-
-@item -Wno-analyzer-allocation-size
-@opindex Wanalyzer-allocation-size
-@opindex Wno-analyzer-allocation-size
-This warning requires @option{-fanalyzer}, which enables it; use
-@option{-Wno-analyzer-allocation-size}
-to disable it.
-
-This diagnostic warns for paths through the code in which a pointer to
-a buffer is assigned to point at a buffer with a size that is not a
-multiple of @code{sizeof (*pointer)}.
-
-See @uref{https://cwe.mitre.org/data/definitions/131.html, CWE-131: Incorrect Calculation of Buffer Size}.
-
-@item -Wno-analyzer-double-fclose
-@opindex Wanalyzer-double-fclose
-@opindex Wno-analyzer-double-fclose
-This warning requires @option{-fanalyzer}, which enables it; use
-@option{-Wno-analyzer-double-fclose} to disable it.
-
-This diagnostic warns for paths through the code in which a @code{FILE *}
-can have @code{fclose} called on it more than once.
-
-See @uref{https://cwe.mitre.org/data/definitions/1341.html, CWE-1341: Multiple Releases of Same Resource or Handle}.
-
-@item -Wno-analyzer-double-free
-@opindex Wanalyzer-double-free
-@opindex Wno-analyzer-double-free
-This warning requires @option{-fanalyzer}, which enables it; use
-@option{-Wno-analyzer-double-free} to disable it.
-
-This diagnostic warns for paths through the code in which a pointer
-can have a deallocator called on it more than once, either @code{free},
-or a deallocator referenced by attribute @code{malloc}.
-
-See @uref{https://cwe.mitre.org/data/definitions/415.html, CWE-415: Double Free}.
-
-@item -Wno-analyzer-exposure-through-output-file
-@opindex Wanalyzer-exposure-through-output-file
-@opindex Wno-analyzer-exposure-through-output-file
-This warning requires @option{-fanalyzer}, which enables it; use
-@option{-Wno-analyzer-exposure-through-output-file}
-to disable it.
-
-This diagnostic warns for paths through the code in which a
-security-sensitive value is written to an output file
-(such as writing a password to a log file).
-
-See @uref{https://cwe.mitre.org/data/definitions/532.html, CWE-532: Information Exposure Through Log Files}.
-
-@item -Wanalyzer-exposure-through-uninit-copy
-@opindex Wanalyzer-exposure-through-uninit-copy
-@opindex Wno-analyzer-exposure-through-uninit-copy
-This warning requires both @option{-fanalyzer} and the use of a plugin
-to specify a function that copies across a ``trust boundary''. Use
-@option{-Wno-analyzer-exposure-through-uninit-copy} to disable it.
-
-This diagnostic warns for ``infoleaks'' - paths through the code in which
-uninitialized values are copied across a security boundary
-(such as code within an OS kernel that copies a partially-initialized
-struct on the stack to user space).
-
-See @uref{https://cwe.mitre.org/data/definitions/200.html, CWE-200: Exposure of Sensitive Information to an Unauthorized Actor}.
-
-@item -Wno-analyzer-fd-access-mode-mismatch
-@opindex Wanalyzer-fd-access-mode-mismatch
-@opindex Wno-analyzer-fd-access-mode-mismatch
-This warning requires @option{-fanalyzer}, which enables it; use
-@option{-Wno-analyzer-fd-access-mode-mismatch}
-to disable it.
-
-This diagnostic warns for paths through code in which a
-@code{read} on a write-only file descriptor is attempted, or vice versa.
-
-This diagnostic also warns for code paths in a which a function with attribute
-@code{fd_arg_read (N)} is called with a file descriptor opened with
-@code{O_WRONLY} at referenced argument @code{N} or a function with attribute
-@code{fd_arg_write (N)} is called with a file descriptor opened with
-@code{O_RDONLY} at referenced argument @var{N}.
-
-@item -Wno-analyzer-fd-double-close
-@opindex Wanalyzer-fd-double-close
-@opindex Wno-analyzer-fd-double-close
-This warning requires @option{-fanalyzer}, which enables it; use
-@option{-Wno-analyzer-fd-double-close}
-to disable it.
-
-This diagnostic warns for paths through code in which a
-file descriptor can be closed more than once.
-
-See @uref{https://cwe.mitre.org/data/definitions/1341.html, CWE-1341: Multiple Releases of Same Resource or Handle}.
-
-@item -Wno-analyzer-fd-leak
-@opindex Wanalyzer-fd-leak
-@opindex Wno-analyzer-fd-leak
-This warning requires @option{-fanalyzer}, which enables it; use
-@option{-Wno-analyzer-fd-leak}
-to disable it.
-
-This diagnostic warns for paths through code in which an
-open file descriptor is leaked.
-
-See @uref{https://cwe.mitre.org/data/definitions/775.html, CWE-775: Missing Release of File Descriptor or Handle after Effective Lifetime}.
-
-@item -Wno-analyzer-fd-use-after-close
-@opindex Wanalyzer-fd-use-after-close
-@opindex Wno-analyzer-fd-use-after-close
-This warning requires @option{-fanalyzer}, which enables it; use
-@option{-Wno-analyzer-fd-use-after-close}
-to disable it.
-
-This diagnostic warns for paths through code in which a
-read or write is called on a closed file descriptor.
-
-This diagnostic also warns for paths through code in which
-a function with attribute @code{fd_arg (N)} or @code{fd_arg_read (N)}
-or @code{fd_arg_write (N)} is called with a closed file descriptor at
-referenced argument @code{N}.
-
-@item -Wno-analyzer-fd-use-without-check
-@opindex Wanalyzer-fd-use-without-check
-@opindex Wno-analyzer-fd-use-without-check
-This warning requires @option{-fanalyzer}, which enables it; use
-@option{-Wno-analyzer-fd-use-without-check}
-to disable it.
-
-This diagnostic warns for paths through code in which a
-file descriptor is used without being checked for validity.
-
-This diagnostic also warns for paths through code in which
-a function with attribute @code{fd_arg (N)} or @code{fd_arg_read (N)}
-or @code{fd_arg_write (N)} is called with a file descriptor, at referenced
-argument @code{N}, without being checked for validity.
-
-@item -Wno-analyzer-file-leak
-@opindex Wanalyzer-file-leak
-@opindex Wno-analyzer-file-leak
-This warning requires @option{-fanalyzer}, which enables it; use
-@option{-Wno-analyzer-file-leak}
-to disable it.
-
-This diagnostic warns for paths through the code in which a
-@code{<stdio.h>} @code{FILE *} stream object is leaked.
-
-See @uref{https://cwe.mitre.org/data/definitions/775.html, CWE-775: Missing Release of File Descriptor or Handle after Effective Lifetime}.
-
-@item -Wno-analyzer-free-of-non-heap
-@opindex Wanalyzer-free-of-non-heap
-@opindex Wno-analyzer-free-of-non-heap
-This warning requires @option{-fanalyzer}, which enables it; use
-@option{-Wno-analyzer-free-of-non-heap}
-to disable it.
-
-This diagnostic warns for paths through the code in which @code{free}
-is called on a non-heap pointer (e.g. an on-stack buffer, or a global).
-
-See @uref{https://cwe.mitre.org/data/definitions/590.html, CWE-590: Free of Memory not on the Heap}.
-
-@item -Wno-analyzer-imprecise-fp-arithmetic
-@opindex Wanalyzer-imprecise-fp-arithmetic
-@opindex Wno-analyzer-imprecise-fp-arithmetic
-This warning requires @option{-fanalyzer}, which enables it; use
-@option{-Wno-analyzer-imprecise-fp-arithmetic}
-to disable it.
-
-This diagnostic warns for paths through the code in which floating-point
-arithmetic is used in locations where precise computation is needed. This
-diagnostic only warns on use of floating-point operands inside the
-calculation of an allocation size at the moment.
-
-@item -Wno-analyzer-jump-through-null
-@opindex Wanalyzer-jump-through-null
-@opindex Wno-analyzer-jump-through-null
-This warning requires @option{-fanalyzer}, which enables it; use
-@option{-Wno-analyzer-jump-through-null}
-to disable it.
-
-This diagnostic warns for paths through the code in which a @code{NULL}
-function pointer is called.
-
-@item -Wno-analyzer-malloc-leak
-@opindex Wanalyzer-malloc-leak
-@opindex Wno-analyzer-malloc-leak
-This warning requires @option{-fanalyzer}, which enables it; use
-@option{-Wno-analyzer-malloc-leak}
-to disable it.
-
-This diagnostic warns for paths through the code in which a
-pointer allocated via an allocator is leaked: either @code{malloc},
-or a function marked with attribute @code{malloc}.
-
-See @uref{https://cwe.mitre.org/data/definitions/401.html, CWE-401: Missing Release of Memory after Effective Lifetime}.
-
-@item -Wno-analyzer-mismatching-deallocation
-@opindex Wanalyzer-mismatching-deallocation
-@opindex Wno-analyzer-mismatching-deallocation
-This warning requires @option{-fanalyzer}, which enables it; use
-@option{-Wno-analyzer-mismatching-deallocation}
-to disable it.
-
-This diagnostic warns for paths through the code in which the
-wrong deallocation function is called on a pointer value, based on
-which function was used to allocate the pointer value. The diagnostic
-will warn about mismatches between @code{free}, scalar @code{delete}
-and vector @code{delete[]}, and those marked as allocator/deallocator
-pairs using attribute @code{malloc}.
-
-See @uref{https://cwe.mitre.org/data/definitions/762.html, CWE-762: Mismatched Memory Management Routines}.
-
-@item -Wno-analyzer-out-of-bounds
-@opindex Wanalyzer-out-of-bounds
-@opindex Wno-analyzer-out-of-bounds
-This warning requires @option{-fanalyzer} to enable it; use
-@option{-Wno-analyzer-out-of-bounds} to disable it.
-
-This diagnostic warns for path through the code in which a buffer is
-definitely read or written out-of-bounds. The diagnostic applies for
-cases where the analyzer is able to determine a constant offset and for
-accesses past the end of a buffer, also a constant capacity. Further,
-the diagnostic does limited checking for accesses past the end when the
-offset as well as the capacity is symbolic.
-
-See @uref{https://cwe.mitre.org/data/definitions/119.html, CWE-119: Improper Restriction of Operations within the Bounds of a Memory Buffer}.
-
-@item -Wno-analyzer-possible-null-argument
-@opindex Wanalyzer-possible-null-argument
-@opindex Wno-analyzer-possible-null-argument
-This warning requires @option{-fanalyzer}, which enables it; use
-@option{-Wno-analyzer-possible-null-argument} to disable it.
-
-This diagnostic warns for paths through the code in which a
-possibly-NULL value is passed to a function argument marked
-with @code{__attribute__((nonnull))} as requiring a non-NULL
-value.
-
-See @uref{https://cwe.mitre.org/data/definitions/690.html, CWE-690: Unchecked Return Value to NULL Pointer Dereference}.
-
-@item -Wno-analyzer-possible-null-dereference
-@opindex Wanalyzer-possible-null-dereference
-@opindex Wno-analyzer-possible-null-dereference
-This warning requires @option{-fanalyzer}, which enables it; use
-@option{-Wno-analyzer-possible-null-dereference} to disable it.
-
-This diagnostic warns for paths through the code in which a
-possibly-NULL value is dereferenced.
-
-See @uref{https://cwe.mitre.org/data/definitions/690.html, CWE-690: Unchecked Return Value to NULL Pointer Dereference}.
-
-@item -Wno-analyzer-null-argument
-@opindex Wanalyzer-null-argument
-@opindex Wno-analyzer-null-argument
-This warning requires @option{-fanalyzer}, which enables it; use
-@option{-Wno-analyzer-null-argument} to disable it.
-
-This diagnostic warns for paths through the code in which a
-value known to be NULL is passed to a function argument marked
-with @code{__attribute__((nonnull))} as requiring a non-NULL
-value.
-
-See @uref{https://cwe.mitre.org/data/definitions/476.html, CWE-476: NULL Pointer Dereference}.
-
-@item -Wno-analyzer-null-dereference
-@opindex Wanalyzer-null-dereference
-@opindex Wno-analyzer-null-dereference
-This warning requires @option{-fanalyzer}, which enables it; use
-@option{-Wno-analyzer-null-dereference} to disable it.
-
-This diagnostic warns for paths through the code in which a
-value known to be NULL is dereferenced.
-
-See @uref{https://cwe.mitre.org/data/definitions/476.html, CWE-476: NULL Pointer Dereference}.
-
-@item -Wno-analyzer-putenv-of-auto-var
-@opindex Wanalyzer-putenv-of-auto-var
-@opindex Wno-analyzer-putenv-of-auto-var
-This warning requires @option{-fanalyzer}, which enables it; use
-@option{-Wno-analyzer-putenv-of-auto-var} to disable it.
-
-This diagnostic warns for paths through the code in which a
-call to @code{putenv} is passed a pointer to an automatic variable
-or an on-stack buffer.
-
-See @uref{https://wiki.sei.cmu.edu/confluence/x/6NYxBQ, POS34-C. Do not call putenv() with a pointer to an automatic variable as the argument}.
-
-@item -Wno-analyzer-shift-count-negative
-@opindex Wanalyzer-shift-count-negative
-@opindex Wno-analyzer-shift-count-negative
-This warning requires @option{-fanalyzer}, which enables it; use
-@option{-Wno-analyzer-shift-count-negative} to disable it.
-
-This diagnostic warns for paths through the code in which a
-shift is attempted with a negative count. It is analogous to
-the @option{-Wshift-count-negative} diagnostic implemented in
-the C/C++ front ends, but is implemented based on analyzing
-interprocedural paths, rather than merely parsing the syntax tree.
-However, the analyzer does not prioritize detection of such paths, so
-false negatives are more likely relative to other warnings.
-
-@item -Wno-analyzer-shift-count-overflow
-@opindex Wanalyzer-shift-count-overflow
-@opindex Wno-analyzer-shift-count-overflow
-This warning requires @option{-fanalyzer}, which enables it; use
-@option{-Wno-analyzer-shift-count-overflow} to disable it.
-
-This diagnostic warns for paths through the code in which a
-shift is attempted with a count greater than or equal to the
-precision of the operand's type. It is analogous to
-the @option{-Wshift-count-overflow} diagnostic implemented in
-the C/C++ front ends, but is implemented based on analyzing
-interprocedural paths, rather than merely parsing the syntax tree.
-However, the analyzer does not prioritize detection of such paths, so
-false negatives are more likely relative to other warnings.
-
-@item -Wno-analyzer-stale-setjmp-buffer
-@opindex Wanalyzer-stale-setjmp-buffer
-@opindex Wno-analyzer-stale-setjmp-buffer
-This warning requires @option{-fanalyzer}, which enables it; use
-@option{-Wno-analyzer-stale-setjmp-buffer} to disable it.
-
-This diagnostic warns for paths through the code in which
-@code{longjmp} is called to rewind to a @code{jmp_buf} relating
-to a @code{setjmp} call in a function that has returned.
-
-When @code{setjmp} is called on a @code{jmp_buf} to record a rewind
-location, it records the stack frame. The stack frame becomes invalid
-when the function containing the @code{setjmp} call returns. Attempting
-to rewind to it via @code{longjmp} would reference a stack frame that
-no longer exists, and likely lead to a crash (or worse).
-
-@item -Wno-analyzer-tainted-allocation-size
-@opindex Wanalyzer-tainted-allocation-size
-@opindex Wno-analyzer-tainted-allocation-size
-This warning requires both @option{-fanalyzer} and
-@option{-fanalyzer-checker=taint} to enable it;
-use @option{-Wno-analyzer-tainted-allocation-size} to disable it.
-
-This diagnostic warns for paths through the code in which a value
-that could be under an attacker's control is used as the size
-of an allocation without being sanitized, so that an attacker could
-inject an excessively large allocation and potentially cause a denial
-of service attack.
-
-See @uref{https://cwe.mitre.org/data/definitions/789.html, CWE-789: Memory Allocation with Excessive Size Value}.
-
-@item -Wno-analyzer-tainted-array-index
-@opindex Wanalyzer-tainted-array-index
-@opindex Wno-analyzer-tainted-array-index
-This warning requires both @option{-fanalyzer} and
-@option{-fanalyzer-checker=taint} to enable it;
-use @option{-Wno-analyzer-tainted-array-index} to disable it.
-
-This diagnostic warns for paths through the code in which a value
-that could be under an attacker's control is used as the index
-of an array access without being sanitized, so that an attacker
-could inject an out-of-bounds access.
-
-See @uref{https://cwe.mitre.org/data/definitions/129.html, CWE-129: Improper Validation of Array Index}.
-
-@item -Wno-analyzer-tainted-divisor
-@opindex Wanalyzer-tainted-divisor
-@opindex Wno-analyzer-tainted-divisor
-This warning requires both @option{-fanalyzer} and
-@option{-fanalyzer-checker=taint} to enable it;
-use @option{-Wno-analyzer-tainted-divisor} to disable it.
-
-This diagnostic warns for paths through the code in which a value
-that could be under an attacker's control is used as the divisor
-in a division or modulus operation without being sanitized, so that
-an attacker could inject a division-by-zero.
-
-See @uref{https://cwe.mitre.org/data/definitions/369.html, CWE-369: Divide By Zero}.
-
-@item -Wno-analyzer-tainted-offset
-@opindex Wanalyzer-tainted-offset
-@opindex Wno-analyzer-tainted-offset
-This warning requires both @option{-fanalyzer} and
-@option{-fanalyzer-checker=taint} to enable it;
-use @option{-Wno-analyzer-tainted-offset} to disable it.
-
-This diagnostic warns for paths through the code in which a value
-that could be under an attacker's control is used as a pointer offset
-without being sanitized, so that an attacker could inject an out-of-bounds
-access.
-
-See @uref{https://cwe.mitre.org/data/definitions/823.html, CWE-823: Use of Out-of-range Pointer Offset}.
-
-@item -Wno-analyzer-tainted-size
-@opindex Wanalyzer-tainted-size
-@opindex Wno-analyzer-tainted-size
-This warning requires both @option{-fanalyzer} and
-@option{-fanalyzer-checker=taint} to enable it;
-use @option{-Wno-analyzer-tainted-size} to disable it.
-
-This diagnostic warns for paths through the code in which a value
-that could be under an attacker's control is used as the size of
-an operation such as @code{memset} without being sanitized, so that an
-attacker could inject an out-of-bounds access.
-
-See @uref{https://cwe.mitre.org/data/definitions/129.html, CWE-129: Improper Validation of Array Index}.
-
-@item -Wno-analyzer-unsafe-call-within-signal-handler
-@opindex Wanalyzer-unsafe-call-within-signal-handler
-@opindex Wno-analyzer-unsafe-call-within-signal-handler
-This warning requires @option{-fanalyzer}, which enables it; use
-@option{-Wno-analyzer-unsafe-call-within-signal-handler} to disable it.
-
-This diagnostic warns for paths through the code in which a
-function known to be async-signal-unsafe (such as @code{fprintf}) is
-called from a signal handler.
-
-See @uref{https://cwe.mitre.org/data/definitions/479.html, CWE-479: Signal Handler Use of a Non-reentrant Function}.
-
-@item -Wno-analyzer-use-after-free
-@opindex Wanalyzer-use-after-free
-@opindex Wno-analyzer-use-after-free
-This warning requires @option{-fanalyzer}, which enables it; use
-@option{-Wno-analyzer-use-after-free} to disable it.
-
-This diagnostic warns for paths through the code in which a
-pointer is used after a deallocator is called on it: either @code{free},
-or a deallocator referenced by attribute @code{malloc}.
-
-See @uref{https://cwe.mitre.org/data/definitions/416.html, CWE-416: Use After Free}.
-
-@item -Wno-analyzer-use-of-pointer-in-stale-stack-frame
-@opindex Wanalyzer-use-of-pointer-in-stale-stack-frame
-@opindex Wno-analyzer-use-of-pointer-in-stale-stack-frame
-This warning requires @option{-fanalyzer}, which enables it; use
-@option{-Wno-analyzer-use-of-pointer-in-stale-stack-frame}
-to disable it.
-
-This diagnostic warns for paths through the code in which a pointer
-is dereferenced that points to a variable in a stale stack frame.
-
-@item -Wno-analyzer-va-arg-type-mismatch
-@opindex Wanalyzer-va-arg-type-mismatch
-@opindex Wno-analyzer-va-arg-type-mismatch
-This warning requires @option{-fanalyzer}, which enables it; use
-@option{-Wno-analyzer-va-arg-type-mismatch}
-to disable it.
-
-This diagnostic warns for interprocedural paths through the code for which
-the analyzer detects an attempt to use @code{va_arg} to extract a value
-passed to a variadic call, but uses a type that does not match that of
-the expression passed to the call.
-
-See @uref{https://cwe.mitre.org/data/definitions/686.html, CWE-686: Function Call With Incorrect Argument Type}.
-
-@item -Wno-analyzer-va-list-exhausted
-@opindex Wanalyzer-va-list-exhausted
-@opindex Wno-analyzer-va-list-exhausted
-This warning requires @option{-fanalyzer}, which enables it; use
-@option{-Wno-analyzer-va-list-exhausted}
-to disable it.
-
-This diagnostic warns for interprocedural paths through the code for which
-the analyzer detects an attempt to use @code{va_arg} to access the next
-value passed to a variadic call, but all of the values in the
-@code{va_list} have already been consumed.
-
-See @uref{https://cwe.mitre.org/data/definitions/685.html, CWE-685: Function Call With Incorrect Number of Arguments}.
-
-@item -Wno-analyzer-va-list-leak
-@opindex Wanalyzer-va-list-leak
-@opindex Wno-analyzer-va-list-leak
-This warning requires @option{-fanalyzer}, which enables it; use
-@option{-Wno-analyzer-va-list-leak}
-to disable it.
-
-This diagnostic warns for interprocedural paths through the code for which
-the analyzer detects that @code{va_start} or @code{va_copy} has been called
-on a @code{va_list} without a corresponding call to @code{va_end}.
-
-@item -Wno-analyzer-va-list-use-after-va-end
-@opindex Wanalyzer-va-list-use-after-va-end
-@opindex Wno-analyzer-va-list-use-after-va-end
-This warning requires @option{-fanalyzer}, which enables it; use
-@option{-Wno-analyzer-va-list-use-after-va-end}
-to disable it.
-
-This diagnostic warns for interprocedural paths through the code for which
-the analyzer detects an attempt to use a @code{va_list} after
-@code{va_end} has been called on it.
-@code{va_list}.
-
-@item -Wno-analyzer-write-to-const
-@opindex Wanalyzer-write-to-const
-@opindex Wno-analyzer-write-to-const
-This warning requires @option{-fanalyzer}, which enables it; use
-@option{-Wno-analyzer-write-to-const}
-to disable it.
-
-This diagnostic warns for paths through the code in which the analyzer
-detects an attempt to write through a pointer to a @code{const} object.
-However, the analyzer does not prioritize detection of such paths, so
-false negatives are more likely relative to other warnings.
-
-@item -Wno-analyzer-write-to-string-literal
-@opindex Wanalyzer-write-to-string-literal
-@opindex Wno-analyzer-write-to-string-literal
-This warning requires @option{-fanalyzer}, which enables it; use
-@option{-Wno-analyzer-write-to-string-literal}
-to disable it.
-
-This diagnostic warns for paths through the code in which the analyzer
-detects an attempt to write through a pointer to a string literal.
-However, the analyzer does not prioritize detection of such paths, so
-false negatives are more likely relative to other warnings.
-
-@item -Wno-analyzer-use-of-uninitialized-value
-@opindex Wanalyzer-use-of-uninitialized-value
-@opindex Wno-analyzer-use-of-uninitialized-value
-This warning requires @option{-fanalyzer}, which enables it; use
-@option{-Wno-analyzer-use-of-uninitialized-value} to disable it.
-
-This diagnostic warns for paths through the code in which an uninitialized
-value is used.
-
-See @uref{https://cwe.mitre.org/data/definitions/457.html, CWE-457: Use of Uninitialized Variable}.
-
-@end table
-
-The analyzer has hardcoded knowledge about the behavior of the following
-memory-management functions:
-
-@itemize @bullet
-@item @code{alloca}
-@item The built-in functions @code{__builtin_alloc},
-@code{__builtin_alloc_with_align}, @item @code{__builtin_calloc},
-@code{__builtin_free}, @code{__builtin_malloc}, @code{__builtin_memcpy},
-@code{__builtin_memcpy_chk}, @code{__builtin_memset},
-@code{__builtin_memset_chk}, @code{__builtin_realloc},
-@code{__builtin_stack_restore}, and @code{__builtin_stack_save}
-@item @code{calloc}
-@item @code{free}
-@item @code{malloc}
-@item @code{memset}
-@item @code{operator delete}
-@item @code{operator delete []}
-@item @code{operator new}
-@item @code{operator new []}
-@item @code{realloc}
-@item @code{strdup}
-@item @code{strndup}
-@end itemize
-
-of the following functions for working with file descriptors:
-
-@itemize @bullet
-@item @code{open}
-@item @code{close}
-@item @code{creat}
-@item @code{dup}, @code{dup2} and @code{dup3}
-@item @code{pipe}, and @code{pipe2}
-@item @code{read}
-@item @code{write}
-@end itemize
-
-of the following functions for working with @code{<stdio.h>} streams:
-@itemize @bullet
-@item The built-in functions @code{__builtin_fprintf},
-@code{__builtin_fprintf_unlocked}, @code{__builtin_fputc},
-@code{__builtin_fputc_unlocked}, @code{__builtin_fputs},
-@code{__builtin_fputs_unlocked}, @code{__builtin_fwrite},
-@code{__builtin_fwrite_unlocked}, @code{__builtin_printf},
-@code{__builtin_printf_unlocked}, @code{__builtin_putc},
-@code{__builtin_putchar}, @code{__builtin_putchar_unlocked},
-@code{__builtin_putc_unlocked}, @code{__builtin_puts},
-@code{__builtin_puts_unlocked}, @code{__builtin_vfprintf}, and
-@code{__builtin_vprintf}
-@item @code{fopen}
-@item @code{fclose}
-@item @code{fgets}
-@item @code{fgets_unlocked}
-@item @code{fread}
-@item @code{getchar}
-@item @code{fprintf}
-@item @code{printf}
-@item @code{fwrite}
-@end itemize
-
-and of the following functions:
-
-@itemize @bullet
-@item The built-in functions @code{__builtin_expect},
-@code{__builtin_expect_with_probability}, @code{__builtin_strchr},
-@code{__builtin_strcpy}, @code{__builtin_strcpy_chk},
-@code{__builtin_strlen}, @code{__builtin_va_copy}, and
-@code{__builtin_va_start}
-@item The GNU extensions @code{error} and @code{error_at_line}
-@item @code{getpass}
-@item @code{longjmp}
-@item @code{putenv}
-@item @code{setjmp}
-@item @code{siglongjmp}
-@item @code{signal}
-@item @code{sigsetjmp}
-@item @code{strchr}
-@item @code{strlen}
-@end itemize
-
-In addition, various functions with an @code{__analyzer_} prefix have
-special meaning to the analyzer, described in the GCC Internals manual.
-
-Pertinent parameters for controlling the exploration are:
-@option{--param analyzer-bb-explosion-factor=@var{value}},
-@option{--param analyzer-max-enodes-per-program-point=@var{value}},
-@option{--param analyzer-max-recursion-depth=@var{value}}, and
-@option{--param analyzer-min-snodes-for-call-summary=@var{value}}.
-
-The following options control the analyzer.
-
-@table @gcctabopt
-
-@item -fanalyzer-call-summaries
-@opindex fanalyzer-call-summaries
-@opindex fno-analyzer-call-summaries
-Simplify interprocedural analysis by computing the effect of certain calls,
-rather than exploring all paths through the function from callsite to each
-possible return.
-
-If enabled, call summaries are only used for functions with more than one
-call site, and that are sufficiently complicated (as per
-@option{--param analyzer-min-snodes-for-call-summary=@var{value}}).
-
-@item -fanalyzer-checker=@var{name}
-@opindex fanalyzer-checker
-Restrict the analyzer to run just the named checker, and enable it.
-
-Some checkers are disabled by default (even with @option{-fanalyzer}),
-such as the @code{taint} checker that implements
-@option{-Wanalyzer-tainted-array-index}, and this option is required
-to enable them.
-
-@emph{Note:} currently, @option{-fanalyzer-checker=taint} disables the
-following warnings from @option{-fanalyzer}:
-
-@gccoptlist{ @gol
--Wanalyzer-double-fclose @gol
--Wanalyzer-double-free @gol
--Wanalyzer-exposure-through-output-file @gol
--Wanalyzer-fd-access-mode-mismatch @gol
--Wanalyzer-fd-double-close @gol
--Wanalyzer-fd-leak @gol
--Wanalyzer-fd-use-after-close @gol
--Wanalyzer-fd-use-without-check @gol
--Wanalyzer-file-leak @gol
--Wanalyzer-free-of-non-heap @gol
--Wanalyzer-malloc-leak @gol
--Wanalyzer-mismatching-deallocation @gol
--Wanalyzer-null-argument @gol
--Wanalyzer-null-dereference @gol
--Wanalyzer-possible-null-argument @gol
--Wanalyzer-possible-null-dereference @gol
--Wanalyzer-unsafe-call-within-signal-handler @gol
--Wanalyzer-use-after-free @gol
--Wanalyzer-va-list-leak @gol
--Wanalyzer-va-list-use-after-va-end @gol
-}
-
-@item -fno-analyzer-feasibility
-@opindex fanalyzer-feasibility
-@opindex fno-analyzer-feasibility
-This option is intended for analyzer developers.
-
-By default the analyzer verifies that there is a feasible control flow path
-for each diagnostic it emits: that the conditions that hold are not mutually
-exclusive. Diagnostics for which no feasible path can be found are rejected.
-This filtering can be suppressed with @option{-fno-analyzer-feasibility}, for
-debugging issues in this code.
-
-@item -fanalyzer-fine-grained
-@opindex fanalyzer-fine-grained
-@opindex fno-analyzer-fine-grained
-This option is intended for analyzer developers.
-
-Internally the analyzer builds an ``exploded graph'' that combines
-control flow graphs with data flow information.
-
-By default, an edge in this graph can contain the effects of a run
-of multiple statements within a basic block. With
-@option{-fanalyzer-fine-grained}, each statement gets its own edge.
-
-@item -fanalyzer-show-duplicate-count
-@opindex fanalyzer-show-duplicate-count
-@opindex fno-analyzer-show-duplicate-count
-This option is intended for analyzer developers: if multiple diagnostics
-have been detected as being duplicates of each other, it emits a note when
-reporting the best diagnostic, giving the number of additional diagnostics
-that were suppressed by the deduplication logic.
-
-@item -fno-analyzer-state-merge
-@opindex fanalyzer-state-merge
-@opindex fno-analyzer-state-merge
-This option is intended for analyzer developers.
-
-By default the analyzer attempts to simplify analysis by merging
-sufficiently similar states at each program point as it builds its
-``exploded graph''. With @option{-fno-analyzer-state-merge} this
-merging can be suppressed, for debugging state-handling issues.
-
-@item -fno-analyzer-state-purge
-@opindex fanalyzer-state-purge
-@opindex fno-analyzer-state-purge
-This option is intended for analyzer developers.
-
-By default the analyzer attempts to simplify analysis by purging
-aspects of state at a program point that appear to no longer be relevant
-e.g. the values of locals that aren't accessed later in the function
-and which aren't relevant to leak analysis.
-
-With @option{-fno-analyzer-state-purge} this purging of state can
-be suppressed, for debugging state-handling issues.
-
-@item -fanalyzer-transitivity
-@opindex fanalyzer-transitivity
-@opindex fno-analyzer-transitivity
-This option enables transitivity of constraints within the analyzer.
-
-@item -fno-analyzer-undo-inlining
-@opindex fanalyzer-undo-inlining
-@opindex fno-analyzer-undo-inlining
-This option is intended for analyzer developers.
-
-@option{-fanalyzer} runs relatively late compared to other code analysis
-tools, and some optimizations have already been applied to the code. In
-particular function inlining may have occurred, leading to the
-interprocedural execution paths emitted by the analyzer containing
-function frames that don't correspond to those in the original source
-code.
-
-By default the analyzer attempts to reconstruct the original function
-frames, and to emit events showing the inlined calls.
-
-With @option{-fno-analyzer-undo-inlining} this attempt to reconstruct
-the original frame information can be be disabled, which may be of help
-when debugging issues in the analyzer.
-
-@item -fanalyzer-verbose-edges
-This option is intended for analyzer developers. It enables more
-verbose, lower-level detail in the descriptions of control flow
-within diagnostic paths.
-
-@item -fanalyzer-verbose-state-changes
-This option is intended for analyzer developers. It enables more
-verbose, lower-level detail in the descriptions of events relating
-to state machines within diagnostic paths.
-
-@item -fanalyzer-verbosity=@var{level}
-This option controls the complexity of the control flow paths that are
-emitted for analyzer diagnostics.
-
-The @var{level} can be one of:
-
-@table @samp
-@item 0
-At this level, interprocedural call and return events are displayed,
-along with the most pertinent state-change events relating to
-a diagnostic. For example, for a double-@code{free} diagnostic,
-both calls to @code{free} will be shown.
-
-@item 1
-As per the previous level, but also show events for the entry
-to each function.
-
-@item 2
-As per the previous level, but also show events relating to
-control flow that are significant to triggering the issue
-(e.g. ``true path taken'' at a conditional).
-
-This level is the default.
-
-@item 3
-As per the previous level, but show all control flow events, not
-just significant ones.
-
-@item 4
-This level is intended for analyzer developers; it adds various
-other events intended for debugging the analyzer.
-
-@end table
-
-@item -fdump-analyzer
-@opindex fdump-analyzer
-Dump internal details about what the analyzer is doing to
-@file{@var{file}.analyzer.txt}.
-This option is overridden by @option{-fdump-analyzer-stderr}.
-
-@item -fdump-analyzer-stderr
-@opindex fdump-analyzer-stderr
-Dump internal details about what the analyzer is doing to stderr.
-This option overrides @option{-fdump-analyzer}.
-
-@item -fdump-analyzer-callgraph
-@opindex fdump-analyzer-callgraph
-Dump a representation of the call graph suitable for viewing with
-GraphViz to @file{@var{file}.callgraph.dot}.
-
-@item -fdump-analyzer-exploded-graph
-@opindex fdump-analyzer-exploded-graph
-Dump a representation of the ``exploded graph'' suitable for viewing with
-GraphViz to @file{@var{file}.eg.dot}.
-Nodes are color-coded based on state-machine states to emphasize
-state changes.
-
-@item -fdump-analyzer-exploded-nodes
-@opindex dump-analyzer-exploded-nodes
-Emit diagnostics showing where nodes in the ``exploded graph'' are
-in relation to the program source.
-
-@item -fdump-analyzer-exploded-nodes-2
-@opindex dump-analyzer-exploded-nodes-2
-Dump a textual representation of the ``exploded graph'' to
-@file{@var{file}.eg.txt}.
-
-@item -fdump-analyzer-exploded-nodes-3
-@opindex dump-analyzer-exploded-nodes-3
-Dump a textual representation of the ``exploded graph'' to
-one dump file per node, to @file{@var{file}.eg-@var{id}.txt}.
-This is typically a large number of dump files.
-
-@item -fdump-analyzer-exploded-paths
-@opindex fdump-analyzer-exploded-paths
-Dump a textual representation of the ``exploded path'' for each
-diagnostic to @file{@var{file}.@var{idx}.@var{kind}.epath.txt}.
-
-@item -fdump-analyzer-feasibility
-@opindex dump-analyzer-feasibility
-Dump internal details about the analyzer's search for feasible paths.
-The details are written in a form suitable for viewing with GraphViz
-to filenames of the form @file{@var{file}.*.fg.dot},
-@file{@var{file}.*.tg.dot}, and @file{@var{file}.*.fpath.txt}.
-
-@item -fdump-analyzer-json
-@opindex fdump-analyzer-json
-Dump a compressed JSON representation of analyzer internals to
-@file{@var{file}.analyzer.json.gz}. The precise format is subject
-to change.
-
-@item -fdump-analyzer-state-purge
-@opindex fdump-analyzer-state-purge
-As per @option{-fdump-analyzer-supergraph}, dump a representation of the
-``supergraph'' suitable for viewing with GraphViz, but annotate the
-graph with information on what state will be purged at each node.
-The graph is written to @file{@var{file}.state-purge.dot}.
-
-@item -fdump-analyzer-supergraph
-@opindex fdump-analyzer-supergraph
-Dump representations of the ``supergraph'' suitable for viewing with
-GraphViz to @file{@var{file}.supergraph.dot} and to
-@file{@var{file}.supergraph-eg.dot}. These show all of the
-control flow graphs in the program, with interprocedural edges for
-calls and returns. The second dump contains annotations showing nodes
-in the ``exploded graph'' and diagnostics associated with them.
-
-@item -fdump-analyzer-untracked
-@opindex fdump-analyzer-untracked
-Emit custom warnings with internal details intended for analyzer developers.
-
-@end table
-
-@node Debugging Options
-@section Options for Debugging Your Program
-@cindex options, debugging
-@cindex debugging information options
-
-To tell GCC to emit extra information for use by a debugger, in almost
-all cases you need only to add @option{-g} to your other options. Some debug
-formats can co-exist (like DWARF with CTF) when each of them is enabled
-explicitly by adding the respective command line option to your other options.
-
-GCC allows you to use @option{-g} with
-@option{-O}. The shortcuts taken by optimized code may occasionally
-be surprising: some variables you declared may not exist
-at all; flow of control may briefly move where you did not expect it;
-some statements may not be executed because they compute constant
-results or their values are already at hand; some statements may
-execute in different places because they have been moved out of loops.
-Nevertheless it is possible to debug optimized output. This makes
-it reasonable to use the optimizer for programs that might have bugs.
-
-If you are not using some other optimization option, consider
-using @option{-Og} (@pxref{Optimize Options}) with @option{-g}.
-With no @option{-O} option at all, some compiler passes that collect
-information useful for debugging do not run at all, so that
-@option{-Og} may result in a better debugging experience.
-
-@table @gcctabopt
-@item -g
-@opindex g
-Produce debugging information in the operating system's native format
-(stabs, COFF, XCOFF, or DWARF)@. GDB can work with this debugging
-information.
-
-On most systems that use stabs format, @option{-g} enables use of extra
-debugging information that only GDB can use; this extra information
-makes debugging work better in GDB but probably makes other debuggers
-crash or refuse to read the program. If you want to control for certain whether
-to generate the extra information, use @option{-gvms} (see below).
-
-@item -ggdb
-@opindex ggdb
-Produce debugging information for use by GDB@. This means to use the
-most expressive format available (DWARF, stabs, or the native format
-if neither of those are supported), including GDB extensions if at all
-possible.
-
-@item -gdwarf
-@itemx -gdwarf-@var{version}
-@opindex gdwarf
-Produce debugging information in DWARF format (if that is supported).
-The value of @var{version} may be either 2, 3, 4 or 5; the default
-version for most targets is 5 (with the exception of VxWorks, TPF and
-Darwin/Mac OS X, which default to version 2, and AIX, which defaults
-to version 4).
-
-Note that with DWARF Version 2, some ports require and always
-use some non-conflicting DWARF 3 extensions in the unwind tables.
-
-Version 4 may require GDB 7.0 and @option{-fvar-tracking-assignments}
-for maximum benefit. Version 5 requires GDB 8.0 or higher.
-
-GCC no longer supports DWARF Version 1, which is substantially
-different than Version 2 and later. For historical reasons, some
-other DWARF-related options such as
-@option{-fno-dwarf2-cfi-asm}) retain a reference to DWARF Version 2
-in their names, but apply to all currently-supported versions of DWARF.
-
-@item -gbtf
-@opindex gbtf
-Request BTF debug information. BTF is the default debugging format for the
-eBPF target. On other targets, like x86, BTF debug information can be
-generated along with DWARF debug information when both of the debug formats are
-enabled explicitly via their respective command line options.
-
-@item -gctf
-@itemx -gctf@var{level}
-@opindex gctf
-Request CTF debug information and use level to specify how much CTF debug
-information should be produced. If @option{-gctf} is specified
-without a value for level, the default level of CTF debug information is 2.
-
-CTF debug information can be generated along with DWARF debug information when
-both of the debug formats are enabled explicitly via their respective command
-line options.
-
-Level 0 produces no CTF debug information at all. Thus, @option{-gctf0}
-negates @option{-gctf}.
-
-Level 1 produces CTF information for tracebacks only. This includes callsite
-information, but does not include type information.
-
-Level 2 produces type information for entities (functions, data objects etc.)
-at file-scope or global-scope only.
-
-@item -gvms
-@opindex gvms
-Produce debugging information in Alpha/VMS debug format (if that is
-supported). This is the format used by DEBUG on Alpha/VMS systems.
-
-@item -g@var{level}
-@itemx -ggdb@var{level}
-@itemx -gvms@var{level}
-Request debugging information and also use @var{level} to specify how
-much information. The default level is 2.
-
-Level 0 produces no debug information at all. Thus, @option{-g0} negates
-@option{-g}.
-
-Level 1 produces minimal information, enough for making backtraces in
-parts of the program that you don't plan to debug. This includes
-descriptions of functions and external variables, and line number
-tables, but no information about local variables.
-
-Level 3 includes extra information, such as all the macro definitions
-present in the program. Some debuggers support macro expansion when
-you use @option{-g3}.
-
-If you use multiple @option{-g} options, with or without level numbers,
-the last such option is the one that is effective.
-
-@option{-gdwarf} does not accept a concatenated debug level, to avoid
-confusion with @option{-gdwarf-@var{level}}.
-Instead use an additional @option{-g@var{level}} option to change the
-debug level for DWARF.
-
-@item -fno-eliminate-unused-debug-symbols
-@opindex feliminate-unused-debug-symbols
-@opindex fno-eliminate-unused-debug-symbols
-By default, no debug information is produced for symbols that are not actually
-used. Use this option if you want debug information for all symbols.
-
-@item -femit-class-debug-always
-@opindex femit-class-debug-always
-Instead of emitting debugging information for a C++ class in only one
-object file, emit it in all object files using the class. This option
-should be used only with debuggers that are unable to handle the way GCC
-normally emits debugging information for classes because using this
-option increases the size of debugging information by as much as a
-factor of two.
-
-@item -fno-merge-debug-strings
-@opindex fmerge-debug-strings
-@opindex fno-merge-debug-strings
-Direct the linker to not merge together strings in the debugging
-information that are identical in different object files. Merging is
-not supported by all assemblers or linkers. Merging decreases the size
-of the debug information in the output file at the cost of increasing
-link processing time. Merging is enabled by default.
-
-@item -fdebug-prefix-map=@var{old}=@var{new}
-@opindex fdebug-prefix-map
-When compiling files residing in directory @file{@var{old}}, record
-debugging information describing them as if the files resided in
-directory @file{@var{new}} instead. This can be used to replace a
-build-time path with an install-time path in the debug info. It can
-also be used to change an absolute path to a relative path by using
-@file{.} for @var{new}. This can give more reproducible builds, which
-are location independent, but may require an extra command to tell GDB
-where to find the source files. See also @option{-ffile-prefix-map}.
-
-@item -fvar-tracking
-@opindex fvar-tracking
-Run variable tracking pass. It computes where variables are stored at each
-position in code. Better debugging information is then generated
-(if the debugging information format supports this information).
-
-It is enabled by default when compiling with optimization (@option{-Os},
-@option{-O}, @option{-O2}, @dots{}), debugging information (@option{-g}) and
-the debug info format supports it.
-
-@item -fvar-tracking-assignments
-@opindex fvar-tracking-assignments
-@opindex fno-var-tracking-assignments
-Annotate assignments to user variables early in the compilation and
-attempt to carry the annotations over throughout the compilation all the
-way to the end, in an attempt to improve debug information while
-optimizing. Use of @option{-gdwarf-4} is recommended along with it.
-
-It can be enabled even if var-tracking is disabled, in which case
-annotations are created and maintained, but discarded at the end.
-By default, this flag is enabled together with @option{-fvar-tracking},
-except when selective scheduling is enabled.
-
-@item -gsplit-dwarf
-@opindex gsplit-dwarf
-If DWARF debugging information is enabled, separate as much debugging
-information as possible into a separate output file with the extension
-@file{.dwo}. This option allows the build system to avoid linking files with
-debug information. To be useful, this option requires a debugger capable of
-reading @file{.dwo} files.
-
-@item -gdwarf32
-@itemx -gdwarf64
-@opindex gdwarf32
-@opindex gdwarf64
-If DWARF debugging information is enabled, the @option{-gdwarf32} selects
-the 32-bit DWARF format and the @option{-gdwarf64} selects the 64-bit
-DWARF format. The default is target specific, on most targets it is
-@option{-gdwarf32} though. The 32-bit DWARF format is smaller, but
-can't support more than 2GiB of debug information in any of the DWARF
-debug information sections. The 64-bit DWARF format allows larger debug
-information and might not be well supported by all consumers yet.
-
-@item -gdescribe-dies
-@opindex gdescribe-dies
-Add description attributes to some DWARF DIEs that have no name attribute,
-such as artificial variables, external references and call site
-parameter DIEs.
-
-@item -gpubnames
-@opindex gpubnames
-Generate DWARF @code{.debug_pubnames} and @code{.debug_pubtypes} sections.
-
-@item -ggnu-pubnames
-@opindex ggnu-pubnames
-Generate @code{.debug_pubnames} and @code{.debug_pubtypes} sections in a format
-suitable for conversion into a GDB@ index. This option is only useful
-with a linker that can produce GDB@ index version 7.
-
-@item -fdebug-types-section
-@opindex fdebug-types-section
-@opindex fno-debug-types-section
-When using DWARF Version 4 or higher, type DIEs can be put into
-their own @code{.debug_types} section instead of making them part of the
-@code{.debug_info} section. It is more efficient to put them in a separate
-comdat section since the linker can then remove duplicates.
-But not all DWARF consumers support @code{.debug_types} sections yet
-and on some objects @code{.debug_types} produces larger instead of smaller
-debugging information.
-
-@item -grecord-gcc-switches
-@itemx -gno-record-gcc-switches
-@opindex grecord-gcc-switches
-@opindex gno-record-gcc-switches
-This switch causes the command-line options used to invoke the
-compiler that may affect code generation to be appended to the
-DW_AT_producer attribute in DWARF debugging information. The options
-are concatenated with spaces separating them from each other and from
-the compiler version.
-It is enabled by default.
-See also @option{-frecord-gcc-switches} for another
-way of storing compiler options into the object file.
-
-@item -gstrict-dwarf
-@opindex gstrict-dwarf
-Disallow using extensions of later DWARF standard version than selected
-with @option{-gdwarf-@var{version}}. On most targets using non-conflicting
-DWARF extensions from later standard versions is allowed.
-
-@item -gno-strict-dwarf
-@opindex gno-strict-dwarf
-Allow using extensions of later DWARF standard version than selected with
-@option{-gdwarf-@var{version}}.
-
-@item -gas-loc-support
-@opindex gas-loc-support
-Inform the compiler that the assembler supports @code{.loc} directives.
-It may then use them for the assembler to generate DWARF2+ line number
-tables.
-
-This is generally desirable, because assembler-generated line-number
-tables are a lot more compact than those the compiler can generate
-itself.
-
-This option will be enabled by default if, at GCC configure time, the
-assembler was found to support such directives.
-
-@item -gno-as-loc-support
-@opindex gno-as-loc-support
-Force GCC to generate DWARF2+ line number tables internally, if DWARF2+
-line number tables are to be generated.
-
-@item -gas-locview-support
-@opindex gas-locview-support
-Inform the compiler that the assembler supports @code{view} assignment
-and reset assertion checking in @code{.loc} directives.
-
-This option will be enabled by default if, at GCC configure time, the
-assembler was found to support them.
-
-@item -gno-as-locview-support
-Force GCC to assign view numbers internally, if
-@option{-gvariable-location-views} are explicitly requested.
-
-@item -gcolumn-info
-@itemx -gno-column-info
-@opindex gcolumn-info
-@opindex gno-column-info
-Emit location column information into DWARF debugging information, rather
-than just file and line.
-This option is enabled by default.
-
-@item -gstatement-frontiers
-@itemx -gno-statement-frontiers
-@opindex gstatement-frontiers
-@opindex gno-statement-frontiers
-This option causes GCC to create markers in the internal representation
-at the beginning of statements, and to keep them roughly in place
-throughout compilation, using them to guide the output of @code{is_stmt}
-markers in the line number table. This is enabled by default when
-compiling with optimization (@option{-Os}, @option{-O1}, @option{-O2},
-@dots{}), and outputting DWARF 2 debug information at the normal level.
-
-@item -gvariable-location-views
-@itemx -gvariable-location-views=incompat5
-@itemx -gno-variable-location-views
-@opindex gvariable-location-views
-@opindex gvariable-location-views=incompat5
-@opindex gno-variable-location-views
-Augment variable location lists with progressive view numbers implied
-from the line number table. This enables debug information consumers to
-inspect state at certain points of the program, even if no instructions
-associated with the corresponding source locations are present at that
-point. If the assembler lacks support for view numbers in line number
-tables, this will cause the compiler to emit the line number table,
-which generally makes them somewhat less compact. The augmented line
-number tables and location lists are fully backward-compatible, so they
-can be consumed by debug information consumers that are not aware of
-these augmentations, but they won't derive any benefit from them either.
-
-This is enabled by default when outputting DWARF 2 debug information at
-the normal level, as long as there is assembler support,
-@option{-fvar-tracking-assignments} is enabled and
-@option{-gstrict-dwarf} is not. When assembler support is not
-available, this may still be enabled, but it will force GCC to output
-internal line number tables, and if
-@option{-ginternal-reset-location-views} is not enabled, that will most
-certainly lead to silently mismatching location views.
-
-There is a proposed representation for view numbers that is not backward
-compatible with the location list format introduced in DWARF 5, that can
-be enabled with @option{-gvariable-location-views=incompat5}. This
-option may be removed in the future, is only provided as a reference
-implementation of the proposed representation. Debug information
-consumers are not expected to support this extended format, and they
-would be rendered unable to decode location lists using it.
-
-@item -ginternal-reset-location-views
-@itemx -gno-internal-reset-location-views
-@opindex ginternal-reset-location-views
-@opindex gno-internal-reset-location-views
-Attempt to determine location views that can be omitted from location
-view lists. This requires the compiler to have very accurate insn
-length estimates, which isn't always the case, and it may cause
-incorrect view lists to be generated silently when using an assembler
-that does not support location view lists. The GNU assembler will flag
-any such error as a @code{view number mismatch}. This is only enabled
-on ports that define a reliable estimation function.
-
-@item -ginline-points
-@itemx -gno-inline-points
-@opindex ginline-points
-@opindex gno-inline-points
-Generate extended debug information for inlined functions. Location
-view tracking markers are inserted at inlined entry points, so that
-address and view numbers can be computed and output in debug
-information. This can be enabled independently of location views, in
-which case the view numbers won't be output, but it can only be enabled
-along with statement frontiers, and it is only enabled by default if
-location views are enabled.
-
-@item -gz@r{[}=@var{type}@r{]}
-@opindex gz
-Produce compressed debug sections in DWARF format, if that is supported.
-If @var{type} is not given, the default type depends on the capabilities
-of the assembler and linker used. @var{type} may be one of
-@samp{none} (don't compress debug sections), or @samp{zlib} (use zlib
-compression in ELF gABI format). If the linker doesn't support writing
-compressed debug sections, the option is rejected. Otherwise, if the
-assembler does not support them, @option{-gz} is silently ignored when
-producing object files.
-
-@item -femit-struct-debug-baseonly
-@opindex femit-struct-debug-baseonly
-Emit debug information for struct-like types
-only when the base name of the compilation source file
-matches the base name of file in which the struct is defined.
-
-This option substantially reduces the size of debugging information,
-but at significant potential loss in type information to the debugger.
-See @option{-femit-struct-debug-reduced} for a less aggressive option.
-See @option{-femit-struct-debug-detailed} for more detailed control.
-
-This option works only with DWARF debug output.
-
-@item -femit-struct-debug-reduced
-@opindex femit-struct-debug-reduced
-Emit debug information for struct-like types
-only when the base name of the compilation source file
-matches the base name of file in which the type is defined,
-unless the struct is a template or defined in a system header.
-
-This option significantly reduces the size of debugging information,
-with some potential loss in type information to the debugger.
-See @option{-femit-struct-debug-baseonly} for a more aggressive option.
-See @option{-femit-struct-debug-detailed} for more detailed control.
-
-This option works only with DWARF debug output.
-
-@item -femit-struct-debug-detailed@r{[}=@var{spec-list}@r{]}
-@opindex femit-struct-debug-detailed
-Specify the struct-like types
-for which the compiler generates debug information.
-The intent is to reduce duplicate struct debug information
-between different object files within the same program.
-
-This option is a detailed version of
-@option{-femit-struct-debug-reduced} and @option{-femit-struct-debug-baseonly},
-which serves for most needs.
-
-A specification has the syntax@*
-[@samp{dir:}|@samp{ind:}][@samp{ord:}|@samp{gen:}](@samp{any}|@samp{sys}|@samp{base}|@samp{none})
-
-The optional first word limits the specification to
-structs that are used directly (@samp{dir:}) or used indirectly (@samp{ind:}).
-A struct type is used directly when it is the type of a variable, member.
-Indirect uses arise through pointers to structs.
-That is, when use of an incomplete struct is valid, the use is indirect.
-An example is
-@samp{struct one direct; struct two * indirect;}.
-
-The optional second word limits the specification to
-ordinary structs (@samp{ord:}) or generic structs (@samp{gen:}).
-Generic structs are a bit complicated to explain.
-For C++, these are non-explicit specializations of template classes,
-or non-template classes within the above.
-Other programming languages have generics,
-but @option{-femit-struct-debug-detailed} does not yet implement them.
-
-The third word specifies the source files for those
-structs for which the compiler should emit debug information.
-The values @samp{none} and @samp{any} have the normal meaning.
-The value @samp{base} means that
-the base of name of the file in which the type declaration appears
-must match the base of the name of the main compilation file.
-In practice, this means that when compiling @file{foo.c}, debug information
-is generated for types declared in that file and @file{foo.h},
-but not other header files.
-The value @samp{sys} means those types satisfying @samp{base}
-or declared in system or compiler headers.
-
-You may need to experiment to determine the best settings for your application.
-
-The default is @option{-femit-struct-debug-detailed=all}.
-
-This option works only with DWARF debug output.
-
-@item -fno-dwarf2-cfi-asm
-@opindex fdwarf2-cfi-asm
-@opindex fno-dwarf2-cfi-asm
-Emit DWARF unwind info as compiler generated @code{.eh_frame} section
-instead of using GAS @code{.cfi_*} directives.
-
-@item -fno-eliminate-unused-debug-types
-@opindex feliminate-unused-debug-types
-@opindex fno-eliminate-unused-debug-types
-Normally, when producing DWARF output, GCC avoids producing debug symbol
-output for types that are nowhere used in the source file being compiled.
-Sometimes it is useful to have GCC emit debugging
-information for all types declared in a compilation
-unit, regardless of whether or not they are actually used
-in that compilation unit, for example
-if, in the debugger, you want to cast a value to a type that is
-not actually used in your program (but is declared). More often,
-however, this results in a significant amount of wasted space.
-@end table
-
-@node Optimize Options
-@section Options That Control Optimization
-@cindex optimize options
-@cindex options, optimization
-
-These options control various sorts of optimizations.
-
-Without any optimization option, the compiler's goal is to reduce the
-cost of compilation and to make debugging produce the expected
-results. Statements are independent: if you stop the program with a
-breakpoint between statements, you can then assign a new value to any
-variable or change the program counter to any other statement in the
-function and get exactly the results you expect from the source
-code.
-
-Turning on optimization flags makes the compiler attempt to improve
-the performance and/or code size at the expense of compilation time
-and possibly the ability to debug the program.
-
-The compiler performs optimization based on the knowledge it has of the
-program. Compiling multiple files at once to a single output file mode allows
-the compiler to use information gained from all of the files when compiling
-each of them.
-
-Not all optimizations are controlled directly by a flag. Only
-optimizations that have a flag are listed in this section.
-
-Most optimizations are completely disabled at @option{-O0} or if an
-@option{-O} level is not set on the command line, even if individual
-optimization flags are specified. Similarly, @option{-Og} suppresses
-many optimization passes.
-
-Depending on the target and how GCC was configured, a slightly different
-set of optimizations may be enabled at each @option{-O} level than
-those listed here. You can invoke GCC with @option{-Q --help=optimizers}
-to find out the exact set of optimizations that are enabled at each level.
-@xref{Overall Options}, for examples.
-
-@table @gcctabopt
-@item -O
-@itemx -O1
-@opindex O
-@opindex O1
-Optimize. Optimizing compilation takes somewhat more time, and a lot
-more memory for a large function.
-
-With @option{-O}, the compiler tries to reduce code size and execution
-time, without performing any optimizations that take a great deal of
-compilation time.
-
-@c Note that in addition to the default_options_table list in opts.cc,
-@c several optimization flags default to true but control optimization
-@c passes that are explicitly disabled at -O0.
-
-@option{-O} turns on the following optimization flags:
-
-@c Please keep the following list alphabetized.
-@gccoptlist{-fauto-inc-dec @gol
--fbranch-count-reg @gol
--fcombine-stack-adjustments @gol
--fcompare-elim @gol
--fcprop-registers @gol
--fdce @gol
--fdefer-pop @gol
--fdelayed-branch @gol
--fdse @gol
--fforward-propagate @gol
--fguess-branch-probability @gol
--fif-conversion @gol
--fif-conversion2 @gol
--finline-functions-called-once @gol
--fipa-modref @gol
--fipa-profile @gol
--fipa-pure-const @gol
--fipa-reference @gol
--fipa-reference-addressable @gol
--fmerge-constants @gol
--fmove-loop-invariants @gol
--fmove-loop-stores@gol
--fomit-frame-pointer @gol
--freorder-blocks @gol
--fshrink-wrap @gol
--fshrink-wrap-separate @gol
--fsplit-wide-types @gol
--fssa-backprop @gol
--fssa-phiopt @gol
--ftree-bit-ccp @gol
--ftree-ccp @gol
--ftree-ch @gol
--ftree-coalesce-vars @gol
--ftree-copy-prop @gol
--ftree-dce @gol
--ftree-dominator-opts @gol
--ftree-dse @gol
--ftree-forwprop @gol
--ftree-fre @gol
--ftree-phiprop @gol
--ftree-pta @gol
--ftree-scev-cprop @gol
--ftree-sink @gol
--ftree-slsr @gol
--ftree-sra @gol
--ftree-ter @gol
--funit-at-a-time}
-
-@item -O2
-@opindex O2
-Optimize even more. GCC performs nearly all supported optimizations
-that do not involve a space-speed tradeoff.
-As compared to @option{-O}, this option increases both compilation time
-and the performance of the generated code.
-
-@option{-O2} turns on all optimization flags specified by @option{-O1}. It
-also turns on the following optimization flags:
-
-@c Please keep the following list alphabetized!
-@gccoptlist{-falign-functions -falign-jumps @gol
--falign-labels -falign-loops @gol
--fcaller-saves @gol
--fcode-hoisting @gol
--fcrossjumping @gol
--fcse-follow-jumps -fcse-skip-blocks @gol
--fdelete-null-pointer-checks @gol
--fdevirtualize -fdevirtualize-speculatively @gol
--fexpensive-optimizations @gol
--ffinite-loops @gol
--fgcse -fgcse-lm @gol
--fhoist-adjacent-loads @gol
--finline-functions @gol
--finline-small-functions @gol
--findirect-inlining @gol
--fipa-bit-cp -fipa-cp -fipa-icf @gol
--fipa-ra -fipa-sra -fipa-vrp @gol
--fisolate-erroneous-paths-dereference @gol
--flra-remat @gol
--foptimize-sibling-calls @gol
--foptimize-strlen @gol
--fpartial-inlining @gol
--fpeephole2 @gol
--freorder-blocks-algorithm=stc @gol
--freorder-blocks-and-partition -freorder-functions @gol
--frerun-cse-after-loop @gol
--fschedule-insns -fschedule-insns2 @gol
--fsched-interblock -fsched-spec @gol
--fstore-merging @gol
--fstrict-aliasing @gol
--fthread-jumps @gol
--ftree-builtin-call-dce @gol
--ftree-loop-vectorize @gol
--ftree-pre @gol
--ftree-slp-vectorize @gol
--ftree-switch-conversion -ftree-tail-merge @gol
--ftree-vrp @gol
--fvect-cost-model=very-cheap}
-
-Please note the warning under @option{-fgcse} about
-invoking @option{-O2} on programs that use computed gotos.
-
-@item -O3
-@opindex O3
-Optimize yet more. @option{-O3} turns on all optimizations specified
-by @option{-O2} and also turns on the following optimization flags:
-
-@c Please keep the following list alphabetized!
-@gccoptlist{-fgcse-after-reload @gol
--fipa-cp-clone
--floop-interchange @gol
--floop-unroll-and-jam @gol
--fpeel-loops @gol
--fpredictive-commoning @gol
--fsplit-loops @gol
--fsplit-paths @gol
--ftree-loop-distribution @gol
--ftree-partial-pre @gol
--funswitch-loops @gol
--fvect-cost-model=dynamic @gol
--fversion-loops-for-strides}
-
-@item -O0
-@opindex O0
-Reduce compilation time and make debugging produce the expected
-results. This is the default.
-
-@item -Os
-@opindex Os
-Optimize for size. @option{-Os} enables all @option{-O2} optimizations
-except those that often increase code size:
-
-@gccoptlist{-falign-functions -falign-jumps @gol
--falign-labels -falign-loops @gol
--fprefetch-loop-arrays -freorder-blocks-algorithm=stc}
-
-It also enables @option{-finline-functions}, causes the compiler to tune for
-code size rather than execution speed, and performs further optimizations
-designed to reduce code size.
-
-@item -Ofast
-@opindex Ofast
-Disregard strict standards compliance. @option{-Ofast} enables all
-@option{-O3} optimizations. It also enables optimizations that are not
-valid for all standard-compliant programs.
-It turns on @option{-ffast-math}, @option{-fallow-store-data-races}
-and the Fortran-specific @option{-fstack-arrays}, unless
-@option{-fmax-stack-var-size} is specified, and @option{-fno-protect-parens}.
-It turns off @option{-fsemantic-interposition}.
-
-@item -Og
-@opindex Og
-Optimize debugging experience. @option{-Og} should be the optimization
-level of choice for the standard edit-compile-debug cycle, offering
-a reasonable level of optimization while maintaining fast compilation
-and a good debugging experience. It is a better choice than @option{-O0}
-for producing debuggable code because some compiler passes
-that collect debug information are disabled at @option{-O0}.
-
-Like @option{-O0}, @option{-Og} completely disables a number of
-optimization passes so that individual options controlling them have
-no effect. Otherwise @option{-Og} enables all @option{-O1}
-optimization flags except for those that may interfere with debugging:
-
-@gccoptlist{-fbranch-count-reg -fdelayed-branch @gol
--fdse -fif-conversion -fif-conversion2 @gol
--finline-functions-called-once @gol
--fmove-loop-invariants -fmove-loop-stores -fssa-phiopt @gol
--ftree-bit-ccp -ftree-dse -ftree-pta -ftree-sra}
-
-@item -Oz
-@opindex Oz
-Optimize aggressively for size rather than speed. This may increase
-the number of instructions executed if those instructions require
-fewer bytes to encode. @option{-Oz} behaves similarly to @option{-Os}
-including enabling most @option{-O2} optimizations.
-
-@end table
-
-If you use multiple @option{-O} options, with or without level numbers,
-the last such option is the one that is effective.
-
-Options of the form @option{-f@var{flag}} specify machine-independent
-flags. Most flags have both positive and negative forms; the negative
-form of @option{-ffoo} is @option{-fno-foo}. In the table
-below, only one of the forms is listed---the one you typically
-use. You can figure out the other form by either removing @samp{no-}
-or adding it.
-
-The following options control specific optimizations. They are either
-activated by @option{-O} options or are related to ones that are. You
-can use the following flags in the rare cases when ``fine-tuning'' of
-optimizations to be performed is desired.
-
-@table @gcctabopt
-@item -fno-defer-pop
-@opindex fno-defer-pop
-@opindex fdefer-pop
-For machines that must pop arguments after a function call, always pop
-the arguments as soon as each function returns.
-At levels @option{-O1} and higher, @option{-fdefer-pop} is the default;
-this allows the compiler to let arguments accumulate on the stack for several
-function calls and pop them all at once.
-
-@item -fforward-propagate
-@opindex fforward-propagate
-Perform a forward propagation pass on RTL@. The pass tries to combine two
-instructions and checks if the result can be simplified. If loop unrolling
-is active, two passes are performed and the second is scheduled after
-loop unrolling.
-
-This option is enabled by default at optimization levels @option{-O1},
-@option{-O2}, @option{-O3}, @option{-Os}.
-
-@item -ffp-contract=@var{style}
-@opindex ffp-contract
-@option{-ffp-contract=off} disables floating-point expression contraction.
-@option{-ffp-contract=fast} enables floating-point expression contraction
-such as forming of fused multiply-add operations if the target has
-native support for them.
-@option{-ffp-contract=on} enables floating-point expression contraction
-if allowed by the language standard. This is currently not implemented
-and treated equal to @option{-ffp-contract=off}.
-
-The default is @option{-ffp-contract=fast}.
-
-@item -fomit-frame-pointer
-@opindex fomit-frame-pointer
-Omit the frame pointer in functions that don't need one. This avoids the
-instructions to save, set up and restore the frame pointer; on many targets
-it also makes an extra register available.
-
-On some targets this flag has no effect because the standard calling sequence
-always uses a frame pointer, so it cannot be omitted.
-
-Note that @option{-fno-omit-frame-pointer} doesn't guarantee the frame pointer
-is used in all functions. Several targets always omit the frame pointer in
-leaf functions.
-
-Enabled by default at @option{-O1} and higher.
-
-@item -foptimize-sibling-calls
-@opindex foptimize-sibling-calls
-Optimize sibling and tail recursive calls.
-
-Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
-
-@item -foptimize-strlen
-@opindex foptimize-strlen
-Optimize various standard C string functions (e.g.@: @code{strlen},
-@code{strchr} or @code{strcpy}) and
-their @code{_FORTIFY_SOURCE} counterparts into faster alternatives.
-
-Enabled at levels @option{-O2}, @option{-O3}.
-
-@item -fno-inline
-@opindex fno-inline
-@opindex finline
-Do not expand any functions inline apart from those marked with
-the @code{always_inline} attribute. This is the default when not
-optimizing.
-
-Single functions can be exempted from inlining by marking them
-with the @code{noinline} attribute.
-
-@item -finline-small-functions
-@opindex finline-small-functions
-Integrate functions into their callers when their body is smaller than expected
-function call code (so overall size of program gets smaller). The compiler
-heuristically decides which functions are simple enough to be worth integrating
-in this way. This inlining applies to all functions, even those not declared
-inline.
-
-Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
-
-@item -findirect-inlining
-@opindex findirect-inlining
-Inline also indirect calls that are discovered to be known at compile
-time thanks to previous inlining. This option has any effect only
-when inlining itself is turned on by the @option{-finline-functions}
-or @option{-finline-small-functions} options.
-
-Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
-
-@item -finline-functions
-@opindex finline-functions
-Consider all functions for inlining, even if they are not declared inline.
-The compiler heuristically decides which functions are worth integrating
-in this way.
-
-If all calls to a given function are integrated, and the function is
-declared @code{static}, then the function is normally not output as
-assembler code in its own right.
-
-Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. Also enabled
-by @option{-fprofile-use} and @option{-fauto-profile}.
-
-@item -finline-functions-called-once
-@opindex finline-functions-called-once
-Consider all @code{static} functions called once for inlining into their
-caller even if they are not marked @code{inline}. If a call to a given
-function is integrated, then the function is not output as assembler code
-in its own right.
-
-Enabled at levels @option{-O1}, @option{-O2}, @option{-O3} and @option{-Os},
-but not @option{-Og}.
-
-@item -fearly-inlining
-@opindex fearly-inlining
-Inline functions marked by @code{always_inline} and functions whose body seems
-smaller than the function call overhead early before doing
-@option{-fprofile-generate} instrumentation and real inlining pass. Doing so
-makes profiling significantly cheaper and usually inlining faster on programs
-having large chains of nested wrapper functions.
-
-Enabled by default.
-
-@item -fipa-sra
-@opindex fipa-sra
-Perform interprocedural scalar replacement of aggregates, removal of
-unused parameters and replacement of parameters passed by reference
-by parameters passed by value.
-
-Enabled at levels @option{-O2}, @option{-O3} and @option{-Os}.
-
-@item -finline-limit=@var{n}
-@opindex finline-limit
-By default, GCC limits the size of functions that can be inlined. This flag
-allows coarse control of this limit. @var{n} is the size of functions that
-can be inlined in number of pseudo instructions.
-
-Inlining is actually controlled by a number of parameters, which may be
-specified individually by using @option{--param @var{name}=@var{value}}.
-The @option{-finline-limit=@var{n}} option sets some of these parameters
-as follows:
-
-@table @gcctabopt
-@item max-inline-insns-single
-is set to @var{n}/2.
-@item max-inline-insns-auto
-is set to @var{n}/2.
-@end table
-
-See below for a documentation of the individual
-parameters controlling inlining and for the defaults of these parameters.
-
-@emph{Note:} there may be no value to @option{-finline-limit} that results
-in default behavior.
-
-@emph{Note:} pseudo instruction represents, in this particular context, an
-abstract measurement of function's size. In no way does it represent a count
-of assembly instructions and as such its exact meaning might change from one
-release to an another.
-
-@item -fno-keep-inline-dllexport
-@opindex fno-keep-inline-dllexport
-@opindex fkeep-inline-dllexport
-This is a more fine-grained version of @option{-fkeep-inline-functions},
-which applies only to functions that are declared using the @code{dllexport}
-attribute or declspec. @xref{Function Attributes,,Declaring Attributes of
-Functions}.
-
-@item -fkeep-inline-functions
-@opindex fkeep-inline-functions
-In C, emit @code{static} functions that are declared @code{inline}
-into the object file, even if the function has been inlined into all
-of its callers. This switch does not affect functions using the
-@code{extern inline} extension in GNU C90@. In C++, emit any and all
-inline functions into the object file.
-
-@item -fkeep-static-functions
-@opindex fkeep-static-functions
-Emit @code{static} functions into the object file, even if the function
-is never used.
-
-@item -fkeep-static-consts
-@opindex fkeep-static-consts
-Emit variables declared @code{static const} when optimization isn't turned
-on, even if the variables aren't referenced.
-
-GCC enables this option by default. If you want to force the compiler to
-check if a variable is referenced, regardless of whether or not
-optimization is turned on, use the @option{-fno-keep-static-consts} option.
-
-@item -fmerge-constants
-@opindex fmerge-constants
-Attempt to merge identical constants (string constants and floating-point
-constants) across compilation units.
-
-This option is the default for optimized compilation if the assembler and
-linker support it. Use @option{-fno-merge-constants} to inhibit this
-behavior.
-
-Enabled at levels @option{-O1}, @option{-O2}, @option{-O3}, @option{-Os}.
-
-@item -fmerge-all-constants
-@opindex fmerge-all-constants
-Attempt to merge identical constants and identical variables.
-
-This option implies @option{-fmerge-constants}. In addition to
-@option{-fmerge-constants} this considers e.g.@: even constant initialized
-arrays or initialized constant variables with integral or floating-point
-types. Languages like C or C++ require each variable, including multiple
-instances of the same variable in recursive calls, to have distinct locations,
-so using this option results in non-conforming
-behavior.
-
-@item -fmodulo-sched
-@opindex fmodulo-sched
-Perform swing modulo scheduling immediately before the first scheduling
-pass. This pass looks at innermost loops and reorders their
-instructions by overlapping different iterations.
-
-@item -fmodulo-sched-allow-regmoves
-@opindex fmodulo-sched-allow-regmoves
-Perform more aggressive SMS-based modulo scheduling with register moves
-allowed. By setting this flag certain anti-dependences edges are
-deleted, which triggers the generation of reg-moves based on the
-life-range analysis. This option is effective only with
-@option{-fmodulo-sched} enabled.
-
-@item -fno-branch-count-reg
-@opindex fno-branch-count-reg
-@opindex fbranch-count-reg
-Disable the optimization pass that scans for opportunities to use
-``decrement and branch'' instructions on a count register instead of
-instruction sequences that decrement a register, compare it against zero, and
-then branch based upon the result. This option is only meaningful on
-architectures that support such instructions, which include x86, PowerPC,
-IA-64 and S/390. Note that the @option{-fno-branch-count-reg} option
-doesn't remove the decrement and branch instructions from the generated
-instruction stream introduced by other optimization passes.
-
-The default is @option{-fbranch-count-reg} at @option{-O1} and higher,
-except for @option{-Og}.
-
-@item -fno-function-cse
-@opindex fno-function-cse
-@opindex ffunction-cse
-Do not put function addresses in registers; make each instruction that
-calls a constant function contain the function's address explicitly.
-
-This option results in less efficient code, but some strange hacks
-that alter the assembler output may be confused by the optimizations
-performed when this option is not used.
-
-The default is @option{-ffunction-cse}
-
-@item -fno-zero-initialized-in-bss
-@opindex fno-zero-initialized-in-bss
-@opindex fzero-initialized-in-bss
-If the target supports a BSS section, GCC by default puts variables that
-are initialized to zero into BSS@. This can save space in the resulting
-code.
-
-This option turns off this behavior because some programs explicitly
-rely on variables going to the data section---e.g., so that the
-resulting executable can find the beginning of that section and/or make
-assumptions based on that.
-
-The default is @option{-fzero-initialized-in-bss}.
-
-@item -fthread-jumps
-@opindex fthread-jumps
-Perform optimizations that check to see if a jump branches to a
-location where another comparison subsumed by the first is found. If
-so, the first branch is redirected to either the destination of the
-second branch or a point immediately following it, depending on whether
-the condition is known to be true or false.
-
-Enabled at levels @option{-O1}, @option{-O2}, @option{-O3}, @option{-Os}.
-
-@item -fsplit-wide-types
-@opindex fsplit-wide-types
-When using a type that occupies multiple registers, such as @code{long
-long} on a 32-bit system, split the registers apart and allocate them
-independently. This normally generates better code for those types,
-but may make debugging more difficult.
-
-Enabled at levels @option{-O1}, @option{-O2}, @option{-O3},
-@option{-Os}.
-
-@item -fsplit-wide-types-early
-@opindex fsplit-wide-types-early
-Fully split wide types early, instead of very late.
-This option has no effect unless @option{-fsplit-wide-types} is turned on.
-
-This is the default on some targets.
-
-@item -fcse-follow-jumps
-@opindex fcse-follow-jumps
-In common subexpression elimination (CSE), scan through jump instructions
-when the target of the jump is not reached by any other path. For
-example, when CSE encounters an @code{if} statement with an
-@code{else} clause, CSE follows the jump when the condition
-tested is false.
-
-Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
-
-@item -fcse-skip-blocks
-@opindex fcse-skip-blocks
-This is similar to @option{-fcse-follow-jumps}, but causes CSE to
-follow jumps that conditionally skip over blocks. When CSE
-encounters a simple @code{if} statement with no else clause,
-@option{-fcse-skip-blocks} causes CSE to follow the jump around the
-body of the @code{if}.
-
-Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
-
-@item -frerun-cse-after-loop
-@opindex frerun-cse-after-loop
-Re-run common subexpression elimination after loop optimizations are
-performed.
-
-Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
-
-@item -fgcse
-@opindex fgcse
-Perform a global common subexpression elimination pass.
-This pass also performs global constant and copy propagation.
-
-@emph{Note:} When compiling a program using computed gotos, a GCC
-extension, you may get better run-time performance if you disable
-the global common subexpression elimination pass by adding
-@option{-fno-gcse} to the command line.
-
-Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
-
-@item -fgcse-lm
-@opindex fgcse-lm
-When @option{-fgcse-lm} is enabled, global common subexpression elimination
-attempts to move loads that are only killed by stores into themselves. This
-allows a loop containing a load/store sequence to be changed to a load outside
-the loop, and a copy/store within the loop.
-
-Enabled by default when @option{-fgcse} is enabled.
-
-@item -fgcse-sm
-@opindex fgcse-sm
-When @option{-fgcse-sm} is enabled, a store motion pass is run after
-global common subexpression elimination. This pass attempts to move
-stores out of loops. When used in conjunction with @option{-fgcse-lm},
-loops containing a load/store sequence can be changed to a load before
-the loop and a store after the loop.
-
-Not enabled at any optimization level.
-
-@item -fgcse-las
-@opindex fgcse-las
-When @option{-fgcse-las} is enabled, the global common subexpression
-elimination pass eliminates redundant loads that come after stores to the
-same memory location (both partial and full redundancies).
-
-Not enabled at any optimization level.
-
-@item -fgcse-after-reload
-@opindex fgcse-after-reload
-When @option{-fgcse-after-reload} is enabled, a redundant load elimination
-pass is performed after reload. The purpose of this pass is to clean up
-redundant spilling.
-
-Enabled by @option{-O3}, @option{-fprofile-use} and @option{-fauto-profile}.
-
-@item -faggressive-loop-optimizations
-@opindex faggressive-loop-optimizations
-This option tells the loop optimizer to use language constraints to
-derive bounds for the number of iterations of a loop. This assumes that
-loop code does not invoke undefined behavior by for example causing signed
-integer overflows or out-of-bound array accesses. The bounds for the
-number of iterations of a loop are used to guide loop unrolling and peeling
-and loop exit test optimizations.
-This option is enabled by default.
-
-@item -funconstrained-commons
-@opindex funconstrained-commons
-This option tells the compiler that variables declared in common blocks
-(e.g.@: Fortran) may later be overridden with longer trailing arrays. This
-prevents certain optimizations that depend on knowing the array bounds.
-
-@item -fcrossjumping
-@opindex fcrossjumping
-Perform cross-jumping transformation.
-This transformation unifies equivalent code and saves code size. The
-resulting code may or may not perform better than without cross-jumping.
-
-Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
-
-@item -fauto-inc-dec
-@opindex fauto-inc-dec
-Combine increments or decrements of addresses with memory accesses.
-This pass is always skipped on architectures that do not have
-instructions to support this. Enabled by default at @option{-O1} and
-higher on architectures that support this.
-
-@item -fdce
-@opindex fdce
-Perform dead code elimination (DCE) on RTL@.
-Enabled by default at @option{-O1} and higher.
-
-@item -fdse
-@opindex fdse
-Perform dead store elimination (DSE) on RTL@.
-Enabled by default at @option{-O1} and higher.
-
-@item -fif-conversion
-@opindex fif-conversion
-Attempt to transform conditional jumps into branch-less equivalents. This
-includes use of conditional moves, min, max, set flags and abs instructions, and
-some tricks doable by standard arithmetics. The use of conditional execution
-on chips where it is available is controlled by @option{-fif-conversion2}.
-
-Enabled at levels @option{-O1}, @option{-O2}, @option{-O3}, @option{-Os}, but
-not with @option{-Og}.
-
-@item -fif-conversion2
-@opindex fif-conversion2
-Use conditional execution (where available) to transform conditional jumps into
-branch-less equivalents.
-
-Enabled at levels @option{-O1}, @option{-O2}, @option{-O3}, @option{-Os}, but
-not with @option{-Og}.
-
-@item -fdeclone-ctor-dtor
-@opindex fdeclone-ctor-dtor
-The C++ ABI requires multiple entry points for constructors and
-destructors: one for a base subobject, one for a complete object, and
-one for a virtual destructor that calls operator delete afterwards.
-For a hierarchy with virtual bases, the base and complete variants are
-clones, which means two copies of the function. With this option, the
-base and complete variants are changed to be thunks that call a common
-implementation.
-
-Enabled by @option{-Os}.
-
-@item -fdelete-null-pointer-checks
-@opindex fdelete-null-pointer-checks
-Assume that programs cannot safely dereference null pointers, and that
-no code or data element resides at address zero.
-This option enables simple constant
-folding optimizations at all optimization levels. In addition, other
-optimization passes in GCC use this flag to control global dataflow
-analyses that eliminate useless checks for null pointers; these assume
-that a memory access to address zero always results in a trap, so
-that if a pointer is checked after it has already been dereferenced,
-it cannot be null.
-
-Note however that in some environments this assumption is not true.
-Use @option{-fno-delete-null-pointer-checks} to disable this optimization
-for programs that depend on that behavior.
-
-This option is enabled by default on most targets. On Nios II ELF, it
-defaults to off. On AVR and MSP430, this option is completely disabled.
-
-Passes that use the dataflow information
-are enabled independently at different optimization levels.
-
-@item -fdevirtualize
-@opindex fdevirtualize
-Attempt to convert calls to virtual functions to direct calls. This
-is done both within a procedure and interprocedurally as part of
-indirect inlining (@option{-findirect-inlining}) and interprocedural constant
-propagation (@option{-fipa-cp}).
-Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
-
-@item -fdevirtualize-speculatively
-@opindex fdevirtualize-speculatively
-Attempt to convert calls to virtual functions to speculative direct calls.
-Based on the analysis of the type inheritance graph, determine for a given call
-the set of likely targets. If the set is small, preferably of size 1, change
-the call into a conditional deciding between direct and indirect calls. The
-speculative calls enable more optimizations, such as inlining. When they seem
-useless after further optimization, they are converted back into original form.
-
-@item -fdevirtualize-at-ltrans
-@opindex fdevirtualize-at-ltrans
-Stream extra information needed for aggressive devirtualization when running
-the link-time optimizer in local transformation mode.
-This option enables more devirtualization but
-significantly increases the size of streamed data. For this reason it is
-disabled by default.
-
-@item -fexpensive-optimizations
-@opindex fexpensive-optimizations
-Perform a number of minor optimizations that are relatively expensive.
-
-Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
-
-@item -free
-@opindex free
-Attempt to remove redundant extension instructions. This is especially
-helpful for the x86-64 architecture, which implicitly zero-extends in 64-bit
-registers after writing to their lower 32-bit half.
-
-Enabled for Alpha, AArch64 and x86 at levels @option{-O2},
-@option{-O3}, @option{-Os}.
-
-@item -fno-lifetime-dse
-@opindex fno-lifetime-dse
-@opindex flifetime-dse
-In C++ the value of an object is only affected by changes within its
-lifetime: when the constructor begins, the object has an indeterminate
-value, and any changes during the lifetime of the object are dead when
-the object is destroyed. Normally dead store elimination will take
-advantage of this; if your code relies on the value of the object
-storage persisting beyond the lifetime of the object, you can use this
-flag to disable this optimization. To preserve stores before the
-constructor starts (e.g.@: because your operator new clears the object
-storage) but still treat the object as dead after the destructor, you
-can use @option{-flifetime-dse=1}. The default behavior can be
-explicitly selected with @option{-flifetime-dse=2}.
-@option{-flifetime-dse=0} is equivalent to @option{-fno-lifetime-dse}.
-
-@item -flive-range-shrinkage
-@opindex flive-range-shrinkage
-Attempt to decrease register pressure through register live range
-shrinkage. This is helpful for fast processors with small or moderate
-size register sets.
-
-@item -fira-algorithm=@var{algorithm}
-@opindex fira-algorithm
-Use the specified coloring algorithm for the integrated register
-allocator. The @var{algorithm} argument can be @samp{priority}, which
-specifies Chow's priority coloring, or @samp{CB}, which specifies
-Chaitin-Briggs coloring. Chaitin-Briggs coloring is not implemented
-for all architectures, but for those targets that do support it, it is
-the default because it generates better code.
-
-@item -fira-region=@var{region}
-@opindex fira-region
-Use specified regions for the integrated register allocator. The
-@var{region} argument should be one of the following:
-
-@table @samp
-
-@item all
-Use all loops as register allocation regions.
-This can give the best results for machines with a small and/or
-irregular register set.
-
-@item mixed
-Use all loops except for loops with small register pressure
-as the regions. This value usually gives
-the best results in most cases and for most architectures,
-and is enabled by default when compiling with optimization for speed
-(@option{-O}, @option{-O2}, @dots{}).
-
-@item one
-Use all functions as a single region.
-This typically results in the smallest code size, and is enabled by default for
-@option{-Os} or @option{-O0}.
-
-@end table
-
-@item -fira-hoist-pressure
-@opindex fira-hoist-pressure
-Use IRA to evaluate register pressure in the code hoisting pass for
-decisions to hoist expressions. This option usually results in smaller
-code, but it can slow the compiler down.
-
-This option is enabled at level @option{-Os} for all targets.
-
-@item -fira-loop-pressure
-@opindex fira-loop-pressure
-Use IRA to evaluate register pressure in loops for decisions to move
-loop invariants. This option usually results in generation
-of faster and smaller code on machines with large register files (>= 32
-registers), but it can slow the compiler down.
-
-This option is enabled at level @option{-O3} for some targets.
-
-@item -fno-ira-share-save-slots
-@opindex fno-ira-share-save-slots
-@opindex fira-share-save-slots
-Disable sharing of stack slots used for saving call-used hard
-registers living through a call. Each hard register gets a
-separate stack slot, and as a result function stack frames are
-larger.
-
-@item -fno-ira-share-spill-slots
-@opindex fno-ira-share-spill-slots
-@opindex fira-share-spill-slots
-Disable sharing of stack slots allocated for pseudo-registers. Each
-pseudo-register that does not get a hard register gets a separate
-stack slot, and as a result function stack frames are larger.
-
-@item -flra-remat
-@opindex flra-remat
-Enable CFG-sensitive rematerialization in LRA. Instead of loading
-values of spilled pseudos, LRA tries to rematerialize (recalculate)
-values if it is profitable.
-
-Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
-
-@item -fdelayed-branch
-@opindex fdelayed-branch
-If supported for the target machine, attempt to reorder instructions
-to exploit instruction slots available after delayed branch
-instructions.
-
-Enabled at levels @option{-O1}, @option{-O2}, @option{-O3}, @option{-Os},
-but not at @option{-Og}.
-
-@item -fschedule-insns
-@opindex fschedule-insns
-If supported for the target machine, attempt to reorder instructions to
-eliminate execution stalls due to required data being unavailable. This
-helps machines that have slow floating point or memory load instructions
-by allowing other instructions to be issued until the result of the load
-or floating-point instruction is required.
-
-Enabled at levels @option{-O2}, @option{-O3}.
-
-@item -fschedule-insns2
-@opindex fschedule-insns2
-Similar to @option{-fschedule-insns}, but requests an additional pass of
-instruction scheduling after register allocation has been done. This is
-especially useful on machines with a relatively small number of
-registers and where memory load instructions take more than one cycle.
-
-Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
-
-@item -fno-sched-interblock
-@opindex fno-sched-interblock
-@opindex fsched-interblock
-Disable instruction scheduling across basic blocks, which
-is normally enabled when scheduling before register allocation, i.e.@:
-with @option{-fschedule-insns} or at @option{-O2} or higher.
-
-@item -fno-sched-spec
-@opindex fno-sched-spec
-@opindex fsched-spec
-Disable speculative motion of non-load instructions, which
-is normally enabled when scheduling before register allocation, i.e.@:
-with @option{-fschedule-insns} or at @option{-O2} or higher.
-
-@item -fsched-pressure
-@opindex fsched-pressure
-Enable register pressure sensitive insn scheduling before register
-allocation. This only makes sense when scheduling before register
-allocation is enabled, i.e.@: with @option{-fschedule-insns} or at
-@option{-O2} or higher. Usage of this option can improve the
-generated code and decrease its size by preventing register pressure
-increase above the number of available hard registers and subsequent
-spills in register allocation.
-
-@item -fsched-spec-load
-@opindex fsched-spec-load
-Allow speculative motion of some load instructions. This only makes
-sense when scheduling before register allocation, i.e.@: with
-@option{-fschedule-insns} or at @option{-O2} or higher.
-
-@item -fsched-spec-load-dangerous
-@opindex fsched-spec-load-dangerous
-Allow speculative motion of more load instructions. This only makes
-sense when scheduling before register allocation, i.e.@: with
-@option{-fschedule-insns} or at @option{-O2} or higher.
-
-@item -fsched-stalled-insns
-@itemx -fsched-stalled-insns=@var{n}
-@opindex fsched-stalled-insns
-Define how many insns (if any) can be moved prematurely from the queue
-of stalled insns into the ready list during the second scheduling pass.
-@option{-fno-sched-stalled-insns} means that no insns are moved
-prematurely, @option{-fsched-stalled-insns=0} means there is no limit
-on how many queued insns can be moved prematurely.
-@option{-fsched-stalled-insns} without a value is equivalent to
-@option{-fsched-stalled-insns=1}.
-
-@item -fsched-stalled-insns-dep
-@itemx -fsched-stalled-insns-dep=@var{n}
-@opindex fsched-stalled-insns-dep
-Define how many insn groups (cycles) are examined for a dependency
-on a stalled insn that is a candidate for premature removal from the queue
-of stalled insns. This has an effect only during the second scheduling pass,
-and only if @option{-fsched-stalled-insns} is used.
-@option{-fno-sched-stalled-insns-dep} is equivalent to
-@option{-fsched-stalled-insns-dep=0}.
-@option{-fsched-stalled-insns-dep} without a value is equivalent to
-@option{-fsched-stalled-insns-dep=1}.
-
-@item -fsched2-use-superblocks
-@opindex fsched2-use-superblocks
-When scheduling after register allocation, use superblock scheduling.
-This allows motion across basic block boundaries,
-resulting in faster schedules. This option is experimental, as not all machine
-descriptions used by GCC model the CPU closely enough to avoid unreliable
-results from the algorithm.
-
-This only makes sense when scheduling after register allocation, i.e.@: with
-@option{-fschedule-insns2} or at @option{-O2} or higher.
-
-@item -fsched-group-heuristic
-@opindex fsched-group-heuristic
-Enable the group heuristic in the scheduler. This heuristic favors
-the instruction that belongs to a schedule group. This is enabled
-by default when scheduling is enabled, i.e.@: with @option{-fschedule-insns}
-or @option{-fschedule-insns2} or at @option{-O2} or higher.
-
-@item -fsched-critical-path-heuristic
-@opindex fsched-critical-path-heuristic
-Enable the critical-path heuristic in the scheduler. This heuristic favors
-instructions on the critical path. This is enabled by default when
-scheduling is enabled, i.e.@: with @option{-fschedule-insns}
-or @option{-fschedule-insns2} or at @option{-O2} or higher.
-
-@item -fsched-spec-insn-heuristic
-@opindex fsched-spec-insn-heuristic
-Enable the speculative instruction heuristic in the scheduler. This
-heuristic favors speculative instructions with greater dependency weakness.
-This is enabled by default when scheduling is enabled, i.e.@:
-with @option{-fschedule-insns} or @option{-fschedule-insns2}
-or at @option{-O2} or higher.
-
-@item -fsched-rank-heuristic
-@opindex fsched-rank-heuristic
-Enable the rank heuristic in the scheduler. This heuristic favors
-the instruction belonging to a basic block with greater size or frequency.
-This is enabled by default when scheduling is enabled, i.e.@:
-with @option{-fschedule-insns} or @option{-fschedule-insns2} or
-at @option{-O2} or higher.
-
-@item -fsched-last-insn-heuristic
-@opindex fsched-last-insn-heuristic
-Enable the last-instruction heuristic in the scheduler. This heuristic
-favors the instruction that is less dependent on the last instruction
-scheduled. This is enabled by default when scheduling is enabled,
-i.e.@: with @option{-fschedule-insns} or @option{-fschedule-insns2} or
-at @option{-O2} or higher.
-
-@item -fsched-dep-count-heuristic
-@opindex fsched-dep-count-heuristic
-Enable the dependent-count heuristic in the scheduler. This heuristic
-favors the instruction that has more instructions depending on it.
-This is enabled by default when scheduling is enabled, i.e.@:
-with @option{-fschedule-insns} or @option{-fschedule-insns2} or
-at @option{-O2} or higher.
-
-@item -freschedule-modulo-scheduled-loops
-@opindex freschedule-modulo-scheduled-loops
-Modulo scheduling is performed before traditional scheduling. If a loop
-is modulo scheduled, later scheduling passes may change its schedule.
-Use this option to control that behavior.
-
-@item -fselective-scheduling
-@opindex fselective-scheduling
-Schedule instructions using selective scheduling algorithm. Selective
-scheduling runs instead of the first scheduler pass.
-
-@item -fselective-scheduling2
-@opindex fselective-scheduling2
-Schedule instructions using selective scheduling algorithm. Selective
-scheduling runs instead of the second scheduler pass.
-
-@item -fsel-sched-pipelining
-@opindex fsel-sched-pipelining
-Enable software pipelining of innermost loops during selective scheduling.
-This option has no effect unless one of @option{-fselective-scheduling} or
-@option{-fselective-scheduling2} is turned on.
-
-@item -fsel-sched-pipelining-outer-loops
-@opindex fsel-sched-pipelining-outer-loops
-When pipelining loops during selective scheduling, also pipeline outer loops.
-This option has no effect unless @option{-fsel-sched-pipelining} is turned on.
-
-@item -fsemantic-interposition
-@opindex fsemantic-interposition
-Some object formats, like ELF, allow interposing of symbols by the
-dynamic linker.
-This means that for symbols exported from the DSO, the compiler cannot perform
-interprocedural propagation, inlining and other optimizations in anticipation
-that the function or variable in question may change. While this feature is
-useful, for example, to rewrite memory allocation functions by a debugging
-implementation, it is expensive in the terms of code quality.
-With @option{-fno-semantic-interposition} the compiler assumes that
-if interposition happens for functions the overwriting function will have
-precisely the same semantics (and side effects).
-Similarly if interposition happens
-for variables, the constructor of the variable will be the same. The flag
-has no effect for functions explicitly declared inline
-(where it is never allowed for interposition to change semantics)
-and for symbols explicitly declared weak.
-
-@item -fshrink-wrap
-@opindex fshrink-wrap
-Emit function prologues only before parts of the function that need it,
-rather than at the top of the function. This flag is enabled by default at
-@option{-O} and higher.
-
-@item -fshrink-wrap-separate
-@opindex fshrink-wrap-separate
-Shrink-wrap separate parts of the prologue and epilogue separately, so that
-those parts are only executed when needed.
-This option is on by default, but has no effect unless @option{-fshrink-wrap}
-is also turned on and the target supports this.
-
-@item -fcaller-saves
-@opindex fcaller-saves
-Enable allocation of values to registers that are clobbered by
-function calls, by emitting extra instructions to save and restore the
-registers around such calls. Such allocation is done only when it
-seems to result in better code.
-
-This option is always enabled by default on certain machines, usually
-those which have no call-preserved registers to use instead.
-
-Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
-
-@item -fcombine-stack-adjustments
-@opindex fcombine-stack-adjustments
-Tracks stack adjustments (pushes and pops) and stack memory references
-and then tries to find ways to combine them.
-
-Enabled by default at @option{-O1} and higher.
-
-@item -fipa-ra
-@opindex fipa-ra
-Use caller save registers for allocation if those registers are not used by
-any called function. In that case it is not necessary to save and restore
-them around calls. This is only possible if called functions are part of
-same compilation unit as current function and they are compiled before it.
-
-Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}, however the option
-is disabled if generated code will be instrumented for profiling
-(@option{-p}, or @option{-pg}) or if callee's register usage cannot be known
-exactly (this happens on targets that do not expose prologues
-and epilogues in RTL).
-
-@item -fconserve-stack
-@opindex fconserve-stack
-Attempt to minimize stack usage. The compiler attempts to use less
-stack space, even if that makes the program slower. This option
-implies setting the @option{large-stack-frame} parameter to 100
-and the @option{large-stack-frame-growth} parameter to 400.
-
-@item -ftree-reassoc
-@opindex ftree-reassoc
-Perform reassociation on trees. This flag is enabled by default
-at @option{-O1} and higher.
-
-@item -fcode-hoisting
-@opindex fcode-hoisting
-Perform code hoisting. Code hoisting tries to move the
-evaluation of expressions executed on all paths to the function exit
-as early as possible. This is especially useful as a code size
-optimization, but it often helps for code speed as well.
-This flag is enabled by default at @option{-O2} and higher.
-
-@item -ftree-pre
-@opindex ftree-pre
-Perform partial redundancy elimination (PRE) on trees. This flag is
-enabled by default at @option{-O2} and @option{-O3}.
-
-@item -ftree-partial-pre
-@opindex ftree-partial-pre
-Make partial redundancy elimination (PRE) more aggressive. This flag is
-enabled by default at @option{-O3}.
-
-@item -ftree-forwprop
-@opindex ftree-forwprop
-Perform forward propagation on trees. This flag is enabled by default
-at @option{-O1} and higher.
-
-@item -ftree-fre
-@opindex ftree-fre
-Perform full redundancy elimination (FRE) on trees. The difference
-between FRE and PRE is that FRE only considers expressions
-that are computed on all paths leading to the redundant computation.
-This analysis is faster than PRE, though it exposes fewer redundancies.
-This flag is enabled by default at @option{-O1} and higher.
-
-@item -ftree-phiprop
-@opindex ftree-phiprop
-Perform hoisting of loads from conditional pointers on trees. This
-pass is enabled by default at @option{-O1} and higher.
-
-@item -fhoist-adjacent-loads
-@opindex fhoist-adjacent-loads
-Speculatively hoist loads from both branches of an if-then-else if the
-loads are from adjacent locations in the same structure and the target
-architecture has a conditional move instruction. This flag is enabled
-by default at @option{-O2} and higher.
-
-@item -ftree-copy-prop
-@opindex ftree-copy-prop
-Perform copy propagation on trees. This pass eliminates unnecessary
-copy operations. This flag is enabled by default at @option{-O1} and
-higher.
-
-@item -fipa-pure-const
-@opindex fipa-pure-const
-Discover which functions are pure or constant.
-Enabled by default at @option{-O1} and higher.
-
-@item -fipa-reference
-@opindex fipa-reference
-Discover which static variables do not escape the
-compilation unit.
-Enabled by default at @option{-O1} and higher.
-
-@item -fipa-reference-addressable
-@opindex fipa-reference-addressable
-Discover read-only, write-only and non-addressable static variables.
-Enabled by default at @option{-O1} and higher.
-
-@item -fipa-stack-alignment
-@opindex fipa-stack-alignment
-Reduce stack alignment on call sites if possible.
-Enabled by default.
-
-@item -fipa-pta
-@opindex fipa-pta
-Perform interprocedural pointer analysis and interprocedural modification
-and reference analysis. This option can cause excessive memory and
-compile-time usage on large compilation units. It is not enabled by
-default at any optimization level.
-
-@item -fipa-profile
-@opindex fipa-profile
-Perform interprocedural profile propagation. The functions called only from
-cold functions are marked as cold. Also functions executed once (such as
-@code{cold}, @code{noreturn}, static constructors or destructors) are
-identified. Cold functions and loop less parts of functions executed once are
-then optimized for size.
-Enabled by default at @option{-O1} and higher.
-
-@item -fipa-modref
-@opindex fipa-modref
-Perform interprocedural mod/ref analysis. This optimization analyzes the side
-effects of functions (memory locations that are modified or referenced) and
-enables better optimization across the function call boundary. This flag is
-enabled by default at @option{-O1} and higher.
-
-@item -fipa-cp
-@opindex fipa-cp
-Perform interprocedural constant propagation.
-This optimization analyzes the program to determine when values passed
-to functions are constants and then optimizes accordingly.
-This optimization can substantially increase performance
-if the application has constants passed to functions.
-This flag is enabled by default at @option{-O2}, @option{-Os} and @option{-O3}.
-It is also enabled by @option{-fprofile-use} and @option{-fauto-profile}.
-
-@item -fipa-cp-clone
-@opindex fipa-cp-clone
-Perform function cloning to make interprocedural constant propagation stronger.
-When enabled, interprocedural constant propagation performs function cloning
-when externally visible function can be called with constant arguments.
-Because this optimization can create multiple copies of functions,
-it may significantly increase code size
-(see @option{--param ipa-cp-unit-growth=@var{value}}).
-This flag is enabled by default at @option{-O3}.
-It is also enabled by @option{-fprofile-use} and @option{-fauto-profile}.
-
-@item -fipa-bit-cp
-@opindex fipa-bit-cp
-When enabled, perform interprocedural bitwise constant
-propagation. This flag is enabled by default at @option{-O2} and
-by @option{-fprofile-use} and @option{-fauto-profile}.
-It requires that @option{-fipa-cp} is enabled.
-
-@item -fipa-vrp
-@opindex fipa-vrp
-When enabled, perform interprocedural propagation of value
-ranges. This flag is enabled by default at @option{-O2}. It requires
-that @option{-fipa-cp} is enabled.
-
-@item -fipa-icf
-@opindex fipa-icf
-Perform Identical Code Folding for functions and read-only variables.
-The optimization reduces code size and may disturb unwind stacks by replacing
-a function by equivalent one with a different name. The optimization works
-more effectively with link-time optimization enabled.
-
-Although the behavior is similar to the Gold Linker's ICF optimization, GCC ICF
-works on different levels and thus the optimizations are not same - there are
-equivalences that are found only by GCC and equivalences found only by Gold.
-
-This flag is enabled by default at @option{-O2} and @option{-Os}.
-
-@item -flive-patching=@var{level}
-@opindex flive-patching
-Control GCC's optimizations to produce output suitable for live-patching.
-
-If the compiler's optimization uses a function's body or information extracted
-from its body to optimize/change another function, the latter is called an
-impacted function of the former. If a function is patched, its impacted
-functions should be patched too.
-
-The impacted functions are determined by the compiler's interprocedural
-optimizations. For example, a caller is impacted when inlining a function
-into its caller,
-cloning a function and changing its caller to call this new clone,
-or extracting a function's pureness/constness information to optimize
-its direct or indirect callers, etc.
-
-Usually, the more IPA optimizations enabled, the larger the number of
-impacted functions for each function. In order to control the number of
-impacted functions and more easily compute the list of impacted function,
-IPA optimizations can be partially enabled at two different levels.
-
-The @var{level} argument should be one of the following:
-
-@table @samp
-
-@item inline-clone
-
-Only enable inlining and cloning optimizations, which includes inlining,
-cloning, interprocedural scalar replacement of aggregates and partial inlining.
-As a result, when patching a function, all its callers and its clones'
-callers are impacted, therefore need to be patched as well.
-
-@option{-flive-patching=inline-clone} disables the following optimization flags:
-@gccoptlist{-fwhole-program -fipa-pta -fipa-reference -fipa-ra @gol
--fipa-icf -fipa-icf-functions -fipa-icf-variables @gol
--fipa-bit-cp -fipa-vrp -fipa-pure-const -fipa-reference-addressable @gol
--fipa-stack-alignment -fipa-modref}
-
-@item inline-only-static
-
-Only enable inlining of static functions.
-As a result, when patching a static function, all its callers are impacted
-and so need to be patched as well.
-
-In addition to all the flags that @option{-flive-patching=inline-clone}
-disables,
-@option{-flive-patching=inline-only-static} disables the following additional
-optimization flags:
-@gccoptlist{-fipa-cp-clone -fipa-sra -fpartial-inlining -fipa-cp}
-
-@end table
-
-When @option{-flive-patching} is specified without any value, the default value
-is @var{inline-clone}.
-
-This flag is disabled by default.
-
-Note that @option{-flive-patching} is not supported with link-time optimization
-(@option{-flto}).
-
-@item -fisolate-erroneous-paths-dereference
-@opindex fisolate-erroneous-paths-dereference
-Detect paths that trigger erroneous or undefined behavior due to
-dereferencing a null pointer. Isolate those paths from the main control
-flow and turn the statement with erroneous or undefined behavior into a trap.
-This flag is enabled by default at @option{-O2} and higher and depends on
-@option{-fdelete-null-pointer-checks} also being enabled.
-
-@item -fisolate-erroneous-paths-attribute
-@opindex fisolate-erroneous-paths-attribute
-Detect paths that trigger erroneous or undefined behavior due to a null value
-being used in a way forbidden by a @code{returns_nonnull} or @code{nonnull}
-attribute. Isolate those paths from the main control flow and turn the
-statement with erroneous or undefined behavior into a trap. This is not
-currently enabled, but may be enabled by @option{-O2} in the future.
-
-@item -ftree-sink
-@opindex ftree-sink
-Perform forward store motion on trees. This flag is
-enabled by default at @option{-O1} and higher.
-
-@item -ftree-bit-ccp
-@opindex ftree-bit-ccp
-Perform sparse conditional bit constant propagation on trees and propagate
-pointer alignment information.
-This pass only operates on local scalar variables and is enabled by default
-at @option{-O1} and higher, except for @option{-Og}.
-It requires that @option{-ftree-ccp} is enabled.
-
-@item -ftree-ccp
-@opindex ftree-ccp
-Perform sparse conditional constant propagation (CCP) on trees. This
-pass only operates on local scalar variables and is enabled by default
-at @option{-O1} and higher.
-
-@item -fssa-backprop
-@opindex fssa-backprop
-Propagate information about uses of a value up the definition chain
-in order to simplify the definitions. For example, this pass strips
-sign operations if the sign of a value never matters. The flag is
-enabled by default at @option{-O1} and higher.
-
-@item -fssa-phiopt
-@opindex fssa-phiopt
-Perform pattern matching on SSA PHI nodes to optimize conditional
-code. This pass is enabled by default at @option{-O1} and higher,
-except for @option{-Og}.
-
-@item -ftree-switch-conversion
-@opindex ftree-switch-conversion
-Perform conversion of simple initializations in a switch to
-initializations from a scalar array. This flag is enabled by default
-at @option{-O2} and higher.
-
-@item -ftree-tail-merge
-@opindex ftree-tail-merge
-Look for identical code sequences. When found, replace one with a jump to the
-other. This optimization is known as tail merging or cross jumping. This flag
-is enabled by default at @option{-O2} and higher. The compilation time
-in this pass can
-be limited using @option{max-tail-merge-comparisons} parameter and
-@option{max-tail-merge-iterations} parameter.
-
-@item -ftree-dce
-@opindex ftree-dce
-Perform dead code elimination (DCE) on trees. This flag is enabled by
-default at @option{-O1} and higher.
-
-@item -ftree-builtin-call-dce
-@opindex ftree-builtin-call-dce
-Perform conditional dead code elimination (DCE) for calls to built-in functions
-that may set @code{errno} but are otherwise free of side effects. This flag is
-enabled by default at @option{-O2} and higher if @option{-Os} is not also
-specified.
-
-@item -ffinite-loops
-@opindex ffinite-loops
-@opindex fno-finite-loops
-Assume that a loop with an exit will eventually take the exit and not loop
-indefinitely. This allows the compiler to remove loops that otherwise have
-no side-effects, not considering eventual endless looping as such.
-
-This option is enabled by default at @option{-O2} for C++ with -std=c++11
-or higher.
-
-@item -ftree-dominator-opts
-@opindex ftree-dominator-opts
-Perform a variety of simple scalar cleanups (constant/copy
-propagation, redundancy elimination, range propagation and expression
-simplification) based on a dominator tree traversal. This also
-performs jump threading (to reduce jumps to jumps). This flag is
-enabled by default at @option{-O1} and higher.
-
-@item -ftree-dse
-@opindex ftree-dse
-Perform dead store elimination (DSE) on trees. A dead store is a store into
-a memory location that is later overwritten by another store without
-any intervening loads. In this case the earlier store can be deleted. This
-flag is enabled by default at @option{-O1} and higher.
-
-@item -ftree-ch
-@opindex ftree-ch
-Perform loop header copying on trees. This is beneficial since it increases
-effectiveness of code motion optimizations. It also saves one jump. This flag
-is enabled by default at @option{-O1} and higher. It is not enabled
-for @option{-Os}, since it usually increases code size.
-
-@item -ftree-loop-optimize
-@opindex ftree-loop-optimize
-Perform loop optimizations on trees. This flag is enabled by default
-at @option{-O1} and higher.
-
-@item -ftree-loop-linear
-@itemx -floop-strip-mine
-@itemx -floop-block
-@opindex ftree-loop-linear
-@opindex floop-strip-mine
-@opindex floop-block
-Perform loop nest optimizations. Same as
-@option{-floop-nest-optimize}. To use this code transformation, GCC has
-to be configured with @option{--with-isl} to enable the Graphite loop
-transformation infrastructure.
-
-@item -fgraphite-identity
-@opindex fgraphite-identity
-Enable the identity transformation for graphite. For every SCoP we generate
-the polyhedral representation and transform it back to gimple. Using
-@option{-fgraphite-identity} we can check the costs or benefits of the
-GIMPLE -> GRAPHITE -> GIMPLE transformation. Some minimal optimizations
-are also performed by the code generator isl, like index splitting and
-dead code elimination in loops.
-
-@item -floop-nest-optimize
-@opindex floop-nest-optimize
-Enable the isl based loop nest optimizer. This is a generic loop nest
-optimizer based on the Pluto optimization algorithms. It calculates a loop
-structure optimized for data-locality and parallelism. This option
-is experimental.
-
-@item -floop-parallelize-all
-@opindex floop-parallelize-all
-Use the Graphite data dependence analysis to identify loops that can
-be parallelized. Parallelize all the loops that can be analyzed to
-not contain loop carried dependences without checking that it is
-profitable to parallelize the loops.
-
-@item -ftree-coalesce-vars
-@opindex ftree-coalesce-vars
-While transforming the program out of the SSA representation, attempt to
-reduce copying by coalescing versions of different user-defined
-variables, instead of just compiler temporaries. This may severely
-limit the ability to debug an optimized program compiled with
-@option{-fno-var-tracking-assignments}. In the negated form, this flag
-prevents SSA coalescing of user variables. This option is enabled by
-default if optimization is enabled, and it does very little otherwise.
-
-@item -ftree-loop-if-convert
-@opindex ftree-loop-if-convert
-Attempt to transform conditional jumps in the innermost loops to
-branch-less equivalents. The intent is to remove control-flow from
-the innermost loops in order to improve the ability of the
-vectorization pass to handle these loops. This is enabled by default
-if vectorization is enabled.
-
-@item -ftree-loop-distribution
-@opindex ftree-loop-distribution
-Perform loop distribution. This flag can improve cache performance on
-big loop bodies and allow further loop optimizations, like
-parallelization or vectorization, to take place. For example, the loop
-@smallexample
-DO I = 1, N
- A(I) = B(I) + C
- D(I) = E(I) * F
-ENDDO
-@end smallexample
-is transformed to
-@smallexample
-DO I = 1, N
- A(I) = B(I) + C
-ENDDO
-DO I = 1, N
- D(I) = E(I) * F
-ENDDO
-@end smallexample
-This flag is enabled by default at @option{-O3}.
-It is also enabled by @option{-fprofile-use} and @option{-fauto-profile}.
-
-@item -ftree-loop-distribute-patterns
-@opindex ftree-loop-distribute-patterns
-Perform loop distribution of patterns that can be code generated with
-calls to a library. This flag is enabled by default at @option{-O2} and
-higher, and by @option{-fprofile-use} and @option{-fauto-profile}.
-
-This pass distributes the initialization loops and generates a call to
-memset zero. For example, the loop
-@smallexample
-DO I = 1, N
- A(I) = 0
- B(I) = A(I) + I
-ENDDO
-@end smallexample
-is transformed to
-@smallexample
-DO I = 1, N
- A(I) = 0
-ENDDO
-DO I = 1, N
- B(I) = A(I) + I
-ENDDO
-@end smallexample
-and the initialization loop is transformed into a call to memset zero.
-This flag is enabled by default at @option{-O3}.
-It is also enabled by @option{-fprofile-use} and @option{-fauto-profile}.
-
-@item -floop-interchange
-@opindex floop-interchange
-Perform loop interchange outside of graphite. This flag can improve cache
-performance on loop nest and allow further loop optimizations, like
-vectorization, to take place. For example, the loop
-@smallexample
-for (int i = 0; i < N; i++)
- for (int j = 0; j < N; j++)
- for (int k = 0; k < N; k++)
- c[i][j] = c[i][j] + a[i][k]*b[k][j];
-@end smallexample
-is transformed to
-@smallexample
-for (int i = 0; i < N; i++)
- for (int k = 0; k < N; k++)
- for (int j = 0; j < N; j++)
- c[i][j] = c[i][j] + a[i][k]*b[k][j];
-@end smallexample
-This flag is enabled by default at @option{-O3}.
-It is also enabled by @option{-fprofile-use} and @option{-fauto-profile}.
-
-@item -floop-unroll-and-jam
-@opindex floop-unroll-and-jam
-Apply unroll and jam transformations on feasible loops. In a loop
-nest this unrolls the outer loop by some factor and fuses the resulting
-multiple inner loops. This flag is enabled by default at @option{-O3}.
-It is also enabled by @option{-fprofile-use} and @option{-fauto-profile}.
-
-@item -ftree-loop-im
-@opindex ftree-loop-im
-Perform loop invariant motion on trees. This pass moves only invariants that
-are hard to handle at RTL level (function calls, operations that expand to
-nontrivial sequences of insns). With @option{-funswitch-loops} it also moves
-operands of conditions that are invariant out of the loop, so that we can use
-just trivial invariantness analysis in loop unswitching. The pass also includes
-store motion.
-
-@item -ftree-loop-ivcanon
-@opindex ftree-loop-ivcanon
-Create a canonical counter for number of iterations in loops for which
-determining number of iterations requires complicated analysis. Later
-optimizations then may determine the number easily. Useful especially
-in connection with unrolling.
-
-@item -ftree-scev-cprop
-@opindex ftree-scev-cprop
-Perform final value replacement. If a variable is modified in a loop
-in such a way that its value when exiting the loop can be determined using
-only its initial value and the number of loop iterations, replace uses of
-the final value by such a computation, provided it is sufficiently cheap.
-This reduces data dependencies and may allow further simplifications.
-Enabled by default at @option{-O1} and higher.
-
-@item -fivopts
-@opindex fivopts
-Perform induction variable optimizations (strength reduction, induction
-variable merging and induction variable elimination) on trees.
-
-@item -ftree-parallelize-loops=n
-@opindex ftree-parallelize-loops
-Parallelize loops, i.e., split their iteration space to run in n threads.
-This is only possible for loops whose iterations are independent
-and can be arbitrarily reordered. The optimization is only
-profitable on multiprocessor machines, for loops that are CPU-intensive,
-rather than constrained e.g.@: by memory bandwidth. This option
-implies @option{-pthread}, and thus is only supported on targets
-that have support for @option{-pthread}.
-
-@item -ftree-pta
-@opindex ftree-pta
-Perform function-local points-to analysis on trees. This flag is
-enabled by default at @option{-O1} and higher, except for @option{-Og}.
-
-@item -ftree-sra
-@opindex ftree-sra
-Perform scalar replacement of aggregates. This pass replaces structure
-references with scalars to prevent committing structures to memory too
-early. This flag is enabled by default at @option{-O1} and higher,
-except for @option{-Og}.
-
-@item -fstore-merging
-@opindex fstore-merging
-Perform merging of narrow stores to consecutive memory addresses. This pass
-merges contiguous stores of immediate values narrower than a word into fewer
-wider stores to reduce the number of instructions. This is enabled by default
-at @option{-O2} and higher as well as @option{-Os}.
-
-@item -ftree-ter
-@opindex ftree-ter
-Perform temporary expression replacement during the SSA->normal phase. Single
-use/single def temporaries are replaced at their use location with their
-defining expression. This results in non-GIMPLE code, but gives the expanders
-much more complex trees to work on resulting in better RTL generation. This is
-enabled by default at @option{-O1} and higher.
-
-@item -ftree-slsr
-@opindex ftree-slsr
-Perform straight-line strength reduction on trees. This recognizes related
-expressions involving multiplications and replaces them by less expensive
-calculations when possible. This is enabled by default at @option{-O1} and
-higher.
-
-@item -ftree-vectorize
-@opindex ftree-vectorize
-Perform vectorization on trees. This flag enables @option{-ftree-loop-vectorize}
-and @option{-ftree-slp-vectorize} if not explicitly specified.
-
-@item -ftree-loop-vectorize
-@opindex ftree-loop-vectorize
-Perform loop vectorization on trees. This flag is enabled by default at
-@option{-O2} and by @option{-ftree-vectorize}, @option{-fprofile-use},
-and @option{-fauto-profile}.
-
-@item -ftree-slp-vectorize
-@opindex ftree-slp-vectorize
-Perform basic block vectorization on trees. This flag is enabled by default at
-@option{-O2} and by @option{-ftree-vectorize}, @option{-fprofile-use},
-and @option{-fauto-profile}.
-
-@item -ftrivial-auto-var-init=@var{choice}
-@opindex ftrivial-auto-var-init
-Initialize automatic variables with either a pattern or with zeroes to increase
-the security and predictability of a program by preventing uninitialized memory
-disclosure and use.
-GCC still considers an automatic variable that doesn't have an explicit
-initializer as uninitialized, @option{-Wuninitialized} and
-@option{-Wanalyzer-use-of-uninitialized-value} will still report
-warning messages on such automatic variables.
-With this option, GCC will also initialize any padding of automatic variables
-that have structure or union types to zeroes.
-However, the current implementation cannot initialize automatic variables that
-are declared between the controlling expression and the first case of a
-@code{switch} statement. Using @option{-Wtrivial-auto-var-init} to report all
-such cases.
-
-The three values of @var{choice} are:
-
-@itemize @bullet
-@item
-@samp{uninitialized} doesn't initialize any automatic variables.
-This is C and C++'s default.
-
-@item
-@samp{pattern} Initialize automatic variables with values which will likely
-transform logic bugs into crashes down the line, are easily recognized in a
-crash dump and without being values that programmers can rely on for useful
-program semantics.
-The current value is byte-repeatable pattern with byte "0xFE".
-The values used for pattern initialization might be changed in the future.
-
-@item
-@samp{zero} Initialize automatic variables with zeroes.
-@end itemize
-
-The default is @samp{uninitialized}.
-
-You can control this behavior for a specific variable by using the variable
-attribute @code{uninitialized} (@pxref{Variable Attributes}).
-
-@item -fvect-cost-model=@var{model}
-@opindex fvect-cost-model
-Alter the cost model used for vectorization. The @var{model} argument
-should be one of @samp{unlimited}, @samp{dynamic}, @samp{cheap} or
-@samp{very-cheap}.
-With the @samp{unlimited} model the vectorized code-path is assumed
-to be profitable while with the @samp{dynamic} model a runtime check
-guards the vectorized code-path to enable it only for iteration
-counts that will likely execute faster than when executing the original
-scalar loop. The @samp{cheap} model disables vectorization of
-loops where doing so would be cost prohibitive for example due to
-required runtime checks for data dependence or alignment but otherwise
-is equal to the @samp{dynamic} model. The @samp{very-cheap} model only
-allows vectorization if the vector code would entirely replace the
-scalar code that is being vectorized. For example, if each iteration
-of a vectorized loop would only be able to handle exactly four iterations
-of the scalar loop, the @samp{very-cheap} model would only allow
-vectorization if the scalar iteration count is known to be a multiple
-of four.
-
-The default cost model depends on other optimization flags and is
-either @samp{dynamic} or @samp{cheap}.
-
-@item -fsimd-cost-model=@var{model}
-@opindex fsimd-cost-model
-Alter the cost model used for vectorization of loops marked with the OpenMP
-simd directive. The @var{model} argument should be one of
-@samp{unlimited}, @samp{dynamic}, @samp{cheap}. All values of @var{model}
-have the same meaning as described in @option{-fvect-cost-model} and by
-default a cost model defined with @option{-fvect-cost-model} is used.
-
-@item -ftree-vrp
-@opindex ftree-vrp
-Perform Value Range Propagation on trees. This is similar to the
-constant propagation pass, but instead of values, ranges of values are
-propagated. This allows the optimizers to remove unnecessary range
-checks like array bound checks and null pointer checks. This is
-enabled by default at @option{-O2} and higher. Null pointer check
-elimination is only done if @option{-fdelete-null-pointer-checks} is
-enabled.
-
-@item -fsplit-paths
-@opindex fsplit-paths
-Split paths leading to loop backedges. This can improve dead code
-elimination and common subexpression elimination. This is enabled by
-default at @option{-O3} and above.
-
-@item -fsplit-ivs-in-unroller
-@opindex fsplit-ivs-in-unroller
-Enables expression of values of induction variables in later iterations
-of the unrolled loop using the value in the first iteration. This breaks
-long dependency chains, thus improving efficiency of the scheduling passes.
-
-A combination of @option{-fweb} and CSE is often sufficient to obtain the
-same effect. However, that is not reliable in cases where the loop body
-is more complicated than a single basic block. It also does not work at all
-on some architectures due to restrictions in the CSE pass.
-
-This optimization is enabled by default.
-
-@item -fvariable-expansion-in-unroller
-@opindex fvariable-expansion-in-unroller
-With this option, the compiler creates multiple copies of some
-local variables when unrolling a loop, which can result in superior code.
-
-This optimization is enabled by default for PowerPC targets, but disabled
-by default otherwise.
-
-@item -fpartial-inlining
-@opindex fpartial-inlining
-Inline parts of functions. This option has any effect only
-when inlining itself is turned on by the @option{-finline-functions}
-or @option{-finline-small-functions} options.
-
-Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
-
-@item -fpredictive-commoning
-@opindex fpredictive-commoning
-Perform predictive commoning optimization, i.e., reusing computations
-(especially memory loads and stores) performed in previous
-iterations of loops.
-
-This option is enabled at level @option{-O3}.
-It is also enabled by @option{-fprofile-use} and @option{-fauto-profile}.
-
-@item -fprefetch-loop-arrays
-@opindex fprefetch-loop-arrays
-If supported by the target machine, generate instructions to prefetch
-memory to improve the performance of loops that access large arrays.
-
-This option may generate better or worse code; results are highly
-dependent on the structure of loops within the source code.
-
-Disabled at level @option{-Os}.
-
-@item -fno-printf-return-value
-@opindex fno-printf-return-value
-@opindex fprintf-return-value
-Do not substitute constants for known return value of formatted output
-functions such as @code{sprintf}, @code{snprintf}, @code{vsprintf}, and
-@code{vsnprintf} (but not @code{printf} of @code{fprintf}). This
-transformation allows GCC to optimize or even eliminate branches based
-on the known return value of these functions called with arguments that
-are either constant, or whose values are known to be in a range that
-makes determining the exact return value possible. For example, when
-@option{-fprintf-return-value} is in effect, both the branch and the
-body of the @code{if} statement (but not the call to @code{snprint})
-can be optimized away when @code{i} is a 32-bit or smaller integer
-because the return value is guaranteed to be at most 8.
-
-@smallexample
-char buf[9];
-if (snprintf (buf, "%08x", i) >= sizeof buf)
- @dots{}
-@end smallexample
-
-The @option{-fprintf-return-value} option relies on other optimizations
-and yields best results with @option{-O2} and above. It works in tandem
-with the @option{-Wformat-overflow} and @option{-Wformat-truncation}
-options. The @option{-fprintf-return-value} option is enabled by default.
-
-@item -fno-peephole
-@itemx -fno-peephole2
-@opindex fno-peephole
-@opindex fpeephole
-@opindex fno-peephole2
-@opindex fpeephole2
-Disable any machine-specific peephole optimizations. The difference
-between @option{-fno-peephole} and @option{-fno-peephole2} is in how they
-are implemented in the compiler; some targets use one, some use the
-other, a few use both.
-
-@option{-fpeephole} is enabled by default.
-@option{-fpeephole2} enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
-
-@item -fno-guess-branch-probability
-@opindex fno-guess-branch-probability
-@opindex fguess-branch-probability
-Do not guess branch probabilities using heuristics.
-
-GCC uses heuristics to guess branch probabilities if they are
-not provided by profiling feedback (@option{-fprofile-arcs}). These
-heuristics are based on the control flow graph. If some branch probabilities
-are specified by @code{__builtin_expect}, then the heuristics are
-used to guess branch probabilities for the rest of the control flow graph,
-taking the @code{__builtin_expect} info into account. The interactions
-between the heuristics and @code{__builtin_expect} can be complex, and in
-some cases, it may be useful to disable the heuristics so that the effects
-of @code{__builtin_expect} are easier to understand.
-
-It is also possible to specify expected probability of the expression
-with @code{__builtin_expect_with_probability} built-in function.
-
-The default is @option{-fguess-branch-probability} at levels
-@option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
-
-@item -freorder-blocks
-@opindex freorder-blocks
-Reorder basic blocks in the compiled function in order to reduce number of
-taken branches and improve code locality.
-
-Enabled at levels @option{-O1}, @option{-O2}, @option{-O3}, @option{-Os}.
-
-@item -freorder-blocks-algorithm=@var{algorithm}
-@opindex freorder-blocks-algorithm
-Use the specified algorithm for basic block reordering. The
-@var{algorithm} argument can be @samp{simple}, which does not increase
-code size (except sometimes due to secondary effects like alignment),
-or @samp{stc}, the ``software trace cache'' algorithm, which tries to
-put all often executed code together, minimizing the number of branches
-executed by making extra copies of code.
-
-The default is @samp{simple} at levels @option{-O1}, @option{-Os}, and
-@samp{stc} at levels @option{-O2}, @option{-O3}.
-
-@item -freorder-blocks-and-partition
-@opindex freorder-blocks-and-partition
-In addition to reordering basic blocks in the compiled function, in order
-to reduce number of taken branches, partitions hot and cold basic blocks
-into separate sections of the assembly and @file{.o} files, to improve
-paging and cache locality performance.
-
-This optimization is automatically turned off in the presence of
-exception handling or unwind tables (on targets using setjump/longjump or target specific scheme), for linkonce sections, for functions with a user-defined
-section attribute and on any architecture that does not support named
-sections. When @option{-fsplit-stack} is used this option is not
-enabled by default (to avoid linker errors), but may be enabled
-explicitly (if using a working linker).
-
-Enabled for x86 at levels @option{-O2}, @option{-O3}, @option{-Os}.
-
-@item -freorder-functions
-@opindex freorder-functions
-Reorder functions in the object file in order to
-improve code locality. This is implemented by using special
-subsections @code{.text.hot} for most frequently executed functions and
-@code{.text.unlikely} for unlikely executed functions. Reordering is done by
-the linker so object file format must support named sections and linker must
-place them in a reasonable way.
-
-This option isn't effective unless you either provide profile feedback
-(see @option{-fprofile-arcs} for details) or manually annotate functions with
-@code{hot} or @code{cold} attributes (@pxref{Common Function Attributes}).
-
-Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
-
-@item -fstrict-aliasing
-@opindex fstrict-aliasing
-Allow the compiler to assume the strictest aliasing rules applicable to
-the language being compiled. For C (and C++), this activates
-optimizations based on the type of expressions. In particular, an
-object of one type is assumed never to reside at the same address as an
-object of a different type, unless the types are almost the same. For
-example, an @code{unsigned int} can alias an @code{int}, but not a
-@code{void*} or a @code{double}. A character type may alias any other
-type.
-
-@anchor{Type-punning}Pay special attention to code like this:
-@smallexample
-union a_union @{
- int i;
- double d;
-@};
-
-int f() @{
- union a_union t;
- t.d = 3.0;
- return t.i;
-@}
-@end smallexample
-The practice of reading from a different union member than the one most
-recently written to (called ``type-punning'') is common. Even with
-@option{-fstrict-aliasing}, type-punning is allowed, provided the memory
-is accessed through the union type. So, the code above works as
-expected. @xref{Structures unions enumerations and bit-fields
-implementation}. However, this code might not:
-@smallexample
-int f() @{
- union a_union t;
- int* ip;
- t.d = 3.0;
- ip = &t.i;
- return *ip;
-@}
-@end smallexample
-
-Similarly, access by taking the address, casting the resulting pointer
-and dereferencing the result has undefined behavior, even if the cast
-uses a union type, e.g.:
-@smallexample
-int f() @{
- double d = 3.0;
- return ((union a_union *) &d)->i;
-@}
-@end smallexample
-
-The @option{-fstrict-aliasing} option is enabled at levels
-@option{-O2}, @option{-O3}, @option{-Os}.
-
-@item -fipa-strict-aliasing
-@opindex fipa-strict-aliasing
-Controls whether rules of @option{-fstrict-aliasing} are applied across
-function boundaries. Note that if multiple functions gets inlined into a
-single function the memory accesses are no longer considered to be crossing a
-function boundary.
-
-The @option{-fipa-strict-aliasing} option is enabled by default and is
-effective only in combination with @option{-fstrict-aliasing}.
-
-@item -falign-functions
-@itemx -falign-functions=@var{n}
-@itemx -falign-functions=@var{n}:@var{m}
-@itemx -falign-functions=@var{n}:@var{m}:@var{n2}
-@itemx -falign-functions=@var{n}:@var{m}:@var{n2}:@var{m2}
-@opindex falign-functions
-Align the start of functions to the next power-of-two greater than or
-equal to @var{n}, skipping up to @var{m}-1 bytes. This ensures that at
-least the first @var{m} bytes of the function can be fetched by the CPU
-without crossing an @var{n}-byte alignment boundary.
-
-If @var{m} is not specified, it defaults to @var{n}.
-
-Examples: @option{-falign-functions=32} aligns functions to the next
-32-byte boundary, @option{-falign-functions=24} aligns to the next
-32-byte boundary only if this can be done by skipping 23 bytes or less,
-@option{-falign-functions=32:7} aligns to the next
-32-byte boundary only if this can be done by skipping 6 bytes or less.
-
-The second pair of @var{n2}:@var{m2} values allows you to specify
-a secondary alignment: @option{-falign-functions=64:7:32:3} aligns to
-the next 64-byte boundary if this can be done by skipping 6 bytes or less,
-otherwise aligns to the next 32-byte boundary if this can be done
-by skipping 2 bytes or less.
-If @var{m2} is not specified, it defaults to @var{n2}.
-
-Some assemblers only support this flag when @var{n} is a power of two;
-in that case, it is rounded up.
-
-@option{-fno-align-functions} and @option{-falign-functions=1} are
-equivalent and mean that functions are not aligned.
-
-If @var{n} is not specified or is zero, use a machine-dependent default.
-The maximum allowed @var{n} option value is 65536.
-
-Enabled at levels @option{-O2}, @option{-O3}.
-
-@item -flimit-function-alignment
-If this option is enabled, the compiler tries to avoid unnecessarily
-overaligning functions. It attempts to instruct the assembler to align
-by the amount specified by @option{-falign-functions}, but not to
-skip more bytes than the size of the function.
-
-@item -falign-labels
-@itemx -falign-labels=@var{n}
-@itemx -falign-labels=@var{n}:@var{m}
-@itemx -falign-labels=@var{n}:@var{m}:@var{n2}
-@itemx -falign-labels=@var{n}:@var{m}:@var{n2}:@var{m2}
-@opindex falign-labels
-Align all branch targets to a power-of-two boundary.
-
-Parameters of this option are analogous to the @option{-falign-functions} option.
-@option{-fno-align-labels} and @option{-falign-labels=1} are
-equivalent and mean that labels are not aligned.
-
-If @option{-falign-loops} or @option{-falign-jumps} are applicable and
-are greater than this value, then their values are used instead.
-
-If @var{n} is not specified or is zero, use a machine-dependent default
-which is very likely to be @samp{1}, meaning no alignment.
-The maximum allowed @var{n} option value is 65536.
-
-Enabled at levels @option{-O2}, @option{-O3}.
-
-@item -falign-loops
-@itemx -falign-loops=@var{n}
-@itemx -falign-loops=@var{n}:@var{m}
-@itemx -falign-loops=@var{n}:@var{m}:@var{n2}
-@itemx -falign-loops=@var{n}:@var{m}:@var{n2}:@var{m2}
-@opindex falign-loops
-Align loops to a power-of-two boundary. If the loops are executed
-many times, this makes up for any execution of the dummy padding
-instructions.
-
-If @option{-falign-labels} is greater than this value, then its value
-is used instead.
-
-Parameters of this option are analogous to the @option{-falign-functions} option.
-@option{-fno-align-loops} and @option{-falign-loops=1} are
-equivalent and mean that loops are not aligned.
-The maximum allowed @var{n} option value is 65536.
-
-If @var{n} is not specified or is zero, use a machine-dependent default.
-
-Enabled at levels @option{-O2}, @option{-O3}.
-
-@item -falign-jumps
-@itemx -falign-jumps=@var{n}
-@itemx -falign-jumps=@var{n}:@var{m}
-@itemx -falign-jumps=@var{n}:@var{m}:@var{n2}
-@itemx -falign-jumps=@var{n}:@var{m}:@var{n2}:@var{m2}
-@opindex falign-jumps
-Align branch targets to a power-of-two boundary, for branch targets
-where the targets can only be reached by jumping. In this case,
-no dummy operations need be executed.
-
-If @option{-falign-labels} is greater than this value, then its value
-is used instead.
-
-Parameters of this option are analogous to the @option{-falign-functions} option.
-@option{-fno-align-jumps} and @option{-falign-jumps=1} are
-equivalent and mean that loops are not aligned.
-
-If @var{n} is not specified or is zero, use a machine-dependent default.
-The maximum allowed @var{n} option value is 65536.
-
-Enabled at levels @option{-O2}, @option{-O3}.
-
-@item -fno-allocation-dce
-@opindex fno-allocation-dce
-Do not remove unused C++ allocations in dead code elimination.
-
-@item -fallow-store-data-races
-@opindex fallow-store-data-races
-Allow the compiler to perform optimizations that may introduce new data races
-on stores, without proving that the variable cannot be concurrently accessed
-by other threads. Does not affect optimization of local data. It is safe to
-use this option if it is known that global data will not be accessed by
-multiple threads.
-
-Examples of optimizations enabled by @option{-fallow-store-data-races} include
-hoisting or if-conversions that may cause a value that was already in memory
-to be re-written with that same value. Such re-writing is safe in a single
-threaded context but may be unsafe in a multi-threaded context. Note that on
-some processors, if-conversions may be required in order to enable
-vectorization.
-
-Enabled at level @option{-Ofast}.
-
-@item -funit-at-a-time
-@opindex funit-at-a-time
-This option is left for compatibility reasons. @option{-funit-at-a-time}
-has no effect, while @option{-fno-unit-at-a-time} implies
-@option{-fno-toplevel-reorder} and @option{-fno-section-anchors}.
-
-Enabled by default.
-
-@item -fno-toplevel-reorder
-@opindex fno-toplevel-reorder
-@opindex ftoplevel-reorder
-Do not reorder top-level functions, variables, and @code{asm}
-statements. Output them in the same order that they appear in the
-input file. When this option is used, unreferenced static variables
-are not removed. This option is intended to support existing code
-that relies on a particular ordering. For new code, it is better to
-use attributes when possible.
-
-@option{-ftoplevel-reorder} is the default at @option{-O1} and higher, and
-also at @option{-O0} if @option{-fsection-anchors} is explicitly requested.
-Additionally @option{-fno-toplevel-reorder} implies
-@option{-fno-section-anchors}.
-
-@item -funreachable-traps
-@opindex funreachable-traps
-With this option, the compiler turns calls to
-@code{__builtin_unreachable} into traps, instead of using them for
-optimization. This also affects any such calls implicitly generated
-by the compiler.
-
-This option has the same effect as @option{-fsanitize=unreachable
--fsanitize-trap=unreachable}, but does not affect the values of those
-options. If @option{-fsanitize=unreachable} is enabled, that option
-takes priority over this one.
-
-This option is enabled by default at @option{-O0} and @option{-Og}.
-
-@item -fweb
-@opindex fweb
-Constructs webs as commonly used for register allocation purposes and assign
-each web individual pseudo register. This allows the register allocation pass
-to operate on pseudos directly, but also strengthens several other optimization
-passes, such as CSE, loop optimizer and trivial dead code remover. It can,
-however, make debugging impossible, since variables no longer stay in a
-``home register''.
-
-Enabled by default with @option{-funroll-loops}.
-
-@item -fwhole-program
-@opindex fwhole-program
-Assume that the current compilation unit represents the whole program being
-compiled. All public functions and variables with the exception of @code{main}
-and those merged by attribute @code{externally_visible} become static functions
-and in effect are optimized more aggressively by interprocedural optimizers.
-
-This option should not be used in combination with @option{-flto}.
-Instead relying on a linker plugin should provide safer and more precise
-information.
-
-@item -flto[=@var{n}]
-@opindex flto
-This option runs the standard link-time optimizer. When invoked
-with source code, it generates GIMPLE (one of GCC's internal
-representations) and writes it to special ELF sections in the object
-file. When the object files are linked together, all the function
-bodies are read from these ELF sections and instantiated as if they
-had been part of the same translation unit.
-
-To use the link-time optimizer, @option{-flto} and optimization
-options should be specified at compile time and during the final link.
-It is recommended that you compile all the files participating in the
-same link with the same options and also specify those options at
-link time.
-For example:
-
-@smallexample
-gcc -c -O2 -flto foo.c
-gcc -c -O2 -flto bar.c
-gcc -o myprog -flto -O2 foo.o bar.o
-@end smallexample
-
-The first two invocations to GCC save a bytecode representation
-of GIMPLE into special ELF sections inside @file{foo.o} and
-@file{bar.o}. The final invocation reads the GIMPLE bytecode from
-@file{foo.o} and @file{bar.o}, merges the two files into a single
-internal image, and compiles the result as usual. Since both
-@file{foo.o} and @file{bar.o} are merged into a single image, this
-causes all the interprocedural analyses and optimizations in GCC to
-work across the two files as if they were a single one. This means,
-for example, that the inliner is able to inline functions in
-@file{bar.o} into functions in @file{foo.o} and vice-versa.
-
-Another (simpler) way to enable link-time optimization is:
-
-@smallexample
-gcc -o myprog -flto -O2 foo.c bar.c
-@end smallexample
-
-The above generates bytecode for @file{foo.c} and @file{bar.c},
-merges them together into a single GIMPLE representation and optimizes
-them as usual to produce @file{myprog}.
-
-The important thing to keep in mind is that to enable link-time
-optimizations you need to use the GCC driver to perform the link step.
-GCC automatically performs link-time optimization if any of the
-objects involved were compiled with the @option{-flto} command-line option.
-You can always override
-the automatic decision to do link-time optimization
-by passing @option{-fno-lto} to the link command.
-
-To make whole program optimization effective, it is necessary to make
-certain whole program assumptions. The compiler needs to know
-what functions and variables can be accessed by libraries and runtime
-outside of the link-time optimized unit. When supported by the linker,
-the linker plugin (see @option{-fuse-linker-plugin}) passes information
-to the compiler about used and externally visible symbols. When
-the linker plugin is not available, @option{-fwhole-program} should be
-used to allow the compiler to make these assumptions, which leads
-to more aggressive optimization decisions.
-
-When a file is compiled with @option{-flto} without
-@option{-fuse-linker-plugin}, the generated object file is larger than
-a regular object file because it contains GIMPLE bytecodes and the usual
-final code (see @option{-ffat-lto-objects}). This means that
-object files with LTO information can be linked as normal object
-files; if @option{-fno-lto} is passed to the linker, no
-interprocedural optimizations are applied. Note that when
-@option{-fno-fat-lto-objects} is enabled the compile stage is faster
-but you cannot perform a regular, non-LTO link on them.
-
-When producing the final binary, GCC only
-applies link-time optimizations to those files that contain bytecode.
-Therefore, you can mix and match object files and libraries with
-GIMPLE bytecodes and final object code. GCC automatically selects
-which files to optimize in LTO mode and which files to link without
-further processing.
-
-Generally, options specified at link time override those
-specified at compile time, although in some cases GCC attempts to infer
-link-time options from the settings used to compile the input files.
-
-If you do not specify an optimization level option @option{-O} at
-link time, then GCC uses the highest optimization level
-used when compiling the object files. Note that it is generally
-ineffective to specify an optimization level option only at link time and
-not at compile time, for two reasons. First, compiling without
-optimization suppresses compiler passes that gather information
-needed for effective optimization at link time. Second, some early
-optimization passes can be performed only at compile time and
-not at link time.
-
-There are some code generation flags preserved by GCC when
-generating bytecodes, as they need to be used during the final link.
-Currently, the following options and their settings are taken from
-the first object file that explicitly specifies them:
-@option{-fcommon}, @option{-fexceptions}, @option{-fnon-call-exceptions},
-@option{-fgnu-tm} and all the @option{-m} target flags.
-
-The following options @option{-fPIC}, @option{-fpic}, @option{-fpie} and
-@option{-fPIE} are combined based on the following scheme:
-
-@smallexample
-@option{-fPIC} + @option{-fpic} = @option{-fpic}
-@option{-fPIC} + @option{-fno-pic} = @option{-fno-pic}
-@option{-fpic/-fPIC} + (no option) = (no option)
-@option{-fPIC} + @option{-fPIE} = @option{-fPIE}
-@option{-fpic} + @option{-fPIE} = @option{-fpie}
-@option{-fPIC/-fpic} + @option{-fpie} = @option{-fpie}
-@end smallexample
-
-Certain ABI-changing flags are required to match in all compilation units,
-and trying to override this at link time with a conflicting value
-is ignored. This includes options such as @option{-freg-struct-return}
-and @option{-fpcc-struct-return}.
-
-Other options such as @option{-ffp-contract}, @option{-fno-strict-overflow},
-@option{-fwrapv}, @option{-fno-trapv} or @option{-fno-strict-aliasing}
-are passed through to the link stage and merged conservatively for
-conflicting translation units. Specifically
-@option{-fno-strict-overflow}, @option{-fwrapv} and @option{-fno-trapv} take
-precedence; and for example @option{-ffp-contract=off} takes precedence
-over @option{-ffp-contract=fast}. You can override them at link time.
-
-Diagnostic options such as @option{-Wstringop-overflow} are passed
-through to the link stage and their setting matches that of the
-compile-step at function granularity. Note that this matters only
-for diagnostics emitted during optimization. Note that code
-transforms such as inlining can lead to warnings being enabled
-or disabled for regions if code not consistent with the setting
-at compile time.
-
-When you need to pass options to the assembler via @option{-Wa} or
-@option{-Xassembler} make sure to either compile such translation
-units with @option{-fno-lto} or consistently use the same assembler
-options on all translation units. You can alternatively also
-specify assembler options at LTO link time.
-
-To enable debug info generation you need to supply @option{-g} at
-compile time. If any of the input files at link time were built
-with debug info generation enabled the link will enable debug info
-generation as well. Any elaborate debug info settings
-like the dwarf level @option{-gdwarf-5} need to be explicitly repeated
-at the linker command line and mixing different settings in different
-translation units is discouraged.
-
-If LTO encounters objects with C linkage declared with incompatible
-types in separate translation units to be linked together (undefined
-behavior according to ISO C99 6.2.7), a non-fatal diagnostic may be
-issued. The behavior is still undefined at run time. Similar
-diagnostics may be raised for other languages.
-
-Another feature of LTO is that it is possible to apply interprocedural
-optimizations on files written in different languages:
-
-@smallexample
-gcc -c -flto foo.c
-g++ -c -flto bar.cc
-gfortran -c -flto baz.f90
-g++ -o myprog -flto -O3 foo.o bar.o baz.o -lgfortran
-@end smallexample
-
-Notice that the final link is done with @command{g++} to get the C++
-runtime libraries and @option{-lgfortran} is added to get the Fortran
-runtime libraries. In general, when mixing languages in LTO mode, you
-should use the same link command options as when mixing languages in a
-regular (non-LTO) compilation.
-
-If object files containing GIMPLE bytecode are stored in a library archive, say
-@file{libfoo.a}, it is possible to extract and use them in an LTO link if you
-are using a linker with plugin support. To create static libraries suitable
-for LTO, use @command{gcc-ar} and @command{gcc-ranlib} instead of @command{ar}
-and @command{ranlib};
-to show the symbols of object files with GIMPLE bytecode, use
-@command{gcc-nm}. Those commands require that @command{ar}, @command{ranlib}
-and @command{nm} have been compiled with plugin support. At link time, use the
-flag @option{-fuse-linker-plugin} to ensure that the library participates in
-the LTO optimization process:
-
-@smallexample
-gcc -o myprog -O2 -flto -fuse-linker-plugin a.o b.o -lfoo
-@end smallexample
-
-With the linker plugin enabled, the linker extracts the needed
-GIMPLE files from @file{libfoo.a} and passes them on to the running GCC
-to make them part of the aggregated GIMPLE image to be optimized.
-
-If you are not using a linker with plugin support and/or do not
-enable the linker plugin, then the objects inside @file{libfoo.a}
-are extracted and linked as usual, but they do not participate
-in the LTO optimization process. In order to make a static library suitable
-for both LTO optimization and usual linkage, compile its object files with
-@option{-flto} @option{-ffat-lto-objects}.
-
-Link-time optimizations do not require the presence of the whole program to
-operate. If the program does not require any symbols to be exported, it is
-possible to combine @option{-flto} and @option{-fwhole-program} to allow
-the interprocedural optimizers to use more aggressive assumptions which may
-lead to improved optimization opportunities.
-Use of @option{-fwhole-program} is not needed when linker plugin is
-active (see @option{-fuse-linker-plugin}).
-
-The current implementation of LTO makes no
-attempt to generate bytecode that is portable between different
-types of hosts. The bytecode files are versioned and there is a
-strict version check, so bytecode files generated in one version of
-GCC do not work with an older or newer version of GCC.
-
-Link-time optimization does not work well with generation of debugging
-information on systems other than those using a combination of ELF and
-DWARF.
-
-If you specify the optional @var{n}, the optimization and code
-generation done at link time is executed in parallel using @var{n}
-parallel jobs by utilizing an installed @command{make} program. The
-environment variable @env{MAKE} may be used to override the program
-used.
-
-You can also specify @option{-flto=jobserver} to use GNU make's
-job server mode to determine the number of parallel jobs. This
-is useful when the Makefile calling GCC is already executing in parallel.
-You must prepend a @samp{+} to the command recipe in the parent Makefile
-for this to work. This option likely only works if @env{MAKE} is
-GNU make. Even without the option value, GCC tries to automatically
-detect a running GNU make's job server.
-
-Use @option{-flto=auto} to use GNU make's job server, if available,
-or otherwise fall back to autodetection of the number of CPU threads
-present in your system.
-
-@item -flto-partition=@var{alg}
-@opindex flto-partition
-Specify the partitioning algorithm used by the link-time optimizer.
-The value is either @samp{1to1} to specify a partitioning mirroring
-the original source files or @samp{balanced} to specify partitioning
-into equally sized chunks (whenever possible) or @samp{max} to create
-new partition for every symbol where possible. Specifying @samp{none}
-as an algorithm disables partitioning and streaming completely.
-The default value is @samp{balanced}. While @samp{1to1} can be used
-as an workaround for various code ordering issues, the @samp{max}
-partitioning is intended for internal testing only.
-The value @samp{one} specifies that exactly one partition should be
-used while the value @samp{none} bypasses partitioning and executes
-the link-time optimization step directly from the WPA phase.
-
-@item -flto-compression-level=@var{n}
-@opindex flto-compression-level
-This option specifies the level of compression used for intermediate
-language written to LTO object files, and is only meaningful in
-conjunction with LTO mode (@option{-flto}). GCC currently supports two
-LTO compression algorithms. For zstd, valid values are 0 (no compression)
-to 19 (maximum compression), while zlib supports values from 0 to 9.
-Values outside this range are clamped to either minimum or maximum
-of the supported values. If the option is not given,
-a default balanced compression setting is used.
-
-@item -fuse-linker-plugin
-@opindex fuse-linker-plugin
-Enables the use of a linker plugin during link-time optimization. This
-option relies on plugin support in the linker, which is available in gold
-or in GNU ld 2.21 or newer.
-
-This option enables the extraction of object files with GIMPLE bytecode out
-of library archives. This improves the quality of optimization by exposing
-more code to the link-time optimizer. This information specifies what
-symbols can be accessed externally (by non-LTO object or during dynamic
-linking). Resulting code quality improvements on binaries (and shared
-libraries that use hidden visibility) are similar to @option{-fwhole-program}.
-See @option{-flto} for a description of the effect of this flag and how to
-use it.
-
-This option is enabled by default when LTO support in GCC is enabled
-and GCC was configured for use with
-a linker supporting plugins (GNU ld 2.21 or newer or gold).
-
-@item -ffat-lto-objects
-@opindex ffat-lto-objects
-Fat LTO objects are object files that contain both the intermediate language
-and the object code. This makes them usable for both LTO linking and normal
-linking. This option is effective only when compiling with @option{-flto}
-and is ignored at link time.
-
-@option{-fno-fat-lto-objects} improves compilation time over plain LTO, but
-requires the complete toolchain to be aware of LTO. It requires a linker with
-linker plugin support for basic functionality. Additionally,
-@command{nm}, @command{ar} and @command{ranlib}
-need to support linker plugins to allow a full-featured build environment
-(capable of building static libraries etc). GCC provides the @command{gcc-ar},
-@command{gcc-nm}, @command{gcc-ranlib} wrappers to pass the right options
-to these tools. With non fat LTO makefiles need to be modified to use them.
-
-Note that modern binutils provide plugin auto-load mechanism.
-Installing the linker plugin into @file{$libdir/bfd-plugins} has the same
-effect as usage of the command wrappers (@command{gcc-ar}, @command{gcc-nm} and
-@command{gcc-ranlib}).
-
-The default is @option{-fno-fat-lto-objects} on targets with linker plugin
-support.
-
-@item -fcompare-elim
-@opindex fcompare-elim
-After register allocation and post-register allocation instruction splitting,
-identify arithmetic instructions that compute processor flags similar to a
-comparison operation based on that arithmetic. If possible, eliminate the
-explicit comparison operation.
-
-This pass only applies to certain targets that cannot explicitly represent
-the comparison operation before register allocation is complete.
-
-Enabled at levels @option{-O1}, @option{-O2}, @option{-O3}, @option{-Os}.
-
-@item -fcprop-registers
-@opindex fcprop-registers
-After register allocation and post-register allocation instruction splitting,
-perform a copy-propagation pass to try to reduce scheduling dependencies
-and occasionally eliminate the copy.
-
-Enabled at levels @option{-O1}, @option{-O2}, @option{-O3}, @option{-Os}.
-
-@item -fprofile-correction
-@opindex fprofile-correction
-Profiles collected using an instrumented binary for multi-threaded programs may
-be inconsistent due to missed counter updates. When this option is specified,
-GCC uses heuristics to correct or smooth out such inconsistencies. By
-default, GCC emits an error message when an inconsistent profile is detected.
-
-This option is enabled by @option{-fauto-profile}.
-
-@item -fprofile-partial-training
-@opindex fprofile-partial-training
-With @code{-fprofile-use} all portions of programs not executed during train
-run are optimized agressively for size rather than speed. In some cases it is
-not practical to train all possible hot paths in the program. (For
-example, program may contain functions specific for a given hardware and
-trianing may not cover all hardware configurations program is run on.) With
-@code{-fprofile-partial-training} profile feedback will be ignored for all
-functions not executed during the train run leading them to be optimized as if
-they were compiled without profile feedback. This leads to better performance
-when train run is not representative but also leads to significantly bigger
-code.
-
-@item -fprofile-use
-@itemx -fprofile-use=@var{path}
-@opindex fprofile-use
-Enable profile feedback-directed optimizations,
-and the following optimizations, many of which
-are generally profitable only with profile feedback available:
-
-@gccoptlist{-fbranch-probabilities -fprofile-values @gol
--funroll-loops -fpeel-loops -ftracer -fvpt @gol
--finline-functions -fipa-cp -fipa-cp-clone -fipa-bit-cp @gol
--fpredictive-commoning -fsplit-loops -funswitch-loops @gol
--fgcse-after-reload -ftree-loop-vectorize -ftree-slp-vectorize @gol
--fvect-cost-model=dynamic -ftree-loop-distribute-patterns @gol
--fprofile-reorder-functions}
-
-Before you can use this option, you must first generate profiling information.
-@xref{Instrumentation Options}, for information about the
-@option{-fprofile-generate} option.
-
-By default, GCC emits an error message if the feedback profiles do not
-match the source code. This error can be turned into a warning by using
-@option{-Wno-error=coverage-mismatch}. Note this may result in poorly
-optimized code. Additionally, by default, GCC also emits a warning message if
-the feedback profiles do not exist (see @option{-Wmissing-profile}).
-
-If @var{path} is specified, GCC looks at the @var{path} to find
-the profile feedback data files. See @option{-fprofile-dir}.
-
-@item -fauto-profile
-@itemx -fauto-profile=@var{path}
-@opindex fauto-profile
-Enable sampling-based feedback-directed optimizations,
-and the following optimizations,
-many of which are generally profitable only with profile feedback available:
-
-@gccoptlist{-fbranch-probabilities -fprofile-values @gol
--funroll-loops -fpeel-loops -ftracer -fvpt @gol
--finline-functions -fipa-cp -fipa-cp-clone -fipa-bit-cp @gol
--fpredictive-commoning -fsplit-loops -funswitch-loops @gol
--fgcse-after-reload -ftree-loop-vectorize -ftree-slp-vectorize @gol
--fvect-cost-model=dynamic -ftree-loop-distribute-patterns @gol
--fprofile-correction}
-
-@var{path} is the name of a file containing AutoFDO profile information.
-If omitted, it defaults to @file{fbdata.afdo} in the current directory.
-
-Producing an AutoFDO profile data file requires running your program
-with the @command{perf} utility on a supported GNU/Linux target system.
-For more information, see @uref{https://perf.wiki.kernel.org/}.
-
-E.g.
-@smallexample
-perf record -e br_inst_retired:near_taken -b -o perf.data \
- -- your_program
-@end smallexample
-
-Then use the @command{create_gcov} tool to convert the raw profile data
-to a format that can be used by GCC.@ You must also supply the
-unstripped binary for your program to this tool.
-See @uref{https://github.com/google/autofdo}.
-
-E.g.
-@smallexample
-create_gcov --binary=your_program.unstripped --profile=perf.data \
- --gcov=profile.afdo
-@end smallexample
-@end table
-
-The following options control compiler behavior regarding floating-point
-arithmetic. These options trade off between speed and
-correctness. All must be specifically enabled.
-
-@table @gcctabopt
-@item -ffloat-store
-@opindex ffloat-store
-Do not store floating-point variables in registers, and inhibit other
-options that might change whether a floating-point value is taken from a
-register or memory.
-
-@cindex floating-point precision
-This option prevents undesirable excess precision on machines such as
-the 68000 where the floating registers (of the 68881) keep more
-precision than a @code{double} is supposed to have. Similarly for the
-x86 architecture. For most programs, the excess precision does only
-good, but a few programs rely on the precise definition of IEEE floating
-point. Use @option{-ffloat-store} for such programs, after modifying
-them to store all pertinent intermediate computations into variables.
-
-@item -fexcess-precision=@var{style}
-@opindex fexcess-precision
-This option allows further control over excess precision on machines
-where floating-point operations occur in a format with more precision or
-range than the IEEE standard and interchange floating-point types. By
-default, @option{-fexcess-precision=fast} is in effect; this means that
-operations may be carried out in a wider precision than the types specified
-in the source if that would result in faster code, and it is unpredictable
-when rounding to the types specified in the source code takes place.
-When compiling C or C++, if @option{-fexcess-precision=standard} is specified
-then excess precision follows the rules specified in ISO C99 or C++; in particular,
-both casts and assignments cause values to be rounded to their
-semantic types (whereas @option{-ffloat-store} only affects
-assignments). This option is enabled by default for C or C++ if a strict
-conformance option such as @option{-std=c99} or @option{-std=c++17} is used.
-@option{-ffast-math} enables @option{-fexcess-precision=fast} by default
-regardless of whether a strict conformance option is used.
-
-@opindex mfpmath
-@option{-fexcess-precision=standard} is not implemented for languages
-other than C or C++. On the x86, it has no effect if @option{-mfpmath=sse}
-or @option{-mfpmath=sse+387} is specified; in the former case, IEEE
-semantics apply without excess precision, and in the latter, rounding
-is unpredictable.
-
-@item -ffast-math
-@opindex ffast-math
-Sets the options @option{-fno-math-errno}, @option{-funsafe-math-optimizations},
-@option{-ffinite-math-only}, @option{-fno-rounding-math},
-@option{-fno-signaling-nans}, @option{-fcx-limited-range} and
-@option{-fexcess-precision=fast}.
-
-This option causes the preprocessor macro @code{__FAST_MATH__} to be defined.
-
-This option is not turned on by any @option{-O} option besides
-@option{-Ofast} since it can result in incorrect output for programs
-that depend on an exact implementation of IEEE or ISO rules/specifications
-for math functions. It may, however, yield faster code for programs
-that do not require the guarantees of these specifications.
-
-@item -fno-math-errno
-@opindex fno-math-errno
-@opindex fmath-errno
-Do not set @code{errno} after calling math functions that are executed
-with a single instruction, e.g., @code{sqrt}. A program that relies on
-IEEE exceptions for math error handling may want to use this flag
-for speed while maintaining IEEE arithmetic compatibility.
-
-This option is not turned on by any @option{-O} option since
-it can result in incorrect output for programs that depend on
-an exact implementation of IEEE or ISO rules/specifications for
-math functions. It may, however, yield faster code for programs
-that do not require the guarantees of these specifications.
-
-The default is @option{-fmath-errno}.
-
-On Darwin systems, the math library never sets @code{errno}. There is
-therefore no reason for the compiler to consider the possibility that
-it might, and @option{-fno-math-errno} is the default.
-
-@item -funsafe-math-optimizations
-@opindex funsafe-math-optimizations
-
-Allow optimizations for floating-point arithmetic that (a) assume
-that arguments and results are valid and (b) may violate IEEE or
-ANSI standards. When used at link time, it may include libraries
-or startup files that change the default FPU control word or other
-similar optimizations.
-
-This option is not turned on by any @option{-O} option since
-it can result in incorrect output for programs that depend on
-an exact implementation of IEEE or ISO rules/specifications for
-math functions. It may, however, yield faster code for programs
-that do not require the guarantees of these specifications.
-Enables @option{-fno-signed-zeros}, @option{-fno-trapping-math},
-@option{-fassociative-math} and @option{-freciprocal-math}.
-
-The default is @option{-fno-unsafe-math-optimizations}.
-
-@item -fassociative-math
-@opindex fassociative-math
-
-Allow re-association of operands in series of floating-point operations.
-This violates the ISO C and C++ language standard by possibly changing
-computation result. NOTE: re-ordering may change the sign of zero as
-well as ignore NaNs and inhibit or create underflow or overflow (and
-thus cannot be used on code that relies on rounding behavior like
-@code{(x + 2**52) - 2**52}. May also reorder floating-point comparisons
-and thus may not be used when ordered comparisons are required.
-This option requires that both @option{-fno-signed-zeros} and
-@option{-fno-trapping-math} be in effect. Moreover, it doesn't make
-much sense with @option{-frounding-math}. For Fortran the option
-is automatically enabled when both @option{-fno-signed-zeros} and
-@option{-fno-trapping-math} are in effect.
-
-The default is @option{-fno-associative-math}.
-
-@item -freciprocal-math
-@opindex freciprocal-math
-
-Allow the reciprocal of a value to be used instead of dividing by
-the value if this enables optimizations. For example @code{x / y}
-can be replaced with @code{x * (1/y)}, which is useful if @code{(1/y)}
-is subject to common subexpression elimination. Note that this loses
-precision and increases the number of flops operating on the value.
-
-The default is @option{-fno-reciprocal-math}.
-
-@item -ffinite-math-only
-@opindex ffinite-math-only
-Allow optimizations for floating-point arithmetic that assume
-that arguments and results are not NaNs or +-Infs.
-
-This option is not turned on by any @option{-O} option since
-it can result in incorrect output for programs that depend on
-an exact implementation of IEEE or ISO rules/specifications for
-math functions. It may, however, yield faster code for programs
-that do not require the guarantees of these specifications.
-
-The default is @option{-fno-finite-math-only}.
-
-@item -fno-signed-zeros
-@opindex fno-signed-zeros
-@opindex fsigned-zeros
-Allow optimizations for floating-point arithmetic that ignore the
-signedness of zero. IEEE arithmetic specifies the behavior of
-distinct +0.0 and @minus{}0.0 values, which then prohibits simplification
-of expressions such as x+0.0 or 0.0*x (even with @option{-ffinite-math-only}).
-This option implies that the sign of a zero result isn't significant.
-
-The default is @option{-fsigned-zeros}.
-
-@item -fno-trapping-math
-@opindex fno-trapping-math
-@opindex ftrapping-math
-Compile code assuming that floating-point operations cannot generate
-user-visible traps. These traps include division by zero, overflow,
-underflow, inexact result and invalid operation. This option requires
-that @option{-fno-signaling-nans} be in effect. Setting this option may
-allow faster code if one relies on ``non-stop'' IEEE arithmetic, for example.
-
-This option should never be turned on by any @option{-O} option since
-it can result in incorrect output for programs that depend on
-an exact implementation of IEEE or ISO rules/specifications for
-math functions.
-
-The default is @option{-ftrapping-math}.
-
-Future versions of GCC may provide finer control of this setting
-using C99's @code{FENV_ACCESS} pragma. This command-line option
-will be used along with @option{-frounding-math} to specify the
-default state for @code{FENV_ACCESS}.
-
-@item -frounding-math
-@opindex frounding-math
-Disable transformations and optimizations that assume default floating-point
-rounding behavior. This is round-to-zero for all floating point
-to integer conversions, and round-to-nearest for all other arithmetic
-truncations. This option should be specified for programs that change
-the FP rounding mode dynamically, or that may be executed with a
-non-default rounding mode. This option disables constant folding of
-floating-point expressions at compile time (which may be affected by
-rounding mode) and arithmetic transformations that are unsafe in the
-presence of sign-dependent rounding modes.
-
-The default is @option{-fno-rounding-math}.
-
-This option is experimental and does not currently guarantee to
-disable all GCC optimizations that are affected by rounding mode.
-Future versions of GCC may provide finer control of this setting
-using C99's @code{FENV_ACCESS} pragma. This command-line option
-will be used along with @option{-ftrapping-math} to specify the
-default state for @code{FENV_ACCESS}.
-
-@item -fsignaling-nans
-@opindex fsignaling-nans
-Compile code assuming that IEEE signaling NaNs may generate user-visible
-traps during floating-point operations. Setting this option disables
-optimizations that may change the number of exceptions visible with
-signaling NaNs. This option implies @option{-ftrapping-math}.
-
-This option causes the preprocessor macro @code{__SUPPORT_SNAN__} to
-be defined.
-
-The default is @option{-fno-signaling-nans}.
-
-This option is experimental and does not currently guarantee to
-disable all GCC optimizations that affect signaling NaN behavior.
-
-@item -fno-fp-int-builtin-inexact
-@opindex fno-fp-int-builtin-inexact
-@opindex ffp-int-builtin-inexact
-Do not allow the built-in functions @code{ceil}, @code{floor},
-@code{round} and @code{trunc}, and their @code{float} and @code{long
-double} variants, to generate code that raises the ``inexact''
-floating-point exception for noninteger arguments. ISO C99 and C11
-allow these functions to raise the ``inexact'' exception, but ISO/IEC
-TS 18661-1:2014, the C bindings to IEEE 754-2008, as integrated into
-ISO C2X, does not allow these functions to do so.
-
-The default is @option{-ffp-int-builtin-inexact}, allowing the
-exception to be raised, unless C2X or a later C standard is selected.
-This option does nothing unless @option{-ftrapping-math} is in effect.
-
-Even if @option{-fno-fp-int-builtin-inexact} is used, if the functions
-generate a call to a library function then the ``inexact'' exception
-may be raised if the library implementation does not follow TS 18661.
-
-@item -fsingle-precision-constant
-@opindex fsingle-precision-constant
-Treat floating-point constants as single precision instead of
-implicitly converting them to double-precision constants.
-
-@item -fcx-limited-range
-@opindex fcx-limited-range
-When enabled, this option states that a range reduction step is not
-needed when performing complex division. Also, there is no checking
-whether the result of a complex multiplication or division is @code{NaN
-+ I*NaN}, with an attempt to rescue the situation in that case. The
-default is @option{-fno-cx-limited-range}, but is enabled by
-@option{-ffast-math}.
-
-This option controls the default setting of the ISO C99
-@code{CX_LIMITED_RANGE} pragma. Nevertheless, the option applies to
-all languages.
-
-@item -fcx-fortran-rules
-@opindex fcx-fortran-rules
-Complex multiplication and division follow Fortran rules. Range
-reduction is done as part of complex division, but there is no checking
-whether the result of a complex multiplication or division is @code{NaN
-+ I*NaN}, with an attempt to rescue the situation in that case.
-
-The default is @option{-fno-cx-fortran-rules}.
-
-@end table
-
-The following options control optimizations that may improve
-performance, but are not enabled by any @option{-O} options. This
-section includes experimental options that may produce broken code.
-
-@table @gcctabopt
-@item -fbranch-probabilities
-@opindex fbranch-probabilities
-After running a program compiled with @option{-fprofile-arcs}
-(@pxref{Instrumentation Options}),
-you can compile it a second time using
-@option{-fbranch-probabilities}, to improve optimizations based on
-the number of times each branch was taken. When a program
-compiled with @option{-fprofile-arcs} exits, it saves arc execution
-counts to a file called @file{@var{sourcename}.gcda} for each source
-file. The information in this data file is very dependent on the
-structure of the generated code, so you must use the same source code
-and the same optimization options for both compilations.
-See details about the file naming in @option{-fprofile-arcs}.
-
-With @option{-fbranch-probabilities}, GCC puts a
-@samp{REG_BR_PROB} note on each @samp{JUMP_INSN} and @samp{CALL_INSN}.
-These can be used to improve optimization. Currently, they are only
-used in one place: in @file{reorg.cc}, instead of guessing which path a
-branch is most likely to take, the @samp{REG_BR_PROB} values are used to
-exactly determine which path is taken more often.
-
-Enabled by @option{-fprofile-use} and @option{-fauto-profile}.
-
-@item -fprofile-values
-@opindex fprofile-values
-If combined with @option{-fprofile-arcs}, it adds code so that some
-data about values of expressions in the program is gathered.
-
-With @option{-fbranch-probabilities}, it reads back the data gathered
-from profiling values of expressions for usage in optimizations.
-
-Enabled by @option{-fprofile-generate}, @option{-fprofile-use}, and
-@option{-fauto-profile}.
-
-@item -fprofile-reorder-functions
-@opindex fprofile-reorder-functions
-Function reordering based on profile instrumentation collects
-first time of execution of a function and orders these functions
-in ascending order.
-
-Enabled with @option{-fprofile-use}.
-
-@item -fvpt
-@opindex fvpt
-If combined with @option{-fprofile-arcs}, this option instructs the compiler
-to add code to gather information about values of expressions.
-
-With @option{-fbranch-probabilities}, it reads back the data gathered
-and actually performs the optimizations based on them.
-Currently the optimizations include specialization of division operations
-using the knowledge about the value of the denominator.
-
-Enabled with @option{-fprofile-use} and @option{-fauto-profile}.
-
-@item -frename-registers
-@opindex frename-registers
-Attempt to avoid false dependencies in scheduled code by making use
-of registers left over after register allocation. This optimization
-most benefits processors with lots of registers. Depending on the
-debug information format adopted by the target, however, it can
-make debugging impossible, since variables no longer stay in
-a ``home register''.
-
-Enabled by default with @option{-funroll-loops}.
-
-@item -fschedule-fusion
-@opindex fschedule-fusion
-Performs a target dependent pass over the instruction stream to schedule
-instructions of same type together because target machine can execute them
-more efficiently if they are adjacent to each other in the instruction flow.
-
-Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
-
-@item -ftracer
-@opindex ftracer
-Perform tail duplication to enlarge superblock size. This transformation
-simplifies the control flow of the function allowing other optimizations to do
-a better job.
-
-Enabled by @option{-fprofile-use} and @option{-fauto-profile}.
-
-@item -funroll-loops
-@opindex funroll-loops
-Unroll loops whose number of iterations can be determined at compile time or
-upon entry to the loop. @option{-funroll-loops} implies
-@option{-frerun-cse-after-loop}, @option{-fweb} and @option{-frename-registers}.
-It also turns on complete loop peeling (i.e.@: complete removal of loops with
-a small constant number of iterations). This option makes code larger, and may
-or may not make it run faster.
-
-Enabled by @option{-fprofile-use} and @option{-fauto-profile}.
-
-@item -funroll-all-loops
-@opindex funroll-all-loops
-Unroll all loops, even if their number of iterations is uncertain when
-the loop is entered. This usually makes programs run more slowly.
-@option{-funroll-all-loops} implies the same options as
-@option{-funroll-loops}.
-
-@item -fpeel-loops
-@opindex fpeel-loops
-Peels loops for which there is enough information that they do not
-roll much (from profile feedback or static analysis). It also turns on
-complete loop peeling (i.e.@: complete removal of loops with small constant
-number of iterations).
-
-Enabled by @option{-O3}, @option{-fprofile-use}, and @option{-fauto-profile}.
-
-@item -fmove-loop-invariants
-@opindex fmove-loop-invariants
-Enables the loop invariant motion pass in the RTL loop optimizer. Enabled
-at level @option{-O1} and higher, except for @option{-Og}.
-
-@item -fmove-loop-stores
-@opindex fmove-loop-stores
-Enables the loop store motion pass in the GIMPLE loop optimizer. This
-moves invariant stores to after the end of the loop in exchange for
-carrying the stored value in a register across the iteration.
-Note for this option to have an effect @option{-ftree-loop-im} has to
-be enabled as well. Enabled at level @option{-O1} and higher, except
-for @option{-Og}.
-
-@item -fsplit-loops
-@opindex fsplit-loops
-Split a loop into two if it contains a condition that's always true
-for one side of the iteration space and false for the other.
-
-Enabled by @option{-fprofile-use} and @option{-fauto-profile}.
-
-@item -funswitch-loops
-@opindex funswitch-loops
-Move branches with loop invariant conditions out of the loop, with duplicates
-of the loop on both branches (modified according to result of the condition).
-
-Enabled by @option{-fprofile-use} and @option{-fauto-profile}.
-
-@item -fversion-loops-for-strides
-@opindex fversion-loops-for-strides
-If a loop iterates over an array with a variable stride, create another
-version of the loop that assumes the stride is always one. For example:
-
-@smallexample
-for (int i = 0; i < n; ++i)
- x[i * stride] = @dots{};
-@end smallexample
-
-becomes:
-
-@smallexample
-if (stride == 1)
- for (int i = 0; i < n; ++i)
- x[i] = @dots{};
-else
- for (int i = 0; i < n; ++i)
- x[i * stride] = @dots{};
-@end smallexample
-
-This is particularly useful for assumed-shape arrays in Fortran where
-(for example) it allows better vectorization assuming contiguous accesses.
-This flag is enabled by default at @option{-O3}.
-It is also enabled by @option{-fprofile-use} and @option{-fauto-profile}.
-
-@item -ffunction-sections
-@itemx -fdata-sections
-@opindex ffunction-sections
-@opindex fdata-sections
-Place each function or data item into its own section in the output
-file if the target supports arbitrary sections. The name of the
-function or the name of the data item determines the section's name
-in the output file.
-
-Use these options on systems where the linker can perform optimizations to
-improve locality of reference in the instruction space. Most systems using the
-ELF object format have linkers with such optimizations. On AIX, the linker
-rearranges sections (CSECTs) based on the call graph. The performance impact
-varies.
-
-Together with a linker garbage collection (linker @option{--gc-sections}
-option) these options may lead to smaller statically-linked executables (after
-stripping).
-
-On ELF/DWARF systems these options do not degenerate the quality of the debug
-information. There could be issues with other object files/debug info formats.
-
-Only use these options when there are significant benefits from doing so. When
-you specify these options, the assembler and linker create larger object and
-executable files and are also slower. These options affect code generation.
-They prevent optimizations by the compiler and assembler using relative
-locations inside a translation unit since the locations are unknown until
-link time. An example of such an optimization is relaxing calls to short call
-instructions.
-
-@item -fstdarg-opt
-@opindex fstdarg-opt
-Optimize the prologue of variadic argument functions with respect to usage of
-those arguments.
-
-@item -fsection-anchors
-@opindex fsection-anchors
-Try to reduce the number of symbolic address calculations by using
-shared ``anchor'' symbols to address nearby objects. This transformation
-can help to reduce the number of GOT entries and GOT accesses on some
-targets.
-
-For example, the implementation of the following function @code{foo}:
-
-@smallexample
-static int a, b, c;
-int foo (void) @{ return a + b + c; @}
-@end smallexample
-
-@noindent
-usually calculates the addresses of all three variables, but if you
-compile it with @option{-fsection-anchors}, it accesses the variables
-from a common anchor point instead. The effect is similar to the
-following pseudocode (which isn't valid C):
-
-@smallexample
-int foo (void)
-@{
- register int *xr = &x;
- return xr[&a - &x] + xr[&b - &x] + xr[&c - &x];
-@}
-@end smallexample
-
-Not all targets support this option.
-
-@item -fzero-call-used-regs=@var{choice}
-@opindex fzero-call-used-regs
-Zero call-used registers at function return to increase program
-security by either mitigating Return-Oriented Programming (ROP)
-attacks or preventing information leakage through registers.
-
-The possible values of @var{choice} are the same as for the
-@code{zero_call_used_regs} attribute (@pxref{Function Attributes}).
-The default is @samp{skip}.
-
-You can control this behavior for a specific function by using the function
-attribute @code{zero_call_used_regs} (@pxref{Function Attributes}).
-
-@item --param @var{name}=@var{value}
-@opindex param
-In some places, GCC uses various constants to control the amount of
-optimization that is done. For example, GCC does not inline functions
-that contain more than a certain number of instructions. You can
-control some of these constants on the command line using the
-@option{--param} option.
-
-The names of specific parameters, and the meaning of the values, are
-tied to the internals of the compiler, and are subject to change
-without notice in future releases.
-
-In order to get minimal, maximal and default value of a parameter,
-one can use @option{--help=param -Q} options.
-
-In each case, the @var{value} is an integer. The following choices
-of @var{name} are recognized for all targets:
-
-@table @gcctabopt
-@item predictable-branch-outcome
-When branch is predicted to be taken with probability lower than this threshold
-(in percent), then it is considered well predictable.
-
-@item max-rtl-if-conversion-insns
-RTL if-conversion tries to remove conditional branches around a block and
-replace them with conditionally executed instructions. This parameter
-gives the maximum number of instructions in a block which should be
-considered for if-conversion. The compiler will
-also use other heuristics to decide whether if-conversion is likely to be
-profitable.
-
-@item max-rtl-if-conversion-predictable-cost
-RTL if-conversion will try to remove conditional branches around a block
-and replace them with conditionally executed instructions. These parameters
-give the maximum permissible cost for the sequence that would be generated
-by if-conversion depending on whether the branch is statically determined
-to be predictable or not. The units for this parameter are the same as
-those for the GCC internal seq_cost metric. The compiler will try to
-provide a reasonable default for this parameter using the BRANCH_COST
-target macro.
-
-@item max-crossjump-edges
-The maximum number of incoming edges to consider for cross-jumping.
-The algorithm used by @option{-fcrossjumping} is @math{O(N^2)} in
-the number of edges incoming to each block. Increasing values mean
-more aggressive optimization, making the compilation time increase with
-probably small improvement in executable size.
-
-@item min-crossjump-insns
-The minimum number of instructions that must be matched at the end
-of two blocks before cross-jumping is performed on them. This
-value is ignored in the case where all instructions in the block being
-cross-jumped from are matched.
-
-@item max-grow-copy-bb-insns
-The maximum code size expansion factor when copying basic blocks
-instead of jumping. The expansion is relative to a jump instruction.
-
-@item max-goto-duplication-insns
-The maximum number of instructions to duplicate to a block that jumps
-to a computed goto. To avoid @math{O(N^2)} behavior in a number of
-passes, GCC factors computed gotos early in the compilation process,
-and unfactors them as late as possible. Only computed jumps at the
-end of a basic blocks with no more than max-goto-duplication-insns are
-unfactored.
-
-@item max-delay-slot-insn-search
-The maximum number of instructions to consider when looking for an
-instruction to fill a delay slot. If more than this arbitrary number of
-instructions are searched, the time savings from filling the delay slot
-are minimal, so stop searching. Increasing values mean more
-aggressive optimization, making the compilation time increase with probably
-small improvement in execution time.
-
-@item max-delay-slot-live-search
-When trying to fill delay slots, the maximum number of instructions to
-consider when searching for a block with valid live register
-information. Increasing this arbitrarily chosen value means more
-aggressive optimization, increasing the compilation time. This parameter
-should be removed when the delay slot code is rewritten to maintain the
-control-flow graph.
-
-@item max-gcse-memory
-The approximate maximum amount of memory in @code{kB} that can be allocated in
-order to perform the global common subexpression elimination
-optimization. If more memory than specified is required, the
-optimization is not done.
-
-@item max-gcse-insertion-ratio
-If the ratio of expression insertions to deletions is larger than this value
-for any expression, then RTL PRE inserts or removes the expression and thus
-leaves partially redundant computations in the instruction stream.
-
-@item max-pending-list-length
-The maximum number of pending dependencies scheduling allows
-before flushing the current state and starting over. Large functions
-with few branches or calls can create excessively large lists which
-needlessly consume memory and resources.
-
-@item max-modulo-backtrack-attempts
-The maximum number of backtrack attempts the scheduler should make
-when modulo scheduling a loop. Larger values can exponentially increase
-compilation time.
-
-@item max-inline-functions-called-once-loop-depth
-Maximal loop depth of a call considered by inline heuristics that tries to
-inline all functions called once.
-
-@item max-inline-functions-called-once-insns
-Maximal estimated size of functions produced while inlining functions called
-once.
-
-@item max-inline-insns-single
-Several parameters control the tree inliner used in GCC@. This number sets the
-maximum number of instructions (counted in GCC's internal representation) in a
-single function that the tree inliner considers for inlining. This only
-affects functions declared inline and methods implemented in a class
-declaration (C++).
-
-
-@item max-inline-insns-auto
-When you use @option{-finline-functions} (included in @option{-O3}),
-a lot of functions that would otherwise not be considered for inlining
-by the compiler are investigated. To those functions, a different
-(more restrictive) limit compared to functions declared inline can
-be applied (@option{--param max-inline-insns-auto}).
-
-@item max-inline-insns-small
-This is bound applied to calls which are considered relevant with
-@option{-finline-small-functions}.
-
-@item max-inline-insns-size
-This is bound applied to calls which are optimized for size. Small growth
-may be desirable to anticipate optimization oppurtunities exposed by inlining.
-
-@item uninlined-function-insns
-Number of instructions accounted by inliner for function overhead such as
-function prologue and epilogue.
-
-@item uninlined-function-time
-Extra time accounted by inliner for function overhead such as time needed to
-execute function prologue and epilogue.
-
-@item inline-heuristics-hint-percent
-The scale (in percents) applied to @option{inline-insns-single},
-@option{inline-insns-single-O2}, @option{inline-insns-auto}
-when inline heuristics hints that inlining is
-very profitable (will enable later optimizations).
-
-@item uninlined-thunk-insns
-@item uninlined-thunk-time
-Same as @option{--param uninlined-function-insns} and
-@option{--param uninlined-function-time} but applied to function thunks.
-
-@item inline-min-speedup
-When estimated performance improvement of caller + callee runtime exceeds this
-threshold (in percent), the function can be inlined regardless of the limit on
-@option{--param max-inline-insns-single} and @option{--param
-max-inline-insns-auto}.
-
-@item large-function-insns
-The limit specifying really large functions. For functions larger than this
-limit after inlining, inlining is constrained by
-@option{--param large-function-growth}. This parameter is useful primarily
-to avoid extreme compilation time caused by non-linear algorithms used by the
-back end.
-
-@item large-function-growth
-Specifies maximal growth of large function caused by inlining in percents.
-For example, parameter value 100 limits large function growth to 2.0 times
-the original size.
-
-@item large-unit-insns
-The limit specifying large translation unit. Growth caused by inlining of
-units larger than this limit is limited by @option{--param inline-unit-growth}.
-For small units this might be too tight.
-For example, consider a unit consisting of function A
-that is inline and B that just calls A three times. If B is small relative to
-A, the growth of unit is 300\% and yet such inlining is very sane. For very
-large units consisting of small inlineable functions, however, the overall unit
-growth limit is needed to avoid exponential explosion of code size. Thus for
-smaller units, the size is increased to @option{--param large-unit-insns}
-before applying @option{--param inline-unit-growth}.
-
-@item lazy-modules
-Maximum number of concurrently open C++ module files when lazy loading.
-
-@item inline-unit-growth
-Specifies maximal overall growth of the compilation unit caused by inlining.
-For example, parameter value 20 limits unit growth to 1.2 times the original
-size. Cold functions (either marked cold via an attribute or by profile
-feedback) are not accounted into the unit size.
-
-@item ipa-cp-unit-growth
-Specifies maximal overall growth of the compilation unit caused by
-interprocedural constant propagation. For example, parameter value 10 limits
-unit growth to 1.1 times the original size.
-
-@item ipa-cp-large-unit-insns
-The size of translation unit that IPA-CP pass considers large.
-
-@item large-stack-frame
-The limit specifying large stack frames. While inlining the algorithm is trying
-to not grow past this limit too much.
-
-@item large-stack-frame-growth
-Specifies maximal growth of large stack frames caused by inlining in percents.
-For example, parameter value 1000 limits large stack frame growth to 11 times
-the original size.
-
-@item max-inline-insns-recursive
-@itemx max-inline-insns-recursive-auto
-Specifies the maximum number of instructions an out-of-line copy of a
-self-recursive inline
-function can grow into by performing recursive inlining.
-
-@option{--param max-inline-insns-recursive} applies to functions
-declared inline.
-For functions not declared inline, recursive inlining
-happens only when @option{-finline-functions} (included in @option{-O3}) is
-enabled; @option{--param max-inline-insns-recursive-auto} applies instead.
-
-@item max-inline-recursive-depth
-@itemx max-inline-recursive-depth-auto
-Specifies the maximum recursion depth used for recursive inlining.
-
-@option{--param max-inline-recursive-depth} applies to functions
-declared inline. For functions not declared inline, recursive inlining
-happens only when @option{-finline-functions} (included in @option{-O3}) is
-enabled; @option{--param max-inline-recursive-depth-auto} applies instead.
-
-@item min-inline-recursive-probability
-Recursive inlining is profitable only for function having deep recursion
-in average and can hurt for function having little recursion depth by
-increasing the prologue size or complexity of function body to other
-optimizers.
-
-When profile feedback is available (see @option{-fprofile-generate}) the actual
-recursion depth can be guessed from the probability that function recurses
-via a given call expression. This parameter limits inlining only to call
-expressions whose probability exceeds the given threshold (in percents).
-
-@item early-inlining-insns
-Specify growth that the early inliner can make. In effect it increases
-the amount of inlining for code having a large abstraction penalty.
-
-@item max-early-inliner-iterations
-Limit of iterations of the early inliner. This basically bounds
-the number of nested indirect calls the early inliner can resolve.
-Deeper chains are still handled by late inlining.
-
-@item comdat-sharing-probability
-Probability (in percent) that C++ inline function with comdat visibility
-are shared across multiple compilation units.
-
-@item modref-max-bases
-@item modref-max-refs
-@item modref-max-accesses
-Specifies the maximal number of base pointers, references and accesses stored
-for a single function by mod/ref analysis.
-
-@item modref-max-tests
-Specifies the maxmal number of tests alias oracle can perform to disambiguate
-memory locations using the mod/ref information. This parameter ought to be
-bigger than @option{--param modref-max-bases} and @option{--param
-modref-max-refs}.
-
-@item modref-max-depth
-Specifies the maximum depth of DFS walk used by modref escape analysis.
-Setting to 0 disables the analysis completely.
-
-@item modref-max-escape-points
-Specifies the maximum number of escape points tracked by modref per SSA-name.
-
-@item modref-max-adjustments
-Specifies the maximum number the access range is enlarged during modref dataflow
-analysis.
-
-@item profile-func-internal-id
-A parameter to control whether to use function internal id in profile
-database lookup. If the value is 0, the compiler uses an id that
-is based on function assembler name and filename, which makes old profile
-data more tolerant to source changes such as function reordering etc.
-
-@item min-vect-loop-bound
-The minimum number of iterations under which loops are not vectorized
-when @option{-ftree-vectorize} is used. The number of iterations after
-vectorization needs to be greater than the value specified by this option
-to allow vectorization.
-
-@item gcse-cost-distance-ratio
-Scaling factor in calculation of maximum distance an expression
-can be moved by GCSE optimizations. This is currently supported only in the
-code hoisting pass. The bigger the ratio, the more aggressive code hoisting
-is with simple expressions, i.e., the expressions that have cost
-less than @option{gcse-unrestricted-cost}. Specifying 0 disables
-hoisting of simple expressions.
-
-@item gcse-unrestricted-cost
-Cost, roughly measured as the cost of a single typical machine
-instruction, at which GCSE optimizations do not constrain
-the distance an expression can travel. This is currently
-supported only in the code hoisting pass. The lesser the cost,
-the more aggressive code hoisting is. Specifying 0
-allows all expressions to travel unrestricted distances.
-
-@item max-hoist-depth
-The depth of search in the dominator tree for expressions to hoist.
-This is used to avoid quadratic behavior in hoisting algorithm.
-The value of 0 does not limit on the search, but may slow down compilation
-of huge functions.
-
-@item max-tail-merge-comparisons
-The maximum amount of similar bbs to compare a bb with. This is used to
-avoid quadratic behavior in tree tail merging.
-
-@item max-tail-merge-iterations
-The maximum amount of iterations of the pass over the function. This is used to
-limit compilation time in tree tail merging.
-
-@item store-merging-allow-unaligned
-Allow the store merging pass to introduce unaligned stores if it is legal to
-do so.
-
-@item max-stores-to-merge
-The maximum number of stores to attempt to merge into wider stores in the store
-merging pass.
-
-@item max-store-chains-to-track
-The maximum number of store chains to track at the same time in the attempt
-to merge them into wider stores in the store merging pass.
-
-@item max-stores-to-track
-The maximum number of stores to track at the same time in the attemt to
-to merge them into wider stores in the store merging pass.
-
-@item max-unrolled-insns
-The maximum number of instructions that a loop may have to be unrolled.
-If a loop is unrolled, this parameter also determines how many times
-the loop code is unrolled.
-
-@item max-average-unrolled-insns
-The maximum number of instructions biased by probabilities of their execution
-that a loop may have to be unrolled. If a loop is unrolled,
-this parameter also determines how many times the loop code is unrolled.
-
-@item max-unroll-times
-The maximum number of unrollings of a single loop.
-
-@item max-peeled-insns
-The maximum number of instructions that a loop may have to be peeled.
-If a loop is peeled, this parameter also determines how many times
-the loop code is peeled.
-
-@item max-peel-times
-The maximum number of peelings of a single loop.
-
-@item max-peel-branches
-The maximum number of branches on the hot path through the peeled sequence.
-
-@item max-completely-peeled-insns
-The maximum number of insns of a completely peeled loop.
-
-@item max-completely-peel-times
-The maximum number of iterations of a loop to be suitable for complete peeling.
-
-@item max-completely-peel-loop-nest-depth
-The maximum depth of a loop nest suitable for complete peeling.
-
-@item max-unswitch-insns
-The maximum number of insns of an unswitched loop.
-
-@item lim-expensive
-The minimum cost of an expensive expression in the loop invariant motion.
-
-@item min-loop-cond-split-prob
-When FDO profile information is available, @option{min-loop-cond-split-prob}
-specifies minimum threshold for probability of semi-invariant condition
-statement to trigger loop split.
-
-@item iv-consider-all-candidates-bound
-Bound on number of candidates for induction variables, below which
-all candidates are considered for each use in induction variable
-optimizations. If there are more candidates than this,
-only the most relevant ones are considered to avoid quadratic time complexity.
-
-@item iv-max-considered-uses
-The induction variable optimizations give up on loops that contain more
-induction variable uses.
-
-@item iv-always-prune-cand-set-bound
-If the number of candidates in the set is smaller than this value,
-always try to remove unnecessary ivs from the set
-when adding a new one.
-
-@item avg-loop-niter
-Average number of iterations of a loop.
-
-@item dse-max-object-size
-Maximum size (in bytes) of objects tracked bytewise by dead store elimination.
-Larger values may result in larger compilation times.
-
-@item dse-max-alias-queries-per-store
-Maximum number of queries into the alias oracle per store.
-Larger values result in larger compilation times and may result in more
-removed dead stores.
-
-@item scev-max-expr-size
-Bound on size of expressions used in the scalar evolutions analyzer.
-Large expressions slow the analyzer.
-
-@item scev-max-expr-complexity
-Bound on the complexity of the expressions in the scalar evolutions analyzer.
-Complex expressions slow the analyzer.
-
-@item max-tree-if-conversion-phi-args
-Maximum number of arguments in a PHI supported by TREE if conversion
-unless the loop is marked with simd pragma.
-
-@item vect-max-layout-candidates
-The maximum number of possible vector layouts (such as permutations)
-to consider when optimizing to-be-vectorized code.
-
-@item vect-max-version-for-alignment-checks
-The maximum number of run-time checks that can be performed when
-doing loop versioning for alignment in the vectorizer.
-
-@item vect-max-version-for-alias-checks
-The maximum number of run-time checks that can be performed when
-doing loop versioning for alias in the vectorizer.
-
-@item vect-max-peeling-for-alignment
-The maximum number of loop peels to enhance access alignment
-for vectorizer. Value -1 means no limit.
-
-@item max-iterations-to-track
-The maximum number of iterations of a loop the brute-force algorithm
-for analysis of the number of iterations of the loop tries to evaluate.
-
-@item hot-bb-count-fraction
-The denominator n of fraction 1/n of the maximal execution count of a
-basic block in the entire program that a basic block needs to at least
-have in order to be considered hot. The default is 10000, which means
-that a basic block is considered hot if its execution count is greater
-than 1/10000 of the maximal execution count. 0 means that it is never
-considered hot. Used in non-LTO mode.
-
-@item hot-bb-count-ws-permille
-The number of most executed permilles, ranging from 0 to 1000, of the
-profiled execution of the entire program to which the execution count
-of a basic block must be part of in order to be considered hot. The
-default is 990, which means that a basic block is considered hot if
-its execution count contributes to the upper 990 permilles, or 99.0%,
-of the profiled execution of the entire program. 0 means that it is
-never considered hot. Used in LTO mode.
-
-@item hot-bb-frequency-fraction
-The denominator n of fraction 1/n of the execution frequency of the
-entry block of a function that a basic block of this function needs
-to at least have in order to be considered hot. The default is 1000,
-which means that a basic block is considered hot in a function if it
-is executed more frequently than 1/1000 of the frequency of the entry
-block of the function. 0 means that it is never considered hot.
-
-@item unlikely-bb-count-fraction
-The denominator n of fraction 1/n of the number of profiled runs of
-the entire program below which the execution count of a basic block
-must be in order for the basic block to be considered unlikely executed.
-The default is 20, which means that a basic block is considered unlikely
-executed if it is executed in fewer than 1/20, or 5%, of the runs of
-the program. 0 means that it is always considered unlikely executed.
-
-@item max-predicted-iterations
-The maximum number of loop iterations we predict statically. This is useful
-in cases where a function contains a single loop with known bound and
-another loop with unknown bound.
-The known number of iterations is predicted correctly, while
-the unknown number of iterations average to roughly 10. This means that the
-loop without bounds appears artificially cold relative to the other one.
-
-@item builtin-expect-probability
-Control the probability of the expression having the specified value. This
-parameter takes a percentage (i.e.@: 0 ... 100) as input.
-
-@item builtin-string-cmp-inline-length
-The maximum length of a constant string for a builtin string cmp call
-eligible for inlining.
-
-@item align-threshold
-
-Select fraction of the maximal frequency of executions of a basic block in
-a function to align the basic block.
-
-@item align-loop-iterations
-
-A loop expected to iterate at least the selected number of iterations is
-aligned.
-
-@item tracer-dynamic-coverage
-@itemx tracer-dynamic-coverage-feedback
-
-This value is used to limit superblock formation once the given percentage of
-executed instructions is covered. This limits unnecessary code size
-expansion.
-
-The @option{tracer-dynamic-coverage-feedback} parameter
-is used only when profile
-feedback is available. The real profiles (as opposed to statically estimated
-ones) are much less balanced allowing the threshold to be larger value.
-
-@item tracer-max-code-growth
-Stop tail duplication once code growth has reached given percentage. This is
-a rather artificial limit, as most of the duplicates are eliminated later in
-cross jumping, so it may be set to much higher values than is the desired code
-growth.
-
-@item tracer-min-branch-ratio
-
-Stop reverse growth when the reverse probability of best edge is less than this
-threshold (in percent).
-
-@item tracer-min-branch-probability
-@itemx tracer-min-branch-probability-feedback
-
-Stop forward growth if the best edge has probability lower than this
-threshold.
-
-Similarly to @option{tracer-dynamic-coverage} two parameters are
-provided. @option{tracer-min-branch-probability-feedback} is used for
-compilation with profile feedback and @option{tracer-min-branch-probability}
-compilation without. The value for compilation with profile feedback
-needs to be more conservative (higher) in order to make tracer
-effective.
-
-@item stack-clash-protection-guard-size
-Specify the size of the operating system provided stack guard as
-2 raised to @var{num} bytes. Higher values may reduce the
-number of explicit probes, but a value larger than the operating system
-provided guard will leave code vulnerable to stack clash style attacks.
-
-@item stack-clash-protection-probe-interval
-Stack clash protection involves probing stack space as it is allocated. This
-param controls the maximum distance between probes into the stack as 2 raised
-to @var{num} bytes. Higher values may reduce the number of explicit probes, but a value
-larger than the operating system provided guard will leave code vulnerable to
-stack clash style attacks.
-
-@item max-cse-path-length
-
-The maximum number of basic blocks on path that CSE considers.
-
-@item max-cse-insns
-The maximum number of instructions CSE processes before flushing.
-
-@item ggc-min-expand
-
-GCC uses a garbage collector to manage its own memory allocation. This
-parameter specifies the minimum percentage by which the garbage
-collector's heap should be allowed to expand between collections.
-Tuning this may improve compilation speed; it has no effect on code
-generation.
-
-The default is 30% + 70% * (RAM/1GB) with an upper bound of 100% when
-RAM >= 1GB@. If @code{getrlimit} is available, the notion of ``RAM'' is
-the smallest of actual RAM and @code{RLIMIT_DATA} or @code{RLIMIT_AS}. If
-GCC is not able to calculate RAM on a particular platform, the lower
-bound of 30% is used. Setting this parameter and
-@option{ggc-min-heapsize} to zero causes a full collection to occur at
-every opportunity. This is extremely slow, but can be useful for
-debugging.
-
-@item ggc-min-heapsize
-
-Minimum size of the garbage collector's heap before it begins bothering
-to collect garbage. The first collection occurs after the heap expands
-by @option{ggc-min-expand}% beyond @option{ggc-min-heapsize}. Again,
-tuning this may improve compilation speed, and has no effect on code
-generation.
-
-The default is the smaller of RAM/8, RLIMIT_RSS, or a limit that
-tries to ensure that RLIMIT_DATA or RLIMIT_AS are not exceeded, but
-with a lower bound of 4096 (four megabytes) and an upper bound of
-131072 (128 megabytes). If GCC is not able to calculate RAM on a
-particular platform, the lower bound is used. Setting this parameter
-very large effectively disables garbage collection. Setting this
-parameter and @option{ggc-min-expand} to zero causes a full collection
-to occur at every opportunity.
-
-@item max-reload-search-insns
-The maximum number of instruction reload should look backward for equivalent
-register. Increasing values mean more aggressive optimization, making the
-compilation time increase with probably slightly better performance.
-
-@item max-cselib-memory-locations
-The maximum number of memory locations cselib should take into account.
-Increasing values mean more aggressive optimization, making the compilation time
-increase with probably slightly better performance.
-
-@item max-sched-ready-insns
-The maximum number of instructions ready to be issued the scheduler should
-consider at any given time during the first scheduling pass. Increasing
-values mean more thorough searches, making the compilation time increase
-with probably little benefit.
-
-@item max-sched-region-blocks
-The maximum number of blocks in a region to be considered for
-interblock scheduling.
-
-@item max-pipeline-region-blocks
-The maximum number of blocks in a region to be considered for
-pipelining in the selective scheduler.
-
-@item max-sched-region-insns
-The maximum number of insns in a region to be considered for
-interblock scheduling.
-
-@item max-pipeline-region-insns
-The maximum number of insns in a region to be considered for
-pipelining in the selective scheduler.
-
-@item min-spec-prob
-The minimum probability (in percents) of reaching a source block
-for interblock speculative scheduling.
-
-@item max-sched-extend-regions-iters
-The maximum number of iterations through CFG to extend regions.
-A value of 0 disables region extensions.
-
-@item max-sched-insn-conflict-delay
-The maximum conflict delay for an insn to be considered for speculative motion.
-
-@item sched-spec-prob-cutoff
-The minimal probability of speculation success (in percents), so that
-speculative insns are scheduled.
-
-@item sched-state-edge-prob-cutoff
-The minimum probability an edge must have for the scheduler to save its
-state across it.
-
-@item sched-mem-true-dep-cost
-Minimal distance (in CPU cycles) between store and load targeting same
-memory locations.
-
-@item selsched-max-lookahead
-The maximum size of the lookahead window of selective scheduling. It is a
-depth of search for available instructions.
-
-@item selsched-max-sched-times
-The maximum number of times that an instruction is scheduled during
-selective scheduling. This is the limit on the number of iterations
-through which the instruction may be pipelined.
-
-@item selsched-insns-to-rename
-The maximum number of best instructions in the ready list that are considered
-for renaming in the selective scheduler.
-
-@item sms-min-sc
-The minimum value of stage count that swing modulo scheduler
-generates.
-
-@item max-last-value-rtl
-The maximum size measured as number of RTLs that can be recorded in an expression
-in combiner for a pseudo register as last known value of that register.
-
-@item max-combine-insns
-The maximum number of instructions the RTL combiner tries to combine.
-
-@item integer-share-limit
-Small integer constants can use a shared data structure, reducing the
-compiler's memory usage and increasing its speed. This sets the maximum
-value of a shared integer constant.
-
-@item ssp-buffer-size
-The minimum size of buffers (i.e.@: arrays) that receive stack smashing
-protection when @option{-fstack-protector} is used.
-
-@item min-size-for-stack-sharing
-The minimum size of variables taking part in stack slot sharing when not
-optimizing.
-
-@item max-jump-thread-duplication-stmts
-Maximum number of statements allowed in a block that needs to be
-duplicated when threading jumps.
-
-@item max-jump-thread-paths
-The maximum number of paths to consider when searching for jump threading
-opportunities. When arriving at a block, incoming edges are only considered
-if the number of paths to be searched so far multiplied by the number of
-incoming edges does not exhaust the specified maximum number of paths to
-consider.
-
-@item max-fields-for-field-sensitive
-Maximum number of fields in a structure treated in
-a field sensitive manner during pointer analysis.
-
-@item prefetch-latency
-Estimate on average number of instructions that are executed before
-prefetch finishes. The distance prefetched ahead is proportional
-to this constant. Increasing this number may also lead to less
-streams being prefetched (see @option{simultaneous-prefetches}).
-
-@item simultaneous-prefetches
-Maximum number of prefetches that can run at the same time.
-
-@item l1-cache-line-size
-The size of cache line in L1 data cache, in bytes.
-
-@item l1-cache-size
-The size of L1 data cache, in kilobytes.
-
-@item l2-cache-size
-The size of L2 data cache, in kilobytes.
-
-@item prefetch-dynamic-strides
-Whether the loop array prefetch pass should issue software prefetch hints
-for strides that are non-constant. In some cases this may be
-beneficial, though the fact the stride is non-constant may make it
-hard to predict when there is clear benefit to issuing these hints.
-
-Set to 1 if the prefetch hints should be issued for non-constant
-strides. Set to 0 if prefetch hints should be issued only for strides that
-are known to be constant and below @option{prefetch-minimum-stride}.
-
-@item prefetch-minimum-stride
-Minimum constant stride, in bytes, to start using prefetch hints for. If
-the stride is less than this threshold, prefetch hints will not be issued.
-
-This setting is useful for processors that have hardware prefetchers, in
-which case there may be conflicts between the hardware prefetchers and
-the software prefetchers. If the hardware prefetchers have a maximum
-stride they can handle, it should be used here to improve the use of
-software prefetchers.
-
-A value of -1 means we don't have a threshold and therefore
-prefetch hints can be issued for any constant stride.
-
-This setting is only useful for strides that are known and constant.
-
-@item destructive-interference-size
-@item constructive-interference-size
-The values for the C++17 variables
-@code{std::hardware_destructive_interference_size} and
-@code{std::hardware_constructive_interference_size}. The destructive
-interference size is the minimum recommended offset between two
-independent concurrently-accessed objects; the constructive
-interference size is the maximum recommended size of contiguous memory
-accessed together. Typically both will be the size of an L1 cache
-line for the target, in bytes. For a generic target covering a range of L1
-cache line sizes, typically the constructive interference size will be
-the small end of the range and the destructive size will be the large
-end.
-
-The destructive interference size is intended to be used for layout,
-and thus has ABI impact. The default value is not expected to be
-stable, and on some targets varies with @option{-mtune}, so use of
-this variable in a context where ABI stability is important, such as
-the public interface of a library, is strongly discouraged; if it is
-used in that context, users can stabilize the value using this
-option.
-
-The constructive interference size is less sensitive, as it is
-typically only used in a @samp{static_assert} to make sure that a type
-fits within a cache line.
-
-See also @option{-Winterference-size}.
-
-@item loop-interchange-max-num-stmts
-The maximum number of stmts in a loop to be interchanged.
-
-@item loop-interchange-stride-ratio
-The minimum ratio between stride of two loops for interchange to be profitable.
-
-@item min-insn-to-prefetch-ratio
-The minimum ratio between the number of instructions and the
-number of prefetches to enable prefetching in a loop.
-
-@item prefetch-min-insn-to-mem-ratio
-The minimum ratio between the number of instructions and the
-number of memory references to enable prefetching in a loop.
-
-@item use-canonical-types
-Whether the compiler should use the ``canonical'' type system.
-Should always be 1, which uses a more efficient internal
-mechanism for comparing types in C++ and Objective-C++. However, if
-bugs in the canonical type system are causing compilation failures,
-set this value to 0 to disable canonical types.
-
-@item switch-conversion-max-branch-ratio
-Switch initialization conversion refuses to create arrays that are
-bigger than @option{switch-conversion-max-branch-ratio} times the number of
-branches in the switch.
-
-@item max-partial-antic-length
-Maximum length of the partial antic set computed during the tree
-partial redundancy elimination optimization (@option{-ftree-pre}) when
-optimizing at @option{-O3} and above. For some sorts of source code
-the enhanced partial redundancy elimination optimization can run away,
-consuming all of the memory available on the host machine. This
-parameter sets a limit on the length of the sets that are computed,
-which prevents the runaway behavior. Setting a value of 0 for
-this parameter allows an unlimited set length.
-
-@item rpo-vn-max-loop-depth
-Maximum loop depth that is value-numbered optimistically.
-When the limit hits the innermost
-@var{rpo-vn-max-loop-depth} loops and the outermost loop in the
-loop nest are value-numbered optimistically and the remaining ones not.
-
-@item sccvn-max-alias-queries-per-access
-Maximum number of alias-oracle queries we perform when looking for
-redundancies for loads and stores. If this limit is hit the search
-is aborted and the load or store is not considered redundant. The
-number of queries is algorithmically limited to the number of
-stores on all paths from the load to the function entry.
-
-@item ira-max-loops-num
-IRA uses regional register allocation by default. If a function
-contains more loops than the number given by this parameter, only at most
-the given number of the most frequently-executed loops form regions
-for regional register allocation.
-
-@item ira-max-conflict-table-size
-Although IRA uses a sophisticated algorithm to compress the conflict
-table, the table can still require excessive amounts of memory for
-huge functions. If the conflict table for a function could be more
-than the size in MB given by this parameter, the register allocator
-instead uses a faster, simpler, and lower-quality
-algorithm that does not require building a pseudo-register conflict table.
-
-@item ira-loop-reserved-regs
-IRA can be used to evaluate more accurate register pressure in loops
-for decisions to move loop invariants (see @option{-O3}). The number
-of available registers reserved for some other purposes is given
-by this parameter. Default of the parameter
-is the best found from numerous experiments.
-
-@item ira-consider-dup-in-all-alts
-Make IRA to consider matching constraint (duplicated operand number)
-heavily in all available alternatives for preferred register class.
-If it is set as zero, it means IRA only respects the matching
-constraint when it's in the only available alternative with an
-appropriate register class. Otherwise, it means IRA will check all
-available alternatives for preferred register class even if it has
-found some choice with an appropriate register class and respect the
-found qualified matching constraint.
-
-@item lra-inheritance-ebb-probability-cutoff
-LRA tries to reuse values reloaded in registers in subsequent insns.
-This optimization is called inheritance. EBB is used as a region to
-do this optimization. The parameter defines a minimal fall-through
-edge probability in percentage used to add BB to inheritance EBB in
-LRA. The default value was chosen
-from numerous runs of SPEC2000 on x86-64.
-
-@item loop-invariant-max-bbs-in-loop
-Loop invariant motion can be very expensive, both in compilation time and
-in amount of needed compile-time memory, with very large loops. Loops
-with more basic blocks than this parameter won't have loop invariant
-motion optimization performed on them.
-
-@item loop-max-datarefs-for-datadeps
-Building data dependencies is expensive for very large loops. This
-parameter limits the number of data references in loops that are
-considered for data dependence analysis. These large loops are no
-handled by the optimizations using loop data dependencies.
-
-@item max-vartrack-size
-Sets a maximum number of hash table slots to use during variable
-tracking dataflow analysis of any function. If this limit is exceeded
-with variable tracking at assignments enabled, analysis for that
-function is retried without it, after removing all debug insns from
-the function. If the limit is exceeded even without debug insns, var
-tracking analysis is completely disabled for the function. Setting
-the parameter to zero makes it unlimited.
-
-@item max-vartrack-expr-depth
-Sets a maximum number of recursion levels when attempting to map
-variable names or debug temporaries to value expressions. This trades
-compilation time for more complete debug information. If this is set too
-low, value expressions that are available and could be represented in
-debug information may end up not being used; setting this higher may
-enable the compiler to find more complex debug expressions, but compile
-time and memory use may grow.
-
-@item max-debug-marker-count
-Sets a threshold on the number of debug markers (e.g.@: begin stmt
-markers) to avoid complexity explosion at inlining or expanding to RTL.
-If a function has more such gimple stmts than the set limit, such stmts
-will be dropped from the inlined copy of a function, and from its RTL
-expansion.
-
-@item min-nondebug-insn-uid
-Use uids starting at this parameter for nondebug insns. The range below
-the parameter is reserved exclusively for debug insns created by
-@option{-fvar-tracking-assignments}, but debug insns may get
-(non-overlapping) uids above it if the reserved range is exhausted.
-
-@item ipa-sra-ptr-growth-factor
-IPA-SRA replaces a pointer to an aggregate with one or more new
-parameters only when their cumulative size is less or equal to
-@option{ipa-sra-ptr-growth-factor} times the size of the original
-pointer parameter.
-
-@item ipa-sra-max-replacements
-Maximum pieces of an aggregate that IPA-SRA tracks. As a
-consequence, it is also the maximum number of replacements of a formal
-parameter.
-
-@item sra-max-scalarization-size-Ospeed
-@itemx sra-max-scalarization-size-Osize
-The two Scalar Reduction of Aggregates passes (SRA and IPA-SRA) aim to
-replace scalar parts of aggregates with uses of independent scalar
-variables. These parameters control the maximum size, in storage units,
-of aggregate which is considered for replacement when compiling for
-speed
-(@option{sra-max-scalarization-size-Ospeed}) or size
-(@option{sra-max-scalarization-size-Osize}) respectively.
-
-@item sra-max-propagations
-The maximum number of artificial accesses that Scalar Replacement of
-Aggregates (SRA) will track, per one local variable, in order to
-facilitate copy propagation.
-
-@item tm-max-aggregate-size
-When making copies of thread-local variables in a transaction, this
-parameter specifies the size in bytes after which variables are
-saved with the logging functions as opposed to save/restore code
-sequence pairs. This option only applies when using
-@option{-fgnu-tm}.
-
-@item graphite-max-nb-scop-params
-To avoid exponential effects in the Graphite loop transforms, the
-number of parameters in a Static Control Part (SCoP) is bounded.
-A value of zero can be used to lift
-the bound. A variable whose value is unknown at compilation time and
-defined outside a SCoP is a parameter of the SCoP.
-
-@item loop-block-tile-size
-Loop blocking or strip mining transforms, enabled with
-@option{-floop-block} or @option{-floop-strip-mine}, strip mine each
-loop in the loop nest by a given number of iterations. The strip
-length can be changed using the @option{loop-block-tile-size}
-parameter.
-
-@item ipa-jump-function-lookups
-Specifies number of statements visited during jump function offset discovery.
-
-@item ipa-cp-value-list-size
-IPA-CP attempts to track all possible values and types passed to a function's
-parameter in order to propagate them and perform devirtualization.
-@option{ipa-cp-value-list-size} is the maximum number of values and types it
-stores per one formal parameter of a function.
-
-@item ipa-cp-eval-threshold
-IPA-CP calculates its own score of cloning profitability heuristics
-and performs those cloning opportunities with scores that exceed
-@option{ipa-cp-eval-threshold}.
-
-@item ipa-cp-max-recursive-depth
-Maximum depth of recursive cloning for self-recursive function.
-
-@item ipa-cp-min-recursive-probability
-Recursive cloning only when the probability of call being executed exceeds
-the parameter.
-
-@item ipa-cp-profile-count-base
-When using @option{-fprofile-use} option, IPA-CP will consider the measured
-execution count of a call graph edge at this percentage position in their
-histogram as the basis for its heuristics calculation.
-
-@item ipa-cp-recursive-freq-factor
-The number of times interprocedural copy propagation expects recursive
-functions to call themselves.
-
-@item ipa-cp-recursion-penalty
-Percentage penalty the recursive functions will receive when they
-are evaluated for cloning.
-
-@item ipa-cp-single-call-penalty
-Percentage penalty functions containing a single call to another
-function will receive when they are evaluated for cloning.
-
-@item ipa-max-agg-items
-IPA-CP is also capable to propagate a number of scalar values passed
-in an aggregate. @option{ipa-max-agg-items} controls the maximum
-number of such values per one parameter.
-
-@item ipa-cp-loop-hint-bonus
-When IPA-CP determines that a cloning candidate would make the number
-of iterations of a loop known, it adds a bonus of
-@option{ipa-cp-loop-hint-bonus} to the profitability score of
-the candidate.
-
-@item ipa-max-loop-predicates
-The maximum number of different predicates IPA will use to describe when
-loops in a function have known properties.
-
-@item ipa-max-aa-steps
-During its analysis of function bodies, IPA-CP employs alias analysis
-in order to track values pointed to by function parameters. In order
-not spend too much time analyzing huge functions, it gives up and
-consider all memory clobbered after examining
-@option{ipa-max-aa-steps} statements modifying memory.
-
-@item ipa-max-switch-predicate-bounds
-Maximal number of boundary endpoints of case ranges of switch statement.
-For switch exceeding this limit, IPA-CP will not construct cloning cost
-predicate, which is used to estimate cloning benefit, for default case
-of the switch statement.
-
-@item ipa-max-param-expr-ops
-IPA-CP will analyze conditional statement that references some function
-parameter to estimate benefit for cloning upon certain constant value.
-But if number of operations in a parameter expression exceeds
-@option{ipa-max-param-expr-ops}, the expression is treated as complicated
-one, and is not handled by IPA analysis.
-
-@item lto-partitions
-Specify desired number of partitions produced during WHOPR compilation.
-The number of partitions should exceed the number of CPUs used for compilation.
-
-@item lto-min-partition
-Size of minimal partition for WHOPR (in estimated instructions).
-This prevents expenses of splitting very small programs into too many
-partitions.
-
-@item lto-max-partition
-Size of max partition for WHOPR (in estimated instructions).
-to provide an upper bound for individual size of partition.
-Meant to be used only with balanced partitioning.
-
-@item lto-max-streaming-parallelism
-Maximal number of parallel processes used for LTO streaming.
-
-@item cxx-max-namespaces-for-diagnostic-help
-The maximum number of namespaces to consult for suggestions when C++
-name lookup fails for an identifier.
-
-@item sink-frequency-threshold
-The maximum relative execution frequency (in percents) of the target block
-relative to a statement's original block to allow statement sinking of a
-statement. Larger numbers result in more aggressive statement sinking.
-A small positive adjustment is applied for
-statements with memory operands as those are even more profitable so sink.
-
-@item max-stores-to-sink
-The maximum number of conditional store pairs that can be sunk. Set to 0
-if either vectorization (@option{-ftree-vectorize}) or if-conversion
-(@option{-ftree-loop-if-convert}) is disabled.
-
-@item case-values-threshold
-The smallest number of different values for which it is best to use a
-jump-table instead of a tree of conditional branches. If the value is
-0, use the default for the machine.
-
-@item jump-table-max-growth-ratio-for-size
-The maximum code size growth ratio when expanding
-into a jump table (in percent). The parameter is used when
-optimizing for size.
-
-@item jump-table-max-growth-ratio-for-speed
-The maximum code size growth ratio when expanding
-into a jump table (in percent). The parameter is used when
-optimizing for speed.
-
-@item tree-reassoc-width
-Set the maximum number of instructions executed in parallel in
-reassociated tree. This parameter overrides target dependent
-heuristics used by default if has non zero value.
-
-@item sched-pressure-algorithm
-Choose between the two available implementations of
-@option{-fsched-pressure}. Algorithm 1 is the original implementation
-and is the more likely to prevent instructions from being reordered.
-Algorithm 2 was designed to be a compromise between the relatively
-conservative approach taken by algorithm 1 and the rather aggressive
-approach taken by the default scheduler. It relies more heavily on
-having a regular register file and accurate register pressure classes.
-See @file{haifa-sched.cc} in the GCC sources for more details.
-
-The default choice depends on the target.
-
-@item max-slsr-cand-scan
-Set the maximum number of existing candidates that are considered when
-seeking a basis for a new straight-line strength reduction candidate.
-
-@item asan-globals
-Enable buffer overflow detection for global objects. This kind
-of protection is enabled by default if you are using
-@option{-fsanitize=address} option.
-To disable global objects protection use @option{--param asan-globals=0}.
-
-@item asan-stack
-Enable buffer overflow detection for stack objects. This kind of
-protection is enabled by default when using @option{-fsanitize=address}.
-To disable stack protection use @option{--param asan-stack=0} option.
-
-@item asan-instrument-reads
-Enable buffer overflow detection for memory reads. This kind of
-protection is enabled by default when using @option{-fsanitize=address}.
-To disable memory reads protection use
-@option{--param asan-instrument-reads=0}.
-
-@item asan-instrument-writes
-Enable buffer overflow detection for memory writes. This kind of
-protection is enabled by default when using @option{-fsanitize=address}.
-To disable memory writes protection use
-@option{--param asan-instrument-writes=0} option.
-
-@item asan-memintrin
-Enable detection for built-in functions. This kind of protection
-is enabled by default when using @option{-fsanitize=address}.
-To disable built-in functions protection use
-@option{--param asan-memintrin=0}.
-
-@item asan-use-after-return
-Enable detection of use-after-return. This kind of protection
-is enabled by default when using the @option{-fsanitize=address} option.
-To disable it use @option{--param asan-use-after-return=0}.
-
-Note: By default the check is disabled at run time. To enable it,
-add @code{detect_stack_use_after_return=1} to the environment variable
-@env{ASAN_OPTIONS}.
-
-@item asan-instrumentation-with-call-threshold
-If number of memory accesses in function being instrumented
-is greater or equal to this number, use callbacks instead of inline checks.
-E.g. to disable inline code use
-@option{--param asan-instrumentation-with-call-threshold=0}.
-
-@item hwasan-instrument-stack
-Enable hwasan instrumentation of statically sized stack-allocated variables.
-This kind of instrumentation is enabled by default when using
-@option{-fsanitize=hwaddress} and disabled by default when using
-@option{-fsanitize=kernel-hwaddress}.
-To disable stack instrumentation use
-@option{--param hwasan-instrument-stack=0}, and to enable it use
-@option{--param hwasan-instrument-stack=1}.
-
-@item hwasan-random-frame-tag
-When using stack instrumentation, decide tags for stack variables using a
-deterministic sequence beginning at a random tag for each frame. With this
-parameter unset tags are chosen using the same sequence but beginning from 1.
-This is enabled by default for @option{-fsanitize=hwaddress} and unavailable
-for @option{-fsanitize=kernel-hwaddress}.
-To disable it use @option{--param hwasan-random-frame-tag=0}.
-
-@item hwasan-instrument-allocas
-Enable hwasan instrumentation of dynamically sized stack-allocated variables.
-This kind of instrumentation is enabled by default when using
-@option{-fsanitize=hwaddress} and disabled by default when using
-@option{-fsanitize=kernel-hwaddress}.
-To disable instrumentation of such variables use
-@option{--param hwasan-instrument-allocas=0}, and to enable it use
-@option{--param hwasan-instrument-allocas=1}.
-
-@item hwasan-instrument-reads
-Enable hwasan checks on memory reads. Instrumentation of reads is enabled by
-default for both @option{-fsanitize=hwaddress} and
-@option{-fsanitize=kernel-hwaddress}.
-To disable checking memory reads use
-@option{--param hwasan-instrument-reads=0}.
-
-@item hwasan-instrument-writes
-Enable hwasan checks on memory writes. Instrumentation of writes is enabled by
-default for both @option{-fsanitize=hwaddress} and
-@option{-fsanitize=kernel-hwaddress}.
-To disable checking memory writes use
-@option{--param hwasan-instrument-writes=0}.
-
-@item hwasan-instrument-mem-intrinsics
-Enable hwasan instrumentation of builtin functions. Instrumentation of these
-builtin functions is enabled by default for both @option{-fsanitize=hwaddress}
-and @option{-fsanitize=kernel-hwaddress}.
-To disable instrumentation of builtin functions use
-@option{--param hwasan-instrument-mem-intrinsics=0}.
-
-@item use-after-scope-direct-emission-threshold
-If the size of a local variable in bytes is smaller or equal to this
-number, directly poison (or unpoison) shadow memory instead of using
-run-time callbacks.
-
-@item tsan-distinguish-volatile
-Emit special instrumentation for accesses to volatiles.
-
-@item tsan-instrument-func-entry-exit
-Emit instrumentation calls to __tsan_func_entry() and __tsan_func_exit().
-
-@item max-fsm-thread-path-insns
-Maximum number of instructions to copy when duplicating blocks on a
-finite state automaton jump thread path.
-
-@item threader-debug
-threader-debug=[none|all] Enables verbose dumping of the threader solver.
-
-@item parloops-chunk-size
-Chunk size of omp schedule for loops parallelized by parloops.
-
-@item parloops-schedule
-Schedule type of omp schedule for loops parallelized by parloops (static,
-dynamic, guided, auto, runtime).
-
-@item parloops-min-per-thread
-The minimum number of iterations per thread of an innermost parallelized
-loop for which the parallelized variant is preferred over the single threaded
-one. Note that for a parallelized loop nest the
-minimum number of iterations of the outermost loop per thread is two.
-
-@item max-ssa-name-query-depth
-Maximum depth of recursion when querying properties of SSA names in things
-like fold routines. One level of recursion corresponds to following a
-use-def chain.
-
-@item max-speculative-devirt-maydefs
-The maximum number of may-defs we analyze when looking for a must-def
-specifying the dynamic type of an object that invokes a virtual call
-we may be able to devirtualize speculatively.
-
-@item max-vrp-switch-assertions
-The maximum number of assertions to add along the default edge of a switch
-statement during VRP.
-
-@item evrp-sparse-threshold
-Maximum number of basic blocks before EVRP uses a sparse cache.
-
-@item vrp1-mode
-Specifies the mode VRP pass 1 should operate in.
-
-@item vrp2-mode
-Specifies the mode VRP pass 2 should operate in.
-
-@item ranger-debug
-Specifies the type of debug output to be issued for ranges.
-
-@item evrp-switch-limit
-Specifies the maximum number of switch cases before EVRP ignores a switch.
-
-@item unroll-jam-min-percent
-The minimum percentage of memory references that must be optimized
-away for the unroll-and-jam transformation to be considered profitable.
-
-@item unroll-jam-max-unroll
-The maximum number of times the outer loop should be unrolled by
-the unroll-and-jam transformation.
-
-@item max-rtl-if-conversion-unpredictable-cost
-Maximum permissible cost for the sequence that would be generated
-by the RTL if-conversion pass for a branch that is considered unpredictable.
-
-@item max-variable-expansions-in-unroller
-If @option{-fvariable-expansion-in-unroller} is used, the maximum number
-of times that an individual variable will be expanded during loop unrolling.
-
-@item partial-inlining-entry-probability
-Maximum probability of the entry BB of split region
-(in percent relative to entry BB of the function)
-to make partial inlining happen.
-
-@item max-tracked-strlens
-Maximum number of strings for which strlen optimization pass will
-track string lengths.
-
-@item gcse-after-reload-partial-fraction
-The threshold ratio for performing partial redundancy
-elimination after reload.
-
-@item gcse-after-reload-critical-fraction
-The threshold ratio of critical edges execution count that
-permit performing redundancy elimination after reload.
-
-@item max-loop-header-insns
-The maximum number of insns in loop header duplicated
-by the copy loop headers pass.
-
-@item vect-epilogues-nomask
-Enable loop epilogue vectorization using smaller vector size.
-
-@item vect-partial-vector-usage
-Controls when the loop vectorizer considers using partial vector loads
-and stores as an alternative to falling back to scalar code. 0 stops
-the vectorizer from ever using partial vector loads and stores. 1 allows
-partial vector loads and stores if vectorization removes the need for the
-code to iterate. 2 allows partial vector loads and stores in all loops.
-The parameter only has an effect on targets that support partial
-vector loads and stores.
-
-@item vect-inner-loop-cost-factor
-The maximum factor which the loop vectorizer applies to the cost of statements
-in an inner loop relative to the loop being vectorized. The factor applied
-is the maximum of the estimated number of iterations of the inner loop and
-this parameter. The default value of this parameter is 50.
-
-@item vect-induction-float
-Enable loop vectorization of floating point inductions.
-
-@item avoid-fma-max-bits
-Maximum number of bits for which we avoid creating FMAs.
-
-@item sms-loop-average-count-threshold
-A threshold on the average loop count considered by the swing modulo scheduler.
-
-@item sms-dfa-history
-The number of cycles the swing modulo scheduler considers when checking
-conflicts using DFA.
-
-@item graphite-allow-codegen-errors
-Whether codegen errors should be ICEs when @option{-fchecking}.
-
-@item sms-max-ii-factor
-A factor for tuning the upper bound that swing modulo scheduler
-uses for scheduling a loop.
-
-@item lra-max-considered-reload-pseudos
-The max number of reload pseudos which are considered during
-spilling a non-reload pseudo.
-
-@item max-pow-sqrt-depth
-Maximum depth of sqrt chains to use when synthesizing exponentiation
-by a real constant.
-
-@item max-dse-active-local-stores
-Maximum number of active local stores in RTL dead store elimination.
-
-@item asan-instrument-allocas
-Enable asan allocas/VLAs protection.
-
-@item max-iterations-computation-cost
-Bound on the cost of an expression to compute the number of iterations.
-
-@item max-isl-operations
-Maximum number of isl operations, 0 means unlimited.
-
-@item graphite-max-arrays-per-scop
-Maximum number of arrays per scop.
-
-@item max-vartrack-reverse-op-size
-Max. size of loc list for which reverse ops should be added.
-
-@item fsm-scale-path-stmts
-Scale factor to apply to the number of statements in a threading path
-when comparing to the number of (scaled) blocks.
-
-@item uninit-control-dep-attempts
-Maximum number of nested calls to search for control dependencies
-during uninitialized variable analysis.
-
-@item fsm-scale-path-blocks
-Scale factor to apply to the number of blocks in a threading path
-when comparing to the number of (scaled) statements.
-
-@item sched-autopref-queue-depth
-Hardware autoprefetcher scheduler model control flag.
-Number of lookahead cycles the model looks into; at '
-' only enable instruction sorting heuristic.
-
-@item loop-versioning-max-inner-insns
-The maximum number of instructions that an inner loop can have
-before the loop versioning pass considers it too big to copy.
-
-@item loop-versioning-max-outer-insns
-The maximum number of instructions that an outer loop can have
-before the loop versioning pass considers it too big to copy,
-discounting any instructions in inner loops that directly benefit
-from versioning.
-
-@item ssa-name-def-chain-limit
-The maximum number of SSA_NAME assignments to follow in determining
-a property of a variable such as its value. This limits the number
-of iterations or recursive calls GCC performs when optimizing certain
-statements or when determining their validity prior to issuing
-diagnostics.
-
-@item store-merging-max-size
-Maximum size of a single store merging region in bytes.
-
-@item hash-table-verification-limit
-The number of elements for which hash table verification is done
-for each searched element.
-
-@item max-find-base-term-values
-Maximum number of VALUEs handled during a single find_base_term call.
-
-@item analyzer-max-enodes-per-program-point
-The maximum number of exploded nodes per program point within
-the analyzer, before terminating analysis of that point.
-
-@item analyzer-max-constraints
-The maximum number of constraints per state.
-
-@item analyzer-min-snodes-for-call-summary
-The minimum number of supernodes within a function for the
-analyzer to consider summarizing its effects at call sites.
-
-@item analyzer-max-enodes-for-full-dump
-The maximum depth of exploded nodes that should appear in a dot dump
-before switching to a less verbose format.
-
-@item analyzer-max-recursion-depth
-The maximum number of times a callsite can appear in a call stack
-within the analyzer, before terminating analysis of a call that would
-recurse deeper.
-
-@item analyzer-max-svalue-depth
-The maximum depth of a symbolic value, before approximating
-the value as unknown.
-
-@item analyzer-max-infeasible-edges
-The maximum number of infeasible edges to reject before declaring
-a diagnostic as infeasible.
-
-@item gimple-fe-computed-hot-bb-threshold
-The number of executions of a basic block which is considered hot.
-The parameter is used only in GIMPLE FE.
-
-@item analyzer-bb-explosion-factor
-The maximum number of 'after supernode' exploded nodes within the analyzer
-per supernode, before terminating analysis.
-
-@item ranger-logical-depth
-Maximum depth of logical expression evaluation ranger will look through
-when evaluating outgoing edge ranges.
-
-@item relation-block-limit
-Maximum number of relations the oracle will register in a basic block.
-
-@item min-pagesize
-Minimum page size for warning purposes.
-
-@item openacc-kernels
-Specify mode of OpenACC `kernels' constructs handling.
-With @option{--param=openacc-kernels=decompose}, OpenACC `kernels'
-constructs are decomposed into parts, a sequence of compute
-constructs, each then handled individually.
-This is work in progress.
-With @option{--param=openacc-kernels=parloops}, OpenACC `kernels'
-constructs are handled by the @samp{parloops} pass, en bloc.
-This is the current default.
-
-@item openacc-privatization
-Specify mode of OpenACC privatization diagnostics for
-@option{-fopt-info-omp-note} and applicable
-@option{-fdump-tree-*-details}.
-With @option{--param=openacc-privatization=quiet}, don't diagnose.
-This is the current default.
-With @option{--param=openacc-privatization=noisy}, do diagnose.
-
-@end table
-
-The following choices of @var{name} are available on AArch64 targets:
-
-@table @gcctabopt
-@item aarch64-sve-compare-costs
-When vectorizing for SVE, consider using ``unpacked'' vectors for
-smaller elements and use the cost model to pick the cheapest approach.
-Also use the cost model to choose between SVE and Advanced SIMD vectorization.
-
-Using unpacked vectors includes storing smaller elements in larger
-containers and accessing elements with extending loads and truncating
-stores.
-
-@item aarch64-float-recp-precision
-The number of Newton iterations for calculating the reciprocal for float type.
-The precision of division is proportional to this param when division
-approximation is enabled. The default value is 1.
-
-@item aarch64-double-recp-precision
-The number of Newton iterations for calculating the reciprocal for double type.
-The precision of division is propotional to this param when division
-approximation is enabled. The default value is 2.
-
-@item aarch64-autovec-preference
-Force an ISA selection strategy for auto-vectorization. Accepts values from
-0 to 4, inclusive.
-@table @samp
-@item 0
-Use the default heuristics.
-@item 1
-Use only Advanced SIMD for auto-vectorization.
-@item 2
-Use only SVE for auto-vectorization.
-@item 3
-Use both Advanced SIMD and SVE. Prefer Advanced SIMD when the costs are
-deemed equal.
-@item 4
-Use both Advanced SIMD and SVE. Prefer SVE when the costs are deemed equal.
-@end table
-The default value is 0.
-
-@item aarch64-loop-vect-issue-rate-niters
-The tuning for some AArch64 CPUs tries to take both latencies and issue
-rates into account when deciding whether a loop should be vectorized
-using SVE, vectorized using Advanced SIMD, or not vectorized at all.
-If this parameter is set to @var{n}, GCC will not use this heuristic
-for loops that are known to execute in fewer than @var{n} Advanced
-SIMD iterations.
-
-@item aarch64-vect-unroll-limit
-The vectorizer will use available tuning information to determine whether it
-would be beneficial to unroll the main vectorized loop and by how much. This
-parameter set's the upper bound of how much the vectorizer will unroll the main
-loop. The default value is four.
-
-@end table
-
-The following choices of @var{name} are available on i386 and x86_64 targets:
-
-@table @gcctabopt
-@item x86-stlf-window-ninsns
-Instructions number above which STFL stall penalty can be compensated.
-
-@end table
-
-@end table
-
-@node Instrumentation Options
-@section Program Instrumentation Options
-@cindex instrumentation options
-@cindex program instrumentation options
-@cindex run-time error checking options
-@cindex profiling options
-@cindex options, program instrumentation
-@cindex options, run-time error checking
-@cindex options, profiling
-
-GCC supports a number of command-line options that control adding
-run-time instrumentation to the code it normally generates.
-For example, one purpose of instrumentation is collect profiling
-statistics for use in finding program hot spots, code coverage
-analysis, or profile-guided optimizations.
-Another class of program instrumentation is adding run-time checking
-to detect programming errors like invalid pointer
-dereferences or out-of-bounds array accesses, as well as deliberately
-hostile attacks such as stack smashing or C++ vtable hijacking.
-There is also a general hook which can be used to implement other
-forms of tracing or function-level instrumentation for debug or
-program analysis purposes.
-
-@table @gcctabopt
-@cindex @command{prof}
-@cindex @command{gprof}
-@item -p
-@itemx -pg
-@opindex p
-@opindex pg
-Generate extra code to write profile information suitable for the
-analysis program @command{prof} (for @option{-p}) or @command{gprof}
-(for @option{-pg}). You must use this option when compiling
-the source files you want data about, and you must also use it when
-linking.
-
-You can use the function attribute @code{no_instrument_function} to
-suppress profiling of individual functions when compiling with these options.
-@xref{Common Function Attributes}.
-
-@item -fprofile-arcs
-@opindex fprofile-arcs
-Add code so that program flow @dfn{arcs} are instrumented. During
-execution the program records how many times each branch and call is
-executed and how many times it is taken or returns. On targets that support
-constructors with priority support, profiling properly handles constructors,
-destructors and C++ constructors (and destructors) of classes which are used
-as a type of a global variable.
-
-When the compiled
-program exits it saves this data to a file called
-@file{@var{auxname}.gcda} for each source file. The data may be used for
-profile-directed optimizations (@option{-fbranch-probabilities}), or for
-test coverage analysis (@option{-ftest-coverage}). Each object file's
-@var{auxname} is generated from the name of the output file, if
-explicitly specified and it is not the final executable, otherwise it is
-the basename of the source file. In both cases any suffix is removed
-(e.g.@: @file{foo.gcda} for input file @file{dir/foo.c}, or
-@file{dir/foo.gcda} for output file specified as @option{-o dir/foo.o}).
-
-Note that if a command line directly links source files, the corresponding
-@var{.gcda} files will be prefixed with the unsuffixed name of the output file.
-E.g. @code{gcc a.c b.c -o binary} would generate @file{binary-a.gcda} and
-@file{binary-b.gcda} files.
-
-@xref{Cross-profiling}.
-
-@cindex @command{gcov}
-@item --coverage
-@opindex coverage
-
-This option is used to compile and link code instrumented for coverage
-analysis. The option is a synonym for @option{-fprofile-arcs}
-@option{-ftest-coverage} (when compiling) and @option{-lgcov} (when
-linking). See the documentation for those options for more details.
-
-@itemize
-
-@item
-Compile the source files with @option{-fprofile-arcs} plus optimization
-and code generation options. For test coverage analysis, use the
-additional @option{-ftest-coverage} option. You do not need to profile
-every source file in a program.
-
-@item
-Compile the source files additionally with @option{-fprofile-abs-path}
-to create absolute path names in the @file{.gcno} files. This allows
-@command{gcov} to find the correct sources in projects where compilations
-occur with different working directories.
-
-@item
-Link your object files with @option{-lgcov} or @option{-fprofile-arcs}
-(the latter implies the former).
-
-@item
-Run the program on a representative workload to generate the arc profile
-information. This may be repeated any number of times. You can run
-concurrent instances of your program, and provided that the file system
-supports locking, the data files will be correctly updated. Unless
-a strict ISO C dialect option is in effect, @code{fork} calls are
-detected and correctly handled without double counting.
-
-Moreover, an object file can be recompiled multiple times
-and the corresponding @file{.gcda} file merges as long as
-the source file and the compiler options are unchanged.
-
-@item
-For profile-directed optimizations, compile the source files again with
-the same optimization and code generation options plus
-@option{-fbranch-probabilities} (@pxref{Optimize Options,,Options that
-Control Optimization}).
-
-@item
-For test coverage analysis, use @command{gcov} to produce human readable
-information from the @file{.gcno} and @file{.gcda} files. Refer to the
-@command{gcov} documentation for further information.
-
-@end itemize
-
-With @option{-fprofile-arcs}, for each function of your program GCC
-creates a program flow graph, then finds a spanning tree for the graph.
-Only arcs that are not on the spanning tree have to be instrumented: the
-compiler adds code to count the number of times that these arcs are
-executed. When an arc is the only exit or only entrance to a block, the
-instrumentation code can be added to the block; otherwise, a new basic
-block must be created to hold the instrumentation code.
-
-@need 2000
-@item -ftest-coverage
-@opindex ftest-coverage
-Produce a notes file that the @command{gcov} code-coverage utility
-(@pxref{Gcov,, @command{gcov}---a Test Coverage Program}) can use to
-show program coverage. Each source file's note file is called
-@file{@var{auxname}.gcno}. Refer to the @option{-fprofile-arcs} option
-above for a description of @var{auxname} and instructions on how to
-generate test coverage data. Coverage data matches the source files
-more closely if you do not optimize.
-
-@item -fprofile-abs-path
-@opindex fprofile-abs-path
-Automatically convert relative source file names to absolute path names
-in the @file{.gcno} files. This allows @command{gcov} to find the correct
-sources in projects where compilations occur with different working
-directories.
-
-@item -fprofile-dir=@var{path}
-@opindex fprofile-dir
-
-Set the directory to search for the profile data files in to @var{path}.
-This option affects only the profile data generated by
-@option{-fprofile-generate}, @option{-ftest-coverage}, @option{-fprofile-arcs}
-and used by @option{-fprofile-use} and @option{-fbranch-probabilities}
-and its related options. Both absolute and relative paths can be used.
-By default, GCC uses the current directory as @var{path}, thus the
-profile data file appears in the same directory as the object file.
-In order to prevent the file name clashing, if the object file name is
-not an absolute path, we mangle the absolute path of the
-@file{@var{sourcename}.gcda} file and use it as the file name of a
-@file{.gcda} file. See details about the file naming in @option{-fprofile-arcs}.
-See similar option @option{-fprofile-note}.
-
-When an executable is run in a massive parallel environment, it is recommended
-to save profile to different folders. That can be done with variables
-in @var{path} that are exported during run-time:
-
-@table @gcctabopt
-
-@item %p
-process ID.
-
-@item %q@{VAR@}
-value of environment variable @var{VAR}
-
-@end table
-
-@item -fprofile-generate
-@itemx -fprofile-generate=@var{path}
-@opindex fprofile-generate
-
-Enable options usually used for instrumenting application to produce
-profile useful for later recompilation with profile feedback based
-optimization. You must use @option{-fprofile-generate} both when
-compiling and when linking your program.
-
-The following options are enabled:
-@option{-fprofile-arcs}, @option{-fprofile-values},
-@option{-finline-functions}, and @option{-fipa-bit-cp}.
-
-If @var{path} is specified, GCC looks at the @var{path} to find
-the profile feedback data files. See @option{-fprofile-dir}.
-
-To optimize the program based on the collected profile information, use
-@option{-fprofile-use}. @xref{Optimize Options}, for more information.
-
-@item -fprofile-info-section
-@itemx -fprofile-info-section=@var{name}
-@opindex fprofile-info-section
-
-Register the profile information in the specified section instead of using a
-constructor/destructor. The section name is @var{name} if it is specified,
-otherwise the section name defaults to @code{.gcov_info}. A pointer to the
-profile information generated by @option{-fprofile-arcs} is placed in the
-specified section for each translation unit. This option disables the profile
-information registration through a constructor and it disables the profile
-information processing through a destructor. This option is not intended to be
-used in hosted environments such as GNU/Linux. It targets freestanding
-environments (for example embedded systems) with limited resources which do not
-support constructors/destructors or the C library file I/O.
-
-The linker could collect the input sections in a continuous memory block and
-define start and end symbols. A GNU linker script example which defines a
-linker output section follows:
-
-@smallexample
- .gcov_info :
- @{
- PROVIDE (__gcov_info_start = .);
- KEEP (*(.gcov_info))
- PROVIDE (__gcov_info_end = .);
- @}
-@end smallexample
-
-The program could dump the profiling information registered in this linker set
-for example like this:
-
-@smallexample
-#include <gcov.h>
-#include <stdio.h>
-#include <stdlib.h>
-
-extern const struct gcov_info *const __gcov_info_start[];
-extern const struct gcov_info *const __gcov_info_end[];
-
-static void
-dump (const void *d, unsigned n, void *arg)
-@{
- const unsigned char *c = d;
-
- for (unsigned i = 0; i < n; ++i)
- printf ("%02x", c[i]);
-@}
-
-static void
-filename (const char *f, void *arg)
-@{
- __gcov_filename_to_gcfn (f, dump, arg );
-@}
-
-static void *
-allocate (unsigned length, void *arg)
-@{
- return malloc (length);
-@}
-
-static void
-dump_gcov_info (void)
-@{
- const struct gcov_info *const *info = __gcov_info_start;
- const struct gcov_info *const *end = __gcov_info_end;
-
- /* Obfuscate variable to prevent compiler optimizations. */
- __asm__ ("" : "+r" (info));
-
- while (info != end)
- @{
- void *arg = NULL;
- __gcov_info_to_gcda (*info, filename, dump, allocate, arg);
- putchar ('\n');
- ++info;
- @}
-@}
-
-int
-main (void)
-@{
- dump_gcov_info ();
- return 0;
-@}
-@end smallexample
-
-The @command{merge-stream} subcommand of @command{gcov-tool} may be used to
-deserialize the data stream generated by the @code{__gcov_filename_to_gcfn} and
-@code{__gcov_info_to_gcda} functions and merge the profile information into
-@file{.gcda} files on the host filesystem.
-
-@item -fprofile-note=@var{path}
-@opindex fprofile-note
-
-If @var{path} is specified, GCC saves @file{.gcno} file into @var{path}
-location. If you combine the option with multiple source files,
-the @file{.gcno} file will be overwritten.
-
-@item -fprofile-prefix-path=@var{path}
-@opindex fprofile-prefix-path
-
-This option can be used in combination with
-@option{profile-generate=}@var{profile_dir} and
-@option{profile-use=}@var{profile_dir} to inform GCC where is the base
-directory of built source tree. By default @var{profile_dir} will contain
-files with mangled absolute paths of all object files in the built project.
-This is not desirable when directory used to build the instrumented binary
-differs from the directory used to build the binary optimized with profile
-feedback because the profile data will not be found during the optimized build.
-In such setups @option{-fprofile-prefix-path=}@var{path} with @var{path}
-pointing to the base directory of the build can be used to strip the irrelevant
-part of the path and keep all file names relative to the main build directory.
-
-@item -fprofile-prefix-map=@var{old}=@var{new}
-@opindex fprofile-prefix-map
-When compiling files residing in directory @file{@var{old}}, record
-profiling information (with @option{--coverage})
-describing them as if the files resided in
-directory @file{@var{new}} instead.
-See also @option{-ffile-prefix-map}.
-
-@item -fprofile-update=@var{method}
-@opindex fprofile-update
-
-Alter the update method for an application instrumented for profile
-feedback based optimization. The @var{method} argument should be one of
-@samp{single}, @samp{atomic} or @samp{prefer-atomic}.
-The first one is useful for single-threaded applications,
-while the second one prevents profile corruption by emitting thread-safe code.
-
-@strong{Warning:} When an application does not properly join all threads
-(or creates an detached thread), a profile file can be still corrupted.
-
-Using @samp{prefer-atomic} would be transformed either to @samp{atomic},
-when supported by a target, or to @samp{single} otherwise. The GCC driver
-automatically selects @samp{prefer-atomic} when @option{-pthread}
-is present in the command line.
-
-@item -fprofile-filter-files=@var{regex}
-@opindex fprofile-filter-files
-
-Instrument only functions from files whose name matches
-any of the regular expressions (separated by semi-colons).
-
-For example, @option{-fprofile-filter-files=main\.c;module.*\.c} will instrument
-only @file{main.c} and all C files starting with 'module'.
-
-@item -fprofile-exclude-files=@var{regex}
-@opindex fprofile-exclude-files
-
-Instrument only functions from files whose name does not match
-any of the regular expressions (separated by semi-colons).
-
-For example, @option{-fprofile-exclude-files=/usr/.*} will prevent instrumentation
-of all files that are located in the @file{/usr/} folder.
-
-@item -fprofile-reproducible=@r{[}multithreaded@r{|}parallel-runs@r{|}serial@r{]}
-@opindex fprofile-reproducible
-Control level of reproducibility of profile gathered by
-@code{-fprofile-generate}. This makes it possible to rebuild program
-with same outcome which is useful, for example, for distribution
-packages.
-
-With @option{-fprofile-reproducible=serial} the profile gathered by
-@option{-fprofile-generate} is reproducible provided the trained program
-behaves the same at each invocation of the train run, it is not
-multi-threaded and profile data streaming is always done in the same
-order. Note that profile streaming happens at the end of program run but
-also before @code{fork} function is invoked.
-
-Note that it is quite common that execution counts of some part of
-programs depends, for example, on length of temporary file names or
-memory space randomization (that may affect hash-table collision rate).
-Such non-reproducible part of programs may be annotated by
-@code{no_instrument_function} function attribute. @command{gcov-dump} with
-@option{-l} can be used to dump gathered data and verify that they are
-indeed reproducible.
-
-With @option{-fprofile-reproducible=parallel-runs} collected profile
-stays reproducible regardless the order of streaming of the data into
-gcda files. This setting makes it possible to run multiple instances of
-instrumented program in parallel (such as with @code{make -j}). This
-reduces quality of gathered data, in particular of indirect call
-profiling.
-
-@item -fsanitize=address
-@opindex fsanitize=address
-Enable AddressSanitizer, a fast memory error detector.
-Memory access instructions are instrumented to detect
-out-of-bounds and use-after-free bugs.
-The option enables @option{-fsanitize-address-use-after-scope}.
-See @uref{https://github.com/google/sanitizers/wiki/AddressSanitizer} for
-more details. The run-time behavior can be influenced using the
-@env{ASAN_OPTIONS} environment variable. When set to @code{help=1},
-the available options are shown at startup of the instrumented program. See
-@url{https://github.com/google/sanitizers/wiki/AddressSanitizerFlags#run-time-flags}
-for a list of supported options.
-The option cannot be combined with @option{-fsanitize=thread} or
-@option{-fsanitize=hwaddress}. Note that the only target
-@option{-fsanitize=hwaddress} is currently supported on is AArch64.
-
-@item -fsanitize=kernel-address
-@opindex fsanitize=kernel-address
-Enable AddressSanitizer for Linux kernel.
-See @uref{https://github.com/google/kasan} for more details.
-
-@item -fsanitize=hwaddress
-@opindex fsanitize=hwaddress
-Enable Hardware-assisted AddressSanitizer, which uses a hardware ability to
-ignore the top byte of a pointer to allow the detection of memory errors with
-a low memory overhead.
-Memory access instructions are instrumented to detect out-of-bounds and
-use-after-free bugs.
-The option enables @option{-fsanitize-address-use-after-scope}.
-See
-@uref{https://clang.llvm.org/docs/HardwareAssistedAddressSanitizerDesign.html}
-for more details. The run-time behavior can be influenced using the
-@env{HWASAN_OPTIONS} environment variable. When set to @code{help=1},
-the available options are shown at startup of the instrumented program.
-The option cannot be combined with @option{-fsanitize=thread} or
-@option{-fsanitize=address}, and is currently only available on AArch64.
-
-@item -fsanitize=kernel-hwaddress
-@opindex fsanitize=kernel-hwaddress
-Enable Hardware-assisted AddressSanitizer for compilation of the Linux kernel.
-Similar to @option{-fsanitize=kernel-address} but using an alternate
-instrumentation method, and similar to @option{-fsanitize=hwaddress} but with
-instrumentation differences necessary for compiling the Linux kernel.
-These differences are to avoid hwasan library initialization calls and to
-account for the stack pointer having a different value in its top byte.
-
-@emph{Note:} This option has different defaults to the @option{-fsanitize=hwaddress}.
-Instrumenting the stack and alloca calls are not on by default but are still
-possible by specifying the command-line options
-@option{--param hwasan-instrument-stack=1} and
-@option{--param hwasan-instrument-allocas=1} respectively. Using a random frame
-tag is not implemented for kernel instrumentation.
-
-@item -fsanitize=pointer-compare
-@opindex fsanitize=pointer-compare
-Instrument comparison operation (<, <=, >, >=) with pointer operands.
-The option must be combined with either @option{-fsanitize=kernel-address} or
-@option{-fsanitize=address}
-The option cannot be combined with @option{-fsanitize=thread}.
-Note: By default the check is disabled at run time. To enable it,
-add @code{detect_invalid_pointer_pairs=2} to the environment variable
-@env{ASAN_OPTIONS}. Using @code{detect_invalid_pointer_pairs=1} detects
-invalid operation only when both pointers are non-null.
-
-@item -fsanitize=pointer-subtract
-@opindex fsanitize=pointer-subtract
-Instrument subtraction with pointer operands.
-The option must be combined with either @option{-fsanitize=kernel-address} or
-@option{-fsanitize=address}
-The option cannot be combined with @option{-fsanitize=thread}.
-Note: By default the check is disabled at run time. To enable it,
-add @code{detect_invalid_pointer_pairs=2} to the environment variable
-@env{ASAN_OPTIONS}. Using @code{detect_invalid_pointer_pairs=1} detects
-invalid operation only when both pointers are non-null.
-
-@item -fsanitize=shadow-call-stack
-@opindex fsanitize=shadow-call-stack
-Enable ShadowCallStack, a security enhancement mechanism used to protect
-programs against return address overwrites (e.g. stack buffer overflows.)
-It works by saving a function's return address to a separately allocated
-shadow call stack in the function prologue and restoring the return address
-from the shadow call stack in the function epilogue. Instrumentation only
-occurs in functions that need to save the return address to the stack.
-
-Currently it only supports the aarch64 platform. It is specifically
-designed for linux kernels that enable the CONFIG_SHADOW_CALL_STACK option.
-For the user space programs, runtime support is not currently provided
-in libc and libgcc. Users who want to use this feature in user space need
-to provide their own support for the runtime. It should be noted that
-this may cause the ABI rules to be broken.
-
-On aarch64, the instrumentation makes use of the platform register @code{x18}.
-This generally means that any code that may run on the same thread as code
-compiled with ShadowCallStack must be compiled with the flag
-@option{-ffixed-x18}, otherwise functions compiled without
-@option{-ffixed-x18} might clobber @code{x18} and so corrupt the shadow
-stack pointer.
-
-Also, because there is no userspace runtime support, code compiled with
-ShadowCallStack cannot use exception handling. Use @option{-fno-exceptions}
-to turn off exceptions.
-
-See @uref{https://clang.llvm.org/docs/ShadowCallStack.html} for more
-details.
-
-@item -fsanitize=thread
-@opindex fsanitize=thread
-Enable ThreadSanitizer, a fast data race detector.
-Memory access instructions are instrumented to detect
-data race bugs. See @uref{https://github.com/google/sanitizers/wiki#threadsanitizer} for more
-details. The run-time behavior can be influenced using the @env{TSAN_OPTIONS}
-environment variable; see
-@url{https://github.com/google/sanitizers/wiki/ThreadSanitizerFlags} for a list of
-supported options.
-The option cannot be combined with @option{-fsanitize=address},
-@option{-fsanitize=leak}.
-
-Note that sanitized atomic builtins cannot throw exceptions when
-operating on invalid memory addresses with non-call exceptions
-(@option{-fnon-call-exceptions}).
-
-@item -fsanitize=leak
-@opindex fsanitize=leak
-Enable LeakSanitizer, a memory leak detector.
-This option only matters for linking of executables and
-the executable is linked against a library that overrides @code{malloc}
-and other allocator functions. See
-@uref{https://github.com/google/sanitizers/wiki/AddressSanitizerLeakSanitizer} for more
-details. The run-time behavior can be influenced using the
-@env{LSAN_OPTIONS} environment variable.
-The option cannot be combined with @option{-fsanitize=thread}.
-
-@item -fsanitize=undefined
-@opindex fsanitize=undefined
-Enable UndefinedBehaviorSanitizer, a fast undefined behavior detector.
-Various computations are instrumented to detect undefined behavior
-at runtime. See @uref{https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html} for more details. The run-time behavior can be influenced using the
-@env{UBSAN_OPTIONS} environment variable. Current suboptions are:
-
-@table @gcctabopt
-
-@item -fsanitize=shift
-@opindex fsanitize=shift
-This option enables checking that the result of a shift operation is
-not undefined. Note that what exactly is considered undefined differs
-slightly between C and C++, as well as between ISO C90 and C99, etc.
-This option has two suboptions, @option{-fsanitize=shift-base} and
-@option{-fsanitize=shift-exponent}.
-
-@item -fsanitize=shift-exponent
-@opindex fsanitize=shift-exponent
-This option enables checking that the second argument of a shift operation
-is not negative and is smaller than the precision of the promoted first
-argument.
-
-@item -fsanitize=shift-base
-@opindex fsanitize=shift-base
-If the second argument of a shift operation is within range, check that the
-result of a shift operation is not undefined. Note that what exactly is
-considered undefined differs slightly between C and C++, as well as between
-ISO C90 and C99, etc.
-
-@item -fsanitize=integer-divide-by-zero
-@opindex fsanitize=integer-divide-by-zero
-Detect integer division by zero.
-
-@item -fsanitize=unreachable
-@opindex fsanitize=unreachable
-With this option, the compiler turns the @code{__builtin_unreachable}
-call into a diagnostics message call instead. When reaching the
-@code{__builtin_unreachable} call, the behavior is undefined.
-
-@item -fsanitize=vla-bound
-@opindex fsanitize=vla-bound
-This option instructs the compiler to check that the size of a variable
-length array is positive.
-
-@item -fsanitize=null
-@opindex fsanitize=null
-This option enables pointer checking. Particularly, the application
-built with this option turned on will issue an error message when it
-tries to dereference a NULL pointer, or if a reference (possibly an
-rvalue reference) is bound to a NULL pointer, or if a method is invoked
-on an object pointed by a NULL pointer.
-
-@item -fsanitize=return
-@opindex fsanitize=return
-This option enables return statement checking. Programs
-built with this option turned on will issue an error message
-when the end of a non-void function is reached without actually
-returning a value. This option works in C++ only.
-
-@item -fsanitize=signed-integer-overflow
-@opindex fsanitize=signed-integer-overflow
-This option enables signed integer overflow checking. We check that
-the result of @code{+}, @code{*}, and both unary and binary @code{-}
-does not overflow in the signed arithmetics. This also detects
-@code{INT_MIN / -1} signed division. Note, integer promotion
-rules must be taken into account. That is, the following is not an
-overflow:
-@smallexample
-signed char a = SCHAR_MAX;
-a++;
-@end smallexample
-
-@item -fsanitize=bounds
-@opindex fsanitize=bounds
-This option enables instrumentation of array bounds. Various out of bounds
-accesses are detected. Flexible array members, flexible array member-like
-arrays, and initializers of variables with static storage are not instrumented.
-
-@item -fsanitize=bounds-strict
-@opindex fsanitize=bounds-strict
-This option enables strict instrumentation of array bounds. Most out of bounds
-accesses are detected, including flexible array members and flexible array
-member-like arrays. Initializers of variables with static storage are not
-instrumented.
-
-@item -fsanitize=alignment
-@opindex fsanitize=alignment
-
-This option enables checking of alignment of pointers when they are
-dereferenced, or when a reference is bound to insufficiently aligned target,
-or when a method or constructor is invoked on insufficiently aligned object.
-
-@item -fsanitize=object-size
-@opindex fsanitize=object-size
-This option enables instrumentation of memory references using the
-@code{__builtin_object_size} function. Various out of bounds pointer
-accesses are detected.
-
-@item -fsanitize=float-divide-by-zero
-@opindex fsanitize=float-divide-by-zero
-Detect floating-point division by zero. Unlike other similar options,
-@option{-fsanitize=float-divide-by-zero} is not enabled by
-@option{-fsanitize=undefined}, since floating-point division by zero can
-be a legitimate way of obtaining infinities and NaNs.
-
-@item -fsanitize=float-cast-overflow
-@opindex fsanitize=float-cast-overflow
-This option enables floating-point type to integer conversion checking.
-We check that the result of the conversion does not overflow.
-Unlike other similar options, @option{-fsanitize=float-cast-overflow} is
-not enabled by @option{-fsanitize=undefined}.
-This option does not work well with @code{FE_INVALID} exceptions enabled.
-
-@item -fsanitize=nonnull-attribute
-@opindex fsanitize=nonnull-attribute
-
-This option enables instrumentation of calls, checking whether null values
-are not passed to arguments marked as requiring a non-null value by the
-@code{nonnull} function attribute.
-
-@item -fsanitize=returns-nonnull-attribute
-@opindex fsanitize=returns-nonnull-attribute
-
-This option enables instrumentation of return statements in functions
-marked with @code{returns_nonnull} function attribute, to detect returning
-of null values from such functions.
-
-@item -fsanitize=bool
-@opindex fsanitize=bool
-
-This option enables instrumentation of loads from bool. If a value other
-than 0/1 is loaded, a run-time error is issued.
-
-@item -fsanitize=enum
-@opindex fsanitize=enum
-
-This option enables instrumentation of loads from an enum type. If
-a value outside the range of values for the enum type is loaded,
-a run-time error is issued.
-
-@item -fsanitize=vptr
-@opindex fsanitize=vptr
-
-This option enables instrumentation of C++ member function calls, member
-accesses and some conversions between pointers to base and derived classes,
-to verify the referenced object has the correct dynamic type.
-
-@item -fsanitize=pointer-overflow
-@opindex fsanitize=pointer-overflow
-
-This option enables instrumentation of pointer arithmetics. If the pointer
-arithmetics overflows, a run-time error is issued.
-
-@item -fsanitize=builtin
-@opindex fsanitize=builtin
-
-This option enables instrumentation of arguments to selected builtin
-functions. If an invalid value is passed to such arguments, a run-time
-error is issued. E.g.@ passing 0 as the argument to @code{__builtin_ctz}
-or @code{__builtin_clz} invokes undefined behavior and is diagnosed
-by this option.
-
-@end table
-
-Note that sanitizers tend to increase the rate of false positive
-warnings, most notably those around @option{-Wmaybe-uninitialized}.
-We recommend against combining @option{-Werror} and [the use of]
-sanitizers.
-
-While @option{-ftrapv} causes traps for signed overflows to be emitted,
-@option{-fsanitize=undefined} gives a diagnostic message.
-This currently works only for the C family of languages.
-
-@item -fno-sanitize=all
-@opindex fno-sanitize=all
-
-This option disables all previously enabled sanitizers.
-@option{-fsanitize=all} is not allowed, as some sanitizers cannot be used
-together.
-
-@item -fasan-shadow-offset=@var{number}
-@opindex fasan-shadow-offset
-This option forces GCC to use custom shadow offset in AddressSanitizer checks.
-It is useful for experimenting with different shadow memory layouts in
-Kernel AddressSanitizer.
-
-@item -fsanitize-sections=@var{s1},@var{s2},...
-@opindex fsanitize-sections
-Sanitize global variables in selected user-defined sections. @var{si} may
-contain wildcards.
-
-@item -fsanitize-recover@r{[}=@var{opts}@r{]}
-@opindex fsanitize-recover
-@opindex fno-sanitize-recover
-@option{-fsanitize-recover=} controls error recovery mode for sanitizers
-mentioned in comma-separated list of @var{opts}. Enabling this option
-for a sanitizer component causes it to attempt to continue
-running the program as if no error happened. This means multiple
-runtime errors can be reported in a single program run, and the exit
-code of the program may indicate success even when errors
-have been reported. The @option{-fno-sanitize-recover=} option
-can be used to alter
-this behavior: only the first detected error is reported
-and program then exits with a non-zero exit code.
-
-Currently this feature only works for @option{-fsanitize=undefined} (and its suboptions
-except for @option{-fsanitize=unreachable} and @option{-fsanitize=return}),
-@option{-fsanitize=float-cast-overflow}, @option{-fsanitize=float-divide-by-zero},
-@option{-fsanitize=bounds-strict},
-@option{-fsanitize=kernel-address} and @option{-fsanitize=address}.
-For these sanitizers error recovery is turned on by default,
-except @option{-fsanitize=address}, for which this feature is experimental.
-@option{-fsanitize-recover=all} and @option{-fno-sanitize-recover=all} is also
-accepted, the former enables recovery for all sanitizers that support it,
-the latter disables recovery for all sanitizers that support it.
-
-Even if a recovery mode is turned on the compiler side, it needs to be also
-enabled on the runtime library side, otherwise the failures are still fatal.
-The runtime library defaults to @code{halt_on_error=0} for
-ThreadSanitizer and UndefinedBehaviorSanitizer, while default value for
-AddressSanitizer is @code{halt_on_error=1}. This can be overridden through
-setting the @code{halt_on_error} flag in the corresponding environment variable.
-
-Syntax without an explicit @var{opts} parameter is deprecated. It is
-equivalent to specifying an @var{opts} list of:
-
-@smallexample
-undefined,float-cast-overflow,float-divide-by-zero,bounds-strict
-@end smallexample
-
-@item -fsanitize-address-use-after-scope
-@opindex fsanitize-address-use-after-scope
-Enable sanitization of local variables to detect use-after-scope bugs.
-The option sets @option{-fstack-reuse} to @samp{none}.
-
-@item -fsanitize-trap@r{[}=@var{opts}@r{]}
-@opindex fsanitize-trap
-@opindex fno-sanitize-trap
-The @option{-fsanitize-trap=} option instructs the compiler to
-report for sanitizers mentioned in comma-separated list of @var{opts}
-undefined behavior using @code{__builtin_trap} rather than a @code{libubsan}
-library routine. If this option is enabled for certain sanitizer,
-it takes precedence over the @option{-fsanitizer-recover=} for that
-sanitizer, @code{__builtin_trap} will be emitted and be fatal regardless
-of whether recovery is enabled or disabled using @option{-fsanitize-recover=}.
-
-The advantage of this is that the @code{libubsan} library is not needed
-and is not linked in, so this is usable even in freestanding environments.
-
-Currently this feature works with @option{-fsanitize=undefined} (and its suboptions
-except for @option{-fsanitize=vptr}), @option{-fsanitize=float-cast-overflow},
-@option{-fsanitize=float-divide-by-zero} and
-@option{-fsanitize=bounds-strict}. @code{-fsanitize-trap=all} can be also
-specified, which enables it for @code{undefined} suboptions,
-@option{-fsanitize=float-cast-overflow},
-@option{-fsanitize=float-divide-by-zero} and
-@option{-fsanitize=bounds-strict}.
-If @code{-fsanitize-trap=undefined} or @code{-fsanitize-trap=all} is used
-and @code{-fsanitize=vptr} is enabled on the command line, the
-instrumentation is silently ignored as the instrumentation always needs
-@code{libubsan} support, @option{-fsanitize-trap=vptr} is not allowed.
-
-@item -fsanitize-undefined-trap-on-error
-@opindex fsanitize-undefined-trap-on-error
-The @option{-fsanitize-undefined-trap-on-error} option is deprecated
-equivalent of @option{-fsanitize-trap=all}.
-
-@item -fsanitize-coverage=trace-pc
-@opindex fsanitize-coverage=trace-pc
-Enable coverage-guided fuzzing code instrumentation.
-Inserts a call to @code{__sanitizer_cov_trace_pc} into every basic block.
-
-@item -fsanitize-coverage=trace-cmp
-@opindex fsanitize-coverage=trace-cmp
-Enable dataflow guided fuzzing code instrumentation.
-Inserts a call to @code{__sanitizer_cov_trace_cmp1},
-@code{__sanitizer_cov_trace_cmp2}, @code{__sanitizer_cov_trace_cmp4} or
-@code{__sanitizer_cov_trace_cmp8} for integral comparison with both operands
-variable or @code{__sanitizer_cov_trace_const_cmp1},
-@code{__sanitizer_cov_trace_const_cmp2},
-@code{__sanitizer_cov_trace_const_cmp4} or
-@code{__sanitizer_cov_trace_const_cmp8} for integral comparison with one
-operand constant, @code{__sanitizer_cov_trace_cmpf} or
-@code{__sanitizer_cov_trace_cmpd} for float or double comparisons and
-@code{__sanitizer_cov_trace_switch} for switch statements.
-
-@item -fcf-protection=@r{[}full@r{|}branch@r{|}return@r{|}none@r{|}check@r{]}
-@opindex fcf-protection
-Enable code instrumentation of control-flow transfers to increase
-program security by checking that target addresses of control-flow
-transfer instructions (such as indirect function call, function return,
-indirect jump) are valid. This prevents diverting the flow of control
-to an unexpected target. This is intended to protect against such
-threats as Return-oriented Programming (ROP), and similarly
-call/jmp-oriented programming (COP/JOP).
-
-The value @code{branch} tells the compiler to implement checking of
-validity of control-flow transfer at the point of indirect branch
-instructions, i.e.@: call/jmp instructions. The value @code{return}
-implements checking of validity at the point of returning from a
-function. The value @code{full} is an alias for specifying both
-@code{branch} and @code{return}. The value @code{none} turns off
-instrumentation.
-
-The value @code{check} is used for the final link with link-time
-optimization (LTO). An error is issued if LTO object files are
-compiled with different @option{-fcf-protection} values. The
-value @code{check} is ignored at the compile time.
-
-The macro @code{__CET__} is defined when @option{-fcf-protection} is
-used. The first bit of @code{__CET__} is set to 1 for the value
-@code{branch} and the second bit of @code{__CET__} is set to 1 for
-the @code{return}.
-
-You can also use the @code{nocf_check} attribute to identify
-which functions and calls should be skipped from instrumentation
-(@pxref{Function Attributes}).
-
-Currently the x86 GNU/Linux target provides an implementation based
-on Intel Control-flow Enforcement Technology (CET) which works for
-i686 processor or newer.
-
-@item -fharden-compares
-@opindex fharden-compares
-For every logical test that survives gimple optimizations and is
-@emph{not} the condition in a conditional branch (for example,
-conditions tested for conditional moves, or to store in boolean
-variables), emit extra code to compute and verify the reversed
-condition, and to call @code{__builtin_trap} if the results do not
-match. Use with @samp{-fharden-conditional-branches} to cover all
-conditionals.
-
-@item -fharden-conditional-branches
-@opindex fharden-conditional-branches
-For every non-vectorized conditional branch that survives gimple
-optimizations, emit extra code to compute and verify the reversed
-condition, and to call @code{__builtin_trap} if the result is
-unexpected. Use with @samp{-fharden-compares} to cover all
-conditionals.
-
-@item -fstack-protector
-@opindex fstack-protector
-Emit extra code to check for buffer overflows, such as stack smashing
-attacks. This is done by adding a guard variable to functions with
-vulnerable objects. This includes functions that call @code{alloca}, and
-functions with buffers larger than or equal to 8 bytes. The guards are
-initialized when a function is entered and then checked when the function
-exits. If a guard check fails, an error message is printed and the program
-exits. Only variables that are actually allocated on the stack are
-considered, optimized away variables or variables allocated in registers
-don't count.
-
-@item -fstack-protector-all
-@opindex fstack-protector-all
-Like @option{-fstack-protector} except that all functions are protected.
-
-@item -fstack-protector-strong
-@opindex fstack-protector-strong
-Like @option{-fstack-protector} but includes additional functions to
-be protected --- those that have local array definitions, or have
-references to local frame addresses. Only variables that are actually
-allocated on the stack are considered, optimized away variables or variables
-allocated in registers don't count.
-
-@item -fstack-protector-explicit
-@opindex fstack-protector-explicit
-Like @option{-fstack-protector} but only protects those functions which
-have the @code{stack_protect} attribute.
-
-@item -fstack-check
-@opindex fstack-check
-Generate code to verify that you do not go beyond the boundary of the
-stack. You should specify this flag if you are running in an
-environment with multiple threads, but you only rarely need to specify it in
-a single-threaded environment since stack overflow is automatically
-detected on nearly all systems if there is only one stack.
-
-Note that this switch does not actually cause checking to be done; the
-operating system or the language runtime must do that. The switch causes
-generation of code to ensure that they see the stack being extended.
-
-You can additionally specify a string parameter: @samp{no} means no
-checking, @samp{generic} means force the use of old-style checking,
-@samp{specific} means use the best checking method and is equivalent
-to bare @option{-fstack-check}.
-
-Old-style checking is a generic mechanism that requires no specific
-target support in the compiler but comes with the following drawbacks:
-
-@enumerate
-@item
-Modified allocation strategy for large objects: they are always
-allocated dynamically if their size exceeds a fixed threshold. Note this
-may change the semantics of some code.
-
-@item
-Fixed limit on the size of the static frame of functions: when it is
-topped by a particular function, stack checking is not reliable and
-a warning is issued by the compiler.
-
-@item
-Inefficiency: because of both the modified allocation strategy and the
-generic implementation, code performance is hampered.
-@end enumerate
-
-Note that old-style stack checking is also the fallback method for
-@samp{specific} if no target support has been added in the compiler.
-
-@samp{-fstack-check=} is designed for Ada's needs to detect infinite recursion
-and stack overflows. @samp{specific} is an excellent choice when compiling
-Ada code. It is not generally sufficient to protect against stack-clash
-attacks. To protect against those you want @samp{-fstack-clash-protection}.
-
-@item -fstack-clash-protection
-@opindex fstack-clash-protection
-Generate code to prevent stack clash style attacks. When this option is
-enabled, the compiler will only allocate one page of stack space at a time
-and each page is accessed immediately after allocation. Thus, it prevents
-allocations from jumping over any stack guard page provided by the
-operating system.
-
-Most targets do not fully support stack clash protection. However, on
-those targets @option{-fstack-clash-protection} will protect dynamic stack
-allocations. @option{-fstack-clash-protection} may also provide limited
-protection for static stack allocations if the target supports
-@option{-fstack-check=specific}.
-
-@item -fstack-limit-register=@var{reg}
-@itemx -fstack-limit-symbol=@var{sym}
-@itemx -fno-stack-limit
-@opindex fstack-limit-register
-@opindex fstack-limit-symbol
-@opindex fno-stack-limit
-Generate code to ensure that the stack does not grow beyond a certain value,
-either the value of a register or the address of a symbol. If a larger
-stack is required, a signal is raised at run time. For most targets,
-the signal is raised before the stack overruns the boundary, so
-it is possible to catch the signal without taking special precautions.
-
-For instance, if the stack starts at absolute address @samp{0x80000000}
-and grows downwards, you can use the flags
-@option{-fstack-limit-symbol=__stack_limit} and
-@option{-Wl,--defsym,__stack_limit=0x7ffe0000} to enforce a stack limit
-of 128KB@. Note that this may only work with the GNU linker.
-
-You can locally override stack limit checking by using the
-@code{no_stack_limit} function attribute (@pxref{Function Attributes}).
-
-@item -fsplit-stack
-@opindex fsplit-stack
-Generate code to automatically split the stack before it overflows.
-The resulting program has a discontiguous stack which can only
-overflow if the program is unable to allocate any more memory. This
-is most useful when running threaded programs, as it is no longer
-necessary to calculate a good stack size to use for each thread. This
-is currently only implemented for the x86 targets running
-GNU/Linux.
-
-When code compiled with @option{-fsplit-stack} calls code compiled
-without @option{-fsplit-stack}, there may not be much stack space
-available for the latter code to run. If compiling all code,
-including library code, with @option{-fsplit-stack} is not an option,
-then the linker can fix up these calls so that the code compiled
-without @option{-fsplit-stack} always has a large stack. Support for
-this is implemented in the gold linker in GNU binutils release 2.21
-and later.
-
-@item -fvtable-verify=@r{[}std@r{|}preinit@r{|}none@r{]}
-@opindex fvtable-verify
-This option is only available when compiling C++ code.
-It turns on (or off, if using @option{-fvtable-verify=none}) the security
-feature that verifies at run time, for every virtual call, that
-the vtable pointer through which the call is made is valid for the type of
-the object, and has not been corrupted or overwritten. If an invalid vtable
-pointer is detected at run time, an error is reported and execution of the
-program is immediately halted.
-
-This option causes run-time data structures to be built at program startup,
-which are used for verifying the vtable pointers.
-The options @samp{std} and @samp{preinit}
-control the timing of when these data structures are built. In both cases the
-data structures are built before execution reaches @code{main}. Using
-@option{-fvtable-verify=std} causes the data structures to be built after
-shared libraries have been loaded and initialized.
-@option{-fvtable-verify=preinit} causes them to be built before shared
-libraries have been loaded and initialized.
-
-If this option appears multiple times in the command line with different
-values specified, @samp{none} takes highest priority over both @samp{std} and
-@samp{preinit}; @samp{preinit} takes priority over @samp{std}.
-
-@item -fvtv-debug
-@opindex fvtv-debug
-When used in conjunction with @option{-fvtable-verify=std} or
-@option{-fvtable-verify=preinit}, causes debug versions of the
-runtime functions for the vtable verification feature to be called.
-This flag also causes the compiler to log information about which
-vtable pointers it finds for each class.
-This information is written to a file named @file{vtv_set_ptr_data.log}
-in the directory named by the environment variable @env{VTV_LOGS_DIR}
-if that is defined or the current working directory otherwise.
-
-Note: This feature @emph{appends} data to the log file. If you want a fresh log
-file, be sure to delete any existing one.
-
-@item -fvtv-counts
-@opindex fvtv-counts
-This is a debugging flag. When used in conjunction with
-@option{-fvtable-verify=std} or @option{-fvtable-verify=preinit}, this
-causes the compiler to keep track of the total number of virtual calls
-it encounters and the number of verifications it inserts. It also
-counts the number of calls to certain run-time library functions
-that it inserts and logs this information for each compilation unit.
-The compiler writes this information to a file named
-@file{vtv_count_data.log} in the directory named by the environment
-variable @env{VTV_LOGS_DIR} if that is defined or the current working
-directory otherwise. It also counts the size of the vtable pointer sets
-for each class, and writes this information to @file{vtv_class_set_sizes.log}
-in the same directory.
-
-Note: This feature @emph{appends} data to the log files. To get fresh log
-files, be sure to delete any existing ones.
-
-@item -finstrument-functions
-@opindex finstrument-functions
-Generate instrumentation calls for entry and exit to functions. Just
-after function entry and just before function exit, the following
-profiling functions are called with the address of the current
-function and its call site. (On some platforms,
-@code{__builtin_return_address} does not work beyond the current
-function, so the call site information may not be available to the
-profiling functions otherwise.)
-
-@smallexample
-void __cyg_profile_func_enter (void *this_fn,
- void *call_site);
-void __cyg_profile_func_exit (void *this_fn,
- void *call_site);
-@end smallexample
-
-The first argument is the address of the start of the current function,
-which may be looked up exactly in the symbol table.
-
-This instrumentation is also done for functions expanded inline in other
-functions. The profiling calls indicate where, conceptually, the
-inline function is entered and exited. This means that addressable
-versions of such functions must be available. If all your uses of a
-function are expanded inline, this may mean an additional expansion of
-code size. If you use @code{extern inline} in your C code, an
-addressable version of such functions must be provided. (This is
-normally the case anyway, but if you get lucky and the optimizer always
-expands the functions inline, you might have gotten away without
-providing static copies.)
-
-A function may be given the attribute @code{no_instrument_function}, in
-which case this instrumentation is not done. This can be used, for
-example, for the profiling functions listed above, high-priority
-interrupt routines, and any functions from which the profiling functions
-cannot safely be called (perhaps signal handlers, if the profiling
-routines generate output or allocate memory).
-@xref{Common Function Attributes}.
-
-@item -finstrument-functions-once
-@opindex -finstrument-functions-once
-This is similar to @option{-finstrument-functions}, but the profiling
-functions are called only once per instrumented function, i.e. the first
-profiling function is called after the first entry into the instrumented
-function and the second profiling function is called before the exit
-corresponding to this first entry.
-
-The definition of @code{once} for the purpose of this option is a little
-vague because the implementation is not protected against data races.
-As a result, the implementation only guarantees that the profiling
-functions are called at @emph{least} once per process and at @emph{most}
-once per thread, but the calls are always paired, that is to say, if a
-thread calls the first function, then it will call the second function,
-unless it never reaches the exit of the instrumented function.
-
-@item -finstrument-functions-exclude-file-list=@var{file},@var{file},@dots{}
-@opindex finstrument-functions-exclude-file-list
-
-Set the list of functions that are excluded from instrumentation (see
-the description of @option{-finstrument-functions}). If the file that
-contains a function definition matches with one of @var{file}, then
-that function is not instrumented. The match is done on substrings:
-if the @var{file} parameter is a substring of the file name, it is
-considered to be a match.
-
-For example:
-
-@smallexample
--finstrument-functions-exclude-file-list=/bits/stl,include/sys
-@end smallexample
-
-@noindent
-excludes any inline function defined in files whose pathnames
-contain @file{/bits/stl} or @file{include/sys}.
-
-If, for some reason, you want to include letter @samp{,} in one of
-@var{sym}, write @samp{\,}. For example,
-@option{-finstrument-functions-exclude-file-list='\,\,tmp'}
-(note the single quote surrounding the option).
-
-@item -finstrument-functions-exclude-function-list=@var{sym},@var{sym},@dots{}
-@opindex finstrument-functions-exclude-function-list
-
-This is similar to @option{-finstrument-functions-exclude-file-list},
-but this option sets the list of function names to be excluded from
-instrumentation. The function name to be matched is its user-visible
-name, such as @code{vector<int> blah(const vector<int> &)}, not the
-internal mangled name (e.g., @code{_Z4blahRSt6vectorIiSaIiEE}). The
-match is done on substrings: if the @var{sym} parameter is a substring
-of the function name, it is considered to be a match. For C99 and C++
-extended identifiers, the function name must be given in UTF-8, not
-using universal character names.
-
-@item -fpatchable-function-entry=@var{N}[,@var{M}]
-@opindex fpatchable-function-entry
-Generate @var{N} NOPs right at the beginning
-of each function, with the function entry point before the @var{M}th NOP.
-If @var{M} is omitted, it defaults to @code{0} so the
-function entry points to the address just at the first NOP.
-The NOP instructions reserve extra space which can be used to patch in
-any desired instrumentation at run time, provided that the code segment
-is writable. The amount of space is controllable indirectly via
-the number of NOPs; the NOP instruction used corresponds to the instruction
-emitted by the internal GCC back-end interface @code{gen_nop}. This behavior
-is target-specific and may also depend on the architecture variant and/or
-other compilation options.
-
-For run-time identification, the starting addresses of these areas,
-which correspond to their respective function entries minus @var{M},
-are additionally collected in the @code{__patchable_function_entries}
-section of the resulting binary.
-
-Note that the value of @code{__attribute__ ((patchable_function_entry
-(N,M)))} takes precedence over command-line option
-@option{-fpatchable-function-entry=N,M}. This can be used to increase
-the area size or to remove it completely on a single function.
-If @code{N=0}, no pad location is recorded.
-
-The NOP instructions are inserted at---and maybe before, depending on
-@var{M}---the function entry address, even before the prologue. On
-PowerPC with the ELFv2 ABI, for a function with dual entry points,
-the local entry point is this function entry address.
-
-The maximum value of @var{N} and @var{M} is 65535. On PowerPC with the
-ELFv2 ABI, for a function with dual entry points, the supported values
-for @var{M} are 0, 2, 6 and 14.
-@end table
-
-
-@node Preprocessor Options
-@section Options Controlling the Preprocessor
-@cindex preprocessor options
-@cindex options, preprocessor
-
-These options control the C preprocessor, which is run on each C source
-file before actual compilation.
-
-If you use the @option{-E} option, nothing is done except preprocessing.
-Some of these options make sense only together with @option{-E} because
-they cause the preprocessor output to be unsuitable for actual
-compilation.
-
-In addition to the options listed here, there are a number of options
-to control search paths for include files documented in
-@ref{Directory Options}.
-Options to control preprocessor diagnostics are listed in
-@ref{Warning Options}.
-
-@table @gcctabopt
-@include cppopts.texi
-
-@item -Wp,@var{option}
-@opindex Wp
-You can use @option{-Wp,@var{option}} to bypass the compiler driver
-and pass @var{option} directly through to the preprocessor. If
-@var{option} contains commas, it is split into multiple options at the
-commas. However, many options are modified, translated or interpreted
-by the compiler driver before being passed to the preprocessor, and
-@option{-Wp} forcibly bypasses this phase. The preprocessor's direct
-interface is undocumented and subject to change, so whenever possible
-you should avoid using @option{-Wp} and let the driver handle the
-options instead.
-
-@item -Xpreprocessor @var{option}
-@opindex Xpreprocessor
-Pass @var{option} as an option to the preprocessor. You can use this to
-supply system-specific preprocessor options that GCC does not
-recognize.
-
-If you want to pass an option that takes an argument, you must use
-@option{-Xpreprocessor} twice, once for the option and once for the argument.
-
-@item -no-integrated-cpp
-@opindex no-integrated-cpp
-Perform preprocessing as a separate pass before compilation.
-By default, GCC performs preprocessing as an integrated part of
-input tokenization and parsing.
-If this option is provided, the appropriate language front end
-(@command{cc1}, @command{cc1plus}, or @command{cc1obj} for C, C++,
-and Objective-C, respectively) is instead invoked twice,
-once for preprocessing only and once for actual compilation
-of the preprocessed input.
-This option may be useful in conjunction with the @option{-B} or
-@option{-wrapper} options to specify an alternate preprocessor or
-perform additional processing of the program source between
-normal preprocessing and compilation.
-
-@item -flarge-source-files
-@opindex flarge-source-files
-Adjust GCC to expect large source files, at the expense of slower
-compilation and higher memory usage.
-
-Specifically, GCC normally tracks both column numbers and line numbers
-within source files and it normally prints both of these numbers in
-diagnostics. However, once it has processed a certain number of source
-lines, it stops tracking column numbers and only tracks line numbers.
-This means that diagnostics for later lines do not include column numbers.
-It also means that options like @option{-Wmisleading-indentation} cease to work
-at that point, although the compiler prints a note if this happens.
-Passing @option{-flarge-source-files} significantly increases the number
-of source lines that GCC can process before it stops tracking columns.
-
-@end table
-
-@node Assembler Options
-@section Passing Options to the Assembler
-
-@c prevent bad page break with this line
-You can pass options to the assembler.
-
-@table @gcctabopt
-@item -Wa,@var{option}
-@opindex Wa
-Pass @var{option} as an option to the assembler. If @var{option}
-contains commas, it is split into multiple options at the commas.
-
-@item -Xassembler @var{option}
-@opindex Xassembler
-Pass @var{option} as an option to the assembler. You can use this to
-supply system-specific assembler options that GCC does not
-recognize.
-
-If you want to pass an option that takes an argument, you must use
-@option{-Xassembler} twice, once for the option and once for the argument.
-
-@end table
-
-@node Link Options
-@section Options for Linking
-@cindex link options
-@cindex options, linking
-
-These options come into play when the compiler links object files into
-an executable output file. They are meaningless if the compiler is
-not doing a link step.
-
-@table @gcctabopt
-@cindex file names
-@item @var{object-file-name}
-A file name that does not end in a special recognized suffix is
-considered to name an object file or library. (Object files are
-distinguished from libraries by the linker according to the file
-contents.) If linking is done, these object files are used as input
-to the linker.
-
-@item -c
-@itemx -S
-@itemx -E
-@opindex c
-@opindex S
-@opindex E
-If any of these options is used, then the linker is not run, and
-object file names should not be used as arguments. @xref{Overall
-Options}.
-
-@item -flinker-output=@var{type}
-@opindex flinker-output
-This option controls code generation of the link-time optimizer. By
-default the linker output is automatically determined by the linker
-plugin. For debugging the compiler and if incremental linking with a
-non-LTO object file is desired, it may be useful to control the type
-manually.
-
-If @var{type} is @samp{exec}, code generation produces a static
-binary. In this case @option{-fpic} and @option{-fpie} are both
-disabled.
-
-If @var{type} is @samp{dyn}, code generation produces a shared
-library. In this case @option{-fpic} or @option{-fPIC} is preserved,
-but not enabled automatically. This allows to build shared libraries
-without position-independent code on architectures where this is
-possible, i.e.@: on x86.
-
-If @var{type} is @samp{pie}, code generation produces an @option{-fpie}
-executable. This results in similar optimizations as @samp{exec}
-except that @option{-fpie} is not disabled if specified at compilation
-time.
-
-If @var{type} is @samp{rel}, the compiler assumes that incremental linking is
-done. The sections containing intermediate code for link-time optimization are
-merged, pre-optimized, and output to the resulting object file. In addition, if
-@option{-ffat-lto-objects} is specified, binary code is produced for future
-non-LTO linking. The object file produced by incremental linking is smaller
-than a static library produced from the same object files. At link time the
-result of incremental linking also loads faster than a static
-library assuming that the majority of objects in the library are used.
-
-Finally @samp{nolto-rel} configures the compiler for incremental linking where
-code generation is forced, a final binary is produced, and the intermediate
-code for later link-time optimization is stripped. When multiple object files
-are linked together the resulting code is better optimized than with
-link-time optimizations disabled (for example, cross-module inlining
-happens), but most of benefits of whole program optimizations are lost.
-
-During the incremental link (by @option{-r}) the linker plugin defaults to
-@option{rel}. With current interfaces to GNU Binutils it is however not
-possible to incrementally link LTO objects and non-LTO objects into a single
-mixed object file. If any of object files in incremental link cannot
-be used for link-time optimization, the linker plugin issues a warning and
-uses @samp{nolto-rel}. To maintain whole program optimization, it is
-recommended to link such objects into static library instead. Alternatively it
-is possible to use H.J. Lu's binutils with support for mixed objects.
-
-@item -fuse-ld=bfd
-@opindex fuse-ld=bfd
-Use the @command{bfd} linker instead of the default linker.
-
-@item -fuse-ld=gold
-@opindex fuse-ld=gold
-Use the @command{gold} linker instead of the default linker.
-
-@item -fuse-ld=lld
-@opindex fuse-ld=lld
-Use the LLVM @command{lld} linker instead of the default linker.
-
-@item -fuse-ld=mold
-@opindex fuse-ld=mold
-Use the Modern Linker (@command{mold}) instead of the default linker.
-
-@cindex Libraries
-@item -l@var{library}
-@itemx -l @var{library}
-@opindex l
-Search the library named @var{library} when linking. (The second
-alternative with the library as a separate argument is only for
-POSIX compliance and is not recommended.)
-
-The @option{-l} option is passed directly to the linker by GCC. Refer
-to your linker documentation for exact details. The general
-description below applies to the GNU linker.
-
-The linker searches a standard list of directories for the library.
-The directories searched include several standard system directories
-plus any that you specify with @option{-L}.
-
-Static libraries are archives of object files, and have file names
-like @file{lib@var{library}.a}. Some targets also support shared
-libraries, which typically have names like @file{lib@var{library}.so}.
-If both static and shared libraries are found, the linker gives
-preference to linking with the shared library unless the
-@option{-static} option is used.
-
-It makes a difference where in the command you write this option; the
-linker searches and processes libraries and object files in the order they
-are specified. Thus, @samp{foo.o -lz bar.o} searches library @samp{z}
-after file @file{foo.o} but before @file{bar.o}. If @file{bar.o} refers
-to functions in @samp{z}, those functions may not be loaded.
-
-@item -lobjc
-@opindex lobjc
-You need this special case of the @option{-l} option in order to
-link an Objective-C or Objective-C++ program.
-
-@item -nostartfiles
-@opindex nostartfiles
-Do not use the standard system startup files when linking.
-The standard system libraries are used normally, unless @option{-nostdlib},
-@option{-nolibc}, or @option{-nodefaultlibs} is used.
-
-@item -nodefaultlibs
-@opindex nodefaultlibs
-Do not use the standard system libraries when linking.
-Only the libraries you specify are passed to the linker, and options
-specifying linkage of the system libraries, such as @option{-static-libgcc}
-or @option{-shared-libgcc}, are ignored.
-The standard startup files are used normally, unless @option{-nostartfiles}
-is used.
-
-The compiler may generate calls to @code{memcmp},
-@code{memset}, @code{memcpy} and @code{memmove}.
-These entries are usually resolved by entries in
-libc. These entry points should be supplied through some other
-mechanism when this option is specified.
-
-@item -nolibc
-@opindex nolibc
-Do not use the C library or system libraries tightly coupled with it when
-linking. Still link with the startup files, @file{libgcc} or toolchain
-provided language support libraries such as @file{libgnat}, @file{libgfortran}
-or @file{libstdc++} unless options preventing their inclusion are used as
-well. This typically removes @option{-lc} from the link command line, as well
-as system libraries that normally go with it and become meaningless when
-absence of a C library is assumed, for example @option{-lpthread} or
-@option{-lm} in some configurations. This is intended for bare-board
-targets when there is indeed no C library available.
-
-@item -nostdlib
-@opindex nostdlib
-Do not use the standard system startup files or libraries when linking.
-No startup files and only the libraries you specify are passed to
-the linker, and options specifying linkage of the system libraries, such as
-@option{-static-libgcc} or @option{-shared-libgcc}, are ignored.
-
-The compiler may generate calls to @code{memcmp}, @code{memset},
-@code{memcpy} and @code{memmove}.
-These entries are usually resolved by entries in
-libc. These entry points should be supplied through some other
-mechanism when this option is specified.
-
-@cindex @option{-lgcc}, use with @option{-nostdlib}
-@cindex @option{-nostdlib} and unresolved references
-@cindex unresolved references and @option{-nostdlib}
-@cindex @option{-lgcc}, use with @option{-nodefaultlibs}
-@cindex @option{-nodefaultlibs} and unresolved references
-@cindex unresolved references and @option{-nodefaultlibs}
-One of the standard libraries bypassed by @option{-nostdlib} and
-@option{-nodefaultlibs} is @file{libgcc.a}, a library of internal subroutines
-which GCC uses to overcome shortcomings of particular machines, or special
-needs for some languages.
-(@xref{Interface,,Interfacing to GCC Output,gccint,GNU Compiler
-Collection (GCC) Internals},
-for more discussion of @file{libgcc.a}.)
-In most cases, you need @file{libgcc.a} even when you want to avoid
-other standard libraries. In other words, when you specify @option{-nostdlib}
-or @option{-nodefaultlibs} you should usually specify @option{-lgcc} as well.
-This ensures that you have no unresolved references to internal GCC
-library subroutines.
-(An example of such an internal subroutine is @code{__main}, used to ensure C++
-constructors are called; @pxref{Collect2,,@code{collect2}, gccint,
-GNU Compiler Collection (GCC) Internals}.)
-
-@item -nostdlib++
-@opindex nostdlib++
-Do not implicitly link with standard C++ libraries.
-
-@item -e @var{entry}
-@itemx --entry=@var{entry}
-@opindex e
-@opindex entry
-
-Specify that the program entry point is @var{entry}. The argument is
-interpreted by the linker; the GNU linker accepts either a symbol name
-or an address.
-
-@item -pie
-@opindex pie
-Produce a dynamically linked position independent executable on targets
-that support it. For predictable results, you must also specify the same
-set of options used for compilation (@option{-fpie}, @option{-fPIE},
-or model suboptions) when you specify this linker option.
-
-@item -no-pie
-@opindex no-pie
-Don't produce a dynamically linked position independent executable.
-
-@item -static-pie
-@opindex static-pie
-Produce a static position independent executable on targets that support
-it. A static position independent executable is similar to a static
-executable, but can be loaded at any address without a dynamic linker.
-For predictable results, you must also specify the same set of options
-used for compilation (@option{-fpie}, @option{-fPIE}, or model
-suboptions) when you specify this linker option.
-
-@item -pthread
-@opindex pthread
-Link with the POSIX threads library. This option is supported on
-GNU/Linux targets, most other Unix derivatives, and also on
-x86 Cygwin and MinGW targets. On some targets this option also sets
-flags for the preprocessor, so it should be used consistently for both
-compilation and linking.
-
-@item -r
-@opindex r
-Produce a relocatable object as output. This is also known as partial
-linking.
-
-@item -rdynamic
-@opindex rdynamic
-Pass the flag @option{-export-dynamic} to the ELF linker, on targets
-that support it. This instructs the linker to add all symbols, not
-only used ones, to the dynamic symbol table. This option is needed
-for some uses of @code{dlopen} or to allow obtaining backtraces
-from within a program.
-
-@item -s
-@opindex s
-Remove all symbol table and relocation information from the executable.
-
-@item -static
-@opindex static
-On systems that support dynamic linking, this overrides @option{-pie}
-and prevents linking with the shared libraries. On other systems, this
-option has no effect.
-
-@item -shared
-@opindex shared
-Produce a shared object which can then be linked with other objects to
-form an executable. Not all systems support this option. For predictable
-results, you must also specify the same set of options used for compilation
-(@option{-fpic}, @option{-fPIC}, or model suboptions) when
-you specify this linker option.@footnote{On some systems, @samp{gcc -shared}
-needs to build supplementary stub code for constructors to work. On
-multi-libbed systems, @samp{gcc -shared} must select the correct support
-libraries to link against. Failing to supply the correct flags may lead
-to subtle defects. Supplying them in cases where they are not necessary
-is innocuous.}
-
-@item -shared-libgcc
-@itemx -static-libgcc
-@opindex shared-libgcc
-@opindex static-libgcc
-On systems that provide @file{libgcc} as a shared library, these options
-force the use of either the shared or static version, respectively.
-If no shared version of @file{libgcc} was built when the compiler was
-configured, these options have no effect.
-
-There are several situations in which an application should use the
-shared @file{libgcc} instead of the static version. The most common
-of these is when the application wishes to throw and catch exceptions
-across different shared libraries. In that case, each of the libraries
-as well as the application itself should use the shared @file{libgcc}.
-
-Therefore, the G++ driver automatically adds @option{-shared-libgcc}
-whenever you build a shared library or a main executable, because C++
-programs typically use exceptions, so this is the right thing to do.
-
-If, instead, you use the GCC driver to create shared libraries, you may
-find that they are not always linked with the shared @file{libgcc}.
-If GCC finds, at its configuration time, that you have a non-GNU linker
-or a GNU linker that does not support option @option{--eh-frame-hdr},
-it links the shared version of @file{libgcc} into shared libraries
-by default. Otherwise, it takes advantage of the linker and optimizes
-away the linking with the shared version of @file{libgcc}, linking with
-the static version of libgcc by default. This allows exceptions to
-propagate through such shared libraries, without incurring relocation
-costs at library load time.
-
-However, if a library or main executable is supposed to throw or catch
-exceptions, you must link it using the G++ driver, or using the option
-@option{-shared-libgcc}, such that it is linked with the shared
-@file{libgcc}.
-
-@item -static-libasan
-@opindex static-libasan
-When the @option{-fsanitize=address} option is used to link a program,
-the GCC driver automatically links against @option{libasan}. If
-@file{libasan} is available as a shared library, and the @option{-static}
-option is not used, then this links against the shared version of
-@file{libasan}. The @option{-static-libasan} option directs the GCC
-driver to link @file{libasan} statically, without necessarily linking
-other libraries statically.
-
-@item -static-libtsan
-@opindex static-libtsan
-When the @option{-fsanitize=thread} option is used to link a program,
-the GCC driver automatically links against @option{libtsan}. If
-@file{libtsan} is available as a shared library, and the @option{-static}
-option is not used, then this links against the shared version of
-@file{libtsan}. The @option{-static-libtsan} option directs the GCC
-driver to link @file{libtsan} statically, without necessarily linking
-other libraries statically.
-
-@item -static-liblsan
-@opindex static-liblsan
-When the @option{-fsanitize=leak} option is used to link a program,
-the GCC driver automatically links against @option{liblsan}. If
-@file{liblsan} is available as a shared library, and the @option{-static}
-option is not used, then this links against the shared version of
-@file{liblsan}. The @option{-static-liblsan} option directs the GCC
-driver to link @file{liblsan} statically, without necessarily linking
-other libraries statically.
-
-@item -static-libubsan
-@opindex static-libubsan
-When the @option{-fsanitize=undefined} option is used to link a program,
-the GCC driver automatically links against @option{libubsan}. If
-@file{libubsan} is available as a shared library, and the @option{-static}
-option is not used, then this links against the shared version of
-@file{libubsan}. The @option{-static-libubsan} option directs the GCC
-driver to link @file{libubsan} statically, without necessarily linking
-other libraries statically.
-
-@item -static-libstdc++
-@opindex static-libstdc++
-When the @command{g++} program is used to link a C++ program, it
-normally automatically links against @option{libstdc++}. If
-@file{libstdc++} is available as a shared library, and the
-@option{-static} option is not used, then this links against the
-shared version of @file{libstdc++}. That is normally fine. However, it
-is sometimes useful to freeze the version of @file{libstdc++} used by
-the program without going all the way to a fully static link. The
-@option{-static-libstdc++} option directs the @command{g++} driver to
-link @file{libstdc++} statically, without necessarily linking other
-libraries statically.
-
-@item -symbolic
-@opindex symbolic
-Bind references to global symbols when building a shared object. Warn
-about any unresolved references (unless overridden by the link editor
-option @option{-Xlinker -z -Xlinker defs}). Only a few systems support
-this option.
-
-@item -T @var{script}
-@opindex T
-@cindex linker script
-Use @var{script} as the linker script. This option is supported by most
-systems using the GNU linker. On some targets, such as bare-board
-targets without an operating system, the @option{-T} option may be required
-when linking to avoid references to undefined symbols.
-
-@item -Xlinker @var{option}
-@opindex Xlinker
-Pass @var{option} as an option to the linker. You can use this to
-supply system-specific linker options that GCC does not recognize.
-
-If you want to pass an option that takes a separate argument, you must use
-@option{-Xlinker} twice, once for the option and once for the argument.
-For example, to pass @option{-assert definitions}, you must write
-@option{-Xlinker -assert -Xlinker definitions}. It does not work to write
-@option{-Xlinker "-assert definitions"}, because this passes the entire
-string as a single argument, which is not what the linker expects.
-
-When using the GNU linker, it is usually more convenient to pass
-arguments to linker options using the @option{@var{option}=@var{value}}
-syntax than as separate arguments. For example, you can specify
-@option{-Xlinker -Map=output.map} rather than
-@option{-Xlinker -Map -Xlinker output.map}. Other linkers may not support
-this syntax for command-line options.
-
-@item -Wl,@var{option}
-@opindex Wl
-Pass @var{option} as an option to the linker. If @var{option} contains
-commas, it is split into multiple options at the commas. You can use this
-syntax to pass an argument to the option.
-For example, @option{-Wl,-Map,output.map} passes @option{-Map output.map} to the
-linker. When using the GNU linker, you can also get the same effect with
-@option{-Wl,-Map=output.map}.
-
-@item -u @var{symbol}
-@opindex u
-Pretend the symbol @var{symbol} is undefined, to force linking of
-library modules to define it. You can use @option{-u} multiple times with
-different symbols to force loading of additional library modules.
-
-@item -z @var{keyword}
-@opindex z
-@option{-z} is passed directly on to the linker along with the keyword
-@var{keyword}. See the section in the documentation of your linker for
-permitted values and their meanings.
-@end table
-
-@node Directory Options
-@section Options for Directory Search
-@cindex directory options
-@cindex options, directory search
-@cindex search path
-
-These options specify directories to search for header files, for
-libraries and for parts of the compiler:
-
-@table @gcctabopt
-@include cppdiropts.texi
-
-@item -iplugindir=@var{dir}
-@opindex iplugindir=
-Set the directory to search for plugins that are passed
-by @option{-fplugin=@var{name}} instead of
-@option{-fplugin=@var{path}/@var{name}.so}. This option is not meant
-to be used by the user, but only passed by the driver.
-
-@item -L@var{dir}
-@opindex L
-Add directory @var{dir} to the list of directories to be searched
-for @option{-l}.
-
-@item -B@var{prefix}
-@opindex B
-This option specifies where to find the executables, libraries,
-include files, and data files of the compiler itself.
-
-The compiler driver program runs one or more of the subprograms
-@command{cpp}, @command{cc1}, @command{as} and @command{ld}. It tries
-@var{prefix} as a prefix for each program it tries to run, both with and
-without @samp{@var{machine}/@var{version}/} for the corresponding target
-machine and compiler version.
-
-For each subprogram to be run, the compiler driver first tries the
-@option{-B} prefix, if any. If that name is not found, or if @option{-B}
-is not specified, the driver tries two standard prefixes,
-@file{/usr/lib/gcc/} and @file{/usr/local/lib/gcc/}. If neither of
-those results in a file name that is found, the unmodified program
-name is searched for using the directories specified in your
-@env{PATH} environment variable.
-
-The compiler checks to see if the path provided by @option{-B}
-refers to a directory, and if necessary it adds a directory
-separator character at the end of the path.
-
-@option{-B} prefixes that effectively specify directory names also apply
-to libraries in the linker, because the compiler translates these
-options into @option{-L} options for the linker. They also apply to
-include files in the preprocessor, because the compiler translates these
-options into @option{-isystem} options for the preprocessor. In this case,
-the compiler appends @samp{include} to the prefix.
-
-The runtime support file @file{libgcc.a} can also be searched for using
-the @option{-B} prefix, if needed. If it is not found there, the two
-standard prefixes above are tried, and that is all. The file is left
-out of the link if it is not found by those means.
-
-Another way to specify a prefix much like the @option{-B} prefix is to use
-the environment variable @env{GCC_EXEC_PREFIX}. @xref{Environment
-Variables}.
-
-As a special kludge, if the path provided by @option{-B} is
-@file{[dir/]stage@var{N}/}, where @var{N} is a number in the range 0 to
-9, then it is replaced by @file{[dir/]include}. This is to help
-with boot-strapping the compiler.
-
-@item -no-canonical-prefixes
-@opindex no-canonical-prefixes
-Do not expand any symbolic links, resolve references to @samp{/../}
-or @samp{/./}, or make the path absolute when generating a relative
-prefix.
-
-@item --sysroot=@var{dir}
-@opindex sysroot
-Use @var{dir} as the logical root directory for headers and libraries.
-For example, if the compiler normally searches for headers in
-@file{/usr/include} and libraries in @file{/usr/lib}, it instead
-searches @file{@var{dir}/usr/include} and @file{@var{dir}/usr/lib}.
-
-If you use both this option and the @option{-isysroot} option, then
-the @option{--sysroot} option applies to libraries, but the
-@option{-isysroot} option applies to header files.
-
-The GNU linker (beginning with version 2.16) has the necessary support
-for this option. If your linker does not support this option, the
-header file aspect of @option{--sysroot} still works, but the
-library aspect does not.
-
-@item --no-sysroot-suffix
-@opindex no-sysroot-suffix
-For some targets, a suffix is added to the root directory specified
-with @option{--sysroot}, depending on the other options used, so that
-headers may for example be found in
-@file{@var{dir}/@var{suffix}/usr/include} instead of
-@file{@var{dir}/usr/include}. This option disables the addition of
-such a suffix.
-
-@end table
-
-@node Code Gen Options
-@section Options for Code Generation Conventions
-@cindex code generation conventions
-@cindex options, code generation
-@cindex run-time options
-
-These machine-independent options control the interface conventions
-used in code generation.
-
-Most of them have both positive and negative forms; the negative form
-of @option{-ffoo} is @option{-fno-foo}. In the table below, only
-one of the forms is listed---the one that is not the default. You
-can figure out the other form by either removing @samp{no-} or adding
-it.
-
-@table @gcctabopt
-@item -fstack-reuse=@var{reuse-level}
-@opindex fstack_reuse
-This option controls stack space reuse for user declared local/auto variables
-and compiler generated temporaries. @var{reuse_level} can be @samp{all},
-@samp{named_vars}, or @samp{none}. @samp{all} enables stack reuse for all
-local variables and temporaries, @samp{named_vars} enables the reuse only for
-user defined local variables with names, and @samp{none} disables stack reuse
-completely. The default value is @samp{all}. The option is needed when the
-program extends the lifetime of a scoped local variable or a compiler generated
-temporary beyond the end point defined by the language. When a lifetime of
-a variable ends, and if the variable lives in memory, the optimizing compiler
-has the freedom to reuse its stack space with other temporaries or scoped
-local variables whose live range does not overlap with it. Legacy code extending
-local lifetime is likely to break with the stack reuse optimization.
-
-For example,
-
-@smallexample
- int *p;
- @{
- int local1;
-
- p = &local1;
- local1 = 10;
- ....
- @}
- @{
- int local2;
- local2 = 20;
- ...
- @}
-
- if (*p == 10) // out of scope use of local1
- @{
-
- @}
-@end smallexample
-
-Another example:
-@smallexample
-
- struct A
- @{
- A(int k) : i(k), j(k) @{ @}
- int i;
- int j;
- @};
-
- A *ap;
-
- void foo(const A& ar)
- @{
- ap = &ar;
- @}
-
- void bar()
- @{
- foo(A(10)); // temp object's lifetime ends when foo returns
-
- @{
- A a(20);
- ....
- @}
- ap->i+= 10; // ap references out of scope temp whose space
- // is reused with a. What is the value of ap->i?
- @}
-
-@end smallexample
-
-The lifetime of a compiler generated temporary is well defined by the C++
-standard. When a lifetime of a temporary ends, and if the temporary lives
-in memory, the optimizing compiler has the freedom to reuse its stack
-space with other temporaries or scoped local variables whose live range
-does not overlap with it. However some of the legacy code relies on
-the behavior of older compilers in which temporaries' stack space is
-not reused, the aggressive stack reuse can lead to runtime errors. This
-option is used to control the temporary stack reuse optimization.
-
-@item -ftrapv
-@opindex ftrapv
-This option generates traps for signed overflow on addition, subtraction,
-multiplication operations.
-The options @option{-ftrapv} and @option{-fwrapv} override each other, so using
-@option{-ftrapv} @option{-fwrapv} on the command-line results in
-@option{-fwrapv} being effective. Note that only active options override, so
-using @option{-ftrapv} @option{-fwrapv} @option{-fno-wrapv} on the command-line
-results in @option{-ftrapv} being effective.
-
-@item -fwrapv
-@opindex fwrapv
-This option instructs the compiler to assume that signed arithmetic
-overflow of addition, subtraction and multiplication wraps around
-using twos-complement representation. This flag enables some optimizations
-and disables others.
-The options @option{-ftrapv} and @option{-fwrapv} override each other, so using
-@option{-ftrapv} @option{-fwrapv} on the command-line results in
-@option{-fwrapv} being effective. Note that only active options override, so
-using @option{-ftrapv} @option{-fwrapv} @option{-fno-wrapv} on the command-line
-results in @option{-ftrapv} being effective.
-
-@item -fwrapv-pointer
-@opindex fwrapv-pointer
-This option instructs the compiler to assume that pointer arithmetic
-overflow on addition and subtraction wraps around using twos-complement
-representation. This flag disables some optimizations which assume
-pointer overflow is invalid.
-
-@item -fstrict-overflow
-@opindex fstrict-overflow
-This option implies @option{-fno-wrapv} @option{-fno-wrapv-pointer} and when
-negated implies @option{-fwrapv} @option{-fwrapv-pointer}.
-
-@item -fexceptions
-@opindex fexceptions
-Enable exception handling. Generates extra code needed to propagate
-exceptions. For some targets, this implies GCC generates frame
-unwind information for all functions, which can produce significant data
-size overhead, although it does not affect execution. If you do not
-specify this option, GCC enables it by default for languages like
-C++ that normally require exception handling, and disables it for
-languages like C that do not normally require it. However, you may need
-to enable this option when compiling C code that needs to interoperate
-properly with exception handlers written in C++. You may also wish to
-disable this option if you are compiling older C++ programs that don't
-use exception handling.
-
-@item -fnon-call-exceptions
-@opindex fnon-call-exceptions
-Generate code that allows trapping instructions to throw exceptions.
-Note that this requires platform-specific runtime support that does
-not exist everywhere. Moreover, it only allows @emph{trapping}
-instructions to throw exceptions, i.e.@: memory references or floating-point
-instructions. It does not allow exceptions to be thrown from
-arbitrary signal handlers such as @code{SIGALRM}. This enables
-@option{-fexceptions}.
-
-@item -fdelete-dead-exceptions
-@opindex fdelete-dead-exceptions
-Consider that instructions that may throw exceptions but don't otherwise
-contribute to the execution of the program can be optimized away.
-This does not affect calls to functions except those with the
-@code{pure} or @code{const} attributes.
-This option is enabled by default for the Ada and C++ compilers, as permitted by
-the language specifications.
-Optimization passes that cause dead exceptions to be removed are enabled independently at different optimization levels.
-
-@item -funwind-tables
-@opindex funwind-tables
-Similar to @option{-fexceptions}, except that it just generates any needed
-static data, but does not affect the generated code in any other way.
-You normally do not need to enable this option; instead, a language processor
-that needs this handling enables it on your behalf.
-
-@item -fasynchronous-unwind-tables
-@opindex fasynchronous-unwind-tables
-Generate unwind table in DWARF format, if supported by target machine. The
-table is exact at each instruction boundary, so it can be used for stack
-unwinding from asynchronous events (such as debugger or garbage collector).
-
-@item -fno-gnu-unique
-@opindex fno-gnu-unique
-@opindex fgnu-unique
-On systems with recent GNU assembler and C library, the C++ compiler
-uses the @code{STB_GNU_UNIQUE} binding to make sure that definitions
-of template static data members and static local variables in inline
-functions are unique even in the presence of @code{RTLD_LOCAL}; this
-is necessary to avoid problems with a library used by two different
-@code{RTLD_LOCAL} plugins depending on a definition in one of them and
-therefore disagreeing with the other one about the binding of the
-symbol. But this causes @code{dlclose} to be ignored for affected
-DSOs; if your program relies on reinitialization of a DSO via
-@code{dlclose} and @code{dlopen}, you can use
-@option{-fno-gnu-unique}.
-
-@item -fpcc-struct-return
-@opindex fpcc-struct-return
-Return ``short'' @code{struct} and @code{union} values in memory like
-longer ones, rather than in registers. This convention is less
-efficient, but it has the advantage of allowing intercallability between
-GCC-compiled files and files compiled with other compilers, particularly
-the Portable C Compiler (pcc).
-
-The precise convention for returning structures in memory depends
-on the target configuration macros.
-
-Short structures and unions are those whose size and alignment match
-that of some integer type.
-
-@strong{Warning:} code compiled with the @option{-fpcc-struct-return}
-switch is not binary compatible with code compiled with the
-@option{-freg-struct-return} switch.
-Use it to conform to a non-default application binary interface.
-
-@item -freg-struct-return
-@opindex freg-struct-return
-Return @code{struct} and @code{union} values in registers when possible.
-This is more efficient for small structures than
-@option{-fpcc-struct-return}.
-
-If you specify neither @option{-fpcc-struct-return} nor
-@option{-freg-struct-return}, GCC defaults to whichever convention is
-standard for the target. If there is no standard convention, GCC
-defaults to @option{-fpcc-struct-return}, except on targets where GCC is
-the principal compiler. In those cases, we can choose the standard, and
-we chose the more efficient register return alternative.
-
-@strong{Warning:} code compiled with the @option{-freg-struct-return}
-switch is not binary compatible with code compiled with the
-@option{-fpcc-struct-return} switch.
-Use it to conform to a non-default application binary interface.
-
-@item -fshort-enums
-@opindex fshort-enums
-Allocate to an @code{enum} type only as many bytes as it needs for the
-declared range of possible values. Specifically, the @code{enum} type
-is equivalent to the smallest integer type that has enough room.
-
-@strong{Warning:} the @option{-fshort-enums} switch causes GCC to generate
-code that is not binary compatible with code generated without that switch.
-Use it to conform to a non-default application binary interface.
-
-@item -fshort-wchar
-@opindex fshort-wchar
-Override the underlying type for @code{wchar_t} to be @code{short
-unsigned int} instead of the default for the target. This option is
-useful for building programs to run under WINE@.
-
-@strong{Warning:} the @option{-fshort-wchar} switch causes GCC to generate
-code that is not binary compatible with code generated without that switch.
-Use it to conform to a non-default application binary interface.
-
-@item -fcommon
-@opindex fcommon
-@opindex fno-common
-@cindex tentative definitions
-In C code, this option controls the placement of global variables
-defined without an initializer, known as @dfn{tentative definitions}
-in the C standard. Tentative definitions are distinct from declarations
-of a variable with the @code{extern} keyword, which do not allocate storage.
-
-The default is @option{-fno-common}, which specifies that the compiler places
-uninitialized global variables in the BSS section of the object file.
-This inhibits the merging of tentative definitions by the linker so you get a
-multiple-definition error if the same variable is accidentally defined in more
-than one compilation unit.
-
-The @option{-fcommon} places uninitialized global variables in a common block.
-This allows the linker to resolve all tentative definitions of the same variable
-in different compilation units to the same object, or to a non-tentative
-definition. This behavior is inconsistent with C++, and on many targets implies
-a speed and code size penalty on global variable references. It is mainly
-useful to enable legacy code to link without errors.
-
-@item -fno-ident
-@opindex fno-ident
-@opindex fident
-Ignore the @code{#ident} directive.
-
-@item -finhibit-size-directive
-@opindex finhibit-size-directive
-Don't output a @code{.size} assembler directive, or anything else that
-would cause trouble if the function is split in the middle, and the
-two halves are placed at locations far apart in memory. This option is
-used when compiling @file{crtstuff.c}; you should not need to use it
-for anything else.
-
-@item -fverbose-asm
-@opindex fverbose-asm
-Put extra commentary information in the generated assembly code to
-make it more readable. This option is generally only of use to those
-who actually need to read the generated assembly code (perhaps while
-debugging the compiler itself).
-
-@option{-fno-verbose-asm}, the default, causes the
-extra information to be omitted and is useful when comparing two assembler
-files.
-
-The added comments include:
-
-@itemize @bullet
-
-@item
-information on the compiler version and command-line options,
-
-@item
-the source code lines associated with the assembly instructions,
-in the form FILENAME:LINENUMBER:CONTENT OF LINE,
-
-@item
-hints on which high-level expressions correspond to
-the various assembly instruction operands.
-
-@end itemize
-
-For example, given this C source file:
-
-@smallexample
-int test (int n)
-@{
- int i;
- int total = 0;
-
- for (i = 0; i < n; i++)
- total += i * i;
-
- return total;
-@}
-@end smallexample
-
-compiling to (x86_64) assembly via @option{-S} and emitting the result
-direct to stdout via @option{-o} @option{-}
-
-@smallexample
-gcc -S test.c -fverbose-asm -Os -o -
-@end smallexample
-
-gives output similar to this:
-
-@smallexample
- .file "test.c"
-# GNU C11 (GCC) version 7.0.0 20160809 (experimental) (x86_64-pc-linux-gnu)
- [...snip...]
-# options passed:
- [...snip...]
-
- .text
- .globl test
- .type test, @@function
-test:
-.LFB0:
- .cfi_startproc
-# test.c:4: int total = 0;
- xorl %eax, %eax # <retval>
-# test.c:6: for (i = 0; i < n; i++)
- xorl %edx, %edx # i
-.L2:
-# test.c:6: for (i = 0; i < n; i++)
- cmpl %edi, %edx # n, i
- jge .L5 #,
-# test.c:7: total += i * i;
- movl %edx, %ecx # i, tmp92
- imull %edx, %ecx # i, tmp92
-# test.c:6: for (i = 0; i < n; i++)
- incl %edx # i
-# test.c:7: total += i * i;
- addl %ecx, %eax # tmp92, <retval>
- jmp .L2 #
-.L5:
-# test.c:10: @}
- ret
- .cfi_endproc
-.LFE0:
- .size test, .-test
- .ident "GCC: (GNU) 7.0.0 20160809 (experimental)"
- .section .note.GNU-stack,"",@@progbits
-@end smallexample
-
-The comments are intended for humans rather than machines and hence the
-precise format of the comments is subject to change.
-
-@item -frecord-gcc-switches
-@opindex frecord-gcc-switches
-This switch causes the command line used to invoke the
-compiler to be recorded into the object file that is being created.
-This switch is only implemented on some targets and the exact format
-of the recording is target and binary file format dependent, but it
-usually takes the form of a section containing ASCII text. This
-switch is related to the @option{-fverbose-asm} switch, but that
-switch only records information in the assembler output file as
-comments, so it never reaches the object file.
-See also @option{-grecord-gcc-switches} for another
-way of storing compiler options into the object file.
-
-@item -fpic
-@opindex fpic
-@cindex global offset table
-@cindex PIC
-Generate position-independent code (PIC) suitable for use in a shared
-library, if supported for the target machine. Such code accesses all
-constant addresses through a global offset table (GOT)@. The dynamic
-loader resolves the GOT entries when the program starts (the dynamic
-loader is not part of GCC; it is part of the operating system). If
-the GOT size for the linked executable exceeds a machine-specific
-maximum size, you get an error message from the linker indicating that
-@option{-fpic} does not work; in that case, recompile with @option{-fPIC}
-instead. (These maximums are 8k on the SPARC, 28k on AArch64 and 32k
-on the m68k and RS/6000. The x86 has no such limit.)
-
-Position-independent code requires special support, and therefore works
-only on certain machines. For the x86, GCC supports PIC for System V
-but not for the Sun 386i. Code generated for the IBM RS/6000 is always
-position-independent.
-
-When this flag is set, the macros @code{__pic__} and @code{__PIC__}
-are defined to 1.
-
-@item -fPIC
-@opindex fPIC
-If supported for the target machine, emit position-independent code,
-suitable for dynamic linking and avoiding any limit on the size of the
-global offset table. This option makes a difference on AArch64, m68k,
-PowerPC and SPARC@.
-
-Position-independent code requires special support, and therefore works
-only on certain machines.
-
-When this flag is set, the macros @code{__pic__} and @code{__PIC__}
-are defined to 2.
-
-@item -fpie
-@itemx -fPIE
-@opindex fpie
-@opindex fPIE
-These options are similar to @option{-fpic} and @option{-fPIC}, but the
-generated position-independent code can be only linked into executables.
-Usually these options are used to compile code that will be linked using
-the @option{-pie} GCC option.
-
-@option{-fpie} and @option{-fPIE} both define the macros
-@code{__pie__} and @code{__PIE__}. The macros have the value 1
-for @option{-fpie} and 2 for @option{-fPIE}.
-
-@item -fno-plt
-@opindex fno-plt
-@opindex fplt
-Do not use the PLT for external function calls in position-independent code.
-Instead, load the callee address at call sites from the GOT and branch to it.
-This leads to more efficient code by eliminating PLT stubs and exposing
-GOT loads to optimizations. On architectures such as 32-bit x86 where
-PLT stubs expect the GOT pointer in a specific register, this gives more
-register allocation freedom to the compiler.
-Lazy binding requires use of the PLT;
-with @option{-fno-plt} all external symbols are resolved at load time.
-
-Alternatively, the function attribute @code{noplt} can be used to avoid calls
-through the PLT for specific external functions.
-
-In position-dependent code, a few targets also convert calls to
-functions that are marked to not use the PLT to use the GOT instead.
-
-@item -fno-jump-tables
-@opindex fno-jump-tables
-@opindex fjump-tables
-Do not use jump tables for switch statements even where it would be
-more efficient than other code generation strategies. This option is
-of use in conjunction with @option{-fpic} or @option{-fPIC} for
-building code that forms part of a dynamic linker and cannot
-reference the address of a jump table. On some targets, jump tables
-do not require a GOT and this option is not needed.
-
-@item -fno-bit-tests
-@opindex fno-bit-tests
-@opindex fbit-tests
-Do not use bit tests for switch statements even where it would be
-more efficient than other code generation strategies.
-
-@item -ffixed-@var{reg}
-@opindex ffixed
-Treat the register named @var{reg} as a fixed register; generated code
-should never refer to it (except perhaps as a stack pointer, frame
-pointer or in some other fixed role).
-
-@var{reg} must be the name of a register. The register names accepted
-are machine-specific and are defined in the @code{REGISTER_NAMES}
-macro in the machine description macro file.
-
-This flag does not have a negative form, because it specifies a
-three-way choice.
-
-@item -fcall-used-@var{reg}
-@opindex fcall-used
-Treat the register named @var{reg} as an allocable register that is
-clobbered by function calls. It may be allocated for temporaries or
-variables that do not live across a call. Functions compiled this way
-do not save and restore the register @var{reg}.
-
-It is an error to use this flag with the frame pointer or stack pointer.
-Use of this flag for other registers that have fixed pervasive roles in
-the machine's execution model produces disastrous results.
-
-This flag does not have a negative form, because it specifies a
-three-way choice.
-
-@item -fcall-saved-@var{reg}
-@opindex fcall-saved
-Treat the register named @var{reg} as an allocable register saved by
-functions. It may be allocated even for temporaries or variables that
-live across a call. Functions compiled this way save and restore
-the register @var{reg} if they use it.
-
-It is an error to use this flag with the frame pointer or stack pointer.
-Use of this flag for other registers that have fixed pervasive roles in
-the machine's execution model produces disastrous results.
-
-A different sort of disaster results from the use of this flag for
-a register in which function values may be returned.
-
-This flag does not have a negative form, because it specifies a
-three-way choice.
-
-@item -fpack-struct[=@var{n}]
-@opindex fpack-struct
-Without a value specified, pack all structure members together without
-holes. When a value is specified (which must be a small power of two), pack
-structure members according to this value, representing the maximum
-alignment (that is, objects with default alignment requirements larger than
-this are output potentially unaligned at the next fitting location.
-
-@strong{Warning:} the @option{-fpack-struct} switch causes GCC to generate
-code that is not binary compatible with code generated without that switch.
-Additionally, it makes the code suboptimal.
-Use it to conform to a non-default application binary interface.
-
-@item -fleading-underscore
-@opindex fleading-underscore
-This option and its counterpart, @option{-fno-leading-underscore}, forcibly
-change the way C symbols are represented in the object file. One use
-is to help link with legacy assembly code.
-
-@strong{Warning:} the @option{-fleading-underscore} switch causes GCC to
-generate code that is not binary compatible with code generated without that
-switch. Use it to conform to a non-default application binary interface.
-Not all targets provide complete support for this switch.
-
-@item -ftls-model=@var{model}
-@opindex ftls-model
-Alter the thread-local storage model to be used (@pxref{Thread-Local}).
-The @var{model} argument should be one of @samp{global-dynamic},
-@samp{local-dynamic}, @samp{initial-exec} or @samp{local-exec}.
-Note that the choice is subject to optimization: the compiler may use
-a more efficient model for symbols not visible outside of the translation
-unit, or if @option{-fpic} is not given on the command line.
-
-The default without @option{-fpic} is @samp{initial-exec}; with
-@option{-fpic} the default is @samp{global-dynamic}.
-
-@item -ftrampolines
-@opindex ftrampolines
-For targets that normally need trampolines for nested functions, always
-generate them instead of using descriptors. Otherwise, for targets that
-do not need them, like for example HP-PA or IA-64, do nothing.
-
-A trampoline is a small piece of code that is created at run time on the
-stack when the address of a nested function is taken, and is used to call
-the nested function indirectly. Therefore, it requires the stack to be
-made executable in order for the program to work properly.
-
-@option{-fno-trampolines} is enabled by default on a language by language
-basis to let the compiler avoid generating them, if it computes that this
-is safe, and replace them with descriptors. Descriptors are made up of data
-only, but the generated code must be prepared to deal with them. As of this
-writing, @option{-fno-trampolines} is enabled by default only for Ada.
-
-Moreover, code compiled with @option{-ftrampolines} and code compiled with
-@option{-fno-trampolines} are not binary compatible if nested functions are
-present. This option must therefore be used on a program-wide basis and be
-manipulated with extreme care.
-
-For languages other than Ada, the @code{-ftrampolines} and
-@code{-fno-trampolines} options currently have no effect, and
-trampolines are always generated on platforms that need them
-for nested functions.
-
-@item -fvisibility=@r{[}default@r{|}internal@r{|}hidden@r{|}protected@r{]}
-@opindex fvisibility
-Set the default ELF image symbol visibility to the specified option---all
-symbols are marked with this unless overridden within the code.
-Using this feature can very substantially improve linking and
-load times of shared object libraries, produce more optimized
-code, provide near-perfect API export and prevent symbol clashes.
-It is @strong{strongly} recommended that you use this in any shared objects
-you distribute.
-
-Despite the nomenclature, @samp{default} always means public; i.e.,
-available to be linked against from outside the shared object.
-@samp{protected} and @samp{internal} are pretty useless in real-world
-usage so the only other commonly used option is @samp{hidden}.
-The default if @option{-fvisibility} isn't specified is
-@samp{default}, i.e., make every symbol public.
-
-A good explanation of the benefits offered by ensuring ELF
-symbols have the correct visibility is given by ``How To Write
-Shared Libraries'' by Ulrich Drepper (which can be found at
-@w{@uref{https://www.akkadia.org/drepper/}})---however a superior
-solution made possible by this option to marking things hidden when
-the default is public is to make the default hidden and mark things
-public. This is the norm with DLLs on Windows and with @option{-fvisibility=hidden}
-and @code{__attribute__ ((visibility("default")))} instead of
-@code{__declspec(dllexport)} you get almost identical semantics with
-identical syntax. This is a great boon to those working with
-cross-platform projects.
-
-For those adding visibility support to existing code, you may find
-@code{#pragma GCC visibility} of use. This works by you enclosing
-the declarations you wish to set visibility for with (for example)
-@code{#pragma GCC visibility push(hidden)} and
-@code{#pragma GCC visibility pop}.
-Bear in mind that symbol visibility should be viewed @strong{as
-part of the API interface contract} and thus all new code should
-always specify visibility when it is not the default; i.e., declarations
-only for use within the local DSO should @strong{always} be marked explicitly
-as hidden as so to avoid PLT indirection overheads---making this
-abundantly clear also aids readability and self-documentation of the code.
-Note that due to ISO C++ specification requirements, @code{operator new} and
-@code{operator delete} must always be of default visibility.
-
-Be aware that headers from outside your project, in particular system
-headers and headers from any other library you use, may not be
-expecting to be compiled with visibility other than the default. You
-may need to explicitly say @code{#pragma GCC visibility push(default)}
-before including any such headers.
-
-@code{extern} declarations are not affected by @option{-fvisibility}, so
-a lot of code can be recompiled with @option{-fvisibility=hidden} with
-no modifications. However, this means that calls to @code{extern}
-functions with no explicit visibility use the PLT, so it is more
-effective to use @code{__attribute ((visibility))} and/or
-@code{#pragma GCC visibility} to tell the compiler which @code{extern}
-declarations should be treated as hidden.
-
-Note that @option{-fvisibility} does affect C++ vague linkage
-entities. This means that, for instance, an exception class that is
-be thrown between DSOs must be explicitly marked with default
-visibility so that the @samp{type_info} nodes are unified between
-the DSOs.
-
-An overview of these techniques, their benefits and how to use them
-is at @uref{https://gcc.gnu.org/@/wiki/@/Visibility}.
-
-@item -fstrict-volatile-bitfields
-@opindex fstrict-volatile-bitfields
-This option should be used if accesses to volatile bit-fields (or other
-structure fields, although the compiler usually honors those types
-anyway) should use a single access of the width of the
-field's type, aligned to a natural alignment if possible. For
-example, targets with memory-mapped peripheral registers might require
-all such accesses to be 16 bits wide; with this flag you can
-declare all peripheral bit-fields as @code{unsigned short} (assuming short
-is 16 bits on these targets) to force GCC to use 16-bit accesses
-instead of, perhaps, a more efficient 32-bit access.
-
-If this option is disabled, the compiler uses the most efficient
-instruction. In the previous example, that might be a 32-bit load
-instruction, even though that accesses bytes that do not contain
-any portion of the bit-field, or memory-mapped registers unrelated to
-the one being updated.
-
-In some cases, such as when the @code{packed} attribute is applied to a
-structure field, it may not be possible to access the field with a single
-read or write that is correctly aligned for the target machine. In this
-case GCC falls back to generating multiple accesses rather than code that
-will fault or truncate the result at run time.
-
-Note: Due to restrictions of the C/C++11 memory model, write accesses are
-not allowed to touch non bit-field members. It is therefore recommended
-to define all bits of the field's type as bit-field members.
-
-The default value of this option is determined by the application binary
-interface for the target processor.
-
-@item -fsync-libcalls
-@opindex fsync-libcalls
-This option controls whether any out-of-line instance of the @code{__sync}
-family of functions may be used to implement the C++11 @code{__atomic}
-family of functions.
-
-The default value of this option is enabled, thus the only useful form
-of the option is @option{-fno-sync-libcalls}. This option is used in
-the implementation of the @file{libatomic} runtime library.
-
-@end table
-
-@node Developer Options
-@section GCC Developer Options
-@cindex developer options
-@cindex debugging GCC
-@cindex debug dump options
-@cindex dump options
-@cindex compilation statistics
-
-This section describes command-line options that are primarily of
-interest to GCC developers, including options to support compiler
-testing and investigation of compiler bugs and compile-time
-performance problems. This includes options that produce debug dumps
-at various points in the compilation; that print statistics such as
-memory use and execution time; and that print information about GCC's
-configuration, such as where it searches for libraries. You should
-rarely need to use any of these options for ordinary compilation and
-linking tasks.
-
-Many developer options that cause GCC to dump output to a file take an
-optional @samp{=@var{filename}} suffix. You can specify @samp{stdout}
-or @samp{-} to dump to standard output, and @samp{stderr} for standard
-error.
-
-If @samp{=@var{filename}} is omitted, a default dump file name is
-constructed by concatenating the base dump file name, a pass number,
-phase letter, and pass name. The base dump file name is the name of
-output file produced by the compiler if explicitly specified and not
-an executable; otherwise it is the source file name.
-The pass number is determined by the order passes are registered with
-the compiler's pass manager.
-This is generally the same as the order of execution, but passes
-registered by plugins, target-specific passes, or passes that are
-otherwise registered late are numbered higher than the pass named
-@samp{final}, even if they are executed earlier. The phase letter is
-one of @samp{i} (inter-procedural analysis), @samp{l}
-(language-specific), @samp{r} (RTL), or @samp{t} (tree).
-The files are created in the directory of the output file.
-
-@table @gcctabopt
-
-@item -fcallgraph-info
-@itemx -fcallgraph-info=@var{MARKERS}
-@opindex fcallgraph-info
-Makes the compiler output callgraph information for the program, on a
-per-object-file basis. The information is generated in the common VCG
-format. It can be decorated with additional, per-node and/or per-edge
-information, if a list of comma-separated markers is additionally
-specified. When the @code{su} marker is specified, the callgraph is
-decorated with stack usage information; it is equivalent to
-@option{-fstack-usage}. When the @code{da} marker is specified, the
-callgraph is decorated with information about dynamically allocated
-objects.
-
-When compiling with @option{-flto}, no callgraph information is output
-along with the object file. At LTO link time, @option{-fcallgraph-info}
-may generate multiple callgraph information files next to intermediate
-LTO output files.
-
-@item -d@var{letters}
-@itemx -fdump-rtl-@var{pass}
-@itemx -fdump-rtl-@var{pass}=@var{filename}
-@opindex d
-@opindex fdump-rtl-@var{pass}
-Says to make debugging dumps during compilation at times specified by
-@var{letters}. This is used for debugging the RTL-based passes of the
-compiler.
-
-Some @option{-d@var{letters}} switches have different meaning when
-@option{-E} is used for preprocessing. @xref{Preprocessor Options},
-for information about preprocessor-specific dump options.
-
-Debug dumps can be enabled with a @option{-fdump-rtl} switch or some
-@option{-d} option @var{letters}. Here are the possible
-letters for use in @var{pass} and @var{letters}, and their meanings:
-
-@table @gcctabopt
-
-@item -fdump-rtl-alignments
-@opindex fdump-rtl-alignments
-Dump after branch alignments have been computed.
-
-@item -fdump-rtl-asmcons
-@opindex fdump-rtl-asmcons
-Dump after fixing rtl statements that have unsatisfied in/out constraints.
-
-@item -fdump-rtl-auto_inc_dec
-@opindex fdump-rtl-auto_inc_dec
-Dump after auto-inc-dec discovery. This pass is only run on
-architectures that have auto inc or auto dec instructions.
-
-@item -fdump-rtl-barriers
-@opindex fdump-rtl-barriers
-Dump after cleaning up the barrier instructions.
-
-@item -fdump-rtl-bbpart
-@opindex fdump-rtl-bbpart
-Dump after partitioning hot and cold basic blocks.
-
-@item -fdump-rtl-bbro
-@opindex fdump-rtl-bbro
-Dump after block reordering.
-
-@item -fdump-rtl-btl1
-@itemx -fdump-rtl-btl2
-@opindex fdump-rtl-btl2
-@opindex fdump-rtl-btl2
-@option{-fdump-rtl-btl1} and @option{-fdump-rtl-btl2} enable dumping
-after the two branch
-target load optimization passes.
-
-@item -fdump-rtl-bypass
-@opindex fdump-rtl-bypass
-Dump after jump bypassing and control flow optimizations.
-
-@item -fdump-rtl-combine
-@opindex fdump-rtl-combine
-Dump after the RTL instruction combination pass.
-
-@item -fdump-rtl-compgotos
-@opindex fdump-rtl-compgotos
-Dump after duplicating the computed gotos.
-
-@item -fdump-rtl-ce1
-@itemx -fdump-rtl-ce2
-@itemx -fdump-rtl-ce3
-@opindex fdump-rtl-ce1
-@opindex fdump-rtl-ce2
-@opindex fdump-rtl-ce3
-@option{-fdump-rtl-ce1}, @option{-fdump-rtl-ce2}, and
-@option{-fdump-rtl-ce3} enable dumping after the three
-if conversion passes.
-
-@item -fdump-rtl-cprop_hardreg
-@opindex fdump-rtl-cprop_hardreg
-Dump after hard register copy propagation.
-
-@item -fdump-rtl-csa
-@opindex fdump-rtl-csa
-Dump after combining stack adjustments.
-
-@item -fdump-rtl-cse1
-@itemx -fdump-rtl-cse2
-@opindex fdump-rtl-cse1
-@opindex fdump-rtl-cse2
-@option{-fdump-rtl-cse1} and @option{-fdump-rtl-cse2} enable dumping after
-the two common subexpression elimination passes.
-
-@item -fdump-rtl-dce
-@opindex fdump-rtl-dce
-Dump after the standalone dead code elimination passes.
-
-@item -fdump-rtl-dbr
-@opindex fdump-rtl-dbr
-Dump after delayed branch scheduling.
-
-@item -fdump-rtl-dce1
-@itemx -fdump-rtl-dce2
-@opindex fdump-rtl-dce1
-@opindex fdump-rtl-dce2
-@option{-fdump-rtl-dce1} and @option{-fdump-rtl-dce2} enable dumping after
-the two dead store elimination passes.
-
-@item -fdump-rtl-eh
-@opindex fdump-rtl-eh
-Dump after finalization of EH handling code.
-
-@item -fdump-rtl-eh_ranges
-@opindex fdump-rtl-eh_ranges
-Dump after conversion of EH handling range regions.
-
-@item -fdump-rtl-expand
-@opindex fdump-rtl-expand
-Dump after RTL generation.
-
-@item -fdump-rtl-fwprop1
-@itemx -fdump-rtl-fwprop2
-@opindex fdump-rtl-fwprop1
-@opindex fdump-rtl-fwprop2
-@option{-fdump-rtl-fwprop1} and @option{-fdump-rtl-fwprop2} enable
-dumping after the two forward propagation passes.
-
-@item -fdump-rtl-gcse1
-@itemx -fdump-rtl-gcse2
-@opindex fdump-rtl-gcse1
-@opindex fdump-rtl-gcse2
-@option{-fdump-rtl-gcse1} and @option{-fdump-rtl-gcse2} enable dumping
-after global common subexpression elimination.
-
-@item -fdump-rtl-init-regs
-@opindex fdump-rtl-init-regs
-Dump after the initialization of the registers.
-
-@item -fdump-rtl-initvals
-@opindex fdump-rtl-initvals
-Dump after the computation of the initial value sets.
-
-@item -fdump-rtl-into_cfglayout
-@opindex fdump-rtl-into_cfglayout
-Dump after converting to cfglayout mode.
-
-@item -fdump-rtl-ira
-@opindex fdump-rtl-ira
-Dump after iterated register allocation.
-
-@item -fdump-rtl-jump
-@opindex fdump-rtl-jump
-Dump after the second jump optimization.
-
-@item -fdump-rtl-loop2
-@opindex fdump-rtl-loop2
-@option{-fdump-rtl-loop2} enables dumping after the rtl
-loop optimization passes.
-
-@item -fdump-rtl-mach
-@opindex fdump-rtl-mach
-Dump after performing the machine dependent reorganization pass, if that
-pass exists.
-
-@item -fdump-rtl-mode_sw
-@opindex fdump-rtl-mode_sw
-Dump after removing redundant mode switches.
-
-@item -fdump-rtl-rnreg
-@opindex fdump-rtl-rnreg
-Dump after register renumbering.
-
-@item -fdump-rtl-outof_cfglayout
-@opindex fdump-rtl-outof_cfglayout
-Dump after converting from cfglayout mode.
-
-@item -fdump-rtl-peephole2
-@opindex fdump-rtl-peephole2
-Dump after the peephole pass.
-
-@item -fdump-rtl-postreload
-@opindex fdump-rtl-postreload
-Dump after post-reload optimizations.
-
-@item -fdump-rtl-pro_and_epilogue
-@opindex fdump-rtl-pro_and_epilogue
-Dump after generating the function prologues and epilogues.
-
-@item -fdump-rtl-sched1
-@itemx -fdump-rtl-sched2
-@opindex fdump-rtl-sched1
-@opindex fdump-rtl-sched2
-@option{-fdump-rtl-sched1} and @option{-fdump-rtl-sched2} enable dumping
-after the basic block scheduling passes.
-
-@item -fdump-rtl-ree
-@opindex fdump-rtl-ree
-Dump after sign/zero extension elimination.
-
-@item -fdump-rtl-seqabstr
-@opindex fdump-rtl-seqabstr
-Dump after common sequence discovery.
-
-@item -fdump-rtl-shorten
-@opindex fdump-rtl-shorten
-Dump after shortening branches.
-
-@item -fdump-rtl-sibling
-@opindex fdump-rtl-sibling
-Dump after sibling call optimizations.
-
-@item -fdump-rtl-split1
-@itemx -fdump-rtl-split2
-@itemx -fdump-rtl-split3
-@itemx -fdump-rtl-split4
-@itemx -fdump-rtl-split5
-@opindex fdump-rtl-split1
-@opindex fdump-rtl-split2
-@opindex fdump-rtl-split3
-@opindex fdump-rtl-split4
-@opindex fdump-rtl-split5
-These options enable dumping after five rounds of
-instruction splitting.
-
-@item -fdump-rtl-sms
-@opindex fdump-rtl-sms
-Dump after modulo scheduling. This pass is only run on some
-architectures.
-
-@item -fdump-rtl-stack
-@opindex fdump-rtl-stack
-Dump after conversion from GCC's ``flat register file'' registers to the
-x87's stack-like registers. This pass is only run on x86 variants.
-
-@item -fdump-rtl-subreg1
-@itemx -fdump-rtl-subreg2
-@opindex fdump-rtl-subreg1
-@opindex fdump-rtl-subreg2
-@option{-fdump-rtl-subreg1} and @option{-fdump-rtl-subreg2} enable dumping after
-the two subreg expansion passes.
-
-@item -fdump-rtl-unshare
-@opindex fdump-rtl-unshare
-Dump after all rtl has been unshared.
-
-@item -fdump-rtl-vartrack
-@opindex fdump-rtl-vartrack
-Dump after variable tracking.
-
-@item -fdump-rtl-vregs
-@opindex fdump-rtl-vregs
-Dump after converting virtual registers to hard registers.
-
-@item -fdump-rtl-web
-@opindex fdump-rtl-web
-Dump after live range splitting.
-
-@item -fdump-rtl-regclass
-@itemx -fdump-rtl-subregs_of_mode_init
-@itemx -fdump-rtl-subregs_of_mode_finish
-@itemx -fdump-rtl-dfinit
-@itemx -fdump-rtl-dfinish
-@opindex fdump-rtl-regclass
-@opindex fdump-rtl-subregs_of_mode_init
-@opindex fdump-rtl-subregs_of_mode_finish
-@opindex fdump-rtl-dfinit
-@opindex fdump-rtl-dfinish
-These dumps are defined but always produce empty files.
-
-@item -da
-@itemx -fdump-rtl-all
-@opindex da
-@opindex fdump-rtl-all
-Produce all the dumps listed above.
-
-@item -dA
-@opindex dA
-Annotate the assembler output with miscellaneous debugging information.
-
-@item -dD
-@opindex dD
-Dump all macro definitions, at the end of preprocessing, in addition to
-normal output.
-
-@item -dH
-@opindex dH
-Produce a core dump whenever an error occurs.
-
-@item -dp
-@opindex dp
-Annotate the assembler output with a comment indicating which
-pattern and alternative is used. The length and cost of each instruction are
-also printed.
-
-@item -dP
-@opindex dP
-Dump the RTL in the assembler output as a comment before each instruction.
-Also turns on @option{-dp} annotation.
-
-@item -dx
-@opindex dx
-Just generate RTL for a function instead of compiling it. Usually used
-with @option{-fdump-rtl-expand}.
-@end table
-
-@item -fdump-debug
-@opindex fdump-debug
-Dump debugging information generated during the debug
-generation phase.
-
-@item -fdump-earlydebug
-@opindex fdump-earlydebug
-Dump debugging information generated during the early debug
-generation phase.
-
-@item -fdump-noaddr
-@opindex fdump-noaddr
-When doing debugging dumps, suppress address output. This makes it more
-feasible to use diff on debugging dumps for compiler invocations with
-different compiler binaries and/or different
-text / bss / data / heap / stack / dso start locations.
-
-@item -freport-bug
-@opindex freport-bug
-Collect and dump debug information into a temporary file if an
-internal compiler error (ICE) occurs.
-
-@item -fdump-unnumbered
-@opindex fdump-unnumbered
-When doing debugging dumps, suppress instruction numbers and address output.
-This makes it more feasible to use diff on debugging dumps for compiler
-invocations with different options, in particular with and without
-@option{-g}.
-
-@item -fdump-unnumbered-links
-@opindex fdump-unnumbered-links
-When doing debugging dumps (see @option{-d} option above), suppress
-instruction numbers for the links to the previous and next instructions
-in a sequence.
-
-@item -fdump-ipa-@var{switch}
-@itemx -fdump-ipa-@var{switch}-@var{options}
-@opindex fdump-ipa
-Control the dumping at various stages of inter-procedural analysis
-language tree to a file. The file name is generated by appending a
-switch specific suffix to the source file name, and the file is created
-in the same directory as the output file. The following dumps are
-possible:
-
-@table @samp
-@item all
-Enables all inter-procedural analysis dumps.
-
-@item cgraph
-Dumps information about call-graph optimization, unused function removal,
-and inlining decisions.
-
-@item inline
-Dump after function inlining.
-
-@end table
-
-Additionally, the options @option{-optimized}, @option{-missed},
-@option{-note}, and @option{-all} can be provided, with the same meaning
-as for @option{-fopt-info}, defaulting to @option{-optimized}.
-
-For example, @option{-fdump-ipa-inline-optimized-missed} will emit
-information on callsites that were inlined, along with callsites
-that were not inlined.
-
-By default, the dump will contain messages about successful
-optimizations (equivalent to @option{-optimized}) together with
-low-level details about the analysis.
-
-@item -fdump-lang
-@opindex fdump-lang
-Dump language-specific information. The file name is made by appending
-@file{.lang} to the source file name.
-
-@item -fdump-lang-all
-@itemx -fdump-lang-@var{switch}
-@itemx -fdump-lang-@var{switch}-@var{options}
-@itemx -fdump-lang-@var{switch}-@var{options}=@var{filename}
-@opindex fdump-lang-all
-@opindex fdump-lang
-Control the dumping of language-specific information. The @var{options}
-and @var{filename} portions behave as described in the
-@option{-fdump-tree} option. The following @var{switch} values are
-accepted:
-
-@table @samp
-@item all
-
-Enable all language-specific dumps.
-
-@item class
-Dump class hierarchy information. Virtual table information is emitted
-unless '@option{slim}' is specified. This option is applicable to C++ only.
-
-@item module
-Dump module information. Options @option{lineno} (locations),
-@option{graph} (reachability), @option{blocks} (clusters),
-@option{uid} (serialization), @option{alias} (mergeable),
-@option{asmname} (Elrond), @option{eh} (mapper) & @option{vops}
-(macros) may provide additional information. This option is
-applicable to C++ only.
-
-@item raw
-Dump the raw internal tree data. This option is applicable to C++ only.
-
-@end table
-
-@item -fdump-passes
-@opindex fdump-passes
-Print on @file{stderr} the list of optimization passes that are turned
-on and off by the current command-line options.
-
-@item -fdump-statistics-@var{option}
-@opindex fdump-statistics
-Enable and control dumping of pass statistics in a separate file. The
-file name is generated by appending a suffix ending in
-@samp{.statistics} to the source file name, and the file is created in
-the same directory as the output file. If the @samp{-@var{option}}
-form is used, @samp{-stats} causes counters to be summed over the
-whole compilation unit while @samp{-details} dumps every event as
-the passes generate them. The default with no option is to sum
-counters for each function compiled.
-
-@item -fdump-tree-all
-@itemx -fdump-tree-@var{switch}
-@itemx -fdump-tree-@var{switch}-@var{options}
-@itemx -fdump-tree-@var{switch}-@var{options}=@var{filename}
-@opindex fdump-tree-all
-@opindex fdump-tree
-Control the dumping at various stages of processing the intermediate
-language tree to a file. If the @samp{-@var{options}}
-form is used, @var{options} is a list of @samp{-} separated options
-which control the details of the dump. Not all options are applicable
-to all dumps; those that are not meaningful are ignored. The
-following options are available
-
-@table @samp
-@item address
-Print the address of each node. Usually this is not meaningful as it
-changes according to the environment and source file. Its primary use
-is for tying up a dump file with a debug environment.
-@item asmname
-If @code{DECL_ASSEMBLER_NAME} has been set for a given decl, use that
-in the dump instead of @code{DECL_NAME}. Its primary use is ease of
-use working backward from mangled names in the assembly file.
-@item slim
-When dumping front-end intermediate representations, inhibit dumping
-of members of a scope or body of a function merely because that scope
-has been reached. Only dump such items when they are directly reachable
-by some other path.
-
-When dumping pretty-printed trees, this option inhibits dumping the
-bodies of control structures.
-
-When dumping RTL, print the RTL in slim (condensed) form instead of
-the default LISP-like representation.
-@item raw
-Print a raw representation of the tree. By default, trees are
-pretty-printed into a C-like representation.
-@item details
-Enable more detailed dumps (not honored by every dump option). Also
-include information from the optimization passes.
-@item stats
-Enable dumping various statistics about the pass (not honored by every dump
-option).
-@item blocks
-Enable showing basic block boundaries (disabled in raw dumps).
-@item graph
-For each of the other indicated dump files (@option{-fdump-rtl-@var{pass}}),
-dump a representation of the control flow graph suitable for viewing with
-GraphViz to @file{@var{file}.@var{passid}.@var{pass}.dot}. Each function in
-the file is pretty-printed as a subgraph, so that GraphViz can render them
-all in a single plot.
-
-This option currently only works for RTL dumps, and the RTL is always
-dumped in slim form.
-@item vops
-Enable showing virtual operands for every statement.
-@item lineno
-Enable showing line numbers for statements.
-@item uid
-Enable showing the unique ID (@code{DECL_UID}) for each variable.
-@item verbose
-Enable showing the tree dump for each statement.
-@item eh
-Enable showing the EH region number holding each statement.
-@item scev
-Enable showing scalar evolution analysis details.
-@item optimized
-Enable showing optimization information (only available in certain
-passes).
-@item missed
-Enable showing missed optimization information (only available in certain
-passes).
-@item note
-Enable other detailed optimization information (only available in
-certain passes).
-@item all
-Turn on all options, except @option{raw}, @option{slim}, @option{verbose}
-and @option{lineno}.
-@item optall
-Turn on all optimization options, i.e., @option{optimized},
-@option{missed}, and @option{note}.
-@end table
-
-To determine what tree dumps are available or find the dump for a pass
-of interest follow the steps below.
-
-@enumerate
-@item
-Invoke GCC with @option{-fdump-passes} and in the @file{stderr} output
-look for a code that corresponds to the pass you are interested in.
-For example, the codes @code{tree-evrp}, @code{tree-vrp1}, and
-@code{tree-vrp2} correspond to the three Value Range Propagation passes.
-The number at the end distinguishes distinct invocations of the same pass.
-@item
-To enable the creation of the dump file, append the pass code to
-the @option{-fdump-} option prefix and invoke GCC with it. For example,
-to enable the dump from the Early Value Range Propagation pass, invoke
-GCC with the @option{-fdump-tree-evrp} option. Optionally, you may
-specify the name of the dump file. If you don't specify one, GCC
-creates as described below.
-@item
-Find the pass dump in a file whose name is composed of three components
-separated by a period: the name of the source file GCC was invoked to
-compile, a numeric suffix indicating the pass number followed by the
-letter @samp{t} for tree passes (and the letter @samp{r} for RTL passes),
-and finally the pass code. For example, the Early VRP pass dump might
-be in a file named @file{myfile.c.038t.evrp} in the current working
-directory. Note that the numeric codes are not stable and may change
-from one version of GCC to another.
-@end enumerate
-
-@item -fopt-info
-@itemx -fopt-info-@var{options}
-@itemx -fopt-info-@var{options}=@var{filename}
-@opindex fopt-info
-Controls optimization dumps from various optimization passes. If the
-@samp{-@var{options}} form is used, @var{options} is a list of
-@samp{-} separated option keywords to select the dump details and
-optimizations.
-
-The @var{options} can be divided into three groups:
-@enumerate
-@item
-options describing what kinds of messages should be emitted,
-@item
-options describing the verbosity of the dump, and
-@item
-options describing which optimizations should be included.
-@end enumerate
-The options from each group can be freely mixed as they are
-non-overlapping. However, in case of any conflicts,
-the later options override the earlier options on the command
-line.
-
-The following options control which kinds of messages should be emitted:
-
-@table @samp
-@item optimized
-Print information when an optimization is successfully applied. It is
-up to a pass to decide which information is relevant. For example, the
-vectorizer passes print the source location of loops which are
-successfully vectorized.
-@item missed
-Print information about missed optimizations. Individual passes
-control which information to include in the output.
-@item note
-Print verbose information about optimizations, such as certain
-transformations, more detailed messages about decisions etc.
-@item all
-Print detailed optimization information. This includes
-@samp{optimized}, @samp{missed}, and @samp{note}.
-@end table
-
-The following option controls the dump verbosity:
-
-@table @samp
-@item internals
-By default, only ``high-level'' messages are emitted. This option enables
-additional, more detailed, messages, which are likely to only be of interest
-to GCC developers.
-@end table
-
-One or more of the following option keywords can be used to describe a
-group of optimizations:
-
-@table @samp
-@item ipa
-Enable dumps from all interprocedural optimizations.
-@item loop
-Enable dumps from all loop optimizations.
-@item inline
-Enable dumps from all inlining optimizations.
-@item omp
-Enable dumps from all OMP (Offloading and Multi Processing) optimizations.
-@item vec
-Enable dumps from all vectorization optimizations.
-@item optall
-Enable dumps from all optimizations. This is a superset of
-the optimization groups listed above.
-@end table
-
-If @var{options} is
-omitted, it defaults to @samp{optimized-optall}, which means to dump messages
-about successful optimizations from all the passes, omitting messages
-that are treated as ``internals''.
-
-If the @var{filename} is provided, then the dumps from all the
-applicable optimizations are concatenated into the @var{filename}.
-Otherwise the dump is output onto @file{stderr}. Though multiple
-@option{-fopt-info} options are accepted, only one of them can include
-a @var{filename}. If other filenames are provided then all but the
-first such option are ignored.
-
-Note that the output @var{filename} is overwritten
-in case of multiple translation units. If a combined output from
-multiple translation units is desired, @file{stderr} should be used
-instead.
-
-In the following example, the optimization info is output to
-@file{stderr}:
-
-@smallexample
-gcc -O3 -fopt-info
-@end smallexample
-
-This example:
-@smallexample
-gcc -O3 -fopt-info-missed=missed.all
-@end smallexample
-
-@noindent
-outputs missed optimization report from all the passes into
-@file{missed.all}, and this one:
-
-@smallexample
-gcc -O2 -ftree-vectorize -fopt-info-vec-missed
-@end smallexample
-
-@noindent
-prints information about missed optimization opportunities from
-vectorization passes on @file{stderr}.
-Note that @option{-fopt-info-vec-missed} is equivalent to
-@option{-fopt-info-missed-vec}. The order of the optimization group
-names and message types listed after @option{-fopt-info} does not matter.
-
-As another example,
-@smallexample
-gcc -O3 -fopt-info-inline-optimized-missed=inline.txt
-@end smallexample
-
-@noindent
-outputs information about missed optimizations as well as
-optimized locations from all the inlining passes into
-@file{inline.txt}.
-
-Finally, consider:
-
-@smallexample
-gcc -fopt-info-vec-missed=vec.miss -fopt-info-loop-optimized=loop.opt
-@end smallexample
-
-@noindent
-Here the two output filenames @file{vec.miss} and @file{loop.opt} are
-in conflict since only one output file is allowed. In this case, only
-the first option takes effect and the subsequent options are
-ignored. Thus only @file{vec.miss} is produced which contains
-dumps from the vectorizer about missed opportunities.
-
-@item -fsave-optimization-record
-@opindex fsave-optimization-record
-Write a SRCFILE.opt-record.json.gz file detailing what optimizations
-were performed, for those optimizations that support @option{-fopt-info}.
-
-This option is experimental and the format of the data within the
-compressed JSON file is subject to change.
-
-It is roughly equivalent to a machine-readable version of
-@option{-fopt-info-all}, as a collection of messages with source file,
-line number and column number, with the following additional data for
-each message:
-
-@itemize @bullet
-
-@item
-the execution count of the code being optimized, along with metadata about
-whether this was from actual profile data, or just an estimate, allowing
-consumers to prioritize messages by code hotness,
-
-@item
-the function name of the code being optimized, where applicable,
-
-@item
-the ``inlining chain'' for the code being optimized, so that when
-a function is inlined into several different places (which might
-themselves be inlined), the reader can distinguish between the copies,
-
-@item
-objects identifying those parts of the message that refer to expressions,
-statements or symbol-table nodes, which of these categories they are, and,
-when available, their source code location,
-
-@item
-the GCC pass that emitted the message, and
-
-@item
-the location in GCC's own code from which the message was emitted
-
-@end itemize
-
-Additionally, some messages are logically nested within other
-messages, reflecting implementation details of the optimization
-passes.
-
-@item -fsched-verbose=@var{n}
-@opindex fsched-verbose
-On targets that use instruction scheduling, this option controls the
-amount of debugging output the scheduler prints to the dump files.
-
-For @var{n} greater than zero, @option{-fsched-verbose} outputs the
-same information as @option{-fdump-rtl-sched1} and @option{-fdump-rtl-sched2}.
-For @var{n} greater than one, it also output basic block probabilities,
-detailed ready list information and unit/insn info. For @var{n} greater
-than two, it includes RTL at abort point, control-flow and regions info.
-And for @var{n} over four, @option{-fsched-verbose} also includes
-dependence info.
-
-
-
-@item -fenable-@var{kind}-@var{pass}
-@itemx -fdisable-@var{kind}-@var{pass}=@var{range-list}
-@opindex fdisable-
-@opindex fenable-
-
-This is a set of options that are used to explicitly disable/enable
-optimization passes. These options are intended for use for debugging GCC.
-Compiler users should use regular options for enabling/disabling
-passes instead.
-
-@table @gcctabopt
-
-@item -fdisable-ipa-@var{pass}
-Disable IPA pass @var{pass}. @var{pass} is the pass name. If the same pass is
-statically invoked in the compiler multiple times, the pass name should be
-appended with a sequential number starting from 1.
-
-@item -fdisable-rtl-@var{pass}
-@itemx -fdisable-rtl-@var{pass}=@var{range-list}
-Disable RTL pass @var{pass}. @var{pass} is the pass name. If the same pass is
-statically invoked in the compiler multiple times, the pass name should be
-appended with a sequential number starting from 1. @var{range-list} is a
-comma-separated list of function ranges or assembler names. Each range is a number
-pair separated by a colon. The range is inclusive in both ends. If the range
-is trivial, the number pair can be simplified as a single number. If the
-function's call graph node's @var{uid} falls within one of the specified ranges,
-the @var{pass} is disabled for that function. The @var{uid} is shown in the
-function header of a dump file, and the pass names can be dumped by using
-option @option{-fdump-passes}.
-
-@item -fdisable-tree-@var{pass}
-@itemx -fdisable-tree-@var{pass}=@var{range-list}
-Disable tree pass @var{pass}. See @option{-fdisable-rtl} for the description of
-option arguments.
-
-@item -fenable-ipa-@var{pass}
-Enable IPA pass @var{pass}. @var{pass} is the pass name. If the same pass is
-statically invoked in the compiler multiple times, the pass name should be
-appended with a sequential number starting from 1.
-
-@item -fenable-rtl-@var{pass}
-@itemx -fenable-rtl-@var{pass}=@var{range-list}
-Enable RTL pass @var{pass}. See @option{-fdisable-rtl} for option argument
-description and examples.
-
-@item -fenable-tree-@var{pass}
-@itemx -fenable-tree-@var{pass}=@var{range-list}
-Enable tree pass @var{pass}. See @option{-fdisable-rtl} for the description
-of option arguments.
-
-@end table
-
-Here are some examples showing uses of these options.
-
-@smallexample
-
-# disable ccp1 for all functions
- -fdisable-tree-ccp1
-# disable complete unroll for function whose cgraph node uid is 1
- -fenable-tree-cunroll=1
-# disable gcse2 for functions at the following ranges [1,1],
-# [300,400], and [400,1000]
-# disable gcse2 for functions foo and foo2
- -fdisable-rtl-gcse2=foo,foo2
-# disable early inlining
- -fdisable-tree-einline
-# disable ipa inlining
- -fdisable-ipa-inline
-# enable tree full unroll
- -fenable-tree-unroll
-
-@end smallexample
-
-@item -fchecking
-@itemx -fchecking=@var{n}
-@opindex fchecking
-@opindex fno-checking
-Enable internal consistency checking. The default depends on
-the compiler configuration. @option{-fchecking=2} enables further
-internal consistency checking that might affect code generation.
-
-@item -frandom-seed=@var{string}
-@opindex frandom-seed
-This option provides a seed that GCC uses in place of
-random numbers in generating certain symbol names
-that have to be different in every compiled file. It is also used to
-place unique stamps in coverage data files and the object files that
-produce them. You can use the @option{-frandom-seed} option to produce
-reproducibly identical object files.
-
-The @var{string} can either be a number (decimal, octal or hex) or an
-arbitrary string (in which case it's converted to a number by
-computing CRC32).
-
-The @var{string} should be different for every file you compile.
-
-@item -save-temps
-@opindex save-temps
-Store the usual ``temporary'' intermediate files permanently; name them
-as auxiliary output files, as specified described under
-@option{-dumpbase} and @option{-dumpdir}.
-
-When used in combination with the @option{-x} command-line option,
-@option{-save-temps} is sensible enough to avoid overwriting an
-input source file with the same extension as an intermediate file.
-The corresponding intermediate file may be obtained by renaming the
-source file before using @option{-save-temps}.
-
-@item -save-temps=cwd
-@opindex save-temps=cwd
-Equivalent to @option{-save-temps -dumpdir ./}.
-
-@item -save-temps=obj
-@opindex save-temps=obj
-Equivalent to @option{-save-temps -dumpdir @file{outdir/}}, where
-@file{outdir/} is the directory of the output file specified after the
-@option{-o} option, including any directory separators. If the
-@option{-o} option is not used, the @option{-save-temps=obj} switch
-behaves like @option{-save-temps=cwd}.
-
-@item -time@r{[}=@var{file}@r{]}
-@opindex time
-Report the CPU time taken by each subprocess in the compilation
-sequence. For C source files, this is the compiler proper and assembler
-(plus the linker if linking is done).
-
-Without the specification of an output file, the output looks like this:
-
-@smallexample
-# cc1 0.12 0.01
-# as 0.00 0.01
-@end smallexample
-
-The first number on each line is the ``user time'', that is time spent
-executing the program itself. The second number is ``system time'',
-time spent executing operating system routines on behalf of the program.
-Both numbers are in seconds.
-
-With the specification of an output file, the output is appended to the
-named file, and it looks like this:
-
-@smallexample
-0.12 0.01 cc1 @var{options}
-0.00 0.01 as @var{options}
-@end smallexample
-
-The ``user time'' and the ``system time'' are moved before the program
-name, and the options passed to the program are displayed, so that one
-can later tell what file was being compiled, and with which options.
-
-@item -fdump-final-insns@r{[}=@var{file}@r{]}
-@opindex fdump-final-insns
-Dump the final internal representation (RTL) to @var{file}. If the
-optional argument is omitted (or if @var{file} is @code{.}), the name
-of the dump file is determined by appending @code{.gkd} to the
-dump base name, see @option{-dumpbase}.
-
-@item -fcompare-debug@r{[}=@var{opts}@r{]}
-@opindex fcompare-debug
-@opindex fno-compare-debug
-If no error occurs during compilation, run the compiler a second time,
-adding @var{opts} and @option{-fcompare-debug-second} to the arguments
-passed to the second compilation. Dump the final internal
-representation in both compilations, and print an error if they differ.
-
-If the equal sign is omitted, the default @option{-gtoggle} is used.
-
-The environment variable @env{GCC_COMPARE_DEBUG}, if defined, non-empty
-and nonzero, implicitly enables @option{-fcompare-debug}. If
-@env{GCC_COMPARE_DEBUG} is defined to a string starting with a dash,
-then it is used for @var{opts}, otherwise the default @option{-gtoggle}
-is used.
-
-@option{-fcompare-debug=}, with the equal sign but without @var{opts},
-is equivalent to @option{-fno-compare-debug}, which disables the dumping
-of the final representation and the second compilation, preventing even
-@env{GCC_COMPARE_DEBUG} from taking effect.
-
-To verify full coverage during @option{-fcompare-debug} testing, set
-@env{GCC_COMPARE_DEBUG} to say @option{-fcompare-debug-not-overridden},
-which GCC rejects as an invalid option in any actual compilation
-(rather than preprocessing, assembly or linking). To get just a
-warning, setting @env{GCC_COMPARE_DEBUG} to @samp{-w%n-fcompare-debug
-not overridden} will do.
-
-@item -fcompare-debug-second
-@opindex fcompare-debug-second
-This option is implicitly passed to the compiler for the second
-compilation requested by @option{-fcompare-debug}, along with options to
-silence warnings, and omitting other options that would cause the compiler
-to produce output to files or to standard output as a side effect. Dump
-files and preserved temporary files are renamed so as to contain the
-@code{.gk} additional extension during the second compilation, to avoid
-overwriting those generated by the first.
-
-When this option is passed to the compiler driver, it causes the
-@emph{first} compilation to be skipped, which makes it useful for little
-other than debugging the compiler proper.
-
-@item -gtoggle
-@opindex gtoggle
-Turn off generation of debug info, if leaving out this option
-generates it, or turn it on at level 2 otherwise. The position of this
-argument in the command line does not matter; it takes effect after all
-other options are processed, and it does so only once, no matter how
-many times it is given. This is mainly intended to be used with
-@option{-fcompare-debug}.
-
-@item -fvar-tracking-assignments-toggle
-@opindex fvar-tracking-assignments-toggle
-@opindex fno-var-tracking-assignments-toggle
-Toggle @option{-fvar-tracking-assignments}, in the same way that
-@option{-gtoggle} toggles @option{-g}.
-
-@item -Q
-@opindex Q
-Makes the compiler print out each function name as it is compiled, and
-print some statistics about each pass when it finishes.
-
-@item -ftime-report
-@opindex ftime-report
-Makes the compiler print some statistics about the time consumed by each
-pass when it finishes.
-
-@item -ftime-report-details
-@opindex ftime-report-details
-Record the time consumed by infrastructure parts separately for each pass.
-
-@item -fira-verbose=@var{n}
-@opindex fira-verbose
-Control the verbosity of the dump file for the integrated register allocator.
-The default value is 5. If the value @var{n} is greater or equal to 10,
-the dump output is sent to stderr using the same format as @var{n} minus 10.
-
-@item -flto-report
-@opindex flto-report
-Prints a report with internal details on the workings of the link-time
-optimizer. The contents of this report vary from version to version.
-It is meant to be useful to GCC developers when processing object
-files in LTO mode (via @option{-flto}).
-
-Disabled by default.
-
-@item -flto-report-wpa
-@opindex flto-report-wpa
-Like @option{-flto-report}, but only print for the WPA phase of link-time
-optimization.
-
-@item -fmem-report
-@opindex fmem-report
-Makes the compiler print some statistics about permanent memory
-allocation when it finishes.
-
-@item -fmem-report-wpa
-@opindex fmem-report-wpa
-Makes the compiler print some statistics about permanent memory
-allocation for the WPA phase only.
-
-@item -fpre-ipa-mem-report
-@opindex fpre-ipa-mem-report
-@item -fpost-ipa-mem-report
-@opindex fpost-ipa-mem-report
-Makes the compiler print some statistics about permanent memory
-allocation before or after interprocedural optimization.
-
-@item -fmultiflags
-@opindex fmultiflags
-This option enables multilib-aware @code{TFLAGS} to be used to build
-target libraries with options different from those the compiler is
-configured to use by default, through the use of specs (@xref{Spec
-Files}) set up by compiler internals, by the target, or by builders at
-configure time.
-
-Like @code{TFLAGS}, this allows the target libraries to be built for
-portable baseline environments, while the compiler defaults to more
-demanding ones. That's useful because users can easily override the
-defaults the compiler is configured to use to build their own programs,
-if the defaults are not ideal for their target environment, whereas
-rebuilding the runtime libraries is usually not as easy or desirable.
-
-Unlike @code{TFLAGS}, the use of specs enables different flags to be
-selected for different multilibs. The way to accomplish that is to
-build with @samp{make TFLAGS=-fmultiflags}, after configuring
-@samp{--with-specs=%@{fmultiflags:...@}}.
-
-This option is discarded by the driver once it's done processing driver
-self spec.
-
-It is also useful to check that @code{TFLAGS} are being used to build
-all target libraries, by configuring a non-bootstrap compiler
-@samp{--with-specs='%@{!fmultiflags:%emissing TFLAGS@}'} and building
-the compiler and target libraries.
-
-@item -fprofile-report
-@opindex fprofile-report
-Makes the compiler print some statistics about consistency of the
-(estimated) profile and effect of individual passes.
-
-@item -fstack-usage
-@opindex fstack-usage
-Makes the compiler output stack usage information for the program, on a
-per-function basis. The filename for the dump is made by appending
-@file{.su} to the @var{auxname}. @var{auxname} is generated from the name of
-the output file, if explicitly specified and it is not an executable,
-otherwise it is the basename of the source file. An entry is made up
-of three fields:
-
-@itemize
-@item
-The name of the function.
-@item
-A number of bytes.
-@item
-One or more qualifiers: @code{static}, @code{dynamic}, @code{bounded}.
-@end itemize
-
-The qualifier @code{static} means that the function manipulates the stack
-statically: a fixed number of bytes are allocated for the frame on function
-entry and released on function exit; no stack adjustments are otherwise made
-in the function. The second field is this fixed number of bytes.
-
-The qualifier @code{dynamic} means that the function manipulates the stack
-dynamically: in addition to the static allocation described above, stack
-adjustments are made in the body of the function, for example to push/pop
-arguments around function calls. If the qualifier @code{bounded} is also
-present, the amount of these adjustments is bounded at compile time and
-the second field is an upper bound of the total amount of stack used by
-the function. If it is not present, the amount of these adjustments is
-not bounded at compile time and the second field only represents the
-bounded part.
-
-@item -fstats
-@opindex fstats
-Emit statistics about front-end processing at the end of the compilation.
-This option is supported only by the C++ front end, and
-the information is generally only useful to the G++ development team.
-
-@item -fdbg-cnt-list
-@opindex fdbg-cnt-list
-Print the name and the counter upper bound for all debug counters.
-
-
-@item -fdbg-cnt=@var{counter-value-list}
-@opindex fdbg-cnt
-Set the internal debug counter lower and upper bound. @var{counter-value-list}
-is a comma-separated list of @var{name}:@var{lower_bound1}-@var{upper_bound1}
-[:@var{lower_bound2}-@var{upper_bound2}...] tuples which sets
-the name of the counter and list of closed intervals.
-The @var{lower_bound} is optional and is zero
-initialized if not set.
-For example, with @option{-fdbg-cnt=dce:2-4:10-11,tail_call:10},
-@code{dbg_cnt(dce)} returns true only for second, third, fourth, tenth and
-eleventh invocation.
-For @code{dbg_cnt(tail_call)} true is returned for first 10 invocations.
-
-@item -print-file-name=@var{library}
-@opindex print-file-name
-Print the full absolute name of the library file @var{library} that
-would be used when linking---and don't do anything else. With this
-option, GCC does not compile or link anything; it just prints the
-file name.
-
-@item -print-multi-directory
-@opindex print-multi-directory
-Print the directory name corresponding to the multilib selected by any
-other switches present in the command line. This directory is supposed
-to exist in @env{GCC_EXEC_PREFIX}.
-
-@item -print-multi-lib
-@opindex print-multi-lib
-Print the mapping from multilib directory names to compiler switches
-that enable them. The directory name is separated from the switches by
-@samp{;}, and each switch starts with an @samp{@@} instead of the
-@samp{-}, without spaces between multiple switches. This is supposed to
-ease shell processing.
-
-@item -print-multi-os-directory
-@opindex print-multi-os-directory
-Print the path to OS libraries for the selected
-multilib, relative to some @file{lib} subdirectory. If OS libraries are
-present in the @file{lib} subdirectory and no multilibs are used, this is
-usually just @file{.}, if OS libraries are present in @file{lib@var{suffix}}
-sibling directories this prints e.g.@: @file{../lib64}, @file{../lib} or
-@file{../lib32}, or if OS libraries are present in @file{lib/@var{subdir}}
-subdirectories it prints e.g.@: @file{amd64}, @file{sparcv9} or @file{ev6}.
-
-@item -print-multiarch
-@opindex print-multiarch
-Print the path to OS libraries for the selected multiarch,
-relative to some @file{lib} subdirectory.
-
-@item -print-prog-name=@var{program}
-@opindex print-prog-name
-Like @option{-print-file-name}, but searches for a program such as @command{cpp}.
-
-@item -print-libgcc-file-name
-@opindex print-libgcc-file-name
-Same as @option{-print-file-name=libgcc.a}.
-
-This is useful when you use @option{-nostdlib} or @option{-nodefaultlibs}
-but you do want to link with @file{libgcc.a}. You can do:
-
-@smallexample
-gcc -nostdlib @var{files}@dots{} `gcc -print-libgcc-file-name`
-@end smallexample
-
-@item -print-search-dirs
-@opindex print-search-dirs
-Print the name of the configured installation directory and a list of
-program and library directories @command{gcc} searches---and don't do anything else.
-
-This is useful when @command{gcc} prints the error message
-@samp{installation problem, cannot exec cpp0: No such file or directory}.
-To resolve this you either need to put @file{cpp0} and the other compiler
-components where @command{gcc} expects to find them, or you can set the environment
-variable @env{GCC_EXEC_PREFIX} to the directory where you installed them.
-Don't forget the trailing @samp{/}.
-@xref{Environment Variables}.
-
-@item -print-sysroot
-@opindex print-sysroot
-Print the target sysroot directory that is used during
-compilation. This is the target sysroot specified either at configure
-time or using the @option{--sysroot} option, possibly with an extra
-suffix that depends on compilation options. If no target sysroot is
-specified, the option prints nothing.
-
-@item -print-sysroot-headers-suffix
-@opindex print-sysroot-headers-suffix
-Print the suffix added to the target sysroot when searching for
-headers, or give an error if the compiler is not configured with such
-a suffix---and don't do anything else.
-
-@item -dumpmachine
-@opindex dumpmachine
-Print the compiler's target machine (for example,
-@samp{i686-pc-linux-gnu})---and don't do anything else.
-
-@item -dumpversion
-@opindex dumpversion
-Print the compiler version (for example, @code{3.0}, @code{6.3.0} or @code{7})---and don't do
-anything else. This is the compiler version used in filesystem paths and
-specs. Depending on how the compiler has been configured it can be just
-a single number (major version), two numbers separated by a dot (major and
-minor version) or three numbers separated by dots (major, minor and patchlevel
-version).
-
-@item -dumpfullversion
-@opindex dumpfullversion
-Print the full compiler version---and don't do anything else. The output is
-always three numbers separated by dots, major, minor and patchlevel version.
-
-@item -dumpspecs
-@opindex dumpspecs
-Print the compiler's built-in specs---and don't do anything else. (This
-is used when GCC itself is being built.) @xref{Spec Files}.
-@end table
-
-@node Submodel Options
-@section Machine-Dependent Options
-@cindex submodel options
-@cindex specifying hardware config
-@cindex hardware models and configurations, specifying
-@cindex target-dependent options
-@cindex machine-dependent options
-
-Each target machine supported by GCC can have its own options---for
-example, to allow you to compile for a particular processor variant or
-ABI, or to control optimizations specific to that machine. By
-convention, the names of machine-specific options start with
-@samp{-m}.
-
-Some configurations of the compiler also support additional target-specific
-options, usually for compatibility with other compilers on the same
-platform.
-
-@c This list is ordered alphanumerically by subsection name.
-@c It should be the same order and spelling as these options are listed
-@c in Machine Dependent Options
-
-@menu
-* AArch64 Options::
-* Adapteva Epiphany Options::
-* AMD GCN Options::
-* ARC Options::
-* ARM Options::
-* AVR Options::
-* Blackfin Options::
-* C6X Options::
-* CRIS Options::
-* C-SKY Options::
-* Darwin Options::
-* DEC Alpha Options::
-* eBPF Options::
-* FR30 Options::
-* FT32 Options::
-* FRV Options::
-* GNU/Linux Options::
-* H8/300 Options::
-* HPPA Options::
-* IA-64 Options::
-* LM32 Options::
-* LoongArch Options::
-* M32C Options::
-* M32R/D Options::
-* M680x0 Options::
-* MCore Options::
-* MeP Options::
-* MicroBlaze Options::
-* MIPS Options::
-* MMIX Options::
-* MN10300 Options::
-* Moxie Options::
-* MSP430 Options::
-* NDS32 Options::
-* Nios II Options::
-* Nvidia PTX Options::
-* OpenRISC Options::
-* PDP-11 Options::
-* picoChip Options::
-* PowerPC Options::
-* PRU Options::
-* RISC-V Options::
-* RL78 Options::
-* RS/6000 and PowerPC Options::
-* RX Options::
-* S/390 and zSeries Options::
-* Score Options::
-* SH Options::
-* Solaris 2 Options::
-* SPARC Options::
-* System V Options::
-* V850 Options::
-* VAX Options::
-* Visium Options::
-* VMS Options::
-* VxWorks Options::
-* x86 Options::
-* x86 Windows Options::
-* Xstormy16 Options::
-* Xtensa Options::
-* zSeries Options::
-@end menu
-
-@node AArch64 Options
-@subsection AArch64 Options
-@cindex AArch64 Options
-
-These options are defined for AArch64 implementations:
-
-@table @gcctabopt
-
-@item -mabi=@var{name}
-@opindex mabi
-Generate code for the specified data model. Permissible values
-are @samp{ilp32} for SysV-like data model where int, long int and pointers
-are 32 bits, and @samp{lp64} for SysV-like data model where int is 32 bits,
-but long int and pointers are 64 bits.
-
-The default depends on the specific target configuration. Note that
-the LP64 and ILP32 ABIs are not link-compatible; you must compile your
-entire program with the same ABI, and link with a compatible set of libraries.
-
-@item -mbig-endian
-@opindex mbig-endian
-Generate big-endian code. This is the default when GCC is configured for an
-@samp{aarch64_be-*-*} target.
-
-@item -mgeneral-regs-only
-@opindex mgeneral-regs-only
-Generate code which uses only the general-purpose registers. This will prevent
-the compiler from using floating-point and Advanced SIMD registers but will not
-impose any restrictions on the assembler.
-
-@item -mlittle-endian
-@opindex mlittle-endian
-Generate little-endian code. This is the default when GCC is configured for an
-@samp{aarch64-*-*} but not an @samp{aarch64_be-*-*} target.
-
-@item -mcmodel=tiny
-@opindex mcmodel=tiny
-Generate code for the tiny code model. The program and its statically defined
-symbols must be within 1MB of each other. Programs can be statically or
-dynamically linked.
-
-@item -mcmodel=small
-@opindex mcmodel=small
-Generate code for the small code model. The program and its statically defined
-symbols must be within 4GB of each other. Programs can be statically or
-dynamically linked. This is the default code model.
-
-@item -mcmodel=large
-@opindex mcmodel=large
-Generate code for the large code model. This makes no assumptions about
-addresses and sizes of sections. Programs can be statically linked only. The
-@option{-mcmodel=large} option is incompatible with @option{-mabi=ilp32},
-@option{-fpic} and @option{-fPIC}.
-
-@item -mstrict-align
-@itemx -mno-strict-align
-@opindex mstrict-align
-@opindex mno-strict-align
-Avoid or allow generating memory accesses that may not be aligned on a natural
-object boundary as described in the architecture specification.
-
-@item -momit-leaf-frame-pointer
-@itemx -mno-omit-leaf-frame-pointer
-@opindex momit-leaf-frame-pointer
-@opindex mno-omit-leaf-frame-pointer
-Omit or keep the frame pointer in leaf functions. The former behavior is the
-default.
-
-@item -mstack-protector-guard=@var{guard}
-@itemx -mstack-protector-guard-reg=@var{reg}
-@itemx -mstack-protector-guard-offset=@var{offset}
-@opindex mstack-protector-guard
-@opindex mstack-protector-guard-reg
-@opindex mstack-protector-guard-offset
-Generate stack protection code using canary at @var{guard}. Supported
-locations are @samp{global} for a global canary or @samp{sysreg} for a
-canary in an appropriate system register.
-
-With the latter choice the options
-@option{-mstack-protector-guard-reg=@var{reg}} and
-@option{-mstack-protector-guard-offset=@var{offset}} furthermore specify
-which system register to use as base register for reading the canary,
-and from what offset from that base register. There is no default
-register or offset as this is entirely for use within the Linux
-kernel.
-
-@item -mtls-dialect=desc
-@opindex mtls-dialect=desc
-Use TLS descriptors as the thread-local storage mechanism for dynamic accesses
-of TLS variables. This is the default.
-
-@item -mtls-dialect=traditional
-@opindex mtls-dialect=traditional
-Use traditional TLS as the thread-local storage mechanism for dynamic accesses
-of TLS variables.
-
-@item -mtls-size=@var{size}
-@opindex mtls-size
-Specify bit size of immediate TLS offsets. Valid values are 12, 24, 32, 48.
-This option requires binutils 2.26 or newer.
-
-@item -mfix-cortex-a53-835769
-@itemx -mno-fix-cortex-a53-835769
-@opindex mfix-cortex-a53-835769
-@opindex mno-fix-cortex-a53-835769
-Enable or disable the workaround for the ARM Cortex-A53 erratum number 835769.
-This involves inserting a NOP instruction between memory instructions and
-64-bit integer multiply-accumulate instructions.
-
-@item -mfix-cortex-a53-843419
-@itemx -mno-fix-cortex-a53-843419
-@opindex mfix-cortex-a53-843419
-@opindex mno-fix-cortex-a53-843419
-Enable or disable the workaround for the ARM Cortex-A53 erratum number 843419.
-This erratum workaround is made at link time and this will only pass the
-corresponding flag to the linker.
-
-@item -mlow-precision-recip-sqrt
-@itemx -mno-low-precision-recip-sqrt
-@opindex mlow-precision-recip-sqrt
-@opindex mno-low-precision-recip-sqrt
-Enable or disable the reciprocal square root approximation.
-This option only has an effect if @option{-ffast-math} or
-@option{-funsafe-math-optimizations} is used as well. Enabling this reduces
-precision of reciprocal square root results to about 16 bits for
-single precision and to 32 bits for double precision.
-
-@item -mlow-precision-sqrt
-@itemx -mno-low-precision-sqrt
-@opindex mlow-precision-sqrt
-@opindex mno-low-precision-sqrt
-Enable or disable the square root approximation.
-This option only has an effect if @option{-ffast-math} or
-@option{-funsafe-math-optimizations} is used as well. Enabling this reduces
-precision of square root results to about 16 bits for
-single precision and to 32 bits for double precision.
-If enabled, it implies @option{-mlow-precision-recip-sqrt}.
-
-@item -mlow-precision-div
-@itemx -mno-low-precision-div
-@opindex mlow-precision-div
-@opindex mno-low-precision-div
-Enable or disable the division approximation.
-This option only has an effect if @option{-ffast-math} or
-@option{-funsafe-math-optimizations} is used as well. Enabling this reduces
-precision of division results to about 16 bits for
-single precision and to 32 bits for double precision.
-
-@item -mtrack-speculation
-@itemx -mno-track-speculation
-Enable or disable generation of additional code to track speculative
-execution through conditional branches. The tracking state can then
-be used by the compiler when expanding calls to
-@code{__builtin_speculation_safe_copy} to permit a more efficient code
-sequence to be generated.
-
-@item -moutline-atomics
-@itemx -mno-outline-atomics
-Enable or disable calls to out-of-line helpers to implement atomic operations.
-These helpers will, at runtime, determine if the LSE instructions from
-ARMv8.1-A can be used; if not, they will use the load/store-exclusive
-instructions that are present in the base ARMv8.0 ISA.
-
-This option is only applicable when compiling for the base ARMv8.0
-instruction set. If using a later revision, e.g. @option{-march=armv8.1-a}
-or @option{-march=armv8-a+lse}, the ARMv8.1-Atomics instructions will be
-used directly. The same applies when using @option{-mcpu=} when the
-selected cpu supports the @samp{lse} feature.
-This option is on by default.
-
-@item -march=@var{name}
-@opindex march
-Specify the name of the target architecture and, optionally, one or
-more feature modifiers. This option has the form
-@option{-march=@var{arch}@r{@{}+@r{[}no@r{]}@var{feature}@r{@}*}}.
-
-The table below summarizes the permissible values for @var{arch}
-and the features that they enable by default:
-
-@multitable @columnfractions 0.20 0.20 0.60
-@headitem @var{arch} value @tab Architecture @tab Includes by default
-@item @samp{armv8-a} @tab Armv8-A @tab @samp{+fp}, @samp{+simd}
-@item @samp{armv8.1-a} @tab Armv8.1-A @tab @samp{armv8-a}, @samp{+crc}, @samp{+lse}, @samp{+rdma}
-@item @samp{armv8.2-a} @tab Armv8.2-A @tab @samp{armv8.1-a}
-@item @samp{armv8.3-a} @tab Armv8.3-A @tab @samp{armv8.2-a}, @samp{+pauth}
-@item @samp{armv8.4-a} @tab Armv8.4-A @tab @samp{armv8.3-a}, @samp{+flagm}, @samp{+fp16fml}, @samp{+dotprod}
-@item @samp{armv8.5-a} @tab Armv8.5-A @tab @samp{armv8.4-a}, @samp{+sb}, @samp{+ssbs}, @samp{+predres}
-@item @samp{armv8.6-a} @tab Armv8.6-A @tab @samp{armv8.5-a}, @samp{+bf16}, @samp{+i8mm}
-@item @samp{armv8.7-a} @tab Armv8.7-A @tab @samp{armv8.6-a}, @samp{+ls64}
-@item @samp{armv8.8-a} @tab Armv8.8-a @tab @samp{armv8.7-a}, @samp{+mops}
-@item @samp{armv9-a} @tab Armv9-A @tab @samp{armv8.5-a}, @samp{+sve}, @samp{+sve2}
-@item @samp{armv9.1-a} @tab Armv9.1-A @tab @samp{armv9-a}, @samp{+bf16}, @samp{+i8mm}
-@item @samp{armv9.2-a} @tab Armv9.2-A @tab @samp{armv9.1-a}, @samp{+ls64}
-@item @samp{armv9.3-a} @tab Armv9.3-A @tab @samp{armv9.2-a}, @samp{+mops}
-@item @samp{armv8-r} @tab Armv8-R @tab @samp{armv8-r}
-@end multitable
-
-The value @samp{native} is available on native AArch64 GNU/Linux and
-causes the compiler to pick the architecture of the host system. This
-option has no effect if the compiler is unable to recognize the
-architecture of the host system,
-
-The permissible values for @var{feature} are listed in the sub-section
-on @ref{aarch64-feature-modifiers,,@option{-march} and @option{-mcpu}
-Feature Modifiers}. Where conflicting feature modifiers are
-specified, the right-most feature is used.
-
-GCC uses @var{name} to determine what kind of instructions it can emit
-when generating assembly code. If @option{-march} is specified
-without either of @option{-mtune} or @option{-mcpu} also being
-specified, the code is tuned to perform well across a range of target
-processors implementing the target architecture.
-
-@item -mtune=@var{name}
-@opindex mtune
-Specify the name of the target processor for which GCC should tune the
-performance of the code. Permissible values for this option are:
-@samp{generic}, @samp{cortex-a35}, @samp{cortex-a53}, @samp{cortex-a55},
-@samp{cortex-a57}, @samp{cortex-a72}, @samp{cortex-a73}, @samp{cortex-a75},
-@samp{cortex-a76}, @samp{cortex-a76ae}, @samp{cortex-a77},
-@samp{cortex-a65}, @samp{cortex-a65ae}, @samp{cortex-a34},
-@samp{cortex-a78}, @samp{cortex-a78ae}, @samp{cortex-a78c},
-@samp{ares}, @samp{exynos-m1}, @samp{emag}, @samp{falkor},
-@samp{neoverse-512tvb}, @samp{neoverse-e1}, @samp{neoverse-n1},
-@samp{neoverse-n2}, @samp{neoverse-v1}, @samp{neoverse-v2}, @samp{qdf24xx},
-@samp{saphira}, @samp{phecda}, @samp{xgene1}, @samp{vulcan},
-@samp{octeontx}, @samp{octeontx81}, @samp{octeontx83},
-@samp{octeontx2}, @samp{octeontx2t98}, @samp{octeontx2t96}
-@samp{octeontx2t93}, @samp{octeontx2f95}, @samp{octeontx2f95n},
-@samp{octeontx2f95mm},
-@samp{a64fx},
-@samp{thunderx}, @samp{thunderxt88},
-@samp{thunderxt88p1}, @samp{thunderxt81}, @samp{tsv110},
-@samp{thunderxt83}, @samp{thunderx2t99}, @samp{thunderx3t110}, @samp{zeus},
-@samp{cortex-a57.cortex-a53}, @samp{cortex-a72.cortex-a53},
-@samp{cortex-a73.cortex-a35}, @samp{cortex-a73.cortex-a53},
-@samp{cortex-a75.cortex-a55}, @samp{cortex-a76.cortex-a55},
-@samp{cortex-r82}, @samp{cortex-x1}, @samp{cortex-x2},
-@samp{cortex-a510}, @samp{cortex-a710}, @samp{ampere1}, @samp{native}.
-
-The values @samp{cortex-a57.cortex-a53}, @samp{cortex-a72.cortex-a53},
-@samp{cortex-a73.cortex-a35}, @samp{cortex-a73.cortex-a53},
-@samp{cortex-a75.cortex-a55}, @samp{cortex-a76.cortex-a55} specify that GCC
-should tune for a big.LITTLE system.
-
-The value @samp{neoverse-512tvb} specifies that GCC should tune
-for Neoverse cores that (a) implement SVE and (b) have a total vector
-bandwidth of 512 bits per cycle. In other words, the option tells GCC to
-tune for Neoverse cores that can execute 4 128-bit Advanced SIMD arithmetic
-instructions a cycle and that can execute an equivalent number of SVE
-arithmetic instructions per cycle (2 for 256-bit SVE, 4 for 128-bit SVE).
-This is more general than tuning for a specific core like Neoverse V1
-but is more specific than the default tuning described below.
-
-Additionally on native AArch64 GNU/Linux systems the value
-@samp{native} tunes performance to the host system. This option has no effect
-if the compiler is unable to recognize the processor of the host system.
-
-Where none of @option{-mtune=}, @option{-mcpu=} or @option{-march=}
-are specified, the code is tuned to perform well across a range
-of target processors.
-
-This option cannot be suffixed by feature modifiers.
-
-@item -mcpu=@var{name}
-@opindex mcpu
-Specify the name of the target processor, optionally suffixed by one
-or more feature modifiers. This option has the form
-@option{-mcpu=@var{cpu}@r{@{}+@r{[}no@r{]}@var{feature}@r{@}*}}, where
-the permissible values for @var{cpu} are the same as those available
-for @option{-mtune}. The permissible values for @var{feature} are
-documented in the sub-section on
-@ref{aarch64-feature-modifiers,,@option{-march} and @option{-mcpu}
-Feature Modifiers}. Where conflicting feature modifiers are
-specified, the right-most feature is used.
-
-GCC uses @var{name} to determine what kind of instructions it can emit when
-generating assembly code (as if by @option{-march}) and to determine
-the target processor for which to tune for performance (as if
-by @option{-mtune}). Where this option is used in conjunction
-with @option{-march} or @option{-mtune}, those options take precedence
-over the appropriate part of this option.
-
-@option{-mcpu=neoverse-512tvb} is special in that it does not refer
-to a specific core, but instead refers to all Neoverse cores that
-(a) implement SVE and (b) have a total vector bandwidth of 512 bits
-a cycle. Unless overridden by @option{-march},
-@option{-mcpu=neoverse-512tvb} generates code that can run on a
-Neoverse V1 core, since Neoverse V1 is the first Neoverse core with
-these properties. Unless overridden by @option{-mtune},
-@option{-mcpu=neoverse-512tvb} tunes code in the same way as for
-@option{-mtune=neoverse-512tvb}.
-
-@item -moverride=@var{string}
-@opindex moverride
-Override tuning decisions made by the back-end in response to a
-@option{-mtune=} switch. The syntax, semantics, and accepted values
-for @var{string} in this option are not guaranteed to be consistent
-across releases.
-
-This option is only intended to be useful when developing GCC.
-
-@item -mverbose-cost-dump
-@opindex mverbose-cost-dump
-Enable verbose cost model dumping in the debug dump files. This option is
-provided for use in debugging the compiler.
-
-@item -mpc-relative-literal-loads
-@itemx -mno-pc-relative-literal-loads
-@opindex mpc-relative-literal-loads
-@opindex mno-pc-relative-literal-loads
-Enable or disable PC-relative literal loads. With this option literal pools are
-accessed using a single instruction and emitted after each function. This
-limits the maximum size of functions to 1MB. This is enabled by default for
-@option{-mcmodel=tiny}.
-
-@item -msign-return-address=@var{scope}
-@opindex msign-return-address
-Select the function scope on which return address signing will be applied.
-Permissible values are @samp{none}, which disables return address signing,
-@samp{non-leaf}, which enables pointer signing for functions which are not leaf
-functions, and @samp{all}, which enables pointer signing for all functions. The
-default value is @samp{none}. This option has been deprecated by
--mbranch-protection.
-
-@item -mbranch-protection=@var{none}|@var{standard}|@var{pac-ret}[+@var{leaf}+@var{b-key}]|@var{bti}
-@opindex mbranch-protection
-Select the branch protection features to use.
-@samp{none} is the default and turns off all types of branch protection.
-@samp{standard} turns on all types of branch protection features. If a feature
-has additional tuning options, then @samp{standard} sets it to its standard
-level.
-@samp{pac-ret[+@var{leaf}]} turns on return address signing to its standard
-level: signing functions that save the return address to memory (non-leaf
-functions will practically always do this) using the a-key. The optional
-argument @samp{leaf} can be used to extend the signing to include leaf
-functions. The optional argument @samp{b-key} can be used to sign the functions
-with the B-key instead of the A-key.
-@samp{bti} turns on branch target identification mechanism.
-
-@item -mharden-sls=@var{opts}
-@opindex mharden-sls
-Enable compiler hardening against straight line speculation (SLS).
-@var{opts} is a comma-separated list of the following options:
-@table @samp
-@item retbr
-@item blr
-@end table
-In addition, @samp{-mharden-sls=all} enables all SLS hardening while
-@samp{-mharden-sls=none} disables all SLS hardening.
-
-@item -msve-vector-bits=@var{bits}
-@opindex msve-vector-bits
-Specify the number of bits in an SVE vector register. This option only has
-an effect when SVE is enabled.
-
-GCC supports two forms of SVE code generation: ``vector-length
-agnostic'' output that works with any size of vector register and
-``vector-length specific'' output that allows GCC to make assumptions
-about the vector length when it is useful for optimization reasons.
-The possible values of @samp{bits} are: @samp{scalable}, @samp{128},
-@samp{256}, @samp{512}, @samp{1024} and @samp{2048}.
-Specifying @samp{scalable} selects vector-length agnostic
-output. At present @samp{-msve-vector-bits=128} also generates vector-length
-agnostic output for big-endian targets. All other values generate
-vector-length specific code. The behavior of these values may change
-in future releases and no value except @samp{scalable} should be
-relied on for producing code that is portable across different
-hardware SVE vector lengths.
-
-The default is @samp{-msve-vector-bits=scalable}, which produces
-vector-length agnostic code.
-@end table
-
-@subsubsection @option{-march} and @option{-mcpu} Feature Modifiers
-@anchor{aarch64-feature-modifiers}
-@cindex @option{-march} feature modifiers
-@cindex @option{-mcpu} feature modifiers
-Feature modifiers used with @option{-march} and @option{-mcpu} can be any of
-the following and their inverses @option{no@var{feature}}:
-
-@table @samp
-@item crc
-Enable CRC extension. This is on by default for
-@option{-march=armv8.1-a}.
-@item crypto
-Enable Crypto extension. This also enables Advanced SIMD and floating-point
-instructions.
-@item fp
-Enable floating-point instructions. This is on by default for all possible
-values for options @option{-march} and @option{-mcpu}.
-@item simd
-Enable Advanced SIMD instructions. This also enables floating-point
-instructions. This is on by default for all possible values for options
-@option{-march} and @option{-mcpu}.
-@item sve
-Enable Scalable Vector Extension instructions. This also enables Advanced
-SIMD and floating-point instructions.
-@item lse
-Enable Large System Extension instructions. This is on by default for
-@option{-march=armv8.1-a}.
-@item rdma
-Enable Round Double Multiply Accumulate instructions. This is on by default
-for @option{-march=armv8.1-a}.
-@item fp16
-Enable FP16 extension. This also enables floating-point instructions.
-@item fp16fml
-Enable FP16 fmla extension. This also enables FP16 extensions and
-floating-point instructions. This option is enabled by default for @option{-march=armv8.4-a}. Use of this option with architectures prior to Armv8.2-A is not supported.
-
-@item rcpc
-Enable the RcPc extension. This does not change code generation from GCC,
-but is passed on to the assembler, enabling inline asm statements to use
-instructions from the RcPc extension.
-@item dotprod
-Enable the Dot Product extension. This also enables Advanced SIMD instructions.
-@item aes
-Enable the Armv8-a aes and pmull crypto extension. This also enables Advanced
-SIMD instructions.
-@item sha2
-Enable the Armv8-a sha2 crypto extension. This also enables Advanced SIMD instructions.
-@item sha3
-Enable the sha512 and sha3 crypto extension. This also enables Advanced SIMD
-instructions. Use of this option with architectures prior to Armv8.2-A is not supported.
-@item sm4
-Enable the sm3 and sm4 crypto extension. This also enables Advanced SIMD instructions.
-Use of this option with architectures prior to Armv8.2-A is not supported.
-@item profile
-Enable the Statistical Profiling extension. This option is only to enable the
-extension at the assembler level and does not affect code generation.
-@item rng
-Enable the Armv8.5-a Random Number instructions. This option is only to
-enable the extension at the assembler level and does not affect code
-generation.
-@item memtag
-Enable the Armv8.5-a Memory Tagging Extensions.
-Use of this option with architectures prior to Armv8.5-A is not supported.
-@item sb
-Enable the Armv8-a Speculation Barrier instruction. This option is only to
-enable the extension at the assembler level and does not affect code
-generation. This option is enabled by default for @option{-march=armv8.5-a}.
-@item ssbs
-Enable the Armv8-a Speculative Store Bypass Safe instruction. This option
-is only to enable the extension at the assembler level and does not affect code
-generation. This option is enabled by default for @option{-march=armv8.5-a}.
-@item predres
-Enable the Armv8-a Execution and Data Prediction Restriction instructions.
-This option is only to enable the extension at the assembler level and does
-not affect code generation. This option is enabled by default for
-@option{-march=armv8.5-a}.
-@item sve2
-Enable the Armv8-a Scalable Vector Extension 2. This also enables SVE
-instructions.
-@item sve2-bitperm
-Enable SVE2 bitperm instructions. This also enables SVE2 instructions.
-@item sve2-sm4
-Enable SVE2 sm4 instructions. This also enables SVE2 instructions.
-@item sve2-aes
-Enable SVE2 aes instructions. This also enables SVE2 instructions.
-@item sve2-sha3
-Enable SVE2 sha3 instructions. This also enables SVE2 instructions.
-@item tme
-Enable the Transactional Memory Extension.
-@item i8mm
-Enable 8-bit Integer Matrix Multiply instructions. This also enables
-Advanced SIMD and floating-point instructions. This option is enabled by
-default for @option{-march=armv8.6-a}. Use of this option with architectures
-prior to Armv8.2-A is not supported.
-@item f32mm
-Enable 32-bit Floating point Matrix Multiply instructions. This also enables
-SVE instructions. Use of this option with architectures prior to Armv8.2-A is
-not supported.
-@item f64mm
-Enable 64-bit Floating point Matrix Multiply instructions. This also enables
-SVE instructions. Use of this option with architectures prior to Armv8.2-A is
-not supported.
-@item bf16
-Enable brain half-precision floating-point instructions. This also enables
-Advanced SIMD and floating-point instructions. This option is enabled by
-default for @option{-march=armv8.6-a}. Use of this option with architectures
-prior to Armv8.2-A is not supported.
-@item ls64
-Enable the 64-byte atomic load and store instructions for accelerators.
-This option is enabled by default for @option{-march=armv8.7-a}.
-@item mops
-Enable the instructions to accelerate memory operations like @code{memcpy},
-@code{memmove}, @code{memset}. This option is enabled by default for
-@option{-march=armv8.8-a}
-@item flagm
-Enable the Flag Manipulation instructions Extension.
-@item pauth
-Enable the Pointer Authentication Extension.
-
-@end table
-
-Feature @option{crypto} implies @option{aes}, @option{sha2}, and @option{simd},
-which implies @option{fp}.
-Conversely, @option{nofp} implies @option{nosimd}, which implies
-@option{nocrypto}, @option{noaes} and @option{nosha2}.
-
-@node Adapteva Epiphany Options
-@subsection Adapteva Epiphany Options
-
-These @samp{-m} options are defined for Adapteva Epiphany:
-
-@table @gcctabopt
-@item -mhalf-reg-file
-@opindex mhalf-reg-file
-Don't allocate any register in the range @code{r32}@dots{}@code{r63}.
-That allows code to run on hardware variants that lack these registers.
-
-@item -mprefer-short-insn-regs
-@opindex mprefer-short-insn-regs
-Preferentially allocate registers that allow short instruction generation.
-This can result in increased instruction count, so this may either reduce or
-increase overall code size.
-
-@item -mbranch-cost=@var{num}
-@opindex mbranch-cost
-Set the cost of branches to roughly @var{num} ``simple'' instructions.
-This cost is only a heuristic and is not guaranteed to produce
-consistent results across releases.
-
-@item -mcmove
-@opindex mcmove
-Enable the generation of conditional moves.
-
-@item -mnops=@var{num}
-@opindex mnops
-Emit @var{num} NOPs before every other generated instruction.
-
-@item -mno-soft-cmpsf
-@opindex mno-soft-cmpsf
-@opindex msoft-cmpsf
-For single-precision floating-point comparisons, emit an @code{fsub} instruction
-and test the flags. This is faster than a software comparison, but can
-get incorrect results in the presence of NaNs, or when two different small
-numbers are compared such that their difference is calculated as zero.
-The default is @option{-msoft-cmpsf}, which uses slower, but IEEE-compliant,
-software comparisons.
-
-@item -mstack-offset=@var{num}
-@opindex mstack-offset
-Set the offset between the top of the stack and the stack pointer.
-E.g., a value of 8 means that the eight bytes in the range @code{sp+0@dots{}sp+7}
-can be used by leaf functions without stack allocation.
-Values other than @samp{8} or @samp{16} are untested and unlikely to work.
-Note also that this option changes the ABI; compiling a program with a
-different stack offset than the libraries have been compiled with
-generally does not work.
-This option can be useful if you want to evaluate if a different stack
-offset would give you better code, but to actually use a different stack
-offset to build working programs, it is recommended to configure the
-toolchain with the appropriate @option{--with-stack-offset=@var{num}} option.
-
-@item -mno-round-nearest
-@opindex mno-round-nearest
-@opindex mround-nearest
-Make the scheduler assume that the rounding mode has been set to
-truncating. The default is @option{-mround-nearest}.
-
-@item -mlong-calls
-@opindex mlong-calls
-If not otherwise specified by an attribute, assume all calls might be beyond
-the offset range of the @code{b} / @code{bl} instructions, and therefore load the
-function address into a register before performing a (otherwise direct) call.
-This is the default.
-
-@item -mshort-calls
-@opindex short-calls
-If not otherwise specified by an attribute, assume all direct calls are
-in the range of the @code{b} / @code{bl} instructions, so use these instructions
-for direct calls. The default is @option{-mlong-calls}.
-
-@item -msmall16
-@opindex msmall16
-Assume addresses can be loaded as 16-bit unsigned values. This does not
-apply to function addresses for which @option{-mlong-calls} semantics
-are in effect.
-
-@item -mfp-mode=@var{mode}
-@opindex mfp-mode
-Set the prevailing mode of the floating-point unit.
-This determines the floating-point mode that is provided and expected
-at function call and return time. Making this mode match the mode you
-predominantly need at function start can make your programs smaller and
-faster by avoiding unnecessary mode switches.
-
-@var{mode} can be set to one the following values:
-
-@table @samp
-@item caller
-Any mode at function entry is valid, and retained or restored when
-the function returns, and when it calls other functions.
-This mode is useful for compiling libraries or other compilation units
-you might want to incorporate into different programs with different
-prevailing FPU modes, and the convenience of being able to use a single
-object file outweighs the size and speed overhead for any extra
-mode switching that might be needed, compared with what would be needed
-with a more specific choice of prevailing FPU mode.
-
-@item truncate
-This is the mode used for floating-point calculations with
-truncating (i.e.@: round towards zero) rounding mode. That includes
-conversion from floating point to integer.
-
-@item round-nearest
-This is the mode used for floating-point calculations with
-round-to-nearest-or-even rounding mode.
-
-@item int
-This is the mode used to perform integer calculations in the FPU, e.g.@:
-integer multiply, or integer multiply-and-accumulate.
-@end table
-
-The default is @option{-mfp-mode=caller}
-
-@item -mno-split-lohi
-@itemx -mno-postinc
-@itemx -mno-postmodify
-@opindex mno-split-lohi
-@opindex msplit-lohi
-@opindex mno-postinc
-@opindex mpostinc
-@opindex mno-postmodify
-@opindex mpostmodify
-Code generation tweaks that disable, respectively, splitting of 32-bit
-loads, generation of post-increment addresses, and generation of
-post-modify addresses. The defaults are @option{msplit-lohi},
-@option{-mpost-inc}, and @option{-mpost-modify}.
-
-@item -mnovect-double
-@opindex mno-vect-double
-@opindex mvect-double
-Change the preferred SIMD mode to SImode. The default is
-@option{-mvect-double}, which uses DImode as preferred SIMD mode.
-
-@item -max-vect-align=@var{num}
-@opindex max-vect-align
-The maximum alignment for SIMD vector mode types.
-@var{num} may be 4 or 8. The default is 8.
-Note that this is an ABI change, even though many library function
-interfaces are unaffected if they don't use SIMD vector modes
-in places that affect size and/or alignment of relevant types.
-
-@item -msplit-vecmove-early
-@opindex msplit-vecmove-early
-Split vector moves into single word moves before reload. In theory this
-can give better register allocation, but so far the reverse seems to be
-generally the case.
-
-@item -m1reg-@var{reg}
-@opindex m1reg-
-Specify a register to hold the constant @minus{}1, which makes loading small negative
-constants and certain bitmasks faster.
-Allowable values for @var{reg} are @samp{r43} and @samp{r63},
-which specify use of that register as a fixed register,
-and @samp{none}, which means that no register is used for this
-purpose. The default is @option{-m1reg-none}.
-
-@end table
-
-@node AMD GCN Options
-@subsection AMD GCN Options
-@cindex AMD GCN Options
-
-These options are defined specifically for the AMD GCN port.
-
-@table @gcctabopt
-
-@item -march=@var{gpu}
-@opindex march
-@itemx -mtune=@var{gpu}
-@opindex mtune
-Set architecture type or tuning for @var{gpu}. Supported values for @var{gpu}
-are
-
-@table @samp
-@item fiji
-Compile for GCN3 Fiji devices (gfx803).
-
-@item gfx900
-Compile for GCN5 Vega 10 devices (gfx900).
-
-@item gfx906
-Compile for GCN5 Vega 20 devices (gfx906).
-
-@item gfx908
-Compile for CDNA1 Instinct MI100 series devices (gfx908).
-
-@item gfx90a
-Compile for CDNA2 Instinct MI200 series devices (gfx90a).
-
-@end table
-
-@item -msram-ecc=on
-@itemx -msram-ecc=off
-@itemx -msram-ecc=any
-@opindex msram-ecc
-Compile binaries suitable for devices with the SRAM-ECC feature enabled,
-disabled, or either mode. This feature can be enabled per-process on some
-devices. The compiled code must match the device mode. The default is
-@samp{any}, for devices that support it.
-
-@item -mstack-size=@var{bytes}
-@opindex mstack-size
-Specify how many @var{bytes} of stack space will be requested for each GPU
-thread (wave-front). Beware that there may be many threads and limited memory
-available. The size of the stack allocation may also have an impact on
-run-time performance. The default is 32KB when using OpenACC or OpenMP, and
-1MB otherwise.
-
-@item -mxnack
-@opindex mxnack
-Compile binaries suitable for devices with the XNACK feature enabled. Some
-devices always require XNACK and some allow the user to configure XNACK. The
-compiled code must match the device mode. The default is @samp{-mno-xnack}.
-At present this option is a placeholder for support that is not yet
-implemented.
-
-@end table
-
-@node ARC Options
-@subsection ARC Options
-@cindex ARC options
-
-The following options control the architecture variant for which code
-is being compiled:
-
-@c architecture variants
-@table @gcctabopt
-
-@item -mbarrel-shifter
-@opindex mbarrel-shifter
-Generate instructions supported by barrel shifter. This is the default
-unless @option{-mcpu=ARC601} or @samp{-mcpu=ARCEM} is in effect.
-
-@item -mjli-always
-@opindex mjli-always
-Force to call a function using jli_s instruction. This option is
-valid only for ARCv2 architecture.
-
-@item -mcpu=@var{cpu}
-@opindex mcpu
-Set architecture type, register usage, and instruction scheduling
-parameters for @var{cpu}. There are also shortcut alias options
-available for backward compatibility and convenience. Supported
-values for @var{cpu} are
-
-@table @samp
-@opindex mA6
-@opindex mARC600
-@item arc600
-Compile for ARC600. Aliases: @option{-mA6}, @option{-mARC600}.
-
-@item arc601
-@opindex mARC601
-Compile for ARC601. Alias: @option{-mARC601}.
-
-@item arc700
-@opindex mA7
-@opindex mARC700
-Compile for ARC700. Aliases: @option{-mA7}, @option{-mARC700}.
-This is the default when configured with @option{--with-cpu=arc700}@.
-
-@item arcem
-Compile for ARC EM.
-
-@item archs
-Compile for ARC HS.
-
-@item em
-Compile for ARC EM CPU with no hardware extensions.
-
-@item em4
-Compile for ARC EM4 CPU.
-
-@item em4_dmips
-Compile for ARC EM4 DMIPS CPU.
-
-@item em4_fpus
-Compile for ARC EM4 DMIPS CPU with the single-precision floating-point
-extension.
-
-@item em4_fpuda
-Compile for ARC EM4 DMIPS CPU with single-precision floating-point and
-double assist instructions.
-
-@item hs
-Compile for ARC HS CPU with no hardware extensions except the atomic
-instructions.
-
-@item hs34
-Compile for ARC HS34 CPU.
-
-@item hs38
-Compile for ARC HS38 CPU.
-
-@item hs38_linux
-Compile for ARC HS38 CPU with all hardware extensions on.
-
-@item hs4x
-Compile for ARC HS4x CPU.
-
-@item hs4xd
-Compile for ARC HS4xD CPU.
-
-@item hs4x_rel31
-Compile for ARC HS4x CPU release 3.10a.
-
-@item arc600_norm
-Compile for ARC 600 CPU with @code{norm} instructions enabled.
-
-@item arc600_mul32x16
-Compile for ARC 600 CPU with @code{norm} and 32x16-bit multiply
-instructions enabled.
-
-@item arc600_mul64
-Compile for ARC 600 CPU with @code{norm} and @code{mul64}-family
-instructions enabled.
-
-@item arc601_norm
-Compile for ARC 601 CPU with @code{norm} instructions enabled.
-
-@item arc601_mul32x16
-Compile for ARC 601 CPU with @code{norm} and 32x16-bit multiply
-instructions enabled.
-
-@item arc601_mul64
-Compile for ARC 601 CPU with @code{norm} and @code{mul64}-family
-instructions enabled.
-
-@item nps400
-Compile for ARC 700 on NPS400 chip.
-
-@item em_mini
-Compile for ARC EM minimalist configuration featuring reduced register
-set.
-
-@end table
-
-@item -mdpfp
-@opindex mdpfp
-@itemx -mdpfp-compact
-@opindex mdpfp-compact
-Generate double-precision FPX instructions, tuned for the compact
-implementation.
-
-@item -mdpfp-fast
-@opindex mdpfp-fast
-Generate double-precision FPX instructions, tuned for the fast
-implementation.
-
-@item -mno-dpfp-lrsr
-@opindex mno-dpfp-lrsr
-Disable @code{lr} and @code{sr} instructions from using FPX extension
-aux registers.
-
-@item -mea
-@opindex mea
-Generate extended arithmetic instructions. Currently only
-@code{divaw}, @code{adds}, @code{subs}, and @code{sat16} are
-supported. Only valid for @option{-mcpu=ARC700}.
-
-@item -mno-mpy
-@opindex mno-mpy
-@opindex mmpy
-Do not generate @code{mpy}-family instructions for ARC700. This option is
-deprecated.
-
-@item -mmul32x16
-@opindex mmul32x16
-Generate 32x16-bit multiply and multiply-accumulate instructions.
-
-@item -mmul64
-@opindex mmul64
-Generate @code{mul64} and @code{mulu64} instructions.
-Only valid for @option{-mcpu=ARC600}.
-
-@item -mnorm
-@opindex mnorm
-Generate @code{norm} instructions. This is the default if @option{-mcpu=ARC700}
-is in effect.
-
-@item -mspfp
-@opindex mspfp
-@itemx -mspfp-compact
-@opindex mspfp-compact
-Generate single-precision FPX instructions, tuned for the compact
-implementation.
-
-@item -mspfp-fast
-@opindex mspfp-fast
-Generate single-precision FPX instructions, tuned for the fast
-implementation.
-
-@item -msimd
-@opindex msimd
-Enable generation of ARC SIMD instructions via target-specific
-builtins. Only valid for @option{-mcpu=ARC700}.
-
-@item -msoft-float
-@opindex msoft-float
-This option ignored; it is provided for compatibility purposes only.
-Software floating-point code is emitted by default, and this default
-can overridden by FPX options; @option{-mspfp}, @option{-mspfp-compact}, or
-@option{-mspfp-fast} for single precision, and @option{-mdpfp},
-@option{-mdpfp-compact}, or @option{-mdpfp-fast} for double precision.
-
-@item -mswap
-@opindex mswap
-Generate @code{swap} instructions.
-
-@item -matomic
-@opindex matomic
-This enables use of the locked load/store conditional extension to implement
-atomic memory built-in functions. Not available for ARC 6xx or ARC
-EM cores.
-
-@item -mdiv-rem
-@opindex mdiv-rem
-Enable @code{div} and @code{rem} instructions for ARCv2 cores.
-
-@item -mcode-density
-@opindex mcode-density
-Enable code density instructions for ARC EM.
-This option is on by default for ARC HS.
-
-@item -mll64
-@opindex mll64
-Enable double load/store operations for ARC HS cores.
-
-@item -mtp-regno=@var{regno}
-@opindex mtp-regno
-Specify thread pointer register number.
-
-@item -mmpy-option=@var{multo}
-@opindex mmpy-option
-Compile ARCv2 code with a multiplier design option. You can specify
-the option using either a string or numeric value for @var{multo}.
-@samp{wlh1} is the default value. The recognized values are:
-
-@table @samp
-@item 0
-@itemx none
-No multiplier available.
-
-@item 1
-@itemx w
-16x16 multiplier, fully pipelined.
-The following instructions are enabled: @code{mpyw} and @code{mpyuw}.
-
-@item 2
-@itemx wlh1
-32x32 multiplier, fully
-pipelined (1 stage). The following instructions are additionally
-enabled: @code{mpy}, @code{mpyu}, @code{mpym}, @code{mpymu}, and @code{mpy_s}.
-
-@item 3
-@itemx wlh2
-32x32 multiplier, fully pipelined
-(2 stages). The following instructions are additionally enabled: @code{mpy},
-@code{mpyu}, @code{mpym}, @code{mpymu}, and @code{mpy_s}.
-
-@item 4
-@itemx wlh3
-Two 16x16 multipliers, blocking,
-sequential. The following instructions are additionally enabled: @code{mpy},
-@code{mpyu}, @code{mpym}, @code{mpymu}, and @code{mpy_s}.
-
-@item 5
-@itemx wlh4
-One 16x16 multiplier, blocking,
-sequential. The following instructions are additionally enabled: @code{mpy},
-@code{mpyu}, @code{mpym}, @code{mpymu}, and @code{mpy_s}.
-
-@item 6
-@itemx wlh5
-One 32x4 multiplier, blocking,
-sequential. The following instructions are additionally enabled: @code{mpy},
-@code{mpyu}, @code{mpym}, @code{mpymu}, and @code{mpy_s}.
-
-@item 7
-@itemx plus_dmpy
-ARC HS SIMD support.
-
-@item 8
-@itemx plus_macd
-ARC HS SIMD support.
-
-@item 9
-@itemx plus_qmacw
-ARC HS SIMD support.
-
-@end table
-
-This option is only available for ARCv2 cores@.
-
-@item -mfpu=@var{fpu}
-@opindex mfpu
-Enables support for specific floating-point hardware extensions for ARCv2
-cores. Supported values for @var{fpu} are:
-
-@table @samp
-
-@item fpus
-Enables support for single-precision floating-point hardware
-extensions@.
-
-@item fpud
-Enables support for double-precision floating-point hardware
-extensions. The single-precision floating-point extension is also
-enabled. Not available for ARC EM@.
-
-@item fpuda
-Enables support for double-precision floating-point hardware
-extensions using double-precision assist instructions. The single-precision
-floating-point extension is also enabled. This option is
-only available for ARC EM@.
-
-@item fpuda_div
-Enables support for double-precision floating-point hardware
-extensions using double-precision assist instructions.
-The single-precision floating-point, square-root, and divide
-extensions are also enabled. This option is
-only available for ARC EM@.
-
-@item fpuda_fma
-Enables support for double-precision floating-point hardware
-extensions using double-precision assist instructions.
-The single-precision floating-point and fused multiply and add
-hardware extensions are also enabled. This option is
-only available for ARC EM@.
-
-@item fpuda_all
-Enables support for double-precision floating-point hardware
-extensions using double-precision assist instructions.
-All single-precision floating-point hardware extensions are also
-enabled. This option is only available for ARC EM@.
-
-@item fpus_div
-Enables support for single-precision floating-point, square-root and divide
-hardware extensions@.
-
-@item fpud_div
-Enables support for double-precision floating-point, square-root and divide
-hardware extensions. This option
-includes option @samp{fpus_div}. Not available for ARC EM@.
-
-@item fpus_fma
-Enables support for single-precision floating-point and
-fused multiply and add hardware extensions@.
-
-@item fpud_fma
-Enables support for double-precision floating-point and
-fused multiply and add hardware extensions. This option
-includes option @samp{fpus_fma}. Not available for ARC EM@.
-
-@item fpus_all
-Enables support for all single-precision floating-point hardware
-extensions@.
-
-@item fpud_all
-Enables support for all single- and double-precision floating-point
-hardware extensions. Not available for ARC EM@.
-
-@end table
-
-@item -mirq-ctrl-saved=@var{register-range}, @var{blink}, @var{lp_count}
-@opindex mirq-ctrl-saved
-Specifies general-purposes registers that the processor automatically
-saves/restores on interrupt entry and exit. @var{register-range} is
-specified as two registers separated by a dash. The register range
-always starts with @code{r0}, the upper limit is @code{fp} register.
-@var{blink} and @var{lp_count} are optional. This option is only
-valid for ARC EM and ARC HS cores.
-
-@item -mrgf-banked-regs=@var{number}
-@opindex mrgf-banked-regs
-Specifies the number of registers replicated in second register bank
-on entry to fast interrupt. Fast interrupts are interrupts with the
-highest priority level P0. These interrupts save only PC and STATUS32
-registers to avoid memory transactions during interrupt entry and exit
-sequences. Use this option when you are using fast interrupts in an
-ARC V2 family processor. Permitted values are 4, 8, 16, and 32.
-
-@item -mlpc-width=@var{width}
-@opindex mlpc-width
-Specify the width of the @code{lp_count} register. Valid values for
-@var{width} are 8, 16, 20, 24, 28 and 32 bits. The default width is
-fixed to 32 bits. If the width is less than 32, the compiler does not
-attempt to transform loops in your program to use the zero-delay loop
-mechanism unless it is known that the @code{lp_count} register can
-hold the required loop-counter value. Depending on the width
-specified, the compiler and run-time library might continue to use the
-loop mechanism for various needs. This option defines macro
-@code{__ARC_LPC_WIDTH__} with the value of @var{width}.
-
-@item -mrf16
-@opindex mrf16
-This option instructs the compiler to generate code for a 16-entry
-register file. This option defines the @code{__ARC_RF16__}
-preprocessor macro.
-
-@item -mbranch-index
-@opindex mbranch-index
-Enable use of @code{bi} or @code{bih} instructions to implement jump
-tables.
-
-@end table
-
-The following options are passed through to the assembler, and also
-define preprocessor macro symbols.
-
-@c Flags used by the assembler, but for which we define preprocessor
-@c macro symbols as well.
-@table @gcctabopt
-@item -mdsp-packa
-@opindex mdsp-packa
-Passed down to the assembler to enable the DSP Pack A extensions.
-Also sets the preprocessor symbol @code{__Xdsp_packa}. This option is
-deprecated.
-
-@item -mdvbf
-@opindex mdvbf
-Passed down to the assembler to enable the dual Viterbi butterfly
-extension. Also sets the preprocessor symbol @code{__Xdvbf}. This
-option is deprecated.
-
-@c ARC700 4.10 extension instruction
-@item -mlock
-@opindex mlock
-Passed down to the assembler to enable the locked load/store
-conditional extension. Also sets the preprocessor symbol
-@code{__Xlock}.
-
-@item -mmac-d16
-@opindex mmac-d16
-Passed down to the assembler. Also sets the preprocessor symbol
-@code{__Xxmac_d16}. This option is deprecated.
-
-@item -mmac-24
-@opindex mmac-24
-Passed down to the assembler. Also sets the preprocessor symbol
-@code{__Xxmac_24}. This option is deprecated.
-
-@c ARC700 4.10 extension instruction
-@item -mrtsc
-@opindex mrtsc
-Passed down to the assembler to enable the 64-bit time-stamp counter
-extension instruction. Also sets the preprocessor symbol
-@code{__Xrtsc}. This option is deprecated.
-
-@c ARC700 4.10 extension instruction
-@item -mswape
-@opindex mswape
-Passed down to the assembler to enable the swap byte ordering
-extension instruction. Also sets the preprocessor symbol
-@code{__Xswape}.
-
-@item -mtelephony
-@opindex mtelephony
-Passed down to the assembler to enable dual- and single-operand
-instructions for telephony. Also sets the preprocessor symbol
-@code{__Xtelephony}. This option is deprecated.
-
-@item -mxy
-@opindex mxy
-Passed down to the assembler to enable the XY memory extension. Also
-sets the preprocessor symbol @code{__Xxy}.
-
-@end table
-
-The following options control how the assembly code is annotated:
-
-@c Assembly annotation options
-@table @gcctabopt
-@item -misize
-@opindex misize
-Annotate assembler instructions with estimated addresses.
-
-@item -mannotate-align
-@opindex mannotate-align
-Explain what alignment considerations lead to the decision to make an
-instruction short or long.
-
-@end table
-
-The following options are passed through to the linker:
-
-@c options passed through to the linker
-@table @gcctabopt
-@item -marclinux
-@opindex marclinux
-Passed through to the linker, to specify use of the @code{arclinux} emulation.
-This option is enabled by default in tool chains built for
-@w{@code{arc-linux-uclibc}} and @w{@code{arceb-linux-uclibc}} targets
-when profiling is not requested.
-
-@item -marclinux_prof
-@opindex marclinux_prof
-Passed through to the linker, to specify use of the
-@code{arclinux_prof} emulation. This option is enabled by default in
-tool chains built for @w{@code{arc-linux-uclibc}} and
-@w{@code{arceb-linux-uclibc}} targets when profiling is requested.
-
-@end table
-
-The following options control the semantics of generated code:
-
-@c semantically relevant code generation options
-@table @gcctabopt
-@item -mlong-calls
-@opindex mlong-calls
-Generate calls as register indirect calls, thus providing access
-to the full 32-bit address range.
-
-@item -mmedium-calls
-@opindex mmedium-calls
-Don't use less than 25-bit addressing range for calls, which is the
-offset available for an unconditional branch-and-link
-instruction. Conditional execution of function calls is suppressed, to
-allow use of the 25-bit range, rather than the 21-bit range with
-conditional branch-and-link. This is the default for tool chains built
-for @w{@code{arc-linux-uclibc}} and @w{@code{arceb-linux-uclibc}} targets.
-
-@item -G @var{num}
-@opindex G
-Put definitions of externally-visible data in a small data section if
-that data is no bigger than @var{num} bytes. The default value of
-@var{num} is 4 for any ARC configuration, or 8 when we have double
-load/store operations.
-
-@item -mno-sdata
-@opindex mno-sdata
-@opindex msdata
-Do not generate sdata references. This is the default for tool chains
-built for @w{@code{arc-linux-uclibc}} and @w{@code{arceb-linux-uclibc}}
-targets.
-
-@item -mvolatile-cache
-@opindex mvolatile-cache
-Use ordinarily cached memory accesses for volatile references. This is the
-default.
-
-@item -mno-volatile-cache
-@opindex mno-volatile-cache
-@opindex mvolatile-cache
-Enable cache bypass for volatile references.
-
-@end table
-
-The following options fine tune code generation:
-@c code generation tuning options
-@table @gcctabopt
-@item -malign-call
-@opindex malign-call
-Does nothing. Preserved for backward compatibility.
-
-@item -mauto-modify-reg
-@opindex mauto-modify-reg
-Enable the use of pre/post modify with register displacement.
-
-@item -mbbit-peephole
-@opindex mbbit-peephole
-Enable bbit peephole2.
-
-@item -mno-brcc
-@opindex mno-brcc
-This option disables a target-specific pass in @file{arc_reorg} to
-generate compare-and-branch (@code{br@var{cc}}) instructions.
-It has no effect on
-generation of these instructions driven by the combiner pass.
-
-@item -mcase-vector-pcrel
-@opindex mcase-vector-pcrel
-Use PC-relative switch case tables to enable case table shortening.
-This is the default for @option{-Os}.
-
-@item -mcompact-casesi
-@opindex mcompact-casesi
-Enable compact @code{casesi} pattern. This is the default for @option{-Os},
-and only available for ARCv1 cores. This option is deprecated.
-
-@item -mno-cond-exec
-@opindex mno-cond-exec
-Disable the ARCompact-specific pass to generate conditional
-execution instructions.
-
-Due to delay slot scheduling and interactions between operand numbers,
-literal sizes, instruction lengths, and the support for conditional execution,
-the target-independent pass to generate conditional execution is often lacking,
-so the ARC port has kept a special pass around that tries to find more
-conditional execution generation opportunities after register allocation,
-branch shortening, and delay slot scheduling have been done. This pass
-generally, but not always, improves performance and code size, at the cost of
-extra compilation time, which is why there is an option to switch it off.
-If you have a problem with call instructions exceeding their allowable
-offset range because they are conditionalized, you should consider using
-@option{-mmedium-calls} instead.
-
-@item -mearly-cbranchsi
-@opindex mearly-cbranchsi
-Enable pre-reload use of the @code{cbranchsi} pattern.
-
-@item -mexpand-adddi
-@opindex mexpand-adddi
-Expand @code{adddi3} and @code{subdi3} at RTL generation time into
-@code{add.f}, @code{adc} etc. This option is deprecated.
-
-@item -mindexed-loads
-@opindex mindexed-loads
-Enable the use of indexed loads. This can be problematic because some
-optimizers then assume that indexed stores exist, which is not
-the case.
-
-@item -mlra
-@opindex mlra
-Enable Local Register Allocation. This is still experimental for ARC,
-so by default the compiler uses standard reload
-(i.e.@: @option{-mno-lra}).
-
-@item -mlra-priority-none
-@opindex mlra-priority-none
-Don't indicate any priority for target registers.
-
-@item -mlra-priority-compact
-@opindex mlra-priority-compact
-Indicate target register priority for r0..r3 / r12..r15.
-
-@item -mlra-priority-noncompact
-@opindex mlra-priority-noncompact
-Reduce target register priority for r0..r3 / r12..r15.
-
-@item -mmillicode
-@opindex mmillicode
-When optimizing for size (using @option{-Os}), prologues and epilogues
-that have to save or restore a large number of registers are often
-shortened by using call to a special function in libgcc; this is
-referred to as a @emph{millicode} call. As these calls can pose
-performance issues, and/or cause linking issues when linking in a
-nonstandard way, this option is provided to turn on or off millicode
-call generation.
-
-@item -mcode-density-frame
-@opindex mcode-density-frame
-This option enable the compiler to emit @code{enter} and @code{leave}
-instructions. These instructions are only valid for CPUs with
-code-density feature.
-
-@item -mmixed-code
-@opindex mmixed-code
-Does nothing. Preserved for backward compatibility.
-
-@item -mq-class
-@opindex mq-class
-Ths option is deprecated. Enable @samp{q} instruction alternatives.
-This is the default for @option{-Os}.
-
-@item -mRcq
-@opindex mRcq
-Does nothing. Preserved for backward compatibility.
-
-@item -mRcw
-@opindex mRcw
-Does nothing. Preserved for backward compatibility.
-
-@item -msize-level=@var{level}
-@opindex msize-level
-Fine-tune size optimization with regards to instruction lengths and alignment.
-The recognized values for @var{level} are:
-@table @samp
-@item 0
-No size optimization. This level is deprecated and treated like @samp{1}.
-
-@item 1
-Short instructions are used opportunistically.
-
-@item 2
-In addition, alignment of loops and of code after barriers are dropped.
-
-@item 3
-In addition, optional data alignment is dropped, and the option @option{Os} is enabled.
-
-@end table
-
-This defaults to @samp{3} when @option{-Os} is in effect. Otherwise,
-the behavior when this is not set is equivalent to level @samp{1}.
-
-@item -mtune=@var{cpu}
-@opindex mtune
-Set instruction scheduling parameters for @var{cpu}, overriding any implied
-by @option{-mcpu=}.
-
-Supported values for @var{cpu} are
-
-@table @samp
-@item ARC600
-Tune for ARC600 CPU.
-
-@item ARC601
-Tune for ARC601 CPU.
-
-@item ARC700
-Tune for ARC700 CPU with standard multiplier block.
-
-@item ARC700-xmac
-Tune for ARC700 CPU with XMAC block.
-
-@item ARC725D
-Tune for ARC725D CPU.
-
-@item ARC750D
-Tune for ARC750D CPU.
-
-@item core3
-Tune for ARCv2 core3 type CPU. This option enable usage of
-@code{dbnz} instruction.
-
-@item release31a
-Tune for ARC4x release 3.10a.
-
-@end table
-
-@item -mmultcost=@var{num}
-@opindex mmultcost
-Cost to assume for a multiply instruction, with @samp{4} being equal to a
-normal instruction.
-
-@item -munalign-prob-threshold=@var{probability}
-@opindex munalign-prob-threshold
-Does nothing. Preserved for backward compatibility.
-
-@end table
-
-The following options are maintained for backward compatibility, but
-are now deprecated and will be removed in a future release:
-
-@c Deprecated options
-@table @gcctabopt
-
-@item -margonaut
-@opindex margonaut
-Obsolete FPX.
-
-@item -mbig-endian
-@opindex mbig-endian
-@itemx -EB
-@opindex EB
-Compile code for big-endian targets. Use of these options is now
-deprecated. Big-endian code is supported by configuring GCC to build
-@w{@code{arceb-elf32}} and @w{@code{arceb-linux-uclibc}} targets,
-for which big endian is the default.
-
-@item -mlittle-endian
-@opindex mlittle-endian
-@itemx -EL
-@opindex EL
-Compile code for little-endian targets. Use of these options is now
-deprecated. Little-endian code is supported by configuring GCC to build
-@w{@code{arc-elf32}} and @w{@code{arc-linux-uclibc}} targets,
-for which little endian is the default.
-
-@item -mbarrel_shifter
-@opindex mbarrel_shifter
-Replaced by @option{-mbarrel-shifter}.
-
-@item -mdpfp_compact
-@opindex mdpfp_compact
-Replaced by @option{-mdpfp-compact}.
-
-@item -mdpfp_fast
-@opindex mdpfp_fast
-Replaced by @option{-mdpfp-fast}.
-
-@item -mdsp_packa
-@opindex mdsp_packa
-Replaced by @option{-mdsp-packa}.
-
-@item -mEA
-@opindex mEA
-Replaced by @option{-mea}.
-
-@item -mmac_24
-@opindex mmac_24
-Replaced by @option{-mmac-24}.
-
-@item -mmac_d16
-@opindex mmac_d16
-Replaced by @option{-mmac-d16}.
-
-@item -mspfp_compact
-@opindex mspfp_compact
-Replaced by @option{-mspfp-compact}.
-
-@item -mspfp_fast
-@opindex mspfp_fast
-Replaced by @option{-mspfp-fast}.
-
-@item -mtune=@var{cpu}
-@opindex mtune
-Values @samp{arc600}, @samp{arc601}, @samp{arc700} and
-@samp{arc700-xmac} for @var{cpu} are replaced by @samp{ARC600},
-@samp{ARC601}, @samp{ARC700} and @samp{ARC700-xmac} respectively.
-
-@item -multcost=@var{num}
-@opindex multcost
-Replaced by @option{-mmultcost}.
-
-@end table
-
-@node ARM Options
-@subsection ARM Options
-@cindex ARM options
-
-These @samp{-m} options are defined for the ARM port:
-
-@table @gcctabopt
-@item -mabi=@var{name}
-@opindex mabi
-Generate code for the specified ABI@. Permissible values are: @samp{apcs-gnu},
-@samp{atpcs}, @samp{aapcs}, @samp{aapcs-linux} and @samp{iwmmxt}.
-
-@item -mapcs-frame
-@opindex mapcs-frame
-Generate a stack frame that is compliant with the ARM Procedure Call
-Standard for all functions, even if this is not strictly necessary for
-correct execution of the code. Specifying @option{-fomit-frame-pointer}
-with this option causes the stack frames not to be generated for
-leaf functions. The default is @option{-mno-apcs-frame}.
-This option is deprecated.
-
-@item -mapcs
-@opindex mapcs
-This is a synonym for @option{-mapcs-frame} and is deprecated.
-
-@ignore
-@c not currently implemented
-@item -mapcs-stack-check
-@opindex mapcs-stack-check
-Generate code to check the amount of stack space available upon entry to
-every function (that actually uses some stack space). If there is
-insufficient space available then either the function
-@code{__rt_stkovf_split_small} or @code{__rt_stkovf_split_big} is
-called, depending upon the amount of stack space required. The runtime
-system is required to provide these functions. The default is
-@option{-mno-apcs-stack-check}, since this produces smaller code.
-
-@c not currently implemented
-@item -mapcs-reentrant
-@opindex mapcs-reentrant
-Generate reentrant, position-independent code. The default is
-@option{-mno-apcs-reentrant}.
-@end ignore
-
-@item -mthumb-interwork
-@opindex mthumb-interwork
-Generate code that supports calling between the ARM and Thumb
-instruction sets. Without this option, on pre-v5 architectures, the
-two instruction sets cannot be reliably used inside one program. The
-default is @option{-mno-thumb-interwork}, since slightly larger code
-is generated when @option{-mthumb-interwork} is specified. In AAPCS
-configurations this option is meaningless.
-
-@item -mno-sched-prolog
-@opindex mno-sched-prolog
-@opindex msched-prolog
-Prevent the reordering of instructions in the function prologue, or the
-merging of those instruction with the instructions in the function's
-body. This means that all functions start with a recognizable set
-of instructions (or in fact one of a choice from a small set of
-different function prologues), and this information can be used to
-locate the start of functions inside an executable piece of code. The
-default is @option{-msched-prolog}.
-
-@item -mfloat-abi=@var{name}
-@opindex mfloat-abi
-Specifies which floating-point ABI to use. Permissible values
-are: @samp{soft}, @samp{softfp} and @samp{hard}.
-
-Specifying @samp{soft} causes GCC to generate output containing
-library calls for floating-point operations.
-@samp{softfp} allows the generation of code using hardware floating-point
-instructions, but still uses the soft-float calling conventions.
-@samp{hard} allows generation of floating-point instructions
-and uses FPU-specific calling conventions.
-
-The default depends on the specific target configuration. Note that
-the hard-float and soft-float ABIs are not link-compatible; you must
-compile your entire program with the same ABI, and link with a
-compatible set of libraries.
-
-@item -mgeneral-regs-only
-@opindex mgeneral-regs-only
-Generate code which uses only the general-purpose registers. This will prevent
-the compiler from using floating-point and Advanced SIMD registers but will not
-impose any restrictions on the assembler.
-
-@item -mlittle-endian
-@opindex mlittle-endian
-Generate code for a processor running in little-endian mode. This is
-the default for all standard configurations.
-
-@item -mbig-endian
-@opindex mbig-endian
-Generate code for a processor running in big-endian mode; the default is
-to compile code for a little-endian processor.
-
-@item -mbe8
-@itemx -mbe32
-@opindex mbe8
-When linking a big-endian image select between BE8 and BE32 formats.
-The option has no effect for little-endian images and is ignored. The
-default is dependent on the selected target architecture. For ARMv6
-and later architectures the default is BE8, for older architectures
-the default is BE32. BE32 format has been deprecated by ARM.
-
-@item -march=@var{name}@r{[}+extension@dots{}@r{]}
-@opindex march
-This specifies the name of the target ARM architecture. GCC uses this
-name to determine what kind of instructions it can emit when generating
-assembly code. This option can be used in conjunction with or instead
-of the @option{-mcpu=} option.
-
-Permissible names are:
-@samp{armv4t},
-@samp{armv5t}, @samp{armv5te},
-@samp{armv6}, @samp{armv6j}, @samp{armv6k}, @samp{armv6kz}, @samp{armv6t2},
-@samp{armv6z}, @samp{armv6zk},
-@samp{armv7}, @samp{armv7-a}, @samp{armv7ve},
-@samp{armv8-a}, @samp{armv8.1-a}, @samp{armv8.2-a}, @samp{armv8.3-a},
-@samp{armv8.4-a},
-@samp{armv8.5-a},
-@samp{armv8.6-a},
-@samp{armv9-a},
-@samp{armv7-r},
-@samp{armv8-r},
-@samp{armv6-m}, @samp{armv6s-m},
-@samp{armv7-m}, @samp{armv7e-m},
-@samp{armv8-m.base}, @samp{armv8-m.main},
-@samp{armv8.1-m.main},
-@samp{armv9-a},
-@samp{iwmmxt} and @samp{iwmmxt2}.
-
-Additionally, the following architectures, which lack support for the
-Thumb execution state, are recognized but support is deprecated: @samp{armv4}.
-
-Many of the architectures support extensions. These can be added by
-appending @samp{+@var{extension}} to the architecture name. Extension
-options are processed in order and capabilities accumulate. An extension
-will also enable any necessary base extensions
-upon which it depends. For example, the @samp{+crypto} extension
-will always enable the @samp{+simd} extension. The exception to the
-additive construction is for extensions that are prefixed with
-@samp{+no@dots{}}: these extensions disable the specified option and
-any other extensions that may depend on the presence of that
-extension.
-
-For example, @samp{-march=armv7-a+simd+nofp+vfpv4} is equivalent to
-writing @samp{-march=armv7-a+vfpv4} since the @samp{+simd} option is
-entirely disabled by the @samp{+nofp} option that follows it.
-
-Most extension names are generically named, but have an effect that is
-dependent upon the architecture to which it is applied. For example,
-the @samp{+simd} option can be applied to both @samp{armv7-a} and
-@samp{armv8-a} architectures, but will enable the original ARMv7-A
-Advanced SIMD (Neon) extensions for @samp{armv7-a} and the ARMv8-A
-variant for @samp{armv8-a}.
-
-The table below lists the supported extensions for each architecture.
-Architectures not mentioned do not support any extensions.
-
-@table @samp
-@item armv5te
-@itemx armv6
-@itemx armv6j
-@itemx armv6k
-@itemx armv6kz
-@itemx armv6t2
-@itemx armv6z
-@itemx armv6zk
-@table @samp
-@item +fp
-The VFPv2 floating-point instructions. The extension @samp{+vfpv2} can be
-used as an alias for this extension.
-
-@item +nofp
-Disable the floating-point instructions.
-@end table
-
-@item armv7
-The common subset of the ARMv7-A, ARMv7-R and ARMv7-M architectures.
-@table @samp
-@item +fp
-The VFPv3 floating-point instructions, with 16 double-precision
-registers. The extension @samp{+vfpv3-d16} can be used as an alias
-for this extension. Note that floating-point is not supported by the
-base ARMv7-M architecture, but is compatible with both the ARMv7-A and
-ARMv7-R architectures.
-
-@item +nofp
-Disable the floating-point instructions.
-@end table
-
-@item armv7-a
-@table @samp
-@item +mp
-The multiprocessing extension.
-
-@item +sec
-The security extension.
-
-@item +fp
-The VFPv3 floating-point instructions, with 16 double-precision
-registers. The extension @samp{+vfpv3-d16} can be used as an alias
-for this extension.
-
-@item +simd
-The Advanced SIMD (Neon) v1 and the VFPv3 floating-point instructions.
-The extensions @samp{+neon} and @samp{+neon-vfpv3} can be used as aliases
-for this extension.
-
-@item +vfpv3
-The VFPv3 floating-point instructions, with 32 double-precision
-registers.
-
-@item +vfpv3-d16-fp16
-The VFPv3 floating-point instructions, with 16 double-precision
-registers and the half-precision floating-point conversion operations.
-
-@item +vfpv3-fp16
-The VFPv3 floating-point instructions, with 32 double-precision
-registers and the half-precision floating-point conversion operations.
-
-@item +vfpv4-d16
-The VFPv4 floating-point instructions, with 16 double-precision
-registers.
-
-@item +vfpv4
-The VFPv4 floating-point instructions, with 32 double-precision
-registers.
-
-@item +neon-fp16
-The Advanced SIMD (Neon) v1 and the VFPv3 floating-point instructions, with
-the half-precision floating-point conversion operations.
-
-@item +neon-vfpv4
-The Advanced SIMD (Neon) v2 and the VFPv4 floating-point instructions.
-
-@item +nosimd
-Disable the Advanced SIMD instructions (does not disable floating point).
-
-@item +nofp
-Disable the floating-point and Advanced SIMD instructions.
-@end table
-
-@item armv7ve
-The extended version of the ARMv7-A architecture with support for
-virtualization.
-@table @samp
-@item +fp
-The VFPv4 floating-point instructions, with 16 double-precision registers.
-The extension @samp{+vfpv4-d16} can be used as an alias for this extension.
-
-@item +simd
-The Advanced SIMD (Neon) v2 and the VFPv4 floating-point instructions. The
-extension @samp{+neon-vfpv4} can be used as an alias for this extension.
-
-@item +vfpv3-d16
-The VFPv3 floating-point instructions, with 16 double-precision
-registers.
-
-@item +vfpv3
-The VFPv3 floating-point instructions, with 32 double-precision
-registers.
-
-@item +vfpv3-d16-fp16
-The VFPv3 floating-point instructions, with 16 double-precision
-registers and the half-precision floating-point conversion operations.
-
-@item +vfpv3-fp16
-The VFPv3 floating-point instructions, with 32 double-precision
-registers and the half-precision floating-point conversion operations.
-
-@item +vfpv4-d16
-The VFPv4 floating-point instructions, with 16 double-precision
-registers.
-
-@item +vfpv4
-The VFPv4 floating-point instructions, with 32 double-precision
-registers.
-
-@item +neon
-The Advanced SIMD (Neon) v1 and the VFPv3 floating-point instructions.
-The extension @samp{+neon-vfpv3} can be used as an alias for this extension.
-
-@item +neon-fp16
-The Advanced SIMD (Neon) v1 and the VFPv3 floating-point instructions, with
-the half-precision floating-point conversion operations.
-
-@item +nosimd
-Disable the Advanced SIMD instructions (does not disable floating point).
-
-@item +nofp
-Disable the floating-point and Advanced SIMD instructions.
-@end table
-
-@item armv8-a
-@table @samp
-@item +crc
-The Cyclic Redundancy Check (CRC) instructions.
-@item +simd
-The ARMv8-A Advanced SIMD and floating-point instructions.
-@item +crypto
-The cryptographic instructions.
-@item +nocrypto
-Disable the cryptographic instructions.
-@item +nofp
-Disable the floating-point, Advanced SIMD and cryptographic instructions.
-@item +sb
-Speculation Barrier Instruction.
-@item +predres
-Execution and Data Prediction Restriction Instructions.
-@end table
-
-@item armv8.1-a
-@table @samp
-@item +simd
-The ARMv8.1-A Advanced SIMD and floating-point instructions.
-
-@item +crypto
-The cryptographic instructions. This also enables the Advanced SIMD and
-floating-point instructions.
-
-@item +nocrypto
-Disable the cryptographic instructions.
-
-@item +nofp
-Disable the floating-point, Advanced SIMD and cryptographic instructions.
-
-@item +sb
-Speculation Barrier Instruction.
-
-@item +predres
-Execution and Data Prediction Restriction Instructions.
-@end table
-
-@item armv8.2-a
-@itemx armv8.3-a
-@table @samp
-@item +fp16
-The half-precision floating-point data processing instructions.
-This also enables the Advanced SIMD and floating-point instructions.
-
-@item +fp16fml
-The half-precision floating-point fmla extension. This also enables
-the half-precision floating-point extension and Advanced SIMD and
-floating-point instructions.
-
-@item +simd
-The ARMv8.1-A Advanced SIMD and floating-point instructions.
-
-@item +crypto
-The cryptographic instructions. This also enables the Advanced SIMD and
-floating-point instructions.
-
-@item +dotprod
-Enable the Dot Product extension. This also enables Advanced SIMD instructions.
-
-@item +nocrypto
-Disable the cryptographic extension.
-
-@item +nofp
-Disable the floating-point, Advanced SIMD and cryptographic instructions.
-
-@item +sb
-Speculation Barrier Instruction.
-
-@item +predres
-Execution and Data Prediction Restriction Instructions.
-
-@item +i8mm
-8-bit Integer Matrix Multiply instructions.
-This also enables Advanced SIMD and floating-point instructions.
-
-@item +bf16
-Brain half-precision floating-point instructions.
-This also enables Advanced SIMD and floating-point instructions.
-@end table
-
-@item armv8.4-a
-@table @samp
-@item +fp16
-The half-precision floating-point data processing instructions.
-This also enables the Advanced SIMD and floating-point instructions as well
-as the Dot Product extension and the half-precision floating-point fmla
-extension.
-
-@item +simd
-The ARMv8.3-A Advanced SIMD and floating-point instructions as well as the
-Dot Product extension.
-
-@item +crypto
-The cryptographic instructions. This also enables the Advanced SIMD and
-floating-point instructions as well as the Dot Product extension.
-
-@item +nocrypto
-Disable the cryptographic extension.
-
-@item +nofp
-Disable the floating-point, Advanced SIMD and cryptographic instructions.
-
-@item +sb
-Speculation Barrier Instruction.
-
-@item +predres
-Execution and Data Prediction Restriction Instructions.
-
-@item +i8mm
-8-bit Integer Matrix Multiply instructions.
-This also enables Advanced SIMD and floating-point instructions.
-
-@item +bf16
-Brain half-precision floating-point instructions.
-This also enables Advanced SIMD and floating-point instructions.
-@end table
-
-@item armv8.5-a
-@table @samp
-@item +fp16
-The half-precision floating-point data processing instructions.
-This also enables the Advanced SIMD and floating-point instructions as well
-as the Dot Product extension and the half-precision floating-point fmla
-extension.
-
-@item +simd
-The ARMv8.3-A Advanced SIMD and floating-point instructions as well as the
-Dot Product extension.
-
-@item +crypto
-The cryptographic instructions. This also enables the Advanced SIMD and
-floating-point instructions as well as the Dot Product extension.
-
-@item +nocrypto
-Disable the cryptographic extension.
-
-@item +nofp
-Disable the floating-point, Advanced SIMD and cryptographic instructions.
-
-@item +i8mm
-8-bit Integer Matrix Multiply instructions.
-This also enables Advanced SIMD and floating-point instructions.
-
-@item +bf16
-Brain half-precision floating-point instructions.
-This also enables Advanced SIMD and floating-point instructions.
-@end table
-
-@item armv8.6-a
-@table @samp
-@item +fp16
-The half-precision floating-point data processing instructions.
-This also enables the Advanced SIMD and floating-point instructions as well
-as the Dot Product extension and the half-precision floating-point fmla
-extension.
-
-@item +simd
-The ARMv8.3-A Advanced SIMD and floating-point instructions as well as the
-Dot Product extension.
-
-@item +crypto
-The cryptographic instructions. This also enables the Advanced SIMD and
-floating-point instructions as well as the Dot Product extension.
-
-@item +nocrypto
-Disable the cryptographic extension.
-
-@item +nofp
-Disable the floating-point, Advanced SIMD and cryptographic instructions.
-
-@item +i8mm
-8-bit Integer Matrix Multiply instructions.
-This also enables Advanced SIMD and floating-point instructions.
-
-@item +bf16
-Brain half-precision floating-point instructions.
-This also enables Advanced SIMD and floating-point instructions.
-@end table
-
-@item armv7-r
-@table @samp
-@item +fp.sp
-The single-precision VFPv3 floating-point instructions. The extension
-@samp{+vfpv3xd} can be used as an alias for this extension.
-
-@item +fp
-The VFPv3 floating-point instructions with 16 double-precision registers.
-The extension +vfpv3-d16 can be used as an alias for this extension.
-
-@item +vfpv3xd-d16-fp16
-The single-precision VFPv3 floating-point instructions with 16 double-precision
-registers and the half-precision floating-point conversion operations.
-
-@item +vfpv3-d16-fp16
-The VFPv3 floating-point instructions with 16 double-precision
-registers and the half-precision floating-point conversion operations.
-
-@item +nofp
-Disable the floating-point extension.
-
-@item +idiv
-The ARM-state integer division instructions.
-
-@item +noidiv
-Disable the ARM-state integer division extension.
-@end table
-
-@item armv7e-m
-@table @samp
-@item +fp
-The single-precision VFPv4 floating-point instructions.
-
-@item +fpv5
-The single-precision FPv5 floating-point instructions.
-
-@item +fp.dp
-The single- and double-precision FPv5 floating-point instructions.
-
-@item +nofp
-Disable the floating-point extensions.
-@end table
-
-@item armv8.1-m.main
-@table @samp
-
-@item +dsp
-The DSP instructions.
-
-@item +mve
-The M-Profile Vector Extension (MVE) integer instructions.
-
-@item +mve.fp
-The M-Profile Vector Extension (MVE) integer and single precision
-floating-point instructions.
-
-@item +fp
-The single-precision floating-point instructions.
-
-@item +fp.dp
-The single- and double-precision floating-point instructions.
-
-@item +nofp
-Disable the floating-point extension.
-
-@item +cdecp0, +cdecp1, ... , +cdecp7
-Enable the Custom Datapath Extension (CDE) on selected coprocessors according
-to the numbers given in the options in the range 0 to 7.
-@end table
-
-@item armv8-m.main
-@table @samp
-@item +dsp
-The DSP instructions.
-
-@item +nodsp
-Disable the DSP extension.
-
-@item +fp
-The single-precision floating-point instructions.
-
-@item +fp.dp
-The single- and double-precision floating-point instructions.
-
-@item +nofp
-Disable the floating-point extension.
-
-@item +cdecp0, +cdecp1, ... , +cdecp7
-Enable the Custom Datapath Extension (CDE) on selected coprocessors according
-to the numbers given in the options in the range 0 to 7.
-@end table
-
-@item armv8-r
-@table @samp
-@item +crc
-The Cyclic Redundancy Check (CRC) instructions.
-@item +fp.sp
-The single-precision FPv5 floating-point instructions.
-@item +simd
-The ARMv8-A Advanced SIMD and floating-point instructions.
-@item +crypto
-The cryptographic instructions.
-@item +nocrypto
-Disable the cryptographic instructions.
-@item +nofp
-Disable the floating-point, Advanced SIMD and cryptographic instructions.
-@end table
-
-@end table
-
-@option{-march=native} causes the compiler to auto-detect the architecture
-of the build computer. At present, this feature is only supported on
-GNU/Linux, and not all architectures are recognized. If the auto-detect
-is unsuccessful the option has no effect.
-
-@item -mtune=@var{name}
-@opindex mtune
-This option specifies the name of the target ARM processor for
-which GCC should tune the performance of the code.
-For some ARM implementations better performance can be obtained by using
-this option.
-Permissible names are: @samp{arm7tdmi}, @samp{arm7tdmi-s}, @samp{arm710t},
-@samp{arm720t}, @samp{arm740t}, @samp{strongarm}, @samp{strongarm110},
-@samp{strongarm1100}, @samp{strongarm1110}, @samp{arm8}, @samp{arm810},
-@samp{arm9}, @samp{arm9e}, @samp{arm920}, @samp{arm920t}, @samp{arm922t},
-@samp{arm946e-s}, @samp{arm966e-s}, @samp{arm968e-s}, @samp{arm926ej-s},
-@samp{arm940t}, @samp{arm9tdmi}, @samp{arm10tdmi}, @samp{arm1020t},
-@samp{arm1026ej-s}, @samp{arm10e}, @samp{arm1020e}, @samp{arm1022e},
-@samp{arm1136j-s}, @samp{arm1136jf-s}, @samp{mpcore}, @samp{mpcorenovfp},
-@samp{arm1156t2-s}, @samp{arm1156t2f-s}, @samp{arm1176jz-s}, @samp{arm1176jzf-s},
-@samp{generic-armv7-a}, @samp{cortex-a5}, @samp{cortex-a7}, @samp{cortex-a8},
-@samp{cortex-a9}, @samp{cortex-a12}, @samp{cortex-a15}, @samp{cortex-a17},
-@samp{cortex-a32}, @samp{cortex-a35}, @samp{cortex-a53}, @samp{cortex-a55},
-@samp{cortex-a57}, @samp{cortex-a72}, @samp{cortex-a73}, @samp{cortex-a75},
-@samp{cortex-a76}, @samp{cortex-a76ae}, @samp{cortex-a77},
-@samp{cortex-a78}, @samp{cortex-a78ae}, @samp{cortex-a78c}, @samp{cortex-a710},
-@samp{ares}, @samp{cortex-r4}, @samp{cortex-r4f}, @samp{cortex-r5},
-@samp{cortex-r7}, @samp{cortex-r8}, @samp{cortex-r52}, @samp{cortex-r52plus},
-@samp{cortex-m0}, @samp{cortex-m0plus}, @samp{cortex-m1}, @samp{cortex-m3},
-@samp{cortex-m4}, @samp{cortex-m7}, @samp{cortex-m23}, @samp{cortex-m33},
-@samp{cortex-m35p}, @samp{cortex-m55}, @samp{cortex-x1},
-@samp{cortex-m1.small-multiply}, @samp{cortex-m0.small-multiply},
-@samp{cortex-m0plus.small-multiply}, @samp{exynos-m1}, @samp{marvell-pj4},
-@samp{neoverse-n1}, @samp{neoverse-n2}, @samp{neoverse-v1}, @samp{xscale},
-@samp{iwmmxt}, @samp{iwmmxt2}, @samp{ep9312}, @samp{fa526}, @samp{fa626},
-@samp{fa606te}, @samp{fa626te}, @samp{fmp626}, @samp{fa726te}, @samp{star-mc1},
-@samp{xgene1}.
-
-Additionally, this option can specify that GCC should tune the performance
-of the code for a big.LITTLE system. Permissible names are:
-@samp{cortex-a15.cortex-a7}, @samp{cortex-a17.cortex-a7},
-@samp{cortex-a57.cortex-a53}, @samp{cortex-a72.cortex-a53},
-@samp{cortex-a72.cortex-a35}, @samp{cortex-a73.cortex-a53},
-@samp{cortex-a75.cortex-a55}, @samp{cortex-a76.cortex-a55}.
-
-@option{-mtune=generic-@var{arch}} specifies that GCC should tune the
-performance for a blend of processors within architecture @var{arch}.
-The aim is to generate code that run well on the current most popular
-processors, balancing between optimizations that benefit some CPUs in the
-range, and avoiding performance pitfalls of other CPUs. The effects of
-this option may change in future GCC versions as CPU models come and go.
-
-@option{-mtune} permits the same extension options as @option{-mcpu}, but
-the extension options do not affect the tuning of the generated code.
-
-@option{-mtune=native} causes the compiler to auto-detect the CPU
-of the build computer. At present, this feature is only supported on
-GNU/Linux, and not all architectures are recognized. If the auto-detect is
-unsuccessful the option has no effect.
-
-@item -mcpu=@var{name}@r{[}+extension@dots{}@r{]}
-@opindex mcpu
-This specifies the name of the target ARM processor. GCC uses this name
-to derive the name of the target ARM architecture (as if specified
-by @option{-march}) and the ARM processor type for which to tune for
-performance (as if specified by @option{-mtune}). Where this option
-is used in conjunction with @option{-march} or @option{-mtune},
-those options take precedence over the appropriate part of this option.
-
-Many of the supported CPUs implement optional architectural
-extensions. Where this is so the architectural extensions are
-normally enabled by default. If implementations that lack the
-extension exist, then the extension syntax can be used to disable
-those extensions that have been omitted. For floating-point and
-Advanced SIMD (Neon) instructions, the settings of the options
-@option{-mfloat-abi} and @option{-mfpu} must also be considered:
-floating-point and Advanced SIMD instructions will only be used if
-@option{-mfloat-abi} is not set to @samp{soft}; and any setting of
-@option{-mfpu} other than @samp{auto} will override the available
-floating-point and SIMD extension instructions.
-
-For example, @samp{cortex-a9} can be found in three major
-configurations: integer only, with just a floating-point unit or with
-floating-point and Advanced SIMD. The default is to enable all the
-instructions, but the extensions @samp{+nosimd} and @samp{+nofp} can
-be used to disable just the SIMD or both the SIMD and floating-point
-instructions respectively.
-
-Permissible names for this option are the same as those for
-@option{-mtune}.
-
-The following extension options are common to the listed CPUs:
-
-@table @samp
-@item +nodsp
-Disable the DSP instructions on @samp{cortex-m33}, @samp{cortex-m35p}
-and @samp{cortex-m55}. Also disable the M-Profile Vector Extension (MVE)
-integer and single precision floating-point instructions on @samp{cortex-m55}.
-
-@item +nomve
-Disable the M-Profile Vector Extension (MVE) integer and single precision
-floating-point instructions on @samp{cortex-m55}.
-
-@item +nomve.fp
-Disable the M-Profile Vector Extension (MVE) single precision floating-point
-instructions on @samp{cortex-m55}.
-
-@item +nofp
-Disables the floating-point instructions on @samp{arm9e},
-@samp{arm946e-s}, @samp{arm966e-s}, @samp{arm968e-s}, @samp{arm10e},
-@samp{arm1020e}, @samp{arm1022e}, @samp{arm926ej-s},
-@samp{arm1026ej-s}, @samp{cortex-r5}, @samp{cortex-r7}, @samp{cortex-r8},
-@samp{cortex-m4}, @samp{cortex-m7}, @samp{cortex-m33}, @samp{cortex-m35p}
-and @samp{cortex-m55}.
-Disables the floating-point and SIMD instructions on
-@samp{generic-armv7-a}, @samp{cortex-a5}, @samp{cortex-a7},
-@samp{cortex-a8}, @samp{cortex-a9}, @samp{cortex-a12},
-@samp{cortex-a15}, @samp{cortex-a17}, @samp{cortex-a15.cortex-a7},
-@samp{cortex-a17.cortex-a7}, @samp{cortex-a32}, @samp{cortex-a35},
-@samp{cortex-a53} and @samp{cortex-a55}.
-
-@item +nofp.dp
-Disables the double-precision component of the floating-point instructions
-on @samp{cortex-r5}, @samp{cortex-r7}, @samp{cortex-r8}, @samp{cortex-r52},
-@samp{cortex-r52plus} and @samp{cortex-m7}.
-
-@item +nosimd
-Disables the SIMD (but not floating-point) instructions on
-@samp{generic-armv7-a}, @samp{cortex-a5}, @samp{cortex-a7}
-and @samp{cortex-a9}.
-
-@item +crypto
-Enables the cryptographic instructions on @samp{cortex-a32},
-@samp{cortex-a35}, @samp{cortex-a53}, @samp{cortex-a55}, @samp{cortex-a57},
-@samp{cortex-a72}, @samp{cortex-a73}, @samp{cortex-a75}, @samp{exynos-m1},
-@samp{xgene1}, @samp{cortex-a57.cortex-a53}, @samp{cortex-a72.cortex-a53},
-@samp{cortex-a73.cortex-a35}, @samp{cortex-a73.cortex-a53} and
-@samp{cortex-a75.cortex-a55}.
-@end table
-
-Additionally the @samp{generic-armv7-a} pseudo target defaults to
-VFPv3 with 16 double-precision registers. It supports the following
-extension options: @samp{mp}, @samp{sec}, @samp{vfpv3-d16},
-@samp{vfpv3}, @samp{vfpv3-d16-fp16}, @samp{vfpv3-fp16},
-@samp{vfpv4-d16}, @samp{vfpv4}, @samp{neon}, @samp{neon-vfpv3},
-@samp{neon-fp16}, @samp{neon-vfpv4}. The meanings are the same as for
-the extensions to @option{-march=armv7-a}.
-
-@option{-mcpu=generic-@var{arch}} is also permissible, and is
-equivalent to @option{-march=@var{arch} -mtune=generic-@var{arch}}.
-See @option{-mtune} for more information.
-
-@option{-mcpu=native} causes the compiler to auto-detect the CPU
-of the build computer. At present, this feature is only supported on
-GNU/Linux, and not all architectures are recognized. If the auto-detect
-is unsuccessful the option has no effect.
-
-@item -mfpu=@var{name}
-@opindex mfpu
-This specifies what floating-point hardware (or hardware emulation) is
-available on the target. Permissible names are: @samp{auto}, @samp{vfpv2},
-@samp{vfpv3},
-@samp{vfpv3-fp16}, @samp{vfpv3-d16}, @samp{vfpv3-d16-fp16}, @samp{vfpv3xd},
-@samp{vfpv3xd-fp16}, @samp{neon-vfpv3}, @samp{neon-fp16}, @samp{vfpv4},
-@samp{vfpv4-d16}, @samp{fpv4-sp-d16}, @samp{neon-vfpv4},
-@samp{fpv5-d16}, @samp{fpv5-sp-d16},
-@samp{fp-armv8}, @samp{neon-fp-armv8} and @samp{crypto-neon-fp-armv8}.
-Note that @samp{neon} is an alias for @samp{neon-vfpv3} and @samp{vfp}
-is an alias for @samp{vfpv2}.
-
-The setting @samp{auto} is the default and is special. It causes the
-compiler to select the floating-point and Advanced SIMD instructions
-based on the settings of @option{-mcpu} and @option{-march}.
-
-If the selected floating-point hardware includes the NEON extension
-(e.g.@: @option{-mfpu=neon}), note that floating-point
-operations are not generated by GCC's auto-vectorization pass unless
-@option{-funsafe-math-optimizations} is also specified. This is
-because NEON hardware does not fully implement the IEEE 754 standard for
-floating-point arithmetic (in particular denormal values are treated as
-zero), so the use of NEON instructions may lead to a loss of precision.
-
-You can also set the fpu name at function level by using the @code{target("fpu=")} function attributes (@pxref{ARM Function Attributes}) or pragmas (@pxref{Function Specific Option Pragmas}).
-
-@item -mfp16-format=@var{name}
-@opindex mfp16-format
-Specify the format of the @code{__fp16} half-precision floating-point type.
-Permissible names are @samp{none}, @samp{ieee}, and @samp{alternative};
-the default is @samp{none}, in which case the @code{__fp16} type is not
-defined. @xref{Half-Precision}, for more information.
-
-@item -mstructure-size-boundary=@var{n}
-@opindex mstructure-size-boundary
-The sizes of all structures and unions are rounded up to a multiple
-of the number of bits set by this option. Permissible values are 8, 32
-and 64. The default value varies for different toolchains. For the COFF
-targeted toolchain the default value is 8. A value of 64 is only allowed
-if the underlying ABI supports it.
-
-Specifying a larger number can produce faster, more efficient code, but
-can also increase the size of the program. Different values are potentially
-incompatible. Code compiled with one value cannot necessarily expect to
-work with code or libraries compiled with another value, if they exchange
-information using structures or unions.
-
-This option is deprecated.
-
-@item -mabort-on-noreturn
-@opindex mabort-on-noreturn
-Generate a call to the function @code{abort} at the end of a
-@code{noreturn} function. It is executed if the function tries to
-return.
-
-@item -mlong-calls
-@itemx -mno-long-calls
-@opindex mlong-calls
-@opindex mno-long-calls
-Tells the compiler to perform function calls by first loading the
-address of the function into a register and then performing a subroutine
-call on this register. This switch is needed if the target function
-lies outside of the 64-megabyte addressing range of the offset-based
-version of subroutine call instruction.
-
-Even if this switch is enabled, not all function calls are turned
-into long calls. The heuristic is that static functions, functions
-that have the @code{short_call} attribute, functions that are inside
-the scope of a @code{#pragma no_long_calls} directive, and functions whose
-definitions have already been compiled within the current compilation
-unit are not turned into long calls. The exceptions to this rule are
-that weak function definitions, functions with the @code{long_call}
-attribute or the @code{section} attribute, and functions that are within
-the scope of a @code{#pragma long_calls} directive are always
-turned into long calls.
-
-This feature is not enabled by default. Specifying
-@option{-mno-long-calls} restores the default behavior, as does
-placing the function calls within the scope of a @code{#pragma
-long_calls_off} directive. Note these switches have no effect on how
-the compiler generates code to handle function calls via function
-pointers.
-
-@item -msingle-pic-base
-@opindex msingle-pic-base
-Treat the register used for PIC addressing as read-only, rather than
-loading it in the prologue for each function. The runtime system is
-responsible for initializing this register with an appropriate value
-before execution begins.
-
-@item -mpic-register=@var{reg}
-@opindex mpic-register
-Specify the register to be used for PIC addressing.
-For standard PIC base case, the default is any suitable register
-determined by compiler. For single PIC base case, the default is
-@samp{R9} if target is EABI based or stack-checking is enabled,
-otherwise the default is @samp{R10}.
-
-@item -mpic-data-is-text-relative
-@opindex mpic-data-is-text-relative
-Assume that the displacement between the text and data segments is fixed
-at static link time. This permits using PC-relative addressing
-operations to access data known to be in the data segment. For
-non-VxWorks RTP targets, this option is enabled by default. When
-disabled on such targets, it will enable @option{-msingle-pic-base} by
-default.
-
-@item -mpoke-function-name
-@opindex mpoke-function-name
-Write the name of each function into the text section, directly
-preceding the function prologue. The generated code is similar to this:
-
-@smallexample
- t0
- .ascii "arm_poke_function_name", 0
- .align
- t1
- .word 0xff000000 + (t1 - t0)
- arm_poke_function_name
- mov ip, sp
- stmfd sp!, @{fp, ip, lr, pc@}
- sub fp, ip, #4
-@end smallexample
-
-When performing a stack backtrace, code can inspect the value of
-@code{pc} stored at @code{fp + 0}. If the trace function then looks at
-location @code{pc - 12} and the top 8 bits are set, then we know that
-there is a function name embedded immediately preceding this location
-and has length @code{((pc[-3]) & 0xff000000)}.
-
-@item -mthumb
-@itemx -marm
-@opindex marm
-@opindex mthumb
-
-Select between generating code that executes in ARM and Thumb
-states. The default for most configurations is to generate code
-that executes in ARM state, but the default can be changed by
-configuring GCC with the @option{--with-mode=}@var{state}
-configure option.
-
-You can also override the ARM and Thumb mode for each function
-by using the @code{target("thumb")} and @code{target("arm")} function attributes
-(@pxref{ARM Function Attributes}) or pragmas (@pxref{Function Specific Option Pragmas}).
-
-@item -mflip-thumb
-@opindex mflip-thumb
-Switch ARM/Thumb modes on alternating functions.
-This option is provided for regression testing of mixed Thumb/ARM code
-generation, and is not intended for ordinary use in compiling code.
-
-@item -mtpcs-frame
-@opindex mtpcs-frame
-Generate a stack frame that is compliant with the Thumb Procedure Call
-Standard for all non-leaf functions. (A leaf function is one that does
-not call any other functions.) The default is @option{-mno-tpcs-frame}.
-
-@item -mtpcs-leaf-frame
-@opindex mtpcs-leaf-frame
-Generate a stack frame that is compliant with the Thumb Procedure Call
-Standard for all leaf functions. (A leaf function is one that does
-not call any other functions.) The default is @option{-mno-apcs-leaf-frame}.
-
-@item -mcallee-super-interworking
-@opindex mcallee-super-interworking
-Gives all externally visible functions in the file being compiled an ARM
-instruction set header which switches to Thumb mode before executing the
-rest of the function. This allows these functions to be called from
-non-interworking code. This option is not valid in AAPCS configurations
-because interworking is enabled by default.
-
-@item -mcaller-super-interworking
-@opindex mcaller-super-interworking
-Allows calls via function pointers (including virtual functions) to
-execute correctly regardless of whether the target code has been
-compiled for interworking or not. There is a small overhead in the cost
-of executing a function pointer if this option is enabled. This option
-is not valid in AAPCS configurations because interworking is enabled
-by default.
-
-@item -mtp=@var{name}
-@opindex mtp
-Specify the access model for the thread local storage pointer. The valid
-models are @samp{soft}, which generates calls to @code{__aeabi_read_tp},
-@samp{cp15}, which fetches the thread pointer from @code{cp15} directly
-(supported in the arm6k architecture), and @samp{auto}, which uses the
-best available method for the selected processor. The default setting is
-@samp{auto}.
-
-@item -mtls-dialect=@var{dialect}
-@opindex mtls-dialect
-Specify the dialect to use for accessing thread local storage. Two
-@var{dialect}s are supported---@samp{gnu} and @samp{gnu2}. The
-@samp{gnu} dialect selects the original GNU scheme for supporting
-local and global dynamic TLS models. The @samp{gnu2} dialect
-selects the GNU descriptor scheme, which provides better performance
-for shared libraries. The GNU descriptor scheme is compatible with
-the original scheme, but does require new assembler, linker and
-library support. Initial and local exec TLS models are unaffected by
-this option and always use the original scheme.
-
-@item -mword-relocations
-@opindex mword-relocations
-Only generate absolute relocations on word-sized values (i.e.@: R_ARM_ABS32).
-This is enabled by default on targets (uClinux, SymbianOS) where the runtime
-loader imposes this restriction, and when @option{-fpic} or @option{-fPIC}
-is specified. This option conflicts with @option{-mslow-flash-data}.
-
-@item -mfix-cortex-m3-ldrd
-@opindex mfix-cortex-m3-ldrd
-Some Cortex-M3 cores can cause data corruption when @code{ldrd} instructions
-with overlapping destination and base registers are used. This option avoids
-generating these instructions. This option is enabled by default when
-@option{-mcpu=cortex-m3} is specified.
-
-@item -mfix-cortex-a57-aes-1742098
-@itemx -mno-fix-cortex-a57-aes-1742098
-@itemx -mfix-cortex-a72-aes-1655431
-@itemx -mno-fix-cortex-a72-aes-1655431
-Enable (disable) mitigation for an erratum on Cortex-A57 and
-Cortex-A72 that affects the AES cryptographic instructions. This
-option is enabled by default when either @option{-mcpu=cortex-a57} or
-@option{-mcpu=cortex-a72} is specified.
-
-@item -munaligned-access
-@itemx -mno-unaligned-access
-@opindex munaligned-access
-@opindex mno-unaligned-access
-Enables (or disables) reading and writing of 16- and 32- bit values
-from addresses that are not 16- or 32- bit aligned. By default
-unaligned access is disabled for all pre-ARMv6, all ARMv6-M and for
-ARMv8-M Baseline architectures, and enabled for all other
-architectures. If unaligned access is not enabled then words in packed
-data structures are accessed a byte at a time.
-
-The ARM attribute @code{Tag_CPU_unaligned_access} is set in the
-generated object file to either true or false, depending upon the
-setting of this option. If unaligned access is enabled then the
-preprocessor symbol @code{__ARM_FEATURE_UNALIGNED} is also
-defined.
-
-@item -mneon-for-64bits
-@opindex mneon-for-64bits
-This option is deprecated and has no effect.
-
-@item -mslow-flash-data
-@opindex mslow-flash-data
-Assume loading data from flash is slower than fetching instruction.
-Therefore literal load is minimized for better performance.
-This option is only supported when compiling for ARMv7 M-profile and
-off by default. It conflicts with @option{-mword-relocations}.
-
-@item -masm-syntax-unified
-@opindex masm-syntax-unified
-Assume inline assembler is using unified asm syntax. The default is
-currently off which implies divided syntax. This option has no impact
-on Thumb2. However, this may change in future releases of GCC.
-Divided syntax should be considered deprecated.
-
-@item -mrestrict-it
-@opindex mrestrict-it
-Restricts generation of IT blocks to conform to the rules of ARMv8-A.
-IT blocks can only contain a single 16-bit instruction from a select
-set of instructions. This option is on by default for ARMv8-A Thumb mode.
-
-@item -mprint-tune-info
-@opindex mprint-tune-info
-Print CPU tuning information as comment in assembler file. This is
-an option used only for regression testing of the compiler and not
-intended for ordinary use in compiling code. This option is disabled
-by default.
-
-@item -mverbose-cost-dump
-@opindex mverbose-cost-dump
-Enable verbose cost model dumping in the debug dump files. This option is
-provided for use in debugging the compiler.
-
-@item -mpure-code
-@opindex mpure-code
-Do not allow constant data to be placed in code sections.
-Additionally, when compiling for ELF object format give all text sections the
-ELF processor-specific section attribute @code{SHF_ARM_PURECODE}. This option
-is only available when generating non-pic code for M-profile targets.
-
-@item -mcmse
-@opindex mcmse
-Generate secure code as per the "ARMv8-M Security Extensions: Requirements on
-Development Tools Engineering Specification", which can be found on
-@url{https://developer.arm.com/documentation/ecm0359818/latest/}.
-
-@item -mfix-cmse-cve-2021-35465
-@opindex mfix-cmse-cve-2021-35465
-Mitigate against a potential security issue with the @code{VLLDM} instruction
-in some M-profile devices when using CMSE (CVE-2021-365465). This option is
-enabled by default when the option @option{-mcpu=} is used with
-@code{cortex-m33}, @code{cortex-m35p}, @code{cortex-m55} or @code{star-mc1}.
-The option @option{-mno-fix-cmse-cve-2021-35465} can be used to disable
-the mitigation.
-
-@item -mstack-protector-guard=@var{guard}
-@itemx -mstack-protector-guard-offset=@var{offset}
-@opindex mstack-protector-guard
-@opindex mstack-protector-guard-offset
-Generate stack protection code using canary at @var{guard}. Supported
-locations are @samp{global} for a global canary or @samp{tls} for a
-canary accessible via the TLS register. The option
-@option{-mstack-protector-guard-offset=} is for use with
-@option{-fstack-protector-guard=tls} and not for use in user-land code.
-
-@item -mfdpic
-@itemx -mno-fdpic
-@opindex mfdpic
-@opindex mno-fdpic
-Select the FDPIC ABI, which uses 64-bit function descriptors to
-represent pointers to functions. When the compiler is configured for
-@code{arm-*-uclinuxfdpiceabi} targets, this option is on by default
-and implies @option{-fPIE} if none of the PIC/PIE-related options is
-provided. On other targets, it only enables the FDPIC-specific code
-generation features, and the user should explicitly provide the
-PIC/PIE-related options as needed.
-
-Note that static linking is not supported because it would still
-involve the dynamic linker when the program self-relocates. If such
-behavior is acceptable, use -static and -Wl,-dynamic-linker options.
-
-The opposite @option{-mno-fdpic} option is useful (and required) to
-build the Linux kernel using the same (@code{arm-*-uclinuxfdpiceabi})
-toolchain as the one used to build the userland programs.
-
-@end table
-
-@node AVR Options
-@subsection AVR Options
-@cindex AVR Options
-
-These options are defined for AVR implementations:
-
-@table @gcctabopt
-@item -mmcu=@var{mcu}
-@opindex mmcu
-Specify Atmel AVR instruction set architectures (ISA) or MCU type.
-
-The default for this option is@tie{}@samp{avr2}.
-
-GCC supports the following AVR devices and ISAs:
-
-@include avr-mmcu.texi
-
-@item -mabsdata
-@opindex mabsdata
-
-Assume that all data in static storage can be accessed by LDS / STS
-instructions. This option has only an effect on reduced Tiny devices like
-ATtiny40. See also the @code{absdata}
-@ref{AVR Variable Attributes,variable attribute}.
-
-@item -maccumulate-args
-@opindex maccumulate-args
-Accumulate outgoing function arguments and acquire/release the needed
-stack space for outgoing function arguments once in function
-prologue/epilogue. Without this option, outgoing arguments are pushed
-before calling a function and popped afterwards.
-
-Popping the arguments after the function call can be expensive on
-AVR so that accumulating the stack space might lead to smaller
-executables because arguments need not be removed from the
-stack after such a function call.
-
-This option can lead to reduced code size for functions that perform
-several calls to functions that get their arguments on the stack like
-calls to printf-like functions.
-
-@item -mbranch-cost=@var{cost}
-@opindex mbranch-cost
-Set the branch costs for conditional branch instructions to
-@var{cost}. Reasonable values for @var{cost} are small, non-negative
-integers. The default branch cost is 0.
-
-@item -mcall-prologues
-@opindex mcall-prologues
-Functions prologues/epilogues are expanded as calls to appropriate
-subroutines. Code size is smaller.
-
-@item -mdouble=@var{bits}
-@itemx -mlong-double=@var{bits}
-@opindex mdouble
-@opindex mlong-double
-Set the size (in bits) of the @code{double} or @code{long double} type,
-respectively. Possible values for @var{bits} are 32 and 64.
-Whether or not a specific value for @var{bits} is allowed depends on
-the @code{--with-double=} and @code{--with-long-double=}
-@w{@uref{https://gcc.gnu.org/install/configure.html#avr,configure options}},
-and the same applies for the default values of the options.
-
-@item -mgas-isr-prologues
-@opindex mgas-isr-prologues
-Interrupt service routines (ISRs) may use the @code{__gcc_isr} pseudo
-instruction supported by GNU Binutils.
-If this option is on, the feature can still be disabled for individual
-ISRs by means of the @ref{AVR Function Attributes,,@code{no_gccisr}}
-function attribute. This feature is activated per default
-if optimization is on (but not with @option{-Og}, @pxref{Optimize Options}),
-and if GNU Binutils support @w{@uref{https://sourceware.org/PR21683,PR21683}}.
-
-@item -mint8
-@opindex mint8
-Assume @code{int} to be 8-bit integer. This affects the sizes of all types: a
-@code{char} is 1 byte, an @code{int} is 1 byte, a @code{long} is 2 bytes,
-and @code{long long} is 4 bytes. Please note that this option does not
-conform to the C standards, but it results in smaller code
-size.
-
-@item -mmain-is-OS_task
-@opindex mmain-is-OS_task
-Do not save registers in @code{main}. The effect is the same like
-attaching attribute @ref{AVR Function Attributes,,@code{OS_task}}
-to @code{main}. It is activated per default if optimization is on.
-
-@item -mn-flash=@var{num}
-@opindex mn-flash
-Assume that the flash memory has a size of
-@var{num} times 64@tie{}KiB.
-
-@item -mno-interrupts
-@opindex mno-interrupts
-Generated code is not compatible with hardware interrupts.
-Code size is smaller.
-
-@item -mrelax
-@opindex mrelax
-Try to replace @code{CALL} resp.@: @code{JMP} instruction by the shorter
-@code{RCALL} resp.@: @code{RJMP} instruction if applicable.
-Setting @option{-mrelax} just adds the @option{--mlink-relax} option to
-the assembler's command line and the @option{--relax} option to the
-linker's command line.
-
-Jump relaxing is performed by the linker because jump offsets are not
-known before code is located. Therefore, the assembler code generated by the
-compiler is the same, but the instructions in the executable may
-differ from instructions in the assembler code.
-
-Relaxing must be turned on if linker stubs are needed, see the
-section on @code{EIND} and linker stubs below.
-
-@item -mrmw
-@opindex mrmw
-Assume that the device supports the Read-Modify-Write
-instructions @code{XCH}, @code{LAC}, @code{LAS} and @code{LAT}.
-
-@item -mshort-calls
-@opindex mshort-calls
-
-Assume that @code{RJMP} and @code{RCALL} can target the whole
-program memory.
-
-This option is used internally for multilib selection. It is
-not an optimization option, and you don't need to set it by hand.
-
-@item -msp8
-@opindex msp8
-Treat the stack pointer register as an 8-bit register,
-i.e.@: assume the high byte of the stack pointer is zero.
-In general, you don't need to set this option by hand.
-
-This option is used internally by the compiler to select and
-build multilibs for architectures @code{avr2} and @code{avr25}.
-These architectures mix devices with and without @code{SPH}.
-For any setting other than @option{-mmcu=avr2} or @option{-mmcu=avr25}
-the compiler driver adds or removes this option from the compiler
-proper's command line, because the compiler then knows if the device
-or architecture has an 8-bit stack pointer and thus no @code{SPH}
-register or not.
-
-@item -mstrict-X
-@opindex mstrict-X
-Use address register @code{X} in a way proposed by the hardware. This means
-that @code{X} is only used in indirect, post-increment or
-pre-decrement addressing.
-
-Without this option, the @code{X} register may be used in the same way
-as @code{Y} or @code{Z} which then is emulated by additional
-instructions.
-For example, loading a value with @code{X+const} addressing with a
-small non-negative @code{const < 64} to a register @var{Rn} is
-performed as
-
-@example
-adiw r26, const ; X += const
-ld @var{Rn}, X ; @var{Rn} = *X
-sbiw r26, const ; X -= const
-@end example
-
-@item -mtiny-stack
-@opindex mtiny-stack
-Only change the lower 8@tie{}bits of the stack pointer.
-
-@item -mfract-convert-truncate
-@opindex mfract-convert-truncate
-Allow to use truncation instead of rounding towards zero for fractional fixed-point types.
-
-@item -nodevicelib
-@opindex nodevicelib
-Don't link against AVR-LibC's device specific library @code{lib<mcu>.a}.
-
-@item -nodevicespecs
-@opindex nodevicespecs
-Don't add @option{-specs=device-specs/specs-@var{mcu}} to the compiler driver's
-command line. The user takes responsibility for supplying the sub-processes
-like compiler proper, assembler and linker with appropriate command line
-options. This means that the user has to supply her private device specs
-file by means of @option{-specs=@var{path-to-specs-file}}. There is no
-more need for option @option{-mmcu=@var{mcu}}.
-
-This option can also serve as a replacement for the older way of
-specifying custom device-specs files that needed @option{-B @var{some-path}} to point to a directory
-which contains a folder named @code{device-specs} which contains a specs file named
-@code{specs-@var{mcu}}, where @var{mcu} was specified by @option{-mmcu=@var{mcu}}.
-
-@item -Waddr-space-convert
-@opindex Waddr-space-convert
-@opindex Wno-addr-space-convert
-Warn about conversions between address spaces in the case where the
-resulting address space is not contained in the incoming address space.
-
-@item -Wmisspelled-isr
-@opindex Wmisspelled-isr
-@opindex Wno-misspelled-isr
-Warn if the ISR is misspelled, i.e.@: without __vector prefix.
-Enabled by default.
-@end table
-
-@subsubsection @code{EIND} and Devices with More Than 128 Ki Bytes of Flash
-@cindex @code{EIND}
-Pointers in the implementation are 16@tie{}bits wide.
-The address of a function or label is represented as word address so
-that indirect jumps and calls can target any code address in the
-range of 64@tie{}Ki words.
-
-In order to facilitate indirect jump on devices with more than 128@tie{}Ki
-bytes of program memory space, there is a special function register called
-@code{EIND} that serves as most significant part of the target address
-when @code{EICALL} or @code{EIJMP} instructions are used.
-
-Indirect jumps and calls on these devices are handled as follows by
-the compiler and are subject to some limitations:
-
-@itemize @bullet
-
-@item
-The compiler never sets @code{EIND}.
-
-@item
-The compiler uses @code{EIND} implicitly in @code{EICALL}/@code{EIJMP}
-instructions or might read @code{EIND} directly in order to emulate an
-indirect call/jump by means of a @code{RET} instruction.
-
-@item
-The compiler assumes that @code{EIND} never changes during the startup
-code or during the application. In particular, @code{EIND} is not
-saved/restored in function or interrupt service routine
-prologue/epilogue.
-
-@item
-For indirect calls to functions and computed goto, the linker
-generates @emph{stubs}. Stubs are jump pads sometimes also called
-@emph{trampolines}. Thus, the indirect call/jump jumps to such a stub.
-The stub contains a direct jump to the desired address.
-
-@item
-Linker relaxation must be turned on so that the linker generates
-the stubs correctly in all situations. See the compiler option
-@option{-mrelax} and the linker option @option{--relax}.
-There are corner cases where the linker is supposed to generate stubs
-but aborts without relaxation and without a helpful error message.
-
-@item
-The default linker script is arranged for code with @code{EIND = 0}.
-If code is supposed to work for a setup with @code{EIND != 0}, a custom
-linker script has to be used in order to place the sections whose
-name start with @code{.trampolines} into the segment where @code{EIND}
-points to.
-
-@item
-The startup code from libgcc never sets @code{EIND}.
-Notice that startup code is a blend of code from libgcc and AVR-LibC.
-For the impact of AVR-LibC on @code{EIND}, see the
-@w{@uref{http://nongnu.org/avr-libc/user-manual/,AVR-LibC user manual}}.
-
-@item
-It is legitimate for user-specific startup code to set up @code{EIND}
-early, for example by means of initialization code located in
-section @code{.init3}. Such code runs prior to general startup code
-that initializes RAM and calls constructors, but after the bit
-of startup code from AVR-LibC that sets @code{EIND} to the segment
-where the vector table is located.
-@example
-#include <avr/io.h>
-
-static void
-__attribute__((section(".init3"),naked,used,no_instrument_function))
-init3_set_eind (void)
-@{
- __asm volatile ("ldi r24,pm_hh8(__trampolines_start)\n\t"
- "out %i0,r24" :: "n" (&EIND) : "r24","memory");
-@}
-@end example
-
-@noindent
-The @code{__trampolines_start} symbol is defined in the linker script.
-
-@item
-Stubs are generated automatically by the linker if
-the following two conditions are met:
-@itemize @minus
-
-@item The address of a label is taken by means of the @code{gs} modifier
-(short for @emph{generate stubs}) like so:
-@example
-LDI r24, lo8(gs(@var{func}))
-LDI r25, hi8(gs(@var{func}))
-@end example
-@item The final location of that label is in a code segment
-@emph{outside} the segment where the stubs are located.
-@end itemize
-
-@item
-The compiler emits such @code{gs} modifiers for code labels in the
-following situations:
-@itemize @minus
-@item Taking address of a function or code label.
-@item Computed goto.
-@item If prologue-save function is used, see @option{-mcall-prologues}
-command-line option.
-@item Switch/case dispatch tables. If you do not want such dispatch
-tables you can specify the @option{-fno-jump-tables} command-line option.
-@item C and C++ constructors/destructors called during startup/shutdown.
-@item If the tools hit a @code{gs()} modifier explained above.
-@end itemize
-
-@item
-Jumping to non-symbolic addresses like so is @emph{not} supported:
-
-@example
-int main (void)
-@{
- /* Call function at word address 0x2 */
- return ((int(*)(void)) 0x2)();
-@}
-@end example
-
-Instead, a stub has to be set up, i.e.@: the function has to be called
-through a symbol (@code{func_4} in the example):
-
-@example
-int main (void)
-@{
- extern int func_4 (void);
-
- /* Call function at byte address 0x4 */
- return func_4();
-@}
-@end example
-
-and the application be linked with @option{-Wl,--defsym,func_4=0x4}.
-Alternatively, @code{func_4} can be defined in the linker script.
-@end itemize
-
-@subsubsection Handling of the @code{RAMPD}, @code{RAMPX}, @code{RAMPY} and @code{RAMPZ} Special Function Registers
-@cindex @code{RAMPD}
-@cindex @code{RAMPX}
-@cindex @code{RAMPY}
-@cindex @code{RAMPZ}
-Some AVR devices support memories larger than the 64@tie{}KiB range
-that can be accessed with 16-bit pointers. To access memory locations
-outside this 64@tie{}KiB range, the content of a @code{RAMP}
-register is used as high part of the address:
-The @code{X}, @code{Y}, @code{Z} address register is concatenated
-with the @code{RAMPX}, @code{RAMPY}, @code{RAMPZ} special function
-register, respectively, to get a wide address. Similarly,
-@code{RAMPD} is used together with direct addressing.
-
-@itemize
-@item
-The startup code initializes the @code{RAMP} special function
-registers with zero.
-
-@item
-If a @ref{AVR Named Address Spaces,named address space} other than
-generic or @code{__flash} is used, then @code{RAMPZ} is set
-as needed before the operation.
-
-@item
-If the device supports RAM larger than 64@tie{}KiB and the compiler
-needs to change @code{RAMPZ} to accomplish an operation, @code{RAMPZ}
-is reset to zero after the operation.
-
-@item
-If the device comes with a specific @code{RAMP} register, the ISR
-prologue/epilogue saves/restores that SFR and initializes it with
-zero in case the ISR code might (implicitly) use it.
-
-@item
-RAM larger than 64@tie{}KiB is not supported by GCC for AVR targets.
-If you use inline assembler to read from locations outside the
-16-bit address range and change one of the @code{RAMP} registers,
-you must reset it to zero after the access.
-
-@end itemize
-
-@subsubsection AVR Built-in Macros
-
-GCC defines several built-in macros so that the user code can test
-for the presence or absence of features. Almost any of the following
-built-in macros are deduced from device capabilities and thus
-triggered by the @option{-mmcu=} command-line option.
-
-For even more AVR-specific built-in macros see
-@ref{AVR Named Address Spaces} and @ref{AVR Built-in Functions}.
-
-@table @code
-
-@item __AVR_ARCH__
-Build-in macro that resolves to a decimal number that identifies the
-architecture and depends on the @option{-mmcu=@var{mcu}} option.
-Possible values are:
-
-@code{2}, @code{25}, @code{3}, @code{31}, @code{35},
-@code{4}, @code{5}, @code{51}, @code{6}
-
-for @var{mcu}=@code{avr2}, @code{avr25}, @code{avr3}, @code{avr31},
-@code{avr35}, @code{avr4}, @code{avr5}, @code{avr51}, @code{avr6},
-
-respectively and
-
-@code{100},
-@code{102}, @code{103}, @code{104},
-@code{105}, @code{106}, @code{107}
-
-for @var{mcu}=@code{avrtiny},
-@code{avrxmega2}, @code{avrxmega3}, @code{avrxmega4},
-@code{avrxmega5}, @code{avrxmega6}, @code{avrxmega7}, respectively.
-If @var{mcu} specifies a device, this built-in macro is set
-accordingly. For example, with @option{-mmcu=atmega8} the macro is
-defined to @code{4}.
-
-@item __AVR_@var{Device}__
-Setting @option{-mmcu=@var{device}} defines this built-in macro which reflects
-the device's name. For example, @option{-mmcu=atmega8} defines the
-built-in macro @code{__AVR_ATmega8__}, @option{-mmcu=attiny261a} defines
-@code{__AVR_ATtiny261A__}, etc.
-
-The built-in macros' names follow
-the scheme @code{__AVR_@var{Device}__} where @var{Device} is
-the device name as from the AVR user manual. The difference between
-@var{Device} in the built-in macro and @var{device} in
-@option{-mmcu=@var{device}} is that the latter is always lowercase.
-
-If @var{device} is not a device but only a core architecture like
-@samp{avr51}, this macro is not defined.
-
-@item __AVR_DEVICE_NAME__
-Setting @option{-mmcu=@var{device}} defines this built-in macro to
-the device's name. For example, with @option{-mmcu=atmega8} the macro
-is defined to @code{atmega8}.
-
-If @var{device} is not a device but only a core architecture like
-@samp{avr51}, this macro is not defined.
-
-@item __AVR_XMEGA__
-The device / architecture belongs to the XMEGA family of devices.
-
-@item __AVR_HAVE_ELPM__
-The device has the @code{ELPM} instruction.
-
-@item __AVR_HAVE_ELPMX__
-The device has the @code{ELPM R@var{n},Z} and @code{ELPM
-R@var{n},Z+} instructions.
-
-@item __AVR_HAVE_MOVW__
-The device has the @code{MOVW} instruction to perform 16-bit
-register-register moves.
-
-@item __AVR_HAVE_LPMX__
-The device has the @code{LPM R@var{n},Z} and
-@code{LPM R@var{n},Z+} instructions.
-
-@item __AVR_HAVE_MUL__
-The device has a hardware multiplier.
-
-@item __AVR_HAVE_JMP_CALL__
-The device has the @code{JMP} and @code{CALL} instructions.
-This is the case for devices with more than 8@tie{}KiB of program
-memory.
-
-@item __AVR_HAVE_EIJMP_EICALL__
-@itemx __AVR_3_BYTE_PC__
-The device has the @code{EIJMP} and @code{EICALL} instructions.
-This is the case for devices with more than 128@tie{}KiB of program memory.
-This also means that the program counter
-(PC) is 3@tie{}bytes wide.
-
-@item __AVR_2_BYTE_PC__
-The program counter (PC) is 2@tie{}bytes wide. This is the case for devices
-with up to 128@tie{}KiB of program memory.
-
-@item __AVR_HAVE_8BIT_SP__
-@itemx __AVR_HAVE_16BIT_SP__
-The stack pointer (SP) register is treated as 8-bit respectively
-16-bit register by the compiler.
-The definition of these macros is affected by @option{-mtiny-stack}.
-
-@item __AVR_HAVE_SPH__
-@itemx __AVR_SP8__
-The device has the SPH (high part of stack pointer) special function
-register or has an 8-bit stack pointer, respectively.
-The definition of these macros is affected by @option{-mmcu=} and
-in the cases of @option{-mmcu=avr2} and @option{-mmcu=avr25} also
-by @option{-msp8}.
-
-@item __AVR_HAVE_RAMPD__
-@itemx __AVR_HAVE_RAMPX__
-@itemx __AVR_HAVE_RAMPY__
-@itemx __AVR_HAVE_RAMPZ__
-The device has the @code{RAMPD}, @code{RAMPX}, @code{RAMPY},
-@code{RAMPZ} special function register, respectively.
-
-@item __NO_INTERRUPTS__
-This macro reflects the @option{-mno-interrupts} command-line option.
-
-@item __AVR_ERRATA_SKIP__
-@itemx __AVR_ERRATA_SKIP_JMP_CALL__
-Some AVR devices (AT90S8515, ATmega103) must not skip 32-bit
-instructions because of a hardware erratum. Skip instructions are
-@code{SBRS}, @code{SBRC}, @code{SBIS}, @code{SBIC} and @code{CPSE}.
-The second macro is only defined if @code{__AVR_HAVE_JMP_CALL__} is also
-set.
-
-@item __AVR_ISA_RMW__
-The device has Read-Modify-Write instructions (XCH, LAC, LAS and LAT).
-
-@item __AVR_SFR_OFFSET__=@var{offset}
-Instructions that can address I/O special function registers directly
-like @code{IN}, @code{OUT}, @code{SBI}, etc.@: may use a different
-address as if addressed by an instruction to access RAM like @code{LD}
-or @code{STS}. This offset depends on the device architecture and has
-to be subtracted from the RAM address in order to get the
-respective I/O@tie{}address.
-
-@item __AVR_SHORT_CALLS__
-The @option{-mshort-calls} command line option is set.
-
-@item __AVR_PM_BASE_ADDRESS__=@var{addr}
-Some devices support reading from flash memory by means of @code{LD*}
-instructions. The flash memory is seen in the data address space
-at an offset of @code{__AVR_PM_BASE_ADDRESS__}. If this macro
-is not defined, this feature is not available. If defined,
-the address space is linear and there is no need to put
-@code{.rodata} into RAM. This is handled by the default linker
-description file, and is currently available for
-@code{avrtiny} and @code{avrxmega3}. Even more convenient,
-there is no need to use address spaces like @code{__flash} or
-features like attribute @code{progmem} and @code{pgm_read_*}.
-
-@item __WITH_AVRLIBC__
-The compiler is configured to be used together with AVR-Libc.
-See the @option{--with-avrlibc} configure option.
-
-@item __HAVE_DOUBLE_MULTILIB__
-Defined if @option{-mdouble=} acts as a multilib option.
-
-@item __HAVE_DOUBLE32__
-@itemx __HAVE_DOUBLE64__
-Defined if the compiler supports 32-bit double resp. 64-bit double.
-The actual layout is specified by option @option{-mdouble=}.
-
-@item __DEFAULT_DOUBLE__
-The size in bits of @code{double} if @option{-mdouble=} is not set.
-To test the layout of @code{double} in a program, use the built-in
-macro @code{__SIZEOF_DOUBLE__}.
-
-@item __HAVE_LONG_DOUBLE32__
-@itemx __HAVE_LONG_DOUBLE64__
-@itemx __HAVE_LONG_DOUBLE_MULTILIB__
-@itemx __DEFAULT_LONG_DOUBLE__
-Same as above, but for @code{long double} instead of @code{double}.
-
-@item __WITH_DOUBLE_COMPARISON__
-Reflects the @code{--with-double-comparison=@{tristate|bool|libf7@}}
-@w{@uref{https://gcc.gnu.org/install/configure.html#avr,configure option}}
-and is defined to @code{2} or @code{3}.
-
-@item __WITH_LIBF7_LIBGCC__
-@itemx __WITH_LIBF7_MATH__
-@itemx __WITH_LIBF7_MATH_SYMBOLS__
-Reflects the @code{--with-libf7=@{libgcc|math|math-symbols@}}
-@w{@uref{https://gcc.gnu.org/install/configure.html#avr,configure option}}.
-
-@end table
-
-@node Blackfin Options
-@subsection Blackfin Options
-@cindex Blackfin Options
-
-@table @gcctabopt
-@item -mcpu=@var{cpu}@r{[}-@var{sirevision}@r{]}
-@opindex mcpu=
-Specifies the name of the target Blackfin processor. Currently, @var{cpu}
-can be one of @samp{bf512}, @samp{bf514}, @samp{bf516}, @samp{bf518},
-@samp{bf522}, @samp{bf523}, @samp{bf524}, @samp{bf525}, @samp{bf526},
-@samp{bf527}, @samp{bf531}, @samp{bf532}, @samp{bf533},
-@samp{bf534}, @samp{bf536}, @samp{bf537}, @samp{bf538}, @samp{bf539},
-@samp{bf542}, @samp{bf544}, @samp{bf547}, @samp{bf548}, @samp{bf549},
-@samp{bf542m}, @samp{bf544m}, @samp{bf547m}, @samp{bf548m}, @samp{bf549m},
-@samp{bf561}, @samp{bf592}.
-
-The optional @var{sirevision} specifies the silicon revision of the target
-Blackfin processor. Any workarounds available for the targeted silicon revision
-are enabled. If @var{sirevision} is @samp{none}, no workarounds are enabled.
-If @var{sirevision} is @samp{any}, all workarounds for the targeted processor
-are enabled. The @code{__SILICON_REVISION__} macro is defined to two
-hexadecimal digits representing the major and minor numbers in the silicon
-revision. If @var{sirevision} is @samp{none}, the @code{__SILICON_REVISION__}
-is not defined. If @var{sirevision} is @samp{any}, the
-@code{__SILICON_REVISION__} is defined to be @code{0xffff}.
-If this optional @var{sirevision} is not used, GCC assumes the latest known
-silicon revision of the targeted Blackfin processor.
-
-GCC defines a preprocessor macro for the specified @var{cpu}.
-For the @samp{bfin-elf} toolchain, this option causes the hardware BSP
-provided by libgloss to be linked in if @option{-msim} is not given.
-
-Without this option, @samp{bf532} is used as the processor by default.
-
-Note that support for @samp{bf561} is incomplete. For @samp{bf561},
-only the preprocessor macro is defined.
-
-@item -msim
-@opindex msim
-Specifies that the program will be run on the simulator. This causes
-the simulator BSP provided by libgloss to be linked in. This option
-has effect only for @samp{bfin-elf} toolchain.
-Certain other options, such as @option{-mid-shared-library} and
-@option{-mfdpic}, imply @option{-msim}.
-
-@item -momit-leaf-frame-pointer
-@opindex momit-leaf-frame-pointer
-Don't keep the frame pointer in a register for leaf functions. This
-avoids the instructions to save, set up and restore frame pointers and
-makes an extra register available in leaf functions.
-
-@item -mspecld-anomaly
-@opindex mspecld-anomaly
-When enabled, the compiler ensures that the generated code does not
-contain speculative loads after jump instructions. If this option is used,
-@code{__WORKAROUND_SPECULATIVE_LOADS} is defined.
-
-@item -mno-specld-anomaly
-@opindex mno-specld-anomaly
-@opindex mspecld-anomaly
-Don't generate extra code to prevent speculative loads from occurring.
-
-@item -mcsync-anomaly
-@opindex mcsync-anomaly
-When enabled, the compiler ensures that the generated code does not
-contain CSYNC or SSYNC instructions too soon after conditional branches.
-If this option is used, @code{__WORKAROUND_SPECULATIVE_SYNCS} is defined.
-
-@item -mno-csync-anomaly
-@opindex mno-csync-anomaly
-@opindex mcsync-anomaly
-Don't generate extra code to prevent CSYNC or SSYNC instructions from
-occurring too soon after a conditional branch.
-
-@item -mlow64k
-@opindex mlow64k
-When enabled, the compiler is free to take advantage of the knowledge that
-the entire program fits into the low 64k of memory.
-
-@item -mno-low64k
-@opindex mno-low64k
-Assume that the program is arbitrarily large. This is the default.
-
-@item -mstack-check-l1
-@opindex mstack-check-l1
-Do stack checking using information placed into L1 scratchpad memory by the
-uClinux kernel.
-
-@item -mid-shared-library
-@opindex mid-shared-library
-Generate code that supports shared libraries via the library ID method.
-This allows for execute in place and shared libraries in an environment
-without virtual memory management. This option implies @option{-fPIC}.
-With a @samp{bfin-elf} target, this option implies @option{-msim}.
-
-@item -mno-id-shared-library
-@opindex mno-id-shared-library
-@opindex mid-shared-library
-Generate code that doesn't assume ID-based shared libraries are being used.
-This is the default.
-
-@item -mleaf-id-shared-library
-@opindex mleaf-id-shared-library
-Generate code that supports shared libraries via the library ID method,
-but assumes that this library or executable won't link against any other
-ID shared libraries. That allows the compiler to use faster code for jumps
-and calls.
-
-@item -mno-leaf-id-shared-library
-@opindex mno-leaf-id-shared-library
-@opindex mleaf-id-shared-library
-Do not assume that the code being compiled won't link against any ID shared
-libraries. Slower code is generated for jump and call insns.
-
-@item -mshared-library-id=n
-@opindex mshared-library-id
-Specifies the identification number of the ID-based shared library being
-compiled. Specifying a value of 0 generates more compact code; specifying
-other values forces the allocation of that number to the current
-library but is no more space- or time-efficient than omitting this option.
-
-@item -msep-data
-@opindex msep-data
-Generate code that allows the data segment to be located in a different
-area of memory from the text segment. This allows for execute in place in
-an environment without virtual memory management by eliminating relocations
-against the text section.
-
-@item -mno-sep-data
-@opindex mno-sep-data
-@opindex msep-data
-Generate code that assumes that the data segment follows the text segment.
-This is the default.
-
-@item -mlong-calls
-@itemx -mno-long-calls
-@opindex mlong-calls
-@opindex mno-long-calls
-Tells the compiler to perform function calls by first loading the
-address of the function into a register and then performing a subroutine
-call on this register. This switch is needed if the target function
-lies outside of the 24-bit addressing range of the offset-based
-version of subroutine call instruction.
-
-This feature is not enabled by default. Specifying
-@option{-mno-long-calls} restores the default behavior. Note these
-switches have no effect on how the compiler generates code to handle
-function calls via function pointers.
-
-@item -mfast-fp
-@opindex mfast-fp
-Link with the fast floating-point library. This library relaxes some of
-the IEEE floating-point standard's rules for checking inputs against
-Not-a-Number (NAN), in the interest of performance.
-
-@item -minline-plt
-@opindex minline-plt
-Enable inlining of PLT entries in function calls to functions that are
-not known to bind locally. It has no effect without @option{-mfdpic}.
-
-@item -mmulticore
-@opindex mmulticore
-Build a standalone application for multicore Blackfin processors.
-This option causes proper start files and link scripts supporting
-multicore to be used, and defines the macro @code{__BFIN_MULTICORE}.
-It can only be used with @option{-mcpu=bf561@r{[}-@var{sirevision}@r{]}}.
-
-This option can be used with @option{-mcorea} or @option{-mcoreb}, which
-selects the one-application-per-core programming model. Without
-@option{-mcorea} or @option{-mcoreb}, the single-application/dual-core
-programming model is used. In this model, the main function of Core B
-should be named as @code{coreb_main}.
-
-If this option is not used, the single-core application programming
-model is used.
-
-@item -mcorea
-@opindex mcorea
-Build a standalone application for Core A of BF561 when using
-the one-application-per-core programming model. Proper start files
-and link scripts are used to support Core A, and the macro
-@code{__BFIN_COREA} is defined.
-This option can only be used in conjunction with @option{-mmulticore}.
-
-@item -mcoreb
-@opindex mcoreb
-Build a standalone application for Core B of BF561 when using
-the one-application-per-core programming model. Proper start files
-and link scripts are used to support Core B, and the macro
-@code{__BFIN_COREB} is defined. When this option is used, @code{coreb_main}
-should be used instead of @code{main}.
-This option can only be used in conjunction with @option{-mmulticore}.
-
-@item -msdram
-@opindex msdram
-Build a standalone application for SDRAM. Proper start files and
-link scripts are used to put the application into SDRAM, and the macro
-@code{__BFIN_SDRAM} is defined.
-The loader should initialize SDRAM before loading the application.
-
-@item -micplb
-@opindex micplb
-Assume that ICPLBs are enabled at run time. This has an effect on certain
-anomaly workarounds. For Linux targets, the default is to assume ICPLBs
-are enabled; for standalone applications the default is off.
-@end table
-
-@node C6X Options
-@subsection C6X Options
-@cindex C6X Options
-
-@table @gcctabopt
-@item -march=@var{name}
-@opindex march
-This specifies the name of the target architecture. GCC uses this
-name to determine what kind of instructions it can emit when generating
-assembly code. Permissible names are: @samp{c62x},
-@samp{c64x}, @samp{c64x+}, @samp{c67x}, @samp{c67x+}, @samp{c674x}.
-
-@item -mbig-endian
-@opindex mbig-endian
-Generate code for a big-endian target.
-
-@item -mlittle-endian
-@opindex mlittle-endian
-Generate code for a little-endian target. This is the default.
-
-@item -msim
-@opindex msim
-Choose startup files and linker script suitable for the simulator.
-
-@item -msdata=default
-@opindex msdata=default
-Put small global and static data in the @code{.neardata} section,
-which is pointed to by register @code{B14}. Put small uninitialized
-global and static data in the @code{.bss} section, which is adjacent
-to the @code{.neardata} section. Put small read-only data into the
-@code{.rodata} section. The corresponding sections used for large
-pieces of data are @code{.fardata}, @code{.far} and @code{.const}.
-
-@item -msdata=all
-@opindex msdata=all
-Put all data, not just small objects, into the sections reserved for
-small data, and use addressing relative to the @code{B14} register to
-access them.
-
-@item -msdata=none
-@opindex msdata=none
-Make no use of the sections reserved for small data, and use absolute
-addresses to access all data. Put all initialized global and static
-data in the @code{.fardata} section, and all uninitialized data in the
-@code{.far} section. Put all constant data into the @code{.const}
-section.
-@end table
-
-@node CRIS Options
-@subsection CRIS Options
-@cindex CRIS Options
-
-These options are defined specifically for the CRIS ports.
-
-@table @gcctabopt
-@item -march=@var{architecture-type}
-@itemx -mcpu=@var{architecture-type}
-@opindex march
-@opindex mcpu
-Generate code for the specified architecture. The choices for
-@var{architecture-type} are @samp{v3}, @samp{v8} and @samp{v10} for
-respectively ETRAX@w{ }4, ETRAX@w{ }100, and ETRAX@w{ }100@w{ }LX@.
-Default is @samp{v0}.
-
-@item -mtune=@var{architecture-type}
-@opindex mtune
-Tune to @var{architecture-type} everything applicable about the generated
-code, except for the ABI and the set of available instructions. The
-choices for @var{architecture-type} are the same as for
-@option{-march=@var{architecture-type}}.
-
-@item -mmax-stack-frame=@var{n}
-@opindex mmax-stack-frame
-Warn when the stack frame of a function exceeds @var{n} bytes.
-
-@item -metrax4
-@itemx -metrax100
-@opindex metrax4
-@opindex metrax100
-The options @option{-metrax4} and @option{-metrax100} are synonyms for
-@option{-march=v3} and @option{-march=v8} respectively.
-
-@item -mmul-bug-workaround
-@itemx -mno-mul-bug-workaround
-@opindex mmul-bug-workaround
-@opindex mno-mul-bug-workaround
-Work around a bug in the @code{muls} and @code{mulu} instructions for CPU
-models where it applies. This option is disabled by default.
-
-@item -mpdebug
-@opindex mpdebug
-Enable CRIS-specific verbose debug-related information in the assembly
-code. This option also has the effect of turning off the @samp{#NO_APP}
-formatted-code indicator to the assembler at the beginning of the
-assembly file.
-
-@item -mcc-init
-@opindex mcc-init
-Do not use condition-code results from previous instruction; always emit
-compare and test instructions before use of condition codes.
-
-@item -mno-side-effects
-@opindex mno-side-effects
-@opindex mside-effects
-Do not emit instructions with side effects in addressing modes other than
-post-increment.
-
-@item -mstack-align
-@itemx -mno-stack-align
-@itemx -mdata-align
-@itemx -mno-data-align
-@itemx -mconst-align
-@itemx -mno-const-align
-@opindex mstack-align
-@opindex mno-stack-align
-@opindex mdata-align
-@opindex mno-data-align
-@opindex mconst-align
-@opindex mno-const-align
-These options (@samp{no-} options) arrange (eliminate arrangements) for the
-stack frame, individual data and constants to be aligned for the maximum
-single data access size for the chosen CPU model. The default is to
-arrange for 32-bit alignment. ABI details such as structure layout are
-not affected by these options.
-
-@item -m32-bit
-@itemx -m16-bit
-@itemx -m8-bit
-@opindex m32-bit
-@opindex m16-bit
-@opindex m8-bit
-Similar to the stack- data- and const-align options above, these options
-arrange for stack frame, writable data and constants to all be 32-bit,
-16-bit or 8-bit aligned. The default is 32-bit alignment.
-
-@item -mno-prologue-epilogue
-@itemx -mprologue-epilogue
-@opindex mno-prologue-epilogue
-@opindex mprologue-epilogue
-With @option{-mno-prologue-epilogue}, the normal function prologue and
-epilogue which set up the stack frame are omitted and no return
-instructions or return sequences are generated in the code. Use this
-option only together with visual inspection of the compiled code: no
-warnings or errors are generated when call-saved registers must be saved,
-or storage for local variables needs to be allocated.
-
-@item -melf
-@opindex melf
-Legacy no-op option.
-
-@item -sim
-@opindex sim
-This option arranges
-to link with input-output functions from a simulator library. Code,
-initialized data and zero-initialized data are allocated consecutively.
-
-@item -sim2
-@opindex sim2
-Like @option{-sim}, but pass linker options to locate initialized data at
-0x40000000 and zero-initialized data at 0x80000000.
-@end table
-
-@node C-SKY Options
-@subsection C-SKY Options
-@cindex C-SKY Options
-
-GCC supports these options when compiling for C-SKY V2 processors.
-
-@table @gcctabopt
-
-@item -march=@var{arch}
-@opindex march=
-Specify the C-SKY target architecture. Valid values for @var{arch} are:
-@samp{ck801}, @samp{ck802}, @samp{ck803}, @samp{ck807}, and @samp{ck810}.
-The default is @samp{ck810}.
-
-@item -mcpu=@var{cpu}
-@opindex mcpu=
-Specify the C-SKY target processor. Valid values for @var{cpu} are:
-@samp{ck801}, @samp{ck801t},
-@samp{ck802}, @samp{ck802t}, @samp{ck802j},
-@samp{ck803}, @samp{ck803h}, @samp{ck803t}, @samp{ck803ht},
-@samp{ck803f}, @samp{ck803fh}, @samp{ck803e}, @samp{ck803eh},
-@samp{ck803et}, @samp{ck803eht}, @samp{ck803ef}, @samp{ck803efh},
-@samp{ck803ft}, @samp{ck803eft}, @samp{ck803efht}, @samp{ck803r1},
-@samp{ck803hr1}, @samp{ck803tr1}, @samp{ck803htr1}, @samp{ck803fr1},
-@samp{ck803fhr1}, @samp{ck803er1}, @samp{ck803ehr1}, @samp{ck803etr1},
-@samp{ck803ehtr1}, @samp{ck803efr1}, @samp{ck803efhr1}, @samp{ck803ftr1},
-@samp{ck803eftr1}, @samp{ck803efhtr1},
-@samp{ck803s}, @samp{ck803st}, @samp{ck803se}, @samp{ck803sf},
-@samp{ck803sef}, @samp{ck803seft},
-@samp{ck807e}, @samp{ck807ef}, @samp{ck807}, @samp{ck807f},
-@samp{ck810e}, @samp{ck810et}, @samp{ck810ef}, @samp{ck810eft},
-@samp{ck810}, @samp{ck810v}, @samp{ck810f}, @samp{ck810t}, @samp{ck810fv},
-@samp{ck810tv}, @samp{ck810ft}, and @samp{ck810ftv}.
-
-@item -mbig-endian
-@opindex mbig-endian
-@itemx -EB
-@opindex EB
-@itemx -mlittle-endian
-@opindex mlittle-endian
-@itemx -EL
-@opindex EL
-
-Select big- or little-endian code. The default is little-endian.
-
-@item -mfloat-abi=@var{name}
-@opindex mfloat-abi
-Specifies which floating-point ABI to use. Permissible values
-are: @samp{soft}, @samp{softfp} and @samp{hard}.
-
-Specifying @samp{soft} causes GCC to generate output containing
-library calls for floating-point operations.
-@samp{softfp} allows the generation of code using hardware floating-point
-instructions, but still uses the soft-float calling conventions.
-@samp{hard} allows generation of floating-point instructions
-and uses FPU-specific calling conventions.
-
-The default depends on the specific target configuration. Note that
-the hard-float and soft-float ABIs are not link-compatible; you must
-compile your entire program with the same ABI, and link with a
-compatible set of libraries.
-
-@item -mhard-float
-@opindex mhard-float
-@itemx -msoft-float
-@opindex msoft-float
-
-Select hardware or software floating-point implementations.
-The default is soft float.
-
-@item -mdouble-float
-@itemx -mno-double-float
-@opindex mdouble-float
-When @option{-mhard-float} is in effect, enable generation of
-double-precision float instructions. This is the default except
-when compiling for CK803.
-
-@item -mfdivdu
-@itemx -mno-fdivdu
-@opindex mfdivdu
-When @option{-mhard-float} is in effect, enable generation of
-@code{frecipd}, @code{fsqrtd}, and @code{fdivd} instructions.
-This is the default except when compiling for CK803.
-
-@item -mfpu=@var{fpu}
-@opindex mfpu=
-Select the floating-point processor. This option can only be used with
-@option{-mhard-float}.
-Values for @var{fpu} are
-@samp{fpv2_sf} (equivalent to @samp{-mno-double-float -mno-fdivdu}),
-@samp{fpv2} (@samp{-mdouble-float -mno-divdu}), and
-@samp{fpv2_divd} (@samp{-mdouble-float -mdivdu}).
-
-@item -melrw
-@itemx -mno-elrw
-@opindex melrw
-Enable the extended @code{lrw} instruction. This option defaults to on
-for CK801 and off otherwise.
-
-@item -mistack
-@itemx -mno-istack
-@opindex mistack
-Enable interrupt stack instructions; the default is off.
-
-The @option{-mistack} option is required to handle the
-@code{interrupt} and @code{isr} function attributes
-(@pxref{C-SKY Function Attributes}).
-
-@item -mmp
-@opindex mmp
-Enable multiprocessor instructions; the default is off.
-
-@item -mcp
-@opindex mcp
-Enable coprocessor instructions; the default is off.
-
-@item -mcache
-@opindex mcache
-Enable coprocessor instructions; the default is off.
-
-@item -msecurity
-@opindex msecurity
-Enable C-SKY security instructions; the default is off.
-
-@item -mtrust
-@opindex mtrust
-Enable C-SKY trust instructions; the default is off.
-
-@item -mdsp
-@opindex mdsp
-@itemx -medsp
-@opindex medsp
-@itemx -mvdsp
-@opindex mvdsp
-Enable C-SKY DSP, Enhanced DSP, or Vector DSP instructions, respectively.
-All of these options default to off.
-
-@item -mdiv
-@itemx -mno-div
-@opindex mdiv
-Generate divide instructions. Default is off.
-
-@item -msmart
-@itemx -mno-smart
-@opindex msmart
-Generate code for Smart Mode, using only registers numbered 0-7 to allow
-use of 16-bit instructions. This option is ignored for CK801 where this
-is the required behavior, and it defaults to on for CK802.
-For other targets, the default is off.
-
-@item -mhigh-registers
-@itemx -mno-high-registers
-@opindex mhigh-registers
-Generate code using the high registers numbered 16-31. This option
-is not supported on CK801, CK802, or CK803, and is enabled by default
-for other processors.
-
-@item -manchor
-@itemx -mno-anchor
-@opindex manchor
-Generate code using global anchor symbol addresses.
-
-@item -mpushpop
-@itemx -mno-pushpop
-@opindex mpushpop
-Generate code using @code{push} and @code{pop} instructions. This option
-defaults to on.
-
-@item -mmultiple-stld
-@itemx -mstm
-@itemx -mno-multiple-stld
-@itemx -mno-stm
-@opindex mmultiple-stld
-Generate code using @code{stm} and @code{ldm} instructions. This option
-isn't supported on CK801 but is enabled by default on other processors.
-
-@item -mconstpool
-@itemx -mno-constpool
-@opindex mconstpool
-Create constant pools in the compiler instead of deferring it to the
-assembler. This option is the default and required for correct code
-generation on CK801 and CK802, and is optional on other processors.
-
-@item -mstack-size
-@item -mno-stack-size
-@opindex mstack-size
-Emit @code{.stack_size} directives for each function in the assembly
-output. This option defaults to off.
-
-@item -mccrt
-@itemx -mno-ccrt
-@opindex mccrt
-Generate code for the C-SKY compiler runtime instead of libgcc. This
-option defaults to off.
-
-@item -mbranch-cost=@var{n}
-@opindex mbranch-cost=
-Set the branch costs to roughly @code{n} instructions. The default is 1.
-
-@item -msched-prolog
-@itemx -mno-sched-prolog
-@opindex msched-prolog
-Permit scheduling of function prologue and epilogue sequences. Using
-this option can result in code that is not compliant with the C-SKY V2 ABI
-prologue requirements and that cannot be debugged or backtraced.
-It is disabled by default.
-
-@item -msim
-@opindex msim
-Links the library libsemi.a which is in compatible with simulator. Applicable
-to ELF compiler only.
-
-@end table
-
-@node Darwin Options
-@subsection Darwin Options
-@cindex Darwin options
-
-These options are defined for all architectures running the Darwin operating
-system.
-
-FSF GCC on Darwin does not create ``fat'' object files; it creates
-an object file for the single architecture that GCC was built to
-target. Apple's GCC on Darwin does create ``fat'' files if multiple
-@option{-arch} options are used; it does so by running the compiler or
-linker multiple times and joining the results together with
-@file{lipo}.
-
-The subtype of the file created (like @samp{ppc7400} or @samp{ppc970} or
-@samp{i686}) is determined by the flags that specify the ISA
-that GCC is targeting, like @option{-mcpu} or @option{-march}. The
-@option{-force_cpusubtype_ALL} option can be used to override this.
-
-The Darwin tools vary in their behavior when presented with an ISA
-mismatch. The assembler, @file{as}, only permits instructions to
-be used that are valid for the subtype of the file it is generating,
-so you cannot put 64-bit instructions in a @samp{ppc750} object file.
-The linker for shared libraries, @file{/usr/bin/libtool}, fails
-and prints an error if asked to create a shared library with a less
-restrictive subtype than its input files (for instance, trying to put
-a @samp{ppc970} object file in a @samp{ppc7400} library). The linker
-for executables, @command{ld}, quietly gives the executable the most
-restrictive subtype of any of its input files.
-
-@table @gcctabopt
-@item -F@var{dir}
-@opindex F
-Add the framework directory @var{dir} to the head of the list of
-directories to be searched for header files. These directories are
-interleaved with those specified by @option{-I} options and are
-scanned in a left-to-right order.
-
-A framework directory is a directory with frameworks in it. A
-framework is a directory with a @file{Headers} and/or
-@file{PrivateHeaders} directory contained directly in it that ends
-in @file{.framework}. The name of a framework is the name of this
-directory excluding the @file{.framework}. Headers associated with
-the framework are found in one of those two directories, with
-@file{Headers} being searched first. A subframework is a framework
-directory that is in a framework's @file{Frameworks} directory.
-Includes of subframework headers can only appear in a header of a
-framework that contains the subframework, or in a sibling subframework
-header. Two subframeworks are siblings if they occur in the same
-framework. A subframework should not have the same name as a
-framework; a warning is issued if this is violated. Currently a
-subframework cannot have subframeworks; in the future, the mechanism
-may be extended to support this. The standard frameworks can be found
-in @file{/System/Library/Frameworks} and
-@file{/Library/Frameworks}. An example include looks like
-@code{#include <Framework/header.h>}, where @file{Framework} denotes
-the name of the framework and @file{header.h} is found in the
-@file{PrivateHeaders} or @file{Headers} directory.
-
-@item -iframework@var{dir}
-@opindex iframework
-Like @option{-F} except the directory is a treated as a system
-directory. The main difference between this @option{-iframework} and
-@option{-F} is that with @option{-iframework} the compiler does not
-warn about constructs contained within header files found via
-@var{dir}. This option is valid only for the C family of languages.
-
-@item -gused
-@opindex gused
-Emit debugging information for symbols that are used. For stabs
-debugging format, this enables @option{-feliminate-unused-debug-symbols}.
-This is by default ON@.
-
-@item -gfull
-@opindex gfull
-Emit debugging information for all symbols and types.
-
-@item -mmacosx-version-min=@var{version}
-The earliest version of MacOS X that this executable will run on
-is @var{version}. Typical values of @var{version} include @code{10.1},
-@code{10.2}, and @code{10.3.9}.
-
-If the compiler was built to use the system's headers by default,
-then the default for this option is the system version on which the
-compiler is running, otherwise the default is to make choices that
-are compatible with as many systems and code bases as possible.
-
-@item -mkernel
-@opindex mkernel
-Enable kernel development mode. The @option{-mkernel} option sets
-@option{-static}, @option{-fno-common}, @option{-fno-use-cxa-atexit},
-@option{-fno-exceptions}, @option{-fno-non-call-exceptions},
-@option{-fapple-kext}, @option{-fno-weak} and @option{-fno-rtti} where
-applicable. This mode also sets @option{-mno-altivec},
-@option{-msoft-float}, @option{-fno-builtin} and
-@option{-mlong-branch} for PowerPC targets.
-
-@item -mone-byte-bool
-@opindex mone-byte-bool
-Override the defaults for @code{bool} so that @code{sizeof(bool)==1}.
-By default @code{sizeof(bool)} is @code{4} when compiling for
-Darwin/PowerPC and @code{1} when compiling for Darwin/x86, so this
-option has no effect on x86.
-
-@strong{Warning:} The @option{-mone-byte-bool} switch causes GCC
-to generate code that is not binary compatible with code generated
-without that switch. Using this switch may require recompiling all
-other modules in a program, including system libraries. Use this
-switch to conform to a non-default data model.
-
-@item -mfix-and-continue
-@itemx -ffix-and-continue
-@itemx -findirect-data
-@opindex mfix-and-continue
-@opindex ffix-and-continue
-@opindex findirect-data
-Generate code suitable for fast turnaround development, such as to
-allow GDB to dynamically load @file{.o} files into already-running
-programs. @option{-findirect-data} and @option{-ffix-and-continue}
-are provided for backwards compatibility.
-
-@item -all_load
-@opindex all_load
-Loads all members of static archive libraries.
-See man ld(1) for more information.
-
-@item -arch_errors_fatal
-@opindex arch_errors_fatal
-Cause the errors having to do with files that have the wrong architecture
-to be fatal.
-
-@item -bind_at_load
-@opindex bind_at_load
-Causes the output file to be marked such that the dynamic linker will
-bind all undefined references when the file is loaded or launched.
-
-@item -bundle
-@opindex bundle
-Produce a Mach-o bundle format file.
-See man ld(1) for more information.
-
-@item -bundle_loader @var{executable}
-@opindex bundle_loader
-This option specifies the @var{executable} that will load the build
-output file being linked. See man ld(1) for more information.
-
-@item -dynamiclib
-@opindex dynamiclib
-When passed this option, GCC produces a dynamic library instead of
-an executable when linking, using the Darwin @file{libtool} command.
-
-@item -force_cpusubtype_ALL
-@opindex force_cpusubtype_ALL
-This causes GCC's output file to have the @samp{ALL} subtype, instead of
-one controlled by the @option{-mcpu} or @option{-march} option.
-
-@item -allowable_client @var{client_name}
-@itemx -client_name
-@itemx -compatibility_version
-@itemx -current_version
-@itemx -dead_strip
-@itemx -dependency-file
-@itemx -dylib_file
-@itemx -dylinker_install_name
-@itemx -dynamic
-@itemx -exported_symbols_list
-@itemx -filelist
-@need 800
-@itemx -flat_namespace
-@itemx -force_flat_namespace
-@itemx -headerpad_max_install_names
-@itemx -image_base
-@itemx -init
-@itemx -install_name
-@itemx -keep_private_externs
-@itemx -multi_module
-@itemx -multiply_defined
-@itemx -multiply_defined_unused
-@need 800
-@itemx -noall_load
-@itemx -no_dead_strip_inits_and_terms
-@itemx -nofixprebinding
-@itemx -nomultidefs
-@itemx -noprebind
-@itemx -noseglinkedit
-@itemx -pagezero_size
-@itemx -prebind
-@itemx -prebind_all_twolevel_modules
-@itemx -private_bundle
-@need 800
-@itemx -read_only_relocs
-@itemx -sectalign
-@itemx -sectobjectsymbols
-@itemx -whyload
-@itemx -seg1addr
-@itemx -sectcreate
-@itemx -sectobjectsymbols
-@itemx -sectorder
-@itemx -segaddr
-@itemx -segs_read_only_addr
-@need 800
-@itemx -segs_read_write_addr
-@itemx -seg_addr_table
-@itemx -seg_addr_table_filename
-@itemx -seglinkedit
-@itemx -segprot
-@itemx -segs_read_only_addr
-@itemx -segs_read_write_addr
-@itemx -single_module
-@itemx -static
-@itemx -sub_library
-@need 800
-@itemx -sub_umbrella
-@itemx -twolevel_namespace
-@itemx -umbrella
-@itemx -undefined
-@itemx -unexported_symbols_list
-@itemx -weak_reference_mismatches
-@itemx -whatsloaded
-@opindex allowable_client
-@opindex client_name
-@opindex compatibility_version
-@opindex current_version
-@opindex dead_strip
-@opindex dependency-file
-@opindex dylib_file
-@opindex dylinker_install_name
-@opindex dynamic
-@opindex exported_symbols_list
-@opindex filelist
-@opindex flat_namespace
-@opindex force_flat_namespace
-@opindex headerpad_max_install_names
-@opindex image_base
-@opindex init
-@opindex install_name
-@opindex keep_private_externs
-@opindex multi_module
-@opindex multiply_defined
-@opindex multiply_defined_unused
-@opindex noall_load
-@opindex no_dead_strip_inits_and_terms
-@opindex nofixprebinding
-@opindex nomultidefs
-@opindex noprebind
-@opindex noseglinkedit
-@opindex pagezero_size
-@opindex prebind
-@opindex prebind_all_twolevel_modules
-@opindex private_bundle
-@opindex read_only_relocs
-@opindex sectalign
-@opindex sectobjectsymbols
-@opindex whyload
-@opindex seg1addr
-@opindex sectcreate
-@opindex sectobjectsymbols
-@opindex sectorder
-@opindex segaddr
-@opindex segs_read_only_addr
-@opindex segs_read_write_addr
-@opindex seg_addr_table
-@opindex seg_addr_table_filename
-@opindex seglinkedit
-@opindex segprot
-@opindex segs_read_only_addr
-@opindex segs_read_write_addr
-@opindex single_module
-@opindex static
-@opindex sub_library
-@opindex sub_umbrella
-@opindex twolevel_namespace
-@opindex umbrella
-@opindex undefined
-@opindex unexported_symbols_list
-@opindex weak_reference_mismatches
-@opindex whatsloaded
-These options are passed to the Darwin linker. The Darwin linker man page
-describes them in detail.
-@end table
-
-@node DEC Alpha Options
-@subsection DEC Alpha Options
-
-These @samp{-m} options are defined for the DEC Alpha implementations:
-
-@table @gcctabopt
-@item -mno-soft-float
-@itemx -msoft-float
-@opindex mno-soft-float
-@opindex msoft-float
-Use (do not use) the hardware floating-point instructions for
-floating-point operations. When @option{-msoft-float} is specified,
-functions in @file{libgcc.a} are used to perform floating-point
-operations. Unless they are replaced by routines that emulate the
-floating-point operations, or compiled in such a way as to call such
-emulations routines, these routines issue floating-point
-operations. If you are compiling for an Alpha without floating-point
-operations, you must ensure that the library is built so as not to call
-them.
-
-Note that Alpha implementations without floating-point operations are
-required to have floating-point registers.
-
-@item -mfp-reg
-@itemx -mno-fp-regs
-@opindex mfp-reg
-@opindex mno-fp-regs
-Generate code that uses (does not use) the floating-point register set.
-@option{-mno-fp-regs} implies @option{-msoft-float}. If the floating-point
-register set is not used, floating-point operands are passed in integer
-registers as if they were integers and floating-point results are passed
-in @code{$0} instead of @code{$f0}. This is a non-standard calling sequence,
-so any function with a floating-point argument or return value called by code
-compiled with @option{-mno-fp-regs} must also be compiled with that
-option.
-
-A typical use of this option is building a kernel that does not use,
-and hence need not save and restore, any floating-point registers.
-
-@item -mieee
-@opindex mieee
-The Alpha architecture implements floating-point hardware optimized for
-maximum performance. It is mostly compliant with the IEEE floating-point
-standard. However, for full compliance, software assistance is
-required. This option generates code fully IEEE-compliant code
-@emph{except} that the @var{inexact-flag} is not maintained (see below).
-If this option is turned on, the preprocessor macro @code{_IEEE_FP} is
-defined during compilation. The resulting code is less efficient but is
-able to correctly support denormalized numbers and exceptional IEEE
-values such as not-a-number and plus/minus infinity. Other Alpha
-compilers call this option @option{-ieee_with_no_inexact}.
-
-@item -mieee-with-inexact
-@opindex mieee-with-inexact
-This is like @option{-mieee} except the generated code also maintains
-the IEEE @var{inexact-flag}. Turning on this option causes the
-generated code to implement fully-compliant IEEE math. In addition to
-@code{_IEEE_FP}, @code{_IEEE_FP_EXACT} is defined as a preprocessor
-macro. On some Alpha implementations the resulting code may execute
-significantly slower than the code generated by default. Since there is
-very little code that depends on the @var{inexact-flag}, you should
-normally not specify this option. Other Alpha compilers call this
-option @option{-ieee_with_inexact}.
-
-@item -mfp-trap-mode=@var{trap-mode}
-@opindex mfp-trap-mode
-This option controls what floating-point related traps are enabled.
-Other Alpha compilers call this option @option{-fptm @var{trap-mode}}.
-The trap mode can be set to one of four values:
-
-@table @samp
-@item n
-This is the default (normal) setting. The only traps that are enabled
-are the ones that cannot be disabled in software (e.g., division by zero
-trap).
-
-@item u
-In addition to the traps enabled by @samp{n}, underflow traps are enabled
-as well.
-
-@item su
-Like @samp{u}, but the instructions are marked to be safe for software
-completion (see Alpha architecture manual for details).
-
-@item sui
-Like @samp{su}, but inexact traps are enabled as well.
-@end table
-
-@item -mfp-rounding-mode=@var{rounding-mode}
-@opindex mfp-rounding-mode
-Selects the IEEE rounding mode. Other Alpha compilers call this option
-@option{-fprm @var{rounding-mode}}. The @var{rounding-mode} can be one
-of:
-
-@table @samp
-@item n
-Normal IEEE rounding mode. Floating-point numbers are rounded towards
-the nearest machine number or towards the even machine number in case
-of a tie.
-
-@item m
-Round towards minus infinity.
-
-@item c
-Chopped rounding mode. Floating-point numbers are rounded towards zero.
-
-@item d
-Dynamic rounding mode. A field in the floating-point control register
-(@var{fpcr}, see Alpha architecture reference manual) controls the
-rounding mode in effect. The C library initializes this register for
-rounding towards plus infinity. Thus, unless your program modifies the
-@var{fpcr}, @samp{d} corresponds to round towards plus infinity.
-@end table
-
-@item -mtrap-precision=@var{trap-precision}
-@opindex mtrap-precision
-In the Alpha architecture, floating-point traps are imprecise. This
-means without software assistance it is impossible to recover from a
-floating trap and program execution normally needs to be terminated.
-GCC can generate code that can assist operating system trap handlers
-in determining the exact location that caused a floating-point trap.
-Depending on the requirements of an application, different levels of
-precisions can be selected:
-
-@table @samp
-@item p
-Program precision. This option is the default and means a trap handler
-can only identify which program caused a floating-point exception.
-
-@item f
-Function precision. The trap handler can determine the function that
-caused a floating-point exception.
-
-@item i
-Instruction precision. The trap handler can determine the exact
-instruction that caused a floating-point exception.
-@end table
-
-Other Alpha compilers provide the equivalent options called
-@option{-scope_safe} and @option{-resumption_safe}.
-
-@item -mieee-conformant
-@opindex mieee-conformant
-This option marks the generated code as IEEE conformant. You must not
-use this option unless you also specify @option{-mtrap-precision=i} and either
-@option{-mfp-trap-mode=su} or @option{-mfp-trap-mode=sui}. Its only effect
-is to emit the line @samp{.eflag 48} in the function prologue of the
-generated assembly file.
-
-@item -mbuild-constants
-@opindex mbuild-constants
-Normally GCC examines a 32- or 64-bit integer constant to
-see if it can construct it from smaller constants in two or three
-instructions. If it cannot, it outputs the constant as a literal and
-generates code to load it from the data segment at run time.
-
-Use this option to require GCC to construct @emph{all} integer constants
-using code, even if it takes more instructions (the maximum is six).
-
-You typically use this option to build a shared library dynamic
-loader. Itself a shared library, it must relocate itself in memory
-before it can find the variables and constants in its own data segment.
-
-@item -mbwx
-@itemx -mno-bwx
-@itemx -mcix
-@itemx -mno-cix
-@itemx -mfix
-@itemx -mno-fix
-@itemx -mmax
-@itemx -mno-max
-@opindex mbwx
-@opindex mno-bwx
-@opindex mcix
-@opindex mno-cix
-@opindex mfix
-@opindex mno-fix
-@opindex mmax
-@opindex mno-max
-Indicate whether GCC should generate code to use the optional BWX,
-CIX, FIX and MAX instruction sets. The default is to use the instruction
-sets supported by the CPU type specified via @option{-mcpu=} option or that
-of the CPU on which GCC was built if none is specified.
-
-@item -mfloat-vax
-@itemx -mfloat-ieee
-@opindex mfloat-vax
-@opindex mfloat-ieee
-Generate code that uses (does not use) VAX F and G floating-point
-arithmetic instead of IEEE single and double precision.
-
-@item -mexplicit-relocs
-@itemx -mno-explicit-relocs
-@opindex mexplicit-relocs
-@opindex mno-explicit-relocs
-Older Alpha assemblers provided no way to generate symbol relocations
-except via assembler macros. Use of these macros does not allow
-optimal instruction scheduling. GNU binutils as of version 2.12
-supports a new syntax that allows the compiler to explicitly mark
-which relocations should apply to which instructions. This option
-is mostly useful for debugging, as GCC detects the capabilities of
-the assembler when it is built and sets the default accordingly.
-
-@item -msmall-data
-@itemx -mlarge-data
-@opindex msmall-data
-@opindex mlarge-data
-When @option{-mexplicit-relocs} is in effect, static data is
-accessed via @dfn{gp-relative} relocations. When @option{-msmall-data}
-is used, objects 8 bytes long or smaller are placed in a @dfn{small data area}
-(the @code{.sdata} and @code{.sbss} sections) and are accessed via
-16-bit relocations off of the @code{$gp} register. This limits the
-size of the small data area to 64KB, but allows the variables to be
-directly accessed via a single instruction.
-
-The default is @option{-mlarge-data}. With this option the data area
-is limited to just below 2GB@. Programs that require more than 2GB of
-data must use @code{malloc} or @code{mmap} to allocate the data in the
-heap instead of in the program's data segment.
-
-When generating code for shared libraries, @option{-fpic} implies
-@option{-msmall-data} and @option{-fPIC} implies @option{-mlarge-data}.
-
-@item -msmall-text
-@itemx -mlarge-text
-@opindex msmall-text
-@opindex mlarge-text
-When @option{-msmall-text} is used, the compiler assumes that the
-code of the entire program (or shared library) fits in 4MB, and is
-thus reachable with a branch instruction. When @option{-msmall-data}
-is used, the compiler can assume that all local symbols share the
-same @code{$gp} value, and thus reduce the number of instructions
-required for a function call from 4 to 1.
-
-The default is @option{-mlarge-text}.
-
-@item -mcpu=@var{cpu_type}
-@opindex mcpu
-Set the instruction set and instruction scheduling parameters for
-machine type @var{cpu_type}. You can specify either the @samp{EV}
-style name or the corresponding chip number. GCC supports scheduling
-parameters for the EV4, EV5 and EV6 family of processors and
-chooses the default values for the instruction set from the processor
-you specify. If you do not specify a processor type, GCC defaults
-to the processor on which the compiler was built.
-
-Supported values for @var{cpu_type} are
-
-@table @samp
-@item ev4
-@itemx ev45
-@itemx 21064
-Schedules as an EV4 and has no instruction set extensions.
-
-@item ev5
-@itemx 21164
-Schedules as an EV5 and has no instruction set extensions.
-
-@item ev56
-@itemx 21164a
-Schedules as an EV5 and supports the BWX extension.
-
-@item pca56
-@itemx 21164pc
-@itemx 21164PC
-Schedules as an EV5 and supports the BWX and MAX extensions.
-
-@item ev6
-@itemx 21264
-Schedules as an EV6 and supports the BWX, FIX, and MAX extensions.
-
-@item ev67
-@itemx 21264a
-Schedules as an EV6 and supports the BWX, CIX, FIX, and MAX extensions.
-@end table
-
-Native toolchains also support the value @samp{native},
-which selects the best architecture option for the host processor.
-@option{-mcpu=native} has no effect if GCC does not recognize
-the processor.
-
-@item -mtune=@var{cpu_type}
-@opindex mtune
-Set only the instruction scheduling parameters for machine type
-@var{cpu_type}. The instruction set is not changed.
-
-Native toolchains also support the value @samp{native},
-which selects the best architecture option for the host processor.
-@option{-mtune=native} has no effect if GCC does not recognize
-the processor.
-
-@item -mmemory-latency=@var{time}
-@opindex mmemory-latency
-Sets the latency the scheduler should assume for typical memory
-references as seen by the application. This number is highly
-dependent on the memory access patterns used by the application
-and the size of the external cache on the machine.
-
-Valid options for @var{time} are
-
-@table @samp
-@item @var{number}
-A decimal number representing clock cycles.
-
-@item L1
-@itemx L2
-@itemx L3
-@itemx main
-The compiler contains estimates of the number of clock cycles for
-``typical'' EV4 & EV5 hardware for the Level 1, 2 & 3 caches
-(also called Dcache, Scache, and Bcache), as well as to main memory.
-Note that L3 is only valid for EV5.
-
-@end table
-@end table
-
-@node eBPF Options
-@subsection eBPF Options
-@cindex eBPF Options
-
-@table @gcctabopt
-@item -mframe-limit=@var{bytes}
-This specifies the hard limit for frame sizes, in bytes. Currently,
-the value that can be specified should be less than or equal to
-@samp{32767}. Defaults to whatever limit is imposed by the version of
-the Linux kernel targeted.
-
-@item -mkernel=@var{version}
-@opindex mkernel
-This specifies the minimum version of the kernel that will run the
-compiled program. GCC uses this version to determine which
-instructions to use, what kernel helpers to allow, etc. Currently,
-@var{version} can be one of @samp{4.0}, @samp{4.1}, @samp{4.2},
-@samp{4.3}, @samp{4.4}, @samp{4.5}, @samp{4.6}, @samp{4.7},
-@samp{4.8}, @samp{4.9}, @samp{4.10}, @samp{4.11}, @samp{4.12},
-@samp{4.13}, @samp{4.14}, @samp{4.15}, @samp{4.16}, @samp{4.17},
-@samp{4.18}, @samp{4.19}, @samp{4.20}, @samp{5.0}, @samp{5.1},
-@samp{5.2}, @samp{latest} and @samp{native}.
-
-@item -mbig-endian
-@opindex mbig-endian
-Generate code for a big-endian target.
-
-@item -mlittle-endian
-@opindex mlittle-endian
-Generate code for a little-endian target. This is the default.
-
-@item -mjmpext
-@opindex mjmpext
-Enable generation of extra conditional-branch instructions.
-Enabled for CPU v2 and above.
-
-@item -mjmp32
-@opindex mjmp32
-Enable 32-bit jump instructions. Enabled for CPU v3 and above.
-
-@item -malu32
-@opindex malu32
-Enable 32-bit ALU instructions. Enabled for CPU v3 and above.
-
-@item -mcpu=@var{version}
-@opindex mcpu
-This specifies which version of the eBPF ISA to target. Newer versions
-may not be supported by all kernels. The default is @samp{v3}.
-
-Supported values for @var{version} are:
-
-@table @samp
-@item v1
-The first stable eBPF ISA with no special features or extensions.
-
-@item v2
-Supports the jump extensions, as in @option{-mjmpext}.
-
-@item v3
-All features of v2, plus:
-@itemize @minus
-@item 32-bit jump operations, as in @option{-mjmp32}
-@item 32-bit ALU operations, as in @option{-malu32}
-@end itemize
-
-@end table
-
-@item -mco-re
-@opindex mco-re
-Enable BPF Compile Once - Run Everywhere (CO-RE) support. Requires and
-is implied by @option{-gbtf}.
-
-@item -mno-co-re
-@opindex mno-co-re
-Disable BPF Compile Once - Run Everywhere (CO-RE) support. BPF CO-RE
-support is enabled by default when generating BTF debug information for
-the BPF target.
-
-@item -mxbpf
-Generate code for an expanded version of BPF, which relaxes some of
-the restrictions imposed by the BPF architecture:
-@itemize @minus
-@item Save and restore callee-saved registers at function entry and
-exit, respectively.
-@end itemize
-@end table
-
-@node FR30 Options
-@subsection FR30 Options
-@cindex FR30 Options
-
-These options are defined specifically for the FR30 port.
-
-@table @gcctabopt
-
-@item -msmall-model
-@opindex msmall-model
-Use the small address space model. This can produce smaller code, but
-it does assume that all symbolic values and addresses fit into a
-20-bit range.
-
-@item -mno-lsim
-@opindex mno-lsim
-Assume that runtime support has been provided and so there is no need
-to include the simulator library (@file{libsim.a}) on the linker
-command line.
-
-@end table
-
-@node FT32 Options
-@subsection FT32 Options
-@cindex FT32 Options
-
-These options are defined specifically for the FT32 port.
-
-@table @gcctabopt
-
-@item -msim
-@opindex msim
-Specifies that the program will be run on the simulator. This causes
-an alternate runtime startup and library to be linked.
-You must not use this option when generating programs that will run on
-real hardware; you must provide your own runtime library for whatever
-I/O functions are needed.
-
-@item -mlra
-@opindex mlra
-Enable Local Register Allocation. This is still experimental for FT32,
-so by default the compiler uses standard reload.
-
-@item -mnodiv
-@opindex mnodiv
-Do not use div and mod instructions.
-
-@item -mft32b
-@opindex mft32b
-Enable use of the extended instructions of the FT32B processor.
-
-@item -mcompress
-@opindex mcompress
-Compress all code using the Ft32B code compression scheme.
-
-@item -mnopm
-@opindex mnopm
-Do not generate code that reads program memory.
-
-@end table
-
-@node FRV Options
-@subsection FRV Options
-@cindex FRV Options
-
-@table @gcctabopt
-@item -mgpr-32
-@opindex mgpr-32
-
-Only use the first 32 general-purpose registers.
-
-@item -mgpr-64
-@opindex mgpr-64
-
-Use all 64 general-purpose registers.
-
-@item -mfpr-32
-@opindex mfpr-32
-
-Use only the first 32 floating-point registers.
-
-@item -mfpr-64
-@opindex mfpr-64
-
-Use all 64 floating-point registers.
-
-@item -mhard-float
-@opindex mhard-float
-
-Use hardware instructions for floating-point operations.
-
-@item -msoft-float
-@opindex msoft-float
-
-Use library routines for floating-point operations.
-
-@item -malloc-cc
-@opindex malloc-cc
-
-Dynamically allocate condition code registers.
-
-@item -mfixed-cc
-@opindex mfixed-cc
-
-Do not try to dynamically allocate condition code registers, only
-use @code{icc0} and @code{fcc0}.
-
-@item -mdword
-@opindex mdword
-
-Change ABI to use double word insns.
-
-@item -mno-dword
-@opindex mno-dword
-@opindex mdword
-
-Do not use double word instructions.
-
-@item -mdouble
-@opindex mdouble
-
-Use floating-point double instructions.
-
-@item -mno-double
-@opindex mno-double
-
-Do not use floating-point double instructions.
-
-@item -mmedia
-@opindex mmedia
-
-Use media instructions.
-
-@item -mno-media
-@opindex mno-media
-
-Do not use media instructions.
-
-@item -mmuladd
-@opindex mmuladd
-
-Use multiply and add/subtract instructions.
-
-@item -mno-muladd
-@opindex mno-muladd
-
-Do not use multiply and add/subtract instructions.
-
-@item -mfdpic
-@opindex mfdpic
-
-Select the FDPIC ABI, which uses function descriptors to represent
-pointers to functions. Without any PIC/PIE-related options, it
-implies @option{-fPIE}. With @option{-fpic} or @option{-fpie}, it
-assumes GOT entries and small data are within a 12-bit range from the
-GOT base address; with @option{-fPIC} or @option{-fPIE}, GOT offsets
-are computed with 32 bits.
-With a @samp{bfin-elf} target, this option implies @option{-msim}.
-
-@item -minline-plt
-@opindex minline-plt
-
-Enable inlining of PLT entries in function calls to functions that are
-not known to bind locally. It has no effect without @option{-mfdpic}.
-It's enabled by default if optimizing for speed and compiling for
-shared libraries (i.e., @option{-fPIC} or @option{-fpic}), or when an
-optimization option such as @option{-O3} or above is present in the
-command line.
-
-@item -mTLS
-@opindex mTLS
-
-Assume a large TLS segment when generating thread-local code.
-
-@item -mtls
-@opindex mtls
-
-Do not assume a large TLS segment when generating thread-local code.
-
-@item -mgprel-ro
-@opindex mgprel-ro
-
-Enable the use of @code{GPREL} relocations in the FDPIC ABI for data
-that is known to be in read-only sections. It's enabled by default,
-except for @option{-fpic} or @option{-fpie}: even though it may help
-make the global offset table smaller, it trades 1 instruction for 4.
-With @option{-fPIC} or @option{-fPIE}, it trades 3 instructions for 4,
-one of which may be shared by multiple symbols, and it avoids the need
-for a GOT entry for the referenced symbol, so it's more likely to be a
-win. If it is not, @option{-mno-gprel-ro} can be used to disable it.
-
-@item -multilib-library-pic
-@opindex multilib-library-pic
-
-Link with the (library, not FD) pic libraries. It's implied by
-@option{-mlibrary-pic}, as well as by @option{-fPIC} and
-@option{-fpic} without @option{-mfdpic}. You should never have to use
-it explicitly.
-
-@item -mlinked-fp
-@opindex mlinked-fp
-
-Follow the EABI requirement of always creating a frame pointer whenever
-a stack frame is allocated. This option is enabled by default and can
-be disabled with @option{-mno-linked-fp}.
-
-@item -mlong-calls
-@opindex mlong-calls
-
-Use indirect addressing to call functions outside the current
-compilation unit. This allows the functions to be placed anywhere
-within the 32-bit address space.
-
-@item -malign-labels
-@opindex malign-labels
-
-Try to align labels to an 8-byte boundary by inserting NOPs into the
-previous packet. This option only has an effect when VLIW packing
-is enabled. It doesn't create new packets; it merely adds NOPs to
-existing ones.
-
-@item -mlibrary-pic
-@opindex mlibrary-pic
-
-Generate position-independent EABI code.
-
-@item -macc-4
-@opindex macc-4
-
-Use only the first four media accumulator registers.
-
-@item -macc-8
-@opindex macc-8
-
-Use all eight media accumulator registers.
-
-@item -mpack
-@opindex mpack
-
-Pack VLIW instructions.
-
-@item -mno-pack
-@opindex mno-pack
-
-Do not pack VLIW instructions.
-
-@item -mno-eflags
-@opindex mno-eflags
-
-Do not mark ABI switches in e_flags.
-
-@item -mcond-move
-@opindex mcond-move
-
-Enable the use of conditional-move instructions (default).
-
-This switch is mainly for debugging the compiler and will likely be removed
-in a future version.
-
-@item -mno-cond-move
-@opindex mno-cond-move
-
-Disable the use of conditional-move instructions.
-
-This switch is mainly for debugging the compiler and will likely be removed
-in a future version.
-
-@item -mscc
-@opindex mscc
-
-Enable the use of conditional set instructions (default).
-
-This switch is mainly for debugging the compiler and will likely be removed
-in a future version.
-
-@item -mno-scc
-@opindex mno-scc
-
-Disable the use of conditional set instructions.
-
-This switch is mainly for debugging the compiler and will likely be removed
-in a future version.
-
-@item -mcond-exec
-@opindex mcond-exec
-
-Enable the use of conditional execution (default).
-
-This switch is mainly for debugging the compiler and will likely be removed
-in a future version.
-
-@item -mno-cond-exec
-@opindex mno-cond-exec
-
-Disable the use of conditional execution.
-
-This switch is mainly for debugging the compiler and will likely be removed
-in a future version.
-
-@item -mvliw-branch
-@opindex mvliw-branch
-
-Run a pass to pack branches into VLIW instructions (default).
-
-This switch is mainly for debugging the compiler and will likely be removed
-in a future version.
-
-@item -mno-vliw-branch
-@opindex mno-vliw-branch
-
-Do not run a pass to pack branches into VLIW instructions.
-
-This switch is mainly for debugging the compiler and will likely be removed
-in a future version.
-
-@item -mmulti-cond-exec
-@opindex mmulti-cond-exec
-
-Enable optimization of @code{&&} and @code{||} in conditional execution
-(default).
-
-This switch is mainly for debugging the compiler and will likely be removed
-in a future version.
-
-@item -mno-multi-cond-exec
-@opindex mno-multi-cond-exec
-
-Disable optimization of @code{&&} and @code{||} in conditional execution.
-
-This switch is mainly for debugging the compiler and will likely be removed
-in a future version.
-
-@item -mnested-cond-exec
-@opindex mnested-cond-exec
-
-Enable nested conditional execution optimizations (default).
-
-This switch is mainly for debugging the compiler and will likely be removed
-in a future version.
-
-@item -mno-nested-cond-exec
-@opindex mno-nested-cond-exec
-
-Disable nested conditional execution optimizations.
-
-This switch is mainly for debugging the compiler and will likely be removed
-in a future version.
-
-@item -moptimize-membar
-@opindex moptimize-membar
-
-This switch removes redundant @code{membar} instructions from the
-compiler-generated code. It is enabled by default.
-
-@item -mno-optimize-membar
-@opindex mno-optimize-membar
-@opindex moptimize-membar
-
-This switch disables the automatic removal of redundant @code{membar}
-instructions from the generated code.
-
-@item -mtomcat-stats
-@opindex mtomcat-stats
-
-Cause gas to print out tomcat statistics.
-
-@item -mcpu=@var{cpu}
-@opindex mcpu
-
-Select the processor type for which to generate code. Possible values are
-@samp{frv}, @samp{fr550}, @samp{tomcat}, @samp{fr500}, @samp{fr450},
-@samp{fr405}, @samp{fr400}, @samp{fr300} and @samp{simple}.
-
-@end table
-
-@node GNU/Linux Options
-@subsection GNU/Linux Options
-
-These @samp{-m} options are defined for GNU/Linux targets:
-
-@table @gcctabopt
-@item -mglibc
-@opindex mglibc
-Use the GNU C library. This is the default except
-on @samp{*-*-linux-*uclibc*}, @samp{*-*-linux-*musl*} and
-@samp{*-*-linux-*android*} targets.
-
-@item -muclibc
-@opindex muclibc
-Use uClibc C library. This is the default on
-@samp{*-*-linux-*uclibc*} targets.
-
-@item -mmusl
-@opindex mmusl
-Use the musl C library. This is the default on
-@samp{*-*-linux-*musl*} targets.
-
-@item -mbionic
-@opindex mbionic
-Use Bionic C library. This is the default on
-@samp{*-*-linux-*android*} targets.
-
-@item -mandroid
-@opindex mandroid
-Compile code compatible with Android platform. This is the default on
-@samp{*-*-linux-*android*} targets.
-
-When compiling, this option enables @option{-mbionic}, @option{-fPIC},
-@option{-fno-exceptions} and @option{-fno-rtti} by default. When linking,
-this option makes the GCC driver pass Android-specific options to the linker.
-Finally, this option causes the preprocessor macro @code{__ANDROID__}
-to be defined.
-
-@item -tno-android-cc
-@opindex tno-android-cc
-Disable compilation effects of @option{-mandroid}, i.e., do not enable
-@option{-mbionic}, @option{-fPIC}, @option{-fno-exceptions} and
-@option{-fno-rtti} by default.
-
-@item -tno-android-ld
-@opindex tno-android-ld
-Disable linking effects of @option{-mandroid}, i.e., pass standard Linux
-linking options to the linker.
-
-@end table
-
-@node H8/300 Options
-@subsection H8/300 Options
-
-These @samp{-m} options are defined for the H8/300 implementations:
-
-@table @gcctabopt
-@item -mrelax
-@opindex mrelax
-Shorten some address references at link time, when possible; uses the
-linker option @option{-relax}. @xref{H8/300,, @code{ld} and the H8/300,
-ld, Using ld}, for a fuller description.
-
-@item -mh
-@opindex mh
-Generate code for the H8/300H@.
-
-@item -ms
-@opindex ms
-Generate code for the H8S@.
-
-@item -mn
-@opindex mn
-Generate code for the H8S and H8/300H in the normal mode. This switch
-must be used either with @option{-mh} or @option{-ms}.
-
-@item -ms2600
-@opindex ms2600
-Generate code for the H8S/2600. This switch must be used with @option{-ms}.
-
-@item -mexr
-@opindex mexr
-Extended registers are stored on stack before execution of function
-with monitor attribute. Default option is @option{-mexr}.
-This option is valid only for H8S targets.
-
-@item -mno-exr
-@opindex mno-exr
-@opindex mexr
-Extended registers are not stored on stack before execution of function
-with monitor attribute. Default option is @option{-mno-exr}.
-This option is valid only for H8S targets.
-
-@item -mint32
-@opindex mint32
-Make @code{int} data 32 bits by default.
-
-@item -malign-300
-@opindex malign-300
-On the H8/300H and H8S, use the same alignment rules as for the H8/300.
-The default for the H8/300H and H8S is to align longs and floats on
-4-byte boundaries.
-@option{-malign-300} causes them to be aligned on 2-byte boundaries.
-This option has no effect on the H8/300.
-@end table
-
-@node HPPA Options
-@subsection HPPA Options
-@cindex HPPA Options
-
-These @samp{-m} options are defined for the HPPA family of computers:
-
-@table @gcctabopt
-@item -march=@var{architecture-type}
-@opindex march
-Generate code for the specified architecture. The choices for
-@var{architecture-type} are @samp{1.0} for PA 1.0, @samp{1.1} for PA
-1.1, and @samp{2.0} for PA 2.0 processors. Refer to
-@file{/usr/lib/sched.models} on an HP-UX system to determine the proper
-architecture option for your machine. Code compiled for lower numbered
-architectures runs on higher numbered architectures, but not the
-other way around.
-
-@item -mpa-risc-1-0
-@itemx -mpa-risc-1-1
-@itemx -mpa-risc-2-0
-@opindex mpa-risc-1-0
-@opindex mpa-risc-1-1
-@opindex mpa-risc-2-0
-Synonyms for @option{-march=1.0}, @option{-march=1.1}, and @option{-march=2.0} respectively.
-
-@item -mcaller-copies
-@opindex mcaller-copies
-The caller copies function arguments passed by hidden reference. This
-option should be used with care as it is not compatible with the default
-32-bit runtime. However, only aggregates larger than eight bytes are
-passed by hidden reference and the option provides better compatibility
-with OpenMP.
-
-@item -mjump-in-delay
-@opindex mjump-in-delay
-This option is ignored and provided for compatibility purposes only.
-
-@item -mdisable-fpregs
-@opindex mdisable-fpregs
-Prevent floating-point registers from being used in any manner. This is
-necessary for compiling kernels that perform lazy context switching of
-floating-point registers. If you use this option and attempt to perform
-floating-point operations, the compiler aborts.
-
-@item -mdisable-indexing
-@opindex mdisable-indexing
-Prevent the compiler from using indexing address modes. This avoids some
-rather obscure problems when compiling MIG generated code under MACH@.
-
-@item -mno-space-regs
-@opindex mno-space-regs
-@opindex mspace-regs
-Generate code that assumes the target has no space registers. This allows
-GCC to generate faster indirect calls and use unscaled index address modes.
-
-Such code is suitable for level 0 PA systems and kernels.
-
-@item -mfast-indirect-calls
-@opindex mfast-indirect-calls
-Generate code that assumes calls never cross space boundaries. This
-allows GCC to emit code that performs faster indirect calls.
-
-This option does not work in the presence of shared libraries or nested
-functions.
-
-@item -mfixed-range=@var{register-range}
-@opindex mfixed-range
-Generate code treating the given register range as fixed registers.
-A fixed register is one that the register allocator cannot use. This is
-useful when compiling kernel code. A register range is specified as
-two registers separated by a dash. Multiple register ranges can be
-specified separated by a comma.
-
-@item -mlong-load-store
-@opindex mlong-load-store
-Generate 3-instruction load and store sequences as sometimes required by
-the HP-UX 10 linker. This is equivalent to the @samp{+k} option to
-the HP compilers.
-
-@item -mportable-runtime
-@opindex mportable-runtime
-Use the portable calling conventions proposed by HP for ELF systems.
-
-@item -mgas
-@opindex mgas
-Enable the use of assembler directives only GAS understands.
-
-@item -mschedule=@var{cpu-type}
-@opindex mschedule
-Schedule code according to the constraints for the machine type
-@var{cpu-type}. The choices for @var{cpu-type} are @samp{700}
-@samp{7100}, @samp{7100LC}, @samp{7200}, @samp{7300} and @samp{8000}. Refer
-to @file{/usr/lib/sched.models} on an HP-UX system to determine the
-proper scheduling option for your machine. The default scheduling is
-@samp{8000}.
-
-@item -mlinker-opt
-@opindex mlinker-opt
-Enable the optimization pass in the HP-UX linker. Note this makes symbolic
-debugging impossible. It also triggers a bug in the HP-UX 8 and HP-UX 9
-linkers in which they give bogus error messages when linking some programs.
-
-@item -msoft-float
-@opindex msoft-float
-Generate output containing library calls for floating point.
-@strong{Warning:} the requisite libraries are not available for all HPPA
-targets. Normally the facilities of the machine's usual C compiler are
-used, but this cannot be done directly in cross-compilation. You must make
-your own arrangements to provide suitable library functions for
-cross-compilation.
-
-@option{-msoft-float} changes the calling convention in the output file;
-therefore, it is only useful if you compile @emph{all} of a program with
-this option. In particular, you need to compile @file{libgcc.a}, the
-library that comes with GCC, with @option{-msoft-float} in order for
-this to work.
-
-@item -msio
-@opindex msio
-Generate the predefine, @code{_SIO}, for server IO@. The default is
-@option{-mwsio}. This generates the predefines, @code{__hp9000s700},
-@code{__hp9000s700__} and @code{_WSIO}, for workstation IO@. These
-options are available under HP-UX and HI-UX@.
-
-@item -mgnu-ld
-@opindex mgnu-ld
-Use options specific to GNU @command{ld}.
-This passes @option{-shared} to @command{ld} when
-building a shared library. It is the default when GCC is configured,
-explicitly or implicitly, with the GNU linker. This option does not
-affect which @command{ld} is called; it only changes what parameters
-are passed to that @command{ld}.
-The @command{ld} that is called is determined by the
-@option{--with-ld} configure option, GCC's program search path, and
-finally by the user's @env{PATH}. The linker used by GCC can be printed
-using @samp{which `gcc -print-prog-name=ld`}. This option is only available
-on the 64-bit HP-UX GCC, i.e.@: configured with @samp{hppa*64*-*-hpux*}.
-
-@item -mhp-ld
-@opindex mhp-ld
-Use options specific to HP @command{ld}.
-This passes @option{-b} to @command{ld} when building
-a shared library and passes @option{+Accept TypeMismatch} to @command{ld} on all
-links. It is the default when GCC is configured, explicitly or
-implicitly, with the HP linker. This option does not affect
-which @command{ld} is called; it only changes what parameters are passed to that
-@command{ld}.
-The @command{ld} that is called is determined by the @option{--with-ld}
-configure option, GCC's program search path, and finally by the user's
-@env{PATH}. The linker used by GCC can be printed using @samp{which
-`gcc -print-prog-name=ld`}. This option is only available on the 64-bit
-HP-UX GCC, i.e.@: configured with @samp{hppa*64*-*-hpux*}.
-
-@item -mlong-calls
-@opindex mno-long-calls
-@opindex mlong-calls
-Generate code that uses long call sequences. This ensures that a call
-is always able to reach linker generated stubs. The default is to generate
-long calls only when the distance from the call site to the beginning
-of the function or translation unit, as the case may be, exceeds a
-predefined limit set by the branch type being used. The limits for
-normal calls are 7,600,000 and 240,000 bytes, respectively for the
-PA 2.0 and PA 1.X architectures. Sibcalls are always limited at
-240,000 bytes.
-
-Distances are measured from the beginning of functions when using the
-@option{-ffunction-sections} option, or when using the @option{-mgas}
-and @option{-mno-portable-runtime} options together under HP-UX with
-the SOM linker.
-
-It is normally not desirable to use this option as it degrades
-performance. However, it may be useful in large applications,
-particularly when partial linking is used to build the application.
-
-The types of long calls used depends on the capabilities of the
-assembler and linker, and the type of code being generated. The
-impact on systems that support long absolute calls, and long pic
-symbol-difference or pc-relative calls should be relatively small.
-However, an indirect call is used on 32-bit ELF systems in pic code
-and it is quite long.
-
-@item -munix=@var{unix-std}
-@opindex march
-Generate compiler predefines and select a startfile for the specified
-UNIX standard. The choices for @var{unix-std} are @samp{93}, @samp{95}
-and @samp{98}. @samp{93} is supported on all HP-UX versions. @samp{95}
-is available on HP-UX 10.10 and later. @samp{98} is available on HP-UX
-11.11 and later. The default values are @samp{93} for HP-UX 10.00,
-@samp{95} for HP-UX 10.10 though to 11.00, and @samp{98} for HP-UX 11.11
-and later.
-
-@option{-munix=93} provides the same predefines as GCC 3.3 and 3.4.
-@option{-munix=95} provides additional predefines for @code{XOPEN_UNIX}
-and @code{_XOPEN_SOURCE_EXTENDED}, and the startfile @file{unix95.o}.
-@option{-munix=98} provides additional predefines for @code{_XOPEN_UNIX},
-@code{_XOPEN_SOURCE_EXTENDED}, @code{_INCLUDE__STDC_A1_SOURCE} and
-@code{_INCLUDE_XOPEN_SOURCE_500}, and the startfile @file{unix98.o}.
-
-It is @emph{important} to note that this option changes the interfaces
-for various library routines. It also affects the operational behavior
-of the C library. Thus, @emph{extreme} care is needed in using this
-option.
-
-Library code that is intended to operate with more than one UNIX
-standard must test, set and restore the variable @code{__xpg4_extended_mask}
-as appropriate. Most GNU software doesn't provide this capability.
-
-@item -nolibdld
-@opindex nolibdld
-Suppress the generation of link options to search libdld.sl when the
-@option{-static} option is specified on HP-UX 10 and later.
-
-@item -static
-@opindex static
-The HP-UX implementation of setlocale in libc has a dependency on
-libdld.sl. There isn't an archive version of libdld.sl. Thus,
-when the @option{-static} option is specified, special link options
-are needed to resolve this dependency.
-
-On HP-UX 10 and later, the GCC driver adds the necessary options to
-link with libdld.sl when the @option{-static} option is specified.
-This causes the resulting binary to be dynamic. On the 64-bit port,
-the linkers generate dynamic binaries by default in any case. The
-@option{-nolibdld} option can be used to prevent the GCC driver from
-adding these link options.
-
-@item -threads
-@opindex threads
-Add support for multithreading with the @dfn{dce thread} library
-under HP-UX@. This option sets flags for both the preprocessor and
-linker.
-@end table
-
-@node IA-64 Options
-@subsection IA-64 Options
-@cindex IA-64 Options
-
-These are the @samp{-m} options defined for the Intel IA-64 architecture.
-
-@table @gcctabopt
-@item -mbig-endian
-@opindex mbig-endian
-Generate code for a big-endian target. This is the default for HP-UX@.
-
-@item -mlittle-endian
-@opindex mlittle-endian
-Generate code for a little-endian target. This is the default for AIX5
-and GNU/Linux.
-
-@item -mgnu-as
-@itemx -mno-gnu-as
-@opindex mgnu-as
-@opindex mno-gnu-as
-Generate (or don't) code for the GNU assembler. This is the default.
-@c Also, this is the default if the configure option @option{--with-gnu-as}
-@c is used.
-
-@item -mgnu-ld
-@itemx -mno-gnu-ld
-@opindex mgnu-ld
-@opindex mno-gnu-ld
-Generate (or don't) code for the GNU linker. This is the default.
-@c Also, this is the default if the configure option @option{--with-gnu-ld}
-@c is used.
-
-@item -mno-pic
-@opindex mno-pic
-Generate code that does not use a global pointer register. The result
-is not position independent code, and violates the IA-64 ABI@.
-
-@item -mvolatile-asm-stop
-@itemx -mno-volatile-asm-stop
-@opindex mvolatile-asm-stop
-@opindex mno-volatile-asm-stop
-Generate (or don't) a stop bit immediately before and after volatile asm
-statements.
-
-@item -mregister-names
-@itemx -mno-register-names
-@opindex mregister-names
-@opindex mno-register-names
-Generate (or don't) @samp{in}, @samp{loc}, and @samp{out} register names for
-the stacked registers. This may make assembler output more readable.
-
-@item -mno-sdata
-@itemx -msdata
-@opindex mno-sdata
-@opindex msdata
-Disable (or enable) optimizations that use the small data section. This may
-be useful for working around optimizer bugs.
-
-@item -mconstant-gp
-@opindex mconstant-gp
-Generate code that uses a single constant global pointer value. This is
-useful when compiling kernel code.
-
-@item -mauto-pic
-@opindex mauto-pic
-Generate code that is self-relocatable. This implies @option{-mconstant-gp}.
-This is useful when compiling firmware code.
-
-@item -minline-float-divide-min-latency
-@opindex minline-float-divide-min-latency
-Generate code for inline divides of floating-point values
-using the minimum latency algorithm.
-
-@item -minline-float-divide-max-throughput
-@opindex minline-float-divide-max-throughput
-Generate code for inline divides of floating-point values
-using the maximum throughput algorithm.
-
-@item -mno-inline-float-divide
-@opindex mno-inline-float-divide
-Do not generate inline code for divides of floating-point values.
-
-@item -minline-int-divide-min-latency
-@opindex minline-int-divide-min-latency
-Generate code for inline divides of integer values
-using the minimum latency algorithm.
-
-@item -minline-int-divide-max-throughput
-@opindex minline-int-divide-max-throughput
-Generate code for inline divides of integer values
-using the maximum throughput algorithm.
-
-@item -mno-inline-int-divide
-@opindex mno-inline-int-divide
-@opindex minline-int-divide
-Do not generate inline code for divides of integer values.
-
-@item -minline-sqrt-min-latency
-@opindex minline-sqrt-min-latency
-Generate code for inline square roots
-using the minimum latency algorithm.
-
-@item -minline-sqrt-max-throughput
-@opindex minline-sqrt-max-throughput
-Generate code for inline square roots
-using the maximum throughput algorithm.
-
-@item -mno-inline-sqrt
-@opindex mno-inline-sqrt
-Do not generate inline code for @code{sqrt}.
-
-@item -mfused-madd
-@itemx -mno-fused-madd
-@opindex mfused-madd
-@opindex mno-fused-madd
-Do (don't) generate code that uses the fused multiply/add or multiply/subtract
-instructions. The default is to use these instructions.
-
-@item -mno-dwarf2-asm
-@itemx -mdwarf2-asm
-@opindex mno-dwarf2-asm
-@opindex mdwarf2-asm
-Don't (or do) generate assembler code for the DWARF line number debugging
-info. This may be useful when not using the GNU assembler.
-
-@item -mearly-stop-bits
-@itemx -mno-early-stop-bits
-@opindex mearly-stop-bits
-@opindex mno-early-stop-bits
-Allow stop bits to be placed earlier than immediately preceding the
-instruction that triggered the stop bit. This can improve instruction
-scheduling, but does not always do so.
-
-@item -mfixed-range=@var{register-range}
-@opindex mfixed-range
-Generate code treating the given register range as fixed registers.
-A fixed register is one that the register allocator cannot use. This is
-useful when compiling kernel code. A register range is specified as
-two registers separated by a dash. Multiple register ranges can be
-specified separated by a comma.
-
-@item -mtls-size=@var{tls-size}
-@opindex mtls-size
-Specify bit size of immediate TLS offsets. Valid values are 14, 22, and
-64.
-
-@item -mtune=@var{cpu-type}
-@opindex mtune
-Tune the instruction scheduling for a particular CPU, Valid values are
-@samp{itanium}, @samp{itanium1}, @samp{merced}, @samp{itanium2},
-and @samp{mckinley}.
-
-@item -milp32
-@itemx -mlp64
-@opindex milp32
-@opindex mlp64
-Generate code for a 32-bit or 64-bit environment.
-The 32-bit environment sets int, long and pointer to 32 bits.
-The 64-bit environment sets int to 32 bits and long and pointer
-to 64 bits. These are HP-UX specific flags.
-
-@item -mno-sched-br-data-spec
-@itemx -msched-br-data-spec
-@opindex mno-sched-br-data-spec
-@opindex msched-br-data-spec
-(Dis/En)able data speculative scheduling before reload.
-This results in generation of @code{ld.a} instructions and
-the corresponding check instructions (@code{ld.c} / @code{chk.a}).
-The default setting is disabled.
-
-@item -msched-ar-data-spec
-@itemx -mno-sched-ar-data-spec
-@opindex msched-ar-data-spec
-@opindex mno-sched-ar-data-spec
-(En/Dis)able data speculative scheduling after reload.
-This results in generation of @code{ld.a} instructions and
-the corresponding check instructions (@code{ld.c} / @code{chk.a}).
-The default setting is enabled.
-
-@item -mno-sched-control-spec
-@itemx -msched-control-spec
-@opindex mno-sched-control-spec
-@opindex msched-control-spec
-(Dis/En)able control speculative scheduling. This feature is
-available only during region scheduling (i.e.@: before reload).
-This results in generation of the @code{ld.s} instructions and
-the corresponding check instructions @code{chk.s}.
-The default setting is disabled.
-
-@item -msched-br-in-data-spec
-@itemx -mno-sched-br-in-data-spec
-@opindex msched-br-in-data-spec
-@opindex mno-sched-br-in-data-spec
-(En/Dis)able speculative scheduling of the instructions that
-are dependent on the data speculative loads before reload.
-This is effective only with @option{-msched-br-data-spec} enabled.
-The default setting is enabled.
-
-@item -msched-ar-in-data-spec
-@itemx -mno-sched-ar-in-data-spec
-@opindex msched-ar-in-data-spec
-@opindex mno-sched-ar-in-data-spec
-(En/Dis)able speculative scheduling of the instructions that
-are dependent on the data speculative loads after reload.
-This is effective only with @option{-msched-ar-data-spec} enabled.
-The default setting is enabled.
-
-@item -msched-in-control-spec
-@itemx -mno-sched-in-control-spec
-@opindex msched-in-control-spec
-@opindex mno-sched-in-control-spec
-(En/Dis)able speculative scheduling of the instructions that
-are dependent on the control speculative loads.
-This is effective only with @option{-msched-control-spec} enabled.
-The default setting is enabled.
-
-@item -mno-sched-prefer-non-data-spec-insns
-@itemx -msched-prefer-non-data-spec-insns
-@opindex mno-sched-prefer-non-data-spec-insns
-@opindex msched-prefer-non-data-spec-insns
-If enabled, data-speculative instructions are chosen for schedule
-only if there are no other choices at the moment. This makes
-the use of the data speculation much more conservative.
-The default setting is disabled.
-
-@item -mno-sched-prefer-non-control-spec-insns
-@itemx -msched-prefer-non-control-spec-insns
-@opindex mno-sched-prefer-non-control-spec-insns
-@opindex msched-prefer-non-control-spec-insns
-If enabled, control-speculative instructions are chosen for schedule
-only if there are no other choices at the moment. This makes
-the use of the control speculation much more conservative.
-The default setting is disabled.
-
-@item -mno-sched-count-spec-in-critical-path
-@itemx -msched-count-spec-in-critical-path
-@opindex mno-sched-count-spec-in-critical-path
-@opindex msched-count-spec-in-critical-path
-If enabled, speculative dependencies are considered during
-computation of the instructions priorities. This makes the use of the
-speculation a bit more conservative.
-The default setting is disabled.
-
-@item -msched-spec-ldc
-@opindex msched-spec-ldc
-Use a simple data speculation check. This option is on by default.
-
-@item -msched-control-spec-ldc
-@opindex msched-spec-ldc
-Use a simple check for control speculation. This option is on by default.
-
-@item -msched-stop-bits-after-every-cycle
-@opindex msched-stop-bits-after-every-cycle
-Place a stop bit after every cycle when scheduling. This option is on
-by default.
-
-@item -msched-fp-mem-deps-zero-cost
-@opindex msched-fp-mem-deps-zero-cost
-Assume that floating-point stores and loads are not likely to cause a conflict
-when placed into the same instruction group. This option is disabled by
-default.
-
-@item -msel-sched-dont-check-control-spec
-@opindex msel-sched-dont-check-control-spec
-Generate checks for control speculation in selective scheduling.
-This flag is disabled by default.
-
-@item -msched-max-memory-insns=@var{max-insns}
-@opindex msched-max-memory-insns
-Limit on the number of memory insns per instruction group, giving lower
-priority to subsequent memory insns attempting to schedule in the same
-instruction group. Frequently useful to prevent cache bank conflicts.
-The default value is 1.
-
-@item -msched-max-memory-insns-hard-limit
-@opindex msched-max-memory-insns-hard-limit
-Makes the limit specified by @option{msched-max-memory-insns} a hard limit,
-disallowing more than that number in an instruction group.
-Otherwise, the limit is ``soft'', meaning that non-memory operations
-are preferred when the limit is reached, but memory operations may still
-be scheduled.
-
-@end table
-
-@node LM32 Options
-@subsection LM32 Options
-@cindex LM32 options
-
-These @option{-m} options are defined for the LatticeMico32 architecture:
-
-@table @gcctabopt
-@item -mbarrel-shift-enabled
-@opindex mbarrel-shift-enabled
-Enable barrel-shift instructions.
-
-@item -mdivide-enabled
-@opindex mdivide-enabled
-Enable divide and modulus instructions.
-
-@item -mmultiply-enabled
-@opindex multiply-enabled
-Enable multiply instructions.
-
-@item -msign-extend-enabled
-@opindex msign-extend-enabled
-Enable sign extend instructions.
-
-@item -muser-enabled
-@opindex muser-enabled
-Enable user-defined instructions.
-
-@end table
-
-@node LoongArch Options
-@subsection LoongArch Options
-@cindex LoongArch Options
-
-These command-line options are defined for LoongArch targets:
-
-@table @gcctabopt
-@item -march=@var{cpu-type}
-@opindex -march
-Generate instructions for the machine type @var{cpu-type}. In contrast to
-@option{-mtune=@var{cpu-type}}, which merely tunes the generated code
-for the specified @var{cpu-type}, @option{-march=@var{cpu-type}} allows GCC
-to generate code that may not run at all on processors other than the one
-indicated. Specifying @option{-march=@var{cpu-type}} implies
-@option{-mtune=@var{cpu-type}}, except where noted otherwise.
-
-The choices for @var{cpu-type} are:
-
-@table @samp
-@item native
-This selects the CPU to generate code for at compilation time by determining
-the processor type of the compiling machine. Using @option{-march=native}
-enables all instruction subsets supported by the local machine (hence
-the result might not run on different machines). Using @option{-mtune=native}
-produces code optimized for the local machine under the constraints
-of the selected instruction set.
-@item loongarch64
-A generic CPU with 64-bit extensions.
-@item la464
-LoongArch LA464 CPU with LBT, LSX, LASX, LVZ.
-@end table
-
-@item -mtune=@var{cpu-type}
-@opindex mtune
-Optimize the output for the given processor, specified by microarchitecture
-name.
-
-@item -mabi=@var{base-abi-type}
-@opindex mabi
-Generate code for the specified calling convention.
-@var{base-abi-type} can be one of:
-@table @samp
-@item lp64d
-Uses 64-bit general purpose registers and 32/64-bit floating-point
-registers for parameter passing. Data model is LP64, where @samp{int}
-is 32 bits, while @samp{long int} and pointers are 64 bits.
-@item lp64f
-Uses 64-bit general purpose registers and 32-bit floating-point
-registers for parameter passing. Data model is LP64, where @samp{int}
-is 32 bits, while @samp{long int} and pointers are 64 bits.
-@item lp64s
-Uses 64-bit general purpose registers and no floating-point
-registers for parameter passing. Data model is LP64, where @samp{int}
-is 32 bits, while @samp{long int} and pointers are 64 bits.
-@end table
-
-@item -mfpu=@var{fpu-type}
-@opindex mfpu
-Generate code for the specified FPU type, which can be one of:
-@table @samp
-@item 64
-Allow the use of hardware floating-point instructions for 32-bit
-and 64-bit operations.
-@item 32
-Allow the use of hardware floating-point instructions for 32-bit
-operations.
-@item none
-@item 0
-Prevent the use of hardware floating-point instructions.
-@end table
-
-@item -msoft-float
-@opindex msoft-float
-Force @option{-mfpu=none} and prevents the use of floating-point
-registers for parameter passing. This option may change the target
-ABI.
-
-@item -msingle-float
-@opindex -msingle-float
-Force @option{-mfpu=32} and allow the use of 32-bit floating-point
-registers for parameter passing. This option may change the target
-ABI.
-
-@item -mdouble-float
-@opindex -mdouble-float
-Force @option{-mfpu=64} and allow the use of 32/64-bit floating-point
-registers for parameter passing. This option may change the target
-ABI.
-
-@item -mbranch-cost=@var{n}
-@opindex -mbranch-cost
-Set the cost of branches to roughly @var{n} instructions.
-
-@item -mcheck-zero-division
-@itemx -mno-check-zero-divison
-@opindex -mcheck-zero-division
-Trap (do not trap) on integer division by zero. The default is
-@option{-mcheck-zero-division} for @option{-O0} or @option{-Og}, and
-@option{-mno-check-zero-division} for other optimization levels.
-
-@item -mcond-move-int
-@itemx -mno-cond-move-int
-@opindex -mcond-move-int
-Conditional moves for integral data in general-purpose registers
-are enabled (disabled). The default is @option{-mcond-move-int}.
-
-@item -mcond-move-float
-@itemx -mno-cond-move-float
-@opindex -mcond-move-float
-Conditional moves for floating-point registers are enabled (disabled).
-The default is @option{-mcond-move-float}.
-
-@item -mmemcpy
-@itemx -mno-memcpy
-@opindex -mmemcpy
-Force (do not force) the use of @code{memcpy} for non-trivial block moves.
-The default is @option{-mno-memcpy}, which allows GCC to inline most
-constant-sized copies. Setting optimization level to @option{-Os} also
-forces the use of @code{memcpy}, but @option{-mno-memcpy} may override this
-behavior if explicitly specified, regardless of the order these options on
-the command line.
-
-@item -mstrict-align
-@itemx -mno-strict-align
-@opindex -mstrict-align
-Avoid or allow generating memory accesses that may not be aligned on a natural
-object boundary as described in the architecture specification. The default is
-@option{-mno-strict-align}.
-
-@item -msmall-data-limit=@var{number}
-@opindex -msmall-data-limit
-Put global and static data smaller than @var{number} bytes into a special
-section (on some targets). The default value is 0.
-
-@item -mmax-inline-memcpy-size=@var{n}
-@opindex -mmax-inline-memcpy-size
-Inline all block moves (such as calls to @code{memcpy} or structure copies)
-less than or equal to @var{n} bytes. The default value of @var{n} is 1024.
-
-@item -mcmodel=@var{code-model}
-Set the code model to one of:
-@table @samp
-@item tiny-static (Not implemented yet)
-@item tiny (Not implemented yet)
-
-@item normal
-The text segment must be within 128MB addressing space. The data segment must
-be within 2GB addressing space.
-
-@item medium
-The text segment and data segment must be within 2GB addressing space.
-
-@item large (Not implemented yet)
-
-@item extreme
-This mode does not limit the size of the code segment and data segment.
-The @option{-mcmodel=extreme} option is incompatible with @option{-fplt} and
-@option{-mno-explicit-relocs}.
-@end table
-The default code model is @code{normal}.
-
-@item -mexplicit-relocs
-@itemx -mno-explicit-relocs
-@opindex mexplicit-relocs
-@opindex mno-explicit-relocs
-Use or do not use assembler relocation operators when dealing with symbolic
-addresses. The alternative is to use assembler macros instead, which may
-limit optimization. The default value for the option is determined during
-GCC build-time by detecting corresponding assembler support:
-@code{-mexplicit-relocs} if said support is present,
-@code{-mno-explicit-relocs} otherwise. This option is mostly useful for
-debugging, or interoperation with assemblers different from the build-time
-one.
-
-@item -mdirect-extern-access
-@itemx -mno-direct-extern-access
-@opindex mdirect-extern-access
-Do not use or use GOT to access external symbols. The default is
-@option{-mno-direct-extern-access}: GOT is used for external symbols with
-default visibility, but not used for other external symbols.
-
-With @option{-mdirect-extern-access}, GOT is not used and all external
-symbols are PC-relatively addressed. It is @strong{only} suitable for
-environments where no dynamic link is performed, like firmwares, OS
-kernels, executables linked with @option{-static} or @option{-static-pie}.
-@option{-mdirect-extern-access} is not compatible with @option{-fPIC} or
-@option{-fpic}.
-@end table
-
-@node M32C Options
-@subsection M32C Options
-@cindex M32C options
-
-@table @gcctabopt
-@item -mcpu=@var{name}
-@opindex mcpu=
-Select the CPU for which code is generated. @var{name} may be one of
-@samp{r8c} for the R8C/Tiny series, @samp{m16c} for the M16C (up to
-/60) series, @samp{m32cm} for the M16C/80 series, or @samp{m32c} for
-the M32C/80 series.
-
-@item -msim
-@opindex msim
-Specifies that the program will be run on the simulator. This causes
-an alternate runtime library to be linked in which supports, for
-example, file I/O@. You must not use this option when generating
-programs that will run on real hardware; you must provide your own
-runtime library for whatever I/O functions are needed.
-
-@item -memregs=@var{number}
-@opindex memregs=
-Specifies the number of memory-based pseudo-registers GCC uses
-during code generation. These pseudo-registers are used like real
-registers, so there is a tradeoff between GCC's ability to fit the
-code into available registers, and the performance penalty of using
-memory instead of registers. Note that all modules in a program must
-be compiled with the same value for this option. Because of that, you
-must not use this option with GCC's default runtime libraries.
-
-@end table
-
-@node M32R/D Options
-@subsection M32R/D Options
-@cindex M32R/D options
-
-These @option{-m} options are defined for Renesas M32R/D architectures:
-
-@table @gcctabopt
-@item -m32r2
-@opindex m32r2
-Generate code for the M32R/2@.
-
-@item -m32rx
-@opindex m32rx
-Generate code for the M32R/X@.
-
-@item -m32r
-@opindex m32r
-Generate code for the M32R@. This is the default.
-
-@item -mmodel=small
-@opindex mmodel=small
-Assume all objects live in the lower 16MB of memory (so that their addresses
-can be loaded with the @code{ld24} instruction), and assume all subroutines
-are reachable with the @code{bl} instruction.
-This is the default.
-
-The addressability of a particular object can be set with the
-@code{model} attribute.
-
-@item -mmodel=medium
-@opindex mmodel=medium
-Assume objects may be anywhere in the 32-bit address space (the compiler
-generates @code{seth/add3} instructions to load their addresses), and
-assume all subroutines are reachable with the @code{bl} instruction.
-
-@item -mmodel=large
-@opindex mmodel=large
-Assume objects may be anywhere in the 32-bit address space (the compiler
-generates @code{seth/add3} instructions to load their addresses), and
-assume subroutines may not be reachable with the @code{bl} instruction
-(the compiler generates the much slower @code{seth/add3/jl}
-instruction sequence).
-
-@item -msdata=none
-@opindex msdata=none
-Disable use of the small data area. Variables are put into
-one of @code{.data}, @code{.bss}, or @code{.rodata} (unless the
-@code{section} attribute has been specified).
-This is the default.
-
-The small data area consists of sections @code{.sdata} and @code{.sbss}.
-Objects may be explicitly put in the small data area with the
-@code{section} attribute using one of these sections.
-
-@item -msdata=sdata
-@opindex msdata=sdata
-Put small global and static data in the small data area, but do not
-generate special code to reference them.
-
-@item -msdata=use
-@opindex msdata=use
-Put small global and static data in the small data area, and generate
-special instructions to reference them.
-
-@item -G @var{num}
-@opindex G
-@cindex smaller data references
-Put global and static objects less than or equal to @var{num} bytes
-into the small data or BSS sections instead of the normal data or BSS
-sections. The default value of @var{num} is 8.
-The @option{-msdata} option must be set to one of @samp{sdata} or @samp{use}
-for this option to have any effect.
-
-All modules should be compiled with the same @option{-G @var{num}} value.
-Compiling with different values of @var{num} may or may not work; if it
-doesn't the linker gives an error message---incorrect code is not
-generated.
-
-@item -mdebug
-@opindex mdebug
-Makes the M32R-specific code in the compiler display some statistics
-that might help in debugging programs.
-
-@item -malign-loops
-@opindex malign-loops
-Align all loops to a 32-byte boundary.
-
-@item -mno-align-loops
-@opindex mno-align-loops
-Do not enforce a 32-byte alignment for loops. This is the default.
-
-@item -missue-rate=@var{number}
-@opindex missue-rate=@var{number}
-Issue @var{number} instructions per cycle. @var{number} can only be 1
-or 2.
-
-@item -mbranch-cost=@var{number}
-@opindex mbranch-cost=@var{number}
-@var{number} can only be 1 or 2. If it is 1 then branches are
-preferred over conditional code, if it is 2, then the opposite applies.
-
-@item -mflush-trap=@var{number}
-@opindex mflush-trap=@var{number}
-Specifies the trap number to use to flush the cache. The default is
-12. Valid numbers are between 0 and 15 inclusive.
-
-@item -mno-flush-trap
-@opindex mno-flush-trap
-Specifies that the cache cannot be flushed by using a trap.
-
-@item -mflush-func=@var{name}
-@opindex mflush-func=@var{name}
-Specifies the name of the operating system function to call to flush
-the cache. The default is @samp{_flush_cache}, but a function call
-is only used if a trap is not available.
-
-@item -mno-flush-func
-@opindex mno-flush-func
-Indicates that there is no OS function for flushing the cache.
-
-@end table
-
-@node M680x0 Options
-@subsection M680x0 Options
-@cindex M680x0 options
-
-These are the @samp{-m} options defined for M680x0 and ColdFire processors.
-The default settings depend on which architecture was selected when
-the compiler was configured; the defaults for the most common choices
-are given below.
-
-@table @gcctabopt
-@item -march=@var{arch}
-@opindex march
-Generate code for a specific M680x0 or ColdFire instruction set
-architecture. Permissible values of @var{arch} for M680x0
-architectures are: @samp{68000}, @samp{68010}, @samp{68020},
-@samp{68030}, @samp{68040}, @samp{68060} and @samp{cpu32}. ColdFire
-architectures are selected according to Freescale's ISA classification
-and the permissible values are: @samp{isaa}, @samp{isaaplus},
-@samp{isab} and @samp{isac}.
-
-GCC defines a macro @code{__mcf@var{arch}__} whenever it is generating
-code for a ColdFire target. The @var{arch} in this macro is one of the
-@option{-march} arguments given above.
-
-When used together, @option{-march} and @option{-mtune} select code
-that runs on a family of similar processors but that is optimized
-for a particular microarchitecture.
-
-@item -mcpu=@var{cpu}
-@opindex mcpu
-Generate code for a specific M680x0 or ColdFire processor.
-The M680x0 @var{cpu}s are: @samp{68000}, @samp{68010}, @samp{68020},
-@samp{68030}, @samp{68040}, @samp{68060}, @samp{68302}, @samp{68332}
-and @samp{cpu32}. The ColdFire @var{cpu}s are given by the table
-below, which also classifies the CPUs into families:
-
-@multitable @columnfractions 0.20 0.80
-@headitem @strong{Family} @tab @strong{@samp{-mcpu} arguments}
-@item @samp{51} @tab @samp{51} @samp{51ac} @samp{51ag} @samp{51cn} @samp{51em} @samp{51je} @samp{51jf} @samp{51jg} @samp{51jm} @samp{51mm} @samp{51qe} @samp{51qm}
-@item @samp{5206} @tab @samp{5202} @samp{5204} @samp{5206}
-@item @samp{5206e} @tab @samp{5206e}
-@item @samp{5208} @tab @samp{5207} @samp{5208}
-@item @samp{5211a} @tab @samp{5210a} @samp{5211a}
-@item @samp{5213} @tab @samp{5211} @samp{5212} @samp{5213}
-@item @samp{5216} @tab @samp{5214} @samp{5216}
-@item @samp{52235} @tab @samp{52230} @samp{52231} @samp{52232} @samp{52233} @samp{52234} @samp{52235}
-@item @samp{5225} @tab @samp{5224} @samp{5225}
-@item @samp{52259} @tab @samp{52252} @samp{52254} @samp{52255} @samp{52256} @samp{52258} @samp{52259}
-@item @samp{5235} @tab @samp{5232} @samp{5233} @samp{5234} @samp{5235} @samp{523x}
-@item @samp{5249} @tab @samp{5249}
-@item @samp{5250} @tab @samp{5250}
-@item @samp{5271} @tab @samp{5270} @samp{5271}
-@item @samp{5272} @tab @samp{5272}
-@item @samp{5275} @tab @samp{5274} @samp{5275}
-@item @samp{5282} @tab @samp{5280} @samp{5281} @samp{5282} @samp{528x}
-@item @samp{53017} @tab @samp{53011} @samp{53012} @samp{53013} @samp{53014} @samp{53015} @samp{53016} @samp{53017}
-@item @samp{5307} @tab @samp{5307}
-@item @samp{5329} @tab @samp{5327} @samp{5328} @samp{5329} @samp{532x}
-@item @samp{5373} @tab @samp{5372} @samp{5373} @samp{537x}
-@item @samp{5407} @tab @samp{5407}
-@item @samp{5475} @tab @samp{5470} @samp{5471} @samp{5472} @samp{5473} @samp{5474} @samp{5475} @samp{547x} @samp{5480} @samp{5481} @samp{5482} @samp{5483} @samp{5484} @samp{5485}
-@end multitable
-
-@option{-mcpu=@var{cpu}} overrides @option{-march=@var{arch}} if
-@var{arch} is compatible with @var{cpu}. Other combinations of
-@option{-mcpu} and @option{-march} are rejected.
-
-GCC defines the macro @code{__mcf_cpu_@var{cpu}} when ColdFire target
-@var{cpu} is selected. It also defines @code{__mcf_family_@var{family}},
-where the value of @var{family} is given by the table above.
-
-@item -mtune=@var{tune}
-@opindex mtune
-Tune the code for a particular microarchitecture within the
-constraints set by @option{-march} and @option{-mcpu}.
-The M680x0 microarchitectures are: @samp{68000}, @samp{68010},
-@samp{68020}, @samp{68030}, @samp{68040}, @samp{68060}
-and @samp{cpu32}. The ColdFire microarchitectures
-are: @samp{cfv1}, @samp{cfv2}, @samp{cfv3}, @samp{cfv4} and @samp{cfv4e}.
-
-You can also use @option{-mtune=68020-40} for code that needs
-to run relatively well on 68020, 68030 and 68040 targets.
-@option{-mtune=68020-60} is similar but includes 68060 targets
-as well. These two options select the same tuning decisions as
-@option{-m68020-40} and @option{-m68020-60} respectively.
-
-GCC defines the macros @code{__mc@var{arch}} and @code{__mc@var{arch}__}
-when tuning for 680x0 architecture @var{arch}. It also defines
-@code{mc@var{arch}} unless either @option{-ansi} or a non-GNU @option{-std}
-option is used. If GCC is tuning for a range of architectures,
-as selected by @option{-mtune=68020-40} or @option{-mtune=68020-60},
-it defines the macros for every architecture in the range.
-
-GCC also defines the macro @code{__m@var{uarch}__} when tuning for
-ColdFire microarchitecture @var{uarch}, where @var{uarch} is one
-of the arguments given above.
-
-@item -m68000
-@itemx -mc68000
-@opindex m68000
-@opindex mc68000
-Generate output for a 68000. This is the default
-when the compiler is configured for 68000-based systems.
-It is equivalent to @option{-march=68000}.
-
-Use this option for microcontrollers with a 68000 or EC000 core,
-including the 68008, 68302, 68306, 68307, 68322, 68328 and 68356.
-
-@item -m68010
-@opindex m68010
-Generate output for a 68010. This is the default
-when the compiler is configured for 68010-based systems.
-It is equivalent to @option{-march=68010}.
-
-@item -m68020
-@itemx -mc68020
-@opindex m68020
-@opindex mc68020
-Generate output for a 68020. This is the default
-when the compiler is configured for 68020-based systems.
-It is equivalent to @option{-march=68020}.
-
-@item -m68030
-@opindex m68030
-Generate output for a 68030. This is the default when the compiler is
-configured for 68030-based systems. It is equivalent to
-@option{-march=68030}.
-
-@item -m68040
-@opindex m68040
-Generate output for a 68040. This is the default when the compiler is
-configured for 68040-based systems. It is equivalent to
-@option{-march=68040}.
-
-This option inhibits the use of 68881/68882 instructions that have to be
-emulated by software on the 68040. Use this option if your 68040 does not
-have code to emulate those instructions.
-
-@item -m68060
-@opindex m68060
-Generate output for a 68060. This is the default when the compiler is
-configured for 68060-based systems. It is equivalent to
-@option{-march=68060}.
-
-This option inhibits the use of 68020 and 68881/68882 instructions that
-have to be emulated by software on the 68060. Use this option if your 68060
-does not have code to emulate those instructions.
-
-@item -mcpu32
-@opindex mcpu32
-Generate output for a CPU32. This is the default
-when the compiler is configured for CPU32-based systems.
-It is equivalent to @option{-march=cpu32}.
-
-Use this option for microcontrollers with a
-CPU32 or CPU32+ core, including the 68330, 68331, 68332, 68333, 68334,
-68336, 68340, 68341, 68349 and 68360.
-
-@item -m5200
-@opindex m5200
-Generate output for a 520X ColdFire CPU@. This is the default
-when the compiler is configured for 520X-based systems.
-It is equivalent to @option{-mcpu=5206}, and is now deprecated
-in favor of that option.
-
-Use this option for microcontroller with a 5200 core, including
-the MCF5202, MCF5203, MCF5204 and MCF5206.
-
-@item -m5206e
-@opindex m5206e
-Generate output for a 5206e ColdFire CPU@. The option is now
-deprecated in favor of the equivalent @option{-mcpu=5206e}.
-
-@item -m528x
-@opindex m528x
-Generate output for a member of the ColdFire 528X family.
-The option is now deprecated in favor of the equivalent
-@option{-mcpu=528x}.
-
-@item -m5307
-@opindex m5307
-Generate output for a ColdFire 5307 CPU@. The option is now deprecated
-in favor of the equivalent @option{-mcpu=5307}.
-
-@item -m5407
-@opindex m5407
-Generate output for a ColdFire 5407 CPU@. The option is now deprecated
-in favor of the equivalent @option{-mcpu=5407}.
-
-@item -mcfv4e
-@opindex mcfv4e
-Generate output for a ColdFire V4e family CPU (e.g.@: 547x/548x).
-This includes use of hardware floating-point instructions.
-The option is equivalent to @option{-mcpu=547x}, and is now
-deprecated in favor of that option.
-
-@item -m68020-40
-@opindex m68020-40
-Generate output for a 68040, without using any of the new instructions.
-This results in code that can run relatively efficiently on either a
-68020/68881 or a 68030 or a 68040. The generated code does use the
-68881 instructions that are emulated on the 68040.
-
-The option is equivalent to @option{-march=68020} @option{-mtune=68020-40}.
-
-@item -m68020-60
-@opindex m68020-60
-Generate output for a 68060, without using any of the new instructions.
-This results in code that can run relatively efficiently on either a
-68020/68881 or a 68030 or a 68040. The generated code does use the
-68881 instructions that are emulated on the 68060.
-
-The option is equivalent to @option{-march=68020} @option{-mtune=68020-60}.
-
-@item -mhard-float
-@itemx -m68881
-@opindex mhard-float
-@opindex m68881
-Generate floating-point instructions. This is the default for 68020
-and above, and for ColdFire devices that have an FPU@. It defines the
-macro @code{__HAVE_68881__} on M680x0 targets and @code{__mcffpu__}
-on ColdFire targets.
-
-@item -msoft-float
-@opindex msoft-float
-Do not generate floating-point instructions; use library calls instead.
-This is the default for 68000, 68010, and 68832 targets. It is also
-the default for ColdFire devices that have no FPU.
-
-@item -mdiv
-@itemx -mno-div
-@opindex mdiv
-@opindex mno-div
-Generate (do not generate) ColdFire hardware divide and remainder
-instructions. If @option{-march} is used without @option{-mcpu},
-the default is ``on'' for ColdFire architectures and ``off'' for M680x0
-architectures. Otherwise, the default is taken from the target CPU
-(either the default CPU, or the one specified by @option{-mcpu}). For
-example, the default is ``off'' for @option{-mcpu=5206} and ``on'' for
-@option{-mcpu=5206e}.
-
-GCC defines the macro @code{__mcfhwdiv__} when this option is enabled.
-
-@item -mshort
-@opindex mshort
-Consider type @code{int} to be 16 bits wide, like @code{short int}.
-Additionally, parameters passed on the stack are also aligned to a
-16-bit boundary even on targets whose API mandates promotion to 32-bit.
-
-@item -mno-short
-@opindex mno-short
-Do not consider type @code{int} to be 16 bits wide. This is the default.
-
-@item -mnobitfield
-@itemx -mno-bitfield
-@opindex mnobitfield
-@opindex mno-bitfield
-Do not use the bit-field instructions. The @option{-m68000}, @option{-mcpu32}
-and @option{-m5200} options imply @w{@option{-mnobitfield}}.
-
-@item -mbitfield
-@opindex mbitfield
-Do use the bit-field instructions. The @option{-m68020} option implies
-@option{-mbitfield}. This is the default if you use a configuration
-designed for a 68020.
-
-@item -mrtd
-@opindex mrtd
-Use a different function-calling convention, in which functions
-that take a fixed number of arguments return with the @code{rtd}
-instruction, which pops their arguments while returning. This
-saves one instruction in the caller since there is no need to pop
-the arguments there.
-
-This calling convention is incompatible with the one normally
-used on Unix, so you cannot use it if you need to call libraries
-compiled with the Unix compiler.
-
-Also, you must provide function prototypes for all functions that
-take variable numbers of arguments (including @code{printf});
-otherwise incorrect code is generated for calls to those
-functions.
-
-In addition, seriously incorrect code results if you call a
-function with too many arguments. (Normally, extra arguments are
-harmlessly ignored.)
-
-The @code{rtd} instruction is supported by the 68010, 68020, 68030,
-68040, 68060 and CPU32 processors, but not by the 68000 or 5200.
-
-The default is @option{-mno-rtd}.
-
-@item -malign-int
-@itemx -mno-align-int
-@opindex malign-int
-@opindex mno-align-int
-Control whether GCC aligns @code{int}, @code{long}, @code{long long},
-@code{float}, @code{double}, and @code{long double} variables on a 32-bit
-boundary (@option{-malign-int}) or a 16-bit boundary (@option{-mno-align-int}).
-Aligning variables on 32-bit boundaries produces code that runs somewhat
-faster on processors with 32-bit busses at the expense of more memory.
-
-@strong{Warning:} if you use the @option{-malign-int} switch, GCC
-aligns structures containing the above types differently than
-most published application binary interface specifications for the m68k.
-
-@opindex mpcrel
-Use the pc-relative addressing mode of the 68000 directly, instead of
-using a global offset table. At present, this option implies @option{-fpic},
-allowing at most a 16-bit offset for pc-relative addressing. @option{-fPIC} is
-not presently supported with @option{-mpcrel}, though this could be supported for
-68020 and higher processors.
-
-@item -mno-strict-align
-@itemx -mstrict-align
-@opindex mno-strict-align
-@opindex mstrict-align
-Do not (do) assume that unaligned memory references are handled by
-the system.
-
-@item -msep-data
-Generate code that allows the data segment to be located in a different
-area of memory from the text segment. This allows for execute-in-place in
-an environment without virtual memory management. This option implies
-@option{-fPIC}.
-
-@item -mno-sep-data
-Generate code that assumes that the data segment follows the text segment.
-This is the default.
-
-@item -mid-shared-library
-Generate code that supports shared libraries via the library ID method.
-This allows for execute-in-place and shared libraries in an environment
-without virtual memory management. This option implies @option{-fPIC}.
-
-@item -mno-id-shared-library
-Generate code that doesn't assume ID-based shared libraries are being used.
-This is the default.
-
-@item -mshared-library-id=n
-Specifies the identification number of the ID-based shared library being
-compiled. Specifying a value of 0 generates more compact code; specifying
-other values forces the allocation of that number to the current
-library, but is no more space- or time-efficient than omitting this option.
-
-@item -mxgot
-@itemx -mno-xgot
-@opindex mxgot
-@opindex mno-xgot
-When generating position-independent code for ColdFire, generate code
-that works if the GOT has more than 8192 entries. This code is
-larger and slower than code generated without this option. On M680x0
-processors, this option is not needed; @option{-fPIC} suffices.
-
-GCC normally uses a single instruction to load values from the GOT@.
-While this is relatively efficient, it only works if the GOT
-is smaller than about 64k. Anything larger causes the linker
-to report an error such as:
-
-@cindex relocation truncated to fit (ColdFire)
-@smallexample
-relocation truncated to fit: R_68K_GOT16O foobar
-@end smallexample
-
-If this happens, you should recompile your code with @option{-mxgot}.
-It should then work with very large GOTs. However, code generated with
-@option{-mxgot} is less efficient, since it takes 4 instructions to fetch
-the value of a global symbol.
-
-Note that some linkers, including newer versions of the GNU linker,
-can create multiple GOTs and sort GOT entries. If you have such a linker,
-you should only need to use @option{-mxgot} when compiling a single
-object file that accesses more than 8192 GOT entries. Very few do.
-
-These options have no effect unless GCC is generating
-position-independent code.
-
-@item -mlong-jump-table-offsets
-@opindex mlong-jump-table-offsets
-Use 32-bit offsets in @code{switch} tables. The default is to use
-16-bit offsets.
-
-@end table
-
-@node MCore Options
-@subsection MCore Options
-@cindex MCore options
-
-These are the @samp{-m} options defined for the Motorola M*Core
-processors.
-
-@table @gcctabopt
-
-@item -mhardlit
-@itemx -mno-hardlit
-@opindex mhardlit
-@opindex mno-hardlit
-Inline constants into the code stream if it can be done in two
-instructions or less.
-
-@item -mdiv
-@itemx -mno-div
-@opindex mdiv
-@opindex mno-div
-Use the divide instruction. (Enabled by default).
-
-@item -mrelax-immediate
-@itemx -mno-relax-immediate
-@opindex mrelax-immediate
-@opindex mno-relax-immediate
-Allow arbitrary-sized immediates in bit operations.
-
-@item -mwide-bitfields
-@itemx -mno-wide-bitfields
-@opindex mwide-bitfields
-@opindex mno-wide-bitfields
-Always treat bit-fields as @code{int}-sized.
-
-@item -m4byte-functions
-@itemx -mno-4byte-functions
-@opindex m4byte-functions
-@opindex mno-4byte-functions
-Force all functions to be aligned to a 4-byte boundary.
-
-@item -mcallgraph-data
-@itemx -mno-callgraph-data
-@opindex mcallgraph-data
-@opindex mno-callgraph-data
-Emit callgraph information.
-
-@item -mslow-bytes
-@itemx -mno-slow-bytes
-@opindex mslow-bytes
-@opindex mno-slow-bytes
-Prefer word access when reading byte quantities.
-
-@item -mlittle-endian
-@itemx -mbig-endian
-@opindex mlittle-endian
-@opindex mbig-endian
-Generate code for a little-endian target.
-
-@item -m210
-@itemx -m340
-@opindex m210
-@opindex m340
-Generate code for the 210 processor.
-
-@item -mno-lsim
-@opindex mno-lsim
-Assume that runtime support has been provided and so omit the
-simulator library (@file{libsim.a)} from the linker command line.
-
-@item -mstack-increment=@var{size}
-@opindex mstack-increment
-Set the maximum amount for a single stack increment operation. Large
-values can increase the speed of programs that contain functions
-that need a large amount of stack space, but they can also trigger a
-segmentation fault if the stack is extended too much. The default
-value is 0x1000.
-
-@end table
-
-@node MeP Options
-@subsection MeP Options
-@cindex MeP options
-
-@table @gcctabopt
-
-@item -mabsdiff
-@opindex mabsdiff
-Enables the @code{abs} instruction, which is the absolute difference
-between two registers.
-
-@item -mall-opts
-@opindex mall-opts
-Enables all the optional instructions---average, multiply, divide, bit
-operations, leading zero, absolute difference, min/max, clip, and
-saturation.
-
-
-@item -maverage
-@opindex maverage
-Enables the @code{ave} instruction, which computes the average of two
-registers.
-
-@item -mbased=@var{n}
-@opindex mbased=
-Variables of size @var{n} bytes or smaller are placed in the
-@code{.based} section by default. Based variables use the @code{$tp}
-register as a base register, and there is a 128-byte limit to the
-@code{.based} section.
-
-@item -mbitops
-@opindex mbitops
-Enables the bit operation instructions---bit test (@code{btstm}), set
-(@code{bsetm}), clear (@code{bclrm}), invert (@code{bnotm}), and
-test-and-set (@code{tas}).
-
-@item -mc=@var{name}
-@opindex mc=
-Selects which section constant data is placed in. @var{name} may
-be @samp{tiny}, @samp{near}, or @samp{far}.
-
-@item -mclip
-@opindex mclip
-Enables the @code{clip} instruction. Note that @option{-mclip} is not
-useful unless you also provide @option{-mminmax}.
-
-@item -mconfig=@var{name}
-@opindex mconfig=
-Selects one of the built-in core configurations. Each MeP chip has
-one or more modules in it; each module has a core CPU and a variety of
-coprocessors, optional instructions, and peripherals. The
-@code{MeP-Integrator} tool, not part of GCC, provides these
-configurations through this option; using this option is the same as
-using all the corresponding command-line options. The default
-configuration is @samp{default}.
-
-@item -mcop
-@opindex mcop
-Enables the coprocessor instructions. By default, this is a 32-bit
-coprocessor. Note that the coprocessor is normally enabled via the
-@option{-mconfig=} option.
-
-@item -mcop32
-@opindex mcop32
-Enables the 32-bit coprocessor's instructions.
-
-@item -mcop64
-@opindex mcop64
-Enables the 64-bit coprocessor's instructions.
-
-@item -mivc2
-@opindex mivc2
-Enables IVC2 scheduling. IVC2 is a 64-bit VLIW coprocessor.
-
-@item -mdc
-@opindex mdc
-Causes constant variables to be placed in the @code{.near} section.
-
-@item -mdiv
-@opindex mdiv
-Enables the @code{div} and @code{divu} instructions.
-
-@item -meb
-@opindex meb
-Generate big-endian code.
-
-@item -mel
-@opindex mel
-Generate little-endian code.
-
-@item -mio-volatile
-@opindex mio-volatile
-Tells the compiler that any variable marked with the @code{io}
-attribute is to be considered volatile.
-
-@item -ml
-@opindex ml
-Causes variables to be assigned to the @code{.far} section by default.
-
-@item -mleadz
-@opindex mleadz
-Enables the @code{leadz} (leading zero) instruction.
-
-@item -mm
-@opindex mm
-Causes variables to be assigned to the @code{.near} section by default.
-
-@item -mminmax
-@opindex mminmax
-Enables the @code{min} and @code{max} instructions.
-
-@item -mmult
-@opindex mmult
-Enables the multiplication and multiply-accumulate instructions.
-
-@item -mno-opts
-@opindex mno-opts
-Disables all the optional instructions enabled by @option{-mall-opts}.
-
-@item -mrepeat
-@opindex mrepeat
-Enables the @code{repeat} and @code{erepeat} instructions, used for
-low-overhead looping.
-
-@item -ms
-@opindex ms
-Causes all variables to default to the @code{.tiny} section. Note
-that there is a 65536-byte limit to this section. Accesses to these
-variables use the @code{%gp} base register.
-
-@item -msatur
-@opindex msatur
-Enables the saturation instructions. Note that the compiler does not
-currently generate these itself, but this option is included for
-compatibility with other tools, like @code{as}.
-
-@item -msdram
-@opindex msdram
-Link the SDRAM-based runtime instead of the default ROM-based runtime.
-
-@item -msim
-@opindex msim
-Link the simulator run-time libraries.
-
-@item -msimnovec
-@opindex msimnovec
-Link the simulator runtime libraries, excluding built-in support
-for reset and exception vectors and tables.
-
-@item -mtf
-@opindex mtf
-Causes all functions to default to the @code{.far} section. Without
-this option, functions default to the @code{.near} section.
-
-@item -mtiny=@var{n}
-@opindex mtiny=
-Variables that are @var{n} bytes or smaller are allocated to the
-@code{.tiny} section. These variables use the @code{$gp} base
-register. The default for this option is 4, but note that there's a
-65536-byte limit to the @code{.tiny} section.
-
-@end table
-
-@node MicroBlaze Options
-@subsection MicroBlaze Options
-@cindex MicroBlaze Options
-
-@table @gcctabopt
-
-@item -msoft-float
-@opindex msoft-float
-Use software emulation for floating point (default).
-
-@item -mhard-float
-@opindex mhard-float
-Use hardware floating-point instructions.
-
-@item -mmemcpy
-@opindex mmemcpy
-Do not optimize block moves, use @code{memcpy}.
-
-@item -mno-clearbss
-@opindex mno-clearbss
-This option is deprecated. Use @option{-fno-zero-initialized-in-bss} instead.
-
-@item -mcpu=@var{cpu-type}
-@opindex mcpu=
-Use features of, and schedule code for, the given CPU.
-Supported values are in the format @samp{v@var{X}.@var{YY}.@var{Z}},
-where @var{X} is a major version, @var{YY} is the minor version, and
-@var{Z} is compatibility code. Example values are @samp{v3.00.a},
-@samp{v4.00.b}, @samp{v5.00.a}, @samp{v5.00.b}, @samp{v6.00.a}.
-
-@item -mxl-soft-mul
-@opindex mxl-soft-mul
-Use software multiply emulation (default).
-
-@item -mxl-soft-div
-@opindex mxl-soft-div
-Use software emulation for divides (default).
-
-@item -mxl-barrel-shift
-@opindex mxl-barrel-shift
-Use the hardware barrel shifter.
-
-@item -mxl-pattern-compare
-@opindex mxl-pattern-compare
-Use pattern compare instructions.
-
-@item -msmall-divides
-@opindex msmall-divides
-Use table lookup optimization for small signed integer divisions.
-
-@item -mxl-stack-check
-@opindex mxl-stack-check
-This option is deprecated. Use @option{-fstack-check} instead.
-
-@item -mxl-gp-opt
-@opindex mxl-gp-opt
-Use GP-relative @code{.sdata}/@code{.sbss} sections.
-
-@item -mxl-multiply-high
-@opindex mxl-multiply-high
-Use multiply high instructions for high part of 32x32 multiply.
-
-@item -mxl-float-convert
-@opindex mxl-float-convert
-Use hardware floating-point conversion instructions.
-
-@item -mxl-float-sqrt
-@opindex mxl-float-sqrt
-Use hardware floating-point square root instruction.
-
-@item -mbig-endian
-@opindex mbig-endian
-Generate code for a big-endian target.
-
-@item -mlittle-endian
-@opindex mlittle-endian
-Generate code for a little-endian target.
-
-@item -mxl-reorder
-@opindex mxl-reorder
-Use reorder instructions (swap and byte reversed load/store).
-
-@item -mxl-mode-@var{app-model}
-Select application model @var{app-model}. Valid models are
-@table @samp
-@item executable
-normal executable (default), uses startup code @file{crt0.o}.
-
-@item xmdstub
-for use with Xilinx Microprocessor Debugger (XMD) based
-software intrusive debug agent called xmdstub. This uses startup file
-@file{crt1.o} and sets the start address of the program to 0x800.
-
-@item bootstrap
-for applications that are loaded using a bootloader.
-This model uses startup file @file{crt2.o} which does not contain a processor
-reset vector handler. This is suitable for transferring control on a
-processor reset to the bootloader rather than the application.
-
-@item novectors
-for applications that do not require any of the
-MicroBlaze vectors. This option may be useful for applications running
-within a monitoring application. This model uses @file{crt3.o} as a startup file.
-@end table
-
-Option @option{-xl-mode-@var{app-model}} is a deprecated alias for
-@option{-mxl-mode-@var{app-model}}.
-
-@item -mpic-data-is-text-relative
-@opindex mpic-data-is-text-relative
-Assume that the displacement between the text and data segments is fixed
-at static link time. This allows data to be referenced by offset from start of
-text address instead of GOT since PC-relative addressing is not supported.
-
-@end table
-
-@node MIPS Options
-@subsection MIPS Options
-@cindex MIPS options
-
-@table @gcctabopt
-
-@item -EB
-@opindex EB
-Generate big-endian code.
-
-@item -EL
-@opindex EL
-Generate little-endian code. This is the default for @samp{mips*el-*-*}
-configurations.
-
-@item -march=@var{arch}
-@opindex march
-Generate code that runs on @var{arch}, which can be the name of a
-generic MIPS ISA, or the name of a particular processor.
-The ISA names are:
-@samp{mips1}, @samp{mips2}, @samp{mips3}, @samp{mips4},
-@samp{mips32}, @samp{mips32r2}, @samp{mips32r3}, @samp{mips32r5},
-@samp{mips32r6}, @samp{mips64}, @samp{mips64r2}, @samp{mips64r3},
-@samp{mips64r5} and @samp{mips64r6}.
-The processor names are:
-@samp{4kc}, @samp{4km}, @samp{4kp}, @samp{4ksc},
-@samp{4kec}, @samp{4kem}, @samp{4kep}, @samp{4ksd},
-@samp{5kc}, @samp{5kf},
-@samp{20kc},
-@samp{24kc}, @samp{24kf2_1}, @samp{24kf1_1},
-@samp{24kec}, @samp{24kef2_1}, @samp{24kef1_1},
-@samp{34kc}, @samp{34kf2_1}, @samp{34kf1_1}, @samp{34kn},
-@samp{74kc}, @samp{74kf2_1}, @samp{74kf1_1}, @samp{74kf3_2},
-@samp{1004kc}, @samp{1004kf2_1}, @samp{1004kf1_1},
-@samp{i6400}, @samp{i6500},
-@samp{interaptiv},
-@samp{loongson2e}, @samp{loongson2f}, @samp{loongson3a}, @samp{gs464},
-@samp{gs464e}, @samp{gs264e},
-@samp{m4k},
-@samp{m14k}, @samp{m14kc}, @samp{m14ke}, @samp{m14kec},
-@samp{m5100}, @samp{m5101},
-@samp{octeon}, @samp{octeon+}, @samp{octeon2}, @samp{octeon3},
-@samp{orion},
-@samp{p5600}, @samp{p6600},
-@samp{r2000}, @samp{r3000}, @samp{r3900}, @samp{r4000}, @samp{r4400},
-@samp{r4600}, @samp{r4650}, @samp{r4700}, @samp{r5900},
-@samp{r6000}, @samp{r8000},
-@samp{rm7000}, @samp{rm9000},
-@samp{r10000}, @samp{r12000}, @samp{r14000}, @samp{r16000},
-@samp{sb1},
-@samp{sr71000},
-@samp{vr4100}, @samp{vr4111}, @samp{vr4120}, @samp{vr4130}, @samp{vr4300},
-@samp{vr5000}, @samp{vr5400}, @samp{vr5500},
-@samp{xlr} and @samp{xlp}.
-The special value @samp{from-abi} selects the
-most compatible architecture for the selected ABI (that is,
-@samp{mips1} for 32-bit ABIs and @samp{mips3} for 64-bit ABIs)@.
-
-The native Linux/GNU toolchain also supports the value @samp{native},
-which selects the best architecture option for the host processor.
-@option{-march=native} has no effect if GCC does not recognize
-the processor.
-
-In processor names, a final @samp{000} can be abbreviated as @samp{k}
-(for example, @option{-march=r2k}). Prefixes are optional, and
-@samp{vr} may be written @samp{r}.
-
-Names of the form @samp{@var{n}f2_1} refer to processors with
-FPUs clocked at half the rate of the core, names of the form
-@samp{@var{n}f1_1} refer to processors with FPUs clocked at the same
-rate as the core, and names of the form @samp{@var{n}f3_2} refer to
-processors with FPUs clocked a ratio of 3:2 with respect to the core.
-For compatibility reasons, @samp{@var{n}f} is accepted as a synonym
-for @samp{@var{n}f2_1} while @samp{@var{n}x} and @samp{@var{b}fx} are
-accepted as synonyms for @samp{@var{n}f1_1}.
-
-GCC defines two macros based on the value of this option. The first
-is @code{_MIPS_ARCH}, which gives the name of target architecture, as
-a string. The second has the form @code{_MIPS_ARCH_@var{foo}},
-where @var{foo} is the capitalized value of @code{_MIPS_ARCH}@.
-For example, @option{-march=r2000} sets @code{_MIPS_ARCH}
-to @code{"r2000"} and defines the macro @code{_MIPS_ARCH_R2000}.
-
-Note that the @code{_MIPS_ARCH} macro uses the processor names given
-above. In other words, it has the full prefix and does not
-abbreviate @samp{000} as @samp{k}. In the case of @samp{from-abi},
-the macro names the resolved architecture (either @code{"mips1"} or
-@code{"mips3"}). It names the default architecture when no
-@option{-march} option is given.
-
-@item -mtune=@var{arch}
-@opindex mtune
-Optimize for @var{arch}. Among other things, this option controls
-the way instructions are scheduled, and the perceived cost of arithmetic
-operations. The list of @var{arch} values is the same as for
-@option{-march}.
-
-When this option is not used, GCC optimizes for the processor
-specified by @option{-march}. By using @option{-march} and
-@option{-mtune} together, it is possible to generate code that
-runs on a family of processors, but optimize the code for one
-particular member of that family.
-
-@option{-mtune} defines the macros @code{_MIPS_TUNE} and
-@code{_MIPS_TUNE_@var{foo}}, which work in the same way as the
-@option{-march} ones described above.
-
-@item -mips1
-@opindex mips1
-Equivalent to @option{-march=mips1}.
-
-@item -mips2
-@opindex mips2
-Equivalent to @option{-march=mips2}.
-
-@item -mips3
-@opindex mips3
-Equivalent to @option{-march=mips3}.
-
-@item -mips4
-@opindex mips4
-Equivalent to @option{-march=mips4}.
-
-@item -mips32
-@opindex mips32
-Equivalent to @option{-march=mips32}.
-
-@item -mips32r3
-@opindex mips32r3
-Equivalent to @option{-march=mips32r3}.
-
-@item -mips32r5
-@opindex mips32r5
-Equivalent to @option{-march=mips32r5}.
-
-@item -mips32r6
-@opindex mips32r6
-Equivalent to @option{-march=mips32r6}.
-
-@item -mips64
-@opindex mips64
-Equivalent to @option{-march=mips64}.
-
-@item -mips64r2
-@opindex mips64r2
-Equivalent to @option{-march=mips64r2}.
-
-@item -mips64r3
-@opindex mips64r3
-Equivalent to @option{-march=mips64r3}.
-
-@item -mips64r5
-@opindex mips64r5
-Equivalent to @option{-march=mips64r5}.
-
-@item -mips64r6
-@opindex mips64r6
-Equivalent to @option{-march=mips64r6}.
-
-@item -mips16
-@itemx -mno-mips16
-@opindex mips16
-@opindex mno-mips16
-Generate (do not generate) MIPS16 code. If GCC is targeting a
-MIPS32 or MIPS64 architecture, it makes use of the MIPS16e ASE@.
-
-MIPS16 code generation can also be controlled on a per-function basis
-by means of @code{mips16} and @code{nomips16} attributes.
-@xref{Function Attributes}, for more information.
-
-@item -mflip-mips16
-@opindex mflip-mips16
-Generate MIPS16 code on alternating functions. This option is provided
-for regression testing of mixed MIPS16/non-MIPS16 code generation, and is
-not intended for ordinary use in compiling user code.
-
-@item -minterlink-compressed
-@itemx -mno-interlink-compressed
-@opindex minterlink-compressed
-@opindex mno-interlink-compressed
-Require (do not require) that code using the standard (uncompressed) MIPS ISA
-be link-compatible with MIPS16 and microMIPS code, and vice versa.
-
-For example, code using the standard ISA encoding cannot jump directly
-to MIPS16 or microMIPS code; it must either use a call or an indirect jump.
-@option{-minterlink-compressed} therefore disables direct jumps unless GCC
-knows that the target of the jump is not compressed.
-
-@item -minterlink-mips16
-@itemx -mno-interlink-mips16
-@opindex minterlink-mips16
-@opindex mno-interlink-mips16
-Aliases of @option{-minterlink-compressed} and
-@option{-mno-interlink-compressed}. These options predate the microMIPS ASE
-and are retained for backwards compatibility.
-
-@item -mabi=32
-@itemx -mabi=o64
-@itemx -mabi=n32
-@itemx -mabi=64
-@itemx -mabi=eabi
-@opindex mabi=32
-@opindex mabi=o64
-@opindex mabi=n32
-@opindex mabi=64
-@opindex mabi=eabi
-Generate code for the given ABI@.
-
-Note that the EABI has a 32-bit and a 64-bit variant. GCC normally
-generates 64-bit code when you select a 64-bit architecture, but you
-can use @option{-mgp32} to get 32-bit code instead.
-
-For information about the O64 ABI, see
-@uref{https://gcc.gnu.org/@/projects/@/mipso64-abi.html}.
-
-GCC supports a variant of the o32 ABI in which floating-point registers
-are 64 rather than 32 bits wide. You can select this combination with
-@option{-mabi=32} @option{-mfp64}. This ABI relies on the @code{mthc1}
-and @code{mfhc1} instructions and is therefore only supported for
-MIPS32R2, MIPS32R3 and MIPS32R5 processors.
-
-The register assignments for arguments and return values remain the
-same, but each scalar value is passed in a single 64-bit register
-rather than a pair of 32-bit registers. For example, scalar
-floating-point values are returned in @samp{$f0} only, not a
-@samp{$f0}/@samp{$f1} pair. The set of call-saved registers also
-remains the same in that the even-numbered double-precision registers
-are saved.
-
-Two additional variants of the o32 ABI are supported to enable
-a transition from 32-bit to 64-bit registers. These are FPXX
-(@option{-mfpxx}) and FP64A (@option{-mfp64} @option{-mno-odd-spreg}).
-The FPXX extension mandates that all code must execute correctly
-when run using 32-bit or 64-bit registers. The code can be interlinked
-with either FP32 or FP64, but not both.
-The FP64A extension is similar to the FP64 extension but forbids the
-use of odd-numbered single-precision registers. This can be used
-in conjunction with the @code{FRE} mode of FPUs in MIPS32R5
-processors and allows both FP32 and FP64A code to interlink and
-run in the same process without changing FPU modes.
-
-@item -mabicalls
-@itemx -mno-abicalls
-@opindex mabicalls
-@opindex mno-abicalls
-Generate (do not generate) code that is suitable for SVR4-style
-dynamic objects. @option{-mabicalls} is the default for SVR4-based
-systems.
-
-@item -mshared
-@itemx -mno-shared
-Generate (do not generate) code that is fully position-independent,
-and that can therefore be linked into shared libraries. This option
-only affects @option{-mabicalls}.
-
-All @option{-mabicalls} code has traditionally been position-independent,
-regardless of options like @option{-fPIC} and @option{-fpic}. However,
-as an extension, the GNU toolchain allows executables to use absolute
-accesses for locally-binding symbols. It can also use shorter GP
-initialization sequences and generate direct calls to locally-defined
-functions. This mode is selected by @option{-mno-shared}.
-
-@option{-mno-shared} depends on binutils 2.16 or higher and generates
-objects that can only be linked by the GNU linker. However, the option
-does not affect the ABI of the final executable; it only affects the ABI
-of relocatable objects. Using @option{-mno-shared} generally makes
-executables both smaller and quicker.
-
-@option{-mshared} is the default.
-
-@item -mplt
-@itemx -mno-plt
-@opindex mplt
-@opindex mno-plt
-Assume (do not assume) that the static and dynamic linkers
-support PLTs and copy relocations. This option only affects
-@option{-mno-shared -mabicalls}. For the n64 ABI, this option
-has no effect without @option{-msym32}.
-
-You can make @option{-mplt} the default by configuring
-GCC with @option{--with-mips-plt}. The default is
-@option{-mno-plt} otherwise.
-
-@item -mxgot
-@itemx -mno-xgot
-@opindex mxgot
-@opindex mno-xgot
-Lift (do not lift) the usual restrictions on the size of the global
-offset table.
-
-GCC normally uses a single instruction to load values from the GOT@.
-While this is relatively efficient, it only works if the GOT
-is smaller than about 64k. Anything larger causes the linker
-to report an error such as:
-
-@cindex relocation truncated to fit (MIPS)
-@smallexample
-relocation truncated to fit: R_MIPS_GOT16 foobar
-@end smallexample
-
-If this happens, you should recompile your code with @option{-mxgot}.
-This works with very large GOTs, although the code is also
-less efficient, since it takes three instructions to fetch the
-value of a global symbol.
-
-Note that some linkers can create multiple GOTs. If you have such a
-linker, you should only need to use @option{-mxgot} when a single object
-file accesses more than 64k's worth of GOT entries. Very few do.
-
-These options have no effect unless GCC is generating position
-independent code.
-
-@item -mgp32
-@opindex mgp32
-Assume that general-purpose registers are 32 bits wide.
-
-@item -mgp64
-@opindex mgp64
-Assume that general-purpose registers are 64 bits wide.
-
-@item -mfp32
-@opindex mfp32
-Assume that floating-point registers are 32 bits wide.
-
-@item -mfp64
-@opindex mfp64
-Assume that floating-point registers are 64 bits wide.
-
-@item -mfpxx
-@opindex mfpxx
-Do not assume the width of floating-point registers.
-
-@item -mhard-float
-@opindex mhard-float
-Use floating-point coprocessor instructions.
-
-@item -msoft-float
-@opindex msoft-float
-Do not use floating-point coprocessor instructions. Implement
-floating-point calculations using library calls instead.
-
-@item -mno-float
-@opindex mno-float
-Equivalent to @option{-msoft-float}, but additionally asserts that the
-program being compiled does not perform any floating-point operations.
-This option is presently supported only by some bare-metal MIPS
-configurations, where it may select a special set of libraries
-that lack all floating-point support (including, for example, the
-floating-point @code{printf} formats).
-If code compiled with @option{-mno-float} accidentally contains
-floating-point operations, it is likely to suffer a link-time
-or run-time failure.
-
-@item -msingle-float
-@opindex msingle-float
-Assume that the floating-point coprocessor only supports single-precision
-operations.
-
-@item -mdouble-float
-@opindex mdouble-float
-Assume that the floating-point coprocessor supports double-precision
-operations. This is the default.
-
-@item -modd-spreg
-@itemx -mno-odd-spreg
-@opindex modd-spreg
-@opindex mno-odd-spreg
-Enable the use of odd-numbered single-precision floating-point registers
-for the o32 ABI. This is the default for processors that are known to
-support these registers. When using the o32 FPXX ABI, @option{-mno-odd-spreg}
-is set by default.
-
-@item -mabs=2008
-@itemx -mabs=legacy
-@opindex mabs=2008
-@opindex mabs=legacy
-These options control the treatment of the special not-a-number (NaN)
-IEEE 754 floating-point data with the @code{abs.@i{fmt}} and
-@code{neg.@i{fmt}} machine instructions.
-
-By default or when @option{-mabs=legacy} is used the legacy
-treatment is selected. In this case these instructions are considered
-arithmetic and avoided where correct operation is required and the
-input operand might be a NaN. A longer sequence of instructions that
-manipulate the sign bit of floating-point datum manually is used
-instead unless the @option{-ffinite-math-only} option has also been
-specified.
-
-The @option{-mabs=2008} option selects the IEEE 754-2008 treatment. In
-this case these instructions are considered non-arithmetic and therefore
-operating correctly in all cases, including in particular where the
-input operand is a NaN. These instructions are therefore always used
-for the respective operations.
-
-@item -mnan=2008
-@itemx -mnan=legacy
-@opindex mnan=2008
-@opindex mnan=legacy
-These options control the encoding of the special not-a-number (NaN)
-IEEE 754 floating-point data.
-
-The @option{-mnan=legacy} option selects the legacy encoding. In this
-case quiet NaNs (qNaNs) are denoted by the first bit of their trailing
-significand field being 0, whereas signaling NaNs (sNaNs) are denoted
-by the first bit of their trailing significand field being 1.
-
-The @option{-mnan=2008} option selects the IEEE 754-2008 encoding. In
-this case qNaNs are denoted by the first bit of their trailing
-significand field being 1, whereas sNaNs are denoted by the first bit of
-their trailing significand field being 0.
-
-The default is @option{-mnan=legacy} unless GCC has been configured with
-@option{--with-nan=2008}.
-
-@item -mllsc
-@itemx -mno-llsc
-@opindex mllsc
-@opindex mno-llsc
-Use (do not use) @samp{ll}, @samp{sc}, and @samp{sync} instructions to
-implement atomic memory built-in functions. When neither option is
-specified, GCC uses the instructions if the target architecture
-supports them.
-
-@option{-mllsc} is useful if the runtime environment can emulate the
-instructions and @option{-mno-llsc} can be useful when compiling for
-nonstandard ISAs. You can make either option the default by
-configuring GCC with @option{--with-llsc} and @option{--without-llsc}
-respectively. @option{--with-llsc} is the default for some
-configurations; see the installation documentation for details.
-
-@item -mdsp
-@itemx -mno-dsp
-@opindex mdsp
-@opindex mno-dsp
-Use (do not use) revision 1 of the MIPS DSP ASE@.
-@xref{MIPS DSP Built-in Functions}. This option defines the
-preprocessor macro @code{__mips_dsp}. It also defines
-@code{__mips_dsp_rev} to 1.
-
-@item -mdspr2
-@itemx -mno-dspr2
-@opindex mdspr2
-@opindex mno-dspr2
-Use (do not use) revision 2 of the MIPS DSP ASE@.
-@xref{MIPS DSP Built-in Functions}. This option defines the
-preprocessor macros @code{__mips_dsp} and @code{__mips_dspr2}.
-It also defines @code{__mips_dsp_rev} to 2.
-
-@item -msmartmips
-@itemx -mno-smartmips
-@opindex msmartmips
-@opindex mno-smartmips
-Use (do not use) the MIPS SmartMIPS ASE.
-
-@item -mpaired-single
-@itemx -mno-paired-single
-@opindex mpaired-single
-@opindex mno-paired-single
-Use (do not use) paired-single floating-point instructions.
-@xref{MIPS Paired-Single Support}. This option requires
-hardware floating-point support to be enabled.
-
-@item -mdmx
-@itemx -mno-mdmx
-@opindex mdmx
-@opindex mno-mdmx
-Use (do not use) MIPS Digital Media Extension instructions.
-This option can only be used when generating 64-bit code and requires
-hardware floating-point support to be enabled.
-
-@item -mips3d
-@itemx -mno-mips3d
-@opindex mips3d
-@opindex mno-mips3d
-Use (do not use) the MIPS-3D ASE@. @xref{MIPS-3D Built-in Functions}.
-The option @option{-mips3d} implies @option{-mpaired-single}.
-
-@item -mmicromips
-@itemx -mno-micromips
-@opindex mmicromips
-@opindex mno-mmicromips
-Generate (do not generate) microMIPS code.
-
-MicroMIPS code generation can also be controlled on a per-function basis
-by means of @code{micromips} and @code{nomicromips} attributes.
-@xref{Function Attributes}, for more information.
-
-@item -mmt
-@itemx -mno-mt
-@opindex mmt
-@opindex mno-mt
-Use (do not use) MT Multithreading instructions.
-
-@item -mmcu
-@itemx -mno-mcu
-@opindex mmcu
-@opindex mno-mcu
-Use (do not use) the MIPS MCU ASE instructions.
-
-@item -meva
-@itemx -mno-eva
-@opindex meva
-@opindex mno-eva
-Use (do not use) the MIPS Enhanced Virtual Addressing instructions.
-
-@item -mvirt
-@itemx -mno-virt
-@opindex mvirt
-@opindex mno-virt
-Use (do not use) the MIPS Virtualization (VZ) instructions.
-
-@item -mxpa
-@itemx -mno-xpa
-@opindex mxpa
-@opindex mno-xpa
-Use (do not use) the MIPS eXtended Physical Address (XPA) instructions.
-
-@item -mcrc
-@itemx -mno-crc
-@opindex mcrc
-@opindex mno-crc
-Use (do not use) the MIPS Cyclic Redundancy Check (CRC) instructions.
-
-@item -mginv
-@itemx -mno-ginv
-@opindex mginv
-@opindex mno-ginv
-Use (do not use) the MIPS Global INValidate (GINV) instructions.
-
-@item -mloongson-mmi
-@itemx -mno-loongson-mmi
-@opindex mloongson-mmi
-@opindex mno-loongson-mmi
-Use (do not use) the MIPS Loongson MultiMedia extensions Instructions (MMI).
-
-@item -mloongson-ext
-@itemx -mno-loongson-ext
-@opindex mloongson-ext
-@opindex mno-loongson-ext
-Use (do not use) the MIPS Loongson EXTensions (EXT) instructions.
-
-@item -mloongson-ext2
-@itemx -mno-loongson-ext2
-@opindex mloongson-ext2
-@opindex mno-loongson-ext2
-Use (do not use) the MIPS Loongson EXTensions r2 (EXT2) instructions.
-
-@item -mlong64
-@opindex mlong64
-Force @code{long} types to be 64 bits wide. See @option{-mlong32} for
-an explanation of the default and the way that the pointer size is
-determined.
-
-@item -mlong32
-@opindex mlong32
-Force @code{long}, @code{int}, and pointer types to be 32 bits wide.
-
-The default size of @code{int}s, @code{long}s and pointers depends on
-the ABI@. All the supported ABIs use 32-bit @code{int}s. The n64 ABI
-uses 64-bit @code{long}s, as does the 64-bit EABI; the others use
-32-bit @code{long}s. Pointers are the same size as @code{long}s,
-or the same size as integer registers, whichever is smaller.
-
-@item -msym32
-@itemx -mno-sym32
-@opindex msym32
-@opindex mno-sym32
-Assume (do not assume) that all symbols have 32-bit values, regardless
-of the selected ABI@. This option is useful in combination with
-@option{-mabi=64} and @option{-mno-abicalls} because it allows GCC
-to generate shorter and faster references to symbolic addresses.
-
-@item -G @var{num}
-@opindex G
-Put definitions of externally-visible data in a small data section
-if that data is no bigger than @var{num} bytes. GCC can then generate
-more efficient accesses to the data; see @option{-mgpopt} for details.
-
-The default @option{-G} option depends on the configuration.
-
-@item -mlocal-sdata
-@itemx -mno-local-sdata
-@opindex mlocal-sdata
-@opindex mno-local-sdata
-Extend (do not extend) the @option{-G} behavior to local data too,
-such as to static variables in C@. @option{-mlocal-sdata} is the
-default for all configurations.
-
-If the linker complains that an application is using too much small data,
-you might want to try rebuilding the less performance-critical parts with
-@option{-mno-local-sdata}. You might also want to build large
-libraries with @option{-mno-local-sdata}, so that the libraries leave
-more room for the main program.
-
-@item -mextern-sdata
-@itemx -mno-extern-sdata
-@opindex mextern-sdata
-@opindex mno-extern-sdata
-Assume (do not assume) that externally-defined data is in
-a small data section if the size of that data is within the @option{-G} limit.
-@option{-mextern-sdata} is the default for all configurations.
-
-If you compile a module @var{Mod} with @option{-mextern-sdata} @option{-G
-@var{num}} @option{-mgpopt}, and @var{Mod} references a variable @var{Var}
-that is no bigger than @var{num} bytes, you must make sure that @var{Var}
-is placed in a small data section. If @var{Var} is defined by another
-module, you must either compile that module with a high-enough
-@option{-G} setting or attach a @code{section} attribute to @var{Var}'s
-definition. If @var{Var} is common, you must link the application
-with a high-enough @option{-G} setting.
-
-The easiest way of satisfying these restrictions is to compile
-and link every module with the same @option{-G} option. However,
-you may wish to build a library that supports several different
-small data limits. You can do this by compiling the library with
-the highest supported @option{-G} setting and additionally using
-@option{-mno-extern-sdata} to stop the library from making assumptions
-about externally-defined data.
-
-@item -mgpopt
-@itemx -mno-gpopt
-@opindex mgpopt
-@opindex mno-gpopt
-Use (do not use) GP-relative accesses for symbols that are known to be
-in a small data section; see @option{-G}, @option{-mlocal-sdata} and
-@option{-mextern-sdata}. @option{-mgpopt} is the default for all
-configurations.
-
-@option{-mno-gpopt} is useful for cases where the @code{$gp} register
-might not hold the value of @code{_gp}. For example, if the code is
-part of a library that might be used in a boot monitor, programs that
-call boot monitor routines pass an unknown value in @code{$gp}.
-(In such situations, the boot monitor itself is usually compiled
-with @option{-G0}.)
-
-@option{-mno-gpopt} implies @option{-mno-local-sdata} and
-@option{-mno-extern-sdata}.
-
-@item -membedded-data
-@itemx -mno-embedded-data
-@opindex membedded-data
-@opindex mno-embedded-data
-Allocate variables to the read-only data section first if possible, then
-next in the small data section if possible, otherwise in data. This gives
-slightly slower code than the default, but reduces the amount of RAM required
-when executing, and thus may be preferred for some embedded systems.
-
-@item -muninit-const-in-rodata
-@itemx -mno-uninit-const-in-rodata
-@opindex muninit-const-in-rodata
-@opindex mno-uninit-const-in-rodata
-Put uninitialized @code{const} variables in the read-only data section.
-This option is only meaningful in conjunction with @option{-membedded-data}.
-
-@item -mcode-readable=@var{setting}
-@opindex mcode-readable
-Specify whether GCC may generate code that reads from executable sections.
-There are three possible settings:
-
-@table @gcctabopt
-@item -mcode-readable=yes
-Instructions may freely access executable sections. This is the
-default setting.
-
-@item -mcode-readable=pcrel
-MIPS16 PC-relative load instructions can access executable sections,
-but other instructions must not do so. This option is useful on 4KSc
-and 4KSd processors when the code TLBs have the Read Inhibit bit set.
-It is also useful on processors that can be configured to have a dual
-instruction/data SRAM interface and that, like the M4K, automatically
-redirect PC-relative loads to the instruction RAM.
-
-@item -mcode-readable=no
-Instructions must not access executable sections. This option can be
-useful on targets that are configured to have a dual instruction/data
-SRAM interface but that (unlike the M4K) do not automatically redirect
-PC-relative loads to the instruction RAM.
-@end table
-
-@item -msplit-addresses
-@itemx -mno-split-addresses
-@opindex msplit-addresses
-@opindex mno-split-addresses
-Enable (disable) use of the @code{%hi()} and @code{%lo()} assembler
-relocation operators. This option has been superseded by
-@option{-mexplicit-relocs} but is retained for backwards compatibility.
-
-@item -mexplicit-relocs
-@itemx -mno-explicit-relocs
-@opindex mexplicit-relocs
-@opindex mno-explicit-relocs
-Use (do not use) assembler relocation operators when dealing with symbolic
-addresses. The alternative, selected by @option{-mno-explicit-relocs},
-is to use assembler macros instead.
-
-@option{-mexplicit-relocs} is the default if GCC was configured
-to use an assembler that supports relocation operators.
-
-@item -mcheck-zero-division
-@itemx -mno-check-zero-division
-@opindex mcheck-zero-division
-@opindex mno-check-zero-division
-Trap (do not trap) on integer division by zero.
-
-The default is @option{-mcheck-zero-division}.
-
-@item -mdivide-traps
-@itemx -mdivide-breaks
-@opindex mdivide-traps
-@opindex mdivide-breaks
-MIPS systems check for division by zero by generating either a
-conditional trap or a break instruction. Using traps results in
-smaller code, but is only supported on MIPS II and later. Also, some
-versions of the Linux kernel have a bug that prevents trap from
-generating the proper signal (@code{SIGFPE}). Use @option{-mdivide-traps} to
-allow conditional traps on architectures that support them and
-@option{-mdivide-breaks} to force the use of breaks.
-
-The default is usually @option{-mdivide-traps}, but this can be
-overridden at configure time using @option{--with-divide=breaks}.
-Divide-by-zero checks can be completely disabled using
-@option{-mno-check-zero-division}.
-
-@item -mload-store-pairs
-@itemx -mno-load-store-pairs
-@opindex mload-store-pairs
-@opindex mno-load-store-pairs
-Enable (disable) an optimization that pairs consecutive load or store
-instructions to enable load/store bonding. This option is enabled by
-default but only takes effect when the selected architecture is known
-to support bonding.
-
-@item -munaligned-access
-@itemx -mno-unaligned-access
-@opindex munaligned-access
-@opindex mno-unaligned-access
-Enable (disable) direct unaligned access for MIPS Release 6.
-MIPSr6 requires load/store unaligned-access support,
-by hardware or trap&emulate.
-So @option{-mno-unaligned-access} may be needed by kernel.
-
-@item -mmemcpy
-@itemx -mno-memcpy
-@opindex mmemcpy
-@opindex mno-memcpy
-Force (do not force) the use of @code{memcpy} for non-trivial block
-moves. The default is @option{-mno-memcpy}, which allows GCC to inline
-most constant-sized copies.
-
-@item -mlong-calls
-@itemx -mno-long-calls
-@opindex mlong-calls
-@opindex mno-long-calls
-Disable (do not disable) use of the @code{jal} instruction. Calling
-functions using @code{jal} is more efficient but requires the caller
-and callee to be in the same 256 megabyte segment.
-
-This option has no effect on abicalls code. The default is
-@option{-mno-long-calls}.
-
-@item -mmad
-@itemx -mno-mad
-@opindex mmad
-@opindex mno-mad
-Enable (disable) use of the @code{mad}, @code{madu} and @code{mul}
-instructions, as provided by the R4650 ISA@.
-
-@item -mimadd
-@itemx -mno-imadd
-@opindex mimadd
-@opindex mno-imadd
-Enable (disable) use of the @code{madd} and @code{msub} integer
-instructions. The default is @option{-mimadd} on architectures
-that support @code{madd} and @code{msub} except for the 74k
-architecture where it was found to generate slower code.
-
-@item -mfused-madd
-@itemx -mno-fused-madd
-@opindex mfused-madd
-@opindex mno-fused-madd
-Enable (disable) use of the floating-point multiply-accumulate
-instructions, when they are available. The default is
-@option{-mfused-madd}.
-
-On the R8000 CPU when multiply-accumulate instructions are used,
-the intermediate product is calculated to infinite precision
-and is not subject to the FCSR Flush to Zero bit. This may be
-undesirable in some circumstances. On other processors the result
-is numerically identical to the equivalent computation using
-separate multiply, add, subtract and negate instructions.
-
-@item -nocpp
-@opindex nocpp
-Tell the MIPS assembler to not run its preprocessor over user
-assembler files (with a @samp{.s} suffix) when assembling them.
-
-@item -mfix-24k
-@itemx -mno-fix-24k
-@opindex mfix-24k
-@opindex mno-fix-24k
-Work around the 24K E48 (lost data on stores during refill) errata.
-The workarounds are implemented by the assembler rather than by GCC@.
-
-@item -mfix-r4000
-@itemx -mno-fix-r4000
-@opindex mfix-r4000
-@opindex mno-fix-r4000
-Work around certain R4000 CPU errata:
-@itemize @minus
-@item
-A double-word or a variable shift may give an incorrect result if executed
-immediately after starting an integer division.
-@item
-A double-word or a variable shift may give an incorrect result if executed
-while an integer multiplication is in progress.
-@item
-An integer division may give an incorrect result if started in a delay slot
-of a taken branch or a jump.
-@end itemize
-
-@item -mfix-r4400
-@itemx -mno-fix-r4400
-@opindex mfix-r4400
-@opindex mno-fix-r4400
-Work around certain R4400 CPU errata:
-@itemize @minus
-@item
-A double-word or a variable shift may give an incorrect result if executed
-immediately after starting an integer division.
-@end itemize
-
-@item -mfix-r10000
-@itemx -mno-fix-r10000
-@opindex mfix-r10000
-@opindex mno-fix-r10000
-Work around certain R10000 errata:
-@itemize @minus
-@item
-@code{ll}/@code{sc} sequences may not behave atomically on revisions
-prior to 3.0. They may deadlock on revisions 2.6 and earlier.
-@end itemize
-
-This option can only be used if the target architecture supports
-branch-likely instructions. @option{-mfix-r10000} is the default when
-@option{-march=r10000} is used; @option{-mno-fix-r10000} is the default
-otherwise.
-
-@item -mfix-r5900
-@itemx -mno-fix-r5900
-@opindex mfix-r5900
-Do not attempt to schedule the preceding instruction into the delay slot
-of a branch instruction placed at the end of a short loop of six
-instructions or fewer and always schedule a @code{nop} instruction there
-instead. The short loop bug under certain conditions causes loops to
-execute only once or twice, due to a hardware bug in the R5900 chip. The
-workaround is implemented by the assembler rather than by GCC@.
-
-@item -mfix-rm7000
-@itemx -mno-fix-rm7000
-@opindex mfix-rm7000
-Work around the RM7000 @code{dmult}/@code{dmultu} errata. The
-workarounds are implemented by the assembler rather than by GCC@.
-
-@item -mfix-vr4120
-@itemx -mno-fix-vr4120
-@opindex mfix-vr4120
-Work around certain VR4120 errata:
-@itemize @minus
-@item
-@code{dmultu} does not always produce the correct result.
-@item
-@code{div} and @code{ddiv} do not always produce the correct result if one
-of the operands is negative.
-@end itemize
-The workarounds for the division errata rely on special functions in
-@file{libgcc.a}. At present, these functions are only provided by
-the @code{mips64vr*-elf} configurations.
-
-Other VR4120 errata require a NOP to be inserted between certain pairs of
-instructions. These errata are handled by the assembler, not by GCC itself.
-
-@item -mfix-vr4130
-@opindex mfix-vr4130
-Work around the VR4130 @code{mflo}/@code{mfhi} errata. The
-workarounds are implemented by the assembler rather than by GCC,
-although GCC avoids using @code{mflo} and @code{mfhi} if the
-VR4130 @code{macc}, @code{macchi}, @code{dmacc} and @code{dmacchi}
-instructions are available instead.
-
-@item -mfix-sb1
-@itemx -mno-fix-sb1
-@opindex mfix-sb1
-Work around certain SB-1 CPU core errata.
-(This flag currently works around the SB-1 revision 2
-``F1'' and ``F2'' floating-point errata.)
-
-@item -mr10k-cache-barrier=@var{setting}
-@opindex mr10k-cache-barrier
-Specify whether GCC should insert cache barriers to avoid the
-side effects of speculation on R10K processors.
-
-In common with many processors, the R10K tries to predict the outcome
-of a conditional branch and speculatively executes instructions from
-the ``taken'' branch. It later aborts these instructions if the
-predicted outcome is wrong. However, on the R10K, even aborted
-instructions can have side effects.
-
-This problem only affects kernel stores and, depending on the system,
-kernel loads. As an example, a speculatively-executed store may load
-the target memory into cache and mark the cache line as dirty, even if
-the store itself is later aborted. If a DMA operation writes to the
-same area of memory before the ``dirty'' line is flushed, the cached
-data overwrites the DMA-ed data. See the R10K processor manual
-for a full description, including other potential problems.
-
-One workaround is to insert cache barrier instructions before every memory
-access that might be speculatively executed and that might have side
-effects even if aborted. @option{-mr10k-cache-barrier=@var{setting}}
-controls GCC's implementation of this workaround. It assumes that
-aborted accesses to any byte in the following regions does not have
-side effects:
-
-@enumerate
-@item
-the memory occupied by the current function's stack frame;
-
-@item
-the memory occupied by an incoming stack argument;
-
-@item
-the memory occupied by an object with a link-time-constant address.
-@end enumerate
-
-It is the kernel's responsibility to ensure that speculative
-accesses to these regions are indeed safe.
-
-If the input program contains a function declaration such as:
-
-@smallexample
-void foo (void);
-@end smallexample
-
-then the implementation of @code{foo} must allow @code{j foo} and
-@code{jal foo} to be executed speculatively. GCC honors this
-restriction for functions it compiles itself. It expects non-GCC
-functions (such as hand-written assembly code) to do the same.
-
-The option has three forms:
-
-@table @gcctabopt
-@item -mr10k-cache-barrier=load-store
-Insert a cache barrier before a load or store that might be
-speculatively executed and that might have side effects even
-if aborted.
-
-@item -mr10k-cache-barrier=store
-Insert a cache barrier before a store that might be speculatively
-executed and that might have side effects even if aborted.
-
-@item -mr10k-cache-barrier=none
-Disable the insertion of cache barriers. This is the default setting.
-@end table
-
-@item -mflush-func=@var{func}
-@itemx -mno-flush-func
-@opindex mflush-func
-Specifies the function to call to flush the I and D caches, or to not
-call any such function. If called, the function must take the same
-arguments as the common @code{_flush_func}, that is, the address of the
-memory range for which the cache is being flushed, the size of the
-memory range, and the number 3 (to flush both caches). The default
-depends on the target GCC was configured for, but commonly is either
-@code{_flush_func} or @code{__cpu_flush}.
-
-@item mbranch-cost=@var{num}
-@opindex mbranch-cost
-Set the cost of branches to roughly @var{num} ``simple'' instructions.
-This cost is only a heuristic and is not guaranteed to produce
-consistent results across releases. A zero cost redundantly selects
-the default, which is based on the @option{-mtune} setting.
-
-@item -mbranch-likely
-@itemx -mno-branch-likely
-@opindex mbranch-likely
-@opindex mno-branch-likely
-Enable or disable use of Branch Likely instructions, regardless of the
-default for the selected architecture. By default, Branch Likely
-instructions may be generated if they are supported by the selected
-architecture. An exception is for the MIPS32 and MIPS64 architectures
-and processors that implement those architectures; for those, Branch
-Likely instructions are not be generated by default because the MIPS32
-and MIPS64 architectures specifically deprecate their use.
-
-@item -mcompact-branches=never
-@itemx -mcompact-branches=optimal
-@itemx -mcompact-branches=always
-@opindex mcompact-branches=never
-@opindex mcompact-branches=optimal
-@opindex mcompact-branches=always
-These options control which form of branches will be generated. The
-default is @option{-mcompact-branches=optimal}.
-
-The @option{-mcompact-branches=never} option ensures that compact branch
-instructions will never be generated.
-
-The @option{-mcompact-branches=always} option ensures that a compact
-branch instruction will be generated if available for MIPS Release 6 onwards.
-If a compact branch instruction is not available (or pre-R6),
-a delay slot form of the branch will be used instead.
-
-If it is used for MIPS16/microMIPS targets, it will be just ignored now.
-The behaviour for MIPS16/microMIPS may change in future,
-since they do have some compact branch instructions.
-
-The @option{-mcompact-branches=optimal} option will cause a delay slot
-branch to be used if one is available in the current ISA and the delay
-slot is successfully filled. If the delay slot is not filled, a compact
-branch will be chosen if one is available.
-
-@item -mfp-exceptions
-@itemx -mno-fp-exceptions
-@opindex mfp-exceptions
-Specifies whether FP exceptions are enabled. This affects how
-FP instructions are scheduled for some processors.
-The default is that FP exceptions are
-enabled.
-
-For instance, on the SB-1, if FP exceptions are disabled, and we are emitting
-64-bit code, then we can use both FP pipes. Otherwise, we can only use one
-FP pipe.
-
-@item -mvr4130-align
-@itemx -mno-vr4130-align
-@opindex mvr4130-align
-The VR4130 pipeline is two-way superscalar, but can only issue two
-instructions together if the first one is 8-byte aligned. When this
-option is enabled, GCC aligns pairs of instructions that it
-thinks should execute in parallel.
-
-This option only has an effect when optimizing for the VR4130.
-It normally makes code faster, but at the expense of making it bigger.
-It is enabled by default at optimization level @option{-O3}.
-
-@item -msynci
-@itemx -mno-synci
-@opindex msynci
-Enable (disable) generation of @code{synci} instructions on
-architectures that support it. The @code{synci} instructions (if
-enabled) are generated when @code{__builtin___clear_cache} is
-compiled.
-
-This option defaults to @option{-mno-synci}, but the default can be
-overridden by configuring GCC with @option{--with-synci}.
-
-When compiling code for single processor systems, it is generally safe
-to use @code{synci}. However, on many multi-core (SMP) systems, it
-does not invalidate the instruction caches on all cores and may lead
-to undefined behavior.
-
-@item -mrelax-pic-calls
-@itemx -mno-relax-pic-calls
-@opindex mrelax-pic-calls
-Try to turn PIC calls that are normally dispatched via register
-@code{$25} into direct calls. This is only possible if the linker can
-resolve the destination at link time and if the destination is within
-range for a direct call.
-
-@option{-mrelax-pic-calls} is the default if GCC was configured to use
-an assembler and a linker that support the @code{.reloc} assembly
-directive and @option{-mexplicit-relocs} is in effect. With
-@option{-mno-explicit-relocs}, this optimization can be performed by the
-assembler and the linker alone without help from the compiler.
-
-@item -mmcount-ra-address
-@itemx -mno-mcount-ra-address
-@opindex mmcount-ra-address
-@opindex mno-mcount-ra-address
-Emit (do not emit) code that allows @code{_mcount} to modify the
-calling function's return address. When enabled, this option extends
-the usual @code{_mcount} interface with a new @var{ra-address}
-parameter, which has type @code{intptr_t *} and is passed in register
-@code{$12}. @code{_mcount} can then modify the return address by
-doing both of the following:
-@itemize
-@item
-Returning the new address in register @code{$31}.
-@item
-Storing the new address in @code{*@var{ra-address}},
-if @var{ra-address} is nonnull.
-@end itemize
-
-The default is @option{-mno-mcount-ra-address}.
-
-@item -mframe-header-opt
-@itemx -mno-frame-header-opt
-@opindex mframe-header-opt
-Enable (disable) frame header optimization in the o32 ABI. When using the
-o32 ABI, calling functions will allocate 16 bytes on the stack for the called
-function to write out register arguments. When enabled, this optimization
-will suppress the allocation of the frame header if it can be determined that
-it is unused.
-
-This optimization is off by default at all optimization levels.
-
-@item -mlxc1-sxc1
-@itemx -mno-lxc1-sxc1
-@opindex mlxc1-sxc1
-When applicable, enable (disable) the generation of @code{lwxc1},
-@code{swxc1}, @code{ldxc1}, @code{sdxc1} instructions. Enabled by default.
-
-@item -mmadd4
-@itemx -mno-madd4
-@opindex mmadd4
-When applicable, enable (disable) the generation of 4-operand @code{madd.s},
-@code{madd.d} and related instructions. Enabled by default.
-
-@end table
-
-@node MMIX Options
-@subsection MMIX Options
-@cindex MMIX Options
-
-These options are defined for the MMIX:
-
-@table @gcctabopt
-@item -mlibfuncs
-@itemx -mno-libfuncs
-@opindex mlibfuncs
-@opindex mno-libfuncs
-Specify that intrinsic library functions are being compiled, passing all
-values in registers, no matter the size.
-
-@item -mepsilon
-@itemx -mno-epsilon
-@opindex mepsilon
-@opindex mno-epsilon
-Generate floating-point comparison instructions that compare with respect
-to the @code{rE} epsilon register.
-
-@item -mabi=mmixware
-@itemx -mabi=gnu
-@opindex mabi=mmixware
-@opindex mabi=gnu
-Generate code that passes function parameters and return values that (in
-the called function) are seen as registers @code{$0} and up, as opposed to
-the GNU ABI which uses global registers @code{$231} and up.
-
-@item -mzero-extend
-@itemx -mno-zero-extend
-@opindex mzero-extend
-@opindex mno-zero-extend
-When reading data from memory in sizes shorter than 64 bits, use (do not
-use) zero-extending load instructions by default, rather than
-sign-extending ones.
-
-@item -mknuthdiv
-@itemx -mno-knuthdiv
-@opindex mknuthdiv
-@opindex mno-knuthdiv
-Make the result of a division yielding a remainder have the same sign as
-the divisor. With the default, @option{-mno-knuthdiv}, the sign of the
-remainder follows the sign of the dividend. Both methods are
-arithmetically valid, the latter being almost exclusively used.
-
-@item -mtoplevel-symbols
-@itemx -mno-toplevel-symbols
-@opindex mtoplevel-symbols
-@opindex mno-toplevel-symbols
-Prepend (do not prepend) a @samp{:} to all global symbols, so the assembly
-code can be used with the @code{PREFIX} assembly directive.
-
-@item -melf
-@opindex melf
-Generate an executable in the ELF format, rather than the default
-@samp{mmo} format used by the @command{mmix} simulator.
-
-@item -mbranch-predict
-@itemx -mno-branch-predict
-@opindex mbranch-predict
-@opindex mno-branch-predict
-Use (do not use) the probable-branch instructions, when static branch
-prediction indicates a probable branch.
-
-@item -mbase-addresses
-@itemx -mno-base-addresses
-@opindex mbase-addresses
-@opindex mno-base-addresses
-Generate (do not generate) code that uses @emph{base addresses}. Using a
-base address automatically generates a request (handled by the assembler
-and the linker) for a constant to be set up in a global register. The
-register is used for one or more base address requests within the range 0
-to 255 from the value held in the register. The generally leads to short
-and fast code, but the number of different data items that can be
-addressed is limited. This means that a program that uses lots of static
-data may require @option{-mno-base-addresses}.
-
-@item -msingle-exit
-@itemx -mno-single-exit
-@opindex msingle-exit
-@opindex mno-single-exit
-Force (do not force) generated code to have a single exit point in each
-function.
-@end table
-
-@node MN10300 Options
-@subsection MN10300 Options
-@cindex MN10300 options
-
-These @option{-m} options are defined for Matsushita MN10300 architectures:
-
-@table @gcctabopt
-@item -mmult-bug
-@opindex mmult-bug
-Generate code to avoid bugs in the multiply instructions for the MN10300
-processors. This is the default.
-
-@item -mno-mult-bug
-@opindex mno-mult-bug
-Do not generate code to avoid bugs in the multiply instructions for the
-MN10300 processors.
-
-@item -mam33
-@opindex mam33
-Generate code using features specific to the AM33 processor.
-
-@item -mno-am33
-@opindex mno-am33
-Do not generate code using features specific to the AM33 processor. This
-is the default.
-
-@item -mam33-2
-@opindex mam33-2
-Generate code using features specific to the AM33/2.0 processor.
-
-@item -mam34
-@opindex mam34
-Generate code using features specific to the AM34 processor.
-
-@item -mtune=@var{cpu-type}
-@opindex mtune
-Use the timing characteristics of the indicated CPU type when
-scheduling instructions. This does not change the targeted processor
-type. The CPU type must be one of @samp{mn10300}, @samp{am33},
-@samp{am33-2} or @samp{am34}.
-
-@item -mreturn-pointer-on-d0
-@opindex mreturn-pointer-on-d0
-When generating a function that returns a pointer, return the pointer
-in both @code{a0} and @code{d0}. Otherwise, the pointer is returned
-only in @code{a0}, and attempts to call such functions without a prototype
-result in errors. Note that this option is on by default; use
-@option{-mno-return-pointer-on-d0} to disable it.
-
-@item -mno-crt0
-@opindex mno-crt0
-Do not link in the C run-time initialization object file.
-
-@item -mrelax
-@opindex mrelax
-Indicate to the linker that it should perform a relaxation optimization pass
-to shorten branches, calls and absolute memory addresses. This option only
-has an effect when used on the command line for the final link step.
-
-This option makes symbolic debugging impossible.
-
-@item -mliw
-@opindex mliw
-Allow the compiler to generate @emph{Long Instruction Word}
-instructions if the target is the @samp{AM33} or later. This is the
-default. This option defines the preprocessor macro @code{__LIW__}.
-
-@item -mno-liw
-@opindex mno-liw
-Do not allow the compiler to generate @emph{Long Instruction Word}
-instructions. This option defines the preprocessor macro
-@code{__NO_LIW__}.
-
-@item -msetlb
-@opindex msetlb
-Allow the compiler to generate the @emph{SETLB} and @emph{Lcc}
-instructions if the target is the @samp{AM33} or later. This is the
-default. This option defines the preprocessor macro @code{__SETLB__}.
-
-@item -mno-setlb
-@opindex mno-setlb
-Do not allow the compiler to generate @emph{SETLB} or @emph{Lcc}
-instructions. This option defines the preprocessor macro
-@code{__NO_SETLB__}.
-
-@end table
-
-@node Moxie Options
-@subsection Moxie Options
-@cindex Moxie Options
-
-@table @gcctabopt
-
-@item -meb
-@opindex meb
-Generate big-endian code. This is the default for @samp{moxie-*-*}
-configurations.
-
-@item -mel
-@opindex mel
-Generate little-endian code.
-
-@item -mmul.x
-@opindex mmul.x
-Generate mul.x and umul.x instructions. This is the default for
-@samp{moxiebox-*-*} configurations.
-
-@item -mno-crt0
-@opindex mno-crt0
-Do not link in the C run-time initialization object file.
-
-@end table
-
-@node MSP430 Options
-@subsection MSP430 Options
-@cindex MSP430 Options
-
-These options are defined for the MSP430:
-
-@table @gcctabopt
-
-@item -masm-hex
-@opindex masm-hex
-Force assembly output to always use hex constants. Normally such
-constants are signed decimals, but this option is available for
-testsuite and/or aesthetic purposes.
-
-@item -mmcu=
-@opindex mmcu=
-Select the MCU to target. This is used to create a C preprocessor
-symbol based upon the MCU name, converted to upper case and pre- and
-post-fixed with @samp{__}. This in turn is used by the
-@file{msp430.h} header file to select an MCU-specific supplementary
-header file.
-
-The option also sets the ISA to use. If the MCU name is one that is
-known to only support the 430 ISA then that is selected, otherwise the
-430X ISA is selected. A generic MCU name of @samp{msp430} can also be
-used to select the 430 ISA. Similarly the generic @samp{msp430x} MCU
-name selects the 430X ISA.
-
-In addition an MCU-specific linker script is added to the linker
-command line. The script's name is the name of the MCU with
-@file{.ld} appended. Thus specifying @option{-mmcu=xxx} on the @command{gcc}
-command line defines the C preprocessor symbol @code{__XXX__} and
-cause the linker to search for a script called @file{xxx.ld}.
-
-The ISA and hardware multiply supported for the different MCUs is hard-coded
-into GCC. However, an external @samp{devices.csv} file can be used to
-extend device support beyond those that have been hard-coded.
-
-GCC searches for the @samp{devices.csv} file using the following methods in the
-given precedence order, where the first method takes precendence over the
-second which takes precedence over the third.
-
-@table @asis
-@item Include path specified with @code{-I} and @code{-L}
-@samp{devices.csv} will be searched for in each of the directories specified by
-include paths and linker library search paths.
-@item Path specified by the environment variable @samp{MSP430_GCC_INCLUDE_DIR}
-Define the value of the global environment variable
-@samp{MSP430_GCC_INCLUDE_DIR}
-to the full path to the directory containing devices.csv, and GCC will search
-this directory for devices.csv. If devices.csv is found, this directory will
-also be registered as an include path, and linker library path. Header files
-and linker scripts in this directory can therefore be used without manually
-specifying @code{-I} and @code{-L} on the command line.
-@item The @samp{msp430-elf@{,bare@}/include/devices} directory
-Finally, GCC will examine @samp{msp430-elf@{,bare@}/include/devices} from the
-toolchain root directory. This directory does not exist in a default
-installation, but if the user has created it and copied @samp{devices.csv}
-there, then the MCU data will be read. As above, this directory will
-also be registered as an include path, and linker library path.
-
-@end table
-If none of the above search methods find @samp{devices.csv}, then the
-hard-coded MCU data is used.
-
-
-@item -mwarn-mcu
-@itemx -mno-warn-mcu
-@opindex mwarn-mcu
-@opindex mno-warn-mcu
-This option enables or disables warnings about conflicts between the
-MCU name specified by the @option{-mmcu} option and the ISA set by the
-@option{-mcpu} option and/or the hardware multiply support set by the
-@option{-mhwmult} option. It also toggles warnings about unrecognized
-MCU names. This option is on by default.
-
-@item -mcpu=
-@opindex mcpu=
-Specifies the ISA to use. Accepted values are @samp{msp430},
-@samp{msp430x} and @samp{msp430xv2}. This option is deprecated. The
-@option{-mmcu=} option should be used to select the ISA.
-
-@item -msim
-@opindex msim
-Link to the simulator runtime libraries and linker script. Overrides
-any scripts that would be selected by the @option{-mmcu=} option.
-
-@item -mlarge
-@opindex mlarge
-Use large-model addressing (20-bit pointers, 20-bit @code{size_t}).
-
-@item -msmall
-@opindex msmall
-Use small-model addressing (16-bit pointers, 16-bit @code{size_t}).
-
-@item -mrelax
-@opindex mrelax
-This option is passed to the assembler and linker, and allows the
-linker to perform certain optimizations that cannot be done until
-the final link.
-
-@item mhwmult=
-@opindex mhwmult=
-Describes the type of hardware multiply supported by the target.
-Accepted values are @samp{none} for no hardware multiply, @samp{16bit}
-for the original 16-bit-only multiply supported by early MCUs.
-@samp{32bit} for the 16/32-bit multiply supported by later MCUs and
-@samp{f5series} for the 16/32-bit multiply supported by F5-series MCUs.
-A value of @samp{auto} can also be given. This tells GCC to deduce
-the hardware multiply support based upon the MCU name provided by the
-@option{-mmcu} option. If no @option{-mmcu} option is specified or if
-the MCU name is not recognized then no hardware multiply support is
-assumed. @code{auto} is the default setting.
-
-Hardware multiplies are normally performed by calling a library
-routine. This saves space in the generated code. When compiling at
-@option{-O3} or higher however the hardware multiplier is invoked
-inline. This makes for bigger, but faster code.
-
-The hardware multiply routines disable interrupts whilst running and
-restore the previous interrupt state when they finish. This makes
-them safe to use inside interrupt handlers as well as in normal code.
-
-@item -minrt
-@opindex minrt
-Enable the use of a minimum runtime environment - no static
-initializers or constructors. This is intended for memory-constrained
-devices. The compiler includes special symbols in some objects
-that tell the linker and runtime which code fragments are required.
-
-@item -mtiny-printf
-@opindex mtiny-printf
-Enable reduced code size @code{printf} and @code{puts} library functions.
-The @samp{tiny} implementations of these functions are not reentrant, so
-must be used with caution in multi-threaded applications.
-
-Support for streams has been removed and the string to be printed will
-always be sent to stdout via the @code{write} syscall. The string is not
-buffered before it is sent to write.
-
-This option requires Newlib Nano IO, so GCC must be configured with
-@samp{--enable-newlib-nano-formatted-io}.
-
-@item -mmax-inline-shift=
-@opindex mmax-inline-shift=
-This option takes an integer between 0 and 64 inclusive, and sets
-the maximum number of inline shift instructions which should be emitted to
-perform a shift operation by a constant amount. When this value needs to be
-exceeded, an mspabi helper function is used instead. The default value is 4.
-
-This only affects cases where a shift by multiple positions cannot be
-completed with a single instruction (e.g. all shifts >1 on the 430 ISA).
-
-Shifts of a 32-bit value are at least twice as costly, so the value passed for
-this option is divided by 2 and the resulting value used instead.
-
-@item -mcode-region=
-@itemx -mdata-region=
-@opindex mcode-region
-@opindex mdata-region
-These options tell the compiler where to place functions and data that
-do not have one of the @code{lower}, @code{upper}, @code{either} or
-@code{section} attributes. Possible values are @code{lower},
-@code{upper}, @code{either} or @code{any}. The first three behave
-like the corresponding attribute. The fourth possible value -
-@code{any} - is the default. It leaves placement entirely up to the
-linker script and how it assigns the standard sections
-(@code{.text}, @code{.data}, etc) to the memory regions.
-
-@item -msilicon-errata=
-@opindex msilicon-errata
-This option passes on a request to assembler to enable the fixes for
-the named silicon errata.
-
-@item -msilicon-errata-warn=
-@opindex msilicon-errata-warn
-This option passes on a request to the assembler to enable warning
-messages when a silicon errata might need to be applied.
-
-@item -mwarn-devices-csv
-@itemx -mno-warn-devices-csv
-@opindex mwarn-devices-csv
-@opindex mno-warn-devices-csv
-Warn if @samp{devices.csv} is not found or there are problem parsing it
-(default: on).
-
-@end table
-
-@node NDS32 Options
-@subsection NDS32 Options
-@cindex NDS32 Options
-
-These options are defined for NDS32 implementations:
-
-@table @gcctabopt
-
-@item -mbig-endian
-@opindex mbig-endian
-Generate code in big-endian mode.
-
-@item -mlittle-endian
-@opindex mlittle-endian
-Generate code in little-endian mode.
-
-@item -mreduced-regs
-@opindex mreduced-regs
-Use reduced-set registers for register allocation.
-
-@item -mfull-regs
-@opindex mfull-regs
-Use full-set registers for register allocation.
-
-@item -mcmov
-@opindex mcmov
-Generate conditional move instructions.
-
-@item -mno-cmov
-@opindex mno-cmov
-Do not generate conditional move instructions.
-
-@item -mext-perf
-@opindex mext-perf
-Generate performance extension instructions.
-
-@item -mno-ext-perf
-@opindex mno-ext-perf
-Do not generate performance extension instructions.
-
-@item -mext-perf2
-@opindex mext-perf2
-Generate performance extension 2 instructions.
-
-@item -mno-ext-perf2
-@opindex mno-ext-perf2
-Do not generate performance extension 2 instructions.
-
-@item -mext-string
-@opindex mext-string
-Generate string extension instructions.
-
-@item -mno-ext-string
-@opindex mno-ext-string
-Do not generate string extension instructions.
-
-@item -mv3push
-@opindex mv3push
-Generate v3 push25/pop25 instructions.
-
-@item -mno-v3push
-@opindex mno-v3push
-Do not generate v3 push25/pop25 instructions.
-
-@item -m16-bit
-@opindex m16-bit
-Generate 16-bit instructions.
-
-@item -mno-16-bit
-@opindex mno-16-bit
-Do not generate 16-bit instructions.
-
-@item -misr-vector-size=@var{num}
-@opindex misr-vector-size
-Specify the size of each interrupt vector, which must be 4 or 16.
-
-@item -mcache-block-size=@var{num}
-@opindex mcache-block-size
-Specify the size of each cache block,
-which must be a power of 2 between 4 and 512.
-
-@item -march=@var{arch}
-@opindex march
-Specify the name of the target architecture.
-
-@item -mcmodel=@var{code-model}
-@opindex mcmodel
-Set the code model to one of
-@table @asis
-@item @samp{small}
-All the data and read-only data segments must be within 512KB addressing space.
-The text segment must be within 16MB addressing space.
-@item @samp{medium}
-The data segment must be within 512KB while the read-only data segment can be
-within 4GB addressing space. The text segment should be still within 16MB
-addressing space.
-@item @samp{large}
-All the text and data segments can be within 4GB addressing space.
-@end table
-
-@item -mctor-dtor
-@opindex mctor-dtor
-Enable constructor/destructor feature.
-
-@item -mrelax
-@opindex mrelax
-Guide linker to relax instructions.
-
-@end table
-
-@node Nios II Options
-@subsection Nios II Options
-@cindex Nios II options
-@cindex Altera Nios II options
-
-These are the options defined for the Altera Nios II processor.
-
-@table @gcctabopt
-
-@item -G @var{num}
-@opindex G
-@cindex smaller data references
-Put global and static objects less than or equal to @var{num} bytes
-into the small data or BSS sections instead of the normal data or BSS
-sections. The default value of @var{num} is 8.
-
-@item -mgpopt=@var{option}
-@itemx -mgpopt
-@itemx -mno-gpopt
-@opindex mgpopt
-@opindex mno-gpopt
-Generate (do not generate) GP-relative accesses. The following
-@var{option} names are recognized:
-
-@table @samp
-
-@item none
-Do not generate GP-relative accesses.
-
-@item local
-Generate GP-relative accesses for small data objects that are not
-external, weak, or uninitialized common symbols.
-Also use GP-relative addressing for objects that
-have been explicitly placed in a small data section via a @code{section}
-attribute.
-
-@item global
-As for @samp{local}, but also generate GP-relative accesses for
-small data objects that are external, weak, or common. If you use this option,
-you must ensure that all parts of your program (including libraries) are
-compiled with the same @option{-G} setting.
-
-@item data
-Generate GP-relative accesses for all data objects in the program. If you
-use this option, the entire data and BSS segments
-of your program must fit in 64K of memory and you must use an appropriate
-linker script to allocate them within the addressable range of the
-global pointer.
-
-@item all
-Generate GP-relative addresses for function pointers as well as data
-pointers. If you use this option, the entire text, data, and BSS segments
-of your program must fit in 64K of memory and you must use an appropriate
-linker script to allocate them within the addressable range of the
-global pointer.
-
-@end table
-
-@option{-mgpopt} is equivalent to @option{-mgpopt=local}, and
-@option{-mno-gpopt} is equivalent to @option{-mgpopt=none}.
-
-The default is @option{-mgpopt} except when @option{-fpic} or
-@option{-fPIC} is specified to generate position-independent code.
-Note that the Nios II ABI does not permit GP-relative accesses from
-shared libraries.
-
-You may need to specify @option{-mno-gpopt} explicitly when building
-programs that include large amounts of small data, including large
-GOT data sections. In this case, the 16-bit offset for GP-relative
-addressing may not be large enough to allow access to the entire
-small data section.
-
-@item -mgprel-sec=@var{regexp}
-@opindex mgprel-sec
-This option specifies additional section names that can be accessed via
-GP-relative addressing. It is most useful in conjunction with
-@code{section} attributes on variable declarations
-(@pxref{Common Variable Attributes}) and a custom linker script.
-The @var{regexp} is a POSIX Extended Regular Expression.
-
-This option does not affect the behavior of the @option{-G} option, and
-the specified sections are in addition to the standard @code{.sdata}
-and @code{.sbss} small-data sections that are recognized by @option{-mgpopt}.
-
-@item -mr0rel-sec=@var{regexp}
-@opindex mr0rel-sec
-This option specifies names of sections that can be accessed via a
-16-bit offset from @code{r0}; that is, in the low 32K or high 32K
-of the 32-bit address space. It is most useful in conjunction with
-@code{section} attributes on variable declarations
-(@pxref{Common Variable Attributes}) and a custom linker script.
-The @var{regexp} is a POSIX Extended Regular Expression.
-
-In contrast to the use of GP-relative addressing for small data,
-zero-based addressing is never generated by default and there are no
-conventional section names used in standard linker scripts for sections
-in the low or high areas of memory.
-
-@item -mel
-@itemx -meb
-@opindex mel
-@opindex meb
-Generate little-endian (default) or big-endian (experimental) code,
-respectively.
-
-@item -march=@var{arch}
-@opindex march
-This specifies the name of the target Nios II architecture. GCC uses this
-name to determine what kind of instructions it can emit when generating
-assembly code. Permissible names are: @samp{r1}, @samp{r2}.
-
-The preprocessor macro @code{__nios2_arch__} is available to programs,
-with value 1 or 2, indicating the targeted ISA level.
-
-@item -mbypass-cache
-@itemx -mno-bypass-cache
-@opindex mno-bypass-cache
-@opindex mbypass-cache
-Force all load and store instructions to always bypass cache by
-using I/O variants of the instructions. The default is not to
-bypass the cache.
-
-@item -mno-cache-volatile
-@itemx -mcache-volatile
-@opindex mcache-volatile
-@opindex mno-cache-volatile
-Volatile memory access bypass the cache using the I/O variants of
-the load and store instructions. The default is not to bypass the cache.
-
-@item -mno-fast-sw-div
-@itemx -mfast-sw-div
-@opindex mno-fast-sw-div
-@opindex mfast-sw-div
-Do not use table-based fast divide for small numbers. The default
-is to use the fast divide at @option{-O3} and above.
-
-@item -mno-hw-mul
-@itemx -mhw-mul
-@itemx -mno-hw-mulx
-@itemx -mhw-mulx
-@itemx -mno-hw-div
-@itemx -mhw-div
-@opindex mno-hw-mul
-@opindex mhw-mul
-@opindex mno-hw-mulx
-@opindex mhw-mulx
-@opindex mno-hw-div
-@opindex mhw-div
-Enable or disable emitting @code{mul}, @code{mulx} and @code{div} family of
-instructions by the compiler. The default is to emit @code{mul}
-and not emit @code{div} and @code{mulx}.
-
-@item -mbmx
-@itemx -mno-bmx
-@itemx -mcdx
-@itemx -mno-cdx
-Enable or disable generation of Nios II R2 BMX (bit manipulation) and
-CDX (code density) instructions. Enabling these instructions also
-requires @option{-march=r2}. Since these instructions are optional
-extensions to the R2 architecture, the default is not to emit them.
-
-@item -mcustom-@var{insn}=@var{N}
-@itemx -mno-custom-@var{insn}
-@opindex mcustom-@var{insn}
-@opindex mno-custom-@var{insn}
-Each @option{-mcustom-@var{insn}=@var{N}} option enables use of a
-custom instruction with encoding @var{N} when generating code that uses
-@var{insn}. For example, @option{-mcustom-fadds=253} generates custom
-instruction 253 for single-precision floating-point add operations instead
-of the default behavior of using a library call.
-
-The following values of @var{insn} are supported. Except as otherwise
-noted, floating-point operations are expected to be implemented with
-normal IEEE 754 semantics and correspond directly to the C operators or the
-equivalent GCC built-in functions (@pxref{Other Builtins}).
-
-Single-precision floating point:
-@table @asis
-
-@item @samp{fadds}, @samp{fsubs}, @samp{fdivs}, @samp{fmuls}
-Binary arithmetic operations.
-
-@item @samp{fnegs}
-Unary negation.
-
-@item @samp{fabss}
-Unary absolute value.
-
-@item @samp{fcmpeqs}, @samp{fcmpges}, @samp{fcmpgts}, @samp{fcmples}, @samp{fcmplts}, @samp{fcmpnes}
-Comparison operations.
-
-@item @samp{fmins}, @samp{fmaxs}
-Floating-point minimum and maximum. These instructions are only
-generated if @option{-ffinite-math-only} is specified.
-
-@item @samp{fsqrts}
-Unary square root operation.
-
-@item @samp{fcoss}, @samp{fsins}, @samp{ftans}, @samp{fatans}, @samp{fexps}, @samp{flogs}
-Floating-point trigonometric and exponential functions. These instructions
-are only generated if @option{-funsafe-math-optimizations} is also specified.
-
-@end table
-
-Double-precision floating point:
-@table @asis
-
-@item @samp{faddd}, @samp{fsubd}, @samp{fdivd}, @samp{fmuld}
-Binary arithmetic operations.
-
-@item @samp{fnegd}
-Unary negation.
-
-@item @samp{fabsd}
-Unary absolute value.
-
-@item @samp{fcmpeqd}, @samp{fcmpged}, @samp{fcmpgtd}, @samp{fcmpled}, @samp{fcmpltd}, @samp{fcmpned}
-Comparison operations.
-
-@item @samp{fmind}, @samp{fmaxd}
-Double-precision minimum and maximum. These instructions are only
-generated if @option{-ffinite-math-only} is specified.
-
-@item @samp{fsqrtd}
-Unary square root operation.
-
-@item @samp{fcosd}, @samp{fsind}, @samp{ftand}, @samp{fatand}, @samp{fexpd}, @samp{flogd}
-Double-precision trigonometric and exponential functions. These instructions
-are only generated if @option{-funsafe-math-optimizations} is also specified.
-
-@end table
-
-Conversions:
-@table @asis
-@item @samp{fextsd}
-Conversion from single precision to double precision.
-
-@item @samp{ftruncds}
-Conversion from double precision to single precision.
-
-@item @samp{fixsi}, @samp{fixsu}, @samp{fixdi}, @samp{fixdu}
-Conversion from floating point to signed or unsigned integer types, with
-truncation towards zero.
-
-@item @samp{round}
-Conversion from single-precision floating point to signed integer,
-rounding to the nearest integer and ties away from zero.
-This corresponds to the @code{__builtin_lroundf} function when
-@option{-fno-math-errno} is used.
-
-@item @samp{floatis}, @samp{floatus}, @samp{floatid}, @samp{floatud}
-Conversion from signed or unsigned integer types to floating-point types.
-
-@end table
-
-In addition, all of the following transfer instructions for internal
-registers X and Y must be provided to use any of the double-precision
-floating-point instructions. Custom instructions taking two
-double-precision source operands expect the first operand in the
-64-bit register X. The other operand (or only operand of a unary
-operation) is given to the custom arithmetic instruction with the
-least significant half in source register @var{src1} and the most
-significant half in @var{src2}. A custom instruction that returns a
-double-precision result returns the most significant 32 bits in the
-destination register and the other half in 32-bit register Y.
-GCC automatically generates the necessary code sequences to write
-register X and/or read register Y when double-precision floating-point
-instructions are used.
-
-@table @asis
-
-@item @samp{fwrx}
-Write @var{src1} into the least significant half of X and @var{src2} into
-the most significant half of X.
-
-@item @samp{fwry}
-Write @var{src1} into Y.
-
-@item @samp{frdxhi}, @samp{frdxlo}
-Read the most or least (respectively) significant half of X and store it in
-@var{dest}.
-
-@item @samp{frdy}
-Read the value of Y and store it into @var{dest}.
-@end table
-
-Note that you can gain more local control over generation of Nios II custom
-instructions by using the @code{target("custom-@var{insn}=@var{N}")}
-and @code{target("no-custom-@var{insn}")} function attributes
-(@pxref{Function Attributes})
-or pragmas (@pxref{Function Specific Option Pragmas}).
-
-@item -mcustom-fpu-cfg=@var{name}
-@opindex mcustom-fpu-cfg
-
-This option enables a predefined, named set of custom instruction encodings
-(see @option{-mcustom-@var{insn}} above).
-Currently, the following sets are defined:
-
-@option{-mcustom-fpu-cfg=60-1} is equivalent to:
-@gccoptlist{-mcustom-fmuls=252 @gol
--mcustom-fadds=253 @gol
--mcustom-fsubs=254 @gol
--fsingle-precision-constant}
-
-@option{-mcustom-fpu-cfg=60-2} is equivalent to:
-@gccoptlist{-mcustom-fmuls=252 @gol
--mcustom-fadds=253 @gol
--mcustom-fsubs=254 @gol
--mcustom-fdivs=255 @gol
--fsingle-precision-constant}
-
-@option{-mcustom-fpu-cfg=72-3} is equivalent to:
-@gccoptlist{-mcustom-floatus=243 @gol
--mcustom-fixsi=244 @gol
--mcustom-floatis=245 @gol
--mcustom-fcmpgts=246 @gol
--mcustom-fcmples=249 @gol
--mcustom-fcmpeqs=250 @gol
--mcustom-fcmpnes=251 @gol
--mcustom-fmuls=252 @gol
--mcustom-fadds=253 @gol
--mcustom-fsubs=254 @gol
--mcustom-fdivs=255 @gol
--fsingle-precision-constant}
-
-@option{-mcustom-fpu-cfg=fph2} is equivalent to:
-@gccoptlist{-mcustom-fabss=224 @gol
--mcustom-fnegs=225 @gol
--mcustom-fcmpnes=226 @gol
--mcustom-fcmpeqs=227 @gol
--mcustom-fcmpges=228 @gol
--mcustom-fcmpgts=229 @gol
--mcustom-fcmples=230 @gol
--mcustom-fcmplts=231 @gol
--mcustom-fmaxs=232 @gol
--mcustom-fmins=233 @gol
--mcustom-round=248 @gol
--mcustom-fixsi=249 @gol
--mcustom-floatis=250 @gol
--mcustom-fsqrts=251 @gol
--mcustom-fmuls=252 @gol
--mcustom-fadds=253 @gol
--mcustom-fsubs=254 @gol
--mcustom-fdivs=255 @gol}
-
-Custom instruction assignments given by individual
-@option{-mcustom-@var{insn}=} options override those given by
-@option{-mcustom-fpu-cfg=}, regardless of the
-order of the options on the command line.
-
-Note that you can gain more local control over selection of a FPU
-configuration by using the @code{target("custom-fpu-cfg=@var{name}")}
-function attribute (@pxref{Function Attributes})
-or pragma (@pxref{Function Specific Option Pragmas}).
-
-The name @var{fph2} is an abbreviation for @emph{Nios II Floating Point
-Hardware 2 Component}. Please note that the custom instructions enabled by
-@option{-mcustom-fmins=233} and @option{-mcustom-fmaxs=234} are only generated
-if @option{-ffinite-math-only} is specified. The custom instruction enabled by
-@option{-mcustom-round=248} is only generated if @option{-fno-math-errno} is
-specified. In contrast to the other configurations,
-@option{-fsingle-precision-constant} is not set.
-
-@end table
-
-These additional @samp{-m} options are available for the Altera Nios II
-ELF (bare-metal) target:
-
-@table @gcctabopt
-
-@item -mhal
-@opindex mhal
-Link with HAL BSP. This suppresses linking with the GCC-provided C runtime
-startup and termination code, and is typically used in conjunction with
-@option{-msys-crt0=} to specify the location of the alternate startup code
-provided by the HAL BSP.
-
-@item -msmallc
-@opindex msmallc
-Link with a limited version of the C library, @option{-lsmallc}, rather than
-Newlib.
-
-@item -msys-crt0=@var{startfile}
-@opindex msys-crt0
-@var{startfile} is the file name of the startfile (crt0) to use
-when linking. This option is only useful in conjunction with @option{-mhal}.
-
-@item -msys-lib=@var{systemlib}
-@opindex msys-lib
-@var{systemlib} is the library name of the library that provides
-low-level system calls required by the C library,
-e.g.@: @code{read} and @code{write}.
-This option is typically used to link with a library provided by a HAL BSP.
-
-@end table
-
-@node Nvidia PTX Options
-@subsection Nvidia PTX Options
-@cindex Nvidia PTX options
-@cindex nvptx options
-
-These options are defined for Nvidia PTX:
-
-@table @gcctabopt
-
-@item -m64
-@opindex m64
-Ignored, but preserved for backward compatibility. Only 64-bit ABI is
-supported.
-
-@item -march=@var{architecture-string}
-@opindex march
-Generate code for the specified PTX ISA target architecture
-(e.g.@: @samp{sm_35}). Valid architecture strings are @samp{sm_30},
-@samp{sm_35}, @samp{sm_53}, @samp{sm_70}, @samp{sm_75} and
-@samp{sm_80}.
-The default depends on how the compiler has been configured, see
-@option{--with-arch}.
-
-This option sets the value of the preprocessor macro
-@code{__PTX_SM__}; for instance, for @samp{sm_35}, it has the value
-@samp{350}.
-
-@item -misa=@var{architecture-string}
-@opindex misa
-Alias of @option{-march=}.
-
-@item -march-map=@var{architecture-string}
-@opindex march
-Select the closest available @option{-march=} value that is not more
-capable. For instance, for @option{-march-map=sm_50} select
-@option{-march=sm_35}, and for @option{-march-map=sm_53} select
-@option{-march=sm_53}.
-
-@item -mptx=@var{version-string}
-@opindex mptx
-Generate code for the specified PTX ISA version (e.g.@: @samp{7.0}).
-Valid version strings include @samp{3.1}, @samp{6.0}, @samp{6.3}, and
-@samp{7.0}. The default PTX ISA version is 6.0, unless a higher
-version is required for specified PTX ISA target architecture via
-option @option{-march=}.
-
-This option sets the values of the preprocessor macros
-@code{__PTX_ISA_VERSION_MAJOR__} and @code{__PTX_ISA_VERSION_MINOR__};
-for instance, for @samp{3.1} the macros have the values @samp{3} and
-@samp{1}, respectively.
-
-@item -mmainkernel
-@opindex mmainkernel
-Link in code for a __main kernel. This is for stand-alone instead of
-offloading execution.
-
-@item -moptimize
-@opindex moptimize
-Apply partitioned execution optimizations. This is the default when any
-level of optimization is selected.
-
-@item -msoft-stack
-@opindex msoft-stack
-Generate code that does not use @code{.local} memory
-directly for stack storage. Instead, a per-warp stack pointer is
-maintained explicitly. This enables variable-length stack allocation (with
-variable-length arrays or @code{alloca}), and when global memory is used for
-underlying storage, makes it possible to access automatic variables from other
-threads, or with atomic instructions. This code generation variant is used
-for OpenMP offloading, but the option is exposed on its own for the purpose
-of testing the compiler; to generate code suitable for linking into programs
-using OpenMP offloading, use option @option{-mgomp}.
-
-@item -muniform-simt
-@opindex muniform-simt
-Switch to code generation variant that allows to execute all threads in each
-warp, while maintaining memory state and side effects as if only one thread
-in each warp was active outside of OpenMP SIMD regions. All atomic operations
-and calls to runtime (malloc, free, vprintf) are conditionally executed (iff
-current lane index equals the master lane index), and the register being
-assigned is copied via a shuffle instruction from the master lane. Outside of
-SIMD regions lane 0 is the master; inside, each thread sees itself as the
-master. Shared memory array @code{int __nvptx_uni[]} stores all-zeros or
-all-ones bitmasks for each warp, indicating current mode (0 outside of SIMD
-regions). Each thread can bitwise-and the bitmask at position @code{tid.y}
-with current lane index to compute the master lane index.
-
-@item -mgomp
-@opindex mgomp
-Generate code for use in OpenMP offloading: enables @option{-msoft-stack} and
-@option{-muniform-simt} options, and selects corresponding multilib variant.
-
-@end table
-
-@node OpenRISC Options
-@subsection OpenRISC Options
-@cindex OpenRISC Options
-
-These options are defined for OpenRISC:
-
-@table @gcctabopt
-
-@item -mboard=@var{name}
-@opindex mboard
-Configure a board specific runtime. This will be passed to the linker for
-newlib board library linking. The default is @code{or1ksim}.
-
-@item -mnewlib
-@opindex mnewlib
-This option is ignored; it is for compatibility purposes only. This used to
-select linker and preprocessor options for use with newlib.
-
-@item -msoft-div
-@itemx -mhard-div
-@opindex msoft-div
-@opindex mhard-div
-Select software or hardware divide (@code{l.div}, @code{l.divu}) instructions.
-This default is hardware divide.
-
-@item -msoft-mul
-@itemx -mhard-mul
-@opindex msoft-mul
-@opindex mhard-mul
-Select software or hardware multiply (@code{l.mul}, @code{l.muli}) instructions.
-This default is hardware multiply.
-
-@item -msoft-float
-@itemx -mhard-float
-@opindex msoft-float
-@opindex mhard-float
-Select software or hardware for floating point operations.
-The default is software.
-
-@item -mdouble-float
-@opindex mdouble-float
-When @option{-mhard-float} is selected, enables generation of double-precision
-floating point instructions. By default functions from @file{libgcc} are used
-to perform double-precision floating point operations.
-
-@item -munordered-float
-@opindex munordered-float
-When @option{-mhard-float} is selected, enables generation of unordered
-floating point compare and set flag (@code{lf.sfun*}) instructions. By default
-functions from @file{libgcc} are used to perform unordered floating point
-compare and set flag operations.
-
-@item -mcmov
-@opindex mcmov
-Enable generation of conditional move (@code{l.cmov}) instructions. By
-default the equivalent will be generated using set and branch.
-
-@item -mror
-@opindex mror
-Enable generation of rotate right (@code{l.ror}) instructions. By default
-functions from @file{libgcc} are used to perform rotate right operations.
-
-@item -mrori
-@opindex mrori
-Enable generation of rotate right with immediate (@code{l.rori}) instructions.
-By default functions from @file{libgcc} are used to perform rotate right with
-immediate operations.
-
-@item -msext
-@opindex msext
-Enable generation of sign extension (@code{l.ext*}) instructions. By default
-memory loads are used to perform sign extension.
-
-@item -msfimm
-@opindex msfimm
-Enable generation of compare and set flag with immediate (@code{l.sf*i})
-instructions. By default extra instructions will be generated to store the
-immediate to a register first.
-
-@item -mshftimm
-@opindex mshftimm
-Enable generation of shift with immediate (@code{l.srai}, @code{l.srli},
-@code{l.slli}) instructions. By default extra instructions will be generated
-to store the immediate to a register first.
-
-@item -mcmodel=small
-@opindex mcmodel=small
-Generate OpenRISC code for the small model: The GOT is limited to 64k. This is
-the default model.
-
-@item -mcmodel=large
-@opindex mcmodel=large
-Generate OpenRISC code for the large model: The GOT may grow up to 4G in size.
-
-
-@end table
-
-@node PDP-11 Options
-@subsection PDP-11 Options
-@cindex PDP-11 Options
-
-These options are defined for the PDP-11:
-
-@table @gcctabopt
-@item -mfpu
-@opindex mfpu
-Use hardware FPP floating point. This is the default. (FIS floating
-point on the PDP-11/40 is not supported.) Implies -m45.
-
-@item -msoft-float
-@opindex msoft-float
-Do not use hardware floating point.
-
-@item -mac0
-@opindex mac0
-Return floating-point results in ac0 (fr0 in Unix assembler syntax).
-
-@item -mno-ac0
-@opindex mno-ac0
-Return floating-point results in memory. This is the default.
-
-@item -m40
-@opindex m40
-Generate code for a PDP-11/40. Implies -msoft-float -mno-split.
-
-@item -m45
-@opindex m45
-Generate code for a PDP-11/45. This is the default.
-
-@item -m10
-@opindex m10
-Generate code for a PDP-11/10. Implies -msoft-float -mno-split.
-
-@item -mint16
-@itemx -mno-int32
-@opindex mint16
-@opindex mno-int32
-Use 16-bit @code{int}. This is the default.
-
-@item -mint32
-@itemx -mno-int16
-@opindex mint32
-@opindex mno-int16
-Use 32-bit @code{int}.
-
-@item -msplit
-@opindex msplit
-Target has split instruction and data space. Implies -m45.
-
-@item -munix-asm
-@opindex munix-asm
-Use Unix assembler syntax.
-
-@item -mdec-asm
-@opindex mdec-asm
-Use DEC assembler syntax.
-
-@item -mgnu-asm
-@opindex mgnu-asm
-Use GNU assembler syntax. This is the default.
-
-@item -mlra
-@opindex mlra
-Use the new LRA register allocator. By default, the old ``reload''
-allocator is used.
-@end table
-
-@node picoChip Options
-@subsection picoChip Options
-@cindex picoChip options
-
-These @samp{-m} options are defined for picoChip implementations:
-
-@table @gcctabopt
-
-@item -mae=@var{ae_type}
-@opindex mcpu
-Set the instruction set, register set, and instruction scheduling
-parameters for array element type @var{ae_type}. Supported values
-for @var{ae_type} are @samp{ANY}, @samp{MUL}, and @samp{MAC}.
-
-@option{-mae=ANY} selects a completely generic AE type. Code
-generated with this option runs on any of the other AE types. The
-code is not as efficient as it would be if compiled for a specific
-AE type, and some types of operation (e.g., multiplication) do not
-work properly on all types of AE.
-
-@option{-mae=MUL} selects a MUL AE type. This is the most useful AE type
-for compiled code, and is the default.
-
-@option{-mae=MAC} selects a DSP-style MAC AE. Code compiled with this
-option may suffer from poor performance of byte (char) manipulation,
-since the DSP AE does not provide hardware support for byte load/stores.
-
-@item -msymbol-as-address
-Enable the compiler to directly use a symbol name as an address in a
-load/store instruction, without first loading it into a
-register. Typically, the use of this option generates larger
-programs, which run faster than when the option isn't used. However, the
-results vary from program to program, so it is left as a user option,
-rather than being permanently enabled.
-
-@item -mno-inefficient-warnings
-Disables warnings about the generation of inefficient code. These
-warnings can be generated, for example, when compiling code that
-performs byte-level memory operations on the MAC AE type. The MAC AE has
-no hardware support for byte-level memory operations, so all byte
-load/stores must be synthesized from word load/store operations. This is
-inefficient and a warning is generated to indicate
-that you should rewrite the code to avoid byte operations, or to target
-an AE type that has the necessary hardware support. This option disables
-these warnings.
-
-@end table
-
-@node PowerPC Options
-@subsection PowerPC Options
-@cindex PowerPC options
-
-These are listed under @xref{RS/6000 and PowerPC Options}.
-
-@node PRU Options
-@subsection PRU Options
-@cindex PRU Options
-
-These command-line options are defined for PRU target:
-
-@table @gcctabopt
-@item -minrt
-@opindex minrt
-Link with a minimum runtime environment, with no support for static
-initializers and constructors. Using this option can significantly reduce
-the size of the final ELF binary. Beware that the compiler could still
-generate code with static initializers and constructors. It is up to the
-programmer to ensure that the source program will not use those features.
-
-@item -mmcu=@var{mcu}
-@opindex mmcu
-Specify the PRU MCU variant to use. Check Newlib for the exact list of
-supported MCUs.
-
-@item -mno-relax
-@opindex mno-relax
-Make GCC pass the @option{--no-relax} command-line option to the linker
-instead of the @option{--relax} option.
-
-@item -mloop
-@opindex mloop
-Allow (or do not allow) GCC to use the LOOP instruction.
-
-@item -mabi=@var{variant}
-@opindex mabi
-Specify the ABI variant to output code for. @option{-mabi=ti} selects the
-unmodified TI ABI while @option{-mabi=gnu} selects a GNU variant that copes
-more naturally with certain GCC assumptions. These are the differences:
-
-@table @samp
-@item Function Pointer Size
-TI ABI specifies that function (code) pointers are 16-bit, whereas GNU
-supports only 32-bit data and code pointers.
-
-@item Optional Return Value Pointer
-Function return values larger than 64 bits are passed by using a hidden
-pointer as the first argument of the function. TI ABI, though, mandates that
-the pointer can be NULL in case the caller is not using the returned value.
-GNU always passes and expects a valid return value pointer.
-
-@end table
-
-The current @option{-mabi=ti} implementation simply raises a compile error
-when any of the above code constructs is detected. As a consequence
-the standard C library cannot be built and it is omitted when linking with
-@option{-mabi=ti}.
-
-Relaxation is a GNU feature and for safety reasons is disabled when using
-@option{-mabi=ti}. The TI toolchain does not emit relocations for QBBx
-instructions, so the GNU linker cannot adjust them when shortening adjacent
-LDI32 pseudo instructions.
-
-@end table
-
-@node RISC-V Options
-@subsection RISC-V Options
-@cindex RISC-V Options
-
-These command-line options are defined for RISC-V targets:
-
-@table @gcctabopt
-@item -mbranch-cost=@var{n}
-@opindex mbranch-cost
-Set the cost of branches to roughly @var{n} instructions.
-
-@item -mplt
-@itemx -mno-plt
-@opindex plt
-When generating PIC code, do or don't allow the use of PLTs. Ignored for
-non-PIC. The default is @option{-mplt}.
-
-@item -mabi=@var{ABI-string}
-@opindex mabi
-Specify integer and floating-point calling convention. @var{ABI-string}
-contains two parts: the size of integer types and the registers used for
-floating-point types. For example @samp{-march=rv64ifd -mabi=lp64d} means that
-@samp{long} and pointers are 64-bit (implicitly defining @samp{int} to be
-32-bit), and that floating-point values up to 64 bits wide are passed in F
-registers. Contrast this with @samp{-march=rv64ifd -mabi=lp64f}, which still
-allows the compiler to generate code that uses the F and D extensions but only
-allows floating-point values up to 32 bits long to be passed in registers; or
-@samp{-march=rv64ifd -mabi=lp64}, in which no floating-point arguments will be
-passed in registers.
-
-The default for this argument is system dependent, users who want a specific
-calling convention should specify one explicitly. The valid calling
-conventions are: @samp{ilp32}, @samp{ilp32f}, @samp{ilp32d}, @samp{lp64},
-@samp{lp64f}, and @samp{lp64d}. Some calling conventions are impossible to
-implement on some ISAs: for example, @samp{-march=rv32if -mabi=ilp32d} is
-invalid because the ABI requires 64-bit values be passed in F registers, but F
-registers are only 32 bits wide. There is also the @samp{ilp32e} ABI that can
-only be used with the @samp{rv32e} architecture. This ABI is not well
-specified at present, and is subject to change.
-
-@item -mfdiv
-@itemx -mno-fdiv
-@opindex mfdiv
-Do or don't use hardware floating-point divide and square root instructions.
-This requires the F or D extensions for floating-point registers. The default
-is to use them if the specified architecture has these instructions.
-
-@item -mdiv
-@itemx -mno-div
-@opindex mdiv
-Do or don't use hardware instructions for integer division. This requires the
-M extension. The default is to use them if the specified architecture has
-these instructions.
-
-@item -misa-spec=@var{ISA-spec-string}
-@opindex misa-spec
-Specify the version of the RISC-V Unprivileged (formerly User-Level)
-ISA specification to produce code conforming to. The possibilities
-for @var{ISA-spec-string} are:
-@table @code
-@item 2.2
-Produce code conforming to version 2.2.
-@item 20190608
-Produce code conforming to version 20190608.
-@item 20191213
-Produce code conforming to version 20191213.
-@end table
-The default is @option{-misa-spec=20191213} unless GCC has been configured
-with @option{--with-isa-spec=} specifying a different default version.
-
-@item -march=@var{ISA-string}
-@opindex march
-Generate code for given RISC-V ISA (e.g.@: @samp{rv64im}). ISA strings must be
-lower-case. Examples include @samp{rv64i}, @samp{rv32g}, @samp{rv32e}, and
-@samp{rv32imaf}.
-
-When @option{-march=} is not specified, use the setting from @option{-mcpu}.
-
-If both @option{-march} and @option{-mcpu=} are not specified, the default for
-this argument is system dependent, users who want a specific architecture
-extensions should specify one explicitly.
-
-@item -mcpu=@var{processor-string}
-@opindex mcpu
-Use architecture of and optimize the output for the given processor, specified
-by particular CPU name.
-Permissible values for this option are: @samp{sifive-e20}, @samp{sifive-e21},
-@samp{sifive-e24}, @samp{sifive-e31}, @samp{sifive-e34}, @samp{sifive-e76},
-@samp{sifive-s21}, @samp{sifive-s51}, @samp{sifive-s54}, @samp{sifive-s76},
-@samp{sifive-u54}, and @samp{sifive-u74}.
-
-@item -mtune=@var{processor-string}
-@opindex mtune
-Optimize the output for the given processor, specified by microarchitecture or
-particular CPU name. Permissible values for this option are: @samp{rocket},
-@samp{sifive-3-series}, @samp{sifive-5-series}, @samp{sifive-7-series},
-@samp{thead-c906}, @samp{size}, and all valid options for @option{-mcpu=}.
-
-When @option{-mtune=} is not specified, use the setting from @option{-mcpu},
-the default is @samp{rocket} if both are not specified.
-
-The @samp{size} choice is not intended for use by end-users. This is used
-when @option{-Os} is specified. It overrides the instruction cost info
-provided by @option{-mtune=}, but does not override the pipeline info. This
-helps reduce code size while still giving good performance.
-
-@item -mpreferred-stack-boundary=@var{num}
-@opindex mpreferred-stack-boundary
-Attempt to keep the stack boundary aligned to a 2 raised to @var{num}
-byte boundary. If @option{-mpreferred-stack-boundary} is not specified,
-the default is 4 (16 bytes or 128-bits).
-
-@strong{Warning:} If you use this switch, then you must build all modules with
-the same value, including any libraries. This includes the system libraries
-and startup modules.
-
-@item -msmall-data-limit=@var{n}
-@opindex msmall-data-limit
-Put global and static data smaller than @var{n} bytes into a special section
-(on some targets).
-
-@item -msave-restore
-@itemx -mno-save-restore
-@opindex msave-restore
-Do or don't use smaller but slower prologue and epilogue code that uses
-library function calls. The default is to use fast inline prologues and
-epilogues.
-
-@item -mshorten-memrefs
-@itemx -mno-shorten-memrefs
-@opindex mshorten-memrefs
-Do or do not attempt to make more use of compressed load/store instructions by
-replacing a load/store of 'base register + large offset' with a new load/store
-of 'new base + small offset'. If the new base gets stored in a compressed
-register, then the new load/store can be compressed. Currently targets 32-bit
-integer load/stores only.
-
-@item -mstrict-align
-@itemx -mno-strict-align
-@opindex mstrict-align
-Do not or do generate unaligned memory accesses. The default is set depending
-on whether the processor we are optimizing for supports fast unaligned access
-or not.
-
-@item -mcmodel=medlow
-@opindex mcmodel=medlow
-Generate code for the medium-low code model. The program and its statically
-defined symbols must lie within a single 2 GiB address range and must lie
-between absolute addresses @minus{}2 GiB and +2 GiB. Programs can be
-statically or dynamically linked. This is the default code model.
-
-@item -mcmodel=medany
-@opindex mcmodel=medany
-Generate code for the medium-any code model. The program and its statically
-defined symbols must be within any single 2 GiB address range. Programs can be
-statically or dynamically linked.
-
-The code generated by the medium-any code model is position-independent, but is
-not guaranteed to function correctly when linked into position-independent
-executables or libraries.
-
-@item -mexplicit-relocs
-@itemx -mno-exlicit-relocs
-Use or do not use assembler relocation operators when dealing with symbolic
-addresses. The alternative is to use assembler macros instead, which may
-limit optimization.
-
-@item -mrelax
-@itemx -mno-relax
-@opindex mrelax
-Take advantage of linker relaxations to reduce the number of instructions
-required to materialize symbol addresses. The default is to take advantage of
-linker relaxations.
-
-@item -mriscv-attribute
-@itemx -mno-riscv-attribute
-@opindex mriscv-attribute
-Emit (do not emit) RISC-V attribute to record extra information into ELF
-objects. This feature requires at least binutils 2.32.
-
-@item -mcsr-check
-@itemx -mno-csr-check
-@opindex mcsr-check
-Enables or disables the CSR checking.
-
-@item -malign-data=@var{type}
-@opindex malign-data
-Control how GCC aligns variables and constants of array, structure, or union
-types. Supported values for @var{type} are @samp{xlen} which uses x register
-width as the alignment value, and @samp{natural} which uses natural alignment.
-@samp{xlen} is the default.
-
-@item -mbig-endian
-@opindex mbig-endian
-Generate big-endian code. This is the default when GCC is configured for a
-@samp{riscv64be-*-*} or @samp{riscv32be-*-*} target.
-
-@item -mlittle-endian
-@opindex mlittle-endian
-Generate little-endian code. This is the default when GCC is configured for a
-@samp{riscv64-*-*} or @samp{riscv32-*-*} but not a @samp{riscv64be-*-*} or
-@samp{riscv32be-*-*} target.
-
-@item -mstack-protector-guard=@var{guard}
-@itemx -mstack-protector-guard-reg=@var{reg}
-@itemx -mstack-protector-guard-offset=@var{offset}
-@opindex mstack-protector-guard
-@opindex mstack-protector-guard-reg
-@opindex mstack-protector-guard-offset
-Generate stack protection code using canary at @var{guard}. Supported
-locations are @samp{global} for a global canary or @samp{tls} for per-thread
-canary in the TLS block.
-
-With the latter choice the options
-@option{-mstack-protector-guard-reg=@var{reg}} and
-@option{-mstack-protector-guard-offset=@var{offset}} furthermore specify
-which register to use as base register for reading the canary,
-and from what offset from that base register. There is no default
-register or offset as this is entirely for use within the Linux
-kernel.
-@end table
-
-@node RL78 Options
-@subsection RL78 Options
-@cindex RL78 Options
-
-@table @gcctabopt
-
-@item -msim
-@opindex msim
-Links in additional target libraries to support operation within a
-simulator.
-
-@item -mmul=none
-@itemx -mmul=g10
-@itemx -mmul=g13
-@itemx -mmul=g14
-@itemx -mmul=rl78
-@opindex mmul
-Specifies the type of hardware multiplication and division support to
-be used. The simplest is @code{none}, which uses software for both
-multiplication and division. This is the default. The @code{g13}
-value is for the hardware multiply/divide peripheral found on the
-RL78/G13 (S2 core) targets. The @code{g14} value selects the use of
-the multiplication and division instructions supported by the RL78/G14
-(S3 core) parts. The value @code{rl78} is an alias for @code{g14} and
-the value @code{mg10} is an alias for @code{none}.
-
-In addition a C preprocessor macro is defined, based upon the setting
-of this option. Possible values are: @code{__RL78_MUL_NONE__},
-@code{__RL78_MUL_G13__} or @code{__RL78_MUL_G14__}.
-
-@item -mcpu=g10
-@itemx -mcpu=g13
-@itemx -mcpu=g14
-@itemx -mcpu=rl78
-@opindex mcpu
-Specifies the RL78 core to target. The default is the G14 core, also
-known as an S3 core or just RL78. The G13 or S2 core does not have
-multiply or divide instructions, instead it uses a hardware peripheral
-for these operations. The G10 or S1 core does not have register
-banks, so it uses a different calling convention.
-
-If this option is set it also selects the type of hardware multiply
-support to use, unless this is overridden by an explicit
-@option{-mmul=none} option on the command line. Thus specifying
-@option{-mcpu=g13} enables the use of the G13 hardware multiply
-peripheral and specifying @option{-mcpu=g10} disables the use of
-hardware multiplications altogether.
-
-Note, although the RL78/G14 core is the default target, specifying
-@option{-mcpu=g14} or @option{-mcpu=rl78} on the command line does
-change the behavior of the toolchain since it also enables G14
-hardware multiply support. If these options are not specified on the
-command line then software multiplication routines will be used even
-though the code targets the RL78 core. This is for backwards
-compatibility with older toolchains which did not have hardware
-multiply and divide support.
-
-In addition a C preprocessor macro is defined, based upon the setting
-of this option. Possible values are: @code{__RL78_G10__},
-@code{__RL78_G13__} or @code{__RL78_G14__}.
-
-@item -mg10
-@itemx -mg13
-@itemx -mg14
-@itemx -mrl78
-@opindex mg10
-@opindex mg13
-@opindex mg14
-@opindex mrl78
-These are aliases for the corresponding @option{-mcpu=} option. They
-are provided for backwards compatibility.
-
-@item -mallregs
-@opindex mallregs
-Allow the compiler to use all of the available registers. By default
-registers @code{r24..r31} are reserved for use in interrupt handlers.
-With this option enabled these registers can be used in ordinary
-functions as well.
-
-@item -m64bit-doubles
-@itemx -m32bit-doubles
-@opindex m64bit-doubles
-@opindex m32bit-doubles
-Make the @code{double} data type be 64 bits (@option{-m64bit-doubles})
-or 32 bits (@option{-m32bit-doubles}) in size. The default is
-@option{-m32bit-doubles}.
-
-@item -msave-mduc-in-interrupts
-@itemx -mno-save-mduc-in-interrupts
-@opindex msave-mduc-in-interrupts
-@opindex mno-save-mduc-in-interrupts
-Specifies that interrupt handler functions should preserve the
-MDUC registers. This is only necessary if normal code might use
-the MDUC registers, for example because it performs multiplication
-and division operations. The default is to ignore the MDUC registers
-as this makes the interrupt handlers faster. The target option -mg13
-needs to be passed for this to work as this feature is only available
-on the G13 target (S2 core). The MDUC registers will only be saved
-if the interrupt handler performs a multiplication or division
-operation or it calls another function.
-
-@end table
-
-@node RS/6000 and PowerPC Options
-@subsection IBM RS/6000 and PowerPC Options
-@cindex RS/6000 and PowerPC Options
-@cindex IBM RS/6000 and PowerPC Options
-
-These @samp{-m} options are defined for the IBM RS/6000 and PowerPC:
-@table @gcctabopt
-@item -mpowerpc-gpopt
-@itemx -mno-powerpc-gpopt
-@itemx -mpowerpc-gfxopt
-@itemx -mno-powerpc-gfxopt
-@need 800
-@itemx -mpowerpc64
-@itemx -mno-powerpc64
-@itemx -mmfcrf
-@itemx -mno-mfcrf
-@itemx -mpopcntb
-@itemx -mno-popcntb
-@itemx -mpopcntd
-@itemx -mno-popcntd
-@itemx -mfprnd
-@itemx -mno-fprnd
-@need 800
-@itemx -mcmpb
-@itemx -mno-cmpb
-@itemx -mhard-dfp
-@itemx -mno-hard-dfp
-@opindex mpowerpc-gpopt
-@opindex mno-powerpc-gpopt
-@opindex mpowerpc-gfxopt
-@opindex mno-powerpc-gfxopt
-@opindex mpowerpc64
-@opindex mno-powerpc64
-@opindex mmfcrf
-@opindex mno-mfcrf
-@opindex mpopcntb
-@opindex mno-popcntb
-@opindex mpopcntd
-@opindex mno-popcntd
-@opindex mfprnd
-@opindex mno-fprnd
-@opindex mcmpb
-@opindex mno-cmpb
-@opindex mhard-dfp
-@opindex mno-hard-dfp
-You use these options to specify which instructions are available on the
-processor you are using. The default value of these options is
-determined when configuring GCC@. Specifying the
-@option{-mcpu=@var{cpu_type}} overrides the specification of these
-options. We recommend you use the @option{-mcpu=@var{cpu_type}} option
-rather than the options listed above.
-
-Specifying @option{-mpowerpc-gpopt} allows
-GCC to use the optional PowerPC architecture instructions in the
-General Purpose group, including floating-point square root. Specifying
-@option{-mpowerpc-gfxopt} allows GCC to
-use the optional PowerPC architecture instructions in the Graphics
-group, including floating-point select.
-
-The @option{-mmfcrf} option allows GCC to generate the move from
-condition register field instruction implemented on the POWER4
-processor and other processors that support the PowerPC V2.01
-architecture.
-The @option{-mpopcntb} option allows GCC to generate the popcount and
-double-precision FP reciprocal estimate instruction implemented on the
-POWER5 processor and other processors that support the PowerPC V2.02
-architecture.
-The @option{-mpopcntd} option allows GCC to generate the popcount
-instruction implemented on the POWER7 processor and other processors
-that support the PowerPC V2.06 architecture.
-The @option{-mfprnd} option allows GCC to generate the FP round to
-integer instructions implemented on the POWER5+ processor and other
-processors that support the PowerPC V2.03 architecture.
-The @option{-mcmpb} option allows GCC to generate the compare bytes
-instruction implemented on the POWER6 processor and other processors
-that support the PowerPC V2.05 architecture.
-The @option{-mhard-dfp} option allows GCC to generate the decimal
-floating-point instructions implemented on some POWER processors.
-
-The @option{-mpowerpc64} option allows GCC to generate the additional
-64-bit instructions that are found in the full PowerPC64 architecture
-and to treat GPRs as 64-bit, doubleword quantities. GCC defaults to
-@option{-mno-powerpc64}.
-
-@item -mcpu=@var{cpu_type}
-@opindex mcpu
-Set architecture type, register usage, and
-instruction scheduling parameters for machine type @var{cpu_type}.
-Supported values for @var{cpu_type} are @samp{401}, @samp{403},
-@samp{405}, @samp{405fp}, @samp{440}, @samp{440fp}, @samp{464}, @samp{464fp},
-@samp{476}, @samp{476fp}, @samp{505}, @samp{601}, @samp{602}, @samp{603},
-@samp{603e}, @samp{604}, @samp{604e}, @samp{620}, @samp{630}, @samp{740},
-@samp{7400}, @samp{7450}, @samp{750}, @samp{801}, @samp{821}, @samp{823},
-@samp{860}, @samp{970}, @samp{8540}, @samp{a2}, @samp{e300c2},
-@samp{e300c3}, @samp{e500mc}, @samp{e500mc64}, @samp{e5500},
-@samp{e6500}, @samp{ec603e}, @samp{G3}, @samp{G4}, @samp{G5},
-@samp{titan}, @samp{power3}, @samp{power4}, @samp{power5}, @samp{power5+},
-@samp{power6}, @samp{power6x}, @samp{power7}, @samp{power8},
-@samp{power9}, @samp{power10}, @samp{powerpc}, @samp{powerpc64},
-@samp{powerpc64le}, @samp{rs64}, and @samp{native}.
-
-@option{-mcpu=powerpc}, @option{-mcpu=powerpc64}, and
-@option{-mcpu=powerpc64le} specify pure 32-bit PowerPC (either
-endian), 64-bit big endian PowerPC and 64-bit little endian PowerPC
-architecture machine types, with an appropriate, generic processor
-model assumed for scheduling purposes.
-
-Specifying @samp{native} as cpu type detects and selects the
-architecture option that corresponds to the host processor of the
-system performing the compilation.
-@option{-mcpu=native} has no effect if GCC does not recognize the
-processor.
-
-The other options specify a specific processor. Code generated under
-those options runs best on that processor, and may not run at all on
-others.
-
-The @option{-mcpu} options automatically enable or disable the
-following options:
-
-@gccoptlist{-maltivec -mfprnd -mhard-float -mmfcrf -mmultiple @gol
--mpopcntb -mpopcntd -mpowerpc64 @gol
--mpowerpc-gpopt -mpowerpc-gfxopt @gol
--mmulhw -mdlmzb -mmfpgpr -mvsx @gol
--mcrypto -mhtm -mpower8-fusion -mpower8-vector @gol
--mquad-memory -mquad-memory-atomic -mfloat128 @gol
--mfloat128-hardware -mprefixed -mpcrel -mmma @gol
--mrop-protect}
-
-The particular options set for any particular CPU varies between
-compiler versions, depending on what setting seems to produce optimal
-code for that CPU; it doesn't necessarily reflect the actual hardware's
-capabilities. If you wish to set an individual option to a particular
-value, you may specify it after the @option{-mcpu} option, like
-@option{-mcpu=970 -mno-altivec}.
-
-On AIX, the @option{-maltivec} and @option{-mpowerpc64} options are
-not enabled or disabled by the @option{-mcpu} option at present because
-AIX does not have full support for these options. You may still
-enable or disable them individually if you're sure it'll work in your
-environment.
-
-@item -mtune=@var{cpu_type}
-@opindex mtune
-Set the instruction scheduling parameters for machine type
-@var{cpu_type}, but do not set the architecture type or register usage,
-as @option{-mcpu=@var{cpu_type}} does. The same
-values for @var{cpu_type} are used for @option{-mtune} as for
-@option{-mcpu}. If both are specified, the code generated uses the
-architecture and registers set by @option{-mcpu}, but the
-scheduling parameters set by @option{-mtune}.
-
-@item -mcmodel=small
-@opindex mcmodel=small
-Generate PowerPC64 code for the small model: The TOC is limited to
-64k.
-
-@item -mcmodel=medium
-@opindex mcmodel=medium
-Generate PowerPC64 code for the medium model: The TOC and other static
-data may be up to a total of 4G in size. This is the default for 64-bit
-Linux.
-
-@item -mcmodel=large
-@opindex mcmodel=large
-Generate PowerPC64 code for the large model: The TOC may be up to 4G
-in size. Other data and code is only limited by the 64-bit address
-space.
-
-@item -maltivec
-@itemx -mno-altivec
-@opindex maltivec
-@opindex mno-altivec
-Generate code that uses (does not use) AltiVec instructions, and also
-enable the use of built-in functions that allow more direct access to
-the AltiVec instruction set. You may also need to set
-@option{-mabi=altivec} to adjust the current ABI with AltiVec ABI
-enhancements.
-
-When @option{-maltivec} is used, the element order for AltiVec intrinsics
-such as @code{vec_splat}, @code{vec_extract}, and @code{vec_insert}
-match array element order corresponding to the endianness of the
-target. That is, element zero identifies the leftmost element in a
-vector register when targeting a big-endian platform, and identifies
-the rightmost element in a vector register when targeting a
-little-endian platform.
-
-@item -mvrsave
-@itemx -mno-vrsave
-@opindex mvrsave
-@opindex mno-vrsave
-Generate VRSAVE instructions when generating AltiVec code.
-
-@item -msecure-plt
-@opindex msecure-plt
-Generate code that allows @command{ld} and @command{ld.so}
-to build executables and shared
-libraries with non-executable @code{.plt} and @code{.got} sections.
-This is a PowerPC
-32-bit SYSV ABI option.
-
-@item -mbss-plt
-@opindex mbss-plt
-Generate code that uses a BSS @code{.plt} section that @command{ld.so}
-fills in, and
-requires @code{.plt} and @code{.got}
-sections that are both writable and executable.
-This is a PowerPC 32-bit SYSV ABI option.
-
-@item -misel
-@itemx -mno-isel
-@opindex misel
-@opindex mno-isel
-This switch enables or disables the generation of ISEL instructions.
-
-@item -mvsx
-@itemx -mno-vsx
-@opindex mvsx
-@opindex mno-vsx
-Generate code that uses (does not use) vector/scalar (VSX)
-instructions, and also enable the use of built-in functions that allow
-more direct access to the VSX instruction set.
-
-@item -mcrypto
-@itemx -mno-crypto
-@opindex mcrypto
-@opindex mno-crypto
-Enable the use (disable) of the built-in functions that allow direct
-access to the cryptographic instructions that were added in version
-2.07 of the PowerPC ISA.
-
-@item -mhtm
-@itemx -mno-htm
-@opindex mhtm
-@opindex mno-htm
-Enable (disable) the use of the built-in functions that allow direct
-access to the Hardware Transactional Memory (HTM) instructions that
-were added in version 2.07 of the PowerPC ISA.
-
-@item -mpower8-fusion
-@itemx -mno-power8-fusion
-@opindex mpower8-fusion
-@opindex mno-power8-fusion
-Generate code that keeps (does not keeps) some integer operations
-adjacent so that the instructions can be fused together on power8 and
-later processors.
-
-@item -mpower8-vector
-@itemx -mno-power8-vector
-@opindex mpower8-vector
-@opindex mno-power8-vector
-Generate code that uses (does not use) the vector and scalar
-instructions that were added in version 2.07 of the PowerPC ISA. Also
-enable the use of built-in functions that allow more direct access to
-the vector instructions.
-
-@item -mquad-memory
-@itemx -mno-quad-memory
-@opindex mquad-memory
-@opindex mno-quad-memory
-Generate code that uses (does not use) the non-atomic quad word memory
-instructions. The @option{-mquad-memory} option requires use of
-64-bit mode.
-
-@item -mquad-memory-atomic
-@itemx -mno-quad-memory-atomic
-@opindex mquad-memory-atomic
-@opindex mno-quad-memory-atomic
-Generate code that uses (does not use) the atomic quad word memory
-instructions. The @option{-mquad-memory-atomic} option requires use of
-64-bit mode.
-
-@item -mfloat128
-@itemx -mno-float128
-@opindex mfloat128
-@opindex mno-float128
-Enable/disable the @var{__float128} keyword for IEEE 128-bit floating point
-and use either software emulation for IEEE 128-bit floating point or
-hardware instructions.
-
-The VSX instruction set (@option{-mvsx}) must be enabled to use the IEEE
-128-bit floating point support. The IEEE 128-bit floating point is only
-supported on Linux.
-
-The default for @option{-mfloat128} is enabled on PowerPC Linux
-systems using the VSX instruction set, and disabled on other systems.
-
-If you use the ISA 3.0 instruction set (@option{-mpower9-vector} or
-@option{-mcpu=power9}) on a 64-bit system, the IEEE 128-bit floating
-point support will also enable the generation of ISA 3.0 IEEE 128-bit
-floating point instructions. Otherwise, if you do not specify to
-generate ISA 3.0 instructions or you are targeting a 32-bit big endian
-system, IEEE 128-bit floating point will be done with software
-emulation.
-
-@item -mfloat128-hardware
-@itemx -mno-float128-hardware
-@opindex mfloat128-hardware
-@opindex mno-float128-hardware
-Enable/disable using ISA 3.0 hardware instructions to support the
-@var{__float128} data type.
-
-The default for @option{-mfloat128-hardware} is enabled on PowerPC
-Linux systems using the ISA 3.0 instruction set, and disabled on other
-systems.
-
-@item -m32
-@itemx -m64
-@opindex m32
-@opindex m64
-Generate code for 32-bit or 64-bit environments of Darwin and SVR4
-targets (including GNU/Linux). The 32-bit environment sets int, long
-and pointer to 32 bits and generates code that runs on any PowerPC
-variant. The 64-bit environment sets int to 32 bits and long and
-pointer to 64 bits, and generates code for PowerPC64, as for
-@option{-mpowerpc64}.
-
-@item -mfull-toc
-@itemx -mno-fp-in-toc
-@itemx -mno-sum-in-toc
-@itemx -mminimal-toc
-@opindex mfull-toc
-@opindex mno-fp-in-toc
-@opindex mno-sum-in-toc
-@opindex mminimal-toc
-Modify generation of the TOC (Table Of Contents), which is created for
-every executable file. The @option{-mfull-toc} option is selected by
-default. In that case, GCC allocates at least one TOC entry for
-each unique non-automatic variable reference in your program. GCC
-also places floating-point constants in the TOC@. However, only
-16,384 entries are available in the TOC@.
-
-If you receive a linker error message that saying you have overflowed
-the available TOC space, you can reduce the amount of TOC space used
-with the @option{-mno-fp-in-toc} and @option{-mno-sum-in-toc} options.
-@option{-mno-fp-in-toc} prevents GCC from putting floating-point
-constants in the TOC and @option{-mno-sum-in-toc} forces GCC to
-generate code to calculate the sum of an address and a constant at
-run time instead of putting that sum into the TOC@. You may specify one
-or both of these options. Each causes GCC to produce very slightly
-slower and larger code at the expense of conserving TOC space.
-
-If you still run out of space in the TOC even when you specify both of
-these options, specify @option{-mminimal-toc} instead. This option causes
-GCC to make only one TOC entry for every file. When you specify this
-option, GCC produces code that is slower and larger but which
-uses extremely little TOC space. You may wish to use this option
-only on files that contain less frequently-executed code.
-
-@item -maix64
-@itemx -maix32
-@opindex maix64
-@opindex maix32
-Enable 64-bit AIX ABI and calling convention: 64-bit pointers, 64-bit
-@code{long} type, and the infrastructure needed to support them.
-Specifying @option{-maix64} implies @option{-mpowerpc64},
-while @option{-maix32} disables the 64-bit ABI and
-implies @option{-mno-powerpc64}. GCC defaults to @option{-maix32}.
-
-@item -mxl-compat
-@itemx -mno-xl-compat
-@opindex mxl-compat
-@opindex mno-xl-compat
-Produce code that conforms more closely to IBM XL compiler semantics
-when using AIX-compatible ABI@. Pass floating-point arguments to
-prototyped functions beyond the register save area (RSA) on the stack
-in addition to argument FPRs. Do not assume that most significant
-double in 128-bit long double value is properly rounded when comparing
-values and converting to double. Use XL symbol names for long double
-support routines.
-
-The AIX calling convention was extended but not initially documented to
-handle an obscure K&R C case of calling a function that takes the
-address of its arguments with fewer arguments than declared. IBM XL
-compilers access floating-point arguments that do not fit in the
-RSA from the stack when a subroutine is compiled without
-optimization. Because always storing floating-point arguments on the
-stack is inefficient and rarely needed, this option is not enabled by
-default and only is necessary when calling subroutines compiled by IBM
-XL compilers without optimization.
-
-@item -mpe
-@opindex mpe
-Support @dfn{IBM RS/6000 SP} @dfn{Parallel Environment} (PE)@. Link an
-application written to use message passing with special startup code to
-enable the application to run. The system must have PE installed in the
-standard location (@file{/usr/lpp/ppe.poe/}), or the @file{specs} file
-must be overridden with the @option{-specs=} option to specify the
-appropriate directory location. The Parallel Environment does not
-support threads, so the @option{-mpe} option and the @option{-pthread}
-option are incompatible.
-
-@item -malign-natural
-@itemx -malign-power
-@opindex malign-natural
-@opindex malign-power
-On AIX, 32-bit Darwin, and 64-bit PowerPC GNU/Linux, the option
-@option{-malign-natural} overrides the ABI-defined alignment of larger
-types, such as floating-point doubles, on their natural size-based boundary.
-The option @option{-malign-power} instructs GCC to follow the ABI-specified
-alignment rules. GCC defaults to the standard alignment defined in the ABI@.
-
-On 64-bit Darwin, natural alignment is the default, and @option{-malign-power}
-is not supported.
-
-@item -msoft-float
-@itemx -mhard-float
-@opindex msoft-float
-@opindex mhard-float
-Generate code that does not use (uses) the floating-point register set.
-Software floating-point emulation is provided if you use the
-@option{-msoft-float} option, and pass the option to GCC when linking.
-
-@item -mmultiple
-@itemx -mno-multiple
-@opindex mmultiple
-@opindex mno-multiple
-Generate code that uses (does not use) the load multiple word
-instructions and the store multiple word instructions. These
-instructions are generated by default on POWER systems, and not
-generated on PowerPC systems. Do not use @option{-mmultiple} on little-endian
-PowerPC systems, since those instructions do not work when the
-processor is in little-endian mode. The exceptions are PPC740 and
-PPC750 which permit these instructions in little-endian mode.
-
-@item -mupdate
-@itemx -mno-update
-@opindex mupdate
-@opindex mno-update
-Generate code that uses (does not use) the load or store instructions
-that update the base register to the address of the calculated memory
-location. These instructions are generated by default. If you use
-@option{-mno-update}, there is a small window between the time that the
-stack pointer is updated and the address of the previous frame is
-stored, which means code that walks the stack frame across interrupts or
-signals may get corrupted data.
-
-@item -mavoid-indexed-addresses
-@itemx -mno-avoid-indexed-addresses
-@opindex mavoid-indexed-addresses
-@opindex mno-avoid-indexed-addresses
-Generate code that tries to avoid (not avoid) the use of indexed load
-or store instructions. These instructions can incur a performance
-penalty on Power6 processors in certain situations, such as when
-stepping through large arrays that cross a 16M boundary. This option
-is enabled by default when targeting Power6 and disabled otherwise.
-
-@item -mfused-madd
-@itemx -mno-fused-madd
-@opindex mfused-madd
-@opindex mno-fused-madd
-Generate code that uses (does not use) the floating-point multiply and
-accumulate instructions. These instructions are generated by default
-if hardware floating point is used. The machine-dependent
-@option{-mfused-madd} option is now mapped to the machine-independent
-@option{-ffp-contract=fast} option, and @option{-mno-fused-madd} is
-mapped to @option{-ffp-contract=off}.
-
-@item -mmulhw
-@itemx -mno-mulhw
-@opindex mmulhw
-@opindex mno-mulhw
-Generate code that uses (does not use) the half-word multiply and
-multiply-accumulate instructions on the IBM 405, 440, 464 and 476 processors.
-These instructions are generated by default when targeting those
-processors.
-
-@item -mdlmzb
-@itemx -mno-dlmzb
-@opindex mdlmzb
-@opindex mno-dlmzb
-Generate code that uses (does not use) the string-search @samp{dlmzb}
-instruction on the IBM 405, 440, 464 and 476 processors. This instruction is
-generated by default when targeting those processors.
-
-@item -mno-bit-align
-@itemx -mbit-align
-@opindex mno-bit-align
-@opindex mbit-align
-On System V.4 and embedded PowerPC systems do not (do) force structures
-and unions that contain bit-fields to be aligned to the base type of the
-bit-field.
-
-For example, by default a structure containing nothing but 8
-@code{unsigned} bit-fields of length 1 is aligned to a 4-byte
-boundary and has a size of 4 bytes. By using @option{-mno-bit-align},
-the structure is aligned to a 1-byte boundary and is 1 byte in
-size.
-
-@item -mno-strict-align
-@itemx -mstrict-align
-@opindex mno-strict-align
-@opindex mstrict-align
-On System V.4 and embedded PowerPC systems do not (do) assume that
-unaligned memory references are handled by the system.
-
-@item -mrelocatable
-@itemx -mno-relocatable
-@opindex mrelocatable
-@opindex mno-relocatable
-Generate code that allows (does not allow) a static executable to be
-relocated to a different address at run time. A simple embedded
-PowerPC system loader should relocate the entire contents of
-@code{.got2} and 4-byte locations listed in the @code{.fixup} section,
-a table of 32-bit addresses generated by this option. For this to
-work, all objects linked together must be compiled with
-@option{-mrelocatable} or @option{-mrelocatable-lib}.
-@option{-mrelocatable} code aligns the stack to an 8-byte boundary.
-
-@item -mrelocatable-lib
-@itemx -mno-relocatable-lib
-@opindex mrelocatable-lib
-@opindex mno-relocatable-lib
-Like @option{-mrelocatable}, @option{-mrelocatable-lib} generates a
-@code{.fixup} section to allow static executables to be relocated at
-run time, but @option{-mrelocatable-lib} does not use the smaller stack
-alignment of @option{-mrelocatable}. Objects compiled with
-@option{-mrelocatable-lib} may be linked with objects compiled with
-any combination of the @option{-mrelocatable} options.
-
-@item -mno-toc
-@itemx -mtoc
-@opindex mno-toc
-@opindex mtoc
-On System V.4 and embedded PowerPC systems do not (do) assume that
-register 2 contains a pointer to a global area pointing to the addresses
-used in the program.
-
-@item -mlittle
-@itemx -mlittle-endian
-@opindex mlittle
-@opindex mlittle-endian
-On System V.4 and embedded PowerPC systems compile code for the
-processor in little-endian mode. The @option{-mlittle-endian} option is
-the same as @option{-mlittle}.
-
-@item -mbig
-@itemx -mbig-endian
-@opindex mbig
-@opindex mbig-endian
-On System V.4 and embedded PowerPC systems compile code for the
-processor in big-endian mode. The @option{-mbig-endian} option is
-the same as @option{-mbig}.
-
-@item -mdynamic-no-pic
-@opindex mdynamic-no-pic
-On Darwin and Mac OS X systems, compile code so that it is not
-relocatable, but that its external references are relocatable. The
-resulting code is suitable for applications, but not shared
-libraries.
-
-@item -msingle-pic-base
-@opindex msingle-pic-base
-Treat the register used for PIC addressing as read-only, rather than
-loading it in the prologue for each function. The runtime system is
-responsible for initializing this register with an appropriate value
-before execution begins.
-
-@item -mprioritize-restricted-insns=@var{priority}
-@opindex mprioritize-restricted-insns
-This option controls the priority that is assigned to
-dispatch-slot restricted instructions during the second scheduling
-pass. The argument @var{priority} takes the value @samp{0}, @samp{1},
-or @samp{2} to assign no, highest, or second-highest (respectively)
-priority to dispatch-slot restricted
-instructions.
-
-@item -msched-costly-dep=@var{dependence_type}
-@opindex msched-costly-dep
-This option controls which dependences are considered costly
-by the target during instruction scheduling. The argument
-@var{dependence_type} takes one of the following values:
-
-@table @asis
-@item @samp{no}
-No dependence is costly.
-
-@item @samp{all}
-All dependences are costly.
-
-@item @samp{true_store_to_load}
-A true dependence from store to load is costly.
-
-@item @samp{store_to_load}
-Any dependence from store to load is costly.
-
-@item @var{number}
-Any dependence for which the latency is greater than or equal to
-@var{number} is costly.
-@end table
-
-@item -minsert-sched-nops=@var{scheme}
-@opindex minsert-sched-nops
-This option controls which NOP insertion scheme is used during
-the second scheduling pass. The argument @var{scheme} takes one of the
-following values:
-
-@table @asis
-@item @samp{no}
-Don't insert NOPs.
-
-@item @samp{pad}
-Pad with NOPs any dispatch group that has vacant issue slots,
-according to the scheduler's grouping.
-
-@item @samp{regroup_exact}
-Insert NOPs to force costly dependent insns into
-separate groups. Insert exactly as many NOPs as needed to force an insn
-to a new group, according to the estimated processor grouping.
-
-@item @var{number}
-Insert NOPs to force costly dependent insns into
-separate groups. Insert @var{number} NOPs to force an insn to a new group.
-@end table
-
-@item -mcall-sysv
-@opindex mcall-sysv
-On System V.4 and embedded PowerPC systems compile code using calling
-conventions that adhere to the March 1995 draft of the System V
-Application Binary Interface, PowerPC processor supplement. This is the
-default unless you configured GCC using @samp{powerpc-*-eabiaix}.
-
-@item -mcall-sysv-eabi
-@itemx -mcall-eabi
-@opindex mcall-sysv-eabi
-@opindex mcall-eabi
-Specify both @option{-mcall-sysv} and @option{-meabi} options.
-
-@item -mcall-sysv-noeabi
-@opindex mcall-sysv-noeabi
-Specify both @option{-mcall-sysv} and @option{-mno-eabi} options.
-
-@item -mcall-aixdesc
-@opindex m
-On System V.4 and embedded PowerPC systems compile code for the AIX
-operating system.
-
-@item -mcall-linux
-@opindex mcall-linux
-On System V.4 and embedded PowerPC systems compile code for the
-Linux-based GNU system.
-
-@item -mcall-freebsd
-@opindex mcall-freebsd
-On System V.4 and embedded PowerPC systems compile code for the
-FreeBSD operating system.
-
-@item -mcall-netbsd
-@opindex mcall-netbsd
-On System V.4 and embedded PowerPC systems compile code for the
-NetBSD operating system.
-
-@item -mcall-openbsd
-@opindex mcall-netbsd
-On System V.4 and embedded PowerPC systems compile code for the
-OpenBSD operating system.
-
-@item -mtraceback=@var{traceback_type}
-@opindex mtraceback
-Select the type of traceback table. Valid values for @var{traceback_type}
-are @samp{full}, @samp{part}, and @samp{no}.
-
-@item -maix-struct-return
-@opindex maix-struct-return
-Return all structures in memory (as specified by the AIX ABI)@.
-
-@item -msvr4-struct-return
-@opindex msvr4-struct-return
-Return structures smaller than 8 bytes in registers (as specified by the
-SVR4 ABI)@.
-
-@item -mabi=@var{abi-type}
-@opindex mabi
-Extend the current ABI with a particular extension, or remove such extension.
-Valid values are: @samp{altivec}, @samp{no-altivec},
-@samp{ibmlongdouble}, @samp{ieeelongdouble},
-@samp{elfv1}, @samp{elfv2},
-and for AIX: @samp{vec-extabi}, @samp{vec-default}@.
-
-@item -mabi=ibmlongdouble
-@opindex mabi=ibmlongdouble
-Change the current ABI to use IBM extended-precision long double.
-This is not likely to work if your system defaults to using IEEE
-extended-precision long double. If you change the long double type
-from IEEE extended-precision, the compiler will issue a warning unless
-you use the @option{-Wno-psabi} option. Requires @option{-mlong-double-128}
-to be enabled.
-
-@item -mabi=ieeelongdouble
-@opindex mabi=ieeelongdouble
-Change the current ABI to use IEEE extended-precision long double.
-This is not likely to work if your system defaults to using IBM
-extended-precision long double. If you change the long double type
-from IBM extended-precision, the compiler will issue a warning unless
-you use the @option{-Wno-psabi} option. Requires @option{-mlong-double-128}
-to be enabled.
-
-@item -mabi=elfv1
-@opindex mabi=elfv1
-Change the current ABI to use the ELFv1 ABI.
-This is the default ABI for big-endian PowerPC 64-bit Linux.
-Overriding the default ABI requires special system support and is
-likely to fail in spectacular ways.
-
-@item -mabi=elfv2
-@opindex mabi=elfv2
-Change the current ABI to use the ELFv2 ABI.
-This is the default ABI for little-endian PowerPC 64-bit Linux.
-Overriding the default ABI requires special system support and is
-likely to fail in spectacular ways.
-
-@item -mgnu-attribute
-@itemx -mno-gnu-attribute
-@opindex mgnu-attribute
-@opindex mno-gnu-attribute
-Emit .gnu_attribute assembly directives to set tag/value pairs in a
-.gnu.attributes section that specify ABI variations in function
-parameters or return values.
-
-@item -mprototype
-@itemx -mno-prototype
-@opindex mprototype
-@opindex mno-prototype
-On System V.4 and embedded PowerPC systems assume that all calls to
-variable argument functions are properly prototyped. Otherwise, the
-compiler must insert an instruction before every non-prototyped call to
-set or clear bit 6 of the condition code register (@code{CR}) to
-indicate whether floating-point values are passed in the floating-point
-registers in case the function takes variable arguments. With
-@option{-mprototype}, only calls to prototyped variable argument functions
-set or clear the bit.
-
-@item -msim
-@opindex msim
-On embedded PowerPC systems, assume that the startup module is called
-@file{sim-crt0.o} and that the standard C libraries are @file{libsim.a} and
-@file{libc.a}. This is the default for @samp{powerpc-*-eabisim}
-configurations.
-
-@item -mmvme
-@opindex mmvme
-On embedded PowerPC systems, assume that the startup module is called
-@file{crt0.o} and the standard C libraries are @file{libmvme.a} and
-@file{libc.a}.
-
-@item -mads
-@opindex mads
-On embedded PowerPC systems, assume that the startup module is called
-@file{crt0.o} and the standard C libraries are @file{libads.a} and
-@file{libc.a}.
-
-@item -myellowknife
-@opindex myellowknife
-On embedded PowerPC systems, assume that the startup module is called
-@file{crt0.o} and the standard C libraries are @file{libyk.a} and
-@file{libc.a}.
-
-@item -mvxworks
-@opindex mvxworks
-On System V.4 and embedded PowerPC systems, specify that you are
-compiling for a VxWorks system.
-
-@item -memb
-@opindex memb
-On embedded PowerPC systems, set the @code{PPC_EMB} bit in the ELF flags
-header to indicate that @samp{eabi} extended relocations are used.
-
-@item -meabi
-@itemx -mno-eabi
-@opindex meabi
-@opindex mno-eabi
-On System V.4 and embedded PowerPC systems do (do not) adhere to the
-Embedded Applications Binary Interface (EABI), which is a set of
-modifications to the System V.4 specifications. Selecting @option{-meabi}
-means that the stack is aligned to an 8-byte boundary, a function
-@code{__eabi} is called from @code{main} to set up the EABI
-environment, and the @option{-msdata} option can use both @code{r2} and
-@code{r13} to point to two separate small data areas. Selecting
-@option{-mno-eabi} means that the stack is aligned to a 16-byte boundary,
-no EABI initialization function is called from @code{main}, and the
-@option{-msdata} option only uses @code{r13} to point to a single
-small data area. The @option{-meabi} option is on by default if you
-configured GCC using one of the @samp{powerpc*-*-eabi*} options.
-
-@item -msdata=eabi
-@opindex msdata=eabi
-On System V.4 and embedded PowerPC systems, put small initialized
-@code{const} global and static data in the @code{.sdata2} section, which
-is pointed to by register @code{r2}. Put small initialized
-non-@code{const} global and static data in the @code{.sdata} section,
-which is pointed to by register @code{r13}. Put small uninitialized
-global and static data in the @code{.sbss} section, which is adjacent to
-the @code{.sdata} section. The @option{-msdata=eabi} option is
-incompatible with the @option{-mrelocatable} option. The
-@option{-msdata=eabi} option also sets the @option{-memb} option.
-
-@item -msdata=sysv
-@opindex msdata=sysv
-On System V.4 and embedded PowerPC systems, put small global and static
-data in the @code{.sdata} section, which is pointed to by register
-@code{r13}. Put small uninitialized global and static data in the
-@code{.sbss} section, which is adjacent to the @code{.sdata} section.
-The @option{-msdata=sysv} option is incompatible with the
-@option{-mrelocatable} option.
-
-@item -msdata=default
-@itemx -msdata
-@opindex msdata=default
-@opindex msdata
-On System V.4 and embedded PowerPC systems, if @option{-meabi} is used,
-compile code the same as @option{-msdata=eabi}, otherwise compile code the
-same as @option{-msdata=sysv}.
-
-@item -msdata=data
-@opindex msdata=data
-On System V.4 and embedded PowerPC systems, put small global
-data in the @code{.sdata} section. Put small uninitialized global
-data in the @code{.sbss} section. Do not use register @code{r13}
-to address small data however. This is the default behavior unless
-other @option{-msdata} options are used.
-
-@item -msdata=none
-@itemx -mno-sdata
-@opindex msdata=none
-@opindex mno-sdata
-On embedded PowerPC systems, put all initialized global and static data
-in the @code{.data} section, and all uninitialized data in the
-@code{.bss} section.
-
-@item -mreadonly-in-sdata
-@opindex mreadonly-in-sdata
-@opindex mno-readonly-in-sdata
-Put read-only objects in the @code{.sdata} section as well. This is the
-default.
-
-@item -mblock-move-inline-limit=@var{num}
-@opindex mblock-move-inline-limit
-Inline all block moves (such as calls to @code{memcpy} or structure
-copies) less than or equal to @var{num} bytes. The minimum value for
-@var{num} is 32 bytes on 32-bit targets and 64 bytes on 64-bit
-targets. The default value is target-specific.
-
-@item -mblock-compare-inline-limit=@var{num}
-@opindex mblock-compare-inline-limit
-Generate non-looping inline code for all block compares (such as calls
-to @code{memcmp} or structure compares) less than or equal to @var{num}
-bytes. If @var{num} is 0, all inline expansion (non-loop and loop) of
-block compare is disabled. The default value is target-specific.
-
-@item -mblock-compare-inline-loop-limit=@var{num}
-@opindex mblock-compare-inline-loop-limit
-Generate an inline expansion using loop code for all block compares that
-are less than or equal to @var{num} bytes, but greater than the limit
-for non-loop inline block compare expansion. If the block length is not
-constant, at most @var{num} bytes will be compared before @code{memcmp}
-is called to compare the remainder of the block. The default value is
-target-specific.
-
-@item -mstring-compare-inline-limit=@var{num}
-@opindex mstring-compare-inline-limit
-Compare at most @var{num} string bytes with inline code.
-If the difference or end of string is not found at the
-end of the inline compare a call to @code{strcmp} or @code{strncmp} will
-take care of the rest of the comparison. The default is 64 bytes.
-
-@item -G @var{num}
-@opindex G
-@cindex smaller data references (PowerPC)
-@cindex .sdata/.sdata2 references (PowerPC)
-On embedded PowerPC systems, put global and static items less than or
-equal to @var{num} bytes into the small data or BSS sections instead of
-the normal data or BSS section. By default, @var{num} is 8. The
-@option{-G @var{num}} switch is also passed to the linker.
-All modules should be compiled with the same @option{-G @var{num}} value.
-
-@item -mregnames
-@itemx -mno-regnames
-@opindex mregnames
-@opindex mno-regnames
-On System V.4 and embedded PowerPC systems do (do not) emit register
-names in the assembly language output using symbolic forms.
-
-@item -mlongcall
-@itemx -mno-longcall
-@opindex mlongcall
-@opindex mno-longcall
-By default assume that all calls are far away so that a longer and more
-expensive calling sequence is required. This is required for calls
-farther than 32 megabytes (33,554,432 bytes) from the current location.
-A short call is generated if the compiler knows
-the call cannot be that far away. This setting can be overridden by
-the @code{shortcall} function attribute, or by @code{#pragma
-longcall(0)}.
-
-Some linkers are capable of detecting out-of-range calls and generating
-glue code on the fly. On these systems, long calls are unnecessary and
-generate slower code. As of this writing, the AIX linker can do this,
-as can the GNU linker for PowerPC/64. It is planned to add this feature
-to the GNU linker for 32-bit PowerPC systems as well.
-
-On PowerPC64 ELFv2 and 32-bit PowerPC systems with newer GNU linkers,
-GCC can generate long calls using an inline PLT call sequence (see
-@option{-mpltseq}). PowerPC with @option{-mbss-plt} and PowerPC64
-ELFv1 (big-endian) do not support inline PLT calls.
-
-On Darwin/PPC systems, @code{#pragma longcall} generates @code{jbsr
-callee, L42}, plus a @dfn{branch island} (glue code). The two target
-addresses represent the callee and the branch island. The
-Darwin/PPC linker prefers the first address and generates a @code{bl
-callee} if the PPC @code{bl} instruction reaches the callee directly;
-otherwise, the linker generates @code{bl L42} to call the branch
-island. The branch island is appended to the body of the
-calling function; it computes the full 32-bit address of the callee
-and jumps to it.
-
-On Mach-O (Darwin) systems, this option directs the compiler emit to
-the glue for every direct call, and the Darwin linker decides whether
-to use or discard it.
-
-In the future, GCC may ignore all longcall specifications
-when the linker is known to generate glue.
-
-@item -mpltseq
-@itemx -mno-pltseq
-@opindex mpltseq
-@opindex mno-pltseq
-Implement (do not implement) -fno-plt and long calls using an inline
-PLT call sequence that supports lazy linking and long calls to
-functions in dlopen'd shared libraries. Inline PLT calls are only
-supported on PowerPC64 ELFv2 and 32-bit PowerPC systems with newer GNU
-linkers, and are enabled by default if the support is detected when
-configuring GCC, and, in the case of 32-bit PowerPC, if GCC is
-configured with @option{--enable-secureplt}. @option{-mpltseq} code
-and @option{-mbss-plt} 32-bit PowerPC relocatable objects may not be
-linked together.
-
-@item -mtls-markers
-@itemx -mno-tls-markers
-@opindex mtls-markers
-@opindex mno-tls-markers
-Mark (do not mark) calls to @code{__tls_get_addr} with a relocation
-specifying the function argument. The relocation allows the linker to
-reliably associate function call with argument setup instructions for
-TLS optimization, which in turn allows GCC to better schedule the
-sequence.
-
-@item -mrecip
-@itemx -mno-recip
-@opindex mrecip
-This option enables use of the reciprocal estimate and
-reciprocal square root estimate instructions with additional
-Newton-Raphson steps to increase precision instead of doing a divide or
-square root and divide for floating-point arguments. You should use
-the @option{-ffast-math} option when using @option{-mrecip} (or at
-least @option{-funsafe-math-optimizations},
-@option{-ffinite-math-only}, @option{-freciprocal-math} and
-@option{-fno-trapping-math}). Note that while the throughput of the
-sequence is generally higher than the throughput of the non-reciprocal
-instruction, the precision of the sequence can be decreased by up to 2
-ulp (i.e.@: the inverse of 1.0 equals 0.99999994) for reciprocal square
-roots.
-
-@item -mrecip=@var{opt}
-@opindex mrecip=opt
-This option controls which reciprocal estimate instructions
-may be used. @var{opt} is a comma-separated list of options, which may
-be preceded by a @code{!} to invert the option:
-
-@table @samp
-
-@item all
-Enable all estimate instructions.
-
-@item default
-Enable the default instructions, equivalent to @option{-mrecip}.
-
-@item none
-Disable all estimate instructions, equivalent to @option{-mno-recip}.
-
-@item div
-Enable the reciprocal approximation instructions for both
-single and double precision.
-
-@item divf
-Enable the single-precision reciprocal approximation instructions.
-
-@item divd
-Enable the double-precision reciprocal approximation instructions.
-
-@item rsqrt
-Enable the reciprocal square root approximation instructions for both
-single and double precision.
-
-@item rsqrtf
-Enable the single-precision reciprocal square root approximation instructions.
-
-@item rsqrtd
-Enable the double-precision reciprocal square root approximation instructions.
-
-@end table
-
-So, for example, @option{-mrecip=all,!rsqrtd} enables
-all of the reciprocal estimate instructions, except for the
-@code{FRSQRTE}, @code{XSRSQRTEDP}, and @code{XVRSQRTEDP} instructions
-which handle the double-precision reciprocal square root calculations.
-
-@item -mrecip-precision
-@itemx -mno-recip-precision
-@opindex mrecip-precision
-Assume (do not assume) that the reciprocal estimate instructions
-provide higher-precision estimates than is mandated by the PowerPC
-ABI. Selecting @option{-mcpu=power6}, @option{-mcpu=power7} or
-@option{-mcpu=power8} automatically selects @option{-mrecip-precision}.
-The double-precision square root estimate instructions are not generated by
-default on low-precision machines, since they do not provide an
-estimate that converges after three steps.
-
-@item -mveclibabi=@var{type}
-@opindex mveclibabi
-Specifies the ABI type to use for vectorizing intrinsics using an
-external library. The only type supported at present is @samp{mass},
-which specifies to use IBM's Mathematical Acceleration Subsystem
-(MASS) libraries for vectorizing intrinsics using external libraries.
-GCC currently emits calls to @code{acosd2}, @code{acosf4},
-@code{acoshd2}, @code{acoshf4}, @code{asind2}, @code{asinf4},
-@code{asinhd2}, @code{asinhf4}, @code{atan2d2}, @code{atan2f4},
-@code{atand2}, @code{atanf4}, @code{atanhd2}, @code{atanhf4},
-@code{cbrtd2}, @code{cbrtf4}, @code{cosd2}, @code{cosf4},
-@code{coshd2}, @code{coshf4}, @code{erfcd2}, @code{erfcf4},
-@code{erfd2}, @code{erff4}, @code{exp2d2}, @code{exp2f4},
-@code{expd2}, @code{expf4}, @code{expm1d2}, @code{expm1f4},
-@code{hypotd2}, @code{hypotf4}, @code{lgammad2}, @code{lgammaf4},
-@code{log10d2}, @code{log10f4}, @code{log1pd2}, @code{log1pf4},
-@code{log2d2}, @code{log2f4}, @code{logd2}, @code{logf4},
-@code{powd2}, @code{powf4}, @code{sind2}, @code{sinf4}, @code{sinhd2},
-@code{sinhf4}, @code{sqrtd2}, @code{sqrtf4}, @code{tand2},
-@code{tanf4}, @code{tanhd2}, and @code{tanhf4} when generating code
-for power7. Both @option{-ftree-vectorize} and
-@option{-funsafe-math-optimizations} must also be enabled. The MASS
-libraries must be specified at link time.
-
-@item -mfriz
-@itemx -mno-friz
-@opindex mfriz
-Generate (do not generate) the @code{friz} instruction when the
-@option{-funsafe-math-optimizations} option is used to optimize
-rounding of floating-point values to 64-bit integer and back to floating
-point. The @code{friz} instruction does not return the same value if
-the floating-point number is too large to fit in an integer.
-
-@item -mpointers-to-nested-functions
-@itemx -mno-pointers-to-nested-functions
-@opindex mpointers-to-nested-functions
-Generate (do not generate) code to load up the static chain register
-(@code{r11}) when calling through a pointer on AIX and 64-bit Linux
-systems where a function pointer points to a 3-word descriptor giving
-the function address, TOC value to be loaded in register @code{r2}, and
-static chain value to be loaded in register @code{r11}. The
-@option{-mpointers-to-nested-functions} is on by default. You cannot
-call through pointers to nested functions or pointers
-to functions compiled in other languages that use the static chain if
-you use @option{-mno-pointers-to-nested-functions}.
-
-@item -msave-toc-indirect
-@itemx -mno-save-toc-indirect
-@opindex msave-toc-indirect
-Generate (do not generate) code to save the TOC value in the reserved
-stack location in the function prologue if the function calls through
-a pointer on AIX and 64-bit Linux systems. If the TOC value is not
-saved in the prologue, it is saved just before the call through the
-pointer. The @option{-mno-save-toc-indirect} option is the default.
-
-@item -mcompat-align-parm
-@itemx -mno-compat-align-parm
-@opindex mcompat-align-parm
-Generate (do not generate) code to pass structure parameters with a
-maximum alignment of 64 bits, for compatibility with older versions
-of GCC.
-
-Older versions of GCC (prior to 4.9.0) incorrectly did not align a
-structure parameter on a 128-bit boundary when that structure contained
-a member requiring 128-bit alignment. This is corrected in more
-recent versions of GCC. This option may be used to generate code
-that is compatible with functions compiled with older versions of
-GCC.
-
-The @option{-mno-compat-align-parm} option is the default.
-
-@item -mstack-protector-guard=@var{guard}
-@itemx -mstack-protector-guard-reg=@var{reg}
-@itemx -mstack-protector-guard-offset=@var{offset}
-@itemx -mstack-protector-guard-symbol=@var{symbol}
-@opindex mstack-protector-guard
-@opindex mstack-protector-guard-reg
-@opindex mstack-protector-guard-offset
-@opindex mstack-protector-guard-symbol
-Generate stack protection code using canary at @var{guard}. Supported
-locations are @samp{global} for global canary or @samp{tls} for per-thread
-canary in the TLS block (the default with GNU libc version 2.4 or later).
-
-With the latter choice the options
-@option{-mstack-protector-guard-reg=@var{reg}} and
-@option{-mstack-protector-guard-offset=@var{offset}} furthermore specify
-which register to use as base register for reading the canary, and from what
-offset from that base register. The default for those is as specified in the
-relevant ABI. @option{-mstack-protector-guard-symbol=@var{symbol}} overrides
-the offset with a symbol reference to a canary in the TLS block.
-
-@item -mpcrel
-@itemx -mno-pcrel
-@opindex mpcrel
-@opindex mno-pcrel
-Generate (do not generate) pc-relative addressing. The @option{-mpcrel}
-option requires that the medium code model (@option{-mcmodel=medium})
-and prefixed addressing (@option{-mprefixed}) options are enabled.
-
-@item -mprefixed
-@itemx -mno-prefixed
-@opindex mprefixed
-@opindex mno-prefixed
-Generate (do not generate) addressing modes using prefixed load and
-store instructions. The @option{-mprefixed} option requires that
-the option @option{-mcpu=power10} (or later) is enabled.
-
-@item -mmma
-@itemx -mno-mma
-@opindex mmma
-@opindex mno-mma
-Generate (do not generate) the MMA instructions. The @option{-mma}
-option requires that the option @option{-mcpu=power10} (or later)
-is enabled.
-
-@item -mrop-protect
-@itemx -mno-rop-protect
-@opindex mrop-protect
-@opindex mno-rop-protect
-Generate (do not generate) ROP protection instructions when the target
-processor supports them. Currently this option disables the shrink-wrap
-optimization (@option{-fshrink-wrap}).
-
-@item -mprivileged
-@itemx -mno-privileged
-@opindex mprivileged
-@opindex mno-privileged
-Generate (do not generate) code that will run in privileged state.
-
-@item -mblock-ops-unaligned-vsx
-@itemx -mno-block-ops-unaligned-vsx
-@opindex block-ops-unaligned-vsx
-@opindex no-block-ops-unaligned-vsx
-Generate (do not generate) unaligned vsx loads and stores for
-inline expansion of @code{memcpy} and @code{memmove}.
-
-@item --param rs6000-vect-unroll-limit=
-The vectorizer will check with target information to determine whether it
-would be beneficial to unroll the main vectorized loop and by how much. This
-parameter sets the upper bound of how much the vectorizer will unroll the main
-loop. The default value is four.
-
-@end table
-
-@node RX Options
-@subsection RX Options
-@cindex RX Options
-
-These command-line options are defined for RX targets:
-
-@table @gcctabopt
-@item -m64bit-doubles
-@itemx -m32bit-doubles
-@opindex m64bit-doubles
-@opindex m32bit-doubles
-Make the @code{double} data type be 64 bits (@option{-m64bit-doubles})
-or 32 bits (@option{-m32bit-doubles}) in size. The default is
-@option{-m32bit-doubles}. @emph{Note} RX floating-point hardware only
-works on 32-bit values, which is why the default is
-@option{-m32bit-doubles}.
-
-@item -fpu
-@itemx -nofpu
-@opindex fpu
-@opindex nofpu
-Enables (@option{-fpu}) or disables (@option{-nofpu}) the use of RX
-floating-point hardware. The default is enabled for the RX600
-series and disabled for the RX200 series.
-
-Floating-point instructions are only generated for 32-bit floating-point
-values, however, so the FPU hardware is not used for doubles if the
-@option{-m64bit-doubles} option is used.
-
-@emph{Note} If the @option{-fpu} option is enabled then
-@option{-funsafe-math-optimizations} is also enabled automatically.
-This is because the RX FPU instructions are themselves unsafe.
-
-@item -mcpu=@var{name}
-@opindex mcpu
-Selects the type of RX CPU to be targeted. Currently three types are
-supported, the generic @samp{RX600} and @samp{RX200} series hardware and
-the specific @samp{RX610} CPU. The default is @samp{RX600}.
-
-The only difference between @samp{RX600} and @samp{RX610} is that the
-@samp{RX610} does not support the @code{MVTIPL} instruction.
-
-The @samp{RX200} series does not have a hardware floating-point unit
-and so @option{-nofpu} is enabled by default when this type is
-selected.
-
-@item -mbig-endian-data
-@itemx -mlittle-endian-data
-@opindex mbig-endian-data
-@opindex mlittle-endian-data
-Store data (but not code) in the big-endian format. The default is
-@option{-mlittle-endian-data}, i.e.@: to store data in the little-endian
-format.
-
-@item -msmall-data-limit=@var{N}
-@opindex msmall-data-limit
-Specifies the maximum size in bytes of global and static variables
-which can be placed into the small data area. Using the small data
-area can lead to smaller and faster code, but the size of area is
-limited and it is up to the programmer to ensure that the area does
-not overflow. Also when the small data area is used one of the RX's
-registers (usually @code{r13}) is reserved for use pointing to this
-area, so it is no longer available for use by the compiler. This
-could result in slower and/or larger code if variables are pushed onto
-the stack instead of being held in this register.
-
-Note, common variables (variables that have not been initialized) and
-constants are not placed into the small data area as they are assigned
-to other sections in the output executable.
-
-The default value is zero, which disables this feature. Note, this
-feature is not enabled by default with higher optimization levels
-(@option{-O2} etc) because of the potentially detrimental effects of
-reserving a register. It is up to the programmer to experiment and
-discover whether this feature is of benefit to their program. See the
-description of the @option{-mpid} option for a description of how the
-actual register to hold the small data area pointer is chosen.
-
-@item -msim
-@itemx -mno-sim
-@opindex msim
-@opindex mno-sim
-Use the simulator runtime. The default is to use the libgloss
-board-specific runtime.
-
-@item -mas100-syntax
-@itemx -mno-as100-syntax
-@opindex mas100-syntax
-@opindex mno-as100-syntax
-When generating assembler output use a syntax that is compatible with
-Renesas's AS100 assembler. This syntax can also be handled by the GAS
-assembler, but it has some restrictions so it is not generated by default.
-
-@item -mmax-constant-size=@var{N}
-@opindex mmax-constant-size
-Specifies the maximum size, in bytes, of a constant that can be used as
-an operand in a RX instruction. Although the RX instruction set does
-allow constants of up to 4 bytes in length to be used in instructions,
-a longer value equates to a longer instruction. Thus in some
-circumstances it can be beneficial to restrict the size of constants
-that are used in instructions. Constants that are too big are instead
-placed into a constant pool and referenced via register indirection.
-
-The value @var{N} can be between 0 and 4. A value of 0 (the default)
-or 4 means that constants of any size are allowed.
-
-@item -mrelax
-@opindex mrelax
-Enable linker relaxation. Linker relaxation is a process whereby the
-linker attempts to reduce the size of a program by finding shorter
-versions of various instructions. Disabled by default.
-
-@item -mint-register=@var{N}
-@opindex mint-register
-Specify the number of registers to reserve for fast interrupt handler
-functions. The value @var{N} can be between 0 and 4. A value of 1
-means that register @code{r13} is reserved for the exclusive use
-of fast interrupt handlers. A value of 2 reserves @code{r13} and
-@code{r12}. A value of 3 reserves @code{r13}, @code{r12} and
-@code{r11}, and a value of 4 reserves @code{r13} through @code{r10}.
-A value of 0, the default, does not reserve any registers.
-
-@item -msave-acc-in-interrupts
-@opindex msave-acc-in-interrupts
-Specifies that interrupt handler functions should preserve the
-accumulator register. This is only necessary if normal code might use
-the accumulator register, for example because it performs 64-bit
-multiplications. The default is to ignore the accumulator as this
-makes the interrupt handlers faster.
-
-@item -mpid
-@itemx -mno-pid
-@opindex mpid
-@opindex mno-pid
-Enables the generation of position independent data. When enabled any
-access to constant data is done via an offset from a base address
-held in a register. This allows the location of constant data to be
-determined at run time without requiring the executable to be
-relocated, which is a benefit to embedded applications with tight
-memory constraints. Data that can be modified is not affected by this
-option.
-
-Note, using this feature reserves a register, usually @code{r13}, for
-the constant data base address. This can result in slower and/or
-larger code, especially in complicated functions.
-
-The actual register chosen to hold the constant data base address
-depends upon whether the @option{-msmall-data-limit} and/or the
-@option{-mint-register} command-line options are enabled. Starting
-with register @code{r13} and proceeding downwards, registers are
-allocated first to satisfy the requirements of @option{-mint-register},
-then @option{-mpid} and finally @option{-msmall-data-limit}. Thus it
-is possible for the small data area register to be @code{r8} if both
-@option{-mint-register=4} and @option{-mpid} are specified on the
-command line.
-
-By default this feature is not enabled. The default can be restored
-via the @option{-mno-pid} command-line option.
-
-@item -mno-warn-multiple-fast-interrupts
-@itemx -mwarn-multiple-fast-interrupts
-@opindex mno-warn-multiple-fast-interrupts
-@opindex mwarn-multiple-fast-interrupts
-Prevents GCC from issuing a warning message if it finds more than one
-fast interrupt handler when it is compiling a file. The default is to
-issue a warning for each extra fast interrupt handler found, as the RX
-only supports one such interrupt.
-
-@item -mallow-string-insns
-@itemx -mno-allow-string-insns
-@opindex mallow-string-insns
-@opindex mno-allow-string-insns
-Enables or disables the use of the string manipulation instructions
-@code{SMOVF}, @code{SCMPU}, @code{SMOVB}, @code{SMOVU}, @code{SUNTIL}
-@code{SWHILE} and also the @code{RMPA} instruction. These
-instructions may prefetch data, which is not safe to do if accessing
-an I/O register. (See section 12.2.7 of the RX62N Group User's Manual
-for more information).
-
-The default is to allow these instructions, but it is not possible for
-GCC to reliably detect all circumstances where a string instruction
-might be used to access an I/O register, so their use cannot be
-disabled automatically. Instead it is reliant upon the programmer to
-use the @option{-mno-allow-string-insns} option if their program
-accesses I/O space.
-
-When the instructions are enabled GCC defines the C preprocessor
-symbol @code{__RX_ALLOW_STRING_INSNS__}, otherwise it defines the
-symbol @code{__RX_DISALLOW_STRING_INSNS__}.
-
-@item -mjsr
-@itemx -mno-jsr
-@opindex mjsr
-@opindex mno-jsr
-Use only (or not only) @code{JSR} instructions to access functions.
-This option can be used when code size exceeds the range of @code{BSR}
-instructions. Note that @option{-mno-jsr} does not mean to not use
-@code{JSR} but instead means that any type of branch may be used.
-@end table
-
-@emph{Note:} The generic GCC command-line option @option{-ffixed-@var{reg}}
-has special significance to the RX port when used with the
-@code{interrupt} function attribute. This attribute indicates a
-function intended to process fast interrupts. GCC ensures
-that it only uses the registers @code{r10}, @code{r11}, @code{r12}
-and/or @code{r13} and only provided that the normal use of the
-corresponding registers have been restricted via the
-@option{-ffixed-@var{reg}} or @option{-mint-register} command-line
-options.
-
-@node S/390 and zSeries Options
-@subsection S/390 and zSeries Options
-@cindex S/390 and zSeries Options
-
-These are the @samp{-m} options defined for the S/390 and zSeries architecture.
-
-@table @gcctabopt
-@item -mhard-float
-@itemx -msoft-float
-@opindex mhard-float
-@opindex msoft-float
-Use (do not use) the hardware floating-point instructions and registers
-for floating-point operations. When @option{-msoft-float} is specified,
-functions in @file{libgcc.a} are used to perform floating-point
-operations. When @option{-mhard-float} is specified, the compiler
-generates IEEE floating-point instructions. This is the default.
-
-@item -mhard-dfp
-@itemx -mno-hard-dfp
-@opindex mhard-dfp
-@opindex mno-hard-dfp
-Use (do not use) the hardware decimal-floating-point instructions for
-decimal-floating-point operations. When @option{-mno-hard-dfp} is
-specified, functions in @file{libgcc.a} are used to perform
-decimal-floating-point operations. When @option{-mhard-dfp} is
-specified, the compiler generates decimal-floating-point hardware
-instructions. This is the default for @option{-march=z9-ec} or higher.
-
-@item -mlong-double-64
-@itemx -mlong-double-128
-@opindex mlong-double-64
-@opindex mlong-double-128
-These switches control the size of @code{long double} type. A size
-of 64 bits makes the @code{long double} type equivalent to the @code{double}
-type. This is the default.
-
-@item -mbackchain
-@itemx -mno-backchain
-@opindex mbackchain
-@opindex mno-backchain
-Store (do not store) the address of the caller's frame as backchain pointer
-into the callee's stack frame.
-A backchain may be needed to allow debugging using tools that do not understand
-DWARF call frame information.
-When @option{-mno-packed-stack} is in effect, the backchain pointer is stored
-at the bottom of the stack frame; when @option{-mpacked-stack} is in effect,
-the backchain is placed into the topmost word of the 96/160 byte register
-save area.
-
-In general, code compiled with @option{-mbackchain} is call-compatible with
-code compiled with @option{-mno-backchain}; however, use of the backchain
-for debugging purposes usually requires that the whole binary is built with
-@option{-mbackchain}. Note that the combination of @option{-mbackchain},
-@option{-mpacked-stack} and @option{-mhard-float} is not supported. In order
-to build a linux kernel use @option{-msoft-float}.
-
-The default is to not maintain the backchain.
-
-@item -mpacked-stack
-@itemx -mno-packed-stack
-@opindex mpacked-stack
-@opindex mno-packed-stack
-Use (do not use) the packed stack layout. When @option{-mno-packed-stack} is
-specified, the compiler uses the all fields of the 96/160 byte register save
-area only for their default purpose; unused fields still take up stack space.
-When @option{-mpacked-stack} is specified, register save slots are densely
-packed at the top of the register save area; unused space is reused for other
-purposes, allowing for more efficient use of the available stack space.
-However, when @option{-mbackchain} is also in effect, the topmost word of
-the save area is always used to store the backchain, and the return address
-register is always saved two words below the backchain.
-
-As long as the stack frame backchain is not used, code generated with
-@option{-mpacked-stack} is call-compatible with code generated with
-@option{-mno-packed-stack}. Note that some non-FSF releases of GCC 2.95 for
-S/390 or zSeries generated code that uses the stack frame backchain at run
-time, not just for debugging purposes. Such code is not call-compatible
-with code compiled with @option{-mpacked-stack}. Also, note that the
-combination of @option{-mbackchain},
-@option{-mpacked-stack} and @option{-mhard-float} is not supported. In order
-to build a linux kernel use @option{-msoft-float}.
-
-The default is to not use the packed stack layout.
-
-@item -msmall-exec
-@itemx -mno-small-exec
-@opindex msmall-exec
-@opindex mno-small-exec
-Generate (or do not generate) code using the @code{bras} instruction
-to do subroutine calls.
-This only works reliably if the total executable size does not
-exceed 64k. The default is to use the @code{basr} instruction instead,
-which does not have this limitation.
-
-@item -m64
-@itemx -m31
-@opindex m64
-@opindex m31
-When @option{-m31} is specified, generate code compliant to the
-GNU/Linux for S/390 ABI@. When @option{-m64} is specified, generate
-code compliant to the GNU/Linux for zSeries ABI@. This allows GCC in
-particular to generate 64-bit instructions. For the @samp{s390}
-targets, the default is @option{-m31}, while the @samp{s390x}
-targets default to @option{-m64}.
-
-@item -mzarch
-@itemx -mesa
-@opindex mzarch
-@opindex mesa
-When @option{-mzarch} is specified, generate code using the
-instructions available on z/Architecture.
-When @option{-mesa} is specified, generate code using the
-instructions available on ESA/390. Note that @option{-mesa} is
-not possible with @option{-m64}.
-When generating code compliant to the GNU/Linux for S/390 ABI,
-the default is @option{-mesa}. When generating code compliant
-to the GNU/Linux for zSeries ABI, the default is @option{-mzarch}.
-
-@item -mhtm
-@itemx -mno-htm
-@opindex mhtm
-@opindex mno-htm
-The @option{-mhtm} option enables a set of builtins making use of
-instructions available with the transactional execution facility
-introduced with the IBM zEnterprise EC12 machine generation
-@ref{S/390 System z Built-in Functions}.
-@option{-mhtm} is enabled by default when using @option{-march=zEC12}.
-
-@item -mvx
-@itemx -mno-vx
-@opindex mvx
-@opindex mno-vx
-When @option{-mvx} is specified, generate code using the instructions
-available with the vector extension facility introduced with the IBM
-z13 machine generation.
-This option changes the ABI for some vector type values with regard to
-alignment and calling conventions. In case vector type values are
-being used in an ABI-relevant context a GAS @samp{.gnu_attribute}
-command will be added to mark the resulting binary with the ABI used.
-@option{-mvx} is enabled by default when using @option{-march=z13}.
-
-@item -mzvector
-@itemx -mno-zvector
-@opindex mzvector
-@opindex mno-zvector
-The @option{-mzvector} option enables vector language extensions and
-builtins using instructions available with the vector extension
-facility introduced with the IBM z13 machine generation.
-This option adds support for @samp{vector} to be used as a keyword to
-define vector type variables and arguments. @samp{vector} is only
-available when GNU extensions are enabled. It will not be expanded
-when requesting strict standard compliance e.g.@: with @option{-std=c99}.
-In addition to the GCC low-level builtins @option{-mzvector} enables
-a set of builtins added for compatibility with AltiVec-style
-implementations like Power and Cell. In order to make use of these
-builtins the header file @file{vecintrin.h} needs to be included.
-@option{-mzvector} is disabled by default.
-
-@item -mmvcle
-@itemx -mno-mvcle
-@opindex mmvcle
-@opindex mno-mvcle
-Generate (or do not generate) code using the @code{mvcle} instruction
-to perform block moves. When @option{-mno-mvcle} is specified,
-use a @code{mvc} loop instead. This is the default unless optimizing for
-size.
-
-@item -mdebug
-@itemx -mno-debug
-@opindex mdebug
-@opindex mno-debug
-Print (or do not print) additional debug information when compiling.
-The default is to not print debug information.
-
-@item -march=@var{cpu-type}
-@opindex march
-Generate code that runs on @var{cpu-type}, which is the name of a
-system representing a certain processor type. Possible values for
-@var{cpu-type} are @samp{z900}/@samp{arch5}, @samp{z990}/@samp{arch6},
-@samp{z9-109}, @samp{z9-ec}/@samp{arch7}, @samp{z10}/@samp{arch8},
-@samp{z196}/@samp{arch9}, @samp{zEC12}, @samp{z13}/@samp{arch11},
-@samp{z14}/@samp{arch12}, @samp{z15}/@samp{arch13},
-@samp{z16}/@samp{arch14}, and @samp{native}.
-
-The default is @option{-march=z900}.
-
-Specifying @samp{native} as cpu type can be used to select the best
-architecture option for the host processor.
-@option{-march=native} has no effect if GCC does not recognize the
-processor.
-
-@item -mtune=@var{cpu-type}
-@opindex mtune
-Tune to @var{cpu-type} everything applicable about the generated code,
-except for the ABI and the set of available instructions.
-The list of @var{cpu-type} values is the same as for @option{-march}.
-The default is the value used for @option{-march}.
-
-@item -mtpf-trace
-@itemx -mno-tpf-trace
-@opindex mtpf-trace
-@opindex mno-tpf-trace
-Generate code that adds (does not add) in TPF OS specific branches to trace
-routines in the operating system. This option is off by default, even
-when compiling for the TPF OS@.
-
-@item -mtpf-trace-skip
-@itemx -mno-tpf-trace-skip
-@opindex mtpf-trace-skip
-@opindex mno-tpf-trace-skip
-Generate code that changes (does not change) the default branch
-targets enabled by @option{-mtpf-trace} to point to specialized trace
-routines providing the ability of selectively skipping function trace
-entries for the TPF OS. This option is off by default, even when
-compiling for the TPF OS and specifying @option{-mtpf-trace}.
-
-@item -mfused-madd
-@itemx -mno-fused-madd
-@opindex mfused-madd
-@opindex mno-fused-madd
-Generate code that uses (does not use) the floating-point multiply and
-accumulate instructions. These instructions are generated by default if
-hardware floating point is used.
-
-@item -mwarn-framesize=@var{framesize}
-@opindex mwarn-framesize
-Emit a warning if the current function exceeds the given frame size. Because
-this is a compile-time check it doesn't need to be a real problem when the program
-runs. It is intended to identify functions that most probably cause
-a stack overflow. It is useful to be used in an environment with limited stack
-size e.g.@: the linux kernel.
-
-@item -mwarn-dynamicstack
-@opindex mwarn-dynamicstack
-Emit a warning if the function calls @code{alloca} or uses dynamically-sized
-arrays. This is generally a bad idea with a limited stack size.
-
-@item -mstack-guard=@var{stack-guard}
-@itemx -mstack-size=@var{stack-size}
-@opindex mstack-guard
-@opindex mstack-size
-If these options are provided the S/390 back end emits additional instructions in
-the function prologue that trigger a trap if the stack size is @var{stack-guard}
-bytes above the @var{stack-size} (remember that the stack on S/390 grows downward).
-If the @var{stack-guard} option is omitted the smallest power of 2 larger than
-the frame size of the compiled function is chosen.
-These options are intended to be used to help debugging stack overflow problems.
-The additionally emitted code causes only little overhead and hence can also be
-used in production-like systems without greater performance degradation. The given
-values have to be exact powers of 2 and @var{stack-size} has to be greater than
-@var{stack-guard} without exceeding 64k.
-In order to be efficient the extra code makes the assumption that the stack starts
-at an address aligned to the value given by @var{stack-size}.
-The @var{stack-guard} option can only be used in conjunction with @var{stack-size}.
-
-@item -mhotpatch=@var{pre-halfwords},@var{post-halfwords}
-@opindex mhotpatch
-If the hotpatch option is enabled, a ``hot-patching'' function
-prologue is generated for all functions in the compilation unit.
-The funtion label is prepended with the given number of two-byte
-NOP instructions (@var{pre-halfwords}, maximum 1000000). After
-the label, 2 * @var{post-halfwords} bytes are appended, using the
-largest NOP like instructions the architecture allows (maximum
-1000000).
-
-If both arguments are zero, hotpatching is disabled.
-
-This option can be overridden for individual functions with the
-@code{hotpatch} attribute.
-@end table
-
-@node Score Options
-@subsection Score Options
-@cindex Score Options
-
-These options are defined for Score implementations:
-
-@table @gcctabopt
-@item -meb
-@opindex meb
-Compile code for big-endian mode. This is the default.
-
-@item -mel
-@opindex mel
-Compile code for little-endian mode.
-
-@item -mnhwloop
-@opindex mnhwloop
-Disable generation of @code{bcnz} instructions.
-
-@item -muls
-@opindex muls
-Enable generation of unaligned load and store instructions.
-
-@item -mmac
-@opindex mmac
-Enable the use of multiply-accumulate instructions. Disabled by default.
-
-@item -mscore5
-@opindex mscore5
-Specify the SCORE5 as the target architecture.
-
-@item -mscore5u
-@opindex mscore5u
-Specify the SCORE5U of the target architecture.
-
-@item -mscore7
-@opindex mscore7
-Specify the SCORE7 as the target architecture. This is the default.
-
-@item -mscore7d
-@opindex mscore7d
-Specify the SCORE7D as the target architecture.
-@end table
-
-@node SH Options
-@subsection SH Options
-
-These @samp{-m} options are defined for the SH implementations:
-
-@table @gcctabopt
-@item -m1
-@opindex m1
-Generate code for the SH1.
-
-@item -m2
-@opindex m2
-Generate code for the SH2.
-
-@item -m2e
-Generate code for the SH2e.
-
-@item -m2a-nofpu
-@opindex m2a-nofpu
-Generate code for the SH2a without FPU, or for a SH2a-FPU in such a way
-that the floating-point unit is not used.
-
-@item -m2a-single-only
-@opindex m2a-single-only
-Generate code for the SH2a-FPU, in such a way that no double-precision
-floating-point operations are used.
-
-@item -m2a-single
-@opindex m2a-single
-Generate code for the SH2a-FPU assuming the floating-point unit is in
-single-precision mode by default.
-
-@item -m2a
-@opindex m2a
-Generate code for the SH2a-FPU assuming the floating-point unit is in
-double-precision mode by default.
-
-@item -m3
-@opindex m3
-Generate code for the SH3.
-
-@item -m3e
-@opindex m3e
-Generate code for the SH3e.
-
-@item -m4-nofpu
-@opindex m4-nofpu
-Generate code for the SH4 without a floating-point unit.
-
-@item -m4-single-only
-@opindex m4-single-only
-Generate code for the SH4 with a floating-point unit that only
-supports single-precision arithmetic.
-
-@item -m4-single
-@opindex m4-single
-Generate code for the SH4 assuming the floating-point unit is in
-single-precision mode by default.
-
-@item -m4
-@opindex m4
-Generate code for the SH4.
-
-@item -m4-100
-@opindex m4-100
-Generate code for SH4-100.
-
-@item -m4-100-nofpu
-@opindex m4-100-nofpu
-Generate code for SH4-100 in such a way that the
-floating-point unit is not used.
-
-@item -m4-100-single
-@opindex m4-100-single
-Generate code for SH4-100 assuming the floating-point unit is in
-single-precision mode by default.
-
-@item -m4-100-single-only
-@opindex m4-100-single-only
-Generate code for SH4-100 in such a way that no double-precision
-floating-point operations are used.
-
-@item -m4-200
-@opindex m4-200
-Generate code for SH4-200.
-
-@item -m4-200-nofpu
-@opindex m4-200-nofpu
-Generate code for SH4-200 without in such a way that the
-floating-point unit is not used.
-
-@item -m4-200-single
-@opindex m4-200-single
-Generate code for SH4-200 assuming the floating-point unit is in
-single-precision mode by default.
-
-@item -m4-200-single-only
-@opindex m4-200-single-only
-Generate code for SH4-200 in such a way that no double-precision
-floating-point operations are used.
-
-@item -m4-300
-@opindex m4-300
-Generate code for SH4-300.
-
-@item -m4-300-nofpu
-@opindex m4-300-nofpu
-Generate code for SH4-300 without in such a way that the
-floating-point unit is not used.
-
-@item -m4-300-single
-@opindex m4-300-single
-Generate code for SH4-300 in such a way that no double-precision
-floating-point operations are used.
-
-@item -m4-300-single-only
-@opindex m4-300-single-only
-Generate code for SH4-300 in such a way that no double-precision
-floating-point operations are used.
-
-@item -m4-340
-@opindex m4-340
-Generate code for SH4-340 (no MMU, no FPU).
-
-@item -m4-500
-@opindex m4-500
-Generate code for SH4-500 (no FPU). Passes @option{-isa=sh4-nofpu} to the
-assembler.
-
-@item -m4a-nofpu
-@opindex m4a-nofpu
-Generate code for the SH4al-dsp, or for a SH4a in such a way that the
-floating-point unit is not used.
-
-@item -m4a-single-only
-@opindex m4a-single-only
-Generate code for the SH4a, in such a way that no double-precision
-floating-point operations are used.
-
-@item -m4a-single
-@opindex m4a-single
-Generate code for the SH4a assuming the floating-point unit is in
-single-precision mode by default.
-
-@item -m4a
-@opindex m4a
-Generate code for the SH4a.
-
-@item -m4al
-@opindex m4al
-Same as @option{-m4a-nofpu}, except that it implicitly passes
-@option{-dsp} to the assembler. GCC doesn't generate any DSP
-instructions at the moment.
-
-@item -mb
-@opindex mb
-Compile code for the processor in big-endian mode.
-
-@item -ml
-@opindex ml
-Compile code for the processor in little-endian mode.
-
-@item -mdalign
-@opindex mdalign
-Align doubles at 64-bit boundaries. Note that this changes the calling
-conventions, and thus some functions from the standard C library do
-not work unless you recompile it first with @option{-mdalign}.
-
-@item -mrelax
-@opindex mrelax
-Shorten some address references at link time, when possible; uses the
-linker option @option{-relax}.
-
-@item -mbigtable
-@opindex mbigtable
-Use 32-bit offsets in @code{switch} tables. The default is to use
-16-bit offsets.
-
-@item -mbitops
-@opindex mbitops
-Enable the use of bit manipulation instructions on SH2A.
-
-@item -mfmovd
-@opindex mfmovd
-Enable the use of the instruction @code{fmovd}. Check @option{-mdalign} for
-alignment constraints.
-
-@item -mrenesas
-@opindex mrenesas
-Comply with the calling conventions defined by Renesas.
-
-@item -mno-renesas
-@opindex mno-renesas
-Comply with the calling conventions defined for GCC before the Renesas
-conventions were available. This option is the default for all
-targets of the SH toolchain.
-
-@item -mnomacsave
-@opindex mnomacsave
-Mark the @code{MAC} register as call-clobbered, even if
-@option{-mrenesas} is given.
-
-@item -mieee
-@itemx -mno-ieee
-@opindex mieee
-@opindex mno-ieee
-Control the IEEE compliance of floating-point comparisons, which affects the
-handling of cases where the result of a comparison is unordered. By default
-@option{-mieee} is implicitly enabled. If @option{-ffinite-math-only} is
-enabled @option{-mno-ieee} is implicitly set, which results in faster
-floating-point greater-equal and less-equal comparisons. The implicit settings
-can be overridden by specifying either @option{-mieee} or @option{-mno-ieee}.
-
-@item -minline-ic_invalidate
-@opindex minline-ic_invalidate
-Inline code to invalidate instruction cache entries after setting up
-nested function trampolines.
-This option has no effect if @option{-musermode} is in effect and the selected
-code generation option (e.g.@: @option{-m4}) does not allow the use of the @code{icbi}
-instruction.
-If the selected code generation option does not allow the use of the @code{icbi}
-instruction, and @option{-musermode} is not in effect, the inlined code
-manipulates the instruction cache address array directly with an associative
-write. This not only requires privileged mode at run time, but it also
-fails if the cache line had been mapped via the TLB and has become unmapped.
-
-@item -misize
-@opindex misize
-Dump instruction size and location in the assembly code.
-
-@item -mpadstruct
-@opindex mpadstruct
-This option is deprecated. It pads structures to multiple of 4 bytes,
-which is incompatible with the SH ABI@.
-
-@item -matomic-model=@var{model}
-@opindex matomic-model=@var{model}
-Sets the model of atomic operations and additional parameters as a comma
-separated list. For details on the atomic built-in functions see
-@ref{__atomic Builtins}. The following models and parameters are supported:
-
-@table @samp
-
-@item none
-Disable compiler generated atomic sequences and emit library calls for atomic
-operations. This is the default if the target is not @code{sh*-*-linux*}.
-
-@item soft-gusa
-Generate GNU/Linux compatible gUSA software atomic sequences for the atomic
-built-in functions. The generated atomic sequences require additional support
-from the interrupt/exception handling code of the system and are only suitable
-for SH3* and SH4* single-core systems. This option is enabled by default when
-the target is @code{sh*-*-linux*} and SH3* or SH4*. When the target is SH4A,
-this option also partially utilizes the hardware atomic instructions
-@code{movli.l} and @code{movco.l} to create more efficient code, unless
-@samp{strict} is specified.
-
-@item soft-tcb
-Generate software atomic sequences that use a variable in the thread control
-block. This is a variation of the gUSA sequences which can also be used on
-SH1* and SH2* targets. The generated atomic sequences require additional
-support from the interrupt/exception handling code of the system and are only
-suitable for single-core systems. When using this model, the @samp{gbr-offset=}
-parameter has to be specified as well.
-
-@item soft-imask
-Generate software atomic sequences that temporarily disable interrupts by
-setting @code{SR.IMASK = 1111}. This model works only when the program runs
-in privileged mode and is only suitable for single-core systems. Additional
-support from the interrupt/exception handling code of the system is not
-required. This model is enabled by default when the target is
-@code{sh*-*-linux*} and SH1* or SH2*.
-
-@item hard-llcs
-Generate hardware atomic sequences using the @code{movli.l} and @code{movco.l}
-instructions only. This is only available on SH4A and is suitable for
-multi-core systems. Since the hardware instructions support only 32 bit atomic
-variables access to 8 or 16 bit variables is emulated with 32 bit accesses.
-Code compiled with this option is also compatible with other software
-atomic model interrupt/exception handling systems if executed on an SH4A
-system. Additional support from the interrupt/exception handling code of the
-system is not required for this model.
-
-@item gbr-offset=
-This parameter specifies the offset in bytes of the variable in the thread
-control block structure that should be used by the generated atomic sequences
-when the @samp{soft-tcb} model has been selected. For other models this
-parameter is ignored. The specified value must be an integer multiple of four
-and in the range 0-1020.
-
-@item strict
-This parameter prevents mixed usage of multiple atomic models, even if they
-are compatible, and makes the compiler generate atomic sequences of the
-specified model only.
-
-@end table
-
-@item -mtas
-@opindex mtas
-Generate the @code{tas.b} opcode for @code{__atomic_test_and_set}.
-Notice that depending on the particular hardware and software configuration
-this can degrade overall performance due to the operand cache line flushes
-that are implied by the @code{tas.b} instruction. On multi-core SH4A
-processors the @code{tas.b} instruction must be used with caution since it
-can result in data corruption for certain cache configurations.
-
-@item -mprefergot
-@opindex mprefergot
-When generating position-independent code, emit function calls using
-the Global Offset Table instead of the Procedure Linkage Table.
-
-@item -musermode
-@itemx -mno-usermode
-@opindex musermode
-@opindex mno-usermode
-Don't allow (allow) the compiler generating privileged mode code. Specifying
-@option{-musermode} also implies @option{-mno-inline-ic_invalidate} if the
-inlined code would not work in user mode. @option{-musermode} is the default
-when the target is @code{sh*-*-linux*}. If the target is SH1* or SH2*
-@option{-musermode} has no effect, since there is no user mode.
-
-@item -multcost=@var{number}
-@opindex multcost=@var{number}
-Set the cost to assume for a multiply insn.
-
-@item -mdiv=@var{strategy}
-@opindex mdiv=@var{strategy}
-Set the division strategy to be used for integer division operations.
-@var{strategy} can be one of:
-
-@table @samp
-
-@item call-div1
-Calls a library function that uses the single-step division instruction
-@code{div1} to perform the operation. Division by zero calculates an
-unspecified result and does not trap. This is the default except for SH4,
-SH2A and SHcompact.
-
-@item call-fp
-Calls a library function that performs the operation in double precision
-floating point. Division by zero causes a floating-point exception. This is
-the default for SHcompact with FPU. Specifying this for targets that do not
-have a double precision FPU defaults to @code{call-div1}.
-
-@item call-table
-Calls a library function that uses a lookup table for small divisors and
-the @code{div1} instruction with case distinction for larger divisors. Division
-by zero calculates an unspecified result and does not trap. This is the default
-for SH4. Specifying this for targets that do not have dynamic shift
-instructions defaults to @code{call-div1}.
-
-@end table
-
-When a division strategy has not been specified the default strategy is
-selected based on the current target. For SH2A the default strategy is to
-use the @code{divs} and @code{divu} instructions instead of library function
-calls.
-
-@item -maccumulate-outgoing-args
-@opindex maccumulate-outgoing-args
-Reserve space once for outgoing arguments in the function prologue rather
-than around each call. Generally beneficial for performance and size. Also
-needed for unwinding to avoid changing the stack frame around conditional code.
-
-@item -mdivsi3_libfunc=@var{name}
-@opindex mdivsi3_libfunc=@var{name}
-Set the name of the library function used for 32-bit signed division to
-@var{name}.
-This only affects the name used in the @samp{call} division strategies, and
-the compiler still expects the same sets of input/output/clobbered registers as
-if this option were not present.
-
-@item -mfixed-range=@var{register-range}
-@opindex mfixed-range
-Generate code treating the given register range as fixed registers.
-A fixed register is one that the register allocator cannot use. This is
-useful when compiling kernel code. A register range is specified as
-two registers separated by a dash. Multiple register ranges can be
-specified separated by a comma.
-
-@item -mbranch-cost=@var{num}
-@opindex mbranch-cost=@var{num}
-Assume @var{num} to be the cost for a branch instruction. Higher numbers
-make the compiler try to generate more branch-free code if possible.
-If not specified the value is selected depending on the processor type that
-is being compiled for.
-
-@item -mzdcbranch
-@itemx -mno-zdcbranch
-@opindex mzdcbranch
-@opindex mno-zdcbranch
-Assume (do not assume) that zero displacement conditional branch instructions
-@code{bt} and @code{bf} are fast. If @option{-mzdcbranch} is specified, the
-compiler prefers zero displacement branch code sequences. This is
-enabled by default when generating code for SH4 and SH4A. It can be explicitly
-disabled by specifying @option{-mno-zdcbranch}.
-
-@item -mcbranch-force-delay-slot
-@opindex mcbranch-force-delay-slot
-Force the usage of delay slots for conditional branches, which stuffs the delay
-slot with a @code{nop} if a suitable instruction cannot be found. By default
-this option is disabled. It can be enabled to work around hardware bugs as
-found in the original SH7055.
-
-@item -mfused-madd
-@itemx -mno-fused-madd
-@opindex mfused-madd
-@opindex mno-fused-madd
-Generate code that uses (does not use) the floating-point multiply and
-accumulate instructions. These instructions are generated by default
-if hardware floating point is used. The machine-dependent
-@option{-mfused-madd} option is now mapped to the machine-independent
-@option{-ffp-contract=fast} option, and @option{-mno-fused-madd} is
-mapped to @option{-ffp-contract=off}.
-
-@item -mfsca
-@itemx -mno-fsca
-@opindex mfsca
-@opindex mno-fsca
-Allow or disallow the compiler to emit the @code{fsca} instruction for sine
-and cosine approximations. The option @option{-mfsca} must be used in
-combination with @option{-funsafe-math-optimizations}. It is enabled by default
-when generating code for SH4A. Using @option{-mno-fsca} disables sine and cosine
-approximations even if @option{-funsafe-math-optimizations} is in effect.
-
-@item -mfsrra
-@itemx -mno-fsrra
-@opindex mfsrra
-@opindex mno-fsrra
-Allow or disallow the compiler to emit the @code{fsrra} instruction for
-reciprocal square root approximations. The option @option{-mfsrra} must be used
-in combination with @option{-funsafe-math-optimizations} and
-@option{-ffinite-math-only}. It is enabled by default when generating code for
-SH4A. Using @option{-mno-fsrra} disables reciprocal square root approximations
-even if @option{-funsafe-math-optimizations} and @option{-ffinite-math-only} are
-in effect.
-
-@item -mpretend-cmove
-@opindex mpretend-cmove
-Prefer zero-displacement conditional branches for conditional move instruction
-patterns. This can result in faster code on the SH4 processor.
-
-@item -mfdpic
-@opindex fdpic
-Generate code using the FDPIC ABI.
-
-@end table
-
-@node Solaris 2 Options
-@subsection Solaris 2 Options
-@cindex Solaris 2 options
-
-These @samp{-m} options are supported on Solaris 2:
-
-@table @gcctabopt
-@item -mclear-hwcap
-@opindex mclear-hwcap
-@option{-mclear-hwcap} tells the compiler to remove the hardware
-capabilities generated by the Solaris assembler. This is only necessary
-when object files use ISA extensions not supported by the current
-machine, but check at runtime whether or not to use them.
-
-@item -mimpure-text
-@opindex mimpure-text
-@option{-mimpure-text}, used in addition to @option{-shared}, tells
-the compiler to not pass @option{-z text} to the linker when linking a
-shared object. Using this option, you can link position-dependent
-code into a shared object.
-
-@option{-mimpure-text} suppresses the ``relocations remain against
-allocatable but non-writable sections'' linker error message.
-However, the necessary relocations trigger copy-on-write, and the
-shared object is not actually shared across processes. Instead of
-using @option{-mimpure-text}, you should compile all source code with
-@option{-fpic} or @option{-fPIC}.
-
-@end table
-
-These switches are supported in addition to the above on Solaris 2:
-
-@table @gcctabopt
-@item -pthreads
-@opindex pthreads
-This is a synonym for @option{-pthread}.
-@end table
-
-@node SPARC Options
-@subsection SPARC Options
-@cindex SPARC options
-
-These @samp{-m} options are supported on the SPARC:
-
-@table @gcctabopt
-@item -mno-app-regs
-@itemx -mapp-regs
-@opindex mno-app-regs
-@opindex mapp-regs
-Specify @option{-mapp-regs} to generate output using the global registers
-2 through 4, which the SPARC SVR4 ABI reserves for applications. Like the
-global register 1, each global register 2 through 4 is then treated as an
-allocable register that is clobbered by function calls. This is the default.
-
-To be fully SVR4 ABI-compliant at the cost of some performance loss,
-specify @option{-mno-app-regs}. You should compile libraries and system
-software with this option.
-
-@item -mflat
-@itemx -mno-flat
-@opindex mflat
-@opindex mno-flat
-With @option{-mflat}, the compiler does not generate save/restore instructions
-and uses a ``flat'' or single register window model. This model is compatible
-with the regular register window model. The local registers and the input
-registers (0--5) are still treated as ``call-saved'' registers and are
-saved on the stack as needed.
-
-With @option{-mno-flat} (the default), the compiler generates save/restore
-instructions (except for leaf functions). This is the normal operating mode.
-
-@item -mfpu
-@itemx -mhard-float
-@opindex mfpu
-@opindex mhard-float
-Generate output containing floating-point instructions. This is the
-default.
-
-@item -mno-fpu
-@itemx -msoft-float
-@opindex mno-fpu
-@opindex msoft-float
-Generate output containing library calls for floating point.
-@strong{Warning:} the requisite libraries are not available for all SPARC
-targets. Normally the facilities of the machine's usual C compiler are
-used, but this cannot be done directly in cross-compilation. You must make
-your own arrangements to provide suitable library functions for
-cross-compilation. The embedded targets @samp{sparc-*-aout} and
-@samp{sparclite-*-*} do provide software floating-point support.
-
-@option{-msoft-float} changes the calling convention in the output file;
-therefore, it is only useful if you compile @emph{all} of a program with
-this option. In particular, you need to compile @file{libgcc.a}, the
-library that comes with GCC, with @option{-msoft-float} in order for
-this to work.
-
-@item -mhard-quad-float
-@opindex mhard-quad-float
-Generate output containing quad-word (long double) floating-point
-instructions.
-
-@item -msoft-quad-float
-@opindex msoft-quad-float
-Generate output containing library calls for quad-word (long double)
-floating-point instructions. The functions called are those specified
-in the SPARC ABI@. This is the default.
-
-As of this writing, there are no SPARC implementations that have hardware
-support for the quad-word floating-point instructions. They all invoke
-a trap handler for one of these instructions, and then the trap handler
-emulates the effect of the instruction. Because of the trap handler overhead,
-this is much slower than calling the ABI library routines. Thus the
-@option{-msoft-quad-float} option is the default.
-
-@item -mno-unaligned-doubles
-@itemx -munaligned-doubles
-@opindex mno-unaligned-doubles
-@opindex munaligned-doubles
-Assume that doubles have 8-byte alignment. This is the default.
-
-With @option{-munaligned-doubles}, GCC assumes that doubles have 8-byte
-alignment only if they are contained in another type, or if they have an
-absolute address. Otherwise, it assumes they have 4-byte alignment.
-Specifying this option avoids some rare compatibility problems with code
-generated by other compilers. It is not the default because it results
-in a performance loss, especially for floating-point code.
-
-@item -muser-mode
-@itemx -mno-user-mode
-@opindex muser-mode
-@opindex mno-user-mode
-Do not generate code that can only run in supervisor mode. This is relevant
-only for the @code{casa} instruction emitted for the LEON3 processor. This
-is the default.
-
-@item -mfaster-structs
-@itemx -mno-faster-structs
-@opindex mfaster-structs
-@opindex mno-faster-structs
-With @option{-mfaster-structs}, the compiler assumes that structures
-should have 8-byte alignment. This enables the use of pairs of
-@code{ldd} and @code{std} instructions for copies in structure
-assignment, in place of twice as many @code{ld} and @code{st} pairs.
-However, the use of this changed alignment directly violates the SPARC
-ABI@. Thus, it's intended only for use on targets where the developer
-acknowledges that their resulting code is not directly in line with
-the rules of the ABI@.
-
-@item -mstd-struct-return
-@itemx -mno-std-struct-return
-@opindex mstd-struct-return
-@opindex mno-std-struct-return
-With @option{-mstd-struct-return}, the compiler generates checking code
-in functions returning structures or unions to detect size mismatches
-between the two sides of function calls, as per the 32-bit ABI@.
-
-The default is @option{-mno-std-struct-return}. This option has no effect
-in 64-bit mode.
-
-@item -mlra
-@itemx -mno-lra
-@opindex mlra
-@opindex mno-lra
-Enable Local Register Allocation. This is the default for SPARC since GCC 7
-so @option{-mno-lra} needs to be passed to get old Reload.
-
-@item -mcpu=@var{cpu_type}
-@opindex mcpu
-Set the instruction set, register set, and instruction scheduling parameters
-for machine type @var{cpu_type}. Supported values for @var{cpu_type} are
-@samp{v7}, @samp{cypress}, @samp{v8}, @samp{supersparc}, @samp{hypersparc},
-@samp{leon}, @samp{leon3}, @samp{leon3v7}, @samp{leon5}, @samp{sparclite},
-@samp{f930}, @samp{f934}, @samp{sparclite86x}, @samp{sparclet}, @samp{tsc701},
-@samp{v9}, @samp{ultrasparc}, @samp{ultrasparc3}, @samp{niagara},
-@samp{niagara2}, @samp{niagara3}, @samp{niagara4}, @samp{niagara7} and
-@samp{m8}.
-
-Native Solaris and GNU/Linux toolchains also support the value @samp{native},
-which selects the best architecture option for the host processor.
-@option{-mcpu=native} has no effect if GCC does not recognize
-the processor.
-
-Default instruction scheduling parameters are used for values that select
-an architecture and not an implementation. These are @samp{v7}, @samp{v8},
-@samp{sparclite}, @samp{sparclet}, @samp{v9}.
-
-Here is a list of each supported architecture and their supported
-implementations.
-
-@table @asis
-@item v7
-cypress, leon3v7
-
-@item v8
-supersparc, hypersparc, leon, leon3, leon5
-
-@item sparclite
-f930, f934, sparclite86x
-
-@item sparclet
-tsc701
-
-@item v9
-ultrasparc, ultrasparc3, niagara, niagara2, niagara3, niagara4,
-niagara7, m8
-@end table
-
-By default (unless configured otherwise), GCC generates code for the V7
-variant of the SPARC architecture. With @option{-mcpu=cypress}, the compiler
-additionally optimizes it for the Cypress CY7C602 chip, as used in the
-SPARCStation/SPARCServer 3xx series. This is also appropriate for the older
-SPARCStation 1, 2, IPX etc.
-
-With @option{-mcpu=v8}, GCC generates code for the V8 variant of the SPARC
-architecture. The only difference from V7 code is that the compiler emits
-the integer multiply and integer divide instructions which exist in SPARC-V8
-but not in SPARC-V7. With @option{-mcpu=supersparc}, the compiler additionally
-optimizes it for the SuperSPARC chip, as used in the SPARCStation 10, 1000 and
-2000 series.
-
-With @option{-mcpu=sparclite}, GCC generates code for the SPARClite variant of
-the SPARC architecture. This adds the integer multiply, integer divide step
-and scan (@code{ffs}) instructions which exist in SPARClite but not in SPARC-V7.
-With @option{-mcpu=f930}, the compiler additionally optimizes it for the
-Fujitsu MB86930 chip, which is the original SPARClite, with no FPU@. With
-@option{-mcpu=f934}, the compiler additionally optimizes it for the Fujitsu
-MB86934 chip, which is the more recent SPARClite with FPU@.
-
-With @option{-mcpu=sparclet}, GCC generates code for the SPARClet variant of
-the SPARC architecture. This adds the integer multiply, multiply/accumulate,
-integer divide step and scan (@code{ffs}) instructions which exist in SPARClet
-but not in SPARC-V7. With @option{-mcpu=tsc701}, the compiler additionally
-optimizes it for the TEMIC SPARClet chip.
-
-With @option{-mcpu=v9}, GCC generates code for the V9 variant of the SPARC
-architecture. This adds 64-bit integer and floating-point move instructions,
-3 additional floating-point condition code registers and conditional move
-instructions. With @option{-mcpu=ultrasparc}, the compiler additionally
-optimizes it for the Sun UltraSPARC I/II/IIi chips. With
-@option{-mcpu=ultrasparc3}, the compiler additionally optimizes it for the
-Sun UltraSPARC III/III+/IIIi/IIIi+/IV/IV+ chips. With
-@option{-mcpu=niagara}, the compiler additionally optimizes it for
-Sun UltraSPARC T1 chips. With @option{-mcpu=niagara2}, the compiler
-additionally optimizes it for Sun UltraSPARC T2 chips. With
-@option{-mcpu=niagara3}, the compiler additionally optimizes it for Sun
-UltraSPARC T3 chips. With @option{-mcpu=niagara4}, the compiler
-additionally optimizes it for Sun UltraSPARC T4 chips. With
-@option{-mcpu=niagara7}, the compiler additionally optimizes it for
-Oracle SPARC M7 chips. With @option{-mcpu=m8}, the compiler
-additionally optimizes it for Oracle M8 chips.
-
-@item -mtune=@var{cpu_type}
-@opindex mtune
-Set the instruction scheduling parameters for machine type
-@var{cpu_type}, but do not set the instruction set or register set that the
-option @option{-mcpu=@var{cpu_type}} does.
-
-The same values for @option{-mcpu=@var{cpu_type}} can be used for
-@option{-mtune=@var{cpu_type}}, but the only useful values are those
-that select a particular CPU implementation. Those are
-@samp{cypress}, @samp{supersparc}, @samp{hypersparc}, @samp{leon},
-@samp{leon3}, @samp{leon3v7}, @samp{leon5}, @samp{f930}, @samp{f934},
-@samp{sparclite86x}, @samp{tsc701}, @samp{ultrasparc},
-@samp{ultrasparc3}, @samp{niagara}, @samp{niagara2}, @samp{niagara3},
-@samp{niagara4}, @samp{niagara7} and @samp{m8}. With native Solaris
-and GNU/Linux toolchains, @samp{native} can also be used.
-
-@item -mv8plus
-@itemx -mno-v8plus
-@opindex mv8plus
-@opindex mno-v8plus
-With @option{-mv8plus}, GCC generates code for the SPARC-V8+ ABI@. The
-difference from the V8 ABI is that the global and out registers are
-considered 64 bits wide. This is enabled by default on Solaris in 32-bit
-mode for all SPARC-V9 processors.
-
-@item -mvis
-@itemx -mno-vis
-@opindex mvis
-@opindex mno-vis
-With @option{-mvis}, GCC generates code that takes advantage of the UltraSPARC
-Visual Instruction Set extensions. The default is @option{-mno-vis}.
-
-@item -mvis2
-@itemx -mno-vis2
-@opindex mvis2
-@opindex mno-vis2
-With @option{-mvis2}, GCC generates code that takes advantage of
-version 2.0 of the UltraSPARC Visual Instruction Set extensions. The
-default is @option{-mvis2} when targeting a cpu that supports such
-instructions, such as UltraSPARC-III and later. Setting @option{-mvis2}
-also sets @option{-mvis}.
-
-@item -mvis3
-@itemx -mno-vis3
-@opindex mvis3
-@opindex mno-vis3
-With @option{-mvis3}, GCC generates code that takes advantage of
-version 3.0 of the UltraSPARC Visual Instruction Set extensions. The
-default is @option{-mvis3} when targeting a cpu that supports such
-instructions, such as niagara-3 and later. Setting @option{-mvis3}
-also sets @option{-mvis2} and @option{-mvis}.
-
-@item -mvis4
-@itemx -mno-vis4
-@opindex mvis4
-@opindex mno-vis4
-With @option{-mvis4}, GCC generates code that takes advantage of
-version 4.0 of the UltraSPARC Visual Instruction Set extensions. The
-default is @option{-mvis4} when targeting a cpu that supports such
-instructions, such as niagara-7 and later. Setting @option{-mvis4}
-also sets @option{-mvis3}, @option{-mvis2} and @option{-mvis}.
-
-@item -mvis4b
-@itemx -mno-vis4b
-@opindex mvis4b
-@opindex mno-vis4b
-With @option{-mvis4b}, GCC generates code that takes advantage of
-version 4.0 of the UltraSPARC Visual Instruction Set extensions, plus
-the additional VIS instructions introduced in the Oracle SPARC
-Architecture 2017. The default is @option{-mvis4b} when targeting a
-cpu that supports such instructions, such as m8 and later. Setting
-@option{-mvis4b} also sets @option{-mvis4}, @option{-mvis3},
-@option{-mvis2} and @option{-mvis}.
-
-@item -mcbcond
-@itemx -mno-cbcond
-@opindex mcbcond
-@opindex mno-cbcond
-With @option{-mcbcond}, GCC generates code that takes advantage of the UltraSPARC
-Compare-and-Branch-on-Condition instructions. The default is @option{-mcbcond}
-when targeting a CPU that supports such instructions, such as Niagara-4 and
-later.
-
-@item -mfmaf
-@itemx -mno-fmaf
-@opindex mfmaf
-@opindex mno-fmaf
-With @option{-mfmaf}, GCC generates code that takes advantage of the UltraSPARC
-Fused Multiply-Add Floating-point instructions. The default is @option{-mfmaf}
-when targeting a CPU that supports such instructions, such as Niagara-3 and
-later.
-
-@item -mfsmuld
-@itemx -mno-fsmuld
-@opindex mfsmuld
-@opindex mno-fsmuld
-With @option{-mfsmuld}, GCC generates code that takes advantage of the
-Floating-point Multiply Single to Double (FsMULd) instruction. The default is
-@option{-mfsmuld} when targeting a CPU supporting the architecture versions V8
-or V9 with FPU except @option{-mcpu=leon}.
-
-@item -mpopc
-@itemx -mno-popc
-@opindex mpopc
-@opindex mno-popc
-With @option{-mpopc}, GCC generates code that takes advantage of the UltraSPARC
-Population Count instruction. The default is @option{-mpopc}
-when targeting a CPU that supports such an instruction, such as Niagara-2 and
-later.
-
-@item -msubxc
-@itemx -mno-subxc
-@opindex msubxc
-@opindex mno-subxc
-With @option{-msubxc}, GCC generates code that takes advantage of the UltraSPARC
-Subtract-Extended-with-Carry instruction. The default is @option{-msubxc}
-when targeting a CPU that supports such an instruction, such as Niagara-7 and
-later.
-
-@item -mfix-at697f
-@opindex mfix-at697f
-Enable the documented workaround for the single erratum of the Atmel AT697F
-processor (which corresponds to erratum #13 of the AT697E processor).
-
-@item -mfix-ut699
-@opindex mfix-ut699
-Enable the documented workarounds for the floating-point errata and the data
-cache nullify errata of the UT699 processor.
-
-@item -mfix-ut700
-@opindex mfix-ut700
-Enable the documented workaround for the back-to-back store errata of
-the UT699E/UT700 processor.
-
-@item -mfix-gr712rc
-@opindex mfix-gr712rc
-Enable the documented workaround for the back-to-back store errata of
-the GR712RC processor.
-@end table
-
-These @samp{-m} options are supported in addition to the above
-on SPARC-V9 processors in 64-bit environments:
-
-@table @gcctabopt
-@item -m32
-@itemx -m64
-@opindex m32
-@opindex m64
-Generate code for a 32-bit or 64-bit environment.
-The 32-bit environment sets int, long and pointer to 32 bits.
-The 64-bit environment sets int to 32 bits and long and pointer
-to 64 bits.
-
-@item -mcmodel=@var{which}
-@opindex mcmodel
-Set the code model to one of
-
-@table @samp
-@item medlow
-The Medium/Low code model: 64-bit addresses, programs
-must be linked in the low 32 bits of memory. Programs can be statically
-or dynamically linked.
-
-@item medmid
-The Medium/Middle code model: 64-bit addresses, programs
-must be linked in the low 44 bits of memory, the text and data segments must
-be less than 2GB in size and the data segment must be located within 2GB of
-the text segment.
-
-@item medany
-The Medium/Anywhere code model: 64-bit addresses, programs
-may be linked anywhere in memory, the text and data segments must be less
-than 2GB in size and the data segment must be located within 2GB of the
-text segment.
-
-@item embmedany
-The Medium/Anywhere code model for embedded systems:
-64-bit addresses, the text and data segments must be less than 2GB in
-size, both starting anywhere in memory (determined at link time). The
-global register %g4 points to the base of the data segment. Programs
-are statically linked and PIC is not supported.
-@end table
-
-@item -mmemory-model=@var{mem-model}
-@opindex mmemory-model
-Set the memory model in force on the processor to one of
-
-@table @samp
-@item default
-The default memory model for the processor and operating system.
-
-@item rmo
-Relaxed Memory Order
-
-@item pso
-Partial Store Order
-
-@item tso
-Total Store Order
-
-@item sc
-Sequential Consistency
-@end table
-
-These memory models are formally defined in Appendix D of the SPARC-V9
-architecture manual, as set in the processor's @code{PSTATE.MM} field.
-
-@item -mstack-bias
-@itemx -mno-stack-bias
-@opindex mstack-bias
-@opindex mno-stack-bias
-With @option{-mstack-bias}, GCC assumes that the stack pointer, and
-frame pointer if present, are offset by @minus{}2047 which must be added back
-when making stack frame references. This is the default in 64-bit mode.
-Otherwise, assume no such offset is present.
-@end table
-
-@node System V Options
-@subsection Options for System V
-
-These additional options are available on System V Release 4 for
-compatibility with other compilers on those systems:
-
-@table @gcctabopt
-@item -G
-@opindex G
-Create a shared object.
-It is recommended that @option{-symbolic} or @option{-shared} be used instead.
-
-@item -Qy
-@opindex Qy
-Identify the versions of each tool used by the compiler, in a
-@code{.ident} assembler directive in the output.
-
-@item -Qn
-@opindex Qn
-Refrain from adding @code{.ident} directives to the output file (this is
-the default).
-
-@item -YP,@var{dirs}
-@opindex YP
-Search the directories @var{dirs}, and no others, for libraries
-specified with @option{-l}.
-
-@item -Ym,@var{dir}
-@opindex Ym
-Look in the directory @var{dir} to find the M4 preprocessor.
-The assembler uses this option.
-@c This is supposed to go with a -Yd for predefined M4 macro files, but
-@c the generic assembler that comes with Solaris takes just -Ym.
-@end table
-
-@node V850 Options
-@subsection V850 Options
-@cindex V850 Options
-
-These @samp{-m} options are defined for V850 implementations:
-
-@table @gcctabopt
-@item -mlong-calls
-@itemx -mno-long-calls
-@opindex mlong-calls
-@opindex mno-long-calls
-Treat all calls as being far away (near). If calls are assumed to be
-far away, the compiler always loads the function's address into a
-register, and calls indirect through the pointer.
-
-@item -mno-ep
-@itemx -mep
-@opindex mno-ep
-@opindex mep
-Do not optimize (do optimize) basic blocks that use the same index
-pointer 4 or more times to copy pointer into the @code{ep} register, and
-use the shorter @code{sld} and @code{sst} instructions. The @option{-mep}
-option is on by default if you optimize.
-
-@item -mno-prolog-function
-@itemx -mprolog-function
-@opindex mno-prolog-function
-@opindex mprolog-function
-Do not use (do use) external functions to save and restore registers
-at the prologue and epilogue of a function. The external functions
-are slower, but use less code space if more than one function saves
-the same number of registers. The @option{-mprolog-function} option
-is on by default if you optimize.
-
-@item -mspace
-@opindex mspace
-Try to make the code as small as possible. At present, this just turns
-on the @option{-mep} and @option{-mprolog-function} options.
-
-@item -mtda=@var{n}
-@opindex mtda
-Put static or global variables whose size is @var{n} bytes or less into
-the tiny data area that register @code{ep} points to. The tiny data
-area can hold up to 256 bytes in total (128 bytes for byte references).
-
-@item -msda=@var{n}
-@opindex msda
-Put static or global variables whose size is @var{n} bytes or less into
-the small data area that register @code{gp} points to. The small data
-area can hold up to 64 kilobytes.
-
-@item -mzda=@var{n}
-@opindex mzda
-Put static or global variables whose size is @var{n} bytes or less into
-the first 32 kilobytes of memory.
-
-@item -mv850
-@opindex mv850
-Specify that the target processor is the V850.
-
-@item -mv850e3v5
-@opindex mv850e3v5
-Specify that the target processor is the V850E3V5. The preprocessor
-constant @code{__v850e3v5__} is defined if this option is used.
-
-@item -mv850e2v4
-@opindex mv850e2v4
-Specify that the target processor is the V850E3V5. This is an alias for
-the @option{-mv850e3v5} option.
-
-@item -mv850e2v3
-@opindex mv850e2v3
-Specify that the target processor is the V850E2V3. The preprocessor
-constant @code{__v850e2v3__} is defined if this option is used.
-
-@item -mv850e2
-@opindex mv850e2
-Specify that the target processor is the V850E2. The preprocessor
-constant @code{__v850e2__} is defined if this option is used.
-
-@item -mv850e1
-@opindex mv850e1
-Specify that the target processor is the V850E1. The preprocessor
-constants @code{__v850e1__} and @code{__v850e__} are defined if
-this option is used.
-
-@item -mv850es
-@opindex mv850es
-Specify that the target processor is the V850ES. This is an alias for
-the @option{-mv850e1} option.
-
-@item -mv850e
-@opindex mv850e
-Specify that the target processor is the V850E@. The preprocessor
-constant @code{__v850e__} is defined if this option is used.
-
-If neither @option{-mv850} nor @option{-mv850e} nor @option{-mv850e1}
-nor @option{-mv850e2} nor @option{-mv850e2v3} nor @option{-mv850e3v5}
-are defined then a default target processor is chosen and the
-relevant @samp{__v850*__} preprocessor constant is defined.
-
-The preprocessor constants @code{__v850} and @code{__v851__} are always
-defined, regardless of which processor variant is the target.
-
-@item -mdisable-callt
-@itemx -mno-disable-callt
-@opindex mdisable-callt
-@opindex mno-disable-callt
-This option suppresses generation of the @code{CALLT} instruction for the
-v850e, v850e1, v850e2, v850e2v3 and v850e3v5 flavors of the v850
-architecture.
-
-This option is enabled by default when the RH850 ABI is
-in use (see @option{-mrh850-abi}), and disabled by default when the
-GCC ABI is in use. If @code{CALLT} instructions are being generated
-then the C preprocessor symbol @code{__V850_CALLT__} is defined.
-
-@item -mrelax
-@itemx -mno-relax
-@opindex mrelax
-@opindex mno-relax
-Pass on (or do not pass on) the @option{-mrelax} command-line option
-to the assembler.
-
-@item -mlong-jumps
-@itemx -mno-long-jumps
-@opindex mlong-jumps
-@opindex mno-long-jumps
-Disable (or re-enable) the generation of PC-relative jump instructions.
-
-@item -msoft-float
-@itemx -mhard-float
-@opindex msoft-float
-@opindex mhard-float
-Disable (or re-enable) the generation of hardware floating point
-instructions. This option is only significant when the target
-architecture is @samp{V850E2V3} or higher. If hardware floating point
-instructions are being generated then the C preprocessor symbol
-@code{__FPU_OK__} is defined, otherwise the symbol
-@code{__NO_FPU__} is defined.
-
-@item -mloop
-@opindex mloop
-Enables the use of the e3v5 LOOP instruction. The use of this
-instruction is not enabled by default when the e3v5 architecture is
-selected because its use is still experimental.
-
-@item -mrh850-abi
-@itemx -mghs
-@opindex mrh850-abi
-@opindex mghs
-Enables support for the RH850 version of the V850 ABI. This is the
-default. With this version of the ABI the following rules apply:
-
-@itemize
-@item
-Integer sized structures and unions are returned via a memory pointer
-rather than a register.
-
-@item
-Large structures and unions (more than 8 bytes in size) are passed by
-value.
-
-@item
-Functions are aligned to 16-bit boundaries.
-
-@item
-The @option{-m8byte-align} command-line option is supported.
-
-@item
-The @option{-mdisable-callt} command-line option is enabled by
-default. The @option{-mno-disable-callt} command-line option is not
-supported.
-@end itemize
-
-When this version of the ABI is enabled the C preprocessor symbol
-@code{__V850_RH850_ABI__} is defined.
-
-@item -mgcc-abi
-@opindex mgcc-abi
-Enables support for the old GCC version of the V850 ABI. With this
-version of the ABI the following rules apply:
-
-@itemize
-@item
-Integer sized structures and unions are returned in register @code{r10}.
-
-@item
-Large structures and unions (more than 8 bytes in size) are passed by
-reference.
-
-@item
-Functions are aligned to 32-bit boundaries, unless optimizing for
-size.
-
-@item
-The @option{-m8byte-align} command-line option is not supported.
-
-@item
-The @option{-mdisable-callt} command-line option is supported but not
-enabled by default.
-@end itemize
-
-When this version of the ABI is enabled the C preprocessor symbol
-@code{__V850_GCC_ABI__} is defined.
-
-@item -m8byte-align
-@itemx -mno-8byte-align
-@opindex m8byte-align
-@opindex mno-8byte-align
-Enables support for @code{double} and @code{long long} types to be
-aligned on 8-byte boundaries. The default is to restrict the
-alignment of all objects to at most 4-bytes. When
-@option{-m8byte-align} is in effect the C preprocessor symbol
-@code{__V850_8BYTE_ALIGN__} is defined.
-
-@item -mbig-switch
-@opindex mbig-switch
-Generate code suitable for big switch tables. Use this option only if
-the assembler/linker complain about out of range branches within a switch
-table.
-
-@item -mapp-regs
-@opindex mapp-regs
-This option causes r2 and r5 to be used in the code generated by
-the compiler. This setting is the default.
-
-@item -mno-app-regs
-@opindex mno-app-regs
-This option causes r2 and r5 to be treated as fixed registers.
-
-@end table
-
-@node VAX Options
-@subsection VAX Options
-@cindex VAX options
-
-These @samp{-m} options are defined for the VAX:
-
-@table @gcctabopt
-@item -munix
-@opindex munix
-Do not output certain jump instructions (@code{aobleq} and so on)
-that the Unix assembler for the VAX cannot handle across long
-ranges.
-
-@item -mgnu
-@opindex mgnu
-Do output those jump instructions, on the assumption that the
-GNU assembler is being used.
-
-@item -mg
-@opindex mg
-Output code for G-format floating-point numbers instead of D-format.
-
-@item -mlra
-@itemx -mno-lra
-@opindex mlra
-@opindex mno-lra
-Enable Local Register Allocation. This is still experimental for the VAX,
-so by default the compiler uses standard reload.
-@end table
-
-@node Visium Options
-@subsection Visium Options
-@cindex Visium options
-
-@table @gcctabopt
-
-@item -mdebug
-@opindex mdebug
-A program which performs file I/O and is destined to run on an MCM target
-should be linked with this option. It causes the libraries libc.a and
-libdebug.a to be linked. The program should be run on the target under
-the control of the GDB remote debugging stub.
-
-@item -msim
-@opindex msim
-A program which performs file I/O and is destined to run on the simulator
-should be linked with option. This causes libraries libc.a and libsim.a to
-be linked.
-
-@item -mfpu
-@itemx -mhard-float
-@opindex mfpu
-@opindex mhard-float
-Generate code containing floating-point instructions. This is the
-default.
-
-@item -mno-fpu
-@itemx -msoft-float
-@opindex mno-fpu
-@opindex msoft-float
-Generate code containing library calls for floating-point.
-
-@option{-msoft-float} changes the calling convention in the output file;
-therefore, it is only useful if you compile @emph{all} of a program with
-this option. In particular, you need to compile @file{libgcc.a}, the
-library that comes with GCC, with @option{-msoft-float} in order for
-this to work.
-
-@item -mcpu=@var{cpu_type}
-@opindex mcpu
-Set the instruction set, register set, and instruction scheduling parameters
-for machine type @var{cpu_type}. Supported values for @var{cpu_type} are
-@samp{mcm}, @samp{gr5} and @samp{gr6}.
-
-@samp{mcm} is a synonym of @samp{gr5} present for backward compatibility.
-
-By default (unless configured otherwise), GCC generates code for the GR5
-variant of the Visium architecture.
-
-With @option{-mcpu=gr6}, GCC generates code for the GR6 variant of the Visium
-architecture. The only difference from GR5 code is that the compiler will
-generate block move instructions.
-
-@item -mtune=@var{cpu_type}
-@opindex mtune
-Set the instruction scheduling parameters for machine type @var{cpu_type},
-but do not set the instruction set or register set that the option
-@option{-mcpu=@var{cpu_type}} would.
-
-@item -msv-mode
-@opindex msv-mode
-Generate code for the supervisor mode, where there are no restrictions on
-the access to general registers. This is the default.
-
-@item -muser-mode
-@opindex muser-mode
-Generate code for the user mode, where the access to some general registers
-is forbidden: on the GR5, registers r24 to r31 cannot be accessed in this
-mode; on the GR6, only registers r29 to r31 are affected.
-@end table
-
-@node VMS Options
-@subsection VMS Options
-
-These @samp{-m} options are defined for the VMS implementations:
-
-@table @gcctabopt
-@item -mvms-return-codes
-@opindex mvms-return-codes
-Return VMS condition codes from @code{main}. The default is to return POSIX-style
-condition (e.g.@: error) codes.
-
-@item -mdebug-main=@var{prefix}
-@opindex mdebug-main=@var{prefix}
-Flag the first routine whose name starts with @var{prefix} as the main
-routine for the debugger.
-
-@item -mmalloc64
-@opindex mmalloc64
-Default to 64-bit memory allocation routines.
-
-@item -mpointer-size=@var{size}
-@opindex mpointer-size=@var{size}
-Set the default size of pointers. Possible options for @var{size} are
-@samp{32} or @samp{short} for 32 bit pointers, @samp{64} or @samp{long}
-for 64 bit pointers, and @samp{no} for supporting only 32 bit pointers.
-The later option disables @code{pragma pointer_size}.
-@end table
-
-@node VxWorks Options
-@subsection VxWorks Options
-@cindex VxWorks Options
-
-The options in this section are defined for all VxWorks targets.
-Options specific to the target hardware are listed with the other
-options for that target.
-
-@table @gcctabopt
-@item -mrtp
-@opindex mrtp
-GCC can generate code for both VxWorks kernels and real time processes
-(RTPs). This option switches from the former to the latter. It also
-defines the preprocessor macro @code{__RTP__}.
-
-@item -non-static
-@opindex non-static
-Link an RTP executable against shared libraries rather than static
-libraries. The options @option{-static} and @option{-shared} can
-also be used for RTPs (@pxref{Link Options}); @option{-static}
-is the default.
-
-@item -Bstatic
-@itemx -Bdynamic
-@opindex Bstatic
-@opindex Bdynamic
-These options are passed down to the linker. They are defined for
-compatibility with Diab.
-
-@item -Xbind-lazy
-@opindex Xbind-lazy
-Enable lazy binding of function calls. This option is equivalent to
-@option{-Wl,-z,now} and is defined for compatibility with Diab.
-
-@item -Xbind-now
-@opindex Xbind-now
-Disable lazy binding of function calls. This option is the default and
-is defined for compatibility with Diab.
-@end table
-
-@node x86 Options
-@subsection x86 Options
-@cindex x86 Options
-
-These @samp{-m} options are defined for the x86 family of computers.
-
-@table @gcctabopt
-
-@item -march=@var{cpu-type}
-@opindex march
-Generate instructions for the machine type @var{cpu-type}. In contrast to
-@option{-mtune=@var{cpu-type}}, which merely tunes the generated code
-for the specified @var{cpu-type}, @option{-march=@var{cpu-type}} allows GCC
-to generate code that may not run at all on processors other than the one
-indicated. Specifying @option{-march=@var{cpu-type}} implies
-@option{-mtune=@var{cpu-type}}, except where noted otherwise.
-
-The choices for @var{cpu-type} are:
-
-@table @samp
-@item native
-This selects the CPU to generate code for at compilation time by determining
-the processor type of the compiling machine. Using @option{-march=native}
-enables all instruction subsets supported by the local machine (hence
-the result might not run on different machines). Using @option{-mtune=native}
-produces code optimized for the local machine under the constraints
-of the selected instruction set.
-
-@item x86-64
-A generic CPU with 64-bit extensions.
-
-@item x86-64-v2
-@itemx x86-64-v3
-@itemx x86-64-v4
-These choices for @var{cpu-type} select the corresponding
-micro-architecture level from the x86-64 psABI. On ABIs other than
-the x86-64 psABI they select the same CPU features as the x86-64 psABI
-documents for the particular micro-architecture level.
-
-Since these @var{cpu-type} values do not have a corresponding
-@option{-mtune} setting, using @option{-march} with these values enables
-generic tuning. Specific tuning can be enabled using the
-@option{-mtune=@var{other-cpu-type}} option with an appropriate
-@var{other-cpu-type} value.
-
-@item i386
-Original Intel i386 CPU@.
-
-@item i486
-Intel i486 CPU@. (No scheduling is implemented for this chip.)
-
-@item i586
-@itemx pentium
-Intel Pentium CPU with no MMX support.
-
-@item lakemont
-Intel Lakemont MCU, based on Intel Pentium CPU.
-
-@item pentium-mmx
-Intel Pentium MMX CPU, based on Pentium core with MMX instruction set support.
-
-@item pentiumpro
-Intel Pentium Pro CPU@.
-
-@item i686
-When used with @option{-march}, the Pentium Pro
-instruction set is used, so the code runs on all i686 family chips.
-When used with @option{-mtune}, it has the same meaning as @samp{generic}.
-
-@item pentium2
-Intel Pentium II CPU, based on Pentium Pro core with MMX and FXSR instruction
-set support.
-
-@item pentium3
-@itemx pentium3m
-Intel Pentium III CPU, based on Pentium Pro core with MMX, FXSR and SSE
-instruction set support.
-
-@item pentium-m
-Intel Pentium M; low-power version of Intel Pentium III CPU
-with MMX, SSE, SSE2 and FXSR instruction set support. Used by Centrino
-notebooks.
-
-@item pentium4
-@itemx pentium4m
-Intel Pentium 4 CPU with MMX, SSE, SSE2 and FXSR instruction set support.
-
-@item prescott
-Improved version of Intel Pentium 4 CPU with MMX, SSE, SSE2, SSE3 and FXSR
-instruction set support.
-
-@item nocona
-Improved version of Intel Pentium 4 CPU with 64-bit extensions, MMX, SSE,
-SSE2, SSE3 and FXSR instruction set support.
-
-@item core2
-Intel Core 2 CPU with 64-bit extensions, MMX, SSE, SSE2, SSE3, SSSE3, CX16,
-SAHF and FXSR instruction set support.
-
-@item nehalem
-Intel Nehalem CPU with 64-bit extensions, MMX, SSE, SSE2, SSE3, SSSE3,
-SSE4.1, SSE4.2, POPCNT, CX16, SAHF and FXSR instruction set support.
-
-@item westmere
-Intel Westmere CPU with 64-bit extensions, MMX, SSE, SSE2, SSE3, SSSE3,
-SSE4.1, SSE4.2, POPCNT, CX16, SAHF, FXSR and PCLMUL instruction set support.
-
-@item sandybridge
-Intel Sandy Bridge CPU with 64-bit extensions, MMX, SSE, SSE2, SSE3, SSSE3,
-SSE4.1, SSE4.2, POPCNT, CX16, SAHF, FXSR, AVX, XSAVE and PCLMUL instruction set
-support.
-
-@item ivybridge
-Intel Ivy Bridge CPU with 64-bit extensions, MMX, SSE, SSE2, SSE3, SSSE3,
-SSE4.1, SSE4.2, POPCNT, CX16, SAHF, FXSR, AVX, XSAVE, PCLMUL, FSGSBASE, RDRND
-and F16C instruction set support.
-
-@item haswell
-Intel Haswell CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2, SSE3, SSSE3,
-SSE4.1, SSE4.2, POPCNT, CX16, SAHF, FXSR, AVX, XSAVE, PCLMUL, FSGSBASE, RDRND,
-F16C, AVX2, BMI, BMI2, LZCNT, FMA, MOVBE and HLE instruction set support.
-
-@item broadwell
-Intel Broadwell CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2, SSE3, SSSE3,
-SSE4.1, SSE4.2, POPCNT, CX16, SAHF, FXSR, AVX, XSAVE, PCLMUL, FSGSBASE, RDRND,
-F16C, AVX2, BMI, BMI2, LZCNT, FMA, MOVBE, HLE, RDSEED, ADCX and PREFETCHW
-instruction set support.
-
-@item skylake
-Intel Skylake CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2, SSE3, SSSE3,
-SSE4.1, SSE4.2, POPCNT, CX16, SAHF, FXSR, AVX, XSAVE, PCLMUL, FSGSBASE, RDRND,
-F16C, AVX2, BMI, BMI2, LZCNT, FMA, MOVBE, HLE, RDSEED, ADCX, PREFETCHW, AES,
-CLFLUSHOPT, XSAVEC, XSAVES and SGX instruction set support.
-
-@item bonnell
-Intel Bonnell CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2, SSE3 and SSSE3
-instruction set support.
-
-@item silvermont
-Intel Silvermont CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2, SSE3, SSSE3,
-SSE4.1, SSE4.2, POPCNT, CX16, SAHF, FXSR, PCLMUL, PREFETCHW and RDRND
-instruction set support.
-
-@item goldmont
-Intel Goldmont CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2, SSE3, SSSE3,
-SSE4.1, SSE4.2, POPCNT, CX16, SAHF, FXSR, PCLMUL, PREFETCHW, RDRND, AES, SHA,
-RDSEED, XSAVE, XSAVEC, XSAVES, XSAVEOPT, CLFLUSHOPT and FSGSBASE instruction
-set support.
-
-@item goldmont-plus
-Intel Goldmont Plus CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2, SSE3,
-SSSE3, SSE4.1, SSE4.2, POPCNT, CX16, SAHF, FXSR, PCLMUL, PREFETCHW, RDRND, AES,
-SHA, RDSEED, XSAVE, XSAVEC, XSAVES, XSAVEOPT, CLFLUSHOPT, FSGSBASE, PTWRITE,
-RDPID and SGX instruction set support.
-
-@item tremont
-Intel Tremont CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2, SSE3, SSSE3,
-SSE4.1, SSE4.2, POPCNT, CX16, SAHF, FXSR, PCLMUL, PREFETCHW, RDRND, AES, SHA,
-RDSEED, XSAVE, XSAVEC, XSAVES, XSAVEOPT, CLFLUSHOPT, FSGSBASE, PTWRITE, RDPID,
-SGX, CLWB, GFNI-SSE, MOVDIRI, MOVDIR64B, CLDEMOTE and WAITPKG instruction set
-support.
-
-@item sierraforest
-Intel Sierra Forest CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2, SSE3,
-SSSE3, SSE4.1, SSE4.2, POPCNT, AES, PREFETCHW, PCLMUL, RDRND, XSAVE, XSAVEC,
-XSAVES, XSAVEOPT, FSGSBASE, PTWRITE, RDPID, SGX, GFNI-SSE, CLWB, MOVDIRI,
-MOVDIR64B, CLDEMOTE, WAITPKG, ADCX, AVX, AVX2, BMI, BMI2, F16C, FMA, LZCNT,
-PCONFIG, PKU, VAES, VPCLMULQDQ, SERIALIZE, HRESET, KL, WIDEKL, AVX-VNNI,
-AVXIFMA, AVXVNNIINT8, AVXNECONVERT and CMPCCXADD instruction set support.
-
-@item grandridge
-Intel Grand Ridge CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2, SSE3,
-SSSE3, SSE4.1, SSE4.2, POPCNT, AES, PREFETCHW, PCLMUL, RDRND, XSAVE, XSAVEC,
-XSAVES, XSAVEOPT, FSGSBASE, PTWRITE, RDPID, SGX, GFNI-SSE, CLWB, MOVDIRI,
-MOVDIR64B, CLDEMOTE, WAITPKG, ADCX, AVX, AVX2, BMI, BMI2, F16C, FMA, LZCNT,
-PCONFIG, PKU, VAES, VPCLMULQDQ, SERIALIZE, HRESET, KL, WIDEKL, AVX-VNNI,
-AVXIFMA, AVXVNNIINT8, AVXNECONVERT, CMPCCXADD and RAOINT instruction set
-support.
-
-@item knl
-Intel Knight's Landing CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2, SSE3,
-SSSE3, SSE4.1, SSE4.2, POPCNT, CX16, SAHF, FXSR, AVX, XSAVE, PCLMUL, FSGSBASE,
-RDRND, F16C, AVX2, BMI, BMI2, LZCNT, FMA, MOVBE, HLE, RDSEED, ADCX, PREFETCHW,
-AVX512PF, AVX512ER, AVX512F, AVX512CD and PREFETCHWT1 instruction set support.
-
-@item knm
-Intel Knights Mill CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2, SSE3,
-SSSE3, SSE4.1, SSE4.2, POPCNT, CX16, SAHF, FXSR, AVX, XSAVE, PCLMUL, FSGSBASE,
-RDRND, F16C, AVX2, BMI, BMI2, LZCNT, FMA, MOVBE, HLE, RDSEED, ADCX, PREFETCHW,
-AVX512PF, AVX512ER, AVX512F, AVX512CD and PREFETCHWT1, AVX5124VNNIW,
-AVX5124FMAPS and AVX512VPOPCNTDQ instruction set support.
-
-@item skylake-avx512
-Intel Skylake Server CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2, SSE3,
-SSSE3, SSE4.1, SSE4.2, POPCNT, CX16, SAHF, FXSR, AVX, XSAVE, PCLMUL, FSGSBASE,
-RDRND, F16C, AVX2, BMI, BMI2, LZCNT, FMA, MOVBE, HLE, RDSEED, ADCX, PREFETCHW,
-AES, CLFLUSHOPT, XSAVEC, XSAVES, SGX, AVX512F, CLWB, AVX512VL, AVX512BW,
-AVX512DQ and AVX512CD instruction set support.
-
-@item cannonlake
-Intel Cannonlake Server CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2,
-SSE3, SSSE3, SSE4.1, SSE4.2, POPCNT, CX16, SAHF, FXSR, AVX, XSAVE, PCLMUL,
-FSGSBASE, RDRND, F16C, AVX2, BMI, BMI2, LZCNT, FMA, MOVBE, HLE, RDSEED, ADCX,
-PREFETCHW, AES, CLFLUSHOPT, XSAVEC, XSAVES, SGX, AVX512F, AVX512VL, AVX512BW,
-AVX512DQ, AVX512CD, PKU, AVX512VBMI, AVX512IFMA and SHA instruction set
-support.
-
-@item icelake-client
-Intel Icelake Client CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2, SSE3,
-SSSE3, SSE4.1, SSE4.2, POPCNT, CX16, SAHF, FXSR, AVX, XSAVE, PCLMUL, FSGSBASE,
-RDRND, F16C, AVX2, BMI, BMI2, LZCNT, FMA, MOVBE, HLE, RDSEED, ADCX, PREFETCHW,
-AES, CLFLUSHOPT, XSAVEC, XSAVES, SGX, AVX512F, AVX512VL, AVX512BW, AVX512DQ,
-AVX512CD, PKU, AVX512VBMI, AVX512IFMA, SHA, AVX512VNNI, GFNI, VAES, AVX512VBMI2
-, VPCLMULQDQ, AVX512BITALG, RDPID and AVX512VPOPCNTDQ instruction set support.
-
-@item icelake-server
-Intel Icelake Server CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2, SSE3,
-SSSE3, SSE4.1, SSE4.2, POPCNT, CX16, SAHF, FXSR, AVX, XSAVE, PCLMUL, FSGSBASE,
-RDRND, F16C, AVX2, BMI, BMI2, LZCNT, FMA, MOVBE, HLE, RDSEED, ADCX, PREFETCHW,
-AES, CLFLUSHOPT, XSAVEC, XSAVES, SGX, AVX512F, AVX512VL, AVX512BW, AVX512DQ,
-AVX512CD, PKU, AVX512VBMI, AVX512IFMA, SHA, AVX512VNNI, GFNI, VAES, AVX512VBMI2
-, VPCLMULQDQ, AVX512BITALG, RDPID, AVX512VPOPCNTDQ, PCONFIG, WBNOINVD and CLWB
-instruction set support.
-
-@item cascadelake
-Intel Cascadelake CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2, SSE3, SSSE3,
-SSE4.1, SSE4.2, POPCNT, CX16, SAHF, FXSR, AVX, XSAVE, PCLMUL, FSGSBASE, RDRND,
-F16C, AVX2, BMI, BMI2, LZCNT, FMA, MOVBE, HLE, RDSEED, ADCX, PREFETCHW, AES,
-CLFLUSHOPT, XSAVEC, XSAVES, SGX, AVX512F, CLWB, AVX512VL, AVX512BW, AVX512DQ,
-AVX512CD and AVX512VNNI instruction set support.
-
-@item cooperlake
-Intel cooperlake CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2, SSE3, SSSE3,
-SSE4.1, SSE4.2, POPCNT, CX16, SAHF, FXSR, AVX, XSAVE, PCLMUL, FSGSBASE, RDRND,
-F16C, AVX2, BMI, BMI2, LZCNT, FMA, MOVBE, HLE, RDSEED, ADCX, PREFETCHW, AES,
-CLFLUSHOPT, XSAVEC, XSAVES, SGX, AVX512F, CLWB, AVX512VL, AVX512BW, AVX512DQ,
-AVX512CD, AVX512VNNI and AVX512BF16 instruction set support.
-
-@item tigerlake
-Intel Tigerlake CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2, SSE3, SSSE3,
-SSE4.1, SSE4.2, POPCNT, CX16, SAHF, FXSR, AVX, XSAVE, PCLMUL, FSGSBASE, RDRND,
-F16C, AVX2, BMI, BMI2, LZCNT, FMA, MOVBE, HLE, RDSEED, ADCX, PREFETCHW, AES,
-CLFLUSHOPT, XSAVEC, XSAVES, SGX, AVX512F, AVX512VL, AVX512BW, AVX512DQ, AVX512CD
-PKU, AVX512VBMI, AVX512IFMA, SHA, AVX512VNNI, GFNI, VAES, AVX512VBMI2,
-VPCLMULQDQ, AVX512BITALG, RDPID, AVX512VPOPCNTDQ, MOVDIRI, MOVDIR64B, CLWB,
-AVX512VP2INTERSECT and KEYLOCKER instruction set support.
-
-@item sapphirerapids
-Intel sapphirerapids CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2, SSE3,
-SSSE3, SSE4.1, SSE4.2, POPCNT, CX16, SAHF, FXSR, AVX, XSAVE, PCLMUL, FSGSBASE,
-RDRND, F16C, AVX2, BMI, BMI2, LZCNT, FMA, MOVBE, HLE, RDSEED, ADCX, PREFETCHW,
-AES, CLFLUSHOPT, XSAVEC, XSAVES, SGX, AVX512F, AVX512VL, AVX512BW, AVX512DQ,
-AVX512CD, PKU, AVX512VBMI, AVX512IFMA, SHA, AVX512VNNI, GFNI, VAES, AVX512VBMI2,
-VPCLMULQDQ, AVX512BITALG, RDPID, AVX512VPOPCNTDQ, PCONFIG, WBNOINVD, CLWB,
-MOVDIRI, MOVDIR64B, ENQCMD, CLDEMOTE, PTWRITE, WAITPKG, SERIALIZE, TSXLDTRK,
-UINTR, AMX-BF16, AMX-TILE, AMX-INT8, AVX-VNNI, AVX512FP16 and AVX512BF16
-instruction set support.
-
-@item alderlake
-Intel Alderlake CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2, SSE3, SSSE3,
-SSE4.1, SSE4.2, POPCNT, AES, PREFETCHW, PCLMUL, RDRND, XSAVE, XSAVEC, XSAVES,
-XSAVEOPT, FSGSBASE, PTWRITE, RDPID, SGX, GFNI-SSE, CLWB, MOVDIRI, MOVDIR64B,
-CLDEMOTE, WAITPKG, ADCX, AVX, AVX2, BMI, BMI2, F16C, FMA, LZCNT, PCONFIG, PKU,
-VAES, VPCLMULQDQ, SERIALIZE, HRESET, KL, WIDEKL and AVX-VNNI instruction set
-support.
-
-@item rocketlake
-Intel Rocketlake CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2, SSE3, SSSE3
-, SSE4.1, SSE4.2, POPCNT, CX16, SAHF, FXSR, AVX, XSAVE, PCLMUL, FSGSBASE, RDRND,
-F16C, AVX2, BMI, BMI2, LZCNT, FMA, MOVBE, HLE, RDSEED, ADCX, PREFETCHW, AES,
-CLFLUSHOPT, XSAVEC, XSAVES, AVX512F, AVX512VL, AVX512BW, AVX512DQ, AVX512CD
-PKU, AVX512VBMI, AVX512IFMA, SHA, AVX512VNNI, GFNI, VAES, AVX512VBMI2,
-VPCLMULQDQ, AVX512BITALG, RDPID and AVX512VPOPCNTDQ instruction set support.
-
-@item graniterapids
-Intel graniterapids CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2, SSE3,
-SSSE3, SSE4.1, SSE4.2, POPCNT, CX16, SAHF, FXSR, AVX, XSAVE, PCLMUL, FSGSBASE,
-RDRND, F16C, AVX2, BMI, BMI2, LZCNT, FMA, MOVBE, HLE, RDSEED, ADCX, PREFETCHW,
-AES, CLFLUSHOPT, XSAVEC, XSAVES, SGX, AVX512F, AVX512VL, AVX512BW, AVX512DQ,
-AVX512CD, PKU, AVX512VBMI, AVX512IFMA, SHA, AVX512VNNI, GFNI, VAES, AVX512VBMI2,
-VPCLMULQDQ, AVX512BITALG, RDPID, AVX512VPOPCNTDQ, PCONFIG, WBNOINVD, CLWB,
-MOVDIRI, MOVDIR64B, AVX512VP2INTERSECT, ENQCMD, CLDEMOTE, PTWRITE, WAITPKG,
-SERIALIZE, TSXLDTRK, UINTR, AMX-BF16, AMX-TILE, AMX-INT8, AVX-VNNI, AVX512FP16,
-AVX512BF16, AMX-FP16 and PREFETCHI instruction set support.
-
-@item k6
-AMD K6 CPU with MMX instruction set support.
-
-@item k6-2
-@itemx k6-3
-Improved versions of AMD K6 CPU with MMX and 3DNow!@: instruction set support.
-
-@item athlon
-@itemx athlon-tbird
-AMD Athlon CPU with MMX, 3dNOW!, enhanced 3DNow!@: and SSE prefetch instructions
-support.
-
-@item athlon-4
-@itemx athlon-xp
-@itemx athlon-mp
-Improved AMD Athlon CPU with MMX, 3DNow!, enhanced 3DNow!@: and full SSE
-instruction set support.
-
-@item k8
-@itemx opteron
-@itemx athlon64
-@itemx athlon-fx
-Processors based on the AMD K8 core with x86-64 instruction set support,
-including the AMD Opteron, Athlon 64, and Athlon 64 FX processors.
-(This supersets MMX, SSE, SSE2, 3DNow!, enhanced 3DNow!@: and 64-bit
-instruction set extensions.)
-
-@item k8-sse3
-@itemx opteron-sse3
-@itemx athlon64-sse3
-Improved versions of AMD K8 cores with SSE3 instruction set support.
-
-@item amdfam10
-@itemx barcelona
-CPUs based on AMD Family 10h cores with x86-64 instruction set support. (This
-supersets MMX, SSE, SSE2, SSE3, SSE4A, 3DNow!, enhanced 3DNow!, ABM and 64-bit
-instruction set extensions.)
-
-@item bdver1
-CPUs based on AMD Family 15h cores with x86-64 instruction set support. (This
-supersets FMA4, AVX, XOP, LWP, AES, PCLMUL, CX16, MMX, SSE, SSE2, SSE3, SSE4A,
-SSSE3, SSE4.1, SSE4.2, ABM and 64-bit instruction set extensions.)
-
-@item bdver2
-AMD Family 15h core based CPUs with x86-64 instruction set support. (This
-supersets BMI, TBM, F16C, FMA, FMA4, AVX, XOP, LWP, AES, PCLMUL, CX16, MMX,
-SSE, SSE2, SSE3, SSE4A, SSSE3, SSE4.1, SSE4.2, ABM and 64-bit instruction set
-extensions.)
-
-@item bdver3
-AMD Family 15h core based CPUs with x86-64 instruction set support. (This
-supersets BMI, TBM, F16C, FMA, FMA4, FSGSBASE, AVX, XOP, LWP, AES,
-PCLMUL, CX16, MMX, SSE, SSE2, SSE3, SSE4A, SSSE3, SSE4.1, SSE4.2, ABM and
-64-bit instruction set extensions.)
-
-@item bdver4
-AMD Family 15h core based CPUs with x86-64 instruction set support. (This
-supersets BMI, BMI2, TBM, F16C, FMA, FMA4, FSGSBASE, AVX, AVX2, XOP, LWP,
-AES, PCLMUL, CX16, MOVBE, MMX, SSE, SSE2, SSE3, SSE4A, SSSE3, SSE4.1,
-SSE4.2, ABM and 64-bit instruction set extensions.)
-
-@item znver1
-AMD Family 17h core based CPUs with x86-64 instruction set support. (This
-supersets BMI, BMI2, F16C, FMA, FSGSBASE, AVX, AVX2, ADCX, RDSEED, MWAITX,
-SHA, CLZERO, AES, PCLMUL, CX16, MOVBE, MMX, SSE, SSE2, SSE3, SSE4A, SSSE3,
-SSE4.1, SSE4.2, ABM, XSAVEC, XSAVES, CLFLUSHOPT, POPCNT, and 64-bit
-instruction set extensions.)
-
-@item znver2
-AMD Family 17h core based CPUs with x86-64 instruction set support. (This
-supersets BMI, BMI2, CLWB, F16C, FMA, FSGSBASE, AVX, AVX2, ADCX, RDSEED,
-MWAITX, SHA, CLZERO, AES, PCLMUL, CX16, MOVBE, MMX, SSE, SSE2, SSE3, SSE4A,
-SSSE3, SSE4.1, SSE4.2, ABM, XSAVEC, XSAVES, CLFLUSHOPT, POPCNT, RDPID,
-WBNOINVD, and 64-bit instruction set extensions.)
-
-@item znver3
-AMD Family 19h core based CPUs with x86-64 instruction set support. (This
-supersets BMI, BMI2, CLWB, F16C, FMA, FSGSBASE, AVX, AVX2, ADCX, RDSEED,
-MWAITX, SHA, CLZERO, AES, PCLMUL, CX16, MOVBE, MMX, SSE, SSE2, SSE3, SSE4A,
-SSSE3, SSE4.1, SSE4.2, ABM, XSAVEC, XSAVES, CLFLUSHOPT, POPCNT, RDPID,
-WBNOINVD, PKU, VPCLMULQDQ, VAES, and 64-bit instruction set extensions.)
-
-@item znver4
-AMD Family 19h core based CPUs with x86-64 instruction set support. (This
-supersets BMI, BMI2, CLWB, F16C, FMA, FSGSBASE, AVX, AVX2, ADCX, RDSEED,
-MWAITX, SHA, CLZERO, AES, PCLMUL, CX16, MOVBE, MMX, SSE, SSE2, SSE3, SSE4A,
-SSSE3, SSE4.1, SSE4.2, ABM, XSAVEC, XSAVES, CLFLUSHOPT, POPCNT, RDPID,
-WBNOINVD, PKU, VPCLMULQDQ, VAES, AVX512F, AVX512DQ, AVX512IFMA, AVX512CD,
-AVX512BW, AVX512VL, AVX512BF16, AVX512VBMI, AVX512VBMI2, AVX512VNNI,
-AVX512BITALG, AVX512VPOPCNTDQ, GFNI and 64-bit instruction set extensions.)
-
-@item btver1
-CPUs based on AMD Family 14h cores with x86-64 instruction set support. (This
-supersets MMX, SSE, SSE2, SSE3, SSSE3, SSE4A, CX16, ABM and 64-bit
-instruction set extensions.)
-
-@item btver2
-CPUs based on AMD Family 16h cores with x86-64 instruction set support. This
-includes MOVBE, F16C, BMI, AVX, PCLMUL, AES, SSE4.2, SSE4.1, CX16, ABM,
-SSE4A, SSSE3, SSE3, SSE2, SSE, MMX and 64-bit instruction set extensions.
-
-@item winchip-c6
-IDT WinChip C6 CPU, dealt in same way as i486 with additional MMX instruction
-set support.
-
-@item winchip2
-IDT WinChip 2 CPU, dealt in same way as i486 with additional MMX and 3DNow!@:
-instruction set support.
-
-@item c3
-VIA C3 CPU with MMX and 3DNow!@: instruction set support.
-(No scheduling is implemented for this chip.)
-
-@item c3-2
-VIA C3-2 (Nehemiah/C5XL) CPU with MMX and SSE instruction set support.
-(No scheduling is implemented for this chip.)
-
-@item c7
-VIA C7 (Esther) CPU with MMX, SSE, SSE2 and SSE3 instruction set support.
-(No scheduling is implemented for this chip.)
-
-@item samuel-2
-VIA Eden Samuel 2 CPU with MMX and 3DNow!@: instruction set support.
-(No scheduling is implemented for this chip.)
-
-@item nehemiah
-VIA Eden Nehemiah CPU with MMX and SSE instruction set support.
-(No scheduling is implemented for this chip.)
-
-@item esther
-VIA Eden Esther CPU with MMX, SSE, SSE2 and SSE3 instruction set support.
-(No scheduling is implemented for this chip.)
-
-@item eden-x2
-VIA Eden X2 CPU with x86-64, MMX, SSE, SSE2 and SSE3 instruction set support.
-(No scheduling is implemented for this chip.)
-
-@item eden-x4
-VIA Eden X4 CPU with x86-64, MMX, SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2,
-AVX and AVX2 instruction set support.
-(No scheduling is implemented for this chip.)
-
-@item nano
-Generic VIA Nano CPU with x86-64, MMX, SSE, SSE2, SSE3 and SSSE3
-instruction set support.
-(No scheduling is implemented for this chip.)
-
-@item nano-1000
-VIA Nano 1xxx CPU with x86-64, MMX, SSE, SSE2, SSE3 and SSSE3
-instruction set support.
-(No scheduling is implemented for this chip.)
-
-@item nano-2000
-VIA Nano 2xxx CPU with x86-64, MMX, SSE, SSE2, SSE3 and SSSE3
-instruction set support.
-(No scheduling is implemented for this chip.)
-
-@item nano-3000
-VIA Nano 3xxx CPU with x86-64, MMX, SSE, SSE2, SSE3, SSSE3 and SSE4.1
-instruction set support.
-(No scheduling is implemented for this chip.)
-
-@item nano-x2
-VIA Nano Dual Core CPU with x86-64, MMX, SSE, SSE2, SSE3, SSSE3 and SSE4.1
-instruction set support.
-(No scheduling is implemented for this chip.)
-
-@item nano-x4
-VIA Nano Quad Core CPU with x86-64, MMX, SSE, SSE2, SSE3, SSSE3 and SSE4.1
-instruction set support.
-(No scheduling is implemented for this chip.)
-
-@item lujiazui
-ZHAOXIN lujiazui CPU with x86-64, MOVBE, MMX, SSE, SSE2, SSE3, SSSE3, SSE4.1,
-SSE4.2, AVX, POPCNT, AES, PCLMUL, RDRND, XSAVE, XSAVEOPT, FSGSBASE, CX16,
-ABM, BMI, BMI2, F16C, FXSR, RDSEED instruction set support.
-
-@item geode
-AMD Geode embedded processor with MMX and 3DNow!@: instruction set support.
-@end table
-
-@item -mtune=@var{cpu-type}
-@opindex mtune
-Tune to @var{cpu-type} everything applicable about the generated code, except
-for the ABI and the set of available instructions.
-While picking a specific @var{cpu-type} schedules things appropriately
-for that particular chip, the compiler does not generate any code that
-cannot run on the default machine type unless you use a
-@option{-march=@var{cpu-type}} option.
-For example, if GCC is configured for i686-pc-linux-gnu
-then @option{-mtune=pentium4} generates code that is tuned for Pentium 4
-but still runs on i686 machines.
-
-The choices for @var{cpu-type} are the same as for @option{-march}.
-In addition, @option{-mtune} supports 2 extra choices for @var{cpu-type}:
-
-@table @samp
-@item generic
-Produce code optimized for the most common IA32/@/AMD64/@/EM64T processors.
-If you know the CPU on which your code will run, then you should use
-the corresponding @option{-mtune} or @option{-march} option instead of
-@option{-mtune=generic}. But, if you do not know exactly what CPU users
-of your application will have, then you should use this option.
-
-As new processors are deployed in the marketplace, the behavior of this
-option will change. Therefore, if you upgrade to a newer version of
-GCC, code generation controlled by this option will change to reflect
-the processors
-that are most common at the time that version of GCC is released.
-
-There is no @option{-march=generic} option because @option{-march}
-indicates the instruction set the compiler can use, and there is no
-generic instruction set applicable to all processors. In contrast,
-@option{-mtune} indicates the processor (or, in this case, collection of
-processors) for which the code is optimized.
-
-@item intel
-Produce code optimized for the most current Intel processors, which are
-Haswell and Silvermont for this version of GCC. If you know the CPU
-on which your code will run, then you should use the corresponding
-@option{-mtune} or @option{-march} option instead of @option{-mtune=intel}.
-But, if you want your application performs better on both Haswell and
-Silvermont, then you should use this option.
-
-As new Intel processors are deployed in the marketplace, the behavior of
-this option will change. Therefore, if you upgrade to a newer version of
-GCC, code generation controlled by this option will change to reflect
-the most current Intel processors at the time that version of GCC is
-released.
-
-There is no @option{-march=intel} option because @option{-march} indicates
-the instruction set the compiler can use, and there is no common
-instruction set applicable to all processors. In contrast,
-@option{-mtune} indicates the processor (or, in this case, collection of
-processors) for which the code is optimized.
-@end table
-
-@item -mcpu=@var{cpu-type}
-@opindex mcpu
-A deprecated synonym for @option{-mtune}.
-
-@item -mfpmath=@var{unit}
-@opindex mfpmath
-Generate floating-point arithmetic for selected unit @var{unit}. The choices
-for @var{unit} are:
-
-@table @samp
-@item 387
-Use the standard 387 floating-point coprocessor present on the majority of chips and
-emulated otherwise. Code compiled with this option runs almost everywhere.
-The temporary results are computed in 80-bit precision instead of the precision
-specified by the type, resulting in slightly different results compared to most
-of other chips. See @option{-ffloat-store} for more detailed description.
-
-This is the default choice for non-Darwin x86-32 targets.
-
-@item sse
-Use scalar floating-point instructions present in the SSE instruction set.
-This instruction set is supported by Pentium III and newer chips,
-and in the AMD line
-by Athlon-4, Athlon XP and Athlon MP chips. The earlier version of the SSE
-instruction set supports only single-precision arithmetic, thus the double and
-extended-precision arithmetic are still done using 387. A later version, present
-only in Pentium 4 and AMD x86-64 chips, supports double-precision
-arithmetic too.
-
-For the x86-32 compiler, you must use @option{-march=@var{cpu-type}}, @option{-msse}
-or @option{-msse2} switches to enable SSE extensions and make this option
-effective. For the x86-64 compiler, these extensions are enabled by default.
-
-The resulting code should be considerably faster in the majority of cases and avoid
-the numerical instability problems of 387 code, but may break some existing
-code that expects temporaries to be 80 bits.
-
-This is the default choice for the x86-64 compiler, Darwin x86-32 targets,
-and the default choice for x86-32 targets with the SSE2 instruction set
-when @option{-ffast-math} is enabled.
-
-@item sse,387
-@itemx sse+387
-@itemx both
-Attempt to utilize both instruction sets at once. This effectively doubles the
-amount of available registers, and on chips with separate execution units for
-387 and SSE the execution resources too. Use this option with care, as it is
-still experimental, because the GCC register allocator does not model separate
-functional units well, resulting in unstable performance.
-@end table
-
-@item -masm=@var{dialect}
-@opindex masm=@var{dialect}
-Output assembly instructions using selected @var{dialect}. Also affects
-which dialect is used for basic @code{asm} (@pxref{Basic Asm}) and
-extended @code{asm} (@pxref{Extended Asm}). Supported choices (in dialect
-order) are @samp{att} or @samp{intel}. The default is @samp{att}. Darwin does
-not support @samp{intel}.
-
-@item -mieee-fp
-@itemx -mno-ieee-fp
-@opindex mieee-fp
-@opindex mno-ieee-fp
-Control whether or not the compiler uses IEEE floating-point
-comparisons. These correctly handle the case where the result of a
-comparison is unordered.
-
-@item -m80387
-@itemx -mhard-float
-@opindex 80387
-@opindex mhard-float
-Generate output containing 80387 instructions for floating point.
-
-@item -mno-80387
-@itemx -msoft-float
-@opindex no-80387
-@opindex msoft-float
-Generate output containing library calls for floating point.
-
-@strong{Warning:} the requisite libraries are not part of GCC@.
-Normally the facilities of the machine's usual C compiler are used, but
-this cannot be done directly in cross-compilation. You must make your
-own arrangements to provide suitable library functions for
-cross-compilation.
-
-On machines where a function returns floating-point results in the 80387
-register stack, some floating-point opcodes may be emitted even if
-@option{-msoft-float} is used.
-
-@item -mno-fp-ret-in-387
-@opindex mno-fp-ret-in-387
-@opindex mfp-ret-in-387
-Do not use the FPU registers for return values of functions.
-
-The usual calling convention has functions return values of types
-@code{float} and @code{double} in an FPU register, even if there
-is no FPU@. The idea is that the operating system should emulate
-an FPU@.
-
-The option @option{-mno-fp-ret-in-387} causes such values to be returned
-in ordinary CPU registers instead.
-
-@item -mno-fancy-math-387
-@opindex mno-fancy-math-387
-@opindex mfancy-math-387
-Some 387 emulators do not support the @code{sin}, @code{cos} and
-@code{sqrt} instructions for the 387. Specify this option to avoid
-generating those instructions.
-This option is overridden when @option{-march}
-indicates that the target CPU always has an FPU and so the
-instruction does not need emulation. These
-instructions are not generated unless you also use the
-@option{-funsafe-math-optimizations} switch.
-
-@item -malign-double
-@itemx -mno-align-double
-@opindex malign-double
-@opindex mno-align-double
-Control whether GCC aligns @code{double}, @code{long double}, and
-@code{long long} variables on a two-word boundary or a one-word
-boundary. Aligning @code{double} variables on a two-word boundary
-produces code that runs somewhat faster on a Pentium at the
-expense of more memory.
-
-On x86-64, @option{-malign-double} is enabled by default.
-
-@strong{Warning:} if you use the @option{-malign-double} switch,
-structures containing the above types are aligned differently than
-the published application binary interface specifications for the x86-32
-and are not binary compatible with structures in code compiled
-without that switch.
-
-@item -m96bit-long-double
-@itemx -m128bit-long-double
-@opindex m96bit-long-double
-@opindex m128bit-long-double
-These switches control the size of @code{long double} type. The x86-32
-application binary interface specifies the size to be 96 bits,
-so @option{-m96bit-long-double} is the default in 32-bit mode.
-
-Modern architectures (Pentium and newer) prefer @code{long double}
-to be aligned to an 8- or 16-byte boundary. In arrays or structures
-conforming to the ABI, this is not possible. So specifying
-@option{-m128bit-long-double} aligns @code{long double}
-to a 16-byte boundary by padding the @code{long double} with an additional
-32-bit zero.
-
-In the x86-64 compiler, @option{-m128bit-long-double} is the default choice as
-its ABI specifies that @code{long double} is aligned on 16-byte boundary.
-
-Notice that neither of these options enable any extra precision over the x87
-standard of 80 bits for a @code{long double}.
-
-@strong{Warning:} if you override the default value for your target ABI, this
-changes the size of
-structures and arrays containing @code{long double} variables,
-as well as modifying the function calling convention for functions taking
-@code{long double}. Hence they are not binary-compatible
-with code compiled without that switch.
-
-@item -mlong-double-64
-@itemx -mlong-double-80
-@itemx -mlong-double-128
-@opindex mlong-double-64
-@opindex mlong-double-80
-@opindex mlong-double-128
-These switches control the size of @code{long double} type. A size
-of 64 bits makes the @code{long double} type equivalent to the @code{double}
-type. This is the default for 32-bit Bionic C library. A size
-of 128 bits makes the @code{long double} type equivalent to the
-@code{__float128} type. This is the default for 64-bit Bionic C library.
-
-@strong{Warning:} if you override the default value for your target ABI, this
-changes the size of
-structures and arrays containing @code{long double} variables,
-as well as modifying the function calling convention for functions taking
-@code{long double}. Hence they are not binary-compatible
-with code compiled without that switch.
-
-@item -malign-data=@var{type}
-@opindex malign-data
-Control how GCC aligns variables. Supported values for @var{type} are
-@samp{compat} uses increased alignment value compatible uses GCC 4.8
-and earlier, @samp{abi} uses alignment value as specified by the
-psABI, and @samp{cacheline} uses increased alignment value to match
-the cache line size. @samp{compat} is the default.
-
-@item -mlarge-data-threshold=@var{threshold}
-@opindex mlarge-data-threshold
-When @option{-mcmodel=medium} is specified, data objects larger than
-@var{threshold} are placed in the large data section. This value must be the
-same across all objects linked into the binary, and defaults to 65535.
-
-@item -mrtd
-@opindex mrtd
-Use a different function-calling convention, in which functions that
-take a fixed number of arguments return with the @code{ret @var{num}}
-instruction, which pops their arguments while returning. This saves one
-instruction in the caller since there is no need to pop the arguments
-there.
-
-You can specify that an individual function is called with this calling
-sequence with the function attribute @code{stdcall}. You can also
-override the @option{-mrtd} option by using the function attribute
-@code{cdecl}. @xref{Function Attributes}.
-
-@strong{Warning:} this calling convention is incompatible with the one
-normally used on Unix, so you cannot use it if you need to call
-libraries compiled with the Unix compiler.
-
-Also, you must provide function prototypes for all functions that
-take variable numbers of arguments (including @code{printf});
-otherwise incorrect code is generated for calls to those
-functions.
-
-In addition, seriously incorrect code results if you call a
-function with too many arguments. (Normally, extra arguments are
-harmlessly ignored.)
-
-@item -mregparm=@var{num}
-@opindex mregparm
-Control how many registers are used to pass integer arguments. By
-default, no registers are used to pass arguments, and at most 3
-registers can be used. You can control this behavior for a specific
-function by using the function attribute @code{regparm}.
-@xref{Function Attributes}.
-
-@strong{Warning:} if you use this switch, and
-@var{num} is nonzero, then you must build all modules with the same
-value, including any libraries. This includes the system libraries and
-startup modules.
-
-@item -msseregparm
-@opindex msseregparm
-Use SSE register passing conventions for float and double arguments
-and return values. You can control this behavior for a specific
-function by using the function attribute @code{sseregparm}.
-@xref{Function Attributes}.
-
-@strong{Warning:} if you use this switch then you must build all
-modules with the same value, including any libraries. This includes
-the system libraries and startup modules.
-
-@item -mvect8-ret-in-mem
-@opindex mvect8-ret-in-mem
-Return 8-byte vectors in memory instead of MMX registers. This is the
-default on VxWorks to match the ABI of the Sun Studio compilers until
-version 12. @emph{Only} use this option if you need to remain
-compatible with existing code produced by those previous compiler
-versions or older versions of GCC@.
-
-@item -mpc32
-@itemx -mpc64
-@itemx -mpc80
-@opindex mpc32
-@opindex mpc64
-@opindex mpc80
-
-Set 80387 floating-point precision to 32, 64 or 80 bits. When @option{-mpc32}
-is specified, the significands of results of floating-point operations are
-rounded to 24 bits (single precision); @option{-mpc64} rounds the
-significands of results of floating-point operations to 53 bits (double
-precision) and @option{-mpc80} rounds the significands of results of
-floating-point operations to 64 bits (extended double precision), which is
-the default. When this option is used, floating-point operations in higher
-precisions are not available to the programmer without setting the FPU
-control word explicitly.
-
-Setting the rounding of floating-point operations to less than the default
-80 bits can speed some programs by 2% or more. Note that some mathematical
-libraries assume that extended-precision (80-bit) floating-point operations
-are enabled by default; routines in such libraries could suffer significant
-loss of accuracy, typically through so-called ``catastrophic cancellation'',
-when this option is used to set the precision to less than extended precision.
-
-@item -mstackrealign
-@opindex mstackrealign
-Realign the stack at entry. On the x86, the @option{-mstackrealign}
-option generates an alternate prologue and epilogue that realigns the
-run-time stack if necessary. This supports mixing legacy codes that keep
-4-byte stack alignment with modern codes that keep 16-byte stack alignment for
-SSE compatibility. See also the attribute @code{force_align_arg_pointer},
-applicable to individual functions.
-
-@item -mpreferred-stack-boundary=@var{num}
-@opindex mpreferred-stack-boundary
-Attempt to keep the stack boundary aligned to a 2 raised to @var{num}
-byte boundary. If @option{-mpreferred-stack-boundary} is not specified,
-the default is 4 (16 bytes or 128 bits).
-
-@strong{Warning:} When generating code for the x86-64 architecture with
-SSE extensions disabled, @option{-mpreferred-stack-boundary=3} can be
-used to keep the stack boundary aligned to 8 byte boundary. Since
-x86-64 ABI require 16 byte stack alignment, this is ABI incompatible and
-intended to be used in controlled environment where stack space is
-important limitation. This option leads to wrong code when functions
-compiled with 16 byte stack alignment (such as functions from a standard
-library) are called with misaligned stack. In this case, SSE
-instructions may lead to misaligned memory access traps. In addition,
-variable arguments are handled incorrectly for 16 byte aligned
-objects (including x87 long double and __int128), leading to wrong
-results. You must build all modules with
-@option{-mpreferred-stack-boundary=3}, including any libraries. This
-includes the system libraries and startup modules.
-
-@item -mincoming-stack-boundary=@var{num}
-@opindex mincoming-stack-boundary
-Assume the incoming stack is aligned to a 2 raised to @var{num} byte
-boundary. If @option{-mincoming-stack-boundary} is not specified,
-the one specified by @option{-mpreferred-stack-boundary} is used.
-
-On Pentium and Pentium Pro, @code{double} and @code{long double} values
-should be aligned to an 8-byte boundary (see @option{-malign-double}) or
-suffer significant run time performance penalties. On Pentium III, the
-Streaming SIMD Extension (SSE) data type @code{__m128} may not work
-properly if it is not 16-byte aligned.
-
-To ensure proper alignment of this values on the stack, the stack boundary
-must be as aligned as that required by any value stored on the stack.
-Further, every function must be generated such that it keeps the stack
-aligned. Thus calling a function compiled with a higher preferred
-stack boundary from a function compiled with a lower preferred stack
-boundary most likely misaligns the stack. It is recommended that
-libraries that use callbacks always use the default setting.
-
-This extra alignment does consume extra stack space, and generally
-increases code size. Code that is sensitive to stack space usage, such
-as embedded systems and operating system kernels, may want to reduce the
-preferred alignment to @option{-mpreferred-stack-boundary=2}.
-
-@need 200
-@item -mmmx
-@opindex mmmx
-@need 200
-@itemx -msse
-@opindex msse
-@need 200
-@itemx -msse2
-@opindex msse2
-@need 200
-@itemx -msse3
-@opindex msse3
-@need 200
-@itemx -mssse3
-@opindex mssse3
-@need 200
-@itemx -msse4
-@opindex msse4
-@need 200
-@itemx -msse4a
-@opindex msse4a
-@need 200
-@itemx -msse4.1
-@opindex msse4.1
-@need 200
-@itemx -msse4.2
-@opindex msse4.2
-@need 200
-@itemx -mavx
-@opindex mavx
-@need 200
-@itemx -mavx2
-@opindex mavx2
-@need 200
-@itemx -mavx512f
-@opindex mavx512f
-@need 200
-@itemx -mavx512pf
-@opindex mavx512pf
-@need 200
-@itemx -mavx512er
-@opindex mavx512er
-@need 200
-@itemx -mavx512cd
-@opindex mavx512cd
-@need 200
-@itemx -mavx512vl
-@opindex mavx512vl
-@need 200
-@itemx -mavx512bw
-@opindex mavx512bw
-@need 200
-@itemx -mavx512dq
-@opindex mavx512dq
-@need 200
-@itemx -mavx512ifma
-@opindex mavx512ifma
-@need 200
-@itemx -mavx512vbmi
-@opindex mavx512vbmi
-@need 200
-@itemx -msha
-@opindex msha
-@need 200
-@itemx -maes
-@opindex maes
-@need 200
-@itemx -mpclmul
-@opindex mpclmul
-@need 200
-@itemx -mclflushopt
-@opindex mclflushopt
-@need 200
-@itemx -mclwb
-@opindex mclwb
-@need 200
-@itemx -mfsgsbase
-@opindex mfsgsbase
-@need 200
-@itemx -mptwrite
-@opindex mptwrite
-@need 200
-@itemx -mrdrnd
-@opindex mrdrnd
-@need 200
-@itemx -mf16c
-@opindex mf16c
-@need 200
-@itemx -mfma
-@opindex mfma
-@need 200
-@itemx -mpconfig
-@opindex mpconfig
-@need 200
-@itemx -mwbnoinvd
-@opindex mwbnoinvd
-@need 200
-@itemx -mfma4
-@opindex mfma4
-@need 200
-@itemx -mprfchw
-@opindex mprfchw
-@need 200
-@itemx -mrdpid
-@opindex mrdpid
-@need 200
-@itemx -mprefetchwt1
-@opindex mprefetchwt1
-@need 200
-@itemx -mrdseed
-@opindex mrdseed
-@need 200
-@itemx -msgx
-@opindex msgx
-@need 200
-@itemx -mxop
-@opindex mxop
-@need 200
-@itemx -mlwp
-@opindex mlwp
-@need 200
-@itemx -m3dnow
-@opindex m3dnow
-@need 200
-@itemx -m3dnowa
-@opindex m3dnowa
-@need 200
-@itemx -mpopcnt
-@opindex mpopcnt
-@need 200
-@itemx -mabm
-@opindex mabm
-@need 200
-@itemx -madx
-@opindex madx
-@need 200
-@itemx -mbmi
-@opindex mbmi
-@need 200
-@itemx -mbmi2
-@opindex mbmi2
-@need 200
-@itemx -mlzcnt
-@opindex mlzcnt
-@need 200
-@itemx -mfxsr
-@opindex mfxsr
-@need 200
-@itemx -mxsave
-@opindex mxsave
-@need 200
-@itemx -mxsaveopt
-@opindex mxsaveopt
-@need 200
-@itemx -mxsavec
-@opindex mxsavec
-@need 200
-@itemx -mxsaves
-@opindex mxsaves
-@need 200
-@itemx -mrtm
-@opindex mrtm
-@need 200
-@itemx -mhle
-@opindex mhle
-@need 200
-@itemx -mtbm
-@opindex mtbm
-@need 200
-@itemx -mmwaitx
-@opindex mmwaitx
-@need 200
-@itemx -mclzero
-@opindex mclzero
-@need 200
-@itemx -mpku
-@opindex mpku
-@need 200
-@itemx -mavx512vbmi2
-@opindex mavx512vbmi2
-@need 200
-@itemx -mavx512bf16
-@opindex mavx512bf16
-@need 200
-@itemx -mavx512fp16
-@opindex mavx512fp16
-@need 200
-@itemx -mgfni
-@opindex mgfni
-@need 200
-@itemx -mvaes
-@opindex mvaes
-@need 200
-@itemx -mwaitpkg
-@opindex mwaitpkg
-@need 200
-@itemx -mvpclmulqdq
-@opindex mvpclmulqdq
-@need 200
-@itemx -mavx512bitalg
-@opindex mavx512bitalg
-@need 200
-@itemx -mmovdiri
-@opindex mmovdiri
-@need 200
-@itemx -mmovdir64b
-@opindex mmovdir64b
-@need 200
-@itemx -menqcmd
-@opindex menqcmd
-@itemx -muintr
-@opindex muintr
-@need 200
-@itemx -mtsxldtrk
-@opindex mtsxldtrk
-@need 200
-@itemx -mavx512vpopcntdq
-@opindex mavx512vpopcntdq
-@need 200
-@itemx -mavx512vp2intersect
-@opindex mavx512vp2intersect
-@need 200
-@itemx -mavx5124fmaps
-@opindex mavx5124fmaps
-@need 200
-@itemx -mavx512vnni
-@opindex mavx512vnni
-@need 200
-@itemx -mavxvnni
-@opindex mavxvnni
-@need 200
-@itemx -mavx5124vnniw
-@opindex mavx5124vnniw
-@need 200
-@itemx -mcldemote
-@opindex mcldemote
-@need 200
-@itemx -mserialize
-@opindex mserialize
-@need 200
-@itemx -mamx-tile
-@opindex mamx-tile
-@need 200
-@itemx -mamx-int8
-@opindex mamx-int8
-@need 200
-@itemx -mamx-bf16
-@opindex mamx-bf16
-@need 200
-@itemx -mhreset
-@opindex mhreset
-@itemx -mkl
-@opindex mkl
-@need 200
-@itemx -mwidekl
-@opindex mwidekl
-@need 200
-@itemx -mavxifma
-@opindex mavxifma
-@need 200
-@itemx -mavxvnniint8
-@opindex mavxvnniint8
-@need 200
-@itemx -mavxneconvert
-@opindex mavxneconvert
-@need 200
-@itemx -mcmpccxadd
-@opindex mcmpccxadd
-@need 200
-@itemx -mamx-fp16
-@opindex mamx-fp16
-@need 200
-@itemx -mprefetchi
-@opindex mprefetchi
-@need 200
-@itemx -mraoint
-@opindex mraoint
-These switches enable the use of instructions in the MMX, SSE,
-SSE2, SSE3, SSSE3, SSE4, SSE4A, SSE4.1, SSE4.2, AVX, AVX2, AVX512F, AVX512PF,
-AVX512ER, AVX512CD, AVX512VL, AVX512BW, AVX512DQ, AVX512IFMA, AVX512VBMI, SHA,
-AES, PCLMUL, CLFLUSHOPT, CLWB, FSGSBASE, PTWRITE, RDRND, F16C, FMA, PCONFIG,
-WBNOINVD, FMA4, PREFETCHW, RDPID, PREFETCHWT1, RDSEED, SGX, XOP, LWP,
-3DNow!@:, enhanced 3DNow!@:, POPCNT, ABM, ADX, BMI, BMI2, LZCNT, FXSR, XSAVE,
-XSAVEOPT, XSAVEC, XSAVES, RTM, HLE, TBM, MWAITX, CLZERO, PKU, AVX512VBMI2,
-GFNI, VAES, WAITPKG, VPCLMULQDQ, AVX512BITALG, MOVDIRI, MOVDIR64B, AVX512BF16,
-ENQCMD, AVX512VPOPCNTDQ, AVX5124FMAPS, AVX512VNNI, AVX5124VNNIW, SERIALIZE,
-UINTR, HRESET, AMXTILE, AMXINT8, AMXBF16, KL, WIDEKL, AVXVNNI, AVX512FP16,
-AVXIFMA, AVXVNNIINT8, AVXNECONVERT, CMPCCXADD, AMX-FP16, PREFETCHI, RAOINT or
-CLDEMOTE extended instruction sets. Each has a corresponding @option{-mno-}
-option to disable use of these instructions.
-
-These extensions are also available as built-in functions: see
-@ref{x86 Built-in Functions}, for details of the functions enabled and
-disabled by these switches.
-
-To generate SSE/SSE2 instructions automatically from floating-point
-code (as opposed to 387 instructions), see @option{-mfpmath=sse}.
-
-GCC depresses SSEx instructions when @option{-mavx} is used. Instead, it
-generates new AVX instructions or AVX equivalence for all SSEx instructions
-when needed.
-
-These options enable GCC to use these extended instructions in
-generated code, even without @option{-mfpmath=sse}. Applications that
-perform run-time CPU detection must compile separate files for each
-supported architecture, using the appropriate flags. In particular,
-the file containing the CPU detection code should be compiled without
-these options.
-
-@item -mdump-tune-features
-@opindex mdump-tune-features
-This option instructs GCC to dump the names of the x86 performance
-tuning features and default settings. The names can be used in
-@option{-mtune-ctrl=@var{feature-list}}.
-
-@item -mtune-ctrl=@var{feature-list}
-@opindex mtune-ctrl=@var{feature-list}
-This option is used to do fine grain control of x86 code generation features.
-@var{feature-list} is a comma separated list of @var{feature} names. See also
-@option{-mdump-tune-features}. When specified, the @var{feature} is turned
-on if it is not preceded with @samp{^}, otherwise, it is turned off.
-@option{-mtune-ctrl=@var{feature-list}} is intended to be used by GCC
-developers. Using it may lead to code paths not covered by testing and can
-potentially result in compiler ICEs or runtime errors.
-
-@item -mno-default
-@opindex mno-default
-This option instructs GCC to turn off all tunable features. See also
-@option{-mtune-ctrl=@var{feature-list}} and @option{-mdump-tune-features}.
-
-@item -mcld
-@opindex mcld
-This option instructs GCC to emit a @code{cld} instruction in the prologue
-of functions that use string instructions. String instructions depend on
-the DF flag to select between autoincrement or autodecrement mode. While the
-ABI specifies the DF flag to be cleared on function entry, some operating
-systems violate this specification by not clearing the DF flag in their
-exception dispatchers. The exception handler can be invoked with the DF flag
-set, which leads to wrong direction mode when string instructions are used.
-This option can be enabled by default on 32-bit x86 targets by configuring
-GCC with the @option{--enable-cld} configure option. Generation of @code{cld}
-instructions can be suppressed with the @option{-mno-cld} compiler option
-in this case.
-
-@item -mvzeroupper
-@opindex mvzeroupper
-This option instructs GCC to emit a @code{vzeroupper} instruction
-before a transfer of control flow out of the function to minimize
-the AVX to SSE transition penalty as well as remove unnecessary @code{zeroupper}
-intrinsics.
-
-@item -mprefer-avx128
-@opindex mprefer-avx128
-This option instructs GCC to use 128-bit AVX instructions instead of
-256-bit AVX instructions in the auto-vectorizer.
-
-@item -mprefer-vector-width=@var{opt}
-@opindex mprefer-vector-width
-This option instructs GCC to use @var{opt}-bit vector width in instructions
-instead of default on the selected platform.
-
-@item -mmove-max=@var{bits}
-@opindex mmove-max
-This option instructs GCC to set the maximum number of bits can be
-moved from memory to memory efficiently to @var{bits}. The valid
-@var{bits} are 128, 256 and 512.
-
-@item -mstore-max=@var{bits}
-@opindex mstore-max
-This option instructs GCC to set the maximum number of bits can be
-stored to memory efficiently to @var{bits}. The valid @var{bits} are
-128, 256 and 512.
-
-@table @samp
-@item none
-No extra limitations applied to GCC other than defined by the selected platform.
-
-@item 128
-Prefer 128-bit vector width for instructions.
-
-@item 256
-Prefer 256-bit vector width for instructions.
-
-@item 512
-Prefer 512-bit vector width for instructions.
-@end table
-
-@item -mcx16
-@opindex mcx16
-This option enables GCC to generate @code{CMPXCHG16B} instructions in 64-bit
-code to implement compare-and-exchange operations on 16-byte aligned 128-bit
-objects. This is useful for atomic updates of data structures exceeding one
-machine word in size. The compiler uses this instruction to implement
-@ref{__sync Builtins}. However, for @ref{__atomic Builtins} operating on
-128-bit integers, a library call is always used.
-
-@item -msahf
-@opindex msahf
-This option enables generation of @code{SAHF} instructions in 64-bit code.
-Early Intel Pentium 4 CPUs with Intel 64 support,
-prior to the introduction of Pentium 4 G1 step in December 2005,
-lacked the @code{LAHF} and @code{SAHF} instructions
-which are supported by AMD64.
-These are load and store instructions, respectively, for certain status flags.
-In 64-bit mode, the @code{SAHF} instruction is used to optimize @code{fmod},
-@code{drem}, and @code{remainder} built-in functions;
-see @ref{Other Builtins} for details.
-
-@item -mmovbe
-@opindex mmovbe
-This option enables use of the @code{movbe} instruction to implement
-@code{__builtin_bswap32} and @code{__builtin_bswap64}.
-
-@item -mshstk
-@opindex mshstk
-The @option{-mshstk} option enables shadow stack built-in functions
-from x86 Control-flow Enforcement Technology (CET).
-
-@item -mcrc32
-@opindex mcrc32
-This option enables built-in functions @code{__builtin_ia32_crc32qi},
-@code{__builtin_ia32_crc32hi}, @code{__builtin_ia32_crc32si} and
-@code{__builtin_ia32_crc32di} to generate the @code{crc32} machine instruction.
-
-@item -mmwait
-@opindex mmwait
-This option enables built-in functions @code{__builtin_ia32_monitor},
-and @code{__builtin_ia32_mwait} to generate the @code{monitor} and
-@code{mwait} machine instructions.
-
-@item -mrecip
-@opindex mrecip
-This option enables use of @code{RCPSS} and @code{RSQRTSS} instructions
-(and their vectorized variants @code{RCPPS} and @code{RSQRTPS})
-with an additional Newton-Raphson step
-to increase precision instead of @code{DIVSS} and @code{SQRTSS}
-(and their vectorized
-variants) for single-precision floating-point arguments. These instructions
-are generated only when @option{-funsafe-math-optimizations} is enabled
-together with @option{-ffinite-math-only} and @option{-fno-trapping-math}.
-Note that while the throughput of the sequence is higher than the throughput
-of the non-reciprocal instruction, the precision of the sequence can be
-decreased by up to 2 ulp (i.e.@: the inverse of 1.0 equals 0.99999994).
-
-Note that GCC implements @code{1.0f/sqrtf(@var{x})} in terms of @code{RSQRTSS}
-(or @code{RSQRTPS}) already with @option{-ffast-math} (or the above option
-combination), and doesn't need @option{-mrecip}.
-
-Also note that GCC emits the above sequence with additional Newton-Raphson step
-for vectorized single-float division and vectorized @code{sqrtf(@var{x})}
-already with @option{-ffast-math} (or the above option combination), and
-doesn't need @option{-mrecip}.
-
-@item -mrecip=@var{opt}
-@opindex mrecip=opt
-This option controls which reciprocal estimate instructions
-may be used. @var{opt} is a comma-separated list of options, which may
-be preceded by a @samp{!} to invert the option:
-
-@table @samp
-@item all
-Enable all estimate instructions.
-
-@item default
-Enable the default instructions, equivalent to @option{-mrecip}.
-
-@item none
-Disable all estimate instructions, equivalent to @option{-mno-recip}.
-
-@item div
-Enable the approximation for scalar division.
-
-@item vec-div
-Enable the approximation for vectorized division.
-
-@item sqrt
-Enable the approximation for scalar square root.
-
-@item vec-sqrt
-Enable the approximation for vectorized square root.
-@end table
-
-So, for example, @option{-mrecip=all,!sqrt} enables
-all of the reciprocal approximations, except for square root.
-
-@item -mveclibabi=@var{type}
-@opindex mveclibabi
-Specifies the ABI type to use for vectorizing intrinsics using an
-external library. Supported values for @var{type} are @samp{svml}
-for the Intel short
-vector math library and @samp{acml} for the AMD math core library.
-To use this option, both @option{-ftree-vectorize} and
-@option{-funsafe-math-optimizations} have to be enabled, and an SVML or ACML
-ABI-compatible library must be specified at link time.
-
-GCC currently emits calls to @code{vmldExp2},
-@code{vmldLn2}, @code{vmldLog102}, @code{vmldPow2},
-@code{vmldTanh2}, @code{vmldTan2}, @code{vmldAtan2}, @code{vmldAtanh2},
-@code{vmldCbrt2}, @code{vmldSinh2}, @code{vmldSin2}, @code{vmldAsinh2},
-@code{vmldAsin2}, @code{vmldCosh2}, @code{vmldCos2}, @code{vmldAcosh2},
-@code{vmldAcos2}, @code{vmlsExp4}, @code{vmlsLn4},
-@code{vmlsLog104}, @code{vmlsPow4}, @code{vmlsTanh4}, @code{vmlsTan4},
-@code{vmlsAtan4}, @code{vmlsAtanh4}, @code{vmlsCbrt4}, @code{vmlsSinh4},
-@code{vmlsSin4}, @code{vmlsAsinh4}, @code{vmlsAsin4}, @code{vmlsCosh4},
-@code{vmlsCos4}, @code{vmlsAcosh4} and @code{vmlsAcos4} for corresponding
-function type when @option{-mveclibabi=svml} is used, and @code{__vrd2_sin},
-@code{__vrd2_cos}, @code{__vrd2_exp}, @code{__vrd2_log}, @code{__vrd2_log2},
-@code{__vrd2_log10}, @code{__vrs4_sinf}, @code{__vrs4_cosf},
-@code{__vrs4_expf}, @code{__vrs4_logf}, @code{__vrs4_log2f},
-@code{__vrs4_log10f} and @code{__vrs4_powf} for the corresponding function type
-when @option{-mveclibabi=acml} is used.
-
-@item -mabi=@var{name}
-@opindex mabi
-Generate code for the specified calling convention. Permissible values
-are @samp{sysv} for the ABI used on GNU/Linux and other systems, and
-@samp{ms} for the Microsoft ABI. The default is to use the Microsoft
-ABI when targeting Microsoft Windows and the SysV ABI on all other systems.
-You can control this behavior for specific functions by
-using the function attributes @code{ms_abi} and @code{sysv_abi}.
-@xref{Function Attributes}.
-
-@item -mforce-indirect-call
-@opindex mforce-indirect-call
-Force all calls to functions to be indirect. This is useful
-when using Intel Processor Trace where it generates more precise timing
-information for function calls.
-
-@item -mmanual-endbr
-@opindex mmanual-endbr
-Insert ENDBR instruction at function entry only via the @code{cf_check}
-function attribute. This is useful when used with the option
-@option{-fcf-protection=branch} to control ENDBR insertion at the
-function entry.
-
-@item -mcet-switch
-@opindex mcet-switch
-By default, CET instrumentation is turned off on switch statements that
-use a jump table and indirect branch track is disabled. Since jump
-tables are stored in read-only memory, this does not result in a direct
-loss of hardening. But if the jump table index is attacker-controlled,
-the indirect jump may not be constrained by CET. This option turns on
-CET instrumentation to enable indirect branch track for switch statements
-with jump tables which leads to the jump targets reachable via any indirect
-jumps.
-
-@item -mcall-ms2sysv-xlogues
-@opindex mcall-ms2sysv-xlogues
-@opindex mno-call-ms2sysv-xlogues
-Due to differences in 64-bit ABIs, any Microsoft ABI function that calls a
-System V ABI function must consider RSI, RDI and XMM6-15 as clobbered. By
-default, the code for saving and restoring these registers is emitted inline,
-resulting in fairly lengthy prologues and epilogues. Using
-@option{-mcall-ms2sysv-xlogues} emits prologues and epilogues that
-use stubs in the static portion of libgcc to perform these saves and restores,
-thus reducing function size at the cost of a few extra instructions.
-
-@item -mtls-dialect=@var{type}
-@opindex mtls-dialect
-Generate code to access thread-local storage using the @samp{gnu} or
-@samp{gnu2} conventions. @samp{gnu} is the conservative default;
-@samp{gnu2} is more efficient, but it may add compile- and run-time
-requirements that cannot be satisfied on all systems.
-
-@item -mpush-args
-@itemx -mno-push-args
-@opindex mpush-args
-@opindex mno-push-args
-Use PUSH operations to store outgoing parameters. This method is shorter
-and usually equally fast as method using SUB/MOV operations and is enabled
-by default. In some cases disabling it may improve performance because of
-improved scheduling and reduced dependencies.
-
-@item -maccumulate-outgoing-args
-@opindex maccumulate-outgoing-args
-If enabled, the maximum amount of space required for outgoing arguments is
-computed in the function prologue. This is faster on most modern CPUs
-because of reduced dependencies, improved scheduling and reduced stack usage
-when the preferred stack boundary is not equal to 2. The drawback is a notable
-increase in code size. This switch implies @option{-mno-push-args}.
-
-@item -mthreads
-@opindex mthreads
-Support thread-safe exception handling on MinGW. Programs that rely
-on thread-safe exception handling must compile and link all code with the
-@option{-mthreads} option. When compiling, @option{-mthreads} defines
-@option{-D_MT}; when linking, it links in a special thread helper library
-@option{-lmingwthrd} which cleans up per-thread exception-handling data.
-
-@item -mms-bitfields
-@itemx -mno-ms-bitfields
-@opindex mms-bitfields
-@opindex mno-ms-bitfields
-
-Enable/disable bit-field layout compatible with the native Microsoft
-Windows compiler.
-
-If @code{packed} is used on a structure, or if bit-fields are used,
-it may be that the Microsoft ABI lays out the structure differently
-than the way GCC normally does. Particularly when moving packed
-data between functions compiled with GCC and the native Microsoft compiler
-(either via function call or as data in a file), it may be necessary to access
-either format.
-
-This option is enabled by default for Microsoft Windows
-targets. This behavior can also be controlled locally by use of variable
-or type attributes. For more information, see @ref{x86 Variable Attributes}
-and @ref{x86 Type Attributes}.
-
-The Microsoft structure layout algorithm is fairly simple with the exception
-of the bit-field packing.
-The padding and alignment of members of structures and whether a bit-field
-can straddle a storage-unit boundary are determine by these rules:
-
-@enumerate
-@item Structure members are stored sequentially in the order in which they are
-declared: the first member has the lowest memory address and the last member
-the highest.
-
-@item Every data object has an alignment requirement. The alignment requirement
-for all data except structures, unions, and arrays is either the size of the
-object or the current packing size (specified with either the
-@code{aligned} attribute or the @code{pack} pragma),
-whichever is less. For structures, unions, and arrays,
-the alignment requirement is the largest alignment requirement of its members.
-Every object is allocated an offset so that:
-
-@smallexample
-offset % alignment_requirement == 0
-@end smallexample
-
-@item Adjacent bit-fields are packed into the same 1-, 2-, or 4-byte allocation
-unit if the integral types are the same size and if the next bit-field fits
-into the current allocation unit without crossing the boundary imposed by the
-common alignment requirements of the bit-fields.
-@end enumerate
-
-MSVC interprets zero-length bit-fields in the following ways:
-
-@enumerate
-@item If a zero-length bit-field is inserted between two bit-fields that
-are normally coalesced, the bit-fields are not coalesced.
-
-For example:
-
-@smallexample
-struct
- @{
- unsigned long bf_1 : 12;
- unsigned long : 0;
- unsigned long bf_2 : 12;
- @} t1;
-@end smallexample
-
-@noindent
-The size of @code{t1} is 8 bytes with the zero-length bit-field. If the
-zero-length bit-field were removed, @code{t1}'s size would be 4 bytes.
-
-@item If a zero-length bit-field is inserted after a bit-field, @code{foo}, and the
-alignment of the zero-length bit-field is greater than the member that follows it,
-@code{bar}, @code{bar} is aligned as the type of the zero-length bit-field.
-
-For example:
-
-@smallexample
-struct
- @{
- char foo : 4;
- short : 0;
- char bar;
- @} t2;
-
-struct
- @{
- char foo : 4;
- short : 0;
- double bar;
- @} t3;
-@end smallexample
-
-@noindent
-For @code{t2}, @code{bar} is placed at offset 2, rather than offset 1.
-Accordingly, the size of @code{t2} is 4. For @code{t3}, the zero-length
-bit-field does not affect the alignment of @code{bar} or, as a result, the size
-of the structure.
-
-Taking this into account, it is important to note the following:
-
-@enumerate
-@item If a zero-length bit-field follows a normal bit-field, the type of the
-zero-length bit-field may affect the alignment of the structure as whole. For
-example, @code{t2} has a size of 4 bytes, since the zero-length bit-field follows a
-normal bit-field, and is of type short.
-
-@item Even if a zero-length bit-field is not followed by a normal bit-field, it may
-still affect the alignment of the structure:
-
-@smallexample
-struct
- @{
- char foo : 6;
- long : 0;
- @} t4;
-@end smallexample
-
-@noindent
-Here, @code{t4} takes up 4 bytes.
-@end enumerate
-
-@item Zero-length bit-fields following non-bit-field members are ignored:
-
-@smallexample
-struct
- @{
- char foo;
- long : 0;
- char bar;
- @} t5;
-@end smallexample
-
-@noindent
-Here, @code{t5} takes up 2 bytes.
-@end enumerate
-
-
-@item -mno-align-stringops
-@opindex mno-align-stringops
-@opindex malign-stringops
-Do not align the destination of inlined string operations. This switch reduces
-code size and improves performance in case the destination is already aligned,
-but GCC doesn't know about it.
-
-@item -minline-all-stringops
-@opindex minline-all-stringops
-By default GCC inlines string operations only when the destination is
-known to be aligned to least a 4-byte boundary.
-This enables more inlining and increases code
-size, but may improve performance of code that depends on fast
-@code{memcpy} and @code{memset} for short lengths.
-The option enables inline expansion of @code{strlen} for all
-pointer alignments.
-
-@item -minline-stringops-dynamically
-@opindex minline-stringops-dynamically
-For string operations of unknown size, use run-time checks with
-inline code for small blocks and a library call for large blocks.
-
-@item -mstringop-strategy=@var{alg}
-@opindex mstringop-strategy=@var{alg}
-Override the internal decision heuristic for the particular algorithm to use
-for inlining string operations. The allowed values for @var{alg} are:
-
-@table @samp
-@item rep_byte
-@itemx rep_4byte
-@itemx rep_8byte
-Expand using i386 @code{rep} prefix of the specified size.
-
-@item byte_loop
-@itemx loop
-@itemx unrolled_loop
-Expand into an inline loop.
-
-@item libcall
-Always use a library call.
-@end table
-
-@item -mmemcpy-strategy=@var{strategy}
-@opindex mmemcpy-strategy=@var{strategy}
-Override the internal decision heuristic to decide if @code{__builtin_memcpy}
-should be inlined and what inline algorithm to use when the expected size
-of the copy operation is known. @var{strategy}
-is a comma-separated list of @var{alg}:@var{max_size}:@var{dest_align} triplets.
-@var{alg} is specified in @option{-mstringop-strategy}, @var{max_size} specifies
-the max byte size with which inline algorithm @var{alg} is allowed. For the last
-triplet, the @var{max_size} must be @code{-1}. The @var{max_size} of the triplets
-in the list must be specified in increasing order. The minimal byte size for
-@var{alg} is @code{0} for the first triplet and @code{@var{max_size} + 1} of the
-preceding range.
-
-@item -mmemset-strategy=@var{strategy}
-@opindex mmemset-strategy=@var{strategy}
-The option is similar to @option{-mmemcpy-strategy=} except that it is to control
-@code{__builtin_memset} expansion.
-
-@item -momit-leaf-frame-pointer
-@opindex momit-leaf-frame-pointer
-Don't keep the frame pointer in a register for leaf functions. This
-avoids the instructions to save, set up, and restore frame pointers and
-makes an extra register available in leaf functions. The option
-@option{-fomit-leaf-frame-pointer} removes the frame pointer for leaf functions,
-which might make debugging harder.
-
-@item -mtls-direct-seg-refs
-@itemx -mno-tls-direct-seg-refs
-@opindex mtls-direct-seg-refs
-Controls whether TLS variables may be accessed with offsets from the
-TLS segment register (@code{%gs} for 32-bit, @code{%fs} for 64-bit),
-or whether the thread base pointer must be added. Whether or not this
-is valid depends on the operating system, and whether it maps the
-segment to cover the entire TLS area.
-
-For systems that use the GNU C Library, the default is on.
-
-@item -msse2avx
-@itemx -mno-sse2avx
-@opindex msse2avx
-Specify that the assembler should encode SSE instructions with VEX
-prefix. The option @option{-mavx} turns this on by default.
-
-@item -mfentry
-@itemx -mno-fentry
-@opindex mfentry
-If profiling is active (@option{-pg}), put the profiling
-counter call before the prologue.
-Note: On x86 architectures the attribute @code{ms_hook_prologue}
-isn't possible at the moment for @option{-mfentry} and @option{-pg}.
-
-@item -mrecord-mcount
-@itemx -mno-record-mcount
-@opindex mrecord-mcount
-If profiling is active (@option{-pg}), generate a __mcount_loc section
-that contains pointers to each profiling call. This is useful for
-automatically patching and out calls.
-
-@item -mnop-mcount
-@itemx -mno-nop-mcount
-@opindex mnop-mcount
-If profiling is active (@option{-pg}), generate the calls to
-the profiling functions as NOPs. This is useful when they
-should be patched in later dynamically. This is likely only
-useful together with @option{-mrecord-mcount}.
-
-@item -minstrument-return=@var{type}
-@opindex minstrument-return
-Instrument function exit in -pg -mfentry instrumented functions with
-call to specified function. This only instruments true returns ending
-with ret, but not sibling calls ending with jump. Valid types
-are @var{none} to not instrument, @var{call} to generate a call to __return__,
-or @var{nop5} to generate a 5 byte nop.
-
-@item -mrecord-return
-@itemx -mno-record-return
-@opindex mrecord-return
-Generate a __return_loc section pointing to all return instrumentation code.
-
-@item -mfentry-name=@var{name}
-@opindex mfentry-name
-Set name of __fentry__ symbol called at function entry for -pg -mfentry functions.
-
-@item -mfentry-section=@var{name}
-@opindex mfentry-section
-Set name of section to record -mrecord-mcount calls (default __mcount_loc).
-
-@item -mskip-rax-setup
-@itemx -mno-skip-rax-setup
-@opindex mskip-rax-setup
-When generating code for the x86-64 architecture with SSE extensions
-disabled, @option{-mskip-rax-setup} can be used to skip setting up RAX
-register when there are no variable arguments passed in vector registers.
-
-@strong{Warning:} Since RAX register is used to avoid unnecessarily
-saving vector registers on stack when passing variable arguments, the
-impacts of this option are callees may waste some stack space,
-misbehave or jump to a random location. GCC 4.4 or newer don't have
-those issues, regardless the RAX register value.
-
-@item -m8bit-idiv
-@itemx -mno-8bit-idiv
-@opindex m8bit-idiv
-On some processors, like Intel Atom, 8-bit unsigned integer divide is
-much faster than 32-bit/64-bit integer divide. This option generates a
-run-time check. If both dividend and divisor are within range of 0
-to 255, 8-bit unsigned integer divide is used instead of
-32-bit/64-bit integer divide.
-
-@item -mavx256-split-unaligned-load
-@itemx -mavx256-split-unaligned-store
-@opindex mavx256-split-unaligned-load
-@opindex mavx256-split-unaligned-store
-Split 32-byte AVX unaligned load and store.
-
-@item -mstack-protector-guard=@var{guard}
-@itemx -mstack-protector-guard-reg=@var{reg}
-@itemx -mstack-protector-guard-offset=@var{offset}
-@opindex mstack-protector-guard
-@opindex mstack-protector-guard-reg
-@opindex mstack-protector-guard-offset
-Generate stack protection code using canary at @var{guard}. Supported
-locations are @samp{global} for global canary or @samp{tls} for per-thread
-canary in the TLS block (the default). This option has effect only when
-@option{-fstack-protector} or @option{-fstack-protector-all} is specified.
-
-With the latter choice the options
-@option{-mstack-protector-guard-reg=@var{reg}} and
-@option{-mstack-protector-guard-offset=@var{offset}} furthermore specify
-which segment register (@code{%fs} or @code{%gs}) to use as base register
-for reading the canary, and from what offset from that base register.
-The default for those is as specified in the relevant ABI.
-
-@item -mgeneral-regs-only
-@opindex mgeneral-regs-only
-Generate code that uses only the general-purpose registers. This
-prevents the compiler from using floating-point, vector, mask and bound
-registers.
-
-@item -mrelax-cmpxchg-loop
-@opindex mrelax-cmpxchg-loop
-Relax cmpxchg loop by emitting an early load and compare before cmpxchg,
-execute pause if load value is not expected. This reduces excessive
-cachline bouncing when and works for all atomic logic fetch builtins
-that generates compare and swap loop.
-
-@item -mindirect-branch=@var{choice}
-@opindex mindirect-branch
-Convert indirect call and jump with @var{choice}. The default is
-@samp{keep}, which keeps indirect call and jump unmodified.
-@samp{thunk} converts indirect call and jump to call and return thunk.
-@samp{thunk-inline} converts indirect call and jump to inlined call
-and return thunk. @samp{thunk-extern} converts indirect call and jump
-to external call and return thunk provided in a separate object file.
-You can control this behavior for a specific function by using the
-function attribute @code{indirect_branch}. @xref{Function Attributes}.
-
-Note that @option{-mcmodel=large} is incompatible with
-@option{-mindirect-branch=thunk} and
-@option{-mindirect-branch=thunk-extern} since the thunk function may
-not be reachable in the large code model.
-
-Note that @option{-mindirect-branch=thunk-extern} is compatible with
-@option{-fcf-protection=branch} since the external thunk can be made
-to enable control-flow check.
-
-@item -mfunction-return=@var{choice}
-@opindex mfunction-return
-Convert function return with @var{choice}. The default is @samp{keep},
-which keeps function return unmodified. @samp{thunk} converts function
-return to call and return thunk. @samp{thunk-inline} converts function
-return to inlined call and return thunk. @samp{thunk-extern} converts
-function return to external call and return thunk provided in a separate
-object file. You can control this behavior for a specific function by
-using the function attribute @code{function_return}.
-@xref{Function Attributes}.
-
-Note that @option{-mindirect-return=thunk-extern} is compatible with
-@option{-fcf-protection=branch} since the external thunk can be made
-to enable control-flow check.
-
-Note that @option{-mcmodel=large} is incompatible with
-@option{-mfunction-return=thunk} and
-@option{-mfunction-return=thunk-extern} since the thunk function may
-not be reachable in the large code model.
-
-
-@item -mindirect-branch-register
-@opindex mindirect-branch-register
-Force indirect call and jump via register.
-
-@item -mharden-sls=@var{choice}
-@opindex mharden-sls
-Generate code to mitigate against straight line speculation (SLS) with
-@var{choice}. The default is @samp{none} which disables all SLS
-hardening. @samp{return} enables SLS hardening for function returns.
-@samp{indirect-jmp} enables SLS hardening for indirect jumps.
-@samp{all} enables all SLS hardening.
-
-@item -mindirect-branch-cs-prefix
-@opindex mindirect-branch-cs-prefix
-Add CS prefix to call and jmp to indirect thunk with branch target in
-r8-r15 registers so that the call and jmp instruction length is 6 bytes
-to allow them to be replaced with @samp{lfence; call *%r8-r15} or
-@samp{lfence; jmp *%r8-r15} at run-time.
-
-@end table
-
-These @samp{-m} switches are supported in addition to the above
-on x86-64 processors in 64-bit environments.
-
-@table @gcctabopt
-@item -m32
-@itemx -m64
-@itemx -mx32
-@itemx -m16
-@itemx -miamcu
-@opindex m32
-@opindex m64
-@opindex mx32
-@opindex m16
-@opindex miamcu
-Generate code for a 16-bit, 32-bit or 64-bit environment.
-The @option{-m32} option sets @code{int}, @code{long}, and pointer types
-to 32 bits, and
-generates code that runs on any i386 system.
-
-The @option{-m64} option sets @code{int} to 32 bits and @code{long} and pointer
-types to 64 bits, and generates code for the x86-64 architecture.
-For Darwin only the @option{-m64} option also turns off the @option{-fno-pic}
-and @option{-mdynamic-no-pic} options.
-
-The @option{-mx32} option sets @code{int}, @code{long}, and pointer types
-to 32 bits, and
-generates code for the x86-64 architecture.
-
-The @option{-m16} option is the same as @option{-m32}, except for that
-it outputs the @code{.code16gcc} assembly directive at the beginning of
-the assembly output so that the binary can run in 16-bit mode.
-
-The @option{-miamcu} option generates code which conforms to Intel MCU
-psABI. It requires the @option{-m32} option to be turned on.
-
-@item -mno-red-zone
-@opindex mno-red-zone
-@opindex mred-zone
-Do not use a so-called ``red zone'' for x86-64 code. The red zone is mandated
-by the x86-64 ABI; it is a 128-byte area beyond the location of the
-stack pointer that is not modified by signal or interrupt handlers
-and therefore can be used for temporary data without adjusting the stack
-pointer. The flag @option{-mno-red-zone} disables this red zone.
-
-@item -mcmodel=small
-@opindex mcmodel=small
-Generate code for the small code model: the program and its symbols must
-be linked in the lower 2 GB of the address space. Pointers are 64 bits.
-Programs can be statically or dynamically linked. This is the default
-code model.
-
-@item -mcmodel=kernel
-@opindex mcmodel=kernel
-Generate code for the kernel code model. The kernel runs in the
-negative 2 GB of the address space.
-This model has to be used for Linux kernel code.
-
-@item -mcmodel=medium
-@opindex mcmodel=medium
-Generate code for the medium model: the program is linked in the lower 2
-GB of the address space. Small symbols are also placed there. Symbols
-with sizes larger than @option{-mlarge-data-threshold} are put into
-large data or BSS sections and can be located above 2GB. Programs can
-be statically or dynamically linked.
-
-@item -mcmodel=large
-@opindex mcmodel=large
-Generate code for the large model. This model makes no assumptions
-about addresses and sizes of sections.
-
-@item -maddress-mode=long
-@opindex maddress-mode=long
-Generate code for long address mode. This is only supported for 64-bit
-and x32 environments. It is the default address mode for 64-bit
-environments.
-
-@item -maddress-mode=short
-@opindex maddress-mode=short
-Generate code for short address mode. This is only supported for 32-bit
-and x32 environments. It is the default address mode for 32-bit and
-x32 environments.
-
-@item -mneeded
-@itemx -mno-needed
-@opindex mneeded
-Emit GNU_PROPERTY_X86_ISA_1_NEEDED GNU property for Linux target to
-indicate the micro-architecture ISA level required to execute the binary.
-
-@item -mno-direct-extern-access
-@opindex mno-direct-extern-access
-@opindex mdirect-extern-access
-Without @option{-fpic} nor @option{-fPIC}, always use the GOT pointer
-to access external symbols. With @option{-fpic} or @option{-fPIC},
-treat access to protected symbols as local symbols. The default is
-@option{-mdirect-extern-access}.
-
-@strong{Warning:} shared libraries compiled with
-@option{-mno-direct-extern-access} and executable compiled with
-@option{-mdirect-extern-access} may not be binary compatible if
-protected symbols are used in shared libraries and executable.
-@end table
-
-@node x86 Windows Options
-@subsection x86 Windows Options
-@cindex x86 Windows Options
-@cindex Windows Options for x86
-
-These additional options are available for Microsoft Windows targets:
-
-@table @gcctabopt
-@item -mconsole
-@opindex mconsole
-This option
-specifies that a console application is to be generated, by
-instructing the linker to set the PE header subsystem type
-required for console applications.
-This option is available for Cygwin and MinGW targets and is
-enabled by default on those targets.
-
-@item -mdll
-@opindex mdll
-This option is available for Cygwin and MinGW targets. It
-specifies that a DLL---a dynamic link library---is to be
-generated, enabling the selection of the required runtime
-startup object and entry point.
-
-@item -mnop-fun-dllimport
-@opindex mnop-fun-dllimport
-This option is available for Cygwin and MinGW targets. It
-specifies that the @code{dllimport} attribute should be ignored.
-
-@item -mthreads
-@opindex mthreads
-This option is available for MinGW targets. It specifies
-that MinGW-specific thread support is to be used.
-
-@item -municode
-@opindex municode
-This option is available for MinGW-w64 targets. It causes
-the @code{UNICODE} preprocessor macro to be predefined, and
-chooses Unicode-capable runtime startup code.
-
-@item -mwin32
-@opindex mwin32
-This option is available for Cygwin and MinGW targets. It
-specifies that the typical Microsoft Windows predefined macros are to
-be set in the pre-processor, but does not influence the choice
-of runtime library/startup code.
-
-@item -mwindows
-@opindex mwindows
-This option is available for Cygwin and MinGW targets. It
-specifies that a GUI application is to be generated by
-instructing the linker to set the PE header subsystem type
-appropriately.
-
-@item -fno-set-stack-executable
-@opindex fno-set-stack-executable
-@opindex fset-stack-executable
-This option is available for MinGW targets. It specifies that
-the executable flag for the stack used by nested functions isn't
-set. This is necessary for binaries running in kernel mode of
-Microsoft Windows, as there the User32 API, which is used to set executable
-privileges, isn't available.
-
-@item -fwritable-relocated-rdata
-@opindex fno-writable-relocated-rdata
-@opindex fwritable-relocated-rdata
-This option is available for MinGW and Cygwin targets. It specifies
-that relocated-data in read-only section is put into the @code{.data}
-section. This is a necessary for older runtimes not supporting
-modification of @code{.rdata} sections for pseudo-relocation.
-
-@item -mpe-aligned-commons
-@opindex mpe-aligned-commons
-This option is available for Cygwin and MinGW targets. It
-specifies that the GNU extension to the PE file format that
-permits the correct alignment of COMMON variables should be
-used when generating code. It is enabled by default if
-GCC detects that the target assembler found during configuration
-supports the feature.
-@end table
-
-See also under @ref{x86 Options} for standard options.
-
-@node Xstormy16 Options
-@subsection Xstormy16 Options
-@cindex Xstormy16 Options
-
-These options are defined for Xstormy16:
-
-@table @gcctabopt
-@item -msim
-@opindex msim
-Choose startup files and linker script suitable for the simulator.
-@end table
-
-@node Xtensa Options
-@subsection Xtensa Options
-@cindex Xtensa Options
-
-These options are supported for Xtensa targets:
-
-@table @gcctabopt
-@item -mconst16
-@itemx -mno-const16
-@opindex mconst16
-@opindex mno-const16
-Enable or disable use of @code{CONST16} instructions for loading
-constant values. The @code{CONST16} instruction is currently not a
-standard option from Tensilica. When enabled, @code{CONST16}
-instructions are always used in place of the standard @code{L32R}
-instructions. The use of @code{CONST16} is enabled by default only if
-the @code{L32R} instruction is not available.
-
-@item -mfused-madd
-@itemx -mno-fused-madd
-@opindex mfused-madd
-@opindex mno-fused-madd
-Enable or disable use of fused multiply/add and multiply/subtract
-instructions in the floating-point option. This has no effect if the
-floating-point option is not also enabled. Disabling fused multiply/add
-and multiply/subtract instructions forces the compiler to use separate
-instructions for the multiply and add/subtract operations. This may be
-desirable in some cases where strict IEEE 754-compliant results are
-required: the fused multiply add/subtract instructions do not round the
-intermediate result, thereby producing results with @emph{more} bits of
-precision than specified by the IEEE standard. Disabling fused multiply
-add/subtract instructions also ensures that the program output is not
-sensitive to the compiler's ability to combine multiply and add/subtract
-operations.
-
-@item -mserialize-volatile
-@itemx -mno-serialize-volatile
-@opindex mserialize-volatile
-@opindex mno-serialize-volatile
-When this option is enabled, GCC inserts @code{MEMW} instructions before
-@code{volatile} memory references to guarantee sequential consistency.
-The default is @option{-mserialize-volatile}. Use
-@option{-mno-serialize-volatile} to omit the @code{MEMW} instructions.
-
-@item -mforce-no-pic
-@opindex mforce-no-pic
-For targets, like GNU/Linux, where all user-mode Xtensa code must be
-position-independent code (PIC), this option disables PIC for compiling
-kernel code.
-
-@item -mtext-section-literals
-@itemx -mno-text-section-literals
-@opindex mtext-section-literals
-@opindex mno-text-section-literals
-These options control the treatment of literal pools. The default is
-@option{-mno-text-section-literals}, which places literals in a separate
-section in the output file. This allows the literal pool to be placed
-in a data RAM/ROM, and it also allows the linker to combine literal
-pools from separate object files to remove redundant literals and
-improve code size. With @option{-mtext-section-literals}, the literals
-are interspersed in the text section in order to keep them as close as
-possible to their references. This may be necessary for large assembly
-files. Literals for each function are placed right before that function.
-
-@item -mauto-litpools
-@itemx -mno-auto-litpools
-@opindex mauto-litpools
-@opindex mno-auto-litpools
-These options control the treatment of literal pools. The default is
-@option{-mno-auto-litpools}, which places literals in a separate
-section in the output file unless @option{-mtext-section-literals} is
-used. With @option{-mauto-litpools} the literals are interspersed in
-the text section by the assembler. Compiler does not produce explicit
-@code{.literal} directives and loads literals into registers with
-@code{MOVI} instructions instead of @code{L32R} to let the assembler
-do relaxation and place literals as necessary. This option allows
-assembler to create several literal pools per function and assemble
-very big functions, which may not be possible with
-@option{-mtext-section-literals}.
-
-@item -mtarget-align
-@itemx -mno-target-align
-@opindex mtarget-align
-@opindex mno-target-align
-When this option is enabled, GCC instructs the assembler to
-automatically align instructions to reduce branch penalties at the
-expense of some code density. The assembler attempts to widen density
-instructions to align branch targets and the instructions following call
-instructions. If there are not enough preceding safe density
-instructions to align a target, no widening is performed. The
-default is @option{-mtarget-align}. These options do not affect the
-treatment of auto-aligned instructions like @code{LOOP}, which the
-assembler always aligns, either by widening density instructions or
-by inserting NOP instructions.
-
-@item -mlongcalls
-@itemx -mno-longcalls
-@opindex mlongcalls
-@opindex mno-longcalls
-When this option is enabled, GCC instructs the assembler to translate
-direct calls to indirect calls unless it can determine that the target
-of a direct call is in the range allowed by the call instruction. This
-translation typically occurs for calls to functions in other source
-files. Specifically, the assembler translates a direct @code{CALL}
-instruction into an @code{L32R} followed by a @code{CALLX} instruction.
-The default is @option{-mno-longcalls}. This option should be used in
-programs where the call target can potentially be out of range. This
-option is implemented in the assembler, not the compiler, so the
-assembly code generated by GCC still shows direct call
-instructions---look at the disassembled object code to see the actual
-instructions. Note that the assembler uses an indirect call for
-every cross-file call, not just those that really are out of range.
-
-@item -mabi=@var{name}
-@opindex mabi
-Generate code for the specified ABI@. Permissible values are: @samp{call0},
-@samp{windowed}. Default ABI is chosen by the Xtensa core configuration.
-
-@item -mabi=call0
-@opindex mabi=call0
-When this option is enabled function parameters are passed in registers
-@code{a2} through @code{a7}, registers @code{a12} through @code{a15} are
-caller-saved, and register @code{a15} may be used as a frame pointer.
-When this version of the ABI is enabled the C preprocessor symbol
-@code{__XTENSA_CALL0_ABI__} is defined.
-
-@item -mabi=windowed
-@opindex mabi=windowed
-When this option is enabled function parameters are passed in registers
-@code{a10} through @code{a15}, and called function rotates register window
-by 8 registers on entry so that its arguments are found in registers
-@code{a2} through @code{a7}. Register @code{a7} may be used as a frame
-pointer. Register window is rotated 8 registers back upon return.
-When this version of the ABI is enabled the C preprocessor symbol
-@code{__XTENSA_WINDOWED_ABI__} is defined.
-
-@item -mextra-l32r-costs=@var{n}
-@opindex mextra-l32r-costs
-Specify an extra cost of instruction RAM/ROM access for @code{L32R}
-instructions, in clock cycles. This affects, when optimizing for speed,
-whether loading a constant from literal pool using @code{L32R} or
-synthesizing the constant from a small one with a couple of arithmetic
-instructions. The default value is 0.
-@end table
-
-@node zSeries Options
-@subsection zSeries Options
-@cindex zSeries options
-
-These are listed under @xref{S/390 and zSeries Options}.
-
-
-@c man end
-
-@node Spec Files
-@section Specifying Subprocesses and the Switches to Pass to Them
-@cindex Spec Files
-
-@command{gcc} is a driver program. It performs its job by invoking a
-sequence of other programs to do the work of compiling, assembling and
-linking. GCC interprets its command-line parameters and uses these to
-deduce which programs it should invoke, and which command-line options
-it ought to place on their command lines. This behavior is controlled
-by @dfn{spec strings}. In most cases there is one spec string for each
-program that GCC can invoke, but a few programs have multiple spec
-strings to control their behavior. The spec strings built into GCC can
-be overridden by using the @option{-specs=} command-line switch to specify
-a spec file.
-
-@dfn{Spec files} are plain-text files that are used to construct spec
-strings. They consist of a sequence of directives separated by blank
-lines. The type of directive is determined by the first non-whitespace
-character on the line, which can be one of the following:
-
-@table @code
-@item %@var{command}
-Issues a @var{command} to the spec file processor. The commands that can
-appear here are:
-
-@table @code
-@item %include <@var{file}>
-@cindex @code{%include}
-Search for @var{file} and insert its text at the current point in the
-specs file.
-
-@item %include_noerr <@var{file}>
-@cindex @code{%include_noerr}
-Just like @samp{%include}, but do not generate an error message if the include
-file cannot be found.
-
-@item %rename @var{old_name} @var{new_name}
-@cindex @code{%rename}
-Rename the spec string @var{old_name} to @var{new_name}.
-
-@end table
-
-@item *[@var{spec_name}]:
-This tells the compiler to create, override or delete the named spec
-string. All lines after this directive up to the next directive or
-blank line are considered to be the text for the spec string. If this
-results in an empty string then the spec is deleted. (Or, if the
-spec did not exist, then nothing happens.) Otherwise, if the spec
-does not currently exist a new spec is created. If the spec does
-exist then its contents are overridden by the text of this
-directive, unless the first character of that text is the @samp{+}
-character, in which case the text is appended to the spec.
-
-@item [@var{suffix}]:
-Creates a new @samp{[@var{suffix}] spec} pair. All lines after this directive
-and up to the next directive or blank line are considered to make up the
-spec string for the indicated suffix. When the compiler encounters an
-input file with the named suffix, it processes the spec string in
-order to work out how to compile that file. For example:
-
-@smallexample
-.ZZ:
-z-compile -input %i
-@end smallexample
-
-This says that any input file whose name ends in @samp{.ZZ} should be
-passed to the program @samp{z-compile}, which should be invoked with the
-command-line switch @option{-input} and with the result of performing the
-@samp{%i} substitution. (See below.)
-
-As an alternative to providing a spec string, the text following a
-suffix directive can be one of the following:
-
-@table @code
-@item @@@var{language}
-This says that the suffix is an alias for a known @var{language}. This is
-similar to using the @option{-x} command-line switch to GCC to specify a
-language explicitly. For example:
-
-@smallexample
-.ZZ:
-@@c++
-@end smallexample
-
-Says that .ZZ files are, in fact, C++ source files.
-
-@item #@var{name}
-This causes an error messages saying:
-
-@smallexample
-@var{name} compiler not installed on this system.
-@end smallexample
-@end table
-
-GCC already has an extensive list of suffixes built into it.
-This directive adds an entry to the end of the list of suffixes, but
-since the list is searched from the end backwards, it is effectively
-possible to override earlier entries using this technique.
-
-@end table
-
-GCC has the following spec strings built into it. Spec files can
-override these strings or create their own. Note that individual
-targets can also add their own spec strings to this list.
-
-@smallexample
-asm Options to pass to the assembler
-asm_final Options to pass to the assembler post-processor
-cpp Options to pass to the C preprocessor
-cc1 Options to pass to the C compiler
-cc1plus Options to pass to the C++ compiler
-endfile Object files to include at the end of the link
-link Options to pass to the linker
-lib Libraries to include on the command line to the linker
-libgcc Decides which GCC support library to pass to the linker
-linker Sets the name of the linker
-predefines Defines to be passed to the C preprocessor
-signed_char Defines to pass to CPP to say whether @code{char} is signed
- by default
-startfile Object files to include at the start of the link
-@end smallexample
-
-Here is a small example of a spec file:
-
-@smallexample
-%rename lib old_lib
-
-*lib:
---start-group -lgcc -lc -leval1 --end-group %(old_lib)
-@end smallexample
-
-This example renames the spec called @samp{lib} to @samp{old_lib} and
-then overrides the previous definition of @samp{lib} with a new one.
-The new definition adds in some extra command-line options before
-including the text of the old definition.
-
-@dfn{Spec strings} are a list of command-line options to be passed to their
-corresponding program. In addition, the spec strings can contain
-@samp{%}-prefixed sequences to substitute variable text or to
-conditionally insert text into the command line. Using these constructs
-it is possible to generate quite complex command lines.
-
-Here is a table of all defined @samp{%}-sequences for spec
-strings. Note that spaces are not generated automatically around the
-results of expanding these sequences. Therefore you can concatenate them
-together or combine them with constant text in a single argument.
-
-@table @code
-@item %%
-Substitute one @samp{%} into the program name or argument.
-
-@item %"
-Substitute an empty argument.
-
-@item %i
-Substitute the name of the input file being processed.
-
-@item %b
-Substitute the basename for outputs related with the input file being
-processed. This is often the substring up to (and not including) the
-last period and not including the directory but, unless %w is active, it
-expands to the basename for auxiliary outputs, which may be influenced
-by an explicit output name, and by various other options that control
-how auxiliary outputs are named.
-
-@item %B
-This is the same as @samp{%b}, but include the file suffix (text after
-the last period). Without %w, it expands to the basename for dump
-outputs.
-
-@item %d
-Marks the argument containing or following the @samp{%d} as a
-temporary file name, so that that file is deleted if GCC exits
-successfully. Unlike @samp{%g}, this contributes no text to the
-argument.
-
-@item %g@var{suffix}
-Substitute a file name that has suffix @var{suffix} and is chosen
-once per compilation, and mark the argument in the same way as
-@samp{%d}. To reduce exposure to denial-of-service attacks, the file
-name is now chosen in a way that is hard to predict even when previously
-chosen file names are known. For example, @samp{%g.s @dots{} %g.o @dots{} %g.s}
-might turn into @samp{ccUVUUAU.s ccXYAXZ12.o ccUVUUAU.s}. @var{suffix} matches
-the regexp @samp{[.A-Za-z]*} or the special string @samp{%O}, which is
-treated exactly as if @samp{%O} had been preprocessed. Previously, @samp{%g}
-was simply substituted with a file name chosen once per compilation,
-without regard to any appended suffix (which was therefore treated
-just like ordinary text), making such attacks more likely to succeed.
-
-@item %u@var{suffix}
-Like @samp{%g}, but generates a new temporary file name
-each time it appears instead of once per compilation.
-
-@item %U@var{suffix}
-Substitutes the last file name generated with @samp{%u@var{suffix}}, generating a
-new one if there is no such last file name. In the absence of any
-@samp{%u@var{suffix}}, this is just like @samp{%g@var{suffix}}, except they don't share
-the same suffix @emph{space}, so @samp{%g.s @dots{} %U.s @dots{} %g.s @dots{} %U.s}
-involves the generation of two distinct file names, one
-for each @samp{%g.s} and another for each @samp{%U.s}. Previously, @samp{%U} was
-simply substituted with a file name chosen for the previous @samp{%u},
-without regard to any appended suffix.
-
-@item %j@var{suffix}
-Substitutes the name of the @code{HOST_BIT_BUCKET}, if any, and if it is
-writable, and if @option{-save-temps} is not used;
-otherwise, substitute the name
-of a temporary file, just like @samp{%u}. This temporary file is not
-meant for communication between processes, but rather as a junk
-disposal mechanism.
-
-@item %|@var{suffix}
-@itemx %m@var{suffix}
-Like @samp{%g}, except if @option{-pipe} is in effect. In that case
-@samp{%|} substitutes a single dash and @samp{%m} substitutes nothing at
-all. These are the two most common ways to instruct a program that it
-should read from standard input or write to standard output. If you
-need something more elaborate you can use an @samp{%@{pipe:@code{X}@}}
-construct: see for example @file{gcc/fortran/lang-specs.h}.
-
-@item %.@var{SUFFIX}
-Substitutes @var{.SUFFIX} for the suffixes of a matched switch's args
-when it is subsequently output with @samp{%*}. @var{SUFFIX} is
-terminated by the next space or %.
-
-@item %w
-Marks the argument containing or following the @samp{%w} as the
-designated output file of this compilation. This puts the argument
-into the sequence of arguments that @samp{%o} substitutes.
-
-@item %V
-Indicates that this compilation produces no output file.
-
-@item %o
-Substitutes the names of all the output files, with spaces
-automatically placed around them. You should write spaces
-around the @samp{%o} as well or the results are undefined.
-@samp{%o} is for use in the specs for running the linker.
-Input files whose names have no recognized suffix are not compiled
-at all, but they are included among the output files, so they are
-linked.
-
-@item %O
-Substitutes the suffix for object files. Note that this is
-handled specially when it immediately follows @samp{%g, %u, or %U},
-because of the need for those to form complete file names. The
-handling is such that @samp{%O} is treated exactly as if it had already
-been substituted, except that @samp{%g, %u, and %U} do not currently
-support additional @var{suffix} characters following @samp{%O} as they do
-following, for example, @samp{.o}.
-
-@item %I
-Substitute any of @option{-iprefix} (made from @env{GCC_EXEC_PREFIX}),
-@option{-isysroot} (made from @env{TARGET_SYSTEM_ROOT}),
-@option{-isystem} (made from @env{COMPILER_PATH} and @option{-B} options)
-and @option{-imultilib} as necessary.
-
-@item %s
-Current argument is the name of a library or startup file of some sort.
-Search for that file in a standard list of directories and substitute
-the full name found. The current working directory is included in the
-list of directories scanned.
-
-@item %T
-Current argument is the name of a linker script. Search for that file
-in the current list of directories to scan for libraries. If the file
-is located insert a @option{--script} option into the command line
-followed by the full path name found. If the file is not found then
-generate an error message. Note: the current working directory is not
-searched.
-
-@item %e@var{str}
-Print @var{str} as an error message. @var{str} is terminated by a newline.
-Use this when inconsistent options are detected.
-
-@item %n@var{str}
-Print @var{str} as a notice. @var{str} is terminated by a newline.
-
-@item %(@var{name})
-Substitute the contents of spec string @var{name} at this point.
-
-@item %x@{@var{option}@}
-Accumulate an option for @samp{%X}.
-
-@item %X
-Output the accumulated linker options specified by a @samp{%x} spec string.
-
-@item %Y
-Output the accumulated assembler options specified by @option{-Wa}.
-
-@item %Z
-Output the accumulated preprocessor options specified by @option{-Wp}.
-
-@item %M
-Output @code{multilib_os_dir}.
-
-@item %R
-Output the concatenation of @code{target_system_root} and @code{target_sysroot_suffix}.
-
-@item %a
-Process the @code{asm} spec. This is used to compute the
-switches to be passed to the assembler.
-
-@item %A
-Process the @code{asm_final} spec. This is a spec string for
-passing switches to an assembler post-processor, if such a program is
-needed.
-
-@item %l
-Process the @code{link} spec. This is the spec for computing the
-command line passed to the linker. Typically it makes use of the
-@samp{%L %G %S %D and %E} sequences.
-
-@item %D
-Dump out a @option{-L} option for each directory that GCC believes might
-contain startup files. If the target supports multilibs then the
-current multilib directory is prepended to each of these paths.
-
-@item %L
-Process the @code{lib} spec. This is a spec string for deciding which
-libraries are included on the command line to the linker.
-
-@item %G
-Process the @code{libgcc} spec. This is a spec string for deciding
-which GCC support library is included on the command line to the linker.
-
-@item %S
-Process the @code{startfile} spec. This is a spec for deciding which
-object files are the first ones passed to the linker. Typically
-this might be a file named @file{crt0.o}.
-
-@item %E
-Process the @code{endfile} spec. This is a spec string that specifies
-the last object files that are passed to the linker.
-
-@item %C
-Process the @code{cpp} spec. This is used to construct the arguments
-to be passed to the C preprocessor.
-
-@item %1
-Process the @code{cc1} spec. This is used to construct the options to be
-passed to the actual C compiler (@command{cc1}).
-
-@item %2
-Process the @code{cc1plus} spec. This is used to construct the options to be
-passed to the actual C++ compiler (@command{cc1plus}).
-
-@item %*
-Substitute the variable part of a matched option. See below.
-Note that each comma in the substituted string is replaced by
-a single space.
-
-@item %<S
-Remove all occurrences of @code{-S} from the command line. Note---this
-command is position dependent. @samp{%} commands in the spec string
-before this one see @code{-S}, @samp{%} commands in the spec string
-after this one do not.
-
-@item %<S*
-Similar to @samp{%<S}, but match all switches beginning with @code{-S}.
-
-@item %>S
-Similar to @samp{%<S}, but keep @code{-S} in the GCC command line.
-
-@item %:@var{function}(@var{args})
-Call the named function @var{function}, passing it @var{args}.
-@var{args} is first processed as a nested spec string, then split
-into an argument vector in the usual fashion. The function returns
-a string which is processed as if it had appeared literally as part
-of the current spec.
-
-The following built-in spec functions are provided:
-
-@table @code
-@item @code{getenv}
-The @code{getenv} spec function takes two arguments: an environment
-variable name and a string. If the environment variable is not
-defined, a fatal error is issued. Otherwise, the return value is the
-value of the environment variable concatenated with the string. For
-example, if @env{TOPDIR} is defined as @file{/path/to/top}, then:
-
-@smallexample
-%:getenv(TOPDIR /include)
-@end smallexample
-
-expands to @file{/path/to/top/include}.
-
-@item @code{if-exists}
-The @code{if-exists} spec function takes one argument, an absolute
-pathname to a file. If the file exists, @code{if-exists} returns the
-pathname. Here is a small example of its usage:
-
-@smallexample
-*startfile:
-crt0%O%s %:if-exists(crti%O%s) crtbegin%O%s
-@end smallexample
-
-@item @code{if-exists-else}
-The @code{if-exists-else} spec function is similar to the @code{if-exists}
-spec function, except that it takes two arguments. The first argument is
-an absolute pathname to a file. If the file exists, @code{if-exists-else}
-returns the pathname. If it does not exist, it returns the second argument.
-This way, @code{if-exists-else} can be used to select one file or another,
-based on the existence of the first. Here is a small example of its usage:
-
-@smallexample
-*startfile:
-crt0%O%s %:if-exists(crti%O%s) \
-%:if-exists-else(crtbeginT%O%s crtbegin%O%s)
-@end smallexample
-
-@item @code{if-exists-then-else}
-The @code{if-exists-then-else} spec function takes at least two arguments
-and an optional third one. The first argument is an absolute pathname to a
-file. If the file exists, the function returns the second argument.
-If the file does not exist, the function returns the third argument if there
-is one, or NULL otherwise. This can be used to expand one text, or optionally
-another, based on the existence of a file. Here is a small example of its
-usage:
-
-@smallexample
--l%:if-exists-then-else(%:getenv(VSB_DIR rtnet.h) rtnet net)
-@end smallexample
-
-@item @code{sanitize}
-The @code{sanitize} spec function takes no arguments. It returns non-NULL if
-any address, thread or undefined behavior sanitizers are active.
-
-@smallexample
-%@{%:sanitize(address):-funwind-tables@}
-@end smallexample
-
-@item @code{replace-outfile}
-The @code{replace-outfile} spec function takes two arguments. It looks for the
-first argument in the outfiles array and replaces it with the second argument. Here
-is a small example of its usage:
-
-@smallexample
-%@{fgnu-runtime:%:replace-outfile(-lobjc -lobjc-gnu)@}
-@end smallexample
-
-@item @code{remove-outfile}
-The @code{remove-outfile} spec function takes one argument. It looks for the
-first argument in the outfiles array and removes it. Here is a small example
-its usage:
-
-@smallexample
-%:remove-outfile(-lm)
-@end smallexample
-
-@item @code{version-compare}
-The @code{version-compare} spec function takes four or five arguments of the following
-form:
-
-@smallexample
-<comparison-op> <arg1> [<arg2>] <switch> <result>
-@end smallexample
-
-It returns @code{result} if the comparison evaluates to true, and NULL if it doesn't.
-The supported @code{comparison-op} values are:
-
-@table @code
-@item >=
-True if @code{switch} is a later (or same) version than @code{arg1}
-
-@item !>
-Opposite of @code{>=}
-
-@item <
-True if @code{switch} is an earlier version than @code{arg1}
-
-@item !<
-Opposite of @code{<}
-
-@item ><
-True if @code{switch} is @code{arg1} or later, and earlier than @code{arg2}
-
-@item <>
-True if @code{switch} is earlier than @code{arg1}, or is @code{arg2} or later
-@end table
-
-If the @code{switch} is not present at all, the condition is false unless the first character
-of the @code{comparison-op} is @code{!}.
-
-@smallexample
-%:version-compare(>= 10.3 mmacosx-version-min= -lmx)
-@end smallexample
-
-The above example would add @option{-lmx} if @option{-mmacosx-version-min=10.3.9} was
-passed.
-
-@item @code{include}
-The @code{include} spec function behaves much like @code{%include}, with the advantage
-that it can be nested inside a spec and thus be conditionalized. It takes one argument,
-the filename, and looks for it in the startfile path. It always returns NULL.
-
-@smallexample
-%@{static-libasan|static:%:include(libsanitizer.spec)%(link_libasan)@}
-@end smallexample
-
-@item @code{pass-through-libs}
-The @code{pass-through-libs} spec function takes any number of arguments. It
-finds any @option{-l} options and any non-options ending in @file{.a} (which it
-assumes are the names of linker input library archive files) and returns a
-result containing all the found arguments each prepended by
-@option{-plugin-opt=-pass-through=} and joined by spaces. This list is
-intended to be passed to the LTO linker plugin.
-
-@smallexample
-%:pass-through-libs(%G %L %G)
-@end smallexample
-
-@item @code{print-asm-header}
-The @code{print-asm-header} function takes no arguments and simply
-prints a banner like:
-
-@smallexample
-Assembler options
-=================
-
-Use "-Wa,OPTION" to pass "OPTION" to the assembler.
-@end smallexample
-
-It is used to separate compiler options from assembler options
-in the @option{--target-help} output.
-
-@item @code{gt}
-The @code{gt} spec function takes two or more arguments. It returns @code{""} (the
-empty string) if the second-to-last argument is greater than the last argument, and NULL
-otherwise. The following example inserts the @code{link_gomp} spec if the last
-@option{-ftree-parallelize-loops=} option given on the command line is greater than 1:
-
-@smallexample
-%@{%:gt(%@{ftree-parallelize-loops=*:%*@} 1):%:include(libgomp.spec)%(link_gomp)@}
-@end smallexample
-
-@item @code{debug-level-gt}
-The @code{debug-level-gt} spec function takes one argument and returns @code{""} (the
-empty string) if @code{debug_info_level} is greater than the specified number, and NULL
-otherwise.
-
-@smallexample
-%@{%:debug-level-gt(0):%@{gdwarf*:--gdwarf2@}@}
-@end smallexample
-@end table
-
-@item %@{S@}
-Substitutes the @code{-S} switch, if that switch is given to GCC@.
-If that switch is not specified, this substitutes nothing. Note that
-the leading dash is omitted when specifying this option, and it is
-automatically inserted if the substitution is performed. Thus the spec
-string @samp{%@{foo@}} matches the command-line option @option{-foo}
-and outputs the command-line option @option{-foo}.
-
-@item %W@{S@}
-Like %@{@code{S}@} but mark last argument supplied within as a file to be
-deleted on failure.
-
-@item %@@@{S@}
-Like %@{@code{S}@} but puts the result into a @code{FILE} and substitutes
-@code{@@FILE} if an @code{@@file} argument has been supplied.
-
-@item %@{S*@}
-Substitutes all the switches specified to GCC whose names start
-with @code{-S}, but which also take an argument. This is used for
-switches like @option{-o}, @option{-D}, @option{-I}, etc.
-GCC considers @option{-o foo} as being
-one switch whose name starts with @samp{o}. %@{o*@} substitutes this
-text, including the space. Thus two arguments are generated.
-
-@item %@{S*&T*@}
-Like %@{@code{S}*@}, but preserve order of @code{S} and @code{T} options
-(the order of @code{S} and @code{T} in the spec is not significant).
-There can be any number of ampersand-separated variables; for each the
-wild card is optional. Useful for CPP as @samp{%@{D*&U*&A*@}}.
-
-@item %@{S:X@}
-Substitutes @code{X}, if the @option{-S} switch is given to GCC@.
-
-@item %@{!S:X@}
-Substitutes @code{X}, if the @option{-S} switch is @emph{not} given to GCC@.
-
-@item %@{S*:X@}
-Substitutes @code{X} if one or more switches whose names start with
-@code{-S} are specified to GCC@. Normally @code{X} is substituted only
-once, no matter how many such switches appeared. However, if @code{%*}
-appears somewhere in @code{X}, then @code{X} is substituted once
-for each matching switch, with the @code{%*} replaced by the part of
-that switch matching the @code{*}.
-
-If @code{%*} appears as the last part of a spec sequence then a space
-is added after the end of the last substitution. If there is more
-text in the sequence, however, then a space is not generated. This
-allows the @code{%*} substitution to be used as part of a larger
-string. For example, a spec string like this:
-
-@smallexample
-%@{mcu=*:--script=%*/memory.ld@}
-@end smallexample
-
-@noindent
-when matching an option like @option{-mcu=newchip} produces:
-
-@smallexample
---script=newchip/memory.ld
-@end smallexample
-
-@item %@{.S:X@}
-Substitutes @code{X}, if processing a file with suffix @code{S}.
-
-@item %@{!.S:X@}
-Substitutes @code{X}, if @emph{not} processing a file with suffix @code{S}.
-
-@item %@{,S:X@}
-Substitutes @code{X}, if processing a file for language @code{S}.
-
-@item %@{!,S:X@}
-Substitutes @code{X}, if not processing a file for language @code{S}.
-
-@item %@{S|P:X@}
-Substitutes @code{X} if either @code{-S} or @code{-P} is given to
-GCC@. This may be combined with @samp{!}, @samp{.}, @samp{,}, and
-@code{*} sequences as well, although they have a stronger binding than
-the @samp{|}. If @code{%*} appears in @code{X}, all of the
-alternatives must be starred, and only the first matching alternative
-is substituted.
-
-For example, a spec string like this:
-
-@smallexample
-%@{.c:-foo@} %@{!.c:-bar@} %@{.c|d:-baz@} %@{!.c|d:-boggle@}
-@end smallexample
-
-@noindent
-outputs the following command-line options from the following input
-command-line options:
-
-@smallexample
-fred.c -foo -baz
-jim.d -bar -boggle
--d fred.c -foo -baz -boggle
--d jim.d -bar -baz -boggle
-@end smallexample
-
-@item %@{%:@var{function}(@var{args}):X@}
-
-Call function named @var{function} with args @var{args}. If the
-function returns non-NULL, then @code{X} is substituted, if it returns
-NULL, it isn't substituted.
-
-@item %@{S:X; T:Y; :D@}
-
-If @code{S} is given to GCC, substitutes @code{X}; else if @code{T} is
-given to GCC, substitutes @code{Y}; else substitutes @code{D}. There can
-be as many clauses as you need. This may be combined with @code{.},
-@code{,}, @code{!}, @code{|}, and @code{*} as needed.
-
-
-@end table
-
-The switch matching text @code{S} in a @samp{%@{S@}}, @samp{%@{S:X@}}
-or similar construct can use a backslash to ignore the special meaning
-of the character following it, thus allowing literal matching of a
-character that is otherwise specially treated. For example,
-@samp{%@{std=iso9899\:1999:X@}} substitutes @code{X} if the
-@option{-std=iso9899:1999} option is given.
-
-The conditional text @code{X} in a @samp{%@{S:X@}} or similar
-construct may contain other nested @samp{%} constructs or spaces, or
-even newlines. They are processed as usual, as described above.
-Trailing white space in @code{X} is ignored. White space may also
-appear anywhere on the left side of the colon in these constructs,
-except between @code{.} or @code{*} and the corresponding word.
-
-The @option{-O}, @option{-f}, @option{-m}, and @option{-W} switches are
-handled specifically in these constructs. If another value of
-@option{-O} or the negated form of a @option{-f}, @option{-m}, or
-@option{-W} switch is found later in the command line, the earlier
-switch value is ignored, except with @{@code{S}*@} where @code{S} is
-just one letter, which passes all matching options.
-
-The character @samp{|} at the beginning of the predicate text is used to
-indicate that a command should be piped to the following command, but
-only if @option{-pipe} is specified.
-
-It is built into GCC which switches take arguments and which do not.
-(You might think it would be useful to generalize this to allow each
-compiler's spec to say which switches take arguments. But this cannot
-be done in a consistent fashion. GCC cannot even decide which input
-files have been specified without knowing which switches take arguments,
-and it must know which input files to compile in order to tell which
-compilers to run).
-
-GCC also knows implicitly that arguments starting in @option{-l} are to be
-treated as compiler output files, and passed to the linker in their
-proper position among the other output files.
-
-@node Environment Variables
-@section Environment Variables Affecting GCC
-@cindex environment variables
-
-@c man begin ENVIRONMENT
-This section describes several environment variables that affect how GCC
-operates. Some of them work by specifying directories or prefixes to use
-when searching for various kinds of files. Some are used to specify other
-aspects of the compilation environment.
-
-Note that you can also specify places to search using options such as
-@option{-B}, @option{-I} and @option{-L} (@pxref{Directory Options}). These
-take precedence over places specified using environment variables, which
-in turn take precedence over those specified by the configuration of GCC@.
-@xref{Driver,, Controlling the Compilation Driver @file{gcc}, gccint,
-GNU Compiler Collection (GCC) Internals}.
-
-@table @env
-@item LANG
-@itemx LC_CTYPE
-@c @itemx LC_COLLATE
-@itemx LC_MESSAGES
-@c @itemx LC_MONETARY
-@c @itemx LC_NUMERIC
-@c @itemx LC_TIME
-@itemx LC_ALL
-@findex LANG
-@findex LC_CTYPE
-@c @findex LC_COLLATE
-@findex LC_MESSAGES
-@c @findex LC_MONETARY
-@c @findex LC_NUMERIC
-@c @findex LC_TIME
-@findex LC_ALL
-@cindex locale
-These environment variables control the way that GCC uses
-localization information which allows GCC to work with different
-national conventions. GCC inspects the locale categories
-@env{LC_CTYPE} and @env{LC_MESSAGES} if it has been configured to do
-so. These locale categories can be set to any value supported by your
-installation. A typical value is @samp{en_GB.UTF-8} for English in the United
-Kingdom encoded in UTF-8.
-
-The @env{LC_CTYPE} environment variable specifies character
-classification. GCC uses it to determine the character boundaries in
-a string; this is needed for some multibyte encodings that contain quote
-and escape characters that are otherwise interpreted as a string
-end or escape.
-
-The @env{LC_MESSAGES} environment variable specifies the language to
-use in diagnostic messages.
-
-If the @env{LC_ALL} environment variable is set, it overrides the value
-of @env{LC_CTYPE} and @env{LC_MESSAGES}; otherwise, @env{LC_CTYPE}
-and @env{LC_MESSAGES} default to the value of the @env{LANG}
-environment variable. If none of these variables are set, GCC
-defaults to traditional C English behavior.
-
-@item TMPDIR
-@findex TMPDIR
-If @env{TMPDIR} is set, it specifies the directory to use for temporary
-files. GCC uses temporary files to hold the output of one stage of
-compilation which is to be used as input to the next stage: for example,
-the output of the preprocessor, which is the input to the compiler
-proper.
-
-@item GCC_COMPARE_DEBUG
-@findex GCC_COMPARE_DEBUG
-Setting @env{GCC_COMPARE_DEBUG} is nearly equivalent to passing
-@option{-fcompare-debug} to the compiler driver. See the documentation
-of this option for more details.
-
-@item GCC_EXEC_PREFIX
-@findex GCC_EXEC_PREFIX
-If @env{GCC_EXEC_PREFIX} is set, it specifies a prefix to use in the
-names of the subprograms executed by the compiler. No slash is added
-when this prefix is combined with the name of a subprogram, but you can
-specify a prefix that ends with a slash if you wish.
-
-If @env{GCC_EXEC_PREFIX} is not set, GCC attempts to figure out
-an appropriate prefix to use based on the pathname it is invoked with.
-
-If GCC cannot find the subprogram using the specified prefix, it
-tries looking in the usual places for the subprogram.
-
-The default value of @env{GCC_EXEC_PREFIX} is
-@file{@var{prefix}/lib/gcc/} where @var{prefix} is the prefix to
-the installed compiler. In many cases @var{prefix} is the value
-of @code{prefix} when you ran the @file{configure} script.
-
-Other prefixes specified with @option{-B} take precedence over this prefix.
-
-This prefix is also used for finding files such as @file{crt0.o} that are
-used for linking.
-
-In addition, the prefix is used in an unusual way in finding the
-directories to search for header files. For each of the standard
-directories whose name normally begins with @samp{/usr/local/lib/gcc}
-(more precisely, with the value of @env{GCC_INCLUDE_DIR}), GCC tries
-replacing that beginning with the specified prefix to produce an
-alternate directory name. Thus, with @option{-Bfoo/}, GCC searches
-@file{foo/bar} just before it searches the standard directory
-@file{/usr/local/lib/bar}.
-If a standard directory begins with the configured
-@var{prefix} then the value of @var{prefix} is replaced by
-@env{GCC_EXEC_PREFIX} when looking for header files.
-
-@item COMPILER_PATH
-@findex COMPILER_PATH
-The value of @env{COMPILER_PATH} is a colon-separated list of
-directories, much like @env{PATH}. GCC tries the directories thus
-specified when searching for subprograms, if it cannot find the
-subprograms using @env{GCC_EXEC_PREFIX}.
-
-@item LIBRARY_PATH
-@findex LIBRARY_PATH
-The value of @env{LIBRARY_PATH} is a colon-separated list of
-directories, much like @env{PATH}. When configured as a native compiler,
-GCC tries the directories thus specified when searching for special
-linker files, if it cannot find them using @env{GCC_EXEC_PREFIX}. Linking
-using GCC also uses these directories when searching for ordinary
-libraries for the @option{-l} option (but directories specified with
-@option{-L} come first).
-
-@item LANG
-@findex LANG
-@cindex locale definition
-This variable is used to pass locale information to the compiler. One way in
-which this information is used is to determine the character set to be used
-when character literals, string literals and comments are parsed in C and C++.
-When the compiler is configured to allow multibyte characters,
-the following values for @env{LANG} are recognized:
-
-@table @samp
-@item C-JIS
-Recognize JIS characters.
-@item C-SJIS
-Recognize SJIS characters.
-@item C-EUCJP
-Recognize EUCJP characters.
-@end table
-
-If @env{LANG} is not defined, or if it has some other value, then the
-compiler uses @code{mblen} and @code{mbtowc} as defined by the default locale to
-recognize and translate multibyte characters.
-
-@item GCC_EXTRA_DIAGNOSTIC_OUTPUT
-@findex GCC_EXTRA_DIAGNOSTIC_OUTPUT
-If @env{GCC_EXTRA_DIAGNOSTIC_OUTPUT} is set to one of the following values,
-then additional text will be emitted to stderr when fix-it hints are
-emitted. @option{-fdiagnostics-parseable-fixits} and
-@option{-fno-diagnostics-parseable-fixits} take precedence over this
-environment variable.
-
-@table @samp
-@item fixits-v1
-Emit parseable fix-it hints, equivalent to
-@option{-fdiagnostics-parseable-fixits}. In particular, columns are
-expressed as a count of bytes, starting at byte 1 for the initial column.
-
-@item fixits-v2
-As @code{fixits-v1}, but columns are expressed as display columns,
-as per @option{-fdiagnostics-column-unit=display}.
-@end table
-
-@end table
-
-@noindent
-Some additional environment variables affect the behavior of the
-preprocessor.
-
-@include cppenv.texi
-
-@c man end
-
-@node Precompiled Headers
-@section Using Precompiled Headers
-@cindex precompiled headers
-@cindex speed of compilation
-
-Often large projects have many header files that are included in every
-source file. The time the compiler takes to process these header files
-over and over again can account for nearly all of the time required to
-build the project. To make builds faster, GCC allows you to
-@dfn{precompile} a header file.
-
-To create a precompiled header file, simply compile it as you would any
-other file, if necessary using the @option{-x} option to make the driver
-treat it as a C or C++ header file. You may want to use a
-tool like @command{make} to keep the precompiled header up-to-date when
-the headers it contains change.
-
-A precompiled header file is searched for when @code{#include} is
-seen in the compilation. As it searches for the included file
-(@pxref{Search Path,,Search Path,cpp,The C Preprocessor}) the
-compiler looks for a precompiled header in each directory just before it
-looks for the include file in that directory. The name searched for is
-the name specified in the @code{#include} with @samp{.gch} appended. If
-the precompiled header file cannot be used, it is ignored.
-
-For instance, if you have @code{#include "all.h"}, and you have
-@file{all.h.gch} in the same directory as @file{all.h}, then the
-precompiled header file is used if possible, and the original
-header is used otherwise.
-
-Alternatively, you might decide to put the precompiled header file in a
-directory and use @option{-I} to ensure that directory is searched
-before (or instead of) the directory containing the original header.
-Then, if you want to check that the precompiled header file is always
-used, you can put a file of the same name as the original header in this
-directory containing an @code{#error} command.
-
-This also works with @option{-include}. So yet another way to use
-precompiled headers, good for projects not designed with precompiled
-header files in mind, is to simply take most of the header files used by
-a project, include them from another header file, precompile that header
-file, and @option{-include} the precompiled header. If the header files
-have guards against multiple inclusion, they are skipped because
-they've already been included (in the precompiled header).
-
-If you need to precompile the same header file for different
-languages, targets, or compiler options, you can instead make a
-@emph{directory} named like @file{all.h.gch}, and put each precompiled
-header in the directory, perhaps using @option{-o}. It doesn't matter
-what you call the files in the directory; every precompiled header in
-the directory is considered. The first precompiled header
-encountered in the directory that is valid for this compilation is
-used; they're searched in no particular order.
-
-There are many other possibilities, limited only by your imagination,
-good sense, and the constraints of your build system.
-
-A precompiled header file can be used only when these conditions apply:
-
-@itemize
-@item
-Only one precompiled header can be used in a particular compilation.
-
-@item
-A precompiled header cannot be used once the first C token is seen. You
-can have preprocessor directives before a precompiled header; you cannot
-include a precompiled header from inside another header.
-
-@item
-The precompiled header file must be produced for the same language as
-the current compilation. You cannot use a C precompiled header for a C++
-compilation.
-
-@item
-The precompiled header file must have been produced by the same compiler
-binary as the current compilation is using.
-
-@item
-Any macros defined before the precompiled header is included must
-either be defined in the same way as when the precompiled header was
-generated, or must not affect the precompiled header, which usually
-means that they don't appear in the precompiled header at all.
-
-The @option{-D} option is one way to define a macro before a
-precompiled header is included; using a @code{#define} can also do it.
-There are also some options that define macros implicitly, like
-@option{-O} and @option{-Wdeprecated}; the same rule applies to macros
-defined this way.
-
-@item If debugging information is output when using the precompiled
-header, using @option{-g} or similar, the same kind of debugging information
-must have been output when building the precompiled header. However,
-a precompiled header built using @option{-g} can be used in a compilation
-when no debugging information is being output.
-
-@item The same @option{-m} options must generally be used when building
-and using the precompiled header. @xref{Submodel Options},
-for any cases where this rule is relaxed.
-
-@item Each of the following options must be the same when building and using
-the precompiled header:
-
-@gccoptlist{-fexceptions}
-
-@item
-Some other command-line options starting with @option{-f},
-@option{-p}, or @option{-O} must be defined in the same way as when
-the precompiled header was generated. At present, it's not clear
-which options are safe to change and which are not; the safest choice
-is to use exactly the same options when generating and using the
-precompiled header. The following are known to be safe:
-
-@gccoptlist{-fmessage-length= -fpreprocessed -fsched-interblock @gol
--fsched-spec -fsched-spec-load -fsched-spec-load-dangerous @gol
--fsched-verbose=@var{number} -fschedule-insns -fvisibility= @gol
--pedantic-errors}
-
-@item Address space layout randomization (ASLR) can lead to not binary identical
-PCH files. If you rely on stable PCH file contents disable ASLR when generating
-PCH files.
-
-@end itemize
-
-For all of these except the last, the compiler automatically
-ignores the precompiled header if the conditions aren't met. If you
-find an option combination that doesn't work and doesn't cause the
-precompiled header to be ignored, please consider filing a bug report,
-see @ref{Bugs}.
-
-If you do use differing options when generating and using the
-precompiled header, the actual behavior is a mixture of the
-behavior for the options. For instance, if you use @option{-g} to
-generate the precompiled header but not when using it, you may or may
-not get debugging information for routines in the precompiled header.
-
-@node C++ Modules
-@section C++ Modules
-@cindex speed of compilation
-
-Modules are a C++20 language feature. As the name suggests, they
-provides a modular compilation system, intending to provide both
-faster builds and better library isolation. The ``Merging Modules''
-paper @uref{https://wg21.link/p1103}, provides the easiest to read set
-of changes to the standard, although it does not capture later
-changes.
-
-@emph{G++'s modules support is not complete.} Other than bugs, the
-known missing pieces are:
-
-@table @emph
-
-@item Private Module Fragment
-The Private Module Fragment is recognized, but an error is emitted.
-
-@item Partition definition visibility rules
-Entities may be defined in implementation partitions, and those
-definitions are not available outside of the module. This is not
-implemented, and the definitions are available to extra-module use.
-
-@item Textual merging of reachable GM entities
-Entities may be multiply defined across different header-units.
-These must be de-duplicated, and this is implemented across imports,
-or when an import redefines a textually-defined entity. However the
-reverse is not implemented---textually redefining an entity that has
-been defined in an imported header-unit. A redefinition error is
-emitted.
-
-@item Translation-Unit local referencing rules
-Papers p1815 (@uref{https://wg21.link/p1815}) and p2003
-(@uref{https://wg21.link/p2003}) add limitations on which entities an
-exported region may reference (for instance, the entities an exported
-template definition may reference). These are not fully implemented.
-
-@item Standard Library Header Units
-The Standard Library is not provided as importable header units. If
-you want to import such units, you must explicitly build them first.
-If you do not do this with care, you may have multiple declarations,
-which the module machinery must merge---compiler resource usage can be
-affected by how you partition header files into header units.
-
-@end table
-
-Modular compilation is @emph{not} enabled with just the
-@option{-std=c++20} option. You must explicitly enable it with the
-@option{-fmodules-ts} option. It is independent of the language
-version selected, although in pre-C++20 versions, it is of course an
-extension.
-
-No new source file suffixes are required or supported. If you wish to
-use a non-standard suffix (@pxref{Overall Options}), you also need
-to provide a @option{-x c++} option too.@footnote{Some users like to
-distinguish module interface files with a new suffix, such as naming
-the source @code{module.cppm}, which involves
-teaching all tools about the new suffix. A different scheme, such as
-naming @code{module-m.cpp} would be less invasive.}
-
-Compiling a module interface unit produces an additional output (to
-the assembly or object file), called a Compiled Module Interface
-(CMI). This encodes the exported declarations of the module.
-Importing a module reads in the CMI. The import graph is a Directed
-Acyclic Graph (DAG). You must build imports before the importer.
-
-Header files may themselves be compiled to header units, which are a
-transitional ability aiming at faster compilation. The
-@option{-fmodule-header} option is used to enable this, and implies
-the @option{-fmodules-ts} option. These CMIs are named by the fully
-resolved underlying header file, and thus may be a complete pathname
-containing subdirectories. If the header file is found at an absolute
-pathname, the CMI location is still relative to a CMI root directory.
-
-As header files often have no suffix, you commonly have to specify a
-@option{-x} option to tell the compiler the source is a header file.
-You may use @option{-x c++-header}, @option{-x c++-user-header} or
-@option{-x c++-system-header}. When used in conjunction with
-@option{-fmodules-ts}, these all imply an appropriate
-@option{-fmodule-header} option. The latter two variants use the
-user or system include path to search for the file specified. This
-allows you to, for instance, compile standard library header files as
-header units, without needing to know exactly where they are
-installed. Specifying the language as one of these variants also
-inhibits output of the object file, as header files have no associated
-object file.
-
-The @option{-fmodule-only} option disables generation of the
-associated object file for compiling a module interface. Only the CMI
-is generated. This option is implied when using the
-@option{-fmodule-header} option.
-
-The @option{-flang-info-include-translate} and
-@option{-flang-info-include-translate-not} options notes whether
-include translation occurs or not. With no argument, the first will
-note all include translation. The second will note all
-non-translations of include files not known to intentionally be
-textual. With an argument, queries about include translation of a
-header files with that particular trailing pathname are noted. You
-may repeat this form to cover several different header files. This
-option may be helpful in determining whether include translation is
-happening---if it is working correctly, it behaves as if it isn't
-there at all.
-
-The @option{-flang-info-module-cmi} option can be used to determine
-where the compiler is reading a CMI from. Without the option, the
-compiler is silent when such a read is successful. This option has an
-optional argument, which will restrict the notification to just the
-set of named modules or header units specified.
-
-The @option{-Winvalid-imported-macros} option causes all imported macros
-to be resolved at the end of compilation. Without this, imported
-macros are only resolved when expanded or (re)defined. This option
-detects conflicting import definitions for all macros.
-
-For details of the @option{-fmodule-mapper} family of options,
-@pxref{C++ Module Mapper}.
-
-@menu
-* C++ Module Mapper:: Module Mapper
-* C++ Module Preprocessing:: Module Preprocessing
-* C++ Compiled Module Interface:: Compiled Module Interface
-@end menu
-
-@node C++ Module Mapper
-@subsection Module Mapper
-@cindex C++ Module Mapper
-
-A module mapper provides a server or file that the compiler queries to
-determine the mapping between module names and CMI files. It is also
-used to build CMIs on demand. @emph{Mapper functionality is in its
-infancy and is intended for experimentation with build system
-interactions.}
-
-You can specify a mapper with the @option{-fmodule-mapper=@var{val}}
-option or @env{CXX_MODULE_MAPPER} environment variable. The value may
-have one of the following forms:
-
-@table @gcctabopt
-
-@item @r{[}@var{hostname}@r{]}:@var{port}@r{[}?@var{ident}@r{]}
-An optional hostname and a numeric port number to connect to. If the
-hostname is omitted, the loopback address is used. If the hostname
-corresponds to multiple IPV6 addresses, these are tried in turn, until
-one is successful. If your host lacks IPv6, this form is
-non-functional. If you must use IPv4 use
-@option{-fmodule-mapper='|ncat @var{ipv4host} @var{port}'}.
-
-@item =@var{socket}@r{[}?@var{ident}@r{]}
-A local domain socket. If your host lacks local domain sockets, this
-form is non-functional.
-
-@item |@var{program}@r{[}?@var{ident}@r{]} @r{[}@var{args...}@r{]}
-A program to spawn, and communicate with on its stdin/stdout streams.
-Your @var{PATH} environment variable is searched for the program.
-Arguments are separated by space characters, (it is not possible for
-one of the arguments delivered to the program to contain a space). An
-exception is if @var{program} begins with @@. In that case
-@var{program} (sans @@) is looked for in the compiler's internal
-binary directory. Thus the sample mapper-server can be specified
-with @code{@@g++-mapper-server}.
-
-@item <>@r{[}?@var{ident}@r{]}
-@item <>@var{inout}@r{[}?@var{ident}@r{]}
-@item <@var{in}>@var{out}@r{[}?@var{ident}@r{]}
-Named pipes or file descriptors to communicate over. The first form,
-@option{<>}, communicates over stdin and stdout. The other forms
-allow you to specify a file descriptor or name a pipe. A numeric value
-is interpreted as a file descriptor, otherwise named pipe is opened.
-The second form specifies a bidirectional pipe and the last form
-allows specifying two independent pipes. Using file descriptors
-directly in this manner is fragile in general, as it can require the
-cooperation of intermediate processes. In particular using stdin &
-stdout is fraught with danger as other compiler options might also
-cause the compiler to read stdin or write stdout, and it can have
-unfortunate interactions with signal delivery from the terminal.
-
-@item @var{file}@r{[}?@var{ident}@r{]}
-A mapping file consisting of space-separated module-name, filename
-pairs, one per line. Only the mappings for the direct imports and any
-module export name need be provided. If other mappings are provided,
-they override those stored in any imported CMI files. A repository
-root may be specified in the mapping file by using @samp{$root} as the
-module name in the first active line. Use of this option will disable
-any default module->CMI name mapping.
-
-@end table
-
-As shown, an optional @var{ident} may suffix the first word of the
-option, indicated by a @samp{?} prefix. The value is used in the
-initial handshake with the module server, or to specify a prefix on
-mapping file lines. In the server case, the main source file name is
-used if no @var{ident} is specified. In the file case, all non-blank
-lines are significant, unless a value is specified, in which case only
-lines beginning with @var{ident} are significant. The @var{ident}
-must be separated by whitespace from the module name. Be aware that
-@samp{<}, @samp{>}, @samp{?}, and @samp{|} characters are often
-significant to the shell, and therefore may need quoting.
-
-The mapper is connected to or loaded lazily, when the first module
-mapping is required. The networking protocols are only supported on
-hosts that provide networking. If no mapper is specified a default is
-provided.
-
-A project-specific mapper is expected to be provided by the build
-system that invokes the compiler. It is not expected that a
-general-purpose server is provided for all compilations. As such, the
-server will know the build configuration, the compiler it invoked, and
-the environment (such as working directory) in which that is
-operating. As it may parallelize builds, several compilations may
-connect to the same socket.
-
-The default mapper generates CMI files in a @samp{gcm.cache}
-directory. CMI files have a @samp{.gcm} suffix. The module unit name
-is used directly to provide the basename. Header units construct a
-relative path using the underlying header file name. If the path is
-already relative, a @samp{,} directory is prepended. Internal
-@samp{..} components are translated to @samp{,,}. No attempt is made
-to canonicalize these filenames beyond that done by the preprocessor's
-include search algorithm, as in general it is ambiguous when symbolic
-links are present.
-
-The mapper protocol was published as ``A Module Mapper''
-@uref{https://wg21.link/p1184}. The implementation is provided by
-@command{libcody}, @uref{https://github.com/urnathan/libcody},
-which specifies the canonical protocol definition. A proof of concept
-server implementation embedded in @command{make} was described in
-''Make Me A Module'', @uref{https://wg21.link/p1602}.
-
-@node C++ Module Preprocessing
-@subsection Module Preprocessing
-@cindex C++ Module Preprocessing
-
-Modules affect preprocessing because of header units and include
-translation. Some uses of the preprocessor as a separate step either
-do not produce a correct output, or require CMIs to be available.
-
-Header units import macros. These macros can affect later conditional
-inclusion, which therefore can cascade to differing import sets. When
-preprocessing, it is necessary to load the CMI. If a header unit is
-unavailable, the preprocessor issues a warning and continue (when
-not just preprocessing, an error is emitted). Detecting such imports
-requires preprocessor tokenization of the input stream to phase 4
-(macro expansion).
-
-Include translation converts @code{#include}, @code{#include_next} and
-@code{#import} directives to internal @code{import} declarations.
-Whether a particular directive is translated is controlled by the
-module mapper. Header unit names are canonicalized during
-preprocessing.
-
-Dependency information can be emitted for macro import, extending the
-functionality of @option{-MD} and @option{-MMD} options. Detection of
-import declarations also requires phase 4 preprocessing, and thus
-requires full preprocessing (or compilation).
-
-The @option{-M}, @option{-MM} and @option{-E -fdirectives-only} options halt
-preprocessing before phase 4.
-
-The @option{-save-temps} option uses @option{-fdirectives-only} for
-preprocessing, and preserve the macro definitions in the preprocessed
-output. Usually you also want to use this option when explicitly
-preprocessing a header-unit, or consuming such preprocessed output:
-
-@smallexample
-g++ -fmodules-ts -E -fdirectives-only my-header.hh -o my-header.ii
-g++ -x c++-header -fmodules-ts -fpreprocessed -fdirectives-only my-header.ii
-@end smallexample
-
-@node C++ Compiled Module Interface
-@subsection Compiled Module Interface
-@cindex C++ Compiled Module Interface
-
-CMIs are an additional artifact when compiling named module
-interfaces, partitions or header units. These are read when
-importing. CMI contents are implementation-specific, and in GCC's
-case tied to the compiler version. Consider them a rebuildable cache
-artifact, not a distributable object.
-
-When creating an output CMI, any missing directory components are
-created in a manner that is safe for concurrent builds creating
-multiple, different, CMIs within a common subdirectory tree.
-
-CMI contents are written to a temporary file, which is then atomically
-renamed. Observers either see old contents (if there is an
-existing file), or complete new contents. They do not observe the
-CMI during its creation. This is unlike object file writing, which
-may be observed by an external process.
-
-CMIs are read in lazily, if the host OS provides @code{mmap}
-functionality. Generally blocks are read when name lookup or template
-instantiation occurs. To inhibit this, the @option{-fno-module-lazy}
-option may be used.
-
-The @option{--param lazy-modules=@var{n}} parameter controls the limit
-on the number of concurrently open module files during lazy loading.
-Should more modules be imported, an LRU algorithm is used to determine
-which files to close---until that file is needed again. This limit
-may be exceeded with deep module dependency hierarchies. With large
-code bases there may be more imports than the process limit of file
-descriptors. By default, the limit is a few less than the per-process
-file descriptor hard limit, if that is determinable.@footnote{Where
-applicable the soft limit is incremented as needed towards the hard limit.}
-
-GCC CMIs use ELF32 as an architecture-neutral encapsulation mechanism.
-You may use @command{readelf} to inspect them, although section
-contents are largely undecipherable. There is a section named
-@code{.gnu.c++.README}, which contains human-readable text. Other
-than the first line, each line consists of @code{@var{tag}: @code{value}}
-tuples.
-
-@smallexample
-> @command{readelf -p.gnu.c++.README gcm.cache/foo.gcm}
-
-String dump of section '.gnu.c++.README':
- [ 0] GNU C++ primary module interface
- [ 21] compiler: 11.0.0 20201116 (experimental) [c++-modules revision 20201116-0454]
- [ 6f] version: 2020/11/16-04:54
- [ 89] module: foo
- [ 95] source: c_b.ii
- [ a4] dialect: C++20/coroutines
- [ be] cwd: /data/users/nathans/modules/obj/x86_64/gcc
- [ ee] repository: gcm.cache
- [ 104] buildtime: 2020/11/16 15:03:21 UTC
- [ 127] localtime: 2020/11/16 07:03:21 PST
- [ 14a] export: foo:part1 foo-part1.gcm
-@end smallexample
-
-Amongst other things, this lists the source that was built, C++
-dialect used and imports of the module.@footnote{The precise contents
-of this output may change.} The timestamp is the same value as that
-provided by the @code{__DATE__} & @code{__TIME__} macros, and may be
-explicitly specified with the environment variable
-@code{SOURCE_DATE_EPOCH}. For further details
-@pxref{Environment Variables}.
-
-A set of related CMIs may be copied, provided the relative pathnames
-are preserved.
-
-The @code{.gnu.c++.README} contents do not affect CMI integrity, and
-it may be removed or altered. The section numbering of the sections
-whose names do not begin with @code{.gnu.c++.}, or are not the string
-section is significant and must not be altered.
+++ /dev/null
-@c Copyright (C) 2002-2022 Free Software Foundation, Inc.
-@c This is part of the GCC manual.
-@c For copying conditions, see the file gcc.texi.
-
-@node Languages
-@chapter Language Front Ends in GCC
-
-The interface to front ends for languages in GCC, and in particular
-the @code{tree} structure (@pxref{GENERIC}), was initially designed for
-C, and many aspects of it are still somewhat biased towards C and
-C-like languages. It is, however, reasonably well suited to other
-procedural languages, and front ends for many such languages have been
-written for GCC@.
-
-Writing a compiler as a front end for GCC, rather than compiling
-directly to assembler or generating C code which is then compiled by
-GCC, has several advantages:
-
-@itemize @bullet
-@item GCC front ends benefit from the support for many different
-target machines already present in GCC@.
-@item GCC front ends benefit from all the optimizations in GCC@. Some
-of these, such as alias analysis, may work better when GCC is
-compiling directly from source code than when it is compiling from
-generated C code.
-@item Better debugging information is generated when compiling
-directly from source code than when going via intermediate generated C
-code.
-@end itemize
-
-Because of the advantages of writing a compiler as a GCC front end,
-GCC front ends have also been created for languages very different
-from those for which GCC was designed, such as the declarative
-logic/functional language Mercury. For these reasons, it may also be
-useful to implement compilers created for specialized purposes (for
-example, as part of a research project) as GCC front ends.
+++ /dev/null
-@c Copyright (C) 2003-2022 Free Software Foundation, Inc.
-@c This is part of the GCC manual.
-@c For copying conditions, see the file gcc.texi.
-@c Contributed by Aldy Hernandez <aldy@quesejoda.com>
-
-@node Libgcc
-@chapter The GCC low-level runtime library
-
-GCC provides a low-level runtime library, @file{libgcc.a} or
-@file{libgcc_s.so.1} on some platforms. GCC generates calls to
-routines in this library automatically, whenever it needs to perform
-some operation that is too complicated to emit inline code for.
-
-Most of the routines in @code{libgcc} handle arithmetic operations
-that the target processor cannot perform directly. This includes
-integer multiply and divide on some machines, and all floating-point
-and fixed-point operations on other machines. @code{libgcc} also includes
-routines for exception handling, and a handful of miscellaneous operations.
-
-Some of these routines can be defined in mostly machine-independent C@.
-Others must be hand-written in assembly language for each processor
-that needs them.
-
-GCC will also generate calls to C library routines, such as
-@code{memcpy} and @code{memset}, in some cases. The set of routines
-that GCC may possibly use is documented in @ref{Other
-Builtins,,,gcc, Using the GNU Compiler Collection (GCC)}.
-
-These routines take arguments and return values of a specific machine
-mode, not a specific C type. @xref{Machine Modes}, for an explanation
-of this concept. For illustrative purposes, in this chapter the
-floating point type @code{float} is assumed to correspond to @code{SFmode};
-@code{double} to @code{DFmode}; and @code{@w{long double}} to both
-@code{TFmode} and @code{XFmode}. Similarly, the integer types @code{int}
-and @code{@w{unsigned int}} correspond to @code{SImode}; @code{long} and
-@code{@w{unsigned long}} to @code{DImode}; and @code{@w{long long}} and
-@code{@w{unsigned long long}} to @code{TImode}.
-
-@menu
-* Integer library routines::
-* Soft float library routines::
-* Decimal float library routines::
-* Fixed-point fractional library routines::
-* Exception handling routines::
-* Miscellaneous routines::
-@end menu
-
-@node Integer library routines
-@section Routines for integer arithmetic
-
-The integer arithmetic routines are used on platforms that don't provide
-hardware support for arithmetic operations on some modes.
-
-@subsection Arithmetic functions
-
-@deftypefn {Runtime Function} int __ashlsi3 (int @var{a}, int @var{b})
-@deftypefnx {Runtime Function} long __ashldi3 (long @var{a}, int @var{b})
-@deftypefnx {Runtime Function} {long long} __ashlti3 (long long @var{a}, int @var{b})
-These functions return the result of shifting @var{a} left by @var{b} bits.
-@end deftypefn
-
-@deftypefn {Runtime Function} int __ashrsi3 (int @var{a}, int @var{b})
-@deftypefnx {Runtime Function} long __ashrdi3 (long @var{a}, int @var{b})
-@deftypefnx {Runtime Function} {long long} __ashrti3 (long long @var{a}, int @var{b})
-These functions return the result of arithmetically shifting @var{a} right
-by @var{b} bits.
-@end deftypefn
-
-@deftypefn {Runtime Function} int __divsi3 (int @var{a}, int @var{b})
-@deftypefnx {Runtime Function} long __divdi3 (long @var{a}, long @var{b})
-@deftypefnx {Runtime Function} {long long} __divti3 (long long @var{a}, long long @var{b})
-These functions return the quotient of the signed division of @var{a} and
-@var{b}.
-@end deftypefn
-
-@deftypefn {Runtime Function} int __lshrsi3 (int @var{a}, int @var{b})
-@deftypefnx {Runtime Function} long __lshrdi3 (long @var{a}, int @var{b})
-@deftypefnx {Runtime Function} {long long} __lshrti3 (long long @var{a}, int @var{b})
-These functions return the result of logically shifting @var{a} right by
-@var{b} bits.
-@end deftypefn
-
-@deftypefn {Runtime Function} int __modsi3 (int @var{a}, int @var{b})
-@deftypefnx {Runtime Function} long __moddi3 (long @var{a}, long @var{b})
-@deftypefnx {Runtime Function} {long long} __modti3 (long long @var{a}, long long @var{b})
-These functions return the remainder of the signed division of @var{a}
-and @var{b}.
-@end deftypefn
-
-@deftypefn {Runtime Function} int __mulsi3 (int @var{a}, int @var{b})
-@deftypefnx {Runtime Function} long __muldi3 (long @var{a}, long @var{b})
-@deftypefnx {Runtime Function} {long long} __multi3 (long long @var{a}, long long @var{b})
-These functions return the product of @var{a} and @var{b}.
-@end deftypefn
-
-@deftypefn {Runtime Function} long __negdi2 (long @var{a})
-@deftypefnx {Runtime Function} {long long} __negti2 (long long @var{a})
-These functions return the negation of @var{a}.
-@end deftypefn
-
-@deftypefn {Runtime Function} {unsigned int} __udivsi3 (unsigned int @var{a}, unsigned int @var{b})
-@deftypefnx {Runtime Function} {unsigned long} __udivdi3 (unsigned long @var{a}, unsigned long @var{b})
-@deftypefnx {Runtime Function} {unsigned long long} __udivti3 (unsigned long long @var{a}, unsigned long long @var{b})
-These functions return the quotient of the unsigned division of @var{a}
-and @var{b}.
-@end deftypefn
-
-@deftypefn {Runtime Function} {unsigned long} __udivmoddi4 (unsigned long @var{a}, unsigned long @var{b}, unsigned long *@var{c})
-@deftypefnx {Runtime Function} {unsigned long long} __udivmodti4 (unsigned long long @var{a}, unsigned long long @var{b}, unsigned long long *@var{c})
-These functions calculate both the quotient and remainder of the unsigned
-division of @var{a} and @var{b}. The return value is the quotient, and
-the remainder is placed in variable pointed to by @var{c}.
-@end deftypefn
-
-@deftypefn {Runtime Function} {unsigned int} __umodsi3 (unsigned int @var{a}, unsigned int @var{b})
-@deftypefnx {Runtime Function} {unsigned long} __umoddi3 (unsigned long @var{a}, unsigned long @var{b})
-@deftypefnx {Runtime Function} {unsigned long long} __umodti3 (unsigned long long @var{a}, unsigned long long @var{b})
-These functions return the remainder of the unsigned division of @var{a}
-and @var{b}.
-@end deftypefn
-
-@subsection Comparison functions
-
-The following functions implement integral comparisons. These functions
-implement a low-level compare, upon which the higher level comparison
-operators (such as less than and greater than or equal to) can be
-constructed. The returned values lie in the range zero to two, to allow
-the high-level operators to be implemented by testing the returned
-result using either signed or unsigned comparison.
-
-@deftypefn {Runtime Function} int __cmpdi2 (long @var{a}, long @var{b})
-@deftypefnx {Runtime Function} int __cmpti2 (long long @var{a}, long long @var{b})
-These functions perform a signed comparison of @var{a} and @var{b}. If
-@var{a} is less than @var{b}, they return 0; if @var{a} is greater than
-@var{b}, they return 2; and if @var{a} and @var{b} are equal they return 1.
-@end deftypefn
-
-@deftypefn {Runtime Function} int __ucmpdi2 (unsigned long @var{a}, unsigned long @var{b})
-@deftypefnx {Runtime Function} int __ucmpti2 (unsigned long long @var{a}, unsigned long long @var{b})
-These functions perform an unsigned comparison of @var{a} and @var{b}.
-If @var{a} is less than @var{b}, they return 0; if @var{a} is greater than
-@var{b}, they return 2; and if @var{a} and @var{b} are equal they return 1.
-@end deftypefn
-
-@subsection Trapping arithmetic functions
-
-The following functions implement trapping arithmetic. These functions
-call the libc function @code{abort} upon signed arithmetic overflow.
-
-@deftypefn {Runtime Function} int __absvsi2 (int @var{a})
-@deftypefnx {Runtime Function} long __absvdi2 (long @var{a})
-These functions return the absolute value of @var{a}.
-@end deftypefn
-
-@deftypefn {Runtime Function} int __addvsi3 (int @var{a}, int @var{b})
-@deftypefnx {Runtime Function} long __addvdi3 (long @var{a}, long @var{b})
-These functions return the sum of @var{a} and @var{b}; that is
-@code{@var{a} + @var{b}}.
-@end deftypefn
-
-@deftypefn {Runtime Function} int __mulvsi3 (int @var{a}, int @var{b})
-@deftypefnx {Runtime Function} long __mulvdi3 (long @var{a}, long @var{b})
-The functions return the product of @var{a} and @var{b}; that is
-@code{@var{a} * @var{b}}.
-@end deftypefn
-
-@deftypefn {Runtime Function} int __negvsi2 (int @var{a})
-@deftypefnx {Runtime Function} long __negvdi2 (long @var{a})
-These functions return the negation of @var{a}; that is @code{-@var{a}}.
-@end deftypefn
-
-@deftypefn {Runtime Function} int __subvsi3 (int @var{a}, int @var{b})
-@deftypefnx {Runtime Function} long __subvdi3 (long @var{a}, long @var{b})
-These functions return the difference between @var{b} and @var{a};
-that is @code{@var{a} - @var{b}}.
-@end deftypefn
-
-@subsection Bit operations
-
-@deftypefn {Runtime Function} int __clzsi2 (unsigned int @var{a})
-@deftypefnx {Runtime Function} int __clzdi2 (unsigned long @var{a})
-@deftypefnx {Runtime Function} int __clzti2 (unsigned long long @var{a})
-These functions return the number of leading 0-bits in @var{a}, starting
-at the most significant bit position. If @var{a} is zero, the result is
-undefined.
-@end deftypefn
-
-@deftypefn {Runtime Function} int __ctzsi2 (unsigned int @var{a})
-@deftypefnx {Runtime Function} int __ctzdi2 (unsigned long @var{a})
-@deftypefnx {Runtime Function} int __ctzti2 (unsigned long long @var{a})
-These functions return the number of trailing 0-bits in @var{a}, starting
-at the least significant bit position. If @var{a} is zero, the result is
-undefined.
-@end deftypefn
-
-@deftypefn {Runtime Function} int __ffsdi2 (unsigned long @var{a})
-@deftypefnx {Runtime Function} int __ffsti2 (unsigned long long @var{a})
-These functions return the index of the least significant 1-bit in @var{a},
-or the value zero if @var{a} is zero. The least significant bit is index
-one.
-@end deftypefn
-
-@deftypefn {Runtime Function} int __paritysi2 (unsigned int @var{a})
-@deftypefnx {Runtime Function} int __paritydi2 (unsigned long @var{a})
-@deftypefnx {Runtime Function} int __parityti2 (unsigned long long @var{a})
-These functions return the value zero if the number of bits set in
-@var{a} is even, and the value one otherwise.
-@end deftypefn
-
-@deftypefn {Runtime Function} int __popcountsi2 (unsigned int @var{a})
-@deftypefnx {Runtime Function} int __popcountdi2 (unsigned long @var{a})
-@deftypefnx {Runtime Function} int __popcountti2 (unsigned long long @var{a})
-These functions return the number of bits set in @var{a}.
-@end deftypefn
-
-@deftypefn {Runtime Function} int32_t __bswapsi2 (int32_t @var{a})
-@deftypefnx {Runtime Function} int64_t __bswapdi2 (int64_t @var{a})
-These functions return the @var{a} byteswapped.
-@end deftypefn
-
-@node Soft float library routines
-@section Routines for floating point emulation
-@cindex soft float library
-@cindex arithmetic library
-@cindex math library
-@opindex msoft-float
-
-The software floating point library is used on machines which do not
-have hardware support for floating point. It is also used whenever
-@option{-msoft-float} is used to disable generation of floating point
-instructions. (Not all targets support this switch.)
-
-For compatibility with other compilers, the floating point emulation
-routines can be renamed with the @code{DECLARE_LIBRARY_RENAMES} macro
-(@pxref{Library Calls}). In this section, the default names are used.
-
-Presently the library does not support @code{XFmode}, which is used
-for @code{long double} on some architectures.
-
-@subsection Arithmetic functions
-
-@deftypefn {Runtime Function} float __addsf3 (float @var{a}, float @var{b})
-@deftypefnx {Runtime Function} double __adddf3 (double @var{a}, double @var{b})
-@deftypefnx {Runtime Function} {long double} __addtf3 (long double @var{a}, long double @var{b})
-@deftypefnx {Runtime Function} {long double} __addxf3 (long double @var{a}, long double @var{b})
-These functions return the sum of @var{a} and @var{b}.
-@end deftypefn
-
-@deftypefn {Runtime Function} float __subsf3 (float @var{a}, float @var{b})
-@deftypefnx {Runtime Function} double __subdf3 (double @var{a}, double @var{b})
-@deftypefnx {Runtime Function} {long double} __subtf3 (long double @var{a}, long double @var{b})
-@deftypefnx {Runtime Function} {long double} __subxf3 (long double @var{a}, long double @var{b})
-These functions return the difference between @var{b} and @var{a};
-that is, @w{@math{@var{a} - @var{b}}}.
-@end deftypefn
-
-@deftypefn {Runtime Function} float __mulsf3 (float @var{a}, float @var{b})
-@deftypefnx {Runtime Function} double __muldf3 (double @var{a}, double @var{b})
-@deftypefnx {Runtime Function} {long double} __multf3 (long double @var{a}, long double @var{b})
-@deftypefnx {Runtime Function} {long double} __mulxf3 (long double @var{a}, long double @var{b})
-These functions return the product of @var{a} and @var{b}.
-@end deftypefn
-
-@deftypefn {Runtime Function} float __divsf3 (float @var{a}, float @var{b})
-@deftypefnx {Runtime Function} double __divdf3 (double @var{a}, double @var{b})
-@deftypefnx {Runtime Function} {long double} __divtf3 (long double @var{a}, long double @var{b})
-@deftypefnx {Runtime Function} {long double} __divxf3 (long double @var{a}, long double @var{b})
-These functions return the quotient of @var{a} and @var{b}; that is,
-@w{@math{@var{a} / @var{b}}}.
-@end deftypefn
-
-@deftypefn {Runtime Function} float __negsf2 (float @var{a})
-@deftypefnx {Runtime Function} double __negdf2 (double @var{a})
-@deftypefnx {Runtime Function} {long double} __negtf2 (long double @var{a})
-@deftypefnx {Runtime Function} {long double} __negxf2 (long double @var{a})
-These functions return the negation of @var{a}. They simply flip the
-sign bit, so they can produce negative zero and negative NaN@.
-@end deftypefn
-
-@subsection Conversion functions
-
-@deftypefn {Runtime Function} double __extendsfdf2 (float @var{a})
-@deftypefnx {Runtime Function} {long double} __extendsftf2 (float @var{a})
-@deftypefnx {Runtime Function} {long double} __extendsfxf2 (float @var{a})
-@deftypefnx {Runtime Function} {long double} __extenddftf2 (double @var{a})
-@deftypefnx {Runtime Function} {long double} __extenddfxf2 (double @var{a})
-These functions extend @var{a} to the wider mode of their return
-type.
-@end deftypefn
-
-@deftypefn {Runtime Function} double __truncxfdf2 (long double @var{a})
-@deftypefnx {Runtime Function} double __trunctfdf2 (long double @var{a})
-@deftypefnx {Runtime Function} float __truncxfsf2 (long double @var{a})
-@deftypefnx {Runtime Function} float __trunctfsf2 (long double @var{a})
-@deftypefnx {Runtime Function} float __truncdfsf2 (double @var{a})
-These functions truncate @var{a} to the narrower mode of their return
-type, rounding toward zero.
-@end deftypefn
-
-@deftypefn {Runtime Function} int __fixsfsi (float @var{a})
-@deftypefnx {Runtime Function} int __fixdfsi (double @var{a})
-@deftypefnx {Runtime Function} int __fixtfsi (long double @var{a})
-@deftypefnx {Runtime Function} int __fixxfsi (long double @var{a})
-These functions convert @var{a} to a signed integer, rounding toward zero.
-@end deftypefn
-
-@deftypefn {Runtime Function} long __fixsfdi (float @var{a})
-@deftypefnx {Runtime Function} long __fixdfdi (double @var{a})
-@deftypefnx {Runtime Function} long __fixtfdi (long double @var{a})
-@deftypefnx {Runtime Function} long __fixxfdi (long double @var{a})
-These functions convert @var{a} to a signed long, rounding toward zero.
-@end deftypefn
-
-@deftypefn {Runtime Function} {long long} __fixsfti (float @var{a})
-@deftypefnx {Runtime Function} {long long} __fixdfti (double @var{a})
-@deftypefnx {Runtime Function} {long long} __fixtfti (long double @var{a})
-@deftypefnx {Runtime Function} {long long} __fixxfti (long double @var{a})
-These functions convert @var{a} to a signed long long, rounding toward zero.
-@end deftypefn
-
-@deftypefn {Runtime Function} {unsigned int} __fixunssfsi (float @var{a})
-@deftypefnx {Runtime Function} {unsigned int} __fixunsdfsi (double @var{a})
-@deftypefnx {Runtime Function} {unsigned int} __fixunstfsi (long double @var{a})
-@deftypefnx {Runtime Function} {unsigned int} __fixunsxfsi (long double @var{a})
-These functions convert @var{a} to an unsigned integer, rounding
-toward zero. Negative values all become zero.
-@end deftypefn
-
-@deftypefn {Runtime Function} {unsigned long} __fixunssfdi (float @var{a})
-@deftypefnx {Runtime Function} {unsigned long} __fixunsdfdi (double @var{a})
-@deftypefnx {Runtime Function} {unsigned long} __fixunstfdi (long double @var{a})
-@deftypefnx {Runtime Function} {unsigned long} __fixunsxfdi (long double @var{a})
-These functions convert @var{a} to an unsigned long, rounding
-toward zero. Negative values all become zero.
-@end deftypefn
-
-@deftypefn {Runtime Function} {unsigned long long} __fixunssfti (float @var{a})
-@deftypefnx {Runtime Function} {unsigned long long} __fixunsdfti (double @var{a})
-@deftypefnx {Runtime Function} {unsigned long long} __fixunstfti (long double @var{a})
-@deftypefnx {Runtime Function} {unsigned long long} __fixunsxfti (long double @var{a})
-These functions convert @var{a} to an unsigned long long, rounding
-toward zero. Negative values all become zero.
-@end deftypefn
-
-@deftypefn {Runtime Function} float __floatsisf (int @var{i})
-@deftypefnx {Runtime Function} double __floatsidf (int @var{i})
-@deftypefnx {Runtime Function} {long double} __floatsitf (int @var{i})
-@deftypefnx {Runtime Function} {long double} __floatsixf (int @var{i})
-These functions convert @var{i}, a signed integer, to floating point.
-@end deftypefn
-
-@deftypefn {Runtime Function} float __floatdisf (long @var{i})
-@deftypefnx {Runtime Function} double __floatdidf (long @var{i})
-@deftypefnx {Runtime Function} {long double} __floatditf (long @var{i})
-@deftypefnx {Runtime Function} {long double} __floatdixf (long @var{i})
-These functions convert @var{i}, a signed long, to floating point.
-@end deftypefn
-
-@deftypefn {Runtime Function} float __floattisf (long long @var{i})
-@deftypefnx {Runtime Function} double __floattidf (long long @var{i})
-@deftypefnx {Runtime Function} {long double} __floattitf (long long @var{i})
-@deftypefnx {Runtime Function} {long double} __floattixf (long long @var{i})
-These functions convert @var{i}, a signed long long, to floating point.
-@end deftypefn
-
-@deftypefn {Runtime Function} float __floatunsisf (unsigned int @var{i})
-@deftypefnx {Runtime Function} double __floatunsidf (unsigned int @var{i})
-@deftypefnx {Runtime Function} {long double} __floatunsitf (unsigned int @var{i})
-@deftypefnx {Runtime Function} {long double} __floatunsixf (unsigned int @var{i})
-These functions convert @var{i}, an unsigned integer, to floating point.
-@end deftypefn
-
-@deftypefn {Runtime Function} float __floatundisf (unsigned long @var{i})
-@deftypefnx {Runtime Function} double __floatundidf (unsigned long @var{i})
-@deftypefnx {Runtime Function} {long double} __floatunditf (unsigned long @var{i})
-@deftypefnx {Runtime Function} {long double} __floatundixf (unsigned long @var{i})
-These functions convert @var{i}, an unsigned long, to floating point.
-@end deftypefn
-
-@deftypefn {Runtime Function} float __floatuntisf (unsigned long long @var{i})
-@deftypefnx {Runtime Function} double __floatuntidf (unsigned long long @var{i})
-@deftypefnx {Runtime Function} {long double} __floatuntitf (unsigned long long @var{i})
-@deftypefnx {Runtime Function} {long double} __floatuntixf (unsigned long long @var{i})
-These functions convert @var{i}, an unsigned long long, to floating point.
-@end deftypefn
-
-@subsection Comparison functions
-
-There are two sets of basic comparison functions.
-
-@deftypefn {Runtime Function} int __cmpsf2 (float @var{a}, float @var{b})
-@deftypefnx {Runtime Function} int __cmpdf2 (double @var{a}, double @var{b})
-@deftypefnx {Runtime Function} int __cmptf2 (long double @var{a}, long double @var{b})
-These functions calculate @math{a <=> b}. That is, if @var{a} is less
-than @var{b}, they return @minus{}1; if @var{a} is greater than @var{b}, they
-return 1; and if @var{a} and @var{b} are equal they return 0. If
-either argument is NaN they return 1, but you should not rely on this;
-if NaN is a possibility, use one of the higher-level comparison
-functions.
-@end deftypefn
-
-@deftypefn {Runtime Function} int __unordsf2 (float @var{a}, float @var{b})
-@deftypefnx {Runtime Function} int __unorddf2 (double @var{a}, double @var{b})
-@deftypefnx {Runtime Function} int __unordtf2 (long double @var{a}, long double @var{b})
-These functions return a nonzero value if either argument is NaN, otherwise 0.
-@end deftypefn
-
-There is also a complete group of higher level functions which
-correspond directly to comparison operators. They implement the ISO C
-semantics for floating-point comparisons, taking NaN into account.
-Pay careful attention to the return values defined for each set.
-Under the hood, all of these routines are implemented as
-
-@smallexample
- if (__unord@var{X}f2 (a, b))
- return @var{E};
- return __cmp@var{X}f2 (a, b);
-@end smallexample
-
-@noindent
-where @var{E} is a constant chosen to give the proper behavior for
-NaN@. Thus, the meaning of the return value is different for each set.
-Do not rely on this implementation; only the semantics documented
-below are guaranteed.
-
-@deftypefn {Runtime Function} int __eqsf2 (float @var{a}, float @var{b})
-@deftypefnx {Runtime Function} int __eqdf2 (double @var{a}, double @var{b})
-@deftypefnx {Runtime Function} int __eqtf2 (long double @var{a}, long double @var{b})
-These functions return zero if neither argument is NaN, and @var{a} and
-@var{b} are equal.
-@end deftypefn
-
-@deftypefn {Runtime Function} int __nesf2 (float @var{a}, float @var{b})
-@deftypefnx {Runtime Function} int __nedf2 (double @var{a}, double @var{b})
-@deftypefnx {Runtime Function} int __netf2 (long double @var{a}, long double @var{b})
-These functions return a nonzero value if either argument is NaN, or
-if @var{a} and @var{b} are unequal.
-@end deftypefn
-
-@deftypefn {Runtime Function} int __gesf2 (float @var{a}, float @var{b})
-@deftypefnx {Runtime Function} int __gedf2 (double @var{a}, double @var{b})
-@deftypefnx {Runtime Function} int __getf2 (long double @var{a}, long double @var{b})
-These functions return a value greater than or equal to zero if
-neither argument is NaN, and @var{a} is greater than or equal to
-@var{b}.
-@end deftypefn
-
-@deftypefn {Runtime Function} int __ltsf2 (float @var{a}, float @var{b})
-@deftypefnx {Runtime Function} int __ltdf2 (double @var{a}, double @var{b})
-@deftypefnx {Runtime Function} int __lttf2 (long double @var{a}, long double @var{b})
-These functions return a value less than zero if neither argument is
-NaN, and @var{a} is strictly less than @var{b}.
-@end deftypefn
-
-@deftypefn {Runtime Function} int __lesf2 (float @var{a}, float @var{b})
-@deftypefnx {Runtime Function} int __ledf2 (double @var{a}, double @var{b})
-@deftypefnx {Runtime Function} int __letf2 (long double @var{a}, long double @var{b})
-These functions return a value less than or equal to zero if neither
-argument is NaN, and @var{a} is less than or equal to @var{b}.
-@end deftypefn
-
-@deftypefn {Runtime Function} int __gtsf2 (float @var{a}, float @var{b})
-@deftypefnx {Runtime Function} int __gtdf2 (double @var{a}, double @var{b})
-@deftypefnx {Runtime Function} int __gttf2 (long double @var{a}, long double @var{b})
-These functions return a value greater than zero if neither argument
-is NaN, and @var{a} is strictly greater than @var{b}.
-@end deftypefn
-
-@subsection Other floating-point functions
-
-@deftypefn {Runtime Function} float __powisf2 (float @var{a}, int @var{b})
-@deftypefnx {Runtime Function} double __powidf2 (double @var{a}, int @var{b})
-@deftypefnx {Runtime Function} {long double} __powitf2 (long double @var{a}, int @var{b})
-@deftypefnx {Runtime Function} {long double} __powixf2 (long double @var{a}, int @var{b})
-These functions convert raise @var{a} to the power @var{b}.
-@end deftypefn
-
-@deftypefn {Runtime Function} {complex float} __mulsc3 (float @var{a}, float @var{b}, float @var{c}, float @var{d})
-@deftypefnx {Runtime Function} {complex double} __muldc3 (double @var{a}, double @var{b}, double @var{c}, double @var{d})
-@deftypefnx {Runtime Function} {complex long double} __multc3 (long double @var{a}, long double @var{b}, long double @var{c}, long double @var{d})
-@deftypefnx {Runtime Function} {complex long double} __mulxc3 (long double @var{a}, long double @var{b}, long double @var{c}, long double @var{d})
-These functions return the product of @math{@var{a} + i@var{b}} and
-@math{@var{c} + i@var{d}}, following the rules of C99 Annex G@.
-@end deftypefn
-
-@deftypefn {Runtime Function} {complex float} __divsc3 (float @var{a}, float @var{b}, float @var{c}, float @var{d})
-@deftypefnx {Runtime Function} {complex double} __divdc3 (double @var{a}, double @var{b}, double @var{c}, double @var{d})
-@deftypefnx {Runtime Function} {complex long double} __divtc3 (long double @var{a}, long double @var{b}, long double @var{c}, long double @var{d})
-@deftypefnx {Runtime Function} {complex long double} __divxc3 (long double @var{a}, long double @var{b}, long double @var{c}, long double @var{d})
-These functions return the quotient of @math{@var{a} + i@var{b}} and
-@math{@var{c} + i@var{d}} (i.e., @math{(@var{a} + i@var{b}) / (@var{c}
-+ i@var{d})}), following the rules of C99 Annex G@.
-@end deftypefn
-
-@node Decimal float library routines
-@section Routines for decimal floating point emulation
-@cindex decimal float library
-@cindex IEEE 754-2008
-
-The software decimal floating point library implements IEEE 754-2008
-decimal floating point arithmetic and is only activated on selected
-targets.
-
-The software decimal floating point library supports either DPD
-(Densely Packed Decimal) or BID (Binary Integer Decimal) encoding
-as selected at configure time.
-
-
-@subsection Arithmetic functions
-
-@deftypefn {Runtime Function} _Decimal32 __dpd_addsd3 (_Decimal32 @var{a}, _Decimal32 @var{b})
-@deftypefnx {Runtime Function} _Decimal32 __bid_addsd3 (_Decimal32 @var{a}, _Decimal32 @var{b})
-@deftypefnx {Runtime Function} _Decimal64 __dpd_adddd3 (_Decimal64 @var{a}, _Decimal64 @var{b})
-@deftypefnx {Runtime Function} _Decimal64 __bid_adddd3 (_Decimal64 @var{a}, _Decimal64 @var{b})
-@deftypefnx {Runtime Function} _Decimal128 __dpd_addtd3 (_Decimal128 @var{a}, _Decimal128 @var{b})
-@deftypefnx {Runtime Function} _Decimal128 __bid_addtd3 (_Decimal128 @var{a}, _Decimal128 @var{b})
-These functions return the sum of @var{a} and @var{b}.
-@end deftypefn
-
-@deftypefn {Runtime Function} _Decimal32 __dpd_subsd3 (_Decimal32 @var{a}, _Decimal32 @var{b})
-@deftypefnx {Runtime Function} _Decimal32 __bid_subsd3 (_Decimal32 @var{a}, _Decimal32 @var{b})
-@deftypefnx {Runtime Function} _Decimal64 __dpd_subdd3 (_Decimal64 @var{a}, _Decimal64 @var{b})
-@deftypefnx {Runtime Function} _Decimal64 __bid_subdd3 (_Decimal64 @var{a}, _Decimal64 @var{b})
-@deftypefnx {Runtime Function} _Decimal128 __dpd_subtd3 (_Decimal128 @var{a}, _Decimal128 @var{b})
-@deftypefnx {Runtime Function} _Decimal128 __bid_subtd3 (_Decimal128 @var{a}, _Decimal128 @var{b})
-These functions return the difference between @var{b} and @var{a};
-that is, @w{@math{@var{a} - @var{b}}}.
-@end deftypefn
-
-@deftypefn {Runtime Function} _Decimal32 __dpd_mulsd3 (_Decimal32 @var{a}, _Decimal32 @var{b})
-@deftypefnx {Runtime Function} _Decimal32 __bid_mulsd3 (_Decimal32 @var{a}, _Decimal32 @var{b})
-@deftypefnx {Runtime Function} _Decimal64 __dpd_muldd3 (_Decimal64 @var{a}, _Decimal64 @var{b})
-@deftypefnx {Runtime Function} _Decimal64 __bid_muldd3 (_Decimal64 @var{a}, _Decimal64 @var{b})
-@deftypefnx {Runtime Function} _Decimal128 __dpd_multd3 (_Decimal128 @var{a}, _Decimal128 @var{b})
-@deftypefnx {Runtime Function} _Decimal128 __bid_multd3 (_Decimal128 @var{a}, _Decimal128 @var{b})
-These functions return the product of @var{a} and @var{b}.
-@end deftypefn
-
-@deftypefn {Runtime Function} _Decimal32 __dpd_divsd3 (_Decimal32 @var{a}, _Decimal32 @var{b})
-@deftypefnx {Runtime Function} _Decimal32 __bid_divsd3 (_Decimal32 @var{a}, _Decimal32 @var{b})
-@deftypefnx {Runtime Function} _Decimal64 __dpd_divdd3 (_Decimal64 @var{a}, _Decimal64 @var{b})
-@deftypefnx {Runtime Function} _Decimal64 __bid_divdd3 (_Decimal64 @var{a}, _Decimal64 @var{b})
-@deftypefnx {Runtime Function} _Decimal128 __dpd_divtd3 (_Decimal128 @var{a}, _Decimal128 @var{b})
-@deftypefnx {Runtime Function} _Decimal128 __bid_divtd3 (_Decimal128 @var{a}, _Decimal128 @var{b})
-These functions return the quotient of @var{a} and @var{b}; that is,
-@w{@math{@var{a} / @var{b}}}.
-@end deftypefn
-
-@deftypefn {Runtime Function} _Decimal32 __dpd_negsd2 (_Decimal32 @var{a})
-@deftypefnx {Runtime Function} _Decimal32 __bid_negsd2 (_Decimal32 @var{a})
-@deftypefnx {Runtime Function} _Decimal64 __dpd_negdd2 (_Decimal64 @var{a})
-@deftypefnx {Runtime Function} _Decimal64 __bid_negdd2 (_Decimal64 @var{a})
-@deftypefnx {Runtime Function} _Decimal128 __dpd_negtd2 (_Decimal128 @var{a})
-@deftypefnx {Runtime Function} _Decimal128 __bid_negtd2 (_Decimal128 @var{a})
-These functions return the negation of @var{a}. They simply flip the
-sign bit, so they can produce negative zero and negative NaN@.
-@end deftypefn
-
-@subsection Conversion functions
-
-@deftypefn {Runtime Function} _Decimal64 __dpd_extendsddd2 (_Decimal32 @var{a})
-@deftypefnx {Runtime Function} _Decimal64 __bid_extendsddd2 (_Decimal32 @var{a})
-@deftypefnx {Runtime Function} _Decimal128 __dpd_extendsdtd2 (_Decimal32 @var{a})
-@deftypefnx {Runtime Function} _Decimal128 __bid_extendsdtd2 (_Decimal32 @var{a})
-@deftypefnx {Runtime Function} _Decimal128 __dpd_extendddtd2 (_Decimal64 @var{a})
-@deftypefnx {Runtime Function} _Decimal128 __bid_extendddtd2 (_Decimal64 @var{a})
-@deftypefnx {Runtime Function} _Decimal32 __dpd_truncddsd2 (_Decimal64 @var{a})
-@deftypefnx {Runtime Function} _Decimal32 __bid_truncddsd2 (_Decimal64 @var{a})
-@deftypefnx {Runtime Function} _Decimal32 __dpd_trunctdsd2 (_Decimal128 @var{a})
-@deftypefnx {Runtime Function} _Decimal32 __bid_trunctdsd2 (_Decimal128 @var{a})
-@deftypefnx {Runtime Function} _Decimal64 __dpd_trunctddd2 (_Decimal128 @var{a})
-@deftypefnx {Runtime Function} _Decimal64 __bid_trunctddd2 (_Decimal128 @var{a})
-These functions convert the value @var{a} from one decimal floating type
-to another.
-@end deftypefn
-
-@deftypefn {Runtime Function} _Decimal64 __dpd_extendsfdd (float @var{a})
-@deftypefnx {Runtime Function} _Decimal64 __bid_extendsfdd (float @var{a})
-@deftypefnx {Runtime Function} _Decimal128 __dpd_extendsftd (float @var{a})
-@deftypefnx {Runtime Function} _Decimal128 __bid_extendsftd (float @var{a})
-@deftypefnx {Runtime Function} _Decimal128 __dpd_extenddftd (double @var{a})
-@deftypefnx {Runtime Function} _Decimal128 __bid_extenddftd (double @var{a})
-@deftypefnx {Runtime Function} _Decimal128 __dpd_extendxftd ({long double} @var{a})
-@deftypefnx {Runtime Function} _Decimal128 __bid_extendxftd ({long double} @var{a})
-@deftypefnx {Runtime Function} _Decimal32 __dpd_truncdfsd (double @var{a})
-@deftypefnx {Runtime Function} _Decimal32 __bid_truncdfsd (double @var{a})
-@deftypefnx {Runtime Function} _Decimal32 __dpd_truncxfsd ({long double} @var{a})
-@deftypefnx {Runtime Function} _Decimal32 __bid_truncxfsd ({long double} @var{a})
-@deftypefnx {Runtime Function} _Decimal32 __dpd_trunctfsd ({long double} @var{a})
-@deftypefnx {Runtime Function} _Decimal32 __bid_trunctfsd ({long double} @var{a})
-@deftypefnx {Runtime Function} _Decimal64 __dpd_truncxfdd ({long double} @var{a})
-@deftypefnx {Runtime Function} _Decimal64 __bid_truncxfdd ({long double} @var{a})
-@deftypefnx {Runtime Function} _Decimal64 __dpd_trunctfdd ({long double} @var{a})
-@deftypefnx {Runtime Function} _Decimal64 __bid_trunctfdd ({long double} @var{a})
-These functions convert the value of @var{a} from a binary floating type
-to a decimal floating type of a different size.
-@end deftypefn
-
-@deftypefn {Runtime Function} float __dpd_truncddsf (_Decimal64 @var{a})
-@deftypefnx {Runtime Function} float __bid_truncddsf (_Decimal64 @var{a})
-@deftypefnx {Runtime Function} float __dpd_trunctdsf (_Decimal128 @var{a})
-@deftypefnx {Runtime Function} float __bid_trunctdsf (_Decimal128 @var{a})
-@deftypefnx {Runtime Function} double __dpd_extendsddf (_Decimal32 @var{a})
-@deftypefnx {Runtime Function} double __bid_extendsddf (_Decimal32 @var{a})
-@deftypefnx {Runtime Function} double __dpd_trunctddf (_Decimal128 @var{a})
-@deftypefnx {Runtime Function} double __bid_trunctddf (_Decimal128 @var{a})
-@deftypefnx {Runtime Function} {long double} __dpd_extendsdxf (_Decimal32 @var{a})
-@deftypefnx {Runtime Function} {long double} __bid_extendsdxf (_Decimal32 @var{a})
-@deftypefnx {Runtime Function} {long double} __dpd_extendddxf (_Decimal64 @var{a})
-@deftypefnx {Runtime Function} {long double} __bid_extendddxf (_Decimal64 @var{a})
-@deftypefnx {Runtime Function} {long double} __dpd_trunctdxf (_Decimal128 @var{a})
-@deftypefnx {Runtime Function} {long double} __bid_trunctdxf (_Decimal128 @var{a})
-@deftypefnx {Runtime Function} {long double} __dpd_extendsdtf (_Decimal32 @var{a})
-@deftypefnx {Runtime Function} {long double} __bid_extendsdtf (_Decimal32 @var{a})
-@deftypefnx {Runtime Function} {long double} __dpd_extendddtf (_Decimal64 @var{a})
-@deftypefnx {Runtime Function} {long double} __bid_extendddtf (_Decimal64 @var{a})
-These functions convert the value of @var{a} from a decimal floating type
-to a binary floating type of a different size.
-@end deftypefn
-
-@deftypefn {Runtime Function} _Decimal32 __dpd_extendsfsd (float @var{a})
-@deftypefnx {Runtime Function} _Decimal32 __bid_extendsfsd (float @var{a})
-@deftypefnx {Runtime Function} _Decimal64 __dpd_extenddfdd (double @var{a})
-@deftypefnx {Runtime Function} _Decimal64 __bid_extenddfdd (double @var{a})
-@deftypefnx {Runtime Function} _Decimal128 __dpd_extendtftd ({long double} @var{a})
-@deftypefnx {Runtime Function} _Decimal128 __bid_extendtftd ({long double} @var{a})
-@deftypefnx {Runtime Function} float __dpd_truncsdsf (_Decimal32 @var{a})
-@deftypefnx {Runtime Function} float __bid_truncsdsf (_Decimal32 @var{a})
-@deftypefnx {Runtime Function} double __dpd_truncdddf (_Decimal64 @var{a})
-@deftypefnx {Runtime Function} double __bid_truncdddf (_Decimal64 @var{a})
-@deftypefnx {Runtime Function} {long double} __dpd_trunctdtf (_Decimal128 @var{a})
-@deftypefnx {Runtime Function} {long double} __bid_trunctdtf (_Decimal128 @var{a})
-These functions convert the value of @var{a} between decimal and
-binary floating types of the same size.
-@end deftypefn
-
-@deftypefn {Runtime Function} int __dpd_fixsdsi (_Decimal32 @var{a})
-@deftypefnx {Runtime Function} int __bid_fixsdsi (_Decimal32 @var{a})
-@deftypefnx {Runtime Function} int __dpd_fixddsi (_Decimal64 @var{a})
-@deftypefnx {Runtime Function} int __bid_fixddsi (_Decimal64 @var{a})
-@deftypefnx {Runtime Function} int __dpd_fixtdsi (_Decimal128 @var{a})
-@deftypefnx {Runtime Function} int __bid_fixtdsi (_Decimal128 @var{a})
-These functions convert @var{a} to a signed integer.
-@end deftypefn
-
-@deftypefn {Runtime Function} long __dpd_fixsddi (_Decimal32 @var{a})
-@deftypefnx {Runtime Function} long __bid_fixsddi (_Decimal32 @var{a})
-@deftypefnx {Runtime Function} long __dpd_fixdddi (_Decimal64 @var{a})
-@deftypefnx {Runtime Function} long __bid_fixdddi (_Decimal64 @var{a})
-@deftypefnx {Runtime Function} long __dpd_fixtddi (_Decimal128 @var{a})
-@deftypefnx {Runtime Function} long __bid_fixtddi (_Decimal128 @var{a})
-These functions convert @var{a} to a signed long.
-@end deftypefn
-
-@deftypefn {Runtime Function} {unsigned int} __dpd_fixunssdsi (_Decimal32 @var{a})
-@deftypefnx {Runtime Function} {unsigned int} __bid_fixunssdsi (_Decimal32 @var{a})
-@deftypefnx {Runtime Function} {unsigned int} __dpd_fixunsddsi (_Decimal64 @var{a})
-@deftypefnx {Runtime Function} {unsigned int} __bid_fixunsddsi (_Decimal64 @var{a})
-@deftypefnx {Runtime Function} {unsigned int} __dpd_fixunstdsi (_Decimal128 @var{a})
-@deftypefnx {Runtime Function} {unsigned int} __bid_fixunstdsi (_Decimal128 @var{a})
-These functions convert @var{a} to an unsigned integer. Negative values all become zero.
-@end deftypefn
-
-@deftypefn {Runtime Function} {unsigned long} __dpd_fixunssddi (_Decimal32 @var{a})
-@deftypefnx {Runtime Function} {unsigned long} __bid_fixunssddi (_Decimal32 @var{a})
-@deftypefnx {Runtime Function} {unsigned long} __dpd_fixunsdddi (_Decimal64 @var{a})
-@deftypefnx {Runtime Function} {unsigned long} __bid_fixunsdddi (_Decimal64 @var{a})
-@deftypefnx {Runtime Function} {unsigned long} __dpd_fixunstddi (_Decimal128 @var{a})
-@deftypefnx {Runtime Function} {unsigned long} __bid_fixunstddi (_Decimal128 @var{a})
-These functions convert @var{a} to an unsigned long. Negative values
-all become zero.
-@end deftypefn
-
-@deftypefn {Runtime Function} _Decimal32 __dpd_floatsisd (int @var{i})
-@deftypefnx {Runtime Function} _Decimal32 __bid_floatsisd (int @var{i})
-@deftypefnx {Runtime Function} _Decimal64 __dpd_floatsidd (int @var{i})
-@deftypefnx {Runtime Function} _Decimal64 __bid_floatsidd (int @var{i})
-@deftypefnx {Runtime Function} _Decimal128 __dpd_floatsitd (int @var{i})
-@deftypefnx {Runtime Function} _Decimal128 __bid_floatsitd (int @var{i})
-These functions convert @var{i}, a signed integer, to decimal floating point.
-@end deftypefn
-
-@deftypefn {Runtime Function} _Decimal32 __dpd_floatdisd (long @var{i})
-@deftypefnx {Runtime Function} _Decimal32 __bid_floatdisd (long @var{i})
-@deftypefnx {Runtime Function} _Decimal64 __dpd_floatdidd (long @var{i})
-@deftypefnx {Runtime Function} _Decimal64 __bid_floatdidd (long @var{i})
-@deftypefnx {Runtime Function} _Decimal128 __dpd_floatditd (long @var{i})
-@deftypefnx {Runtime Function} _Decimal128 __bid_floatditd (long @var{i})
-These functions convert @var{i}, a signed long, to decimal floating point.
-@end deftypefn
-
-@deftypefn {Runtime Function} _Decimal32 __dpd_floatunssisd (unsigned int @var{i})
-@deftypefnx {Runtime Function} _Decimal32 __bid_floatunssisd (unsigned int @var{i})
-@deftypefnx {Runtime Function} _Decimal64 __dpd_floatunssidd (unsigned int @var{i})
-@deftypefnx {Runtime Function} _Decimal64 __bid_floatunssidd (unsigned int @var{i})
-@deftypefnx {Runtime Function} _Decimal128 __dpd_floatunssitd (unsigned int @var{i})
-@deftypefnx {Runtime Function} _Decimal128 __bid_floatunssitd (unsigned int @var{i})
-These functions convert @var{i}, an unsigned integer, to decimal floating point.
-@end deftypefn
-
-@deftypefn {Runtime Function} _Decimal32 __dpd_floatunsdisd (unsigned long @var{i})
-@deftypefnx {Runtime Function} _Decimal32 __bid_floatunsdisd (unsigned long @var{i})
-@deftypefnx {Runtime Function} _Decimal64 __dpd_floatunsdidd (unsigned long @var{i})
-@deftypefnx {Runtime Function} _Decimal64 __bid_floatunsdidd (unsigned long @var{i})
-@deftypefnx {Runtime Function} _Decimal128 __dpd_floatunsditd (unsigned long @var{i})
-@deftypefnx {Runtime Function} _Decimal128 __bid_floatunsditd (unsigned long @var{i})
-These functions convert @var{i}, an unsigned long, to decimal floating point.
-@end deftypefn
-
-@subsection Comparison functions
-
-@deftypefn {Runtime Function} int __dpd_unordsd2 (_Decimal32 @var{a}, _Decimal32 @var{b})
-@deftypefnx {Runtime Function} int __bid_unordsd2 (_Decimal32 @var{a}, _Decimal32 @var{b})
-@deftypefnx {Runtime Function} int __dpd_unorddd2 (_Decimal64 @var{a}, _Decimal64 @var{b})
-@deftypefnx {Runtime Function} int __bid_unorddd2 (_Decimal64 @var{a}, _Decimal64 @var{b})
-@deftypefnx {Runtime Function} int __dpd_unordtd2 (_Decimal128 @var{a}, _Decimal128 @var{b})
-@deftypefnx {Runtime Function} int __bid_unordtd2 (_Decimal128 @var{a}, _Decimal128 @var{b})
-These functions return a nonzero value if either argument is NaN, otherwise 0.
-@end deftypefn
-
-There is also a complete group of higher level functions which
-correspond directly to comparison operators. They implement the ISO C
-semantics for floating-point comparisons, taking NaN into account.
-Pay careful attention to the return values defined for each set.
-Under the hood, all of these routines are implemented as
-
-@smallexample
- if (__bid_unord@var{X}d2 (a, b))
- return @var{E};
- return __bid_cmp@var{X}d2 (a, b);
-@end smallexample
-
-@noindent
-where @var{E} is a constant chosen to give the proper behavior for
-NaN@. Thus, the meaning of the return value is different for each set.
-Do not rely on this implementation; only the semantics documented
-below are guaranteed.
-
-@deftypefn {Runtime Function} int __dpd_eqsd2 (_Decimal32 @var{a}, _Decimal32 @var{b})
-@deftypefnx {Runtime Function} int __bid_eqsd2 (_Decimal32 @var{a}, _Decimal32 @var{b})
-@deftypefnx {Runtime Function} int __dpd_eqdd2 (_Decimal64 @var{a}, _Decimal64 @var{b})
-@deftypefnx {Runtime Function} int __bid_eqdd2 (_Decimal64 @var{a}, _Decimal64 @var{b})
-@deftypefnx {Runtime Function} int __dpd_eqtd2 (_Decimal128 @var{a}, _Decimal128 @var{b})
-@deftypefnx {Runtime Function} int __bid_eqtd2 (_Decimal128 @var{a}, _Decimal128 @var{b})
-These functions return zero if neither argument is NaN, and @var{a} and
-@var{b} are equal.
-@end deftypefn
-
-@deftypefn {Runtime Function} int __dpd_nesd2 (_Decimal32 @var{a}, _Decimal32 @var{b})
-@deftypefnx {Runtime Function} int __bid_nesd2 (_Decimal32 @var{a}, _Decimal32 @var{b})
-@deftypefnx {Runtime Function} int __dpd_nedd2 (_Decimal64 @var{a}, _Decimal64 @var{b})
-@deftypefnx {Runtime Function} int __bid_nedd2 (_Decimal64 @var{a}, _Decimal64 @var{b})
-@deftypefnx {Runtime Function} int __dpd_netd2 (_Decimal128 @var{a}, _Decimal128 @var{b})
-@deftypefnx {Runtime Function} int __bid_netd2 (_Decimal128 @var{a}, _Decimal128 @var{b})
-These functions return a nonzero value if either argument is NaN, or
-if @var{a} and @var{b} are unequal.
-@end deftypefn
-
-@deftypefn {Runtime Function} int __dpd_gesd2 (_Decimal32 @var{a}, _Decimal32 @var{b})
-@deftypefnx {Runtime Function} int __bid_gesd2 (_Decimal32 @var{a}, _Decimal32 @var{b})
-@deftypefnx {Runtime Function} int __dpd_gedd2 (_Decimal64 @var{a}, _Decimal64 @var{b})
-@deftypefnx {Runtime Function} int __bid_gedd2 (_Decimal64 @var{a}, _Decimal64 @var{b})
-@deftypefnx {Runtime Function} int __dpd_getd2 (_Decimal128 @var{a}, _Decimal128 @var{b})
-@deftypefnx {Runtime Function} int __bid_getd2 (_Decimal128 @var{a}, _Decimal128 @var{b})
-These functions return a value greater than or equal to zero if
-neither argument is NaN, and @var{a} is greater than or equal to
-@var{b}.
-@end deftypefn
-
-@deftypefn {Runtime Function} int __dpd_ltsd2 (_Decimal32 @var{a}, _Decimal32 @var{b})
-@deftypefnx {Runtime Function} int __bid_ltsd2 (_Decimal32 @var{a}, _Decimal32 @var{b})
-@deftypefnx {Runtime Function} int __dpd_ltdd2 (_Decimal64 @var{a}, _Decimal64 @var{b})
-@deftypefnx {Runtime Function} int __bid_ltdd2 (_Decimal64 @var{a}, _Decimal64 @var{b})
-@deftypefnx {Runtime Function} int __dpd_lttd2 (_Decimal128 @var{a}, _Decimal128 @var{b})
-@deftypefnx {Runtime Function} int __bid_lttd2 (_Decimal128 @var{a}, _Decimal128 @var{b})
-These functions return a value less than zero if neither argument is
-NaN, and @var{a} is strictly less than @var{b}.
-@end deftypefn
-
-@deftypefn {Runtime Function} int __dpd_lesd2 (_Decimal32 @var{a}, _Decimal32 @var{b})
-@deftypefnx {Runtime Function} int __bid_lesd2 (_Decimal32 @var{a}, _Decimal32 @var{b})
-@deftypefnx {Runtime Function} int __dpd_ledd2 (_Decimal64 @var{a}, _Decimal64 @var{b})
-@deftypefnx {Runtime Function} int __bid_ledd2 (_Decimal64 @var{a}, _Decimal64 @var{b})
-@deftypefnx {Runtime Function} int __dpd_letd2 (_Decimal128 @var{a}, _Decimal128 @var{b})
-@deftypefnx {Runtime Function} int __bid_letd2 (_Decimal128 @var{a}, _Decimal128 @var{b})
-These functions return a value less than or equal to zero if neither
-argument is NaN, and @var{a} is less than or equal to @var{b}.
-@end deftypefn
-
-@deftypefn {Runtime Function} int __dpd_gtsd2 (_Decimal32 @var{a}, _Decimal32 @var{b})
-@deftypefnx {Runtime Function} int __bid_gtsd2 (_Decimal32 @var{a}, _Decimal32 @var{b})
-@deftypefnx {Runtime Function} int __dpd_gtdd2 (_Decimal64 @var{a}, _Decimal64 @var{b})
-@deftypefnx {Runtime Function} int __bid_gtdd2 (_Decimal64 @var{a}, _Decimal64 @var{b})
-@deftypefnx {Runtime Function} int __dpd_gttd2 (_Decimal128 @var{a}, _Decimal128 @var{b})
-@deftypefnx {Runtime Function} int __bid_gttd2 (_Decimal128 @var{a}, _Decimal128 @var{b})
-These functions return a value greater than zero if neither argument
-is NaN, and @var{a} is strictly greater than @var{b}.
-@end deftypefn
-
-@node Fixed-point fractional library routines
-@section Routines for fixed-point fractional emulation
-@cindex fixed-point fractional library
-@cindex fractional types
-@cindex Embedded C
-
-The software fixed-point library implements fixed-point fractional
-arithmetic, and is only activated on selected targets.
-
-For ease of comprehension @code{fract} is an alias for the
-@code{_Fract} type, @code{accum} an alias for @code{_Accum}, and
-@code{sat} an alias for @code{_Sat}.
-
-For illustrative purposes, in this section the fixed-point fractional type
-@code{@w{short fract}} is assumed to correspond to machine mode @code{QQmode};
-@code{@w{unsigned short fract}} to @code{UQQmode};
-@code{fract} to @code{HQmode};
-@code{@w{unsigned fract}} to @code{UHQmode};
-@code{@w{long fract}} to @code{SQmode};
-@code{@w{unsigned long fract}} to @code{USQmode};
-@code{@w{long long fract}} to @code{DQmode};
-and @code{@w{unsigned long long fract}} to @code{UDQmode}.
-Similarly the fixed-point accumulator type
-@code{@w{short accum}} corresponds to @code{HAmode};
-@code{@w{unsigned short accum}} to @code{UHAmode};
-@code{accum} to @code{SAmode};
-@code{@w{unsigned accum}} to @code{USAmode};
-@code{@w{long accum}} to @code{DAmode};
-@code{@w{unsigned long accum}} to @code{UDAmode};
-@code{@w{long long accum}} to @code{TAmode};
-and @code{@w{unsigned long long accum}} to @code{UTAmode}.
-
-@subsection Arithmetic functions
-
-@deftypefn {Runtime Function} {short fract} __addqq3 (short fract @var{a}, short fract @var{b})
-@deftypefnx {Runtime Function} {fract} __addhq3 (fract @var{a}, fract @var{b})
-@deftypefnx {Runtime Function} {long fract} __addsq3 (long fract @var{a}, long fract @var{b})
-@deftypefnx {Runtime Function} {long long fract} __adddq3 (long long fract @var{a}, long long fract @var{b})
-@deftypefnx {Runtime Function} {unsigned short fract} __adduqq3 (unsigned short fract @var{a}, unsigned short fract @var{b})
-@deftypefnx {Runtime Function} {unsigned fract} __adduhq3 (unsigned fract @var{a}, unsigned fract @var{b})
-@deftypefnx {Runtime Function} {unsigned long fract} __addusq3 (unsigned long fract @var{a}, unsigned long fract @var{b})
-@deftypefnx {Runtime Function} {unsigned long long fract} __addudq3 (unsigned long long fract @var{a}, unsigned long long fract @var{b})
-@deftypefnx {Runtime Function} {short accum} __addha3 (short accum @var{a}, short accum @var{b})
-@deftypefnx {Runtime Function} {accum} __addsa3 (accum @var{a}, accum @var{b})
-@deftypefnx {Runtime Function} {long accum} __addda3 (long accum @var{a}, long accum @var{b})
-@deftypefnx {Runtime Function} {long long accum} __addta3 (long long accum @var{a}, long long accum @var{b})
-@deftypefnx {Runtime Function} {unsigned short accum} __adduha3 (unsigned short accum @var{a}, unsigned short accum @var{b})
-@deftypefnx {Runtime Function} {unsigned accum} __addusa3 (unsigned accum @var{a}, unsigned accum @var{b})
-@deftypefnx {Runtime Function} {unsigned long accum} __adduda3 (unsigned long accum @var{a}, unsigned long accum @var{b})
-@deftypefnx {Runtime Function} {unsigned long long accum} __adduta3 (unsigned long long accum @var{a}, unsigned long long accum @var{b})
-These functions return the sum of @var{a} and @var{b}.
-@end deftypefn
-
-@deftypefn {Runtime Function} {short fract} __ssaddqq3 (short fract @var{a}, short fract @var{b})
-@deftypefnx {Runtime Function} {fract} __ssaddhq3 (fract @var{a}, fract @var{b})
-@deftypefnx {Runtime Function} {long fract} __ssaddsq3 (long fract @var{a}, long fract @var{b})
-@deftypefnx {Runtime Function} {long long fract} __ssadddq3 (long long fract @var{a}, long long fract @var{b})
-@deftypefnx {Runtime Function} {short accum} __ssaddha3 (short accum @var{a}, short accum @var{b})
-@deftypefnx {Runtime Function} {accum} __ssaddsa3 (accum @var{a}, accum @var{b})
-@deftypefnx {Runtime Function} {long accum} __ssaddda3 (long accum @var{a}, long accum @var{b})
-@deftypefnx {Runtime Function} {long long accum} __ssaddta3 (long long accum @var{a}, long long accum @var{b})
-These functions return the sum of @var{a} and @var{b} with signed saturation.
-@end deftypefn
-
-@deftypefn {Runtime Function} {unsigned short fract} __usadduqq3 (unsigned short fract @var{a}, unsigned short fract @var{b})
-@deftypefnx {Runtime Function} {unsigned fract} __usadduhq3 (unsigned fract @var{a}, unsigned fract @var{b})
-@deftypefnx {Runtime Function} {unsigned long fract} __usaddusq3 (unsigned long fract @var{a}, unsigned long fract @var{b})
-@deftypefnx {Runtime Function} {unsigned long long fract} __usaddudq3 (unsigned long long fract @var{a}, unsigned long long fract @var{b})
-@deftypefnx {Runtime Function} {unsigned short accum} __usadduha3 (unsigned short accum @var{a}, unsigned short accum @var{b})
-@deftypefnx {Runtime Function} {unsigned accum} __usaddusa3 (unsigned accum @var{a}, unsigned accum @var{b})
-@deftypefnx {Runtime Function} {unsigned long accum} __usadduda3 (unsigned long accum @var{a}, unsigned long accum @var{b})
-@deftypefnx {Runtime Function} {unsigned long long accum} __usadduta3 (unsigned long long accum @var{a}, unsigned long long accum @var{b})
-These functions return the sum of @var{a} and @var{b} with unsigned saturation.
-@end deftypefn
-
-@deftypefn {Runtime Function} {short fract} __subqq3 (short fract @var{a}, short fract @var{b})
-@deftypefnx {Runtime Function} {fract} __subhq3 (fract @var{a}, fract @var{b})
-@deftypefnx {Runtime Function} {long fract} __subsq3 (long fract @var{a}, long fract @var{b})
-@deftypefnx {Runtime Function} {long long fract} __subdq3 (long long fract @var{a}, long long fract @var{b})
-@deftypefnx {Runtime Function} {unsigned short fract} __subuqq3 (unsigned short fract @var{a}, unsigned short fract @var{b})
-@deftypefnx {Runtime Function} {unsigned fract} __subuhq3 (unsigned fract @var{a}, unsigned fract @var{b})
-@deftypefnx {Runtime Function} {unsigned long fract} __subusq3 (unsigned long fract @var{a}, unsigned long fract @var{b})
-@deftypefnx {Runtime Function} {unsigned long long fract} __subudq3 (unsigned long long fract @var{a}, unsigned long long fract @var{b})
-@deftypefnx {Runtime Function} {short accum} __subha3 (short accum @var{a}, short accum @var{b})
-@deftypefnx {Runtime Function} {accum} __subsa3 (accum @var{a}, accum @var{b})
-@deftypefnx {Runtime Function} {long accum} __subda3 (long accum @var{a}, long accum @var{b})
-@deftypefnx {Runtime Function} {long long accum} __subta3 (long long accum @var{a}, long long accum @var{b})
-@deftypefnx {Runtime Function} {unsigned short accum} __subuha3 (unsigned short accum @var{a}, unsigned short accum @var{b})
-@deftypefnx {Runtime Function} {unsigned accum} __subusa3 (unsigned accum @var{a}, unsigned accum @var{b})
-@deftypefnx {Runtime Function} {unsigned long accum} __subuda3 (unsigned long accum @var{a}, unsigned long accum @var{b})
-@deftypefnx {Runtime Function} {unsigned long long accum} __subuta3 (unsigned long long accum @var{a}, unsigned long long accum @var{b})
-These functions return the difference of @var{a} and @var{b};
-that is, @code{@var{a} - @var{b}}.
-@end deftypefn
-
-@deftypefn {Runtime Function} {short fract} __sssubqq3 (short fract @var{a}, short fract @var{b})
-@deftypefnx {Runtime Function} {fract} __sssubhq3 (fract @var{a}, fract @var{b})
-@deftypefnx {Runtime Function} {long fract} __sssubsq3 (long fract @var{a}, long fract @var{b})
-@deftypefnx {Runtime Function} {long long fract} __sssubdq3 (long long fract @var{a}, long long fract @var{b})
-@deftypefnx {Runtime Function} {short accum} __sssubha3 (short accum @var{a}, short accum @var{b})
-@deftypefnx {Runtime Function} {accum} __sssubsa3 (accum @var{a}, accum @var{b})
-@deftypefnx {Runtime Function} {long accum} __sssubda3 (long accum @var{a}, long accum @var{b})
-@deftypefnx {Runtime Function} {long long accum} __sssubta3 (long long accum @var{a}, long long accum @var{b})
-These functions return the difference of @var{a} and @var{b} with signed
-saturation; that is, @code{@var{a} - @var{b}}.
-@end deftypefn
-
-@deftypefn {Runtime Function} {unsigned short fract} __ussubuqq3 (unsigned short fract @var{a}, unsigned short fract @var{b})
-@deftypefnx {Runtime Function} {unsigned fract} __ussubuhq3 (unsigned fract @var{a}, unsigned fract @var{b})
-@deftypefnx {Runtime Function} {unsigned long fract} __ussubusq3 (unsigned long fract @var{a}, unsigned long fract @var{b})
-@deftypefnx {Runtime Function} {unsigned long long fract} __ussubudq3 (unsigned long long fract @var{a}, unsigned long long fract @var{b})
-@deftypefnx {Runtime Function} {unsigned short accum} __ussubuha3 (unsigned short accum @var{a}, unsigned short accum @var{b})
-@deftypefnx {Runtime Function} {unsigned accum} __ussubusa3 (unsigned accum @var{a}, unsigned accum @var{b})
-@deftypefnx {Runtime Function} {unsigned long accum} __ussubuda3 (unsigned long accum @var{a}, unsigned long accum @var{b})
-@deftypefnx {Runtime Function} {unsigned long long accum} __ussubuta3 (unsigned long long accum @var{a}, unsigned long long accum @var{b})
-These functions return the difference of @var{a} and @var{b} with unsigned
-saturation; that is, @code{@var{a} - @var{b}}.
-@end deftypefn
-
-@deftypefn {Runtime Function} {short fract} __mulqq3 (short fract @var{a}, short fract @var{b})
-@deftypefnx {Runtime Function} {fract} __mulhq3 (fract @var{a}, fract @var{b})
-@deftypefnx {Runtime Function} {long fract} __mulsq3 (long fract @var{a}, long fract @var{b})
-@deftypefnx {Runtime Function} {long long fract} __muldq3 (long long fract @var{a}, long long fract @var{b})
-@deftypefnx {Runtime Function} {unsigned short fract} __muluqq3 (unsigned short fract @var{a}, unsigned short fract @var{b})
-@deftypefnx {Runtime Function} {unsigned fract} __muluhq3 (unsigned fract @var{a}, unsigned fract @var{b})
-@deftypefnx {Runtime Function} {unsigned long fract} __mulusq3 (unsigned long fract @var{a}, unsigned long fract @var{b})
-@deftypefnx {Runtime Function} {unsigned long long fract} __muludq3 (unsigned long long fract @var{a}, unsigned long long fract @var{b})
-@deftypefnx {Runtime Function} {short accum} __mulha3 (short accum @var{a}, short accum @var{b})
-@deftypefnx {Runtime Function} {accum} __mulsa3 (accum @var{a}, accum @var{b})
-@deftypefnx {Runtime Function} {long accum} __mulda3 (long accum @var{a}, long accum @var{b})
-@deftypefnx {Runtime Function} {long long accum} __multa3 (long long accum @var{a}, long long accum @var{b})
-@deftypefnx {Runtime Function} {unsigned short accum} __muluha3 (unsigned short accum @var{a}, unsigned short accum @var{b})
-@deftypefnx {Runtime Function} {unsigned accum} __mulusa3 (unsigned accum @var{a}, unsigned accum @var{b})
-@deftypefnx {Runtime Function} {unsigned long accum} __muluda3 (unsigned long accum @var{a}, unsigned long accum @var{b})
-@deftypefnx {Runtime Function} {unsigned long long accum} __muluta3 (unsigned long long accum @var{a}, unsigned long long accum @var{b})
-These functions return the product of @var{a} and @var{b}.
-@end deftypefn
-
-@deftypefn {Runtime Function} {short fract} __ssmulqq3 (short fract @var{a}, short fract @var{b})
-@deftypefnx {Runtime Function} {fract} __ssmulhq3 (fract @var{a}, fract @var{b})
-@deftypefnx {Runtime Function} {long fract} __ssmulsq3 (long fract @var{a}, long fract @var{b})
-@deftypefnx {Runtime Function} {long long fract} __ssmuldq3 (long long fract @var{a}, long long fract @var{b})
-@deftypefnx {Runtime Function} {short accum} __ssmulha3 (short accum @var{a}, short accum @var{b})
-@deftypefnx {Runtime Function} {accum} __ssmulsa3 (accum @var{a}, accum @var{b})
-@deftypefnx {Runtime Function} {long accum} __ssmulda3 (long accum @var{a}, long accum @var{b})
-@deftypefnx {Runtime Function} {long long accum} __ssmulta3 (long long accum @var{a}, long long accum @var{b})
-These functions return the product of @var{a} and @var{b} with signed
-saturation.
-@end deftypefn
-
-@deftypefn {Runtime Function} {unsigned short fract} __usmuluqq3 (unsigned short fract @var{a}, unsigned short fract @var{b})
-@deftypefnx {Runtime Function} {unsigned fract} __usmuluhq3 (unsigned fract @var{a}, unsigned fract @var{b})
-@deftypefnx {Runtime Function} {unsigned long fract} __usmulusq3 (unsigned long fract @var{a}, unsigned long fract @var{b})
-@deftypefnx {Runtime Function} {unsigned long long fract} __usmuludq3 (unsigned long long fract @var{a}, unsigned long long fract @var{b})
-@deftypefnx {Runtime Function} {unsigned short accum} __usmuluha3 (unsigned short accum @var{a}, unsigned short accum @var{b})
-@deftypefnx {Runtime Function} {unsigned accum} __usmulusa3 (unsigned accum @var{a}, unsigned accum @var{b})
-@deftypefnx {Runtime Function} {unsigned long accum} __usmuluda3 (unsigned long accum @var{a}, unsigned long accum @var{b})
-@deftypefnx {Runtime Function} {unsigned long long accum} __usmuluta3 (unsigned long long accum @var{a}, unsigned long long accum @var{b})
-These functions return the product of @var{a} and @var{b} with unsigned
-saturation.
-@end deftypefn
-
-@deftypefn {Runtime Function} {short fract} __divqq3 (short fract @var{a}, short fract @var{b})
-@deftypefnx {Runtime Function} {fract} __divhq3 (fract @var{a}, fract @var{b})
-@deftypefnx {Runtime Function} {long fract} __divsq3 (long fract @var{a}, long fract @var{b})
-@deftypefnx {Runtime Function} {long long fract} __divdq3 (long long fract @var{a}, long long fract @var{b})
-@deftypefnx {Runtime Function} {short accum} __divha3 (short accum @var{a}, short accum @var{b})
-@deftypefnx {Runtime Function} {accum} __divsa3 (accum @var{a}, accum @var{b})
-@deftypefnx {Runtime Function} {long accum} __divda3 (long accum @var{a}, long accum @var{b})
-@deftypefnx {Runtime Function} {long long accum} __divta3 (long long accum @var{a}, long long accum @var{b})
-These functions return the quotient of the signed division of @var{a}
-and @var{b}.
-@end deftypefn
-
-@deftypefn {Runtime Function} {unsigned short fract} __udivuqq3 (unsigned short fract @var{a}, unsigned short fract @var{b})
-@deftypefnx {Runtime Function} {unsigned fract} __udivuhq3 (unsigned fract @var{a}, unsigned fract @var{b})
-@deftypefnx {Runtime Function} {unsigned long fract} __udivusq3 (unsigned long fract @var{a}, unsigned long fract @var{b})
-@deftypefnx {Runtime Function} {unsigned long long fract} __udivudq3 (unsigned long long fract @var{a}, unsigned long long fract @var{b})
-@deftypefnx {Runtime Function} {unsigned short accum} __udivuha3 (unsigned short accum @var{a}, unsigned short accum @var{b})
-@deftypefnx {Runtime Function} {unsigned accum} __udivusa3 (unsigned accum @var{a}, unsigned accum @var{b})
-@deftypefnx {Runtime Function} {unsigned long accum} __udivuda3 (unsigned long accum @var{a}, unsigned long accum @var{b})
-@deftypefnx {Runtime Function} {unsigned long long accum} __udivuta3 (unsigned long long accum @var{a}, unsigned long long accum @var{b})
-These functions return the quotient of the unsigned division of @var{a}
-and @var{b}.
-@end deftypefn
-
-@deftypefn {Runtime Function} {short fract} __ssdivqq3 (short fract @var{a}, short fract @var{b})
-@deftypefnx {Runtime Function} {fract} __ssdivhq3 (fract @var{a}, fract @var{b})
-@deftypefnx {Runtime Function} {long fract} __ssdivsq3 (long fract @var{a}, long fract @var{b})
-@deftypefnx {Runtime Function} {long long fract} __ssdivdq3 (long long fract @var{a}, long long fract @var{b})
-@deftypefnx {Runtime Function} {short accum} __ssdivha3 (short accum @var{a}, short accum @var{b})
-@deftypefnx {Runtime Function} {accum} __ssdivsa3 (accum @var{a}, accum @var{b})
-@deftypefnx {Runtime Function} {long accum} __ssdivda3 (long accum @var{a}, long accum @var{b})
-@deftypefnx {Runtime Function} {long long accum} __ssdivta3 (long long accum @var{a}, long long accum @var{b})
-These functions return the quotient of the signed division of @var{a}
-and @var{b} with signed saturation.
-@end deftypefn
-
-@deftypefn {Runtime Function} {unsigned short fract} __usdivuqq3 (unsigned short fract @var{a}, unsigned short fract @var{b})
-@deftypefnx {Runtime Function} {unsigned fract} __usdivuhq3 (unsigned fract @var{a}, unsigned fract @var{b})
-@deftypefnx {Runtime Function} {unsigned long fract} __usdivusq3 (unsigned long fract @var{a}, unsigned long fract @var{b})
-@deftypefnx {Runtime Function} {unsigned long long fract} __usdivudq3 (unsigned long long fract @var{a}, unsigned long long fract @var{b})
-@deftypefnx {Runtime Function} {unsigned short accum} __usdivuha3 (unsigned short accum @var{a}, unsigned short accum @var{b})
-@deftypefnx {Runtime Function} {unsigned accum} __usdivusa3 (unsigned accum @var{a}, unsigned accum @var{b})
-@deftypefnx {Runtime Function} {unsigned long accum} __usdivuda3 (unsigned long accum @var{a}, unsigned long accum @var{b})
-@deftypefnx {Runtime Function} {unsigned long long accum} __usdivuta3 (unsigned long long accum @var{a}, unsigned long long accum @var{b})
-These functions return the quotient of the unsigned division of @var{a}
-and @var{b} with unsigned saturation.
-@end deftypefn
-
-@deftypefn {Runtime Function} {short fract} __negqq2 (short fract @var{a})
-@deftypefnx {Runtime Function} {fract} __neghq2 (fract @var{a})
-@deftypefnx {Runtime Function} {long fract} __negsq2 (long fract @var{a})
-@deftypefnx {Runtime Function} {long long fract} __negdq2 (long long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned short fract} __neguqq2 (unsigned short fract @var{a})
-@deftypefnx {Runtime Function} {unsigned fract} __neguhq2 (unsigned fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long fract} __negusq2 (unsigned long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long long fract} __negudq2 (unsigned long long fract @var{a})
-@deftypefnx {Runtime Function} {short accum} __negha2 (short accum @var{a})
-@deftypefnx {Runtime Function} {accum} __negsa2 (accum @var{a})
-@deftypefnx {Runtime Function} {long accum} __negda2 (long accum @var{a})
-@deftypefnx {Runtime Function} {long long accum} __negta2 (long long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned short accum} __neguha2 (unsigned short accum @var{a})
-@deftypefnx {Runtime Function} {unsigned accum} __negusa2 (unsigned accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long accum} __neguda2 (unsigned long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long long accum} __neguta2 (unsigned long long accum @var{a})
-These functions return the negation of @var{a}.
-@end deftypefn
-
-@deftypefn {Runtime Function} {short fract} __ssnegqq2 (short fract @var{a})
-@deftypefnx {Runtime Function} {fract} __ssneghq2 (fract @var{a})
-@deftypefnx {Runtime Function} {long fract} __ssnegsq2 (long fract @var{a})
-@deftypefnx {Runtime Function} {long long fract} __ssnegdq2 (long long fract @var{a})
-@deftypefnx {Runtime Function} {short accum} __ssnegha2 (short accum @var{a})
-@deftypefnx {Runtime Function} {accum} __ssnegsa2 (accum @var{a})
-@deftypefnx {Runtime Function} {long accum} __ssnegda2 (long accum @var{a})
-@deftypefnx {Runtime Function} {long long accum} __ssnegta2 (long long accum @var{a})
-These functions return the negation of @var{a} with signed saturation.
-@end deftypefn
-
-@deftypefn {Runtime Function} {unsigned short fract} __usneguqq2 (unsigned short fract @var{a})
-@deftypefnx {Runtime Function} {unsigned fract} __usneguhq2 (unsigned fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long fract} __usnegusq2 (unsigned long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long long fract} __usnegudq2 (unsigned long long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned short accum} __usneguha2 (unsigned short accum @var{a})
-@deftypefnx {Runtime Function} {unsigned accum} __usnegusa2 (unsigned accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long accum} __usneguda2 (unsigned long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long long accum} __usneguta2 (unsigned long long accum @var{a})
-These functions return the negation of @var{a} with unsigned saturation.
-@end deftypefn
-
-@deftypefn {Runtime Function} {short fract} __ashlqq3 (short fract @var{a}, int @var{b})
-@deftypefnx {Runtime Function} {fract} __ashlhq3 (fract @var{a}, int @var{b})
-@deftypefnx {Runtime Function} {long fract} __ashlsq3 (long fract @var{a}, int @var{b})
-@deftypefnx {Runtime Function} {long long fract} __ashldq3 (long long fract @var{a}, int @var{b})
-@deftypefnx {Runtime Function} {unsigned short fract} __ashluqq3 (unsigned short fract @var{a}, int @var{b})
-@deftypefnx {Runtime Function} {unsigned fract} __ashluhq3 (unsigned fract @var{a}, int @var{b})
-@deftypefnx {Runtime Function} {unsigned long fract} __ashlusq3 (unsigned long fract @var{a}, int @var{b})
-@deftypefnx {Runtime Function} {unsigned long long fract} __ashludq3 (unsigned long long fract @var{a}, int @var{b})
-@deftypefnx {Runtime Function} {short accum} __ashlha3 (short accum @var{a}, int @var{b})
-@deftypefnx {Runtime Function} {accum} __ashlsa3 (accum @var{a}, int @var{b})
-@deftypefnx {Runtime Function} {long accum} __ashlda3 (long accum @var{a}, int @var{b})
-@deftypefnx {Runtime Function} {long long accum} __ashlta3 (long long accum @var{a}, int @var{b})
-@deftypefnx {Runtime Function} {unsigned short accum} __ashluha3 (unsigned short accum @var{a}, int @var{b})
-@deftypefnx {Runtime Function} {unsigned accum} __ashlusa3 (unsigned accum @var{a}, int @var{b})
-@deftypefnx {Runtime Function} {unsigned long accum} __ashluda3 (unsigned long accum @var{a}, int @var{b})
-@deftypefnx {Runtime Function} {unsigned long long accum} __ashluta3 (unsigned long long accum @var{a}, int @var{b})
-These functions return the result of shifting @var{a} left by @var{b} bits.
-@end deftypefn
-
-@deftypefn {Runtime Function} {short fract} __ashrqq3 (short fract @var{a}, int @var{b})
-@deftypefnx {Runtime Function} {fract} __ashrhq3 (fract @var{a}, int @var{b})
-@deftypefnx {Runtime Function} {long fract} __ashrsq3 (long fract @var{a}, int @var{b})
-@deftypefnx {Runtime Function} {long long fract} __ashrdq3 (long long fract @var{a}, int @var{b})
-@deftypefnx {Runtime Function} {short accum} __ashrha3 (short accum @var{a}, int @var{b})
-@deftypefnx {Runtime Function} {accum} __ashrsa3 (accum @var{a}, int @var{b})
-@deftypefnx {Runtime Function} {long accum} __ashrda3 (long accum @var{a}, int @var{b})
-@deftypefnx {Runtime Function} {long long accum} __ashrta3 (long long accum @var{a}, int @var{b})
-These functions return the result of arithmetically shifting @var{a} right
-by @var{b} bits.
-@end deftypefn
-
-@deftypefn {Runtime Function} {unsigned short fract} __lshruqq3 (unsigned short fract @var{a}, int @var{b})
-@deftypefnx {Runtime Function} {unsigned fract} __lshruhq3 (unsigned fract @var{a}, int @var{b})
-@deftypefnx {Runtime Function} {unsigned long fract} __lshrusq3 (unsigned long fract @var{a}, int @var{b})
-@deftypefnx {Runtime Function} {unsigned long long fract} __lshrudq3 (unsigned long long fract @var{a}, int @var{b})
-@deftypefnx {Runtime Function} {unsigned short accum} __lshruha3 (unsigned short accum @var{a}, int @var{b})
-@deftypefnx {Runtime Function} {unsigned accum} __lshrusa3 (unsigned accum @var{a}, int @var{b})
-@deftypefnx {Runtime Function} {unsigned long accum} __lshruda3 (unsigned long accum @var{a}, int @var{b})
-@deftypefnx {Runtime Function} {unsigned long long accum} __lshruta3 (unsigned long long accum @var{a}, int @var{b})
-These functions return the result of logically shifting @var{a} right
-by @var{b} bits.
-@end deftypefn
-
-@deftypefn {Runtime Function} {fract} __ssashlhq3 (fract @var{a}, int @var{b})
-@deftypefnx {Runtime Function} {long fract} __ssashlsq3 (long fract @var{a}, int @var{b})
-@deftypefnx {Runtime Function} {long long fract} __ssashldq3 (long long fract @var{a}, int @var{b})
-@deftypefnx {Runtime Function} {short accum} __ssashlha3 (short accum @var{a}, int @var{b})
-@deftypefnx {Runtime Function} {accum} __ssashlsa3 (accum @var{a}, int @var{b})
-@deftypefnx {Runtime Function} {long accum} __ssashlda3 (long accum @var{a}, int @var{b})
-@deftypefnx {Runtime Function} {long long accum} __ssashlta3 (long long accum @var{a}, int @var{b})
-These functions return the result of shifting @var{a} left by @var{b} bits
-with signed saturation.
-@end deftypefn
-
-@deftypefn {Runtime Function} {unsigned short fract} __usashluqq3 (unsigned short fract @var{a}, int @var{b})
-@deftypefnx {Runtime Function} {unsigned fract} __usashluhq3 (unsigned fract @var{a}, int @var{b})
-@deftypefnx {Runtime Function} {unsigned long fract} __usashlusq3 (unsigned long fract @var{a}, int @var{b})
-@deftypefnx {Runtime Function} {unsigned long long fract} __usashludq3 (unsigned long long fract @var{a}, int @var{b})
-@deftypefnx {Runtime Function} {unsigned short accum} __usashluha3 (unsigned short accum @var{a}, int @var{b})
-@deftypefnx {Runtime Function} {unsigned accum} __usashlusa3 (unsigned accum @var{a}, int @var{b})
-@deftypefnx {Runtime Function} {unsigned long accum} __usashluda3 (unsigned long accum @var{a}, int @var{b})
-@deftypefnx {Runtime Function} {unsigned long long accum} __usashluta3 (unsigned long long accum @var{a}, int @var{b})
-These functions return the result of shifting @var{a} left by @var{b} bits
-with unsigned saturation.
-@end deftypefn
-
-@subsection Comparison functions
-
-The following functions implement fixed-point comparisons. These functions
-implement a low-level compare, upon which the higher level comparison
-operators (such as less than and greater than or equal to) can be
-constructed. The returned values lie in the range zero to two, to allow
-the high-level operators to be implemented by testing the returned
-result using either signed or unsigned comparison.
-
-@deftypefn {Runtime Function} {int} __cmpqq2 (short fract @var{a}, short fract @var{b})
-@deftypefnx {Runtime Function} {int} __cmphq2 (fract @var{a}, fract @var{b})
-@deftypefnx {Runtime Function} {int} __cmpsq2 (long fract @var{a}, long fract @var{b})
-@deftypefnx {Runtime Function} {int} __cmpdq2 (long long fract @var{a}, long long fract @var{b})
-@deftypefnx {Runtime Function} {int} __cmpuqq2 (unsigned short fract @var{a}, unsigned short fract @var{b})
-@deftypefnx {Runtime Function} {int} __cmpuhq2 (unsigned fract @var{a}, unsigned fract @var{b})
-@deftypefnx {Runtime Function} {int} __cmpusq2 (unsigned long fract @var{a}, unsigned long fract @var{b})
-@deftypefnx {Runtime Function} {int} __cmpudq2 (unsigned long long fract @var{a}, unsigned long long fract @var{b})
-@deftypefnx {Runtime Function} {int} __cmpha2 (short accum @var{a}, short accum @var{b})
-@deftypefnx {Runtime Function} {int} __cmpsa2 (accum @var{a}, accum @var{b})
-@deftypefnx {Runtime Function} {int} __cmpda2 (long accum @var{a}, long accum @var{b})
-@deftypefnx {Runtime Function} {int} __cmpta2 (long long accum @var{a}, long long accum @var{b})
-@deftypefnx {Runtime Function} {int} __cmpuha2 (unsigned short accum @var{a}, unsigned short accum @var{b})
-@deftypefnx {Runtime Function} {int} __cmpusa2 (unsigned accum @var{a}, unsigned accum @var{b})
-@deftypefnx {Runtime Function} {int} __cmpuda2 (unsigned long accum @var{a}, unsigned long accum @var{b})
-@deftypefnx {Runtime Function} {int} __cmputa2 (unsigned long long accum @var{a}, unsigned long long accum @var{b})
-These functions perform a signed or unsigned comparison of @var{a} and
-@var{b} (depending on the selected machine mode). If @var{a} is less
-than @var{b}, they return 0; if @var{a} is greater than @var{b}, they
-return 2; and if @var{a} and @var{b} are equal they return 1.
-@end deftypefn
-
-@subsection Conversion functions
-
-@deftypefn {Runtime Function} {fract} __fractqqhq2 (short fract @var{a})
-@deftypefnx {Runtime Function} {long fract} __fractqqsq2 (short fract @var{a})
-@deftypefnx {Runtime Function} {long long fract} __fractqqdq2 (short fract @var{a})
-@deftypefnx {Runtime Function} {short accum} __fractqqha (short fract @var{a})
-@deftypefnx {Runtime Function} {accum} __fractqqsa (short fract @var{a})
-@deftypefnx {Runtime Function} {long accum} __fractqqda (short fract @var{a})
-@deftypefnx {Runtime Function} {long long accum} __fractqqta (short fract @var{a})
-@deftypefnx {Runtime Function} {unsigned short fract} __fractqquqq (short fract @var{a})
-@deftypefnx {Runtime Function} {unsigned fract} __fractqquhq (short fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long fract} __fractqqusq (short fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long long fract} __fractqqudq (short fract @var{a})
-@deftypefnx {Runtime Function} {unsigned short accum} __fractqquha (short fract @var{a})
-@deftypefnx {Runtime Function} {unsigned accum} __fractqqusa (short fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long accum} __fractqquda (short fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long long accum} __fractqquta (short fract @var{a})
-@deftypefnx {Runtime Function} {signed char} __fractqqqi (short fract @var{a})
-@deftypefnx {Runtime Function} {short} __fractqqhi (short fract @var{a})
-@deftypefnx {Runtime Function} {int} __fractqqsi (short fract @var{a})
-@deftypefnx {Runtime Function} {long} __fractqqdi (short fract @var{a})
-@deftypefnx {Runtime Function} {long long} __fractqqti (short fract @var{a})
-@deftypefnx {Runtime Function} {float} __fractqqsf (short fract @var{a})
-@deftypefnx {Runtime Function} {double} __fractqqdf (short fract @var{a})
-@deftypefnx {Runtime Function} {short fract} __fracthqqq2 (fract @var{a})
-@deftypefnx {Runtime Function} {long fract} __fracthqsq2 (fract @var{a})
-@deftypefnx {Runtime Function} {long long fract} __fracthqdq2 (fract @var{a})
-@deftypefnx {Runtime Function} {short accum} __fracthqha (fract @var{a})
-@deftypefnx {Runtime Function} {accum} __fracthqsa (fract @var{a})
-@deftypefnx {Runtime Function} {long accum} __fracthqda (fract @var{a})
-@deftypefnx {Runtime Function} {long long accum} __fracthqta (fract @var{a})
-@deftypefnx {Runtime Function} {unsigned short fract} __fracthquqq (fract @var{a})
-@deftypefnx {Runtime Function} {unsigned fract} __fracthquhq (fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long fract} __fracthqusq (fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long long fract} __fracthqudq (fract @var{a})
-@deftypefnx {Runtime Function} {unsigned short accum} __fracthquha (fract @var{a})
-@deftypefnx {Runtime Function} {unsigned accum} __fracthqusa (fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long accum} __fracthquda (fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long long accum} __fracthquta (fract @var{a})
-@deftypefnx {Runtime Function} {signed char} __fracthqqi (fract @var{a})
-@deftypefnx {Runtime Function} {short} __fracthqhi (fract @var{a})
-@deftypefnx {Runtime Function} {int} __fracthqsi (fract @var{a})
-@deftypefnx {Runtime Function} {long} __fracthqdi (fract @var{a})
-@deftypefnx {Runtime Function} {long long} __fracthqti (fract @var{a})
-@deftypefnx {Runtime Function} {float} __fracthqsf (fract @var{a})
-@deftypefnx {Runtime Function} {double} __fracthqdf (fract @var{a})
-@deftypefnx {Runtime Function} {short fract} __fractsqqq2 (long fract @var{a})
-@deftypefnx {Runtime Function} {fract} __fractsqhq2 (long fract @var{a})
-@deftypefnx {Runtime Function} {long long fract} __fractsqdq2 (long fract @var{a})
-@deftypefnx {Runtime Function} {short accum} __fractsqha (long fract @var{a})
-@deftypefnx {Runtime Function} {accum} __fractsqsa (long fract @var{a})
-@deftypefnx {Runtime Function} {long accum} __fractsqda (long fract @var{a})
-@deftypefnx {Runtime Function} {long long accum} __fractsqta (long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned short fract} __fractsquqq (long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned fract} __fractsquhq (long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long fract} __fractsqusq (long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long long fract} __fractsqudq (long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned short accum} __fractsquha (long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned accum} __fractsqusa (long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long accum} __fractsquda (long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long long accum} __fractsquta (long fract @var{a})
-@deftypefnx {Runtime Function} {signed char} __fractsqqi (long fract @var{a})
-@deftypefnx {Runtime Function} {short} __fractsqhi (long fract @var{a})
-@deftypefnx {Runtime Function} {int} __fractsqsi (long fract @var{a})
-@deftypefnx {Runtime Function} {long} __fractsqdi (long fract @var{a})
-@deftypefnx {Runtime Function} {long long} __fractsqti (long fract @var{a})
-@deftypefnx {Runtime Function} {float} __fractsqsf (long fract @var{a})
-@deftypefnx {Runtime Function} {double} __fractsqdf (long fract @var{a})
-@deftypefnx {Runtime Function} {short fract} __fractdqqq2 (long long fract @var{a})
-@deftypefnx {Runtime Function} {fract} __fractdqhq2 (long long fract @var{a})
-@deftypefnx {Runtime Function} {long fract} __fractdqsq2 (long long fract @var{a})
-@deftypefnx {Runtime Function} {short accum} __fractdqha (long long fract @var{a})
-@deftypefnx {Runtime Function} {accum} __fractdqsa (long long fract @var{a})
-@deftypefnx {Runtime Function} {long accum} __fractdqda (long long fract @var{a})
-@deftypefnx {Runtime Function} {long long accum} __fractdqta (long long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned short fract} __fractdquqq (long long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned fract} __fractdquhq (long long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long fract} __fractdqusq (long long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long long fract} __fractdqudq (long long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned short accum} __fractdquha (long long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned accum} __fractdqusa (long long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long accum} __fractdquda (long long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long long accum} __fractdquta (long long fract @var{a})
-@deftypefnx {Runtime Function} {signed char} __fractdqqi (long long fract @var{a})
-@deftypefnx {Runtime Function} {short} __fractdqhi (long long fract @var{a})
-@deftypefnx {Runtime Function} {int} __fractdqsi (long long fract @var{a})
-@deftypefnx {Runtime Function} {long} __fractdqdi (long long fract @var{a})
-@deftypefnx {Runtime Function} {long long} __fractdqti (long long fract @var{a})
-@deftypefnx {Runtime Function} {float} __fractdqsf (long long fract @var{a})
-@deftypefnx {Runtime Function} {double} __fractdqdf (long long fract @var{a})
-@deftypefnx {Runtime Function} {short fract} __fracthaqq (short accum @var{a})
-@deftypefnx {Runtime Function} {fract} __fracthahq (short accum @var{a})
-@deftypefnx {Runtime Function} {long fract} __fracthasq (short accum @var{a})
-@deftypefnx {Runtime Function} {long long fract} __fracthadq (short accum @var{a})
-@deftypefnx {Runtime Function} {accum} __fracthasa2 (short accum @var{a})
-@deftypefnx {Runtime Function} {long accum} __fracthada2 (short accum @var{a})
-@deftypefnx {Runtime Function} {long long accum} __fracthata2 (short accum @var{a})
-@deftypefnx {Runtime Function} {unsigned short fract} __fracthauqq (short accum @var{a})
-@deftypefnx {Runtime Function} {unsigned fract} __fracthauhq (short accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long fract} __fracthausq (short accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long long fract} __fracthaudq (short accum @var{a})
-@deftypefnx {Runtime Function} {unsigned short accum} __fracthauha (short accum @var{a})
-@deftypefnx {Runtime Function} {unsigned accum} __fracthausa (short accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long accum} __fracthauda (short accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long long accum} __fracthauta (short accum @var{a})
-@deftypefnx {Runtime Function} {signed char} __fracthaqi (short accum @var{a})
-@deftypefnx {Runtime Function} {short} __fracthahi (short accum @var{a})
-@deftypefnx {Runtime Function} {int} __fracthasi (short accum @var{a})
-@deftypefnx {Runtime Function} {long} __fracthadi (short accum @var{a})
-@deftypefnx {Runtime Function} {long long} __fracthati (short accum @var{a})
-@deftypefnx {Runtime Function} {float} __fracthasf (short accum @var{a})
-@deftypefnx {Runtime Function} {double} __fracthadf (short accum @var{a})
-@deftypefnx {Runtime Function} {short fract} __fractsaqq (accum @var{a})
-@deftypefnx {Runtime Function} {fract} __fractsahq (accum @var{a})
-@deftypefnx {Runtime Function} {long fract} __fractsasq (accum @var{a})
-@deftypefnx {Runtime Function} {long long fract} __fractsadq (accum @var{a})
-@deftypefnx {Runtime Function} {short accum} __fractsaha2 (accum @var{a})
-@deftypefnx {Runtime Function} {long accum} __fractsada2 (accum @var{a})
-@deftypefnx {Runtime Function} {long long accum} __fractsata2 (accum @var{a})
-@deftypefnx {Runtime Function} {unsigned short fract} __fractsauqq (accum @var{a})
-@deftypefnx {Runtime Function} {unsigned fract} __fractsauhq (accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long fract} __fractsausq (accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long long fract} __fractsaudq (accum @var{a})
-@deftypefnx {Runtime Function} {unsigned short accum} __fractsauha (accum @var{a})
-@deftypefnx {Runtime Function} {unsigned accum} __fractsausa (accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long accum} __fractsauda (accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long long accum} __fractsauta (accum @var{a})
-@deftypefnx {Runtime Function} {signed char} __fractsaqi (accum @var{a})
-@deftypefnx {Runtime Function} {short} __fractsahi (accum @var{a})
-@deftypefnx {Runtime Function} {int} __fractsasi (accum @var{a})
-@deftypefnx {Runtime Function} {long} __fractsadi (accum @var{a})
-@deftypefnx {Runtime Function} {long long} __fractsati (accum @var{a})
-@deftypefnx {Runtime Function} {float} __fractsasf (accum @var{a})
-@deftypefnx {Runtime Function} {double} __fractsadf (accum @var{a})
-@deftypefnx {Runtime Function} {short fract} __fractdaqq (long accum @var{a})
-@deftypefnx {Runtime Function} {fract} __fractdahq (long accum @var{a})
-@deftypefnx {Runtime Function} {long fract} __fractdasq (long accum @var{a})
-@deftypefnx {Runtime Function} {long long fract} __fractdadq (long accum @var{a})
-@deftypefnx {Runtime Function} {short accum} __fractdaha2 (long accum @var{a})
-@deftypefnx {Runtime Function} {accum} __fractdasa2 (long accum @var{a})
-@deftypefnx {Runtime Function} {long long accum} __fractdata2 (long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned short fract} __fractdauqq (long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned fract} __fractdauhq (long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long fract} __fractdausq (long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long long fract} __fractdaudq (long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned short accum} __fractdauha (long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned accum} __fractdausa (long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long accum} __fractdauda (long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long long accum} __fractdauta (long accum @var{a})
-@deftypefnx {Runtime Function} {signed char} __fractdaqi (long accum @var{a})
-@deftypefnx {Runtime Function} {short} __fractdahi (long accum @var{a})
-@deftypefnx {Runtime Function} {int} __fractdasi (long accum @var{a})
-@deftypefnx {Runtime Function} {long} __fractdadi (long accum @var{a})
-@deftypefnx {Runtime Function} {long long} __fractdati (long accum @var{a})
-@deftypefnx {Runtime Function} {float} __fractdasf (long accum @var{a})
-@deftypefnx {Runtime Function} {double} __fractdadf (long accum @var{a})
-@deftypefnx {Runtime Function} {short fract} __fracttaqq (long long accum @var{a})
-@deftypefnx {Runtime Function} {fract} __fracttahq (long long accum @var{a})
-@deftypefnx {Runtime Function} {long fract} __fracttasq (long long accum @var{a})
-@deftypefnx {Runtime Function} {long long fract} __fracttadq (long long accum @var{a})
-@deftypefnx {Runtime Function} {short accum} __fracttaha2 (long long accum @var{a})
-@deftypefnx {Runtime Function} {accum} __fracttasa2 (long long accum @var{a})
-@deftypefnx {Runtime Function} {long accum} __fracttada2 (long long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned short fract} __fracttauqq (long long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned fract} __fracttauhq (long long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long fract} __fracttausq (long long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long long fract} __fracttaudq (long long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned short accum} __fracttauha (long long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned accum} __fracttausa (long long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long accum} __fracttauda (long long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long long accum} __fracttauta (long long accum @var{a})
-@deftypefnx {Runtime Function} {signed char} __fracttaqi (long long accum @var{a})
-@deftypefnx {Runtime Function} {short} __fracttahi (long long accum @var{a})
-@deftypefnx {Runtime Function} {int} __fracttasi (long long accum @var{a})
-@deftypefnx {Runtime Function} {long} __fracttadi (long long accum @var{a})
-@deftypefnx {Runtime Function} {long long} __fracttati (long long accum @var{a})
-@deftypefnx {Runtime Function} {float} __fracttasf (long long accum @var{a})
-@deftypefnx {Runtime Function} {double} __fracttadf (long long accum @var{a})
-@deftypefnx {Runtime Function} {short fract} __fractuqqqq (unsigned short fract @var{a})
-@deftypefnx {Runtime Function} {fract} __fractuqqhq (unsigned short fract @var{a})
-@deftypefnx {Runtime Function} {long fract} __fractuqqsq (unsigned short fract @var{a})
-@deftypefnx {Runtime Function} {long long fract} __fractuqqdq (unsigned short fract @var{a})
-@deftypefnx {Runtime Function} {short accum} __fractuqqha (unsigned short fract @var{a})
-@deftypefnx {Runtime Function} {accum} __fractuqqsa (unsigned short fract @var{a})
-@deftypefnx {Runtime Function} {long accum} __fractuqqda (unsigned short fract @var{a})
-@deftypefnx {Runtime Function} {long long accum} __fractuqqta (unsigned short fract @var{a})
-@deftypefnx {Runtime Function} {unsigned fract} __fractuqquhq2 (unsigned short fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long fract} __fractuqqusq2 (unsigned short fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long long fract} __fractuqqudq2 (unsigned short fract @var{a})
-@deftypefnx {Runtime Function} {unsigned short accum} __fractuqquha (unsigned short fract @var{a})
-@deftypefnx {Runtime Function} {unsigned accum} __fractuqqusa (unsigned short fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long accum} __fractuqquda (unsigned short fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long long accum} __fractuqquta (unsigned short fract @var{a})
-@deftypefnx {Runtime Function} {signed char} __fractuqqqi (unsigned short fract @var{a})
-@deftypefnx {Runtime Function} {short} __fractuqqhi (unsigned short fract @var{a})
-@deftypefnx {Runtime Function} {int} __fractuqqsi (unsigned short fract @var{a})
-@deftypefnx {Runtime Function} {long} __fractuqqdi (unsigned short fract @var{a})
-@deftypefnx {Runtime Function} {long long} __fractuqqti (unsigned short fract @var{a})
-@deftypefnx {Runtime Function} {float} __fractuqqsf (unsigned short fract @var{a})
-@deftypefnx {Runtime Function} {double} __fractuqqdf (unsigned short fract @var{a})
-@deftypefnx {Runtime Function} {short fract} __fractuhqqq (unsigned fract @var{a})
-@deftypefnx {Runtime Function} {fract} __fractuhqhq (unsigned fract @var{a})
-@deftypefnx {Runtime Function} {long fract} __fractuhqsq (unsigned fract @var{a})
-@deftypefnx {Runtime Function} {long long fract} __fractuhqdq (unsigned fract @var{a})
-@deftypefnx {Runtime Function} {short accum} __fractuhqha (unsigned fract @var{a})
-@deftypefnx {Runtime Function} {accum} __fractuhqsa (unsigned fract @var{a})
-@deftypefnx {Runtime Function} {long accum} __fractuhqda (unsigned fract @var{a})
-@deftypefnx {Runtime Function} {long long accum} __fractuhqta (unsigned fract @var{a})
-@deftypefnx {Runtime Function} {unsigned short fract} __fractuhquqq2 (unsigned fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long fract} __fractuhqusq2 (unsigned fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long long fract} __fractuhqudq2 (unsigned fract @var{a})
-@deftypefnx {Runtime Function} {unsigned short accum} __fractuhquha (unsigned fract @var{a})
-@deftypefnx {Runtime Function} {unsigned accum} __fractuhqusa (unsigned fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long accum} __fractuhquda (unsigned fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long long accum} __fractuhquta (unsigned fract @var{a})
-@deftypefnx {Runtime Function} {signed char} __fractuhqqi (unsigned fract @var{a})
-@deftypefnx {Runtime Function} {short} __fractuhqhi (unsigned fract @var{a})
-@deftypefnx {Runtime Function} {int} __fractuhqsi (unsigned fract @var{a})
-@deftypefnx {Runtime Function} {long} __fractuhqdi (unsigned fract @var{a})
-@deftypefnx {Runtime Function} {long long} __fractuhqti (unsigned fract @var{a})
-@deftypefnx {Runtime Function} {float} __fractuhqsf (unsigned fract @var{a})
-@deftypefnx {Runtime Function} {double} __fractuhqdf (unsigned fract @var{a})
-@deftypefnx {Runtime Function} {short fract} __fractusqqq (unsigned long fract @var{a})
-@deftypefnx {Runtime Function} {fract} __fractusqhq (unsigned long fract @var{a})
-@deftypefnx {Runtime Function} {long fract} __fractusqsq (unsigned long fract @var{a})
-@deftypefnx {Runtime Function} {long long fract} __fractusqdq (unsigned long fract @var{a})
-@deftypefnx {Runtime Function} {short accum} __fractusqha (unsigned long fract @var{a})
-@deftypefnx {Runtime Function} {accum} __fractusqsa (unsigned long fract @var{a})
-@deftypefnx {Runtime Function} {long accum} __fractusqda (unsigned long fract @var{a})
-@deftypefnx {Runtime Function} {long long accum} __fractusqta (unsigned long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned short fract} __fractusquqq2 (unsigned long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned fract} __fractusquhq2 (unsigned long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long long fract} __fractusqudq2 (unsigned long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned short accum} __fractusquha (unsigned long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned accum} __fractusqusa (unsigned long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long accum} __fractusquda (unsigned long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long long accum} __fractusquta (unsigned long fract @var{a})
-@deftypefnx {Runtime Function} {signed char} __fractusqqi (unsigned long fract @var{a})
-@deftypefnx {Runtime Function} {short} __fractusqhi (unsigned long fract @var{a})
-@deftypefnx {Runtime Function} {int} __fractusqsi (unsigned long fract @var{a})
-@deftypefnx {Runtime Function} {long} __fractusqdi (unsigned long fract @var{a})
-@deftypefnx {Runtime Function} {long long} __fractusqti (unsigned long fract @var{a})
-@deftypefnx {Runtime Function} {float} __fractusqsf (unsigned long fract @var{a})
-@deftypefnx {Runtime Function} {double} __fractusqdf (unsigned long fract @var{a})
-@deftypefnx {Runtime Function} {short fract} __fractudqqq (unsigned long long fract @var{a})
-@deftypefnx {Runtime Function} {fract} __fractudqhq (unsigned long long fract @var{a})
-@deftypefnx {Runtime Function} {long fract} __fractudqsq (unsigned long long fract @var{a})
-@deftypefnx {Runtime Function} {long long fract} __fractudqdq (unsigned long long fract @var{a})
-@deftypefnx {Runtime Function} {short accum} __fractudqha (unsigned long long fract @var{a})
-@deftypefnx {Runtime Function} {accum} __fractudqsa (unsigned long long fract @var{a})
-@deftypefnx {Runtime Function} {long accum} __fractudqda (unsigned long long fract @var{a})
-@deftypefnx {Runtime Function} {long long accum} __fractudqta (unsigned long long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned short fract} __fractudquqq2 (unsigned long long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned fract} __fractudquhq2 (unsigned long long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long fract} __fractudqusq2 (unsigned long long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned short accum} __fractudquha (unsigned long long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned accum} __fractudqusa (unsigned long long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long accum} __fractudquda (unsigned long long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long long accum} __fractudquta (unsigned long long fract @var{a})
-@deftypefnx {Runtime Function} {signed char} __fractudqqi (unsigned long long fract @var{a})
-@deftypefnx {Runtime Function} {short} __fractudqhi (unsigned long long fract @var{a})
-@deftypefnx {Runtime Function} {int} __fractudqsi (unsigned long long fract @var{a})
-@deftypefnx {Runtime Function} {long} __fractudqdi (unsigned long long fract @var{a})
-@deftypefnx {Runtime Function} {long long} __fractudqti (unsigned long long fract @var{a})
-@deftypefnx {Runtime Function} {float} __fractudqsf (unsigned long long fract @var{a})
-@deftypefnx {Runtime Function} {double} __fractudqdf (unsigned long long fract @var{a})
-@deftypefnx {Runtime Function} {short fract} __fractuhaqq (unsigned short accum @var{a})
-@deftypefnx {Runtime Function} {fract} __fractuhahq (unsigned short accum @var{a})
-@deftypefnx {Runtime Function} {long fract} __fractuhasq (unsigned short accum @var{a})
-@deftypefnx {Runtime Function} {long long fract} __fractuhadq (unsigned short accum @var{a})
-@deftypefnx {Runtime Function} {short accum} __fractuhaha (unsigned short accum @var{a})
-@deftypefnx {Runtime Function} {accum} __fractuhasa (unsigned short accum @var{a})
-@deftypefnx {Runtime Function} {long accum} __fractuhada (unsigned short accum @var{a})
-@deftypefnx {Runtime Function} {long long accum} __fractuhata (unsigned short accum @var{a})
-@deftypefnx {Runtime Function} {unsigned short fract} __fractuhauqq (unsigned short accum @var{a})
-@deftypefnx {Runtime Function} {unsigned fract} __fractuhauhq (unsigned short accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long fract} __fractuhausq (unsigned short accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long long fract} __fractuhaudq (unsigned short accum @var{a})
-@deftypefnx {Runtime Function} {unsigned accum} __fractuhausa2 (unsigned short accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long accum} __fractuhauda2 (unsigned short accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long long accum} __fractuhauta2 (unsigned short accum @var{a})
-@deftypefnx {Runtime Function} {signed char} __fractuhaqi (unsigned short accum @var{a})
-@deftypefnx {Runtime Function} {short} __fractuhahi (unsigned short accum @var{a})
-@deftypefnx {Runtime Function} {int} __fractuhasi (unsigned short accum @var{a})
-@deftypefnx {Runtime Function} {long} __fractuhadi (unsigned short accum @var{a})
-@deftypefnx {Runtime Function} {long long} __fractuhati (unsigned short accum @var{a})
-@deftypefnx {Runtime Function} {float} __fractuhasf (unsigned short accum @var{a})
-@deftypefnx {Runtime Function} {double} __fractuhadf (unsigned short accum @var{a})
-@deftypefnx {Runtime Function} {short fract} __fractusaqq (unsigned accum @var{a})
-@deftypefnx {Runtime Function} {fract} __fractusahq (unsigned accum @var{a})
-@deftypefnx {Runtime Function} {long fract} __fractusasq (unsigned accum @var{a})
-@deftypefnx {Runtime Function} {long long fract} __fractusadq (unsigned accum @var{a})
-@deftypefnx {Runtime Function} {short accum} __fractusaha (unsigned accum @var{a})
-@deftypefnx {Runtime Function} {accum} __fractusasa (unsigned accum @var{a})
-@deftypefnx {Runtime Function} {long accum} __fractusada (unsigned accum @var{a})
-@deftypefnx {Runtime Function} {long long accum} __fractusata (unsigned accum @var{a})
-@deftypefnx {Runtime Function} {unsigned short fract} __fractusauqq (unsigned accum @var{a})
-@deftypefnx {Runtime Function} {unsigned fract} __fractusauhq (unsigned accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long fract} __fractusausq (unsigned accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long long fract} __fractusaudq (unsigned accum @var{a})
-@deftypefnx {Runtime Function} {unsigned short accum} __fractusauha2 (unsigned accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long accum} __fractusauda2 (unsigned accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long long accum} __fractusauta2 (unsigned accum @var{a})
-@deftypefnx {Runtime Function} {signed char} __fractusaqi (unsigned accum @var{a})
-@deftypefnx {Runtime Function} {short} __fractusahi (unsigned accum @var{a})
-@deftypefnx {Runtime Function} {int} __fractusasi (unsigned accum @var{a})
-@deftypefnx {Runtime Function} {long} __fractusadi (unsigned accum @var{a})
-@deftypefnx {Runtime Function} {long long} __fractusati (unsigned accum @var{a})
-@deftypefnx {Runtime Function} {float} __fractusasf (unsigned accum @var{a})
-@deftypefnx {Runtime Function} {double} __fractusadf (unsigned accum @var{a})
-@deftypefnx {Runtime Function} {short fract} __fractudaqq (unsigned long accum @var{a})
-@deftypefnx {Runtime Function} {fract} __fractudahq (unsigned long accum @var{a})
-@deftypefnx {Runtime Function} {long fract} __fractudasq (unsigned long accum @var{a})
-@deftypefnx {Runtime Function} {long long fract} __fractudadq (unsigned long accum @var{a})
-@deftypefnx {Runtime Function} {short accum} __fractudaha (unsigned long accum @var{a})
-@deftypefnx {Runtime Function} {accum} __fractudasa (unsigned long accum @var{a})
-@deftypefnx {Runtime Function} {long accum} __fractudada (unsigned long accum @var{a})
-@deftypefnx {Runtime Function} {long long accum} __fractudata (unsigned long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned short fract} __fractudauqq (unsigned long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned fract} __fractudauhq (unsigned long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long fract} __fractudausq (unsigned long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long long fract} __fractudaudq (unsigned long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned short accum} __fractudauha2 (unsigned long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned accum} __fractudausa2 (unsigned long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long long accum} __fractudauta2 (unsigned long accum @var{a})
-@deftypefnx {Runtime Function} {signed char} __fractudaqi (unsigned long accum @var{a})
-@deftypefnx {Runtime Function} {short} __fractudahi (unsigned long accum @var{a})
-@deftypefnx {Runtime Function} {int} __fractudasi (unsigned long accum @var{a})
-@deftypefnx {Runtime Function} {long} __fractudadi (unsigned long accum @var{a})
-@deftypefnx {Runtime Function} {long long} __fractudati (unsigned long accum @var{a})
-@deftypefnx {Runtime Function} {float} __fractudasf (unsigned long accum @var{a})
-@deftypefnx {Runtime Function} {double} __fractudadf (unsigned long accum @var{a})
-@deftypefnx {Runtime Function} {short fract} __fractutaqq (unsigned long long accum @var{a})
-@deftypefnx {Runtime Function} {fract} __fractutahq (unsigned long long accum @var{a})
-@deftypefnx {Runtime Function} {long fract} __fractutasq (unsigned long long accum @var{a})
-@deftypefnx {Runtime Function} {long long fract} __fractutadq (unsigned long long accum @var{a})
-@deftypefnx {Runtime Function} {short accum} __fractutaha (unsigned long long accum @var{a})
-@deftypefnx {Runtime Function} {accum} __fractutasa (unsigned long long accum @var{a})
-@deftypefnx {Runtime Function} {long accum} __fractutada (unsigned long long accum @var{a})
-@deftypefnx {Runtime Function} {long long accum} __fractutata (unsigned long long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned short fract} __fractutauqq (unsigned long long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned fract} __fractutauhq (unsigned long long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long fract} __fractutausq (unsigned long long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long long fract} __fractutaudq (unsigned long long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned short accum} __fractutauha2 (unsigned long long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned accum} __fractutausa2 (unsigned long long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long accum} __fractutauda2 (unsigned long long accum @var{a})
-@deftypefnx {Runtime Function} {signed char} __fractutaqi (unsigned long long accum @var{a})
-@deftypefnx {Runtime Function} {short} __fractutahi (unsigned long long accum @var{a})
-@deftypefnx {Runtime Function} {int} __fractutasi (unsigned long long accum @var{a})
-@deftypefnx {Runtime Function} {long} __fractutadi (unsigned long long accum @var{a})
-@deftypefnx {Runtime Function} {long long} __fractutati (unsigned long long accum @var{a})
-@deftypefnx {Runtime Function} {float} __fractutasf (unsigned long long accum @var{a})
-@deftypefnx {Runtime Function} {double} __fractutadf (unsigned long long accum @var{a})
-@deftypefnx {Runtime Function} {short fract} __fractqiqq (signed char @var{a})
-@deftypefnx {Runtime Function} {fract} __fractqihq (signed char @var{a})
-@deftypefnx {Runtime Function} {long fract} __fractqisq (signed char @var{a})
-@deftypefnx {Runtime Function} {long long fract} __fractqidq (signed char @var{a})
-@deftypefnx {Runtime Function} {short accum} __fractqiha (signed char @var{a})
-@deftypefnx {Runtime Function} {accum} __fractqisa (signed char @var{a})
-@deftypefnx {Runtime Function} {long accum} __fractqida (signed char @var{a})
-@deftypefnx {Runtime Function} {long long accum} __fractqita (signed char @var{a})
-@deftypefnx {Runtime Function} {unsigned short fract} __fractqiuqq (signed char @var{a})
-@deftypefnx {Runtime Function} {unsigned fract} __fractqiuhq (signed char @var{a})
-@deftypefnx {Runtime Function} {unsigned long fract} __fractqiusq (signed char @var{a})
-@deftypefnx {Runtime Function} {unsigned long long fract} __fractqiudq (signed char @var{a})
-@deftypefnx {Runtime Function} {unsigned short accum} __fractqiuha (signed char @var{a})
-@deftypefnx {Runtime Function} {unsigned accum} __fractqiusa (signed char @var{a})
-@deftypefnx {Runtime Function} {unsigned long accum} __fractqiuda (signed char @var{a})
-@deftypefnx {Runtime Function} {unsigned long long accum} __fractqiuta (signed char @var{a})
-@deftypefnx {Runtime Function} {short fract} __fracthiqq (short @var{a})
-@deftypefnx {Runtime Function} {fract} __fracthihq (short @var{a})
-@deftypefnx {Runtime Function} {long fract} __fracthisq (short @var{a})
-@deftypefnx {Runtime Function} {long long fract} __fracthidq (short @var{a})
-@deftypefnx {Runtime Function} {short accum} __fracthiha (short @var{a})
-@deftypefnx {Runtime Function} {accum} __fracthisa (short @var{a})
-@deftypefnx {Runtime Function} {long accum} __fracthida (short @var{a})
-@deftypefnx {Runtime Function} {long long accum} __fracthita (short @var{a})
-@deftypefnx {Runtime Function} {unsigned short fract} __fracthiuqq (short @var{a})
-@deftypefnx {Runtime Function} {unsigned fract} __fracthiuhq (short @var{a})
-@deftypefnx {Runtime Function} {unsigned long fract} __fracthiusq (short @var{a})
-@deftypefnx {Runtime Function} {unsigned long long fract} __fracthiudq (short @var{a})
-@deftypefnx {Runtime Function} {unsigned short accum} __fracthiuha (short @var{a})
-@deftypefnx {Runtime Function} {unsigned accum} __fracthiusa (short @var{a})
-@deftypefnx {Runtime Function} {unsigned long accum} __fracthiuda (short @var{a})
-@deftypefnx {Runtime Function} {unsigned long long accum} __fracthiuta (short @var{a})
-@deftypefnx {Runtime Function} {short fract} __fractsiqq (int @var{a})
-@deftypefnx {Runtime Function} {fract} __fractsihq (int @var{a})
-@deftypefnx {Runtime Function} {long fract} __fractsisq (int @var{a})
-@deftypefnx {Runtime Function} {long long fract} __fractsidq (int @var{a})
-@deftypefnx {Runtime Function} {short accum} __fractsiha (int @var{a})
-@deftypefnx {Runtime Function} {accum} __fractsisa (int @var{a})
-@deftypefnx {Runtime Function} {long accum} __fractsida (int @var{a})
-@deftypefnx {Runtime Function} {long long accum} __fractsita (int @var{a})
-@deftypefnx {Runtime Function} {unsigned short fract} __fractsiuqq (int @var{a})
-@deftypefnx {Runtime Function} {unsigned fract} __fractsiuhq (int @var{a})
-@deftypefnx {Runtime Function} {unsigned long fract} __fractsiusq (int @var{a})
-@deftypefnx {Runtime Function} {unsigned long long fract} __fractsiudq (int @var{a})
-@deftypefnx {Runtime Function} {unsigned short accum} __fractsiuha (int @var{a})
-@deftypefnx {Runtime Function} {unsigned accum} __fractsiusa (int @var{a})
-@deftypefnx {Runtime Function} {unsigned long accum} __fractsiuda (int @var{a})
-@deftypefnx {Runtime Function} {unsigned long long accum} __fractsiuta (int @var{a})
-@deftypefnx {Runtime Function} {short fract} __fractdiqq (long @var{a})
-@deftypefnx {Runtime Function} {fract} __fractdihq (long @var{a})
-@deftypefnx {Runtime Function} {long fract} __fractdisq (long @var{a})
-@deftypefnx {Runtime Function} {long long fract} __fractdidq (long @var{a})
-@deftypefnx {Runtime Function} {short accum} __fractdiha (long @var{a})
-@deftypefnx {Runtime Function} {accum} __fractdisa (long @var{a})
-@deftypefnx {Runtime Function} {long accum} __fractdida (long @var{a})
-@deftypefnx {Runtime Function} {long long accum} __fractdita (long @var{a})
-@deftypefnx {Runtime Function} {unsigned short fract} __fractdiuqq (long @var{a})
-@deftypefnx {Runtime Function} {unsigned fract} __fractdiuhq (long @var{a})
-@deftypefnx {Runtime Function} {unsigned long fract} __fractdiusq (long @var{a})
-@deftypefnx {Runtime Function} {unsigned long long fract} __fractdiudq (long @var{a})
-@deftypefnx {Runtime Function} {unsigned short accum} __fractdiuha (long @var{a})
-@deftypefnx {Runtime Function} {unsigned accum} __fractdiusa (long @var{a})
-@deftypefnx {Runtime Function} {unsigned long accum} __fractdiuda (long @var{a})
-@deftypefnx {Runtime Function} {unsigned long long accum} __fractdiuta (long @var{a})
-@deftypefnx {Runtime Function} {short fract} __fracttiqq (long long @var{a})
-@deftypefnx {Runtime Function} {fract} __fracttihq (long long @var{a})
-@deftypefnx {Runtime Function} {long fract} __fracttisq (long long @var{a})
-@deftypefnx {Runtime Function} {long long fract} __fracttidq (long long @var{a})
-@deftypefnx {Runtime Function} {short accum} __fracttiha (long long @var{a})
-@deftypefnx {Runtime Function} {accum} __fracttisa (long long @var{a})
-@deftypefnx {Runtime Function} {long accum} __fracttida (long long @var{a})
-@deftypefnx {Runtime Function} {long long accum} __fracttita (long long @var{a})
-@deftypefnx {Runtime Function} {unsigned short fract} __fracttiuqq (long long @var{a})
-@deftypefnx {Runtime Function} {unsigned fract} __fracttiuhq (long long @var{a})
-@deftypefnx {Runtime Function} {unsigned long fract} __fracttiusq (long long @var{a})
-@deftypefnx {Runtime Function} {unsigned long long fract} __fracttiudq (long long @var{a})
-@deftypefnx {Runtime Function} {unsigned short accum} __fracttiuha (long long @var{a})
-@deftypefnx {Runtime Function} {unsigned accum} __fracttiusa (long long @var{a})
-@deftypefnx {Runtime Function} {unsigned long accum} __fracttiuda (long long @var{a})
-@deftypefnx {Runtime Function} {unsigned long long accum} __fracttiuta (long long @var{a})
-@deftypefnx {Runtime Function} {short fract} __fractsfqq (float @var{a})
-@deftypefnx {Runtime Function} {fract} __fractsfhq (float @var{a})
-@deftypefnx {Runtime Function} {long fract} __fractsfsq (float @var{a})
-@deftypefnx {Runtime Function} {long long fract} __fractsfdq (float @var{a})
-@deftypefnx {Runtime Function} {short accum} __fractsfha (float @var{a})
-@deftypefnx {Runtime Function} {accum} __fractsfsa (float @var{a})
-@deftypefnx {Runtime Function} {long accum} __fractsfda (float @var{a})
-@deftypefnx {Runtime Function} {long long accum} __fractsfta (float @var{a})
-@deftypefnx {Runtime Function} {unsigned short fract} __fractsfuqq (float @var{a})
-@deftypefnx {Runtime Function} {unsigned fract} __fractsfuhq (float @var{a})
-@deftypefnx {Runtime Function} {unsigned long fract} __fractsfusq (float @var{a})
-@deftypefnx {Runtime Function} {unsigned long long fract} __fractsfudq (float @var{a})
-@deftypefnx {Runtime Function} {unsigned short accum} __fractsfuha (float @var{a})
-@deftypefnx {Runtime Function} {unsigned accum} __fractsfusa (float @var{a})
-@deftypefnx {Runtime Function} {unsigned long accum} __fractsfuda (float @var{a})
-@deftypefnx {Runtime Function} {unsigned long long accum} __fractsfuta (float @var{a})
-@deftypefnx {Runtime Function} {short fract} __fractdfqq (double @var{a})
-@deftypefnx {Runtime Function} {fract} __fractdfhq (double @var{a})
-@deftypefnx {Runtime Function} {long fract} __fractdfsq (double @var{a})
-@deftypefnx {Runtime Function} {long long fract} __fractdfdq (double @var{a})
-@deftypefnx {Runtime Function} {short accum} __fractdfha (double @var{a})
-@deftypefnx {Runtime Function} {accum} __fractdfsa (double @var{a})
-@deftypefnx {Runtime Function} {long accum} __fractdfda (double @var{a})
-@deftypefnx {Runtime Function} {long long accum} __fractdfta (double @var{a})
-@deftypefnx {Runtime Function} {unsigned short fract} __fractdfuqq (double @var{a})
-@deftypefnx {Runtime Function} {unsigned fract} __fractdfuhq (double @var{a})
-@deftypefnx {Runtime Function} {unsigned long fract} __fractdfusq (double @var{a})
-@deftypefnx {Runtime Function} {unsigned long long fract} __fractdfudq (double @var{a})
-@deftypefnx {Runtime Function} {unsigned short accum} __fractdfuha (double @var{a})
-@deftypefnx {Runtime Function} {unsigned accum} __fractdfusa (double @var{a})
-@deftypefnx {Runtime Function} {unsigned long accum} __fractdfuda (double @var{a})
-@deftypefnx {Runtime Function} {unsigned long long accum} __fractdfuta (double @var{a})
-These functions convert from fractional and signed non-fractionals to
-fractionals and signed non-fractionals, without saturation.
-@end deftypefn
-
-@deftypefn {Runtime Function} {fract} __satfractqqhq2 (short fract @var{a})
-@deftypefnx {Runtime Function} {long fract} __satfractqqsq2 (short fract @var{a})
-@deftypefnx {Runtime Function} {long long fract} __satfractqqdq2 (short fract @var{a})
-@deftypefnx {Runtime Function} {short accum} __satfractqqha (short fract @var{a})
-@deftypefnx {Runtime Function} {accum} __satfractqqsa (short fract @var{a})
-@deftypefnx {Runtime Function} {long accum} __satfractqqda (short fract @var{a})
-@deftypefnx {Runtime Function} {long long accum} __satfractqqta (short fract @var{a})
-@deftypefnx {Runtime Function} {unsigned short fract} __satfractqquqq (short fract @var{a})
-@deftypefnx {Runtime Function} {unsigned fract} __satfractqquhq (short fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long fract} __satfractqqusq (short fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long long fract} __satfractqqudq (short fract @var{a})
-@deftypefnx {Runtime Function} {unsigned short accum} __satfractqquha (short fract @var{a})
-@deftypefnx {Runtime Function} {unsigned accum} __satfractqqusa (short fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long accum} __satfractqquda (short fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long long accum} __satfractqquta (short fract @var{a})
-@deftypefnx {Runtime Function} {short fract} __satfracthqqq2 (fract @var{a})
-@deftypefnx {Runtime Function} {long fract} __satfracthqsq2 (fract @var{a})
-@deftypefnx {Runtime Function} {long long fract} __satfracthqdq2 (fract @var{a})
-@deftypefnx {Runtime Function} {short accum} __satfracthqha (fract @var{a})
-@deftypefnx {Runtime Function} {accum} __satfracthqsa (fract @var{a})
-@deftypefnx {Runtime Function} {long accum} __satfracthqda (fract @var{a})
-@deftypefnx {Runtime Function} {long long accum} __satfracthqta (fract @var{a})
-@deftypefnx {Runtime Function} {unsigned short fract} __satfracthquqq (fract @var{a})
-@deftypefnx {Runtime Function} {unsigned fract} __satfracthquhq (fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long fract} __satfracthqusq (fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long long fract} __satfracthqudq (fract @var{a})
-@deftypefnx {Runtime Function} {unsigned short accum} __satfracthquha (fract @var{a})
-@deftypefnx {Runtime Function} {unsigned accum} __satfracthqusa (fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long accum} __satfracthquda (fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long long accum} __satfracthquta (fract @var{a})
-@deftypefnx {Runtime Function} {short fract} __satfractsqqq2 (long fract @var{a})
-@deftypefnx {Runtime Function} {fract} __satfractsqhq2 (long fract @var{a})
-@deftypefnx {Runtime Function} {long long fract} __satfractsqdq2 (long fract @var{a})
-@deftypefnx {Runtime Function} {short accum} __satfractsqha (long fract @var{a})
-@deftypefnx {Runtime Function} {accum} __satfractsqsa (long fract @var{a})
-@deftypefnx {Runtime Function} {long accum} __satfractsqda (long fract @var{a})
-@deftypefnx {Runtime Function} {long long accum} __satfractsqta (long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned short fract} __satfractsquqq (long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned fract} __satfractsquhq (long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long fract} __satfractsqusq (long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long long fract} __satfractsqudq (long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned short accum} __satfractsquha (long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned accum} __satfractsqusa (long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long accum} __satfractsquda (long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long long accum} __satfractsquta (long fract @var{a})
-@deftypefnx {Runtime Function} {short fract} __satfractdqqq2 (long long fract @var{a})
-@deftypefnx {Runtime Function} {fract} __satfractdqhq2 (long long fract @var{a})
-@deftypefnx {Runtime Function} {long fract} __satfractdqsq2 (long long fract @var{a})
-@deftypefnx {Runtime Function} {short accum} __satfractdqha (long long fract @var{a})
-@deftypefnx {Runtime Function} {accum} __satfractdqsa (long long fract @var{a})
-@deftypefnx {Runtime Function} {long accum} __satfractdqda (long long fract @var{a})
-@deftypefnx {Runtime Function} {long long accum} __satfractdqta (long long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned short fract} __satfractdquqq (long long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned fract} __satfractdquhq (long long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long fract} __satfractdqusq (long long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long long fract} __satfractdqudq (long long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned short accum} __satfractdquha (long long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned accum} __satfractdqusa (long long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long accum} __satfractdquda (long long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long long accum} __satfractdquta (long long fract @var{a})
-@deftypefnx {Runtime Function} {short fract} __satfracthaqq (short accum @var{a})
-@deftypefnx {Runtime Function} {fract} __satfracthahq (short accum @var{a})
-@deftypefnx {Runtime Function} {long fract} __satfracthasq (short accum @var{a})
-@deftypefnx {Runtime Function} {long long fract} __satfracthadq (short accum @var{a})
-@deftypefnx {Runtime Function} {accum} __satfracthasa2 (short accum @var{a})
-@deftypefnx {Runtime Function} {long accum} __satfracthada2 (short accum @var{a})
-@deftypefnx {Runtime Function} {long long accum} __satfracthata2 (short accum @var{a})
-@deftypefnx {Runtime Function} {unsigned short fract} __satfracthauqq (short accum @var{a})
-@deftypefnx {Runtime Function} {unsigned fract} __satfracthauhq (short accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long fract} __satfracthausq (short accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long long fract} __satfracthaudq (short accum @var{a})
-@deftypefnx {Runtime Function} {unsigned short accum} __satfracthauha (short accum @var{a})
-@deftypefnx {Runtime Function} {unsigned accum} __satfracthausa (short accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long accum} __satfracthauda (short accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long long accum} __satfracthauta (short accum @var{a})
-@deftypefnx {Runtime Function} {short fract} __satfractsaqq (accum @var{a})
-@deftypefnx {Runtime Function} {fract} __satfractsahq (accum @var{a})
-@deftypefnx {Runtime Function} {long fract} __satfractsasq (accum @var{a})
-@deftypefnx {Runtime Function} {long long fract} __satfractsadq (accum @var{a})
-@deftypefnx {Runtime Function} {short accum} __satfractsaha2 (accum @var{a})
-@deftypefnx {Runtime Function} {long accum} __satfractsada2 (accum @var{a})
-@deftypefnx {Runtime Function} {long long accum} __satfractsata2 (accum @var{a})
-@deftypefnx {Runtime Function} {unsigned short fract} __satfractsauqq (accum @var{a})
-@deftypefnx {Runtime Function} {unsigned fract} __satfractsauhq (accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long fract} __satfractsausq (accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long long fract} __satfractsaudq (accum @var{a})
-@deftypefnx {Runtime Function} {unsigned short accum} __satfractsauha (accum @var{a})
-@deftypefnx {Runtime Function} {unsigned accum} __satfractsausa (accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long accum} __satfractsauda (accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long long accum} __satfractsauta (accum @var{a})
-@deftypefnx {Runtime Function} {short fract} __satfractdaqq (long accum @var{a})
-@deftypefnx {Runtime Function} {fract} __satfractdahq (long accum @var{a})
-@deftypefnx {Runtime Function} {long fract} __satfractdasq (long accum @var{a})
-@deftypefnx {Runtime Function} {long long fract} __satfractdadq (long accum @var{a})
-@deftypefnx {Runtime Function} {short accum} __satfractdaha2 (long accum @var{a})
-@deftypefnx {Runtime Function} {accum} __satfractdasa2 (long accum @var{a})
-@deftypefnx {Runtime Function} {long long accum} __satfractdata2 (long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned short fract} __satfractdauqq (long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned fract} __satfractdauhq (long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long fract} __satfractdausq (long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long long fract} __satfractdaudq (long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned short accum} __satfractdauha (long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned accum} __satfractdausa (long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long accum} __satfractdauda (long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long long accum} __satfractdauta (long accum @var{a})
-@deftypefnx {Runtime Function} {short fract} __satfracttaqq (long long accum @var{a})
-@deftypefnx {Runtime Function} {fract} __satfracttahq (long long accum @var{a})
-@deftypefnx {Runtime Function} {long fract} __satfracttasq (long long accum @var{a})
-@deftypefnx {Runtime Function} {long long fract} __satfracttadq (long long accum @var{a})
-@deftypefnx {Runtime Function} {short accum} __satfracttaha2 (long long accum @var{a})
-@deftypefnx {Runtime Function} {accum} __satfracttasa2 (long long accum @var{a})
-@deftypefnx {Runtime Function} {long accum} __satfracttada2 (long long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned short fract} __satfracttauqq (long long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned fract} __satfracttauhq (long long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long fract} __satfracttausq (long long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long long fract} __satfracttaudq (long long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned short accum} __satfracttauha (long long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned accum} __satfracttausa (long long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long accum} __satfracttauda (long long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long long accum} __satfracttauta (long long accum @var{a})
-@deftypefnx {Runtime Function} {short fract} __satfractuqqqq (unsigned short fract @var{a})
-@deftypefnx {Runtime Function} {fract} __satfractuqqhq (unsigned short fract @var{a})
-@deftypefnx {Runtime Function} {long fract} __satfractuqqsq (unsigned short fract @var{a})
-@deftypefnx {Runtime Function} {long long fract} __satfractuqqdq (unsigned short fract @var{a})
-@deftypefnx {Runtime Function} {short accum} __satfractuqqha (unsigned short fract @var{a})
-@deftypefnx {Runtime Function} {accum} __satfractuqqsa (unsigned short fract @var{a})
-@deftypefnx {Runtime Function} {long accum} __satfractuqqda (unsigned short fract @var{a})
-@deftypefnx {Runtime Function} {long long accum} __satfractuqqta (unsigned short fract @var{a})
-@deftypefnx {Runtime Function} {unsigned fract} __satfractuqquhq2 (unsigned short fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long fract} __satfractuqqusq2 (unsigned short fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long long fract} __satfractuqqudq2 (unsigned short fract @var{a})
-@deftypefnx {Runtime Function} {unsigned short accum} __satfractuqquha (unsigned short fract @var{a})
-@deftypefnx {Runtime Function} {unsigned accum} __satfractuqqusa (unsigned short fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long accum} __satfractuqquda (unsigned short fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long long accum} __satfractuqquta (unsigned short fract @var{a})
-@deftypefnx {Runtime Function} {short fract} __satfractuhqqq (unsigned fract @var{a})
-@deftypefnx {Runtime Function} {fract} __satfractuhqhq (unsigned fract @var{a})
-@deftypefnx {Runtime Function} {long fract} __satfractuhqsq (unsigned fract @var{a})
-@deftypefnx {Runtime Function} {long long fract} __satfractuhqdq (unsigned fract @var{a})
-@deftypefnx {Runtime Function} {short accum} __satfractuhqha (unsigned fract @var{a})
-@deftypefnx {Runtime Function} {accum} __satfractuhqsa (unsigned fract @var{a})
-@deftypefnx {Runtime Function} {long accum} __satfractuhqda (unsigned fract @var{a})
-@deftypefnx {Runtime Function} {long long accum} __satfractuhqta (unsigned fract @var{a})
-@deftypefnx {Runtime Function} {unsigned short fract} __satfractuhquqq2 (unsigned fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long fract} __satfractuhqusq2 (unsigned fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long long fract} __satfractuhqudq2 (unsigned fract @var{a})
-@deftypefnx {Runtime Function} {unsigned short accum} __satfractuhquha (unsigned fract @var{a})
-@deftypefnx {Runtime Function} {unsigned accum} __satfractuhqusa (unsigned fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long accum} __satfractuhquda (unsigned fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long long accum} __satfractuhquta (unsigned fract @var{a})
-@deftypefnx {Runtime Function} {short fract} __satfractusqqq (unsigned long fract @var{a})
-@deftypefnx {Runtime Function} {fract} __satfractusqhq (unsigned long fract @var{a})
-@deftypefnx {Runtime Function} {long fract} __satfractusqsq (unsigned long fract @var{a})
-@deftypefnx {Runtime Function} {long long fract} __satfractusqdq (unsigned long fract @var{a})
-@deftypefnx {Runtime Function} {short accum} __satfractusqha (unsigned long fract @var{a})
-@deftypefnx {Runtime Function} {accum} __satfractusqsa (unsigned long fract @var{a})
-@deftypefnx {Runtime Function} {long accum} __satfractusqda (unsigned long fract @var{a})
-@deftypefnx {Runtime Function} {long long accum} __satfractusqta (unsigned long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned short fract} __satfractusquqq2 (unsigned long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned fract} __satfractusquhq2 (unsigned long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long long fract} __satfractusqudq2 (unsigned long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned short accum} __satfractusquha (unsigned long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned accum} __satfractusqusa (unsigned long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long accum} __satfractusquda (unsigned long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long long accum} __satfractusquta (unsigned long fract @var{a})
-@deftypefnx {Runtime Function} {short fract} __satfractudqqq (unsigned long long fract @var{a})
-@deftypefnx {Runtime Function} {fract} __satfractudqhq (unsigned long long fract @var{a})
-@deftypefnx {Runtime Function} {long fract} __satfractudqsq (unsigned long long fract @var{a})
-@deftypefnx {Runtime Function} {long long fract} __satfractudqdq (unsigned long long fract @var{a})
-@deftypefnx {Runtime Function} {short accum} __satfractudqha (unsigned long long fract @var{a})
-@deftypefnx {Runtime Function} {accum} __satfractudqsa (unsigned long long fract @var{a})
-@deftypefnx {Runtime Function} {long accum} __satfractudqda (unsigned long long fract @var{a})
-@deftypefnx {Runtime Function} {long long accum} __satfractudqta (unsigned long long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned short fract} __satfractudquqq2 (unsigned long long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned fract} __satfractudquhq2 (unsigned long long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long fract} __satfractudqusq2 (unsigned long long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned short accum} __satfractudquha (unsigned long long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned accum} __satfractudqusa (unsigned long long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long accum} __satfractudquda (unsigned long long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long long accum} __satfractudquta (unsigned long long fract @var{a})
-@deftypefnx {Runtime Function} {short fract} __satfractuhaqq (unsigned short accum @var{a})
-@deftypefnx {Runtime Function} {fract} __satfractuhahq (unsigned short accum @var{a})
-@deftypefnx {Runtime Function} {long fract} __satfractuhasq (unsigned short accum @var{a})
-@deftypefnx {Runtime Function} {long long fract} __satfractuhadq (unsigned short accum @var{a})
-@deftypefnx {Runtime Function} {short accum} __satfractuhaha (unsigned short accum @var{a})
-@deftypefnx {Runtime Function} {accum} __satfractuhasa (unsigned short accum @var{a})
-@deftypefnx {Runtime Function} {long accum} __satfractuhada (unsigned short accum @var{a})
-@deftypefnx {Runtime Function} {long long accum} __satfractuhata (unsigned short accum @var{a})
-@deftypefnx {Runtime Function} {unsigned short fract} __satfractuhauqq (unsigned short accum @var{a})
-@deftypefnx {Runtime Function} {unsigned fract} __satfractuhauhq (unsigned short accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long fract} __satfractuhausq (unsigned short accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long long fract} __satfractuhaudq (unsigned short accum @var{a})
-@deftypefnx {Runtime Function} {unsigned accum} __satfractuhausa2 (unsigned short accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long accum} __satfractuhauda2 (unsigned short accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long long accum} __satfractuhauta2 (unsigned short accum @var{a})
-@deftypefnx {Runtime Function} {short fract} __satfractusaqq (unsigned accum @var{a})
-@deftypefnx {Runtime Function} {fract} __satfractusahq (unsigned accum @var{a})
-@deftypefnx {Runtime Function} {long fract} __satfractusasq (unsigned accum @var{a})
-@deftypefnx {Runtime Function} {long long fract} __satfractusadq (unsigned accum @var{a})
-@deftypefnx {Runtime Function} {short accum} __satfractusaha (unsigned accum @var{a})
-@deftypefnx {Runtime Function} {accum} __satfractusasa (unsigned accum @var{a})
-@deftypefnx {Runtime Function} {long accum} __satfractusada (unsigned accum @var{a})
-@deftypefnx {Runtime Function} {long long accum} __satfractusata (unsigned accum @var{a})
-@deftypefnx {Runtime Function} {unsigned short fract} __satfractusauqq (unsigned accum @var{a})
-@deftypefnx {Runtime Function} {unsigned fract} __satfractusauhq (unsigned accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long fract} __satfractusausq (unsigned accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long long fract} __satfractusaudq (unsigned accum @var{a})
-@deftypefnx {Runtime Function} {unsigned short accum} __satfractusauha2 (unsigned accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long accum} __satfractusauda2 (unsigned accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long long accum} __satfractusauta2 (unsigned accum @var{a})
-@deftypefnx {Runtime Function} {short fract} __satfractudaqq (unsigned long accum @var{a})
-@deftypefnx {Runtime Function} {fract} __satfractudahq (unsigned long accum @var{a})
-@deftypefnx {Runtime Function} {long fract} __satfractudasq (unsigned long accum @var{a})
-@deftypefnx {Runtime Function} {long long fract} __satfractudadq (unsigned long accum @var{a})
-@deftypefnx {Runtime Function} {short accum} __satfractudaha (unsigned long accum @var{a})
-@deftypefnx {Runtime Function} {accum} __satfractudasa (unsigned long accum @var{a})
-@deftypefnx {Runtime Function} {long accum} __satfractudada (unsigned long accum @var{a})
-@deftypefnx {Runtime Function} {long long accum} __satfractudata (unsigned long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned short fract} __satfractudauqq (unsigned long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned fract} __satfractudauhq (unsigned long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long fract} __satfractudausq (unsigned long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long long fract} __satfractudaudq (unsigned long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned short accum} __satfractudauha2 (unsigned long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned accum} __satfractudausa2 (unsigned long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long long accum} __satfractudauta2 (unsigned long accum @var{a})
-@deftypefnx {Runtime Function} {short fract} __satfractutaqq (unsigned long long accum @var{a})
-@deftypefnx {Runtime Function} {fract} __satfractutahq (unsigned long long accum @var{a})
-@deftypefnx {Runtime Function} {long fract} __satfractutasq (unsigned long long accum @var{a})
-@deftypefnx {Runtime Function} {long long fract} __satfractutadq (unsigned long long accum @var{a})
-@deftypefnx {Runtime Function} {short accum} __satfractutaha (unsigned long long accum @var{a})
-@deftypefnx {Runtime Function} {accum} __satfractutasa (unsigned long long accum @var{a})
-@deftypefnx {Runtime Function} {long accum} __satfractutada (unsigned long long accum @var{a})
-@deftypefnx {Runtime Function} {long long accum} __satfractutata (unsigned long long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned short fract} __satfractutauqq (unsigned long long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned fract} __satfractutauhq (unsigned long long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long fract} __satfractutausq (unsigned long long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long long fract} __satfractutaudq (unsigned long long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned short accum} __satfractutauha2 (unsigned long long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned accum} __satfractutausa2 (unsigned long long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long accum} __satfractutauda2 (unsigned long long accum @var{a})
-@deftypefnx {Runtime Function} {short fract} __satfractqiqq (signed char @var{a})
-@deftypefnx {Runtime Function} {fract} __satfractqihq (signed char @var{a})
-@deftypefnx {Runtime Function} {long fract} __satfractqisq (signed char @var{a})
-@deftypefnx {Runtime Function} {long long fract} __satfractqidq (signed char @var{a})
-@deftypefnx {Runtime Function} {short accum} __satfractqiha (signed char @var{a})
-@deftypefnx {Runtime Function} {accum} __satfractqisa (signed char @var{a})
-@deftypefnx {Runtime Function} {long accum} __satfractqida (signed char @var{a})
-@deftypefnx {Runtime Function} {long long accum} __satfractqita (signed char @var{a})
-@deftypefnx {Runtime Function} {unsigned short fract} __satfractqiuqq (signed char @var{a})
-@deftypefnx {Runtime Function} {unsigned fract} __satfractqiuhq (signed char @var{a})
-@deftypefnx {Runtime Function} {unsigned long fract} __satfractqiusq (signed char @var{a})
-@deftypefnx {Runtime Function} {unsigned long long fract} __satfractqiudq (signed char @var{a})
-@deftypefnx {Runtime Function} {unsigned short accum} __satfractqiuha (signed char @var{a})
-@deftypefnx {Runtime Function} {unsigned accum} __satfractqiusa (signed char @var{a})
-@deftypefnx {Runtime Function} {unsigned long accum} __satfractqiuda (signed char @var{a})
-@deftypefnx {Runtime Function} {unsigned long long accum} __satfractqiuta (signed char @var{a})
-@deftypefnx {Runtime Function} {short fract} __satfracthiqq (short @var{a})
-@deftypefnx {Runtime Function} {fract} __satfracthihq (short @var{a})
-@deftypefnx {Runtime Function} {long fract} __satfracthisq (short @var{a})
-@deftypefnx {Runtime Function} {long long fract} __satfracthidq (short @var{a})
-@deftypefnx {Runtime Function} {short accum} __satfracthiha (short @var{a})
-@deftypefnx {Runtime Function} {accum} __satfracthisa (short @var{a})
-@deftypefnx {Runtime Function} {long accum} __satfracthida (short @var{a})
-@deftypefnx {Runtime Function} {long long accum} __satfracthita (short @var{a})
-@deftypefnx {Runtime Function} {unsigned short fract} __satfracthiuqq (short @var{a})
-@deftypefnx {Runtime Function} {unsigned fract} __satfracthiuhq (short @var{a})
-@deftypefnx {Runtime Function} {unsigned long fract} __satfracthiusq (short @var{a})
-@deftypefnx {Runtime Function} {unsigned long long fract} __satfracthiudq (short @var{a})
-@deftypefnx {Runtime Function} {unsigned short accum} __satfracthiuha (short @var{a})
-@deftypefnx {Runtime Function} {unsigned accum} __satfracthiusa (short @var{a})
-@deftypefnx {Runtime Function} {unsigned long accum} __satfracthiuda (short @var{a})
-@deftypefnx {Runtime Function} {unsigned long long accum} __satfracthiuta (short @var{a})
-@deftypefnx {Runtime Function} {short fract} __satfractsiqq (int @var{a})
-@deftypefnx {Runtime Function} {fract} __satfractsihq (int @var{a})
-@deftypefnx {Runtime Function} {long fract} __satfractsisq (int @var{a})
-@deftypefnx {Runtime Function} {long long fract} __satfractsidq (int @var{a})
-@deftypefnx {Runtime Function} {short accum} __satfractsiha (int @var{a})
-@deftypefnx {Runtime Function} {accum} __satfractsisa (int @var{a})
-@deftypefnx {Runtime Function} {long accum} __satfractsida (int @var{a})
-@deftypefnx {Runtime Function} {long long accum} __satfractsita (int @var{a})
-@deftypefnx {Runtime Function} {unsigned short fract} __satfractsiuqq (int @var{a})
-@deftypefnx {Runtime Function} {unsigned fract} __satfractsiuhq (int @var{a})
-@deftypefnx {Runtime Function} {unsigned long fract} __satfractsiusq (int @var{a})
-@deftypefnx {Runtime Function} {unsigned long long fract} __satfractsiudq (int @var{a})
-@deftypefnx {Runtime Function} {unsigned short accum} __satfractsiuha (int @var{a})
-@deftypefnx {Runtime Function} {unsigned accum} __satfractsiusa (int @var{a})
-@deftypefnx {Runtime Function} {unsigned long accum} __satfractsiuda (int @var{a})
-@deftypefnx {Runtime Function} {unsigned long long accum} __satfractsiuta (int @var{a})
-@deftypefnx {Runtime Function} {short fract} __satfractdiqq (long @var{a})
-@deftypefnx {Runtime Function} {fract} __satfractdihq (long @var{a})
-@deftypefnx {Runtime Function} {long fract} __satfractdisq (long @var{a})
-@deftypefnx {Runtime Function} {long long fract} __satfractdidq (long @var{a})
-@deftypefnx {Runtime Function} {short accum} __satfractdiha (long @var{a})
-@deftypefnx {Runtime Function} {accum} __satfractdisa (long @var{a})
-@deftypefnx {Runtime Function} {long accum} __satfractdida (long @var{a})
-@deftypefnx {Runtime Function} {long long accum} __satfractdita (long @var{a})
-@deftypefnx {Runtime Function} {unsigned short fract} __satfractdiuqq (long @var{a})
-@deftypefnx {Runtime Function} {unsigned fract} __satfractdiuhq (long @var{a})
-@deftypefnx {Runtime Function} {unsigned long fract} __satfractdiusq (long @var{a})
-@deftypefnx {Runtime Function} {unsigned long long fract} __satfractdiudq (long @var{a})
-@deftypefnx {Runtime Function} {unsigned short accum} __satfractdiuha (long @var{a})
-@deftypefnx {Runtime Function} {unsigned accum} __satfractdiusa (long @var{a})
-@deftypefnx {Runtime Function} {unsigned long accum} __satfractdiuda (long @var{a})
-@deftypefnx {Runtime Function} {unsigned long long accum} __satfractdiuta (long @var{a})
-@deftypefnx {Runtime Function} {short fract} __satfracttiqq (long long @var{a})
-@deftypefnx {Runtime Function} {fract} __satfracttihq (long long @var{a})
-@deftypefnx {Runtime Function} {long fract} __satfracttisq (long long @var{a})
-@deftypefnx {Runtime Function} {long long fract} __satfracttidq (long long @var{a})
-@deftypefnx {Runtime Function} {short accum} __satfracttiha (long long @var{a})
-@deftypefnx {Runtime Function} {accum} __satfracttisa (long long @var{a})
-@deftypefnx {Runtime Function} {long accum} __satfracttida (long long @var{a})
-@deftypefnx {Runtime Function} {long long accum} __satfracttita (long long @var{a})
-@deftypefnx {Runtime Function} {unsigned short fract} __satfracttiuqq (long long @var{a})
-@deftypefnx {Runtime Function} {unsigned fract} __satfracttiuhq (long long @var{a})
-@deftypefnx {Runtime Function} {unsigned long fract} __satfracttiusq (long long @var{a})
-@deftypefnx {Runtime Function} {unsigned long long fract} __satfracttiudq (long long @var{a})
-@deftypefnx {Runtime Function} {unsigned short accum} __satfracttiuha (long long @var{a})
-@deftypefnx {Runtime Function} {unsigned accum} __satfracttiusa (long long @var{a})
-@deftypefnx {Runtime Function} {unsigned long accum} __satfracttiuda (long long @var{a})
-@deftypefnx {Runtime Function} {unsigned long long accum} __satfracttiuta (long long @var{a})
-@deftypefnx {Runtime Function} {short fract} __satfractsfqq (float @var{a})
-@deftypefnx {Runtime Function} {fract} __satfractsfhq (float @var{a})
-@deftypefnx {Runtime Function} {long fract} __satfractsfsq (float @var{a})
-@deftypefnx {Runtime Function} {long long fract} __satfractsfdq (float @var{a})
-@deftypefnx {Runtime Function} {short accum} __satfractsfha (float @var{a})
-@deftypefnx {Runtime Function} {accum} __satfractsfsa (float @var{a})
-@deftypefnx {Runtime Function} {long accum} __satfractsfda (float @var{a})
-@deftypefnx {Runtime Function} {long long accum} __satfractsfta (float @var{a})
-@deftypefnx {Runtime Function} {unsigned short fract} __satfractsfuqq (float @var{a})
-@deftypefnx {Runtime Function} {unsigned fract} __satfractsfuhq (float @var{a})
-@deftypefnx {Runtime Function} {unsigned long fract} __satfractsfusq (float @var{a})
-@deftypefnx {Runtime Function} {unsigned long long fract} __satfractsfudq (float @var{a})
-@deftypefnx {Runtime Function} {unsigned short accum} __satfractsfuha (float @var{a})
-@deftypefnx {Runtime Function} {unsigned accum} __satfractsfusa (float @var{a})
-@deftypefnx {Runtime Function} {unsigned long accum} __satfractsfuda (float @var{a})
-@deftypefnx {Runtime Function} {unsigned long long accum} __satfractsfuta (float @var{a})
-@deftypefnx {Runtime Function} {short fract} __satfractdfqq (double @var{a})
-@deftypefnx {Runtime Function} {fract} __satfractdfhq (double @var{a})
-@deftypefnx {Runtime Function} {long fract} __satfractdfsq (double @var{a})
-@deftypefnx {Runtime Function} {long long fract} __satfractdfdq (double @var{a})
-@deftypefnx {Runtime Function} {short accum} __satfractdfha (double @var{a})
-@deftypefnx {Runtime Function} {accum} __satfractdfsa (double @var{a})
-@deftypefnx {Runtime Function} {long accum} __satfractdfda (double @var{a})
-@deftypefnx {Runtime Function} {long long accum} __satfractdfta (double @var{a})
-@deftypefnx {Runtime Function} {unsigned short fract} __satfractdfuqq (double @var{a})
-@deftypefnx {Runtime Function} {unsigned fract} __satfractdfuhq (double @var{a})
-@deftypefnx {Runtime Function} {unsigned long fract} __satfractdfusq (double @var{a})
-@deftypefnx {Runtime Function} {unsigned long long fract} __satfractdfudq (double @var{a})
-@deftypefnx {Runtime Function} {unsigned short accum} __satfractdfuha (double @var{a})
-@deftypefnx {Runtime Function} {unsigned accum} __satfractdfusa (double @var{a})
-@deftypefnx {Runtime Function} {unsigned long accum} __satfractdfuda (double @var{a})
-@deftypefnx {Runtime Function} {unsigned long long accum} __satfractdfuta (double @var{a})
-The functions convert from fractional and signed non-fractionals to
-fractionals, with saturation.
-@end deftypefn
-
-@deftypefn {Runtime Function} {unsigned char} __fractunsqqqi (short fract @var{a})
-@deftypefnx {Runtime Function} {unsigned short} __fractunsqqhi (short fract @var{a})
-@deftypefnx {Runtime Function} {unsigned int} __fractunsqqsi (short fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long} __fractunsqqdi (short fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long long} __fractunsqqti (short fract @var{a})
-@deftypefnx {Runtime Function} {unsigned char} __fractunshqqi (fract @var{a})
-@deftypefnx {Runtime Function} {unsigned short} __fractunshqhi (fract @var{a})
-@deftypefnx {Runtime Function} {unsigned int} __fractunshqsi (fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long} __fractunshqdi (fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long long} __fractunshqti (fract @var{a})
-@deftypefnx {Runtime Function} {unsigned char} __fractunssqqi (long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned short} __fractunssqhi (long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned int} __fractunssqsi (long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long} __fractunssqdi (long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long long} __fractunssqti (long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned char} __fractunsdqqi (long long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned short} __fractunsdqhi (long long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned int} __fractunsdqsi (long long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long} __fractunsdqdi (long long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long long} __fractunsdqti (long long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned char} __fractunshaqi (short accum @var{a})
-@deftypefnx {Runtime Function} {unsigned short} __fractunshahi (short accum @var{a})
-@deftypefnx {Runtime Function} {unsigned int} __fractunshasi (short accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long} __fractunshadi (short accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long long} __fractunshati (short accum @var{a})
-@deftypefnx {Runtime Function} {unsigned char} __fractunssaqi (accum @var{a})
-@deftypefnx {Runtime Function} {unsigned short} __fractunssahi (accum @var{a})
-@deftypefnx {Runtime Function} {unsigned int} __fractunssasi (accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long} __fractunssadi (accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long long} __fractunssati (accum @var{a})
-@deftypefnx {Runtime Function} {unsigned char} __fractunsdaqi (long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned short} __fractunsdahi (long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned int} __fractunsdasi (long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long} __fractunsdadi (long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long long} __fractunsdati (long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned char} __fractunstaqi (long long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned short} __fractunstahi (long long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned int} __fractunstasi (long long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long} __fractunstadi (long long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long long} __fractunstati (long long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned char} __fractunsuqqqi (unsigned short fract @var{a})
-@deftypefnx {Runtime Function} {unsigned short} __fractunsuqqhi (unsigned short fract @var{a})
-@deftypefnx {Runtime Function} {unsigned int} __fractunsuqqsi (unsigned short fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long} __fractunsuqqdi (unsigned short fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long long} __fractunsuqqti (unsigned short fract @var{a})
-@deftypefnx {Runtime Function} {unsigned char} __fractunsuhqqi (unsigned fract @var{a})
-@deftypefnx {Runtime Function} {unsigned short} __fractunsuhqhi (unsigned fract @var{a})
-@deftypefnx {Runtime Function} {unsigned int} __fractunsuhqsi (unsigned fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long} __fractunsuhqdi (unsigned fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long long} __fractunsuhqti (unsigned fract @var{a})
-@deftypefnx {Runtime Function} {unsigned char} __fractunsusqqi (unsigned long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned short} __fractunsusqhi (unsigned long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned int} __fractunsusqsi (unsigned long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long} __fractunsusqdi (unsigned long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long long} __fractunsusqti (unsigned long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned char} __fractunsudqqi (unsigned long long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned short} __fractunsudqhi (unsigned long long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned int} __fractunsudqsi (unsigned long long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long} __fractunsudqdi (unsigned long long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned long long} __fractunsudqti (unsigned long long fract @var{a})
-@deftypefnx {Runtime Function} {unsigned char} __fractunsuhaqi (unsigned short accum @var{a})
-@deftypefnx {Runtime Function} {unsigned short} __fractunsuhahi (unsigned short accum @var{a})
-@deftypefnx {Runtime Function} {unsigned int} __fractunsuhasi (unsigned short accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long} __fractunsuhadi (unsigned short accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long long} __fractunsuhati (unsigned short accum @var{a})
-@deftypefnx {Runtime Function} {unsigned char} __fractunsusaqi (unsigned accum @var{a})
-@deftypefnx {Runtime Function} {unsigned short} __fractunsusahi (unsigned accum @var{a})
-@deftypefnx {Runtime Function} {unsigned int} __fractunsusasi (unsigned accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long} __fractunsusadi (unsigned accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long long} __fractunsusati (unsigned accum @var{a})
-@deftypefnx {Runtime Function} {unsigned char} __fractunsudaqi (unsigned long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned short} __fractunsudahi (unsigned long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned int} __fractunsudasi (unsigned long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long} __fractunsudadi (unsigned long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long long} __fractunsudati (unsigned long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned char} __fractunsutaqi (unsigned long long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned short} __fractunsutahi (unsigned long long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned int} __fractunsutasi (unsigned long long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long} __fractunsutadi (unsigned long long accum @var{a})
-@deftypefnx {Runtime Function} {unsigned long long} __fractunsutati (unsigned long long accum @var{a})
-@deftypefnx {Runtime Function} {short fract} __fractunsqiqq (unsigned char @var{a})
-@deftypefnx {Runtime Function} {fract} __fractunsqihq (unsigned char @var{a})
-@deftypefnx {Runtime Function} {long fract} __fractunsqisq (unsigned char @var{a})
-@deftypefnx {Runtime Function} {long long fract} __fractunsqidq (unsigned char @var{a})
-@deftypefnx {Runtime Function} {short accum} __fractunsqiha (unsigned char @var{a})
-@deftypefnx {Runtime Function} {accum} __fractunsqisa (unsigned char @var{a})
-@deftypefnx {Runtime Function} {long accum} __fractunsqida (unsigned char @var{a})
-@deftypefnx {Runtime Function} {long long accum} __fractunsqita (unsigned char @var{a})
-@deftypefnx {Runtime Function} {unsigned short fract} __fractunsqiuqq (unsigned char @var{a})
-@deftypefnx {Runtime Function} {unsigned fract} __fractunsqiuhq (unsigned char @var{a})
-@deftypefnx {Runtime Function} {unsigned long fract} __fractunsqiusq (unsigned char @var{a})
-@deftypefnx {Runtime Function} {unsigned long long fract} __fractunsqiudq (unsigned char @var{a})
-@deftypefnx {Runtime Function} {unsigned short accum} __fractunsqiuha (unsigned char @var{a})
-@deftypefnx {Runtime Function} {unsigned accum} __fractunsqiusa (unsigned char @var{a})
-@deftypefnx {Runtime Function} {unsigned long accum} __fractunsqiuda (unsigned char @var{a})
-@deftypefnx {Runtime Function} {unsigned long long accum} __fractunsqiuta (unsigned char @var{a})
-@deftypefnx {Runtime Function} {short fract} __fractunshiqq (unsigned short @var{a})
-@deftypefnx {Runtime Function} {fract} __fractunshihq (unsigned short @var{a})
-@deftypefnx {Runtime Function} {long fract} __fractunshisq (unsigned short @var{a})
-@deftypefnx {Runtime Function} {long long fract} __fractunshidq (unsigned short @var{a})
-@deftypefnx {Runtime Function} {short accum} __fractunshiha (unsigned short @var{a})
-@deftypefnx {Runtime Function} {accum} __fractunshisa (unsigned short @var{a})
-@deftypefnx {Runtime Function} {long accum} __fractunshida (unsigned short @var{a})
-@deftypefnx {Runtime Function} {long long accum} __fractunshita (unsigned short @var{a})
-@deftypefnx {Runtime Function} {unsigned short fract} __fractunshiuqq (unsigned short @var{a})
-@deftypefnx {Runtime Function} {unsigned fract} __fractunshiuhq (unsigned short @var{a})
-@deftypefnx {Runtime Function} {unsigned long fract} __fractunshiusq (unsigned short @var{a})
-@deftypefnx {Runtime Function} {unsigned long long fract} __fractunshiudq (unsigned short @var{a})
-@deftypefnx {Runtime Function} {unsigned short accum} __fractunshiuha (unsigned short @var{a})
-@deftypefnx {Runtime Function} {unsigned accum} __fractunshiusa (unsigned short @var{a})
-@deftypefnx {Runtime Function} {unsigned long accum} __fractunshiuda (unsigned short @var{a})
-@deftypefnx {Runtime Function} {unsigned long long accum} __fractunshiuta (unsigned short @var{a})
-@deftypefnx {Runtime Function} {short fract} __fractunssiqq (unsigned int @var{a})
-@deftypefnx {Runtime Function} {fract} __fractunssihq (unsigned int @var{a})
-@deftypefnx {Runtime Function} {long fract} __fractunssisq (unsigned int @var{a})
-@deftypefnx {Runtime Function} {long long fract} __fractunssidq (unsigned int @var{a})
-@deftypefnx {Runtime Function} {short accum} __fractunssiha (unsigned int @var{a})
-@deftypefnx {Runtime Function} {accum} __fractunssisa (unsigned int @var{a})
-@deftypefnx {Runtime Function} {long accum} __fractunssida (unsigned int @var{a})
-@deftypefnx {Runtime Function} {long long accum} __fractunssita (unsigned int @var{a})
-@deftypefnx {Runtime Function} {unsigned short fract} __fractunssiuqq (unsigned int @var{a})
-@deftypefnx {Runtime Function} {unsigned fract} __fractunssiuhq (unsigned int @var{a})
-@deftypefnx {Runtime Function} {unsigned long fract} __fractunssiusq (unsigned int @var{a})
-@deftypefnx {Runtime Function} {unsigned long long fract} __fractunssiudq (unsigned int @var{a})
-@deftypefnx {Runtime Function} {unsigned short accum} __fractunssiuha (unsigned int @var{a})
-@deftypefnx {Runtime Function} {unsigned accum} __fractunssiusa (unsigned int @var{a})
-@deftypefnx {Runtime Function} {unsigned long accum} __fractunssiuda (unsigned int @var{a})
-@deftypefnx {Runtime Function} {unsigned long long accum} __fractunssiuta (unsigned int @var{a})
-@deftypefnx {Runtime Function} {short fract} __fractunsdiqq (unsigned long @var{a})
-@deftypefnx {Runtime Function} {fract} __fractunsdihq (unsigned long @var{a})
-@deftypefnx {Runtime Function} {long fract} __fractunsdisq (unsigned long @var{a})
-@deftypefnx {Runtime Function} {long long fract} __fractunsdidq (unsigned long @var{a})
-@deftypefnx {Runtime Function} {short accum} __fractunsdiha (unsigned long @var{a})
-@deftypefnx {Runtime Function} {accum} __fractunsdisa (unsigned long @var{a})
-@deftypefnx {Runtime Function} {long accum} __fractunsdida (unsigned long @var{a})
-@deftypefnx {Runtime Function} {long long accum} __fractunsdita (unsigned long @var{a})
-@deftypefnx {Runtime Function} {unsigned short fract} __fractunsdiuqq (unsigned long @var{a})
-@deftypefnx {Runtime Function} {unsigned fract} __fractunsdiuhq (unsigned long @var{a})
-@deftypefnx {Runtime Function} {unsigned long fract} __fractunsdiusq (unsigned long @var{a})
-@deftypefnx {Runtime Function} {unsigned long long fract} __fractunsdiudq (unsigned long @var{a})
-@deftypefnx {Runtime Function} {unsigned short accum} __fractunsdiuha (unsigned long @var{a})
-@deftypefnx {Runtime Function} {unsigned accum} __fractunsdiusa (unsigned long @var{a})
-@deftypefnx {Runtime Function} {unsigned long accum} __fractunsdiuda (unsigned long @var{a})
-@deftypefnx {Runtime Function} {unsigned long long accum} __fractunsdiuta (unsigned long @var{a})
-@deftypefnx {Runtime Function} {short fract} __fractunstiqq (unsigned long long @var{a})
-@deftypefnx {Runtime Function} {fract} __fractunstihq (unsigned long long @var{a})
-@deftypefnx {Runtime Function} {long fract} __fractunstisq (unsigned long long @var{a})
-@deftypefnx {Runtime Function} {long long fract} __fractunstidq (unsigned long long @var{a})
-@deftypefnx {Runtime Function} {short accum} __fractunstiha (unsigned long long @var{a})
-@deftypefnx {Runtime Function} {accum} __fractunstisa (unsigned long long @var{a})
-@deftypefnx {Runtime Function} {long accum} __fractunstida (unsigned long long @var{a})
-@deftypefnx {Runtime Function} {long long accum} __fractunstita (unsigned long long @var{a})
-@deftypefnx {Runtime Function} {unsigned short fract} __fractunstiuqq (unsigned long long @var{a})
-@deftypefnx {Runtime Function} {unsigned fract} __fractunstiuhq (unsigned long long @var{a})
-@deftypefnx {Runtime Function} {unsigned long fract} __fractunstiusq (unsigned long long @var{a})
-@deftypefnx {Runtime Function} {unsigned long long fract} __fractunstiudq (unsigned long long @var{a})
-@deftypefnx {Runtime Function} {unsigned short accum} __fractunstiuha (unsigned long long @var{a})
-@deftypefnx {Runtime Function} {unsigned accum} __fractunstiusa (unsigned long long @var{a})
-@deftypefnx {Runtime Function} {unsigned long accum} __fractunstiuda (unsigned long long @var{a})
-@deftypefnx {Runtime Function} {unsigned long long accum} __fractunstiuta (unsigned long long @var{a})
-These functions convert from fractionals to unsigned non-fractionals;
-and from unsigned non-fractionals to fractionals, without saturation.
-@end deftypefn
-
-@deftypefn {Runtime Function} {short fract} __satfractunsqiqq (unsigned char @var{a})
-@deftypefnx {Runtime Function} {fract} __satfractunsqihq (unsigned char @var{a})
-@deftypefnx {Runtime Function} {long fract} __satfractunsqisq (unsigned char @var{a})
-@deftypefnx {Runtime Function} {long long fract} __satfractunsqidq (unsigned char @var{a})
-@deftypefnx {Runtime Function} {short accum} __satfractunsqiha (unsigned char @var{a})
-@deftypefnx {Runtime Function} {accum} __satfractunsqisa (unsigned char @var{a})
-@deftypefnx {Runtime Function} {long accum} __satfractunsqida (unsigned char @var{a})
-@deftypefnx {Runtime Function} {long long accum} __satfractunsqita (unsigned char @var{a})
-@deftypefnx {Runtime Function} {unsigned short fract} __satfractunsqiuqq (unsigned char @var{a})
-@deftypefnx {Runtime Function} {unsigned fract} __satfractunsqiuhq (unsigned char @var{a})
-@deftypefnx {Runtime Function} {unsigned long fract} __satfractunsqiusq (unsigned char @var{a})
-@deftypefnx {Runtime Function} {unsigned long long fract} __satfractunsqiudq (unsigned char @var{a})
-@deftypefnx {Runtime Function} {unsigned short accum} __satfractunsqiuha (unsigned char @var{a})
-@deftypefnx {Runtime Function} {unsigned accum} __satfractunsqiusa (unsigned char @var{a})
-@deftypefnx {Runtime Function} {unsigned long accum} __satfractunsqiuda (unsigned char @var{a})
-@deftypefnx {Runtime Function} {unsigned long long accum} __satfractunsqiuta (unsigned char @var{a})
-@deftypefnx {Runtime Function} {short fract} __satfractunshiqq (unsigned short @var{a})
-@deftypefnx {Runtime Function} {fract} __satfractunshihq (unsigned short @var{a})
-@deftypefnx {Runtime Function} {long fract} __satfractunshisq (unsigned short @var{a})
-@deftypefnx {Runtime Function} {long long fract} __satfractunshidq (unsigned short @var{a})
-@deftypefnx {Runtime Function} {short accum} __satfractunshiha (unsigned short @var{a})
-@deftypefnx {Runtime Function} {accum} __satfractunshisa (unsigned short @var{a})
-@deftypefnx {Runtime Function} {long accum} __satfractunshida (unsigned short @var{a})
-@deftypefnx {Runtime Function} {long long accum} __satfractunshita (unsigned short @var{a})
-@deftypefnx {Runtime Function} {unsigned short fract} __satfractunshiuqq (unsigned short @var{a})
-@deftypefnx {Runtime Function} {unsigned fract} __satfractunshiuhq (unsigned short @var{a})
-@deftypefnx {Runtime Function} {unsigned long fract} __satfractunshiusq (unsigned short @var{a})
-@deftypefnx {Runtime Function} {unsigned long long fract} __satfractunshiudq (unsigned short @var{a})
-@deftypefnx {Runtime Function} {unsigned short accum} __satfractunshiuha (unsigned short @var{a})
-@deftypefnx {Runtime Function} {unsigned accum} __satfractunshiusa (unsigned short @var{a})
-@deftypefnx {Runtime Function} {unsigned long accum} __satfractunshiuda (unsigned short @var{a})
-@deftypefnx {Runtime Function} {unsigned long long accum} __satfractunshiuta (unsigned short @var{a})
-@deftypefnx {Runtime Function} {short fract} __satfractunssiqq (unsigned int @var{a})
-@deftypefnx {Runtime Function} {fract} __satfractunssihq (unsigned int @var{a})
-@deftypefnx {Runtime Function} {long fract} __satfractunssisq (unsigned int @var{a})
-@deftypefnx {Runtime Function} {long long fract} __satfractunssidq (unsigned int @var{a})
-@deftypefnx {Runtime Function} {short accum} __satfractunssiha (unsigned int @var{a})
-@deftypefnx {Runtime Function} {accum} __satfractunssisa (unsigned int @var{a})
-@deftypefnx {Runtime Function} {long accum} __satfractunssida (unsigned int @var{a})
-@deftypefnx {Runtime Function} {long long accum} __satfractunssita (unsigned int @var{a})
-@deftypefnx {Runtime Function} {unsigned short fract} __satfractunssiuqq (unsigned int @var{a})
-@deftypefnx {Runtime Function} {unsigned fract} __satfractunssiuhq (unsigned int @var{a})
-@deftypefnx {Runtime Function} {unsigned long fract} __satfractunssiusq (unsigned int @var{a})
-@deftypefnx {Runtime Function} {unsigned long long fract} __satfractunssiudq (unsigned int @var{a})
-@deftypefnx {Runtime Function} {unsigned short accum} __satfractunssiuha (unsigned int @var{a})
-@deftypefnx {Runtime Function} {unsigned accum} __satfractunssiusa (unsigned int @var{a})
-@deftypefnx {Runtime Function} {unsigned long accum} __satfractunssiuda (unsigned int @var{a})
-@deftypefnx {Runtime Function} {unsigned long long accum} __satfractunssiuta (unsigned int @var{a})
-@deftypefnx {Runtime Function} {short fract} __satfractunsdiqq (unsigned long @var{a})
-@deftypefnx {Runtime Function} {fract} __satfractunsdihq (unsigned long @var{a})
-@deftypefnx {Runtime Function} {long fract} __satfractunsdisq (unsigned long @var{a})
-@deftypefnx {Runtime Function} {long long fract} __satfractunsdidq (unsigned long @var{a})
-@deftypefnx {Runtime Function} {short accum} __satfractunsdiha (unsigned long @var{a})
-@deftypefnx {Runtime Function} {accum} __satfractunsdisa (unsigned long @var{a})
-@deftypefnx {Runtime Function} {long accum} __satfractunsdida (unsigned long @var{a})
-@deftypefnx {Runtime Function} {long long accum} __satfractunsdita (unsigned long @var{a})
-@deftypefnx {Runtime Function} {unsigned short fract} __satfractunsdiuqq (unsigned long @var{a})
-@deftypefnx {Runtime Function} {unsigned fract} __satfractunsdiuhq (unsigned long @var{a})
-@deftypefnx {Runtime Function} {unsigned long fract} __satfractunsdiusq (unsigned long @var{a})
-@deftypefnx {Runtime Function} {unsigned long long fract} __satfractunsdiudq (unsigned long @var{a})
-@deftypefnx {Runtime Function} {unsigned short accum} __satfractunsdiuha (unsigned long @var{a})
-@deftypefnx {Runtime Function} {unsigned accum} __satfractunsdiusa (unsigned long @var{a})
-@deftypefnx {Runtime Function} {unsigned long accum} __satfractunsdiuda (unsigned long @var{a})
-@deftypefnx {Runtime Function} {unsigned long long accum} __satfractunsdiuta (unsigned long @var{a})
-@deftypefnx {Runtime Function} {short fract} __satfractunstiqq (unsigned long long @var{a})
-@deftypefnx {Runtime Function} {fract} __satfractunstihq (unsigned long long @var{a})
-@deftypefnx {Runtime Function} {long fract} __satfractunstisq (unsigned long long @var{a})
-@deftypefnx {Runtime Function} {long long fract} __satfractunstidq (unsigned long long @var{a})
-@deftypefnx {Runtime Function} {short accum} __satfractunstiha (unsigned long long @var{a})
-@deftypefnx {Runtime Function} {accum} __satfractunstisa (unsigned long long @var{a})
-@deftypefnx {Runtime Function} {long accum} __satfractunstida (unsigned long long @var{a})
-@deftypefnx {Runtime Function} {long long accum} __satfractunstita (unsigned long long @var{a})
-@deftypefnx {Runtime Function} {unsigned short fract} __satfractunstiuqq (unsigned long long @var{a})
-@deftypefnx {Runtime Function} {unsigned fract} __satfractunstiuhq (unsigned long long @var{a})
-@deftypefnx {Runtime Function} {unsigned long fract} __satfractunstiusq (unsigned long long @var{a})
-@deftypefnx {Runtime Function} {unsigned long long fract} __satfractunstiudq (unsigned long long @var{a})
-@deftypefnx {Runtime Function} {unsigned short accum} __satfractunstiuha (unsigned long long @var{a})
-@deftypefnx {Runtime Function} {unsigned accum} __satfractunstiusa (unsigned long long @var{a})
-@deftypefnx {Runtime Function} {unsigned long accum} __satfractunstiuda (unsigned long long @var{a})
-@deftypefnx {Runtime Function} {unsigned long long accum} __satfractunstiuta (unsigned long long @var{a})
-These functions convert from unsigned non-fractionals to fractionals,
-with saturation.
-@end deftypefn
-
-@node Exception handling routines
-@section Language-independent routines for exception handling
-
-document me!
-
-@smallexample
- _Unwind_DeleteException
- _Unwind_Find_FDE
- _Unwind_ForcedUnwind
- _Unwind_GetGR
- _Unwind_GetIP
- _Unwind_GetLanguageSpecificData
- _Unwind_GetRegionStart
- _Unwind_GetTextRelBase
- _Unwind_GetDataRelBase
- _Unwind_RaiseException
- _Unwind_Resume
- _Unwind_SetGR
- _Unwind_SetIP
- _Unwind_FindEnclosingFunction
- _Unwind_SjLj_Register
- _Unwind_SjLj_Unregister
- _Unwind_SjLj_RaiseException
- _Unwind_SjLj_ForcedUnwind
- _Unwind_SjLj_Resume
- __deregister_frame
- __deregister_frame_info
- __deregister_frame_info_bases
- __register_frame
- __register_frame_info
- __register_frame_info_bases
- __register_frame_info_table
- __register_frame_info_table_bases
- __register_frame_table
-@end smallexample
-
-@node Miscellaneous routines
-@section Miscellaneous runtime library routines
-
-@subsection Cache control functions
-@deftypefn {Runtime Function} void __clear_cache (char *@var{beg}, char *@var{end})
-This function clears the instruction cache between @var{beg} and @var{end}.
-@end deftypefn
-
-@subsection Split stack functions and variables
-@deftypefn {Runtime Function} {void *} __splitstack_find (void *@var{segment_arg}, @
-void *@var{sp}, size_t @var{len}, void **@var{next_segment}, @
-void **@var{next_sp}, void **@var{initial_sp})
-When using @option{-fsplit-stack}, this call may be used to iterate
-over the stack segments. It may be called like this:
-@smallexample
- void *next_segment = NULL;
- void *next_sp = NULL;
- void *initial_sp = NULL;
- void *stack;
- size_t stack_size;
- while ((stack = __splitstack_find (next_segment, next_sp,
- &stack_size, &next_segment,
- &next_sp, &initial_sp))
- != NULL)
- @{
- /* Stack segment starts at stack and is
- stack_size bytes long. */
- @}
-@end smallexample
-
-There is no way to iterate over the stack segments of a different
-thread. However, what is permitted is for one thread to call this
-with the @var{segment_arg} and @var{sp} arguments NULL, to pass
-@var{next_segment}, @var{next_sp}, and @var{initial_sp} to a different
-thread, and then to suspend one way or another. A different thread
-may run the subsequent @code{__splitstack_find} iterations. Of
-course, this will only work if the first thread is suspended while the
-second thread is calling @code{__splitstack_find}. If not, the second
-thread could be looking at the stack while it is changing, and
-anything could happen.
-@end deftypefn
-
-@defvar __morestack_segments
-@defvarx __morestack_current_segment
-@defvarx __morestack_initial_sp
-Internal variables used by the @option{-fsplit-stack} implementation.
-@end defvar
+++ /dev/null
-@c Copyright (C) 2006-2022 Free Software Foundation, Inc.
-@c Free Software Foundation, Inc.
-@c This is part of the GCC manual.
-@c For copying conditions, see the file gcc.texi.
-
-@c ---------------------------------------------------------------------
-@c Loop Representation
-@c ---------------------------------------------------------------------
-
-@node Loop Analysis and Representation
-@chapter Analysis and Representation of Loops
-
-GCC provides extensive infrastructure for work with natural loops, i.e.,
-strongly connected components of CFG with only one entry block. This
-chapter describes representation of loops in GCC, both on GIMPLE and in
-RTL, as well as the interfaces to loop-related analyses (induction
-variable analysis and number of iterations analysis).
-
-@menu
-* Loop representation:: Representation and analysis of loops.
-* Loop querying:: Getting information about loops.
-* Loop manipulation:: Loop manipulation functions.
-* LCSSA:: Loop-closed SSA form.
-* Scalar evolutions:: Induction variables on GIMPLE.
-* loop-iv:: Induction variables on RTL.
-* Number of iterations:: Number of iterations analysis.
-* Dependency analysis:: Data dependency analysis.
-@end menu
-
-@node Loop representation
-@section Loop representation
-@cindex Loop representation
-@cindex Loop analysis
-
-This chapter describes the representation of loops in GCC, and functions
-that can be used to build, modify and analyze this representation. Most
-of the interfaces and data structures are declared in @file{cfgloop.h}.
-Loop structures are analyzed and this information disposed or updated
-at the discretion of individual passes. Still most of the generic
-CFG manipulation routines are aware of loop structures and try to
-keep them up-to-date. By this means an increasing part of the
-compilation pipeline is setup to maintain loop structure across
-passes to allow attaching meta information to individual loops
-for consumption by later passes.
-
-In general, a natural loop has one entry block (header) and possibly
-several back edges (latches) leading to the header from the inside of
-the loop. Loops with several latches may appear if several loops share
-a single header, or if there is a branching in the middle of the loop.
-The representation of loops in GCC however allows only loops with a
-single latch. During loop analysis, headers of such loops are split and
-forwarder blocks are created in order to disambiguate their structures.
-Heuristic based on profile information and structure of the induction
-variables in the loops is used to determine whether the latches
-correspond to sub-loops or to control flow in a single loop. This means
-that the analysis sometimes changes the CFG, and if you run it in the
-middle of an optimization pass, you must be able to deal with the new
-blocks. You may avoid CFG changes by passing
-@code{LOOPS_MAY_HAVE_MULTIPLE_LATCHES} flag to the loop discovery,
-note however that most other loop manipulation functions will not work
-correctly for loops with multiple latch edges (the functions that only
-query membership of blocks to loops and subloop relationships, or
-enumerate and test loop exits, can be expected to work).
-
-Body of the loop is the set of blocks that are dominated by its header,
-and reachable from its latch against the direction of edges in CFG@. The
-loops are organized in a containment hierarchy (tree) such that all the
-loops immediately contained inside loop L are the children of L in the
-tree. This tree is represented by the @code{struct loops} structure.
-The root of this tree is a fake loop that contains all blocks in the
-function. Each of the loops is represented in a @code{struct loop}
-structure. Each loop is assigned an index (@code{num} field of the
-@code{struct loop} structure), and the pointer to the loop is stored in
-the corresponding field of the @code{larray} vector in the loops
-structure. The indices do not have to be continuous, there may be
-empty (@code{NULL}) entries in the @code{larray} created by deleting
-loops. Also, there is no guarantee on the relative order of a loop
-and its subloops in the numbering. The index of a loop never changes.
-
-The entries of the @code{larray} field should not be accessed directly.
-The function @code{get_loop} returns the loop description for a loop with
-the given index. @code{number_of_loops} function returns number of loops
-in the function. To traverse all loops, use a range-based for loop with
-class @code{loops_list} instance. The @code{flags} argument passed to the
-constructor function of class @code{loops_list} is used to determine the
-direction of traversal and the set of loops visited. Each loop is
-guaranteed to be visited exactly once, regardless of the changes to the
-loop tree, and the loops may be removed during the traversal. The newly
-created loops are never traversed, if they need to be visited, this must
-be done separately after their creation.
-
-Each basic block contains the reference to the innermost loop it belongs
-to (@code{loop_father}). For this reason, it is only possible to have
-one @code{struct loops} structure initialized at the same time for each
-CFG@. The global variable @code{current_loops} contains the
-@code{struct loops} structure. Many of the loop manipulation functions
-assume that dominance information is up-to-date.
-
-The loops are analyzed through @code{loop_optimizer_init} function. The
-argument of this function is a set of flags represented in an integer
-bitmask. These flags specify what other properties of the loop
-structures should be calculated/enforced and preserved later:
-
-@itemize
-@item @code{LOOPS_MAY_HAVE_MULTIPLE_LATCHES}: If this flag is set, no
-changes to CFG will be performed in the loop analysis, in particular,
-loops with multiple latch edges will not be disambiguated. If a loop
-has multiple latches, its latch block is set to NULL@. Most of
-the loop manipulation functions will not work for loops in this shape.
-No other flags that require CFG changes can be passed to
-loop_optimizer_init.
-@item @code{LOOPS_HAVE_PREHEADERS}: Forwarder blocks are created in such
-a way that each loop has only one entry edge, and additionally, the
-source block of this entry edge has only one successor. This creates a
-natural place where the code can be moved out of the loop, and ensures
-that the entry edge of the loop leads from its immediate super-loop.
-@item @code{LOOPS_HAVE_SIMPLE_LATCHES}: Forwarder blocks are created to
-force the latch block of each loop to have only one successor. This
-ensures that the latch of the loop does not belong to any of its
-sub-loops, and makes manipulation with the loops significantly easier.
-Most of the loop manipulation functions assume that the loops are in
-this shape. Note that with this flag, the ``normal'' loop without any
-control flow inside and with one exit consists of two basic blocks.
-@item @code{LOOPS_HAVE_MARKED_IRREDUCIBLE_REGIONS}: Basic blocks and
-edges in the strongly connected components that are not natural loops
-(have more than one entry block) are marked with
-@code{BB_IRREDUCIBLE_LOOP} and @code{EDGE_IRREDUCIBLE_LOOP} flags. The
-flag is not set for blocks and edges that belong to natural loops that
-are in such an irreducible region (but it is set for the entry and exit
-edges of such a loop, if they lead to/from this region).
-@item @code{LOOPS_HAVE_RECORDED_EXITS}: The lists of exits are recorded
-and updated for each loop. This makes some functions (e.g.,
-@code{get_loop_exit_edges}) more efficient. Some functions (e.g.,
-@code{single_exit}) can be used only if the lists of exits are
-recorded.
-@end itemize
-
-These properties may also be computed/enforced later, using functions
-@code{create_preheaders}, @code{force_single_succ_latches},
-@code{mark_irreducible_loops} and @code{record_loop_exits}.
-The properties can be queried using @code{loops_state_satisfies_p}.
-
-The memory occupied by the loops structures should be freed with
-@code{loop_optimizer_finalize} function. When loop structures are
-setup to be preserved across passes this function reduces the
-information to be kept up-to-date to a minimum (only
-@code{LOOPS_MAY_HAVE_MULTIPLE_LATCHES} set).
-
-The CFG manipulation functions in general do not update loop structures.
-Specialized versions that additionally do so are provided for the most
-common tasks. On GIMPLE, @code{cleanup_tree_cfg_loop} function can be
-used to cleanup CFG while updating the loops structures if
-@code{current_loops} is set.
-
-At the moment loop structure is preserved from the start of GIMPLE
-loop optimizations until the end of RTL loop optimizations. During
-this time a loop can be tracked by its @code{struct loop} and number.
-
-@node Loop querying
-@section Loop querying
-@cindex Loop querying
-
-The functions to query the information about loops are declared in
-@file{cfgloop.h}. Some of the information can be taken directly from
-the structures. @code{loop_father} field of each basic block contains
-the innermost loop to that the block belongs. The most useful fields of
-loop structure (that are kept up-to-date at all times) are:
-
-@itemize
-@item @code{header}, @code{latch}: Header and latch basic blocks of the
-loop.
-@item @code{num_nodes}: Number of basic blocks in the loop (including
-the basic blocks of the sub-loops).
-@item @code{outer}, @code{inner}, @code{next}: The super-loop, the first
-sub-loop, and the sibling of the loop in the loops tree.
-@end itemize
-
-There are other fields in the loop structures, many of them used only by
-some of the passes, or not updated during CFG changes; in general, they
-should not be accessed directly.
-
-The most important functions to query loop structures are:
-
-@itemize
-@item @code{loop_depth}: The depth of the loop in the loops tree, i.e., the
-number of super-loops of the loop.
-@item @code{flow_loops_dump}: Dumps the information about loops to a
-file.
-@item @code{verify_loop_structure}: Checks consistency of the loop
-structures.
-@item @code{loop_latch_edge}: Returns the latch edge of a loop.
-@item @code{loop_preheader_edge}: If loops have preheaders, returns
-the preheader edge of a loop.
-@item @code{flow_loop_nested_p}: Tests whether loop is a sub-loop of
-another loop.
-@item @code{flow_bb_inside_loop_p}: Tests whether a basic block belongs
-to a loop (including its sub-loops).
-@item @code{find_common_loop}: Finds the common super-loop of two loops.
-@item @code{superloop_at_depth}: Returns the super-loop of a loop with
-the given depth.
-@item @code{tree_num_loop_insns}, @code{num_loop_insns}: Estimates the
-number of insns in the loop, on GIMPLE and on RTL.
-@item @code{loop_exit_edge_p}: Tests whether edge is an exit from a
-loop.
-@item @code{mark_loop_exit_edges}: Marks all exit edges of all loops
-with @code{EDGE_LOOP_EXIT} flag.
-@item @code{get_loop_body}, @code{get_loop_body_in_dom_order},
-@code{get_loop_body_in_bfs_order}: Enumerates the basic blocks in the
-loop in depth-first search order in reversed CFG, ordered by dominance
-relation, and breath-first search order, respectively.
-@item @code{single_exit}: Returns the single exit edge of the loop, or
-@code{NULL} if the loop has more than one exit. You can only use this
-function if @code{LOOPS_HAVE_RECORDED_EXITS} is used.
-@item @code{get_loop_exit_edges}: Enumerates the exit edges of a loop.
-@item @code{just_once_each_iteration_p}: Returns true if the basic block
-is executed exactly once during each iteration of a loop (that is, it
-does not belong to a sub-loop, and it dominates the latch of the loop).
-@end itemize
-
-@node Loop manipulation
-@section Loop manipulation
-@cindex Loop manipulation
-
-The loops tree can be manipulated using the following functions:
-
-@itemize
-@item @code{flow_loop_tree_node_add}: Adds a node to the tree.
-@item @code{flow_loop_tree_node_remove}: Removes a node from the tree.
-@item @code{add_bb_to_loop}: Adds a basic block to a loop.
-@item @code{remove_bb_from_loops}: Removes a basic block from loops.
-@end itemize
-
-Most low-level CFG functions update loops automatically. The following
-functions handle some more complicated cases of CFG manipulations:
-
-@itemize
-@item @code{remove_path}: Removes an edge and all blocks it dominates.
-@item @code{split_loop_exit_edge}: Splits exit edge of the loop,
-ensuring that PHI node arguments remain in the loop (this ensures that
-loop-closed SSA form is preserved). Only useful on GIMPLE.
-@end itemize
-
-Finally, there are some higher-level loop transformations implemented.
-While some of them are written so that they should work on non-innermost
-loops, they are mostly untested in that case, and at the moment, they
-are only reliable for the innermost loops:
-
-@itemize
-@item @code{create_iv}: Creates a new induction variable. Only works on
-GIMPLE@. @code{standard_iv_increment_position} can be used to find a
-suitable place for the iv increment.
-@item @code{duplicate_loop_body_to_header_edge},
-@code{tree_duplicate_loop_body_to_header_edge}: These functions (on RTL and
-on GIMPLE) duplicate the body of the loop prescribed number of times on
-one of the edges entering loop header, thus performing either loop
-unrolling or loop peeling. @code{can_duplicate_loop_p}
-(@code{can_unroll_loop_p} on GIMPLE) must be true for the duplicated
-loop.
-@item @code{loop_version}: This function creates a copy of a loop, and
-a branch before them that selects one of them depending on the
-prescribed condition. This is useful for optimizations that need to
-verify some assumptions in runtime (one of the copies of the loop is
-usually left unchanged, while the other one is transformed in some way).
-@item @code{tree_unroll_loop}: Unrolls the loop, including peeling the
-extra iterations to make the number of iterations divisible by unroll
-factor, updating the exit condition, and removing the exits that now
-cannot be taken. Works only on GIMPLE.
-@end itemize
-
-@node LCSSA
-@section Loop-closed SSA form
-@cindex LCSSA
-@cindex Loop-closed SSA form
-
-Throughout the loop optimizations on tree level, one extra condition is
-enforced on the SSA form: No SSA name is used outside of the loop in
-that it is defined. The SSA form satisfying this condition is called
-``loop-closed SSA form'' -- LCSSA@. To enforce LCSSA, PHI nodes must be
-created at the exits of the loops for the SSA names that are used
-outside of them. Only the real operands (not virtual SSA names) are
-held in LCSSA, in order to save memory.
-
-There are various benefits of LCSSA:
-
-@itemize
-@item Many optimizations (value range analysis, final value
-replacement) are interested in the values that are defined in the loop
-and used outside of it, i.e., exactly those for that we create new PHI
-nodes.
-@item In induction variable analysis, it is not necessary to specify the
-loop in that the analysis should be performed -- the scalar evolution
-analysis always returns the results with respect to the loop in that the
-SSA name is defined.
-@item It makes updating of SSA form during loop transformations simpler.
-Without LCSSA, operations like loop unrolling may force creation of PHI
-nodes arbitrarily far from the loop, while in LCSSA, the SSA form can be
-updated locally. However, since we only keep real operands in LCSSA, we
-cannot use this advantage (we could have local updating of real
-operands, but it is not much more efficient than to use generic SSA form
-updating for it as well; the amount of changes to SSA is the same).
-@end itemize
-
-However, it also means LCSSA must be updated. This is usually
-straightforward, unless you create a new value in loop and use it
-outside, or unless you manipulate loop exit edges (functions are
-provided to make these manipulations simple).
-@code{rewrite_into_loop_closed_ssa} is used to rewrite SSA form to
-LCSSA, and @code{verify_loop_closed_ssa} to check that the invariant of
-LCSSA is preserved.
-
-@node Scalar evolutions
-@section Scalar evolutions
-@cindex Scalar evolutions
-@cindex IV analysis on GIMPLE
-
-Scalar evolutions (SCEV) are used to represent results of induction
-variable analysis on GIMPLE@. They enable us to represent variables with
-complicated behavior in a simple and consistent way (we only use it to
-express values of polynomial induction variables, but it is possible to
-extend it). The interfaces to SCEV analysis are declared in
-@file{tree-scalar-evolution.h}. To use scalar evolutions analysis,
-@code{scev_initialize} must be used. To stop using SCEV,
-@code{scev_finalize} should be used. SCEV analysis caches results in
-order to save time and memory. This cache however is made invalid by
-most of the loop transformations, including removal of code. If such a
-transformation is performed, @code{scev_reset} must be called to clean
-the caches.
-
-Given an SSA name, its behavior in loops can be analyzed using the
-@code{analyze_scalar_evolution} function. The returned SCEV however
-does not have to be fully analyzed and it may contain references to
-other SSA names defined in the loop. To resolve these (potentially
-recursive) references, @code{instantiate_parameters} or
-@code{resolve_mixers} functions must be used.
-@code{instantiate_parameters} is useful when you use the results of SCEV
-only for some analysis, and when you work with whole nest of loops at
-once. It will try replacing all SSA names by their SCEV in all loops,
-including the super-loops of the current loop, thus providing a complete
-information about the behavior of the variable in the loop nest.
-@code{resolve_mixers} is useful if you work with only one loop at a
-time, and if you possibly need to create code based on the value of the
-induction variable. It will only resolve the SSA names defined in the
-current loop, leaving the SSA names defined outside unchanged, even if
-their evolution in the outer loops is known.
-
-The SCEV is a normal tree expression, except for the fact that it may
-contain several special tree nodes. One of them is
-@code{SCEV_NOT_KNOWN}, used for SSA names whose value cannot be
-expressed. The other one is @code{POLYNOMIAL_CHREC}. Polynomial chrec
-has three arguments -- base, step and loop (both base and step may
-contain further polynomial chrecs). Type of the expression and of base
-and step must be the same. A variable has evolution
-@code{POLYNOMIAL_CHREC(base, step, loop)} if it is (in the specified
-loop) equivalent to @code{x_1} in the following example
-
-@smallexample
-while (@dots{})
- @{
- x_1 = phi (base, x_2);
- x_2 = x_1 + step;
- @}
-@end smallexample
-
-Note that this includes the language restrictions on the operations.
-For example, if we compile C code and @code{x} has signed type, then the
-overflow in addition would cause undefined behavior, and we may assume
-that this does not happen. Hence, the value with this SCEV cannot
-overflow (which restricts the number of iterations of such a loop).
-
-In many cases, one wants to restrict the attention just to affine
-induction variables. In this case, the extra expressive power of SCEV
-is not useful, and may complicate the optimizations. In this case,
-@code{simple_iv} function may be used to analyze a value -- the result
-is a loop-invariant base and step.
-
-@node loop-iv
-@section IV analysis on RTL
-@cindex IV analysis on RTL
-
-The induction variable on RTL is simple and only allows analysis of
-affine induction variables, and only in one loop at once. The interface
-is declared in @file{cfgloop.h}. Before analyzing induction variables
-in a loop L, @code{iv_analysis_loop_init} function must be called on L.
-After the analysis (possibly calling @code{iv_analysis_loop_init} for
-several loops) is finished, @code{iv_analysis_done} should be called.
-The following functions can be used to access the results of the
-analysis:
-
-@itemize
-@item @code{iv_analyze}: Analyzes a single register used in the given
-insn. If no use of the register in this insn is found, the following
-insns are scanned, so that this function can be called on the insn
-returned by get_condition.
-@item @code{iv_analyze_result}: Analyzes result of the assignment in the
-given insn.
-@item @code{iv_analyze_expr}: Analyzes a more complicated expression.
-All its operands are analyzed by @code{iv_analyze}, and hence they must
-be used in the specified insn or one of the following insns.
-@end itemize
-
-The description of the induction variable is provided in @code{struct
-rtx_iv}. In order to handle subregs, the representation is a bit
-complicated; if the value of the @code{extend} field is not
-@code{UNKNOWN}, the value of the induction variable in the i-th
-iteration is
-
-@smallexample
-delta + mult * extend_@{extend_mode@} (subreg_@{mode@} (base + i * step)),
-@end smallexample
-
-with the following exception: if @code{first_special} is true, then the
-value in the first iteration (when @code{i} is zero) is @code{delta +
-mult * base}. However, if @code{extend} is equal to @code{UNKNOWN},
-then @code{first_special} must be false, @code{delta} 0, @code{mult} 1
-and the value in the i-th iteration is
-
-@smallexample
-subreg_@{mode@} (base + i * step)
-@end smallexample
-
-The function @code{get_iv_value} can be used to perform these
-calculations.
-
-@node Number of iterations
-@section Number of iterations analysis
-@cindex Number of iterations analysis
-
-Both on GIMPLE and on RTL, there are functions available to determine
-the number of iterations of a loop, with a similar interface. The
-number of iterations of a loop in GCC is defined as the number of
-executions of the loop latch. In many cases, it is not possible to
-determine the number of iterations unconditionally -- the determined
-number is correct only if some assumptions are satisfied. The analysis
-tries to verify these conditions using the information contained in the
-program; if it fails, the conditions are returned together with the
-result. The following information and conditions are provided by the
-analysis:
-
-@itemize
-@item @code{assumptions}: If this condition is false, the rest of
-the information is invalid.
-@item @code{noloop_assumptions} on RTL, @code{may_be_zero} on GIMPLE: If
-this condition is true, the loop exits in the first iteration.
-@item @code{infinite}: If this condition is true, the loop is infinite.
-This condition is only available on RTL@. On GIMPLE, conditions for
-finiteness of the loop are included in @code{assumptions}.
-@item @code{niter_expr} on RTL, @code{niter} on GIMPLE: The expression
-that gives number of iterations. The number of iterations is defined as
-the number of executions of the loop latch.
-@end itemize
-
-Both on GIMPLE and on RTL, it necessary for the induction variable
-analysis framework to be initialized (SCEV on GIMPLE, loop-iv on RTL).
-On GIMPLE, the results are stored to @code{struct tree_niter_desc}
-structure. Number of iterations before the loop is exited through a
-given exit can be determined using @code{number_of_iterations_exit}
-function. On RTL, the results are returned in @code{struct niter_desc}
-structure. The corresponding function is named
-@code{check_simple_exit}. There are also functions that pass through
-all the exits of a loop and try to find one with easy to determine
-number of iterations -- @code{find_loop_niter} on GIMPLE and
-@code{find_simple_exit} on RTL@. Finally, there are functions that
-provide the same information, but additionally cache it, so that
-repeated calls to number of iterations are not so costly --
-@code{number_of_latch_executions} on GIMPLE and @code{get_simple_loop_desc}
-on RTL.
-
-Note that some of these functions may behave slightly differently than
-others -- some of them return only the expression for the number of
-iterations, and fail if there are some assumptions. The function
-@code{number_of_latch_executions} works only for single-exit loops.
-The function @code{number_of_cond_exit_executions} can be used to
-determine number of executions of the exit condition of a single-exit
-loop (i.e., the @code{number_of_latch_executions} increased by one).
-
-On GIMPLE, below constraint flags affect semantics of some APIs of number
-of iterations analyzer:
-
-@itemize
-@item @code{LOOP_C_INFINITE}: If this constraint flag is set, the loop
-is known to be infinite. APIs like @code{number_of_iterations_exit} can
-return false directly without doing any analysis.
-@item @code{LOOP_C_FINITE}: If this constraint flag is set, the loop is
-known to be finite, in other words, loop's number of iterations can be
-computed with @code{assumptions} be true.
-@end itemize
-
-Generally, the constraint flags are set/cleared by consumers which are
-loop optimizers. It's also the consumers' responsibility to set/clear
-constraints correctly. Failing to do that might result in hard to track
-down bugs in scev/niter consumers. One typical use case is vectorizer:
-it drives number of iterations analyzer by setting @code{LOOP_C_FINITE}
-and vectorizes possibly infinite loop by versioning loop with analysis
-result. In return, constraints set by consumers can also help number of
-iterations analyzer in following optimizers. For example, @code{niter}
-of a loop versioned under @code{assumptions} is valid unconditionally.
-
-Other constraints may be added in the future, for example, a constraint
-indicating that loops' latch must roll thus @code{may_be_zero} would be
-false unconditionally.
-
-@node Dependency analysis
-@section Data Dependency Analysis
-@cindex Data Dependency Analysis
-
-The code for the data dependence analysis can be found in
-@file{tree-data-ref.cc} and its interface and data structures are
-described in @file{tree-data-ref.h}. The function that computes the
-data dependences for all the array and pointer references for a given
-loop is @code{compute_data_dependences_for_loop}. This function is
-currently used by the linear loop transform and the vectorization
-passes. Before calling this function, one has to allocate two vectors:
-a first vector will contain the set of data references that are
-contained in the analyzed loop body, and the second vector will contain
-the dependence relations between the data references. Thus if the
-vector of data references is of size @code{n}, the vector containing the
-dependence relations will contain @code{n*n} elements. However if the
-analyzed loop contains side effects, such as calls that potentially can
-interfere with the data references in the current analyzed loop, the
-analysis stops while scanning the loop body for data references, and
-inserts a single @code{chrec_dont_know} in the dependence relation
-array.
-
-The data references are discovered in a particular order during the
-scanning of the loop body: the loop body is analyzed in execution order,
-and the data references of each statement are pushed at the end of the
-data reference array. Two data references syntactically occur in the
-program in the same order as in the array of data references. This
-syntactic order is important in some classical data dependence tests,
-and mapping this order to the elements of this array avoids costly
-queries to the loop body representation.
-
-Three types of data references are currently handled: ARRAY_REF,
-INDIRECT_REF and COMPONENT_REF@. The data structure for the data reference
-is @code{data_reference}, where @code{data_reference_p} is a name of a
-pointer to the data reference structure. The structure contains the
-following elements:
-
-@itemize
-@item @code{base_object_info}: Provides information about the base object
-of the data reference and its access functions. These access functions
-represent the evolution of the data reference in the loop relative to
-its base, in keeping with the classical meaning of the data reference
-access function for the support of arrays. For example, for a reference
-@code{a.b[i][j]}, the base object is @code{a.b} and the access functions,
-one for each array subscript, are:
-@code{@{i_init, + i_step@}_1, @{j_init, +, j_step@}_2}.
-
-@item @code{first_location_in_loop}: Provides information about the first
-location accessed by the data reference in the loop and about the access
-function used to represent evolution relative to this location. This data
-is used to support pointers, and is not used for arrays (for which we
-have base objects). Pointer accesses are represented as a one-dimensional
-access that starts from the first location accessed in the loop. For
-example:
-
-@smallexample
- for1 i
- for2 j
- *((int *)p + i + j) = a[i][j];
-@end smallexample
-
-The access function of the pointer access is @code{@{0, + 4B@}_for2}
-relative to @code{p + i}. The access functions of the array are
-@code{@{i_init, + i_step@}_for1} and @code{@{j_init, +, j_step@}_for2}
-relative to @code{a}.
-
-Usually, the object the pointer refers to is either unknown, or we cannot
-prove that the access is confined to the boundaries of a certain object.
-
-Two data references can be compared only if at least one of these two
-representations has all its fields filled for both data references.
-
-The current strategy for data dependence tests is as follows:
-If both @code{a} and @code{b} are represented as arrays, compare
-@code{a.base_object} and @code{b.base_object};
-if they are equal, apply dependence tests (use access functions based on
-base_objects).
-Else if both @code{a} and @code{b} are represented as pointers, compare
-@code{a.first_location} and @code{b.first_location};
-if they are equal, apply dependence tests (use access functions based on
-first location).
-However, if @code{a} and @code{b} are represented differently, only try
-to prove that the bases are definitely different.
-
-@item Aliasing information.
-@item Alignment information.
-@end itemize
-
-The structure describing the relation between two data references is
-@code{data_dependence_relation} and the shorter name for a pointer to
-such a structure is @code{ddr_p}. This structure contains:
-
-@itemize
-@item a pointer to each data reference,
-@item a tree node @code{are_dependent} that is set to @code{chrec_known}
-if the analysis has proved that there is no dependence between these two
-data references, @code{chrec_dont_know} if the analysis was not able to
-determine any useful result and potentially there could exist a
-dependence between these data references, and @code{are_dependent} is
-set to @code{NULL_TREE} if there exist a dependence relation between the
-data references, and the description of this dependence relation is
-given in the @code{subscripts}, @code{dir_vects}, and @code{dist_vects}
-arrays,
-@item a boolean that determines whether the dependence relation can be
-represented by a classical distance vector,
-@item an array @code{subscripts} that contains a description of each
-subscript of the data references. Given two array accesses a
-subscript is the tuple composed of the access functions for a given
-dimension. For example, given @code{A[f1][f2][f3]} and
-@code{B[g1][g2][g3]}, there are three subscripts: @code{(f1, g1), (f2,
-g2), (f3, g3)}.
-@item two arrays @code{dir_vects} and @code{dist_vects} that contain
-classical representations of the data dependences under the form of
-direction and distance dependence vectors,
-@item an array of loops @code{loop_nest} that contains the loops to
-which the distance and direction vectors refer to.
-@end itemize
-
-Several functions for pretty printing the information extracted by the
-data dependence analysis are available: @code{dump_ddrs} prints with a
-maximum verbosity the details of a data dependence relations array,
-@code{dump_dist_dir_vectors} prints only the classical distance and
-direction vectors for a data dependence relations array, and
-@code{dump_data_references} prints the details of the data references
-contained in a data reference array.
+++ /dev/null
-@c Copyright (C) 2018-2022 Free Software Foundation, Inc.
-@c This is part of the GCC manual.
-@c For copying conditions, see the file gcc.texi.
-
-@ignore
-@c man begin COPYRIGHT
-Copyright @copyright{} 2017-2022 Free Software Foundation, Inc.
-
-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 the
-Invariant Sections being ``GNU General Public License'' and ``Funding
-Free Software'', the Front-Cover texts being (a) (see below), and with
-the Back-Cover Texts being (b) (see below). A copy of the license is
-included in the gfdl(7) man page.
-
-(a) The FSF's Front-Cover Text is:
-
- A GNU Manual
-
-(b) The FSF's Back-Cover Text is:
-
- You have freedom to copy and modify this GNU Manual, like GNU
- software. Copies published by the Free Software Foundation raise
- funds for GNU development.
-@c man end
-@c Set file name and title for the man page.
-@setfilename lto-dump
-@settitle Tool for dumping LTO object files.
-@end ignore
-
-@node lto-dump
-@chapter @command{lto-dump}---Tool for dumping LTO object files.
-
-@menu
-* lto-dump Intro:: Introduction to lto-dump.
-* Invoking lto-dump:: How to use lto-dump.
-@end menu
-
-@node lto-dump Intro
-@section Introduction to @command{lto-dump}
-@c man begin DESCRIPTION
-
-@command{lto-dump} is a tool you can use in conjunction with GCC to
-dump link time optimization object files.
-
-@c man end
-
-@node Invoking lto-dump
-@section Invoking @command{lto-dump}
-
-@smallexample
-Usage: lto-dump @r{[}@var{OPTION}@r{]} ... @var{objfiles}
-@end smallexample
-
-@command{lto-dump} accepts the following options:
-
-@ignore
-@c man begin SYNOPSIS
-lto-dump [@option{-list}]
- [@option{-demangle}]
- [@option{-defined-only}]
- [@option{-print-value}]
- [@option{-name-sort}]
- [@option{-size-sort}]
- [@option{-reverse-sort}]
- [@option{-no-sort}]
- [@option{-symbol=}]
- [@option{-objects}]
- [@option{-type-stats}]
- [@option{-tree-stats}]
- [@option{-gimple-stats}]
- [@option{-dump-level=}]
- [@option{-dump-body=}]
- [@option{-help}] @var{lto-dump}
-@c man end
-@end ignore
-
-@c man begin OPTIONS
-@table @gcctabopt
-@item -list
-Dumps list of details of functions and variables.
-
-@item -demangle
-Dump the demangled output.
-
-@item -defined-only
-Dump only the defined symbols.
-
-@item -print-value
-Dump initial values of the variables.
-
-@item -name-sort
-Sort the symbols alphabetically.
-
-@item -size-sort
-Sort the symbols according to size.
-
-@item -reverse-sort
-Dump the symbols in reverse order.
-
-@item -no-sort
-Dump the symbols in order of occurrence.
-
-@item -symbol=
-Dump the details of specific symbol.
-
-@item -objects
-Dump the details of LTO objects.
-
-@item -type-stats
-Dump the statistics of tree types.
-
-@item -tree-stats
-Dump the statistics of trees.
-
-@item -gimple-stats
-Dump the statistics of gimple statements.
-
-@item -dump-level=
-For deciding the optimization level of body.
-
-@item -dump-body=
-Dump the specific gimple body.
-
-@item -help
-Display the dump tool help.
-
-@end table
-
-@c man end
+++ /dev/null
-@c Copyright (C) 2010-2022 Free Software Foundation, Inc.
-@c This is part of the GCC manual.
-@c For copying conditions, see the file gcc.texi.
-@c Contributed by Jan Hubicka <jh@suse.cz> and
-@c Diego Novillo <dnovillo@google.com>
-
-@node LTO
-@chapter Link Time Optimization
-@cindex lto
-@cindex whopr
-@cindex wpa
-@cindex ltrans
-
-Link Time Optimization (LTO) gives GCC the capability of
-dumping its internal representation (GIMPLE) to disk,
-so that all the different compilation units that make up
-a single executable can be optimized as a single module.
-This expands the scope of inter-procedural optimizations
-to encompass the whole program (or, rather, everything
-that is visible at link time).
-
-@menu
-* LTO Overview:: Overview of LTO.
-* LTO object file layout:: LTO file sections in ELF.
-* IPA:: Using summary information in IPA passes.
-* WHOPR:: Whole program assumptions,
- linker plugin and symbol visibilities.
-* Internal flags:: Internal flags controlling @code{lto1}.
-@end menu
-
-@node LTO Overview
-@section Design Overview
-
-Link time optimization is implemented as a GCC front end for a
-bytecode representation of GIMPLE that is emitted in special sections
-of @code{.o} files. Currently, LTO support is enabled in most
-ELF-based systems, as well as darwin, cygwin and mingw systems.
-
-By default, object files generated with LTO support contain only GIMPLE
-bytecode. Such objects are called ``slim'', and they require that
-tools like @code{ar} and @code{nm} understand symbol tables of LTO
-sections. For most targets these tools have been extended to use the
-plugin infrastructure, so GCC can support ``slim'' objects consisting
-of the intermediate code alone.
-
-GIMPLE bytecode could also be saved alongside final object code if
-the @option{-ffat-lto-objects} option is passed, or if no plugin support
-is detected for @code{ar} and @code{nm} when GCC is configured. It makes
-the object files generated with LTO support larger than regular object
-files. This ``fat'' object format allows to ship one set of fat
-objects which could be used both for development and the production of
-optimized builds. A, perhaps surprising, side effect of this feature
-is that any mistake in the toolchain leads to LTO information not
-being used (e.g.@: an older @code{libtool} calling @code{ld} directly).
-This is both an advantage, as the system is more robust, and a
-disadvantage, as the user is not informed that the optimization has
-been disabled.
-
-At the highest level, LTO splits the compiler in two. The first half
-(the ``writer'') produces a streaming representation of all the
-internal data structures needed to optimize and generate code. This
-includes declarations, types, the callgraph and the GIMPLE representation
-of function bodies.
-
-When @option{-flto} is given during compilation of a source file, the
-pass manager executes all the passes in @code{all_lto_gen_passes}.
-Currently, this phase is composed of two IPA passes:
-
-@itemize @bullet
-@item @code{pass_ipa_lto_gimple_out}
-This pass executes the function @code{lto_output} in
-@file{lto-streamer-out.cc}, which traverses the call graph encoding
-every reachable declaration, type and function. This generates a
-memory representation of all the file sections described below.
-
-@item @code{pass_ipa_lto_finish_out}
-This pass executes the function @code{produce_asm_for_decls} in
-@file{lto-streamer-out.cc}, which takes the memory image built in the
-previous pass and encodes it in the corresponding ELF file sections.
-@end itemize
-
-The second half of LTO support is the ``reader''. This is implemented
-as the GCC front end @file{lto1} in @file{lto/lto.cc}. When
-@file{collect2} detects a link set of @code{.o}/@code{.a} files with
-LTO information and the @option{-flto} is enabled, it invokes
-@file{lto1} which reads the set of files and aggregates them into a
-single translation unit for optimization. The main entry point for
-the reader is @file{lto/lto.cc}:@code{lto_main}.
-
-@subsection LTO modes of operation
-
-One of the main goals of the GCC link-time infrastructure was to allow
-effective compilation of large programs. For this reason GCC implements two
-link-time compilation modes.
-
-@enumerate
-@item @emph{LTO mode}, in which the whole program is read into the
-compiler at link-time and optimized in a similar way as if it
-were a single source-level compilation unit.
-
-@item @emph{WHOPR or partitioned mode}, designed to utilize multiple
-CPUs and/or a distributed compilation environment to quickly link
-large applications. WHOPR stands for WHOle Program optimizeR (not to
-be confused with the semantics of @option{-fwhole-program}). It
-partitions the aggregated callgraph from many different @code{.o}
-files and distributes the compilation of the sub-graphs to different
-CPUs.
-
-Note that distributed compilation is not implemented yet, but since
-the parallelism is facilitated via generating a @code{Makefile}, it
-would be easy to implement.
-@end enumerate
-
-WHOPR splits LTO into three main stages:
-@enumerate
-@item Local generation (LGEN)
-This stage executes in parallel. Every file in the program is compiled
-into the intermediate language and packaged together with the local
-call-graph and summary information. This stage is the same for both
-the LTO and WHOPR compilation mode.
-
-@item Whole Program Analysis (WPA)
-WPA is performed sequentially. The global call-graph is generated, and
-a global analysis procedure makes transformation decisions. The global
-call-graph is partitioned to facilitate parallel optimization during
-phase 3. The results of the WPA stage are stored into new object files
-which contain the partitions of program expressed in the intermediate
-language and the optimization decisions.
-
-@item Local transformations (LTRANS)
-This stage executes in parallel. All the decisions made during phase 2
-are implemented locally in each partitioned object file, and the final
-object code is generated. Optimizations which cannot be decided
-efficiently during the phase 2 may be performed on the local
-call-graph partitions.
-@end enumerate
-
-WHOPR can be seen as an extension of the usual LTO mode of
-compilation. In LTO, WPA and LTRANS are executed within a single
-execution of the compiler, after the whole program has been read into
-memory.
-
-When compiling in WHOPR mode, the callgraph is partitioned during
-the WPA stage. The whole program is split into a given number of
-partitions of roughly the same size. The compiler tries to
-minimize the number of references which cross partition boundaries.
-The main advantage of WHOPR is to allow the parallel execution of
-LTRANS stages, which are the most time-consuming part of the
-compilation process. Additionally, it avoids the need to load the
-whole program into memory.
-
-
-@node LTO object file layout
-@section LTO file sections
-
-LTO information is stored in several ELF sections inside object files.
-Data structures and enum codes for sections are defined in
-@file{lto-streamer.h}.
-
-These sections are emitted from @file{lto-streamer-out.cc} and mapped
-in all at once from @file{lto/lto.cc}:@code{lto_file_read}. The
-individual functions dealing with the reading/writing of each section
-are described below.
-
-@itemize @bullet
-@item Command line options (@code{.gnu.lto_.opts})
-
-This section contains the command line options used to generate the
-object files. This is used at link time to determine the optimization
-level and other settings when they are not explicitly specified at the
-linker command line.
-
-Currently, GCC does not support combining LTO object files compiled
-with different set of the command line options into a single binary.
-At link time, the options given on the command line and the options
-saved on all the files in a link-time set are applied globally. No
-attempt is made at validating the combination of flags (other than the
-usual validation done by option processing). This is implemented in
-@file{lto/lto.cc}:@code{lto_read_all_file_options}.
-
-
-@item Symbol table (@code{.gnu.lto_.symtab})
-
-This table replaces the ELF symbol table for functions and variables
-represented in the LTO IL. Symbols used and exported by the optimized
-assembly code of ``fat'' objects might not match the ones used and
-exported by the intermediate code. This table is necessary because
-the intermediate code is less optimized and thus requires a separate
-symbol table.
-
-Additionally, the binary code in the ``fat'' object will lack a call
-to a function, since the call was optimized out at compilation time
-after the intermediate language was streamed out. In some special
-cases, the same optimization may not happen during link-time
-optimization. This would lead to an undefined symbol if only one
-symbol table was used.
-
-The symbol table is emitted in
-@file{lto-streamer-out.cc}:@code{produce_symtab}.
-
-
-@item Global declarations and types (@code{.gnu.lto_.decls})
-
-This section contains an intermediate language dump of all
-declarations and types required to represent the callgraph, static
-variables and top-level debug info.
-
-The contents of this section are emitted in
-@file{lto-streamer-out.cc}:@code{produce_asm_for_decls}. Types and
-symbols are emitted in a topological order that preserves the sharing
-of pointers when the file is read back in
-(@file{lto.cc}:@code{read_cgraph_and_symbols}).
-
-
-@item The callgraph (@code{.gnu.lto_.cgraph})
-
-This section contains the basic data structure used by the GCC
-inter-procedural optimization infrastructure. This section stores an
-annotated multi-graph which represents the functions and call sites as
-well as the variables, aliases and top-level @code{asm} statements.
-
-This section is emitted in
-@file{lto-streamer-out.cc}:@code{output_cgraph} and read in
-@file{lto-cgraph.cc}:@code{input_cgraph}.
-
-
-@item IPA references (@code{.gnu.lto_.refs})
-
-This section contains references between function and static
-variables. It is emitted by @file{lto-cgraph.cc}:@code{output_refs}
-and read by @file{lto-cgraph.cc}:@code{input_refs}.
-
-
-@item Function bodies (@code{.gnu.lto_.function_body.<name>})
-
-This section contains function bodies in the intermediate language
-representation. Every function body is in a separate section to allow
-copying of the section independently to different object files or
-reading the function on demand.
-
-Functions are emitted in
-@file{lto-streamer-out.cc}:@code{output_function} and read in
-@file{lto-streamer-in.cc}:@code{input_function}.
-
-
-@item Static variable initializers (@code{.gnu.lto_.vars})
-
-This section contains all the symbols in the global variable pool. It
-is emitted by @file{lto-cgraph.cc}:@code{output_varpool} and read in
-@file{lto-cgraph.cc}:@code{input_cgraph}.
-
-@item Summaries and optimization summaries used by IPA passes
-(@code{.gnu.lto_.<xxx>}, where @code{<xxx>} is one of @code{jmpfuncs},
-@code{pureconst} or @code{reference})
-
-These sections are used by IPA passes that need to emit summary
-information during LTO generation to be read and aggregated at
-link time. Each pass is responsible for implementing two pass manager
-hooks: one for writing the summary and another for reading it in. The
-format of these sections is entirely up to each individual pass. The
-only requirement is that the writer and reader hooks agree on the
-format.
-@end itemize
-
-
-@node IPA
-@section Using summary information in IPA passes
-
-Programs are represented internally as a @emph{callgraph} (a
-multi-graph where nodes are functions and edges are call sites)
-and a @emph{varpool} (a list of static and external variables in
-the program).
-
-The inter-procedural optimization is organized as a sequence of
-individual passes, which operate on the callgraph and the
-varpool. To make the implementation of WHOPR possible, every
-inter-procedural optimization pass is split into several stages
-that are executed at different times during WHOPR compilation:
-
-@itemize @bullet
-@item LGEN time
-@enumerate
-@item @emph{Generate summary} (@code{generate_summary} in
-@code{struct ipa_opt_pass_d}). This stage analyzes every function
-body and variable initializer is examined and stores relevant
-information into a pass-specific data structure.
-
-@item @emph{Write summary} (@code{write_summary} in
-@code{struct ipa_opt_pass_d}). This stage writes all the
-pass-specific information generated by @code{generate_summary}.
-Summaries go into their own @code{LTO_section_*} sections that
-have to be declared in @file{lto-streamer.h}:@code{enum
-lto_section_type}. A new section is created by calling
-@code{create_output_block} and data can be written using the
-@code{lto_output_*} routines.
-@end enumerate
-
-@item WPA time
-@enumerate
-@item @emph{Read summary} (@code{read_summary} in
-@code{struct ipa_opt_pass_d}). This stage reads all the
-pass-specific information in exactly the same order that it was
-written by @code{write_summary}.
-
-@item @emph{Execute} (@code{execute} in @code{struct
-opt_pass}). This performs inter-procedural propagation. This
-must be done without actual access to the individual function
-bodies or variable initializers. Typically, this results in a
-transitive closure operation over the summary information of all
-the nodes in the callgraph.
-
-@item @emph{Write optimization summary}
-(@code{write_optimization_summary} in @code{struct
-ipa_opt_pass_d}). This writes the result of the inter-procedural
-propagation into the object file. This can use the same data
-structures and helper routines used in @code{write_summary}.
-@end enumerate
-
-@item LTRANS time
-@enumerate
-@item @emph{Read optimization summary}
-(@code{read_optimization_summary} in @code{struct
-ipa_opt_pass_d}). The counterpart to
-@code{write_optimization_summary}. This reads the interprocedural
-optimization decisions in exactly the same format emitted by
-@code{write_optimization_summary}.
-
-@item @emph{Transform} (@code{function_transform} and
-@code{variable_transform} in @code{struct ipa_opt_pass_d}).
-The actual function bodies and variable initializers are updated
-based on the information passed down from the @emph{Execute} stage.
-@end enumerate
-@end itemize
-
-The implementation of the inter-procedural passes are shared
-between LTO, WHOPR and classic non-LTO compilation.
-
-@itemize
-@item During the traditional file-by-file mode every pass executes its
-own @emph{Generate summary}, @emph{Execute}, and @emph{Transform}
-stages within the single execution context of the compiler.
-
-@item In LTO compilation mode, every pass uses @emph{Generate
-summary} and @emph{Write summary} stages at compilation time,
-while the @emph{Read summary}, @emph{Execute}, and
-@emph{Transform} stages are executed at link time.
-
-@item In WHOPR mode all stages are used.
-@end itemize
-
-To simplify development, the GCC pass manager differentiates
-between normal inter-procedural passes (@pxref{Regular IPA passes}),
-small inter-procedural passes (@pxref{Small IPA passes})
-and late inter-procedural passes (@pxref{Late IPA passes}).
-A small or late IPA pass (@code{SIMPLE_IPA_PASS}) does
-everything at once and thus cannot be executed during WPA in
-WHOPR mode. It defines only the @emph{Execute} stage and during
-this stage it accesses and modifies the function bodies. Such
-passes are useful for optimization at LGEN or LTRANS time and are
-used, for example, to implement early optimization before writing
-object files. The simple inter-procedural passes can also be used
-for easier prototyping and development of a new inter-procedural
-pass.
-
-
-@subsection Virtual clones
-
-One of the main challenges of introducing the WHOPR compilation
-mode was addressing the interactions between optimization passes.
-In LTO compilation mode, the passes are executed in a sequence,
-each of which consists of analysis (or @emph{Generate summary}),
-propagation (or @emph{Execute}) and @emph{Transform} stages.
-Once the work of one pass is finished, the next pass sees the
-updated program representation and can execute. This makes the
-individual passes dependent on each other.
-
-In WHOPR mode all passes first execute their @emph{Generate
-summary} stage. Then summary writing marks the end of the LGEN
-stage. At WPA time,
-the summaries are read back into memory and all passes run the
-@emph{Execute} stage. Optimization summaries are streamed and
-sent to LTRANS, where all the passes execute the @emph{Transform}
-stage.
-
-Most optimization passes split naturally into analysis,
-propagation and transformation stages. But some do not. The
-main problem arises when one pass performs changes and the
-following pass gets confused by seeing different callgraphs
-between the @emph{Transform} stage and the @emph{Generate summary}
-or @emph{Execute} stage. This means that the passes are required
-to communicate their decisions with each other.
-
-To facilitate this communication, the GCC callgraph
-infrastructure implements @emph{virtual clones}, a method of
-representing the changes performed by the optimization passes in
-the callgraph without needing to update function bodies.
-
-A @emph{virtual clone} in the callgraph is a function that has no
-associated body, just a description of how to create its body based
-on a different function (which itself may be a virtual clone).
-
-The description of function modifications includes adjustments to
-the function's signature (which allows, for example, removing or
-adding function arguments), substitutions to perform on the
-function body, and, for inlined functions, a pointer to the
-function that it will be inlined into.
-
-It is also possible to redirect any edge of the callgraph from a
-function to its virtual clone. This implies updating of the call
-site to adjust for the new function signature.
-
-Most of the transformations performed by inter-procedural
-optimizations can be represented via virtual clones. For
-instance, a constant propagation pass can produce a virtual clone
-of the function which replaces one of its arguments by a
-constant. The inliner can represent its decisions by producing a
-clone of a function whose body will be later integrated into
-a given function.
-
-Using @emph{virtual clones}, the program can be easily updated
-during the @emph{Execute} stage, solving most of pass interactions
-problems that would otherwise occur during @emph{Transform}.
-
-Virtual clones are later materialized in the LTRANS stage and
-turned into real functions. Passes executed after the virtual
-clone were introduced also perform their @emph{Transform} stage
-on new functions, so for a pass there is no significant
-difference between operating on a real function or a virtual
-clone introduced before its @emph{Execute} stage.
-
-Optimization passes then work on virtual clones introduced before
-their @emph{Execute} stage as if they were real functions. The
-only difference is that clones are not visible during the
-@emph{Generate Summary} stage.
-
-To keep function summaries updated, the callgraph interface
-allows an optimizer to register a callback that is called every
-time a new clone is introduced as well as when the actual
-function or variable is generated or when a function or variable
-is removed. These hooks are registered in the @emph{Generate
-summary} stage and allow the pass to keep its information intact
-until the @emph{Execute} stage. The same hooks can also be
-registered during the @emph{Execute} stage to keep the
-optimization summaries updated for the @emph{Transform} stage.
-
-@subsection IPA references
-
-GCC represents IPA references in the callgraph. For a function
-or variable @code{A}, the @emph{IPA reference} is a list of all
-locations where the address of @code{A} is taken and, when
-@code{A} is a variable, a list of all direct stores and reads
-to/from @code{A}. References represent an oriented multi-graph on
-the union of nodes of the callgraph and the varpool. See
-@file{ipa-reference.cc}:@code{ipa_reference_write_optimization_summary}
-and
-@file{ipa-reference.cc}:@code{ipa_reference_read_optimization_summary}
-for details.
-
-@subsection Jump functions
-Suppose that an optimization pass sees a function @code{A} and it
-knows the values of (some of) its arguments. The @emph{jump
-function} describes the value of a parameter of a given function
-call in function @code{A} based on this knowledge.
-
-Jump functions are used by several optimizations, such as the
-inter-procedural constant propagation pass and the
-devirtualization pass. The inliner also uses jump functions to
-perform inlining of callbacks.
-
-@node WHOPR
-@section Whole program assumptions, linker plugin and symbol visibilities
-
-Link-time optimization gives relatively minor benefits when used
-alone. The problem is that propagation of inter-procedural
-information does not work well across functions and variables
-that are called or referenced by other compilation units (such as
-from a dynamically linked library). We say that such functions
-and variables are @emph{externally visible}.
-
-To make the situation even more difficult, many applications
-organize themselves as a set of shared libraries, and the default
-ELF visibility rules allow one to overwrite any externally
-visible symbol with a different symbol at runtime. This
-basically disables any optimizations across such functions and
-variables, because the compiler cannot be sure that the function
-body it is seeing is the same function body that will be used at
-runtime. Any function or variable not declared @code{static} in
-the sources degrades the quality of inter-procedural
-optimization.
-
-To avoid this problem the compiler must assume that it sees the
-whole program when doing link-time optimization. Strictly
-speaking, the whole program is rarely visible even at link-time.
-Standard system libraries are usually linked dynamically or not
-provided with the link-time information. In GCC, the whole
-program option (@option{-fwhole-program}) asserts that every
-function and variable defined in the current compilation
-unit is static, except for function @code{main} (note: at
-link time, the current unit is the union of all objects compiled
-with LTO). Since some functions and variables need to
-be referenced externally, for example by another DSO or from an
-assembler file, GCC also provides the function and variable
-attribute @code{externally_visible} which can be used to disable
-the effect of @option{-fwhole-program} on a specific symbol.
-
-The whole program mode assumptions are slightly more complex in
-C++, where inline functions in headers are put into @emph{COMDAT}
-sections. COMDAT function and variables can be defined by
-multiple object files and their bodies are unified at link-time
-and dynamic link-time. COMDAT functions are changed to local only
-when their address is not taken and thus un-sharing them with a
-library is not harmful. COMDAT variables always remain externally
-visible, however for readonly variables it is assumed that their
-initializers cannot be overwritten by a different value.
-
-GCC provides the function and variable attribute
-@code{visibility} that can be used to specify the visibility of
-externally visible symbols (or alternatively an
-@option{-fdefault-visibility} command line option). ELF defines
-the @code{default}, @code{protected}, @code{hidden} and
-@code{internal} visibilities.
-
-The most commonly used is visibility is @code{hidden}. It
-specifies that the symbol cannot be referenced from outside of
-the current shared library. Unfortunately, this information
-cannot be used directly by the link-time optimization in the
-compiler since the whole shared library also might contain
-non-LTO objects and those are not visible to the compiler.
-
-GCC solves this problem using linker plugins. A @emph{linker
-plugin} is an interface to the linker that allows an external
-program to claim the ownership of a given object file. The linker
-then performs the linking procedure by querying the plugin about
-the symbol table of the claimed objects and once the linking
-decisions are complete, the plugin is allowed to provide the
-final object file before the actual linking is made. The linker
-plugin obtains the symbol resolution information which specifies
-which symbols provided by the claimed objects are bound from the
-rest of a binary being linked.
-
-GCC is designed to be independent of the rest of the toolchain
-and aims to support linkers without plugin support. For this
-reason it does not use the linker plugin by default. Instead,
-the object files are examined by @command{collect2} before being
-passed to the linker and objects found to have LTO sections are
-passed to @command{lto1} first. This mode does not work for
-library archives. The decision on what object files from the
-archive are needed depends on the actual linking and thus GCC
-would have to implement the linker itself. The resolution
-information is missing too and thus GCC needs to make an educated
-guess based on @option{-fwhole-program}. Without the linker
-plugin GCC also assumes that symbols are declared @code{hidden}
-and not referred by non-LTO code by default.
-
-@node Internal flags
-@section Internal flags controlling @code{lto1}
-
-The following flags are passed into @command{lto1} and are not
-meant to be used directly from the command line.
-
-@itemize
-@item -fwpa
-@opindex fwpa
-This option runs the serial part of the link-time optimizer
-performing the inter-procedural propagation (WPA mode). The
-compiler reads in summary information from all inputs and
-performs an analysis based on summary information only. It
-generates object files for subsequent runs of the link-time
-optimizer where individual object files are optimized using both
-summary information from the WPA mode and the actual function
-bodies. It then drives the LTRANS phase.
-
-@item -fltrans
-@opindex fltrans
-This option runs the link-time optimizer in the
-local-transformation (LTRANS) mode, which reads in output from a
-previous run of the LTO in WPA mode. In the LTRANS mode, LTO
-optimizes an object and produces the final assembly.
-
-@item -fltrans-output-list=@var{file}
-@opindex fltrans-output-list
-This option specifies a file to which the names of LTRANS output
-files are written. This option is only meaningful in conjunction
-with @option{-fwpa}.
-
-@item -fresolution=@var{file}
-@opindex fresolution
-This option specifies the linker resolution file. This option is
-only meaningful in conjunction with @option{-fwpa} and as option
-to pass through to the LTO linker plugin.
-@end itemize
+++ /dev/null
-@c Copyright (C) 2001-2022 Free Software Foundation, Inc.
-@c This is part of the GCC manual.
-@c For copying conditions, see the file gcc.texi.
-
-@node Makefile
-@subsection Makefile Targets
-@cindex makefile targets
-@cindex targets, makefile
-
-These targets are available from the @samp{gcc} directory:
-
-@table @code
-@item all
-This is the default target. Depending on what your build/host/target
-configuration is, it coordinates all the things that need to be built.
-
-@item doc
-Produce info-formatted documentation and man pages. Essentially it
-calls @samp{make man} and @samp{make info}.
-
-@item dvi
-Produce DVI-formatted documentation.
-
-@item pdf
-Produce PDF-formatted documentation.
-
-@item html
-Produce HTML-formatted documentation.
-
-@item man
-Generate man pages.
-
-@item info
-Generate info-formatted pages.
-
-@item mostlyclean
-Delete the files made while building the compiler.
-
-@item clean
-That, and all the other files built by @samp{make all}.
-
-@item distclean
-That, and all the files created by @command{configure}.
-
-@item maintainer-clean
-Distclean plus any file that can be generated from other files. Note
-that additional tools may be required beyond what is normally needed to
-build GCC.
-
-@item srcextra
-Generates files in the source directory that are not version-controlled but
-should go into a release tarball.
-
-@item srcinfo
-@itemx srcman
-Copies the info-formatted and manpage documentation into the source
-directory usually for the purpose of generating a release tarball.
-
-@item install
-Installs GCC.
-
-@item uninstall
-Deletes installed files, though this is not supported.
-
-@item check
-Run the testsuite. This creates a @file{testsuite} subdirectory that
-has various @file{.sum} and @file{.log} files containing the results of
-the testing. You can run subsets with, for example, @samp{make check-gcc}.
-You can specify specific tests by setting @env{RUNTESTFLAGS} to be the name
-of the @file{.exp} file, optionally followed by (for some tests) an equals
-and a file wildcard, like:
-
-@smallexample
-make check-gcc RUNTESTFLAGS="execute.exp=19980413-*"
-@end smallexample
-
-Note that running the testsuite may require additional tools be
-installed, such as Tcl or DejaGnu.
-@end table
-
-The toplevel tree from which you start GCC compilation is not
-the GCC directory, but rather a complex Makefile that coordinates
-the various steps of the build, including bootstrapping the compiler
-and using the new compiler to build target libraries.
-
-When GCC is configured for a native configuration, the default action
-for @command{make} is to do a full three-stage bootstrap. This means
-that GCC is built three times---once with the native compiler, once with
-the native-built compiler it just built, and once with the compiler it
-built the second time. In theory, the last two should produce the same
-results, which @samp{make compare} can check. Each stage is configured
-separately and compiled into a separate directory, to minimize problems
-due to ABI incompatibilities between the native compiler and GCC.
-
-If you do a change, rebuilding will also start from the first stage
-and ``bubble'' up the change through the three stages. Each stage
-is taken from its build directory (if it had been built previously),
-rebuilt, and copied to its subdirectory. This will allow you to, for
-example, continue a bootstrap after fixing a bug which causes the
-stage2 build to crash. It does not provide as good coverage of the
-compiler as bootstrapping from scratch, but it ensures that the new
-code is syntactically correct (e.g., that you did not use GCC extensions
-by mistake), and avoids spurious bootstrap comparison
-failures@footnote{Except if the compiler was buggy and miscompiled
-some of the files that were not modified. In this case, it's best
-to use @command{make restrap}.}.
-
-Other targets available from the top level include:
-
-@table @code
-@item bootstrap-lean
-Like @code{bootstrap}, except that the various stages are removed once
-they're no longer needed. This saves disk space.
-
-@item bootstrap2
-@itemx bootstrap2-lean
-Performs only the first two stages of bootstrap. Unlike a three-stage
-bootstrap, this does not perform a comparison to test that the compiler
-is running properly. Note that the disk space required by a ``lean''
-bootstrap is approximately independent of the number of stages.
-
-@item stage@var{N}-bubble (@var{N} = 1@dots{}4, profile, feedback)
-Rebuild all the stages up to @var{N}, with the appropriate flags,
-``bubbling'' the changes as described above.
-
-@item all-stage@var{N} (@var{N} = 1@dots{}4, profile, feedback)
-Assuming that stage @var{N} has already been built, rebuild it with the
-appropriate flags. This is rarely needed.
-
-@item cleanstrap
-Remove everything (@samp{make clean}) and rebuilds (@samp{make bootstrap}).
-
-@item compare
-Compares the results of stages 2 and 3. This ensures that the compiler
-is running properly, since it should produce the same object files
-regardless of how it itself was compiled.
-
-@item distclean-stage@var{N} (@var{N} = 1@dots{}4, profile, feedback)
-Wipe stage @var{N} and all the following ones.
-
-For example,
-@samp{make distclean-stage3} wipes stage 3 and all the following ones,
-so that another @command{make} then rebuilds them from scratch.
-This can be useful if you're doing changes where
-``bubbling'' the changes as described above is not sufficient,
-but a full @command{make restrap} isn't necessary either.
-
-@item profiledbootstrap
-Builds a compiler with profiling feedback information. In this case,
-the second and third stages are named @samp{profile} and @samp{feedback},
-respectively. For more information, see the installation instructions.
-
-@item restrap
-Restart a bootstrap, so that everything that was not built with
-the system compiler is rebuilt.
-
-@item stage@var{N}-start (@var{N} = 1@dots{}4, profile, feedback)
-For each package that is bootstrapped, rename directories so that,
-for example, @file{gcc} points to the stage@var{N} GCC, compiled
-with the stage@var{N-1} GCC@footnote{Customarily, the system compiler
-is also termed the @file{stage0} GCC.}.
-
-You will invoke this target if you need to test or debug the
-stage@var{N} GCC@. If you only need to execute GCC (but you need
-not run @samp{make} either to rebuild it or to run test suites),
-you should be able to work directly in the @file{stage@var{N}-gcc}
-directory. This makes it easier to debug multiple stages in
-parallel.
-
-@item stage
-For each package that is bootstrapped, relocate its build directory
-to indicate its stage. For example, if the @file{gcc} directory
-points to the stage2 GCC, after invoking this target it will be
-renamed to @file{stage2-gcc}.
-
-@end table
-
-If you wish to use non-default GCC flags when compiling the stage2 and
-stage3 compilers, set @code{BOOT_CFLAGS} on the command line when doing
-@samp{make}.
-
-Usually, the first stage only builds the languages that the compiler
-is written in: typically, C and maybe Ada. If you are debugging a
-miscompilation of a different stage2 front-end (for example, of the
-Fortran front-end), you may want to have front-ends for other languages
-in the first stage as well. To do so, set @code{STAGE1_LANGUAGES}
-on the command line when doing @samp{make}.
-
-For example, in the aforementioned scenario of debugging a Fortran
-front-end miscompilation caused by the stage1 compiler, you may need a
-command like
-
-@example
-make stage2-bubble STAGE1_LANGUAGES=c,fortran
-@end example
-
-Alternatively, you can use per-language targets to build and test
-languages that are not enabled by default in stage1. For example,
-@command{make f951} will build a Fortran compiler even in the stage1
-build directory.
-
+++ /dev/null
-@c Copyright (C) 2014-2022 Free Software Foundation, Inc.
-@c Free Software Foundation, Inc.
-@c This is part of the GCC manual.
-@c For copying conditions, see the file gcc.texi.
-
-@node Match and Simplify
-@chapter Match and Simplify
-@cindex Match and Simplify
-
-The GIMPLE and GENERIC pattern matching project match-and-simplify
-tries to address several issues.
-
-@enumerate
-@item unify expression simplifications currently spread and duplicated
- over separate files like fold-const.cc, gimple-fold.cc and builtins.cc
-@item allow for a cheap way to implement building and simplifying
- non-trivial GIMPLE expressions, avoiding the need to go through
- building and simplifying GENERIC via fold_buildN and then
- gimplifying via force_gimple_operand
-@end enumerate
-
-To address these the project introduces a simple domain-specific language
-to write expression simplifications from which code targeting GIMPLE
-and GENERIC is auto-generated. The GENERIC variant follows the
-fold_buildN API while for the GIMPLE variant and to address 2) new
-APIs are introduced.
-
-@menu
-* GIMPLE API::
-* The Language::
-@end menu
-
-@node GIMPLE API
-@section GIMPLE API
-@cindex GIMPLE API
-
-@deftypefn {GIMPLE function} tree gimple_simplify (enum tree_code, tree, tree, gimple_seq *, tree (*)(tree))
-@deftypefnx {GIMPLE function} tree gimple_simplify (enum tree_code, tree, tree, tree, gimple_seq *, tree (*)(tree))
-@deftypefnx {GIMPLE function} tree gimple_simplify (enum tree_code, tree, tree, tree, tree, gimple_seq *, tree (*)(tree))
-@deftypefnx {GIMPLE function} tree gimple_simplify (enum built_in_function, tree, tree, gimple_seq *, tree (*)(tree))
-@deftypefnx {GIMPLE function} tree gimple_simplify (enum built_in_function, tree, tree, tree, gimple_seq *, tree (*)(tree))
-@deftypefnx {GIMPLE function} tree gimple_simplify (enum built_in_function, tree, tree, tree, tree, gimple_seq *, tree (*)(tree))
-The main GIMPLE API entry to the expression simplifications mimicking
-that of the GENERIC fold_@{unary,binary,ternary@} functions.
-@end deftypefn
-
-thus providing n-ary overloads for operation or function. The
-additional arguments are a gimple_seq where built statements are
-inserted on (if @code{NULL} then simplifications requiring new statements
-are not performed) and a valueization hook that can be used to
-tie simplifications to a SSA lattice.
-
-In addition to those APIs @code{fold_stmt} is overloaded with
-a valueization hook:
-
-@deftypefn bool fold_stmt (gimple_stmt_iterator *, tree (*)(tree));
-@end deftypefn
-
-
-On top of these a @code{fold_buildN}-like API for GIMPLE is introduced:
-
-@deftypefn {GIMPLE function} tree gimple_build (gimple_seq *, location_t, enum tree_code, tree, tree, tree (*valueize) (tree) = NULL);
-@deftypefnx {GIMPLE function} tree gimple_build (gimple_seq *, location_t, enum tree_code, tree, tree, tree, tree (*valueize) (tree) = NULL);
-@deftypefnx {GIMPLE function} tree gimple_build (gimple_seq *, location_t, enum tree_code, tree, tree, tree, tree, tree (*valueize) (tree) = NULL);
-@deftypefnx {GIMPLE function} tree gimple_build (gimple_seq *, location_t, enum built_in_function, tree, tree, tree (*valueize) (tree) = NULL);
-@deftypefnx {GIMPLE function} tree gimple_build (gimple_seq *, location_t, enum built_in_function, tree, tree, tree, tree (*valueize) (tree) = NULL);
-@deftypefnx {GIMPLE function} tree gimple_build (gimple_seq *, location_t, enum built_in_function, tree, tree, tree, tree, tree (*valueize) (tree) = NULL);
-@deftypefnx {GIMPLE function} tree gimple_convert (gimple_seq *, location_t, tree, tree);
-@end deftypefn
-
-which is supposed to replace @code{force_gimple_operand (fold_buildN (...), ...)}
-and calls to @code{fold_convert}. Overloads without the @code{location_t}
-argument exist. Built statements are inserted on the provided sequence
-and simplification is performed using the optional valueization hook.
-
-
-@node The Language
-@section The Language
-@cindex The Language
-
-The language in which to write expression simplifications resembles
-other domain-specific languages GCC uses. Thus it is lispy. Let's
-start with an example from the match.pd file:
-
-@smallexample
-(simplify
- (bit_and @@0 integer_all_onesp)
- @@0)
-@end smallexample
-
-This example contains all required parts of an expression simplification.
-A simplification is wrapped inside a @code{(simplify ...)} expression.
-That contains at least two operands - an expression that is matched
-with the GIMPLE or GENERIC IL and a replacement expression that is
-returned if the match was successful.
-
-Expressions have an operator ID, @code{bit_and} in this case. Expressions can
-be lower-case tree codes with @code{_expr} stripped off or builtin
-function code names in all-caps, like @code{BUILT_IN_SQRT}.
-
-@code{@@n} denotes a so-called capture. It captures the operand and lets
-you refer to it in other places of the match-and-simplify. In the
-above example it is referred to in the replacement expression. Captures
-are @code{@@} followed by a number or an identifier.
-
-@smallexample
-(simplify
- (bit_xor @@0 @@0)
- @{ build_zero_cst (type); @})
-@end smallexample
-
-In this example @code{@@0} is mentioned twice which constrains the matched
-expression to have two equal operands. Usually matches are constrained
-to equal types. If operands may be constants and conversions are involved,
-matching by value might be preferred in which case use @code{@@@@0} to
-denote a by-value match and the specific operand you want to refer to
-in the result part. This example also introduces
-operands written in C code. These can be used in the expression
-replacements and are supposed to evaluate to a tree node which has to
-be a valid GIMPLE operand (so you cannot generate expressions in C code).
-
-@smallexample
-(simplify
- (trunc_mod integer_zerop@@0 @@1)
- (if (!integer_zerop (@@1))
- @@0))
-@end smallexample
-
-Here @code{@@0} captures the first operand of the trunc_mod expression
-which is also predicated with @code{integer_zerop}. Expression operands
-may be either expressions, predicates or captures. Captures
-can be unconstrained or capture expressions or predicates.
-
-This example introduces an optional operand of simplify,
-the if-expression. This condition is evaluated after the
-expression matched in the IL and is required to evaluate to true
-to enable the replacement expression in the second operand
-position. The expression operand of the @code{if} is a standard C
-expression which may contain references to captures. The @code{if}
-has an optional third operand which may contain the replacement
-expression that is enabled when the condition evaluates to false.
-
-A @code{if} expression can be used to specify a common condition
-for multiple simplify patterns, avoiding the need
-to repeat that multiple times:
-
-@smallexample
-(if (!TYPE_SATURATING (type)
- && !FLOAT_TYPE_P (type) && !FIXED_POINT_TYPE_P (type))
- (simplify
- (minus (plus @@0 @@1) @@0)
- @@1)
- (simplify
- (minus (minus @@0 @@1) @@0)
- (negate @@1)))
-@end smallexample
-
-Note that @code{if}s in outer position do not have the optional
-else clause but instead have multiple then clauses.
-
-Ifs can be nested.
-
-There exists a @code{switch} expression which can be used to
-chain conditions avoiding nesting @code{if}s too much:
-
-@smallexample
-(simplify
- (simple_comparison @@0 REAL_CST@@1)
- (switch
- /* a CMP (-0) -> a CMP 0 */
- (if (REAL_VALUE_MINUS_ZERO (TREE_REAL_CST (@@1)))
- (cmp @@0 @{ build_real (TREE_TYPE (@@1), dconst0); @}))
- /* x != NaN is always true, other ops are always false. */
- (if (REAL_VALUE_ISNAN (TREE_REAL_CST (@@1))
- && ! HONOR_SNANS (@@1))
- @{ constant_boolean_node (cmp == NE_EXPR, type); @})))
-@end smallexample
-
-Is equal to
-
-@smallexample
-(simplify
- (simple_comparison @@0 REAL_CST@@1)
- (switch
- /* a CMP (-0) -> a CMP 0 */
- (if (REAL_VALUE_MINUS_ZERO (TREE_REAL_CST (@@1)))
- (cmp @@0 @{ build_real (TREE_TYPE (@@1), dconst0); @})
- /* x != NaN is always true, other ops are always false. */
- (if (REAL_VALUE_ISNAN (TREE_REAL_CST (@@1))
- && ! HONOR_SNANS (@@1))
- @{ constant_boolean_node (cmp == NE_EXPR, type); @}))))
-@end smallexample
-
-which has the second @code{if} in the else operand of the first.
-The @code{switch} expression takes @code{if} expressions as
-operands (which may not have else clauses) and as a last operand
-a replacement expression which should be enabled by default if
-no other condition evaluated to true.
-
-Captures can also be used for capturing results of sub-expressions.
-
-@smallexample
-#if GIMPLE
-(simplify
- (pointer_plus (addr@@2 @@0) INTEGER_CST_P@@1)
- (if (is_gimple_min_invariant (@@2)))
- @{
- poly_int64 off;
- tree base = get_addr_base_and_unit_offset (@@0, &off);
- off += tree_to_uhwi (@@1);
- /* Now with that we should be able to simply write
- (addr (mem_ref (addr @@base) (plus @@off @@1))) */
- build1 (ADDR_EXPR, type,
- build2 (MEM_REF, TREE_TYPE (TREE_TYPE (@@2)),
- build_fold_addr_expr (base),
- build_int_cst (ptr_type_node, off)));
- @})
-#endif
-@end smallexample
-
-In the above example, @code{@@2} captures the result of the expression
-@code{(addr @@0)}. For the outermost expression only its type can be
-captured, and the keyword @code{type} is reserved for this purpose. The
-above example also gives a way to conditionalize patterns to only apply
-to @code{GIMPLE} or @code{GENERIC} by means of using the pre-defined
-preprocessor macros @code{GIMPLE} and @code{GENERIC} and using
-preprocessor directives.
-
-@smallexample
-(simplify
- (bit_and:c integral_op_p@@0 (bit_ior:c (bit_not @@0) @@1))
- (bit_and @@1 @@0))
-@end smallexample
-
-Here we introduce flags on match expressions. The flag used
-above, @code{c}, denotes that the expression should
-be also matched commutated. Thus the above match expression
-is really the following four match expressions:
-
-@smallexample
- (bit_and integral_op_p@@0 (bit_ior (bit_not @@0) @@1))
- (bit_and (bit_ior (bit_not @@0) @@1) integral_op_p@@0)
- (bit_and integral_op_p@@0 (bit_ior @@1 (bit_not @@0)))
- (bit_and (bit_ior @@1 (bit_not @@0)) integral_op_p@@0)
-@end smallexample
-
-Usual canonicalizations you know from GENERIC expressions are
-applied before matching, so for example constant operands always
-come second in commutative expressions.
-
-The second supported flag is @code{s} which tells the code
-generator to fail the pattern if the expression marked with
-@code{s} does have more than one use and the simplification
-results in an expression with more than one operator.
-For example in
-
-@smallexample
-(simplify
- (pointer_plus (pointer_plus:s @@0 @@1) @@3)
- (pointer_plus @@0 (plus @@1 @@3)))
-@end smallexample
-
-this avoids the association if @code{(pointer_plus @@0 @@1)} is
-used outside of the matched expression and thus it would stay
-live and not trivially removed by dead code elimination.
-Now consider @code{((x + 3) + -3)} with the temporary
-holding @code{(x + 3)} used elsewhere. This simplifies down
-to @code{x} which is desirable and thus flagging with @code{s}
-does not prevent the transform. Now consider @code{((x + 3) + 1)}
-which simplifies to @code{(x + 4)}. Despite being flagged with
-@code{s} the simplification will be performed. The
-simplification of @code{((x + a) + 1)} to @code{(x + (a + 1))} will
-not performed in this case though.
-
-More features exist to avoid too much repetition.
-
-@smallexample
-(for op (plus pointer_plus minus bit_ior bit_xor)
- (simplify
- (op @@0 integer_zerop)
- @@0))
-@end smallexample
-
-A @code{for} expression can be used to repeat a pattern for each
-operator specified, substituting @code{op}. @code{for} can be
-nested and a @code{for} can have multiple operators to iterate.
-
-@smallexample
-(for opa (plus minus)
- opb (minus plus)
- (for opc (plus minus)
- (simplify...
-@end smallexample
-
-In this example the pattern will be repeated four times with
-@code{opa, opb, opc} being @code{plus, minus, plus};
-@code{plus, minus, minus}; @code{minus, plus, plus};
-@code{minus, plus, minus}.
-
-To avoid repeating operator lists in @code{for} you can name
-them via
-
-@smallexample
-(define_operator_list pmm plus minus mult)
-@end smallexample
-
-and use them in @code{for} operator lists where they get expanded.
-
-@smallexample
-(for opa (pmm trunc_div)
- (simplify...
-@end smallexample
-
-So this example iterates over @code{plus}, @code{minus}, @code{mult}
-and @code{trunc_div}.
-
-Using operator lists can also remove the need to explicitly write
-a @code{for}. All operator list uses that appear in a @code{simplify}
-or @code{match} pattern in operator positions will implicitly
-be added to a new @code{for}. For example
-
-@smallexample
-(define_operator_list SQRT BUILT_IN_SQRTF BUILT_IN_SQRT BUILT_IN_SQRTL)
-(define_operator_list POW BUILT_IN_POWF BUILT_IN_POW BUILT_IN_POWL)
-(simplify
- (SQRT (POW @@0 @@1))
- (POW (abs @@0) (mult @@1 @{ built_real (TREE_TYPE (@@1), dconsthalf); @})))
-@end smallexample
-
-is the same as
-
-@smallexample
-(for SQRT (BUILT_IN_SQRTF BUILT_IN_SQRT BUILT_IN_SQRTL)
- POW (BUILT_IN_POWF BUILT_IN_POW BUILT_IN_POWL)
- (simplify
- (SQRT (POW @@0 @@1))
- (POW (abs @@0) (mult @@1 @{ built_real (TREE_TYPE (@@1), dconsthalf); @}))))
-@end smallexample
-
-@code{for}s and operator lists can include the special identifier
-@code{null} that matches nothing and can never be generated. This can
-be used to pad an operator list so that it has a standard form,
-even if there isn't a suitable operator for every form.
-
-Another building block are @code{with} expressions in the
-result expression which nest the generated code in a new C block
-followed by its argument:
-
-@smallexample
-(simplify
- (convert (mult @@0 @@1))
- (with @{ tree utype = unsigned_type_for (type); @}
- (convert (mult (convert:utype @@0) (convert:utype @@1)))))
-@end smallexample
-
-This allows code nested in the @code{with} to refer to the declared
-variables. In the above case we use the feature to specify the
-type of a generated expression with the @code{:type} syntax where
-@code{type} needs to be an identifier that refers to the desired type.
-Usually the types of the generated result expressions are
-determined from the context, but sometimes like in the above case
-it is required that you specify them explicitly.
-
-Another modifier for generated expressions is @code{!} which
-tells the machinery to only consider the simplification in case
-the marked expression simplified to a simple operand. Consider
-for example
-
-@smallexample
-(simplify
- (plus (vec_cond:s @@0 @@1 @@2) @@3)
- (vec_cond @@0 (plus! @@1 @@3) (plus! @@2 @@3)))
-@end smallexample
-
-which moves the outer @code{plus} operation to the inner arms
-of the @code{vec_cond} expression but only if the actual plus
-operations both simplify. Note that on @code{GENERIC} a simple
-operand means that the result satisfies @code{!EXPR_P} which
-can be limiting if the operation itself simplifies but the
-remaining operand is an (unrelated) expression.
-
-As intermediate conversions are often optional there is a way to
-avoid the need to repeat patterns both with and without such
-conversions. Namely you can mark a conversion as being optional
-with a @code{?}:
-
-@smallexample
-(simplify
- (eq (convert@@0 @@1) (convert@? @@2))
- (eq @@1 (convert @@2)))
-@end smallexample
-
-which will match both @code{(eq (convert @@1) (convert @@2))} and
-@code{(eq (convert @@1) @@2)}. The optional converts are supposed
-to be all either present or not, thus
-@code{(eq (convert@? @@1) (convert@? @@2))} will result in two
-patterns only. If you want to match all four combinations you
-have access to two additional conditional converts as in
-@code{(eq (convert1@? @@1) (convert2@? @@2))}.
-
-The support for @code{?} marking extends to all unary operations
-including predicates you declare yourself with @code{match}.
-
-Predicates available from the GCC middle-end need to be made
-available explicitly via @code{define_predicates}:
-
-@smallexample
-(define_predicates
- integer_onep integer_zerop integer_all_onesp)
-@end smallexample
-
-You can also define predicates using the pattern matching language
-and the @code{match} form:
-
-@smallexample
-(match negate_expr_p
- INTEGER_CST
- (if (TYPE_OVERFLOW_WRAPS (type)
- || may_negate_without_overflow_p (t))))
-(match negate_expr_p
- (negate @@0))
-@end smallexample
-
-This shows that for @code{match} expressions there is @code{t}
-available which captures the outermost expression (something
-not possible in the @code{simplify} context). As you can see
-@code{match} has an identifier as first operand which is how
-you refer to the predicate in patterns. Multiple @code{match}
-for the same identifier add additional cases where the predicate
-matches.
-
-Predicates can also match an expression in which case you need
-to provide a template specifying the identifier and where to
-get its operands from:
-
-@smallexample
-(match (logical_inverted_value @@0)
- (eq @@0 integer_zerop))
-(match (logical_inverted_value @@0)
- (bit_not truth_valued_p@@0))
-@end smallexample
-
-You can use the above predicate like
-
-@smallexample
-(simplify
- (bit_and @@0 (logical_inverted_value @@0))
- @{ build_zero_cst (type); @})
-@end smallexample
-
-Which will match a bitwise and of an operand with its logical
-inverted value.
-
+++ /dev/null
-@c Copyright (C) 1988-2022 Free Software Foundation, Inc.
-@c This is part of the GCC manual.
-@c For copying conditions, see the file gcc.texi.
-
-@ifset INTERNALS
-@node Machine Desc
-@chapter Machine Descriptions
-@cindex machine descriptions
-
-A machine description has two parts: a file of instruction patterns
-(@file{.md} file) and a C header file of macro definitions.
-
-The @file{.md} file for a target machine contains a pattern for each
-instruction that the target machine supports (or at least each instruction
-that is worth telling the compiler about). It may also contain comments.
-A semicolon causes the rest of the line to be a comment, unless the semicolon
-is inside a quoted string.
-
-See the next chapter for information on the C header file.
-
-@menu
-* Overview:: How the machine description is used.
-* Patterns:: How to write instruction patterns.
-* Example:: An explained example of a @code{define_insn} pattern.
-* RTL Template:: The RTL template defines what insns match a pattern.
-* Output Template:: The output template says how to make assembler code
- from such an insn.
-* Output Statement:: For more generality, write C code to output
- the assembler code.
-* Predicates:: Controlling what kinds of operands can be used
- for an insn.
-* Constraints:: Fine-tuning operand selection.
-* Standard Names:: Names mark patterns to use for code generation.
-* Pattern Ordering:: When the order of patterns makes a difference.
-* Dependent Patterns:: Having one pattern may make you need another.
-* Jump Patterns:: Special considerations for patterns for jump insns.
-* Looping Patterns:: How to define patterns for special looping insns.
-* Insn Canonicalizations::Canonicalization of Instructions
-* Expander Definitions::Generating a sequence of several RTL insns
- for a standard operation.
-* Insn Splitting:: Splitting Instructions into Multiple Instructions.
-* Including Patterns:: Including Patterns in Machine Descriptions.
-* Peephole Definitions::Defining machine-specific peephole optimizations.
-* Insn Attributes:: Specifying the value of attributes for generated insns.
-* Conditional Execution::Generating @code{define_insn} patterns for
- predication.
-* Define Subst:: Generating @code{define_insn} and @code{define_expand}
- patterns from other patterns.
-* Constant Definitions::Defining symbolic constants that can be used in the
- md file.
-* Iterators:: Using iterators to generate patterns from a template.
-@end menu
-
-@node Overview
-@section Overview of How the Machine Description is Used
-
-There are three main conversions that happen in the compiler:
-
-@enumerate
-
-@item
-The front end reads the source code and builds a parse tree.
-
-@item
-The parse tree is used to generate an RTL insn list based on named
-instruction patterns.
-
-@item
-The insn list is matched against the RTL templates to produce assembler
-code.
-
-@end enumerate
-
-For the generate pass, only the names of the insns matter, from either a
-named @code{define_insn} or a @code{define_expand}. The compiler will
-choose the pattern with the right name and apply the operands according
-to the documentation later in this chapter, without regard for the RTL
-template or operand constraints. Note that the names the compiler looks
-for are hard-coded in the compiler---it will ignore unnamed patterns and
-patterns with names it doesn't know about, but if you don't provide a
-named pattern it needs, it will abort.
-
-If a @code{define_insn} is used, the template given is inserted into the
-insn list. If a @code{define_expand} is used, one of three things
-happens, based on the condition logic. The condition logic may manually
-create new insns for the insn list, say via @code{emit_insn()}, and
-invoke @code{DONE}. For certain named patterns, it may invoke @code{FAIL} to tell the
-compiler to use an alternate way of performing that task. If it invokes
-neither @code{DONE} nor @code{FAIL}, the template given in the pattern
-is inserted, as if the @code{define_expand} were a @code{define_insn}.
-
-Once the insn list is generated, various optimization passes convert,
-replace, and rearrange the insns in the insn list. This is where the
-@code{define_split} and @code{define_peephole} patterns get used, for
-example.
-
-Finally, the insn list's RTL is matched up with the RTL templates in the
-@code{define_insn} patterns, and those patterns are used to emit the
-final assembly code. For this purpose, each named @code{define_insn}
-acts like it's unnamed, since the names are ignored.
-
-@node Patterns
-@section Everything about Instruction Patterns
-@cindex patterns
-@cindex instruction patterns
-
-@findex define_insn
-A @code{define_insn} expression is used to define instruction patterns
-to which insns may be matched. A @code{define_insn} expression contains
-an incomplete RTL expression, with pieces to be filled in later, operand
-constraints that restrict how the pieces can be filled in, and an output
-template or C code to generate the assembler output.
-
-A @code{define_insn} is an RTL expression containing four or five operands:
-
-@enumerate
-@item
-An optional name @var{n}. When a name is present, the compiler
-automically generates a C++ function @samp{gen_@var{n}} that takes
-the operands of the instruction as arguments and returns the instruction's
-rtx pattern. The compiler also assigns the instruction a unique code
-@samp{CODE_FOR_@var{n}}, with all such codes belonging to an enum
-called @code{insn_code}.
-
-These names serve one of two purposes. The first is to indicate that the
-instruction performs a certain standard job for the RTL-generation
-pass of the compiler, such as a move, an addition, or a conditional
-jump. The second is to help the target generate certain target-specific
-operations, such as when implementing target-specific intrinsic functions.
-
-It is better to prefix target-specific names with the name of the
-target, to avoid any clash with current or future standard names.
-
-The absence of a name is indicated by writing an empty string
-where the name should go. Nameless instruction patterns are never
-used for generating RTL code, but they may permit several simpler insns
-to be combined later on.
-
-For the purpose of debugging the compiler, you may also specify a
-name beginning with the @samp{*} character. Such a name is used only
-for identifying the instruction in RTL dumps; it is equivalent to having
-a nameless pattern for all other purposes. Names beginning with the
-@samp{*} character are not required to be unique.
-
-The name may also have the form @samp{@@@var{n}}. This has the same
-effect as a name @samp{@var{n}}, but in addition tells the compiler to
-generate further helper functions; see @ref{Parameterized Names} for details.
-
-@item
-The @dfn{RTL template}: This is a vector of incomplete RTL expressions
-which describe the semantics of the instruction (@pxref{RTL Template}).
-It is incomplete because it may contain @code{match_operand},
-@code{match_operator}, and @code{match_dup} expressions that stand for
-operands of the instruction.
-
-If the vector has multiple elements, the RTL template is treated as a
-@code{parallel} expression.
-
-@item
-@cindex pattern conditions
-@cindex conditions, in patterns
-The condition: This is a string which contains a C expression. When the
-compiler attempts to match RTL against a pattern, the condition is
-evaluated. If the condition evaluates to @code{true}, the match is
-permitted. The condition may be an empty string, which is treated
-as always @code{true}.
-
-@cindex named patterns and conditions
-For a named pattern, the condition may not depend on the data in the
-insn being matched, but only the target-machine-type flags. The compiler
-needs to test these conditions during initialization in order to learn
-exactly which named instructions are available in a particular run.
-
-@findex operands
-For nameless patterns, the condition is applied only when matching an
-individual insn, and only after the insn has matched the pattern's
-recognition template. The insn's operands may be found in the vector
-@code{operands}.
-
-An instruction condition cannot become more restrictive as compilation
-progresses. If the condition accepts a particular RTL instruction at
-one stage of compilation, it must continue to accept that instruction
-until the final pass. For example, @samp{!reload_completed} and
-@samp{can_create_pseudo_p ()} are both invalid instruction conditions,
-because they are true during the earlier RTL passes and false during
-the later ones. For the same reason, if a condition accepts an
-instruction before register allocation, it cannot later try to control
-register allocation by excluding certain register or value combinations.
-
-Although a condition cannot become more restrictive as compilation
-progresses, the condition for a nameless pattern @emph{can} become
-more permissive. For example, a nameless instruction can require
-@samp{reload_completed} to be true, in which case it only matches
-after register allocation.
-
-@item
-The @dfn{output template} or @dfn{output statement}: This is either
-a string, or a fragment of C code which returns a string.
-
-When simple substitution isn't general enough, you can specify a piece
-of C code to compute the output. @xref{Output Statement}.
-
-@item
-The @dfn{insn attributes}: This is an optional vector containing the values of
-attributes for insns matching this pattern (@pxref{Insn Attributes}).
-@end enumerate
-
-@node Example
-@section Example of @code{define_insn}
-@cindex @code{define_insn} example
-
-Here is an example of an instruction pattern, taken from the machine
-description for the 68000/68020.
-
-@smallexample
-(define_insn "tstsi"
- [(set (cc0)
- (match_operand:SI 0 "general_operand" "rm"))]
- ""
- "*
-@{
- if (TARGET_68020 || ! ADDRESS_REG_P (operands[0]))
- return \"tstl %0\";
- return \"cmpl #0,%0\";
-@}")
-@end smallexample
-
-@noindent
-This can also be written using braced strings:
-
-@smallexample
-(define_insn "tstsi"
- [(set (cc0)
- (match_operand:SI 0 "general_operand" "rm"))]
- ""
-@{
- if (TARGET_68020 || ! ADDRESS_REG_P (operands[0]))
- return "tstl %0";
- return "cmpl #0,%0";
-@})
-@end smallexample
-
-This describes an instruction which sets the condition codes based on the
-value of a general operand. It has no condition, so any insn with an RTL
-description of the form shown may be matched to this pattern. The name
-@samp{tstsi} means ``test a @code{SImode} value'' and tells the RTL
-generation pass that, when it is necessary to test such a value, an insn
-to do so can be constructed using this pattern.
-
-The output control string is a piece of C code which chooses which
-output template to return based on the kind of operand and the specific
-type of CPU for which code is being generated.
-
-@samp{"rm"} is an operand constraint. Its meaning is explained below.
-
-@node RTL Template
-@section RTL Template
-@cindex RTL insn template
-@cindex generating insns
-@cindex insns, generating
-@cindex recognizing insns
-@cindex insns, recognizing
-
-The RTL template is used to define which insns match the particular pattern
-and how to find their operands. For named patterns, the RTL template also
-says how to construct an insn from specified operands.
-
-Construction involves substituting specified operands into a copy of the
-template. Matching involves determining the values that serve as the
-operands in the insn being matched. Both of these activities are
-controlled by special expression types that direct matching and
-substitution of the operands.
-
-@table @code
-@findex match_operand
-@item (match_operand:@var{m} @var{n} @var{predicate} @var{constraint})
-This expression is a placeholder for operand number @var{n} of
-the insn. When constructing an insn, operand number @var{n}
-will be substituted at this point. When matching an insn, whatever
-appears at this position in the insn will be taken as operand
-number @var{n}; but it must satisfy @var{predicate} or this instruction
-pattern will not match at all.
-
-Operand numbers must be chosen consecutively counting from zero in
-each instruction pattern. There may be only one @code{match_operand}
-expression in the pattern for each operand number. Usually operands
-are numbered in the order of appearance in @code{match_operand}
-expressions. In the case of a @code{define_expand}, any operand numbers
-used only in @code{match_dup} expressions have higher values than all
-other operand numbers.
-
-@var{predicate} is a string that is the name of a function that
-accepts two arguments, an expression and a machine mode.
-@xref{Predicates}. During matching, the function will be called with
-the putative operand as the expression and @var{m} as the mode
-argument (if @var{m} is not specified, @code{VOIDmode} will be used,
-which normally causes @var{predicate} to accept any mode). If it
-returns zero, this instruction pattern fails to match.
-@var{predicate} may be an empty string; then it means no test is to be
-done on the operand, so anything which occurs in this position is
-valid.
-
-Most of the time, @var{predicate} will reject modes other than @var{m}---but
-not always. For example, the predicate @code{address_operand} uses
-@var{m} as the mode of memory ref that the address should be valid for.
-Many predicates accept @code{const_int} nodes even though their mode is
-@code{VOIDmode}.
-
-@var{constraint} controls reloading and the choice of the best register
-class to use for a value, as explained later (@pxref{Constraints}).
-If the constraint would be an empty string, it can be omitted.
-
-People are often unclear on the difference between the constraint and the
-predicate. The predicate helps decide whether a given insn matches the
-pattern. The constraint plays no role in this decision; instead, it
-controls various decisions in the case of an insn which does match.
-
-@findex match_scratch
-@item (match_scratch:@var{m} @var{n} @var{constraint})
-This expression is also a placeholder for operand number @var{n}
-and indicates that operand must be a @code{scratch} or @code{reg}
-expression.
-
-When matching patterns, this is equivalent to
-
-@smallexample
-(match_operand:@var{m} @var{n} "scratch_operand" @var{constraint})
-@end smallexample
-
-but, when generating RTL, it produces a (@code{scratch}:@var{m})
-expression.
-
-If the last few expressions in a @code{parallel} are @code{clobber}
-expressions whose operands are either a hard register or
-@code{match_scratch}, the combiner can add or delete them when
-necessary. @xref{Side Effects}.
-
-@findex match_dup
-@item (match_dup @var{n})
-This expression is also a placeholder for operand number @var{n}.
-It is used when the operand needs to appear more than once in the
-insn.
-
-In construction, @code{match_dup} acts just like @code{match_operand}:
-the operand is substituted into the insn being constructed. But in
-matching, @code{match_dup} behaves differently. It assumes that operand
-number @var{n} has already been determined by a @code{match_operand}
-appearing earlier in the recognition template, and it matches only an
-identical-looking expression.
-
-Note that @code{match_dup} should not be used to tell the compiler that
-a particular register is being used for two operands (example:
-@code{add} that adds one register to another; the second register is
-both an input operand and the output operand). Use a matching
-constraint (@pxref{Simple Constraints}) for those. @code{match_dup} is for the cases where one
-operand is used in two places in the template, such as an instruction
-that computes both a quotient and a remainder, where the opcode takes
-two input operands but the RTL template has to refer to each of those
-twice; once for the quotient pattern and once for the remainder pattern.
-
-@findex match_operator
-@item (match_operator:@var{m} @var{n} @var{predicate} [@var{operands}@dots{}])
-This pattern is a kind of placeholder for a variable RTL expression
-code.
-
-When constructing an insn, it stands for an RTL expression whose
-expression code is taken from that of operand @var{n}, and whose
-operands are constructed from the patterns @var{operands}.
-
-When matching an expression, it matches an expression if the function
-@var{predicate} returns nonzero on that expression @emph{and} the
-patterns @var{operands} match the operands of the expression.
-
-Suppose that the function @code{commutative_operator} is defined as
-follows, to match any expression whose operator is one of the
-commutative arithmetic operators of RTL and whose mode is @var{mode}:
-
-@smallexample
-int
-commutative_integer_operator (x, mode)
- rtx x;
- machine_mode mode;
-@{
- enum rtx_code code = GET_CODE (x);
- if (GET_MODE (x) != mode)
- return 0;
- return (GET_RTX_CLASS (code) == RTX_COMM_ARITH
- || code == EQ || code == NE);
-@}
-@end smallexample
-
-Then the following pattern will match any RTL expression consisting
-of a commutative operator applied to two general operands:
-
-@smallexample
-(match_operator:SI 3 "commutative_operator"
- [(match_operand:SI 1 "general_operand" "g")
- (match_operand:SI 2 "general_operand" "g")])
-@end smallexample
-
-Here the vector @code{[@var{operands}@dots{}]} contains two patterns
-because the expressions to be matched all contain two operands.
-
-When this pattern does match, the two operands of the commutative
-operator are recorded as operands 1 and 2 of the insn. (This is done
-by the two instances of @code{match_operand}.) Operand 3 of the insn
-will be the entire commutative expression: use @code{GET_CODE
-(operands[3])} to see which commutative operator was used.
-
-The machine mode @var{m} of @code{match_operator} works like that of
-@code{match_operand}: it is passed as the second argument to the
-predicate function, and that function is solely responsible for
-deciding whether the expression to be matched ``has'' that mode.
-
-When constructing an insn, argument 3 of the gen-function will specify
-the operation (i.e.@: the expression code) for the expression to be
-made. It should be an RTL expression, whose expression code is copied
-into a new expression whose operands are arguments 1 and 2 of the
-gen-function. The subexpressions of argument 3 are not used;
-only its expression code matters.
-
-When @code{match_operator} is used in a pattern for matching an insn,
-it usually best if the operand number of the @code{match_operator}
-is higher than that of the actual operands of the insn. This improves
-register allocation because the register allocator often looks at
-operands 1 and 2 of insns to see if it can do register tying.
-
-There is no way to specify constraints in @code{match_operator}. The
-operand of the insn which corresponds to the @code{match_operator}
-never has any constraints because it is never reloaded as a whole.
-However, if parts of its @var{operands} are matched by
-@code{match_operand} patterns, those parts may have constraints of
-their own.
-
-@findex match_op_dup
-@item (match_op_dup:@var{m} @var{n}[@var{operands}@dots{}])
-Like @code{match_dup}, except that it applies to operators instead of
-operands. When constructing an insn, operand number @var{n} will be
-substituted at this point. But in matching, @code{match_op_dup} behaves
-differently. It assumes that operand number @var{n} has already been
-determined by a @code{match_operator} appearing earlier in the
-recognition template, and it matches only an identical-looking
-expression.
-
-@findex match_parallel
-@item (match_parallel @var{n} @var{predicate} [@var{subpat}@dots{}])
-This pattern is a placeholder for an insn that consists of a
-@code{parallel} expression with a variable number of elements. This
-expression should only appear at the top level of an insn pattern.
-
-When constructing an insn, operand number @var{n} will be substituted at
-this point. When matching an insn, it matches if the body of the insn
-is a @code{parallel} expression with at least as many elements as the
-vector of @var{subpat} expressions in the @code{match_parallel}, if each
-@var{subpat} matches the corresponding element of the @code{parallel},
-@emph{and} the function @var{predicate} returns nonzero on the
-@code{parallel} that is the body of the insn. It is the responsibility
-of the predicate to validate elements of the @code{parallel} beyond
-those listed in the @code{match_parallel}.
-
-A typical use of @code{match_parallel} is to match load and store
-multiple expressions, which can contain a variable number of elements
-in a @code{parallel}. For example,
-
-@smallexample
-(define_insn ""
- [(match_parallel 0 "load_multiple_operation"
- [(set (match_operand:SI 1 "gpc_reg_operand" "=r")
- (match_operand:SI 2 "memory_operand" "m"))
- (use (reg:SI 179))
- (clobber (reg:SI 179))])]
- ""
- "loadm 0,0,%1,%2")
-@end smallexample
-
-This example comes from @file{a29k.md}. The function
-@code{load_multiple_operation} is defined in @file{a29k.c} and checks
-that subsequent elements in the @code{parallel} are the same as the
-@code{set} in the pattern, except that they are referencing subsequent
-registers and memory locations.
-
-An insn that matches this pattern might look like:
-
-@smallexample
-(parallel
- [(set (reg:SI 20) (mem:SI (reg:SI 100)))
- (use (reg:SI 179))
- (clobber (reg:SI 179))
- (set (reg:SI 21)
- (mem:SI (plus:SI (reg:SI 100)
- (const_int 4))))
- (set (reg:SI 22)
- (mem:SI (plus:SI (reg:SI 100)
- (const_int 8))))])
-@end smallexample
-
-@findex match_par_dup
-@item (match_par_dup @var{n} [@var{subpat}@dots{}])
-Like @code{match_op_dup}, but for @code{match_parallel} instead of
-@code{match_operator}.
-
-@end table
-
-@node Output Template
-@section Output Templates and Operand Substitution
-@cindex output templates
-@cindex operand substitution
-
-@cindex @samp{%} in template
-@cindex percent sign
-The @dfn{output template} is a string which specifies how to output the
-assembler code for an instruction pattern. Most of the template is a
-fixed string which is output literally. The character @samp{%} is used
-to specify where to substitute an operand; it can also be used to
-identify places where different variants of the assembler require
-different syntax.
-
-In the simplest case, a @samp{%} followed by a digit @var{n} says to output
-operand @var{n} at that point in the string.
-
-@samp{%} followed by a letter and a digit says to output an operand in an
-alternate fashion. Four letters have standard, built-in meanings described
-below. The machine description macro @code{PRINT_OPERAND} can define
-additional letters with nonstandard meanings.
-
-@samp{%c@var{digit}} can be used to substitute an operand that is a
-constant value without the syntax that normally indicates an immediate
-operand.
-
-@samp{%n@var{digit}} is like @samp{%c@var{digit}} except that the value of
-the constant is negated before printing.
-
-@samp{%a@var{digit}} can be used to substitute an operand as if it were a
-memory reference, with the actual operand treated as the address. This may
-be useful when outputting a ``load address'' instruction, because often the
-assembler syntax for such an instruction requires you to write the operand
-as if it were a memory reference.
-
-@samp{%l@var{digit}} is used to substitute a @code{label_ref} into a jump
-instruction.
-
-@samp{%=} outputs a number which is unique to each instruction in the
-entire compilation. This is useful for making local labels to be
-referred to more than once in a single template that generates multiple
-assembler instructions.
-
-@samp{%} followed by a punctuation character specifies a substitution that
-does not use an operand. Only one case is standard: @samp{%%} outputs a
-@samp{%} into the assembler code. Other nonstandard cases can be
-defined in the @code{PRINT_OPERAND} macro. You must also define
-which punctuation characters are valid with the
-@code{PRINT_OPERAND_PUNCT_VALID_P} macro.
-
-@cindex \
-@cindex backslash
-The template may generate multiple assembler instructions. Write the text
-for the instructions, with @samp{\;} between them.
-
-@cindex matching operands
-When the RTL contains two operands which are required by constraint to match
-each other, the output template must refer only to the lower-numbered operand.
-Matching operands are not always identical, and the rest of the compiler
-arranges to put the proper RTL expression for printing into the lower-numbered
-operand.
-
-One use of nonstandard letters or punctuation following @samp{%} is to
-distinguish between different assembler languages for the same machine; for
-example, Motorola syntax versus MIT syntax for the 68000. Motorola syntax
-requires periods in most opcode names, while MIT syntax does not. For
-example, the opcode @samp{movel} in MIT syntax is @samp{move.l} in Motorola
-syntax. The same file of patterns is used for both kinds of output syntax,
-but the character sequence @samp{%.} is used in each place where Motorola
-syntax wants a period. The @code{PRINT_OPERAND} macro for Motorola syntax
-defines the sequence to output a period; the macro for MIT syntax defines
-it to do nothing.
-
-@cindex @code{#} in template
-As a special case, a template consisting of the single character @code{#}
-instructs the compiler to first split the insn, and then output the
-resulting instructions separately. This helps eliminate redundancy in the
-output templates. If you have a @code{define_insn} that needs to emit
-multiple assembler instructions, and there is a matching @code{define_split}
-already defined, then you can simply use @code{#} as the output template
-instead of writing an output template that emits the multiple assembler
-instructions.
-
-Note that @code{#} only has an effect while generating assembly code;
-it does not affect whether a split occurs earlier. An associated
-@code{define_split} must exist and it must be suitable for use after
-register allocation.
-
-If the macro @code{ASSEMBLER_DIALECT} is defined, you can use construct
-of the form @samp{@{option0|option1|option2@}} in the templates. These
-describe multiple variants of assembler language syntax.
-@xref{Instruction Output}.
-
-@node Output Statement
-@section C Statements for Assembler Output
-@cindex output statements
-@cindex C statements for assembler output
-@cindex generating assembler output
-
-Often a single fixed template string cannot produce correct and efficient
-assembler code for all the cases that are recognized by a single
-instruction pattern. For example, the opcodes may depend on the kinds of
-operands; or some unfortunate combinations of operands may require extra
-machine instructions.
-
-If the output control string starts with a @samp{@@}, then it is actually
-a series of templates, each on a separate line. (Blank lines and
-leading spaces and tabs are ignored.) The templates correspond to the
-pattern's constraint alternatives (@pxref{Multi-Alternative}). For example,
-if a target machine has a two-address add instruction @samp{addr} to add
-into a register and another @samp{addm} to add a register to memory, you
-might write this pattern:
-
-@smallexample
-(define_insn "addsi3"
- [(set (match_operand:SI 0 "general_operand" "=r,m")
- (plus:SI (match_operand:SI 1 "general_operand" "0,0")
- (match_operand:SI 2 "general_operand" "g,r")))]
- ""
- "@@
- addr %2,%0
- addm %2,%0")
-@end smallexample
-
-@cindex @code{*} in template
-@cindex asterisk in template
-If the output control string starts with a @samp{*}, then it is not an
-output template but rather a piece of C program that should compute a
-template. It should execute a @code{return} statement to return the
-template-string you want. Most such templates use C string literals, which
-require doublequote characters to delimit them. To include these
-doublequote characters in the string, prefix each one with @samp{\}.
-
-If the output control string is written as a brace block instead of a
-double-quoted string, it is automatically assumed to be C code. In that
-case, it is not necessary to put in a leading asterisk, or to escape the
-doublequotes surrounding C string literals.
-
-The operands may be found in the array @code{operands}, whose C data type
-is @code{rtx []}.
-
-It is very common to select different ways of generating assembler code
-based on whether an immediate operand is within a certain range. Be
-careful when doing this, because the result of @code{INTVAL} is an
-integer on the host machine. If the host machine has more bits in an
-@code{int} than the target machine has in the mode in which the constant
-will be used, then some of the bits you get from @code{INTVAL} will be
-superfluous. For proper results, you must carefully disregard the
-values of those bits.
-
-@findex output_asm_insn
-It is possible to output an assembler instruction and then go on to output
-or compute more of them, using the subroutine @code{output_asm_insn}. This
-receives two arguments: a template-string and a vector of operands. The
-vector may be @code{operands}, or it may be another array of @code{rtx}
-that you declare locally and initialize yourself.
-
-@findex which_alternative
-When an insn pattern has multiple alternatives in its constraints, often
-the appearance of the assembler code is determined mostly by which alternative
-was matched. When this is so, the C code can test the variable
-@code{which_alternative}, which is the ordinal number of the alternative
-that was actually satisfied (0 for the first, 1 for the second alternative,
-etc.).
-
-For example, suppose there are two opcodes for storing zero, @samp{clrreg}
-for registers and @samp{clrmem} for memory locations. Here is how
-a pattern could use @code{which_alternative} to choose between them:
-
-@smallexample
-(define_insn ""
- [(set (match_operand:SI 0 "general_operand" "=r,m")
- (const_int 0))]
- ""
- @{
- return (which_alternative == 0
- ? "clrreg %0" : "clrmem %0");
- @})
-@end smallexample
-
-The example above, where the assembler code to generate was
-@emph{solely} determined by the alternative, could also have been specified
-as follows, having the output control string start with a @samp{@@}:
-
-@smallexample
-@group
-(define_insn ""
- [(set (match_operand:SI 0 "general_operand" "=r,m")
- (const_int 0))]
- ""
- "@@
- clrreg %0
- clrmem %0")
-@end group
-@end smallexample
-
-If you just need a little bit of C code in one (or a few) alternatives,
-you can use @samp{*} inside of a @samp{@@} multi-alternative template:
-
-@smallexample
-@group
-(define_insn ""
- [(set (match_operand:SI 0 "general_operand" "=r,<,m")
- (const_int 0))]
- ""
- "@@
- clrreg %0
- * return stack_mem_p (operands[0]) ? \"push 0\" : \"clrmem %0\";
- clrmem %0")
-@end group
-@end smallexample
-
-@node Predicates
-@section Predicates
-@cindex predicates
-@cindex operand predicates
-@cindex operator predicates
-
-A predicate determines whether a @code{match_operand} or
-@code{match_operator} expression matches, and therefore whether the
-surrounding instruction pattern will be used for that combination of
-operands. GCC has a number of machine-independent predicates, and you
-can define machine-specific predicates as needed. By convention,
-predicates used with @code{match_operand} have names that end in
-@samp{_operand}, and those used with @code{match_operator} have names
-that end in @samp{_operator}.
-
-All predicates are boolean functions (in the mathematical sense) of
-two arguments: the RTL expression that is being considered at that
-position in the instruction pattern, and the machine mode that the
-@code{match_operand} or @code{match_operator} specifies. In this
-section, the first argument is called @var{op} and the second argument
-@var{mode}. Predicates can be called from C as ordinary two-argument
-functions; this can be useful in output templates or other
-machine-specific code.
-
-Operand predicates can allow operands that are not actually acceptable
-to the hardware, as long as the constraints give reload the ability to
-fix them up (@pxref{Constraints}). However, GCC will usually generate
-better code if the predicates specify the requirements of the machine
-instructions as closely as possible. Reload cannot fix up operands
-that must be constants (``immediate operands''); you must use a
-predicate that allows only constants, or else enforce the requirement
-in the extra condition.
-
-@cindex predicates and machine modes
-@cindex normal predicates
-@cindex special predicates
-Most predicates handle their @var{mode} argument in a uniform manner.
-If @var{mode} is @code{VOIDmode} (unspecified), then @var{op} can have
-any mode. If @var{mode} is anything else, then @var{op} must have the
-same mode, unless @var{op} is a @code{CONST_INT} or integer
-@code{CONST_DOUBLE}. These RTL expressions always have
-@code{VOIDmode}, so it would be counterproductive to check that their
-mode matches. Instead, predicates that accept @code{CONST_INT} and/or
-integer @code{CONST_DOUBLE} check that the value stored in the
-constant will fit in the requested mode.
-
-Predicates with this behavior are called @dfn{normal}.
-@command{genrecog} can optimize the instruction recognizer based on
-knowledge of how normal predicates treat modes. It can also diagnose
-certain kinds of common errors in the use of normal predicates; for
-instance, it is almost always an error to use a normal predicate
-without specifying a mode.
-
-Predicates that do something different with their @var{mode} argument
-are called @dfn{special}. The generic predicates
-@code{address_operand} and @code{pmode_register_operand} are special
-predicates. @command{genrecog} does not do any optimizations or
-diagnosis when special predicates are used.
-
-@menu
-* Machine-Independent Predicates:: Predicates available to all back ends.
-* Defining Predicates:: How to write machine-specific predicate
- functions.
-@end menu
-
-@node Machine-Independent Predicates
-@subsection Machine-Independent Predicates
-@cindex machine-independent predicates
-@cindex generic predicates
-
-These are the generic predicates available to all back ends. They are
-defined in @file{recog.cc}. The first category of predicates allow
-only constant, or @dfn{immediate}, operands.
-
-@defun immediate_operand
-This predicate allows any sort of constant that fits in @var{mode}.
-It is an appropriate choice for instructions that take operands that
-must be constant.
-@end defun
-
-@defun const_int_operand
-This predicate allows any @code{CONST_INT} expression that fits in
-@var{mode}. It is an appropriate choice for an immediate operand that
-does not allow a symbol or label.
-@end defun
-
-@defun const_double_operand
-This predicate accepts any @code{CONST_DOUBLE} expression that has
-exactly @var{mode}. If @var{mode} is @code{VOIDmode}, it will also
-accept @code{CONST_INT}. It is intended for immediate floating point
-constants.
-@end defun
-
-@noindent
-The second category of predicates allow only some kind of machine
-register.
-
-@defun register_operand
-This predicate allows any @code{REG} or @code{SUBREG} expression that
-is valid for @var{mode}. It is often suitable for arithmetic
-instruction operands on a RISC machine.
-@end defun
-
-@defun pmode_register_operand
-This is a slight variant on @code{register_operand} which works around
-a limitation in the machine-description reader.
-
-@smallexample
-(match_operand @var{n} "pmode_register_operand" @var{constraint})
-@end smallexample
-
-@noindent
-means exactly what
-
-@smallexample
-(match_operand:P @var{n} "register_operand" @var{constraint})
-@end smallexample
-
-@noindent
-would mean, if the machine-description reader accepted @samp{:P}
-mode suffixes. Unfortunately, it cannot, because @code{Pmode} is an
-alias for some other mode, and might vary with machine-specific
-options. @xref{Misc}.
-@end defun
-
-@defun scratch_operand
-This predicate allows hard registers and @code{SCRATCH} expressions,
-but not pseudo-registers. It is used internally by @code{match_scratch};
-it should not be used directly.
-@end defun
-
-@noindent
-The third category of predicates allow only some kind of memory reference.
-
-@defun memory_operand
-This predicate allows any valid reference to a quantity of mode
-@var{mode} in memory, as determined by the weak form of
-@code{GO_IF_LEGITIMATE_ADDRESS} (@pxref{Addressing Modes}).
-@end defun
-
-@defun address_operand
-This predicate is a little unusual; it allows any operand that is a
-valid expression for the @emph{address} of a quantity of mode
-@var{mode}, again determined by the weak form of
-@code{GO_IF_LEGITIMATE_ADDRESS}. To first order, if
-@samp{@w{(mem:@var{mode} (@var{exp}))}} is acceptable to
-@code{memory_operand}, then @var{exp} is acceptable to
-@code{address_operand}. Note that @var{exp} does not necessarily have
-the mode @var{mode}.
-@end defun
-
-@defun indirect_operand
-This is a stricter form of @code{memory_operand} which allows only
-memory references with a @code{general_operand} as the address
-expression. New uses of this predicate are discouraged, because
-@code{general_operand} is very permissive, so it's hard to tell what
-an @code{indirect_operand} does or does not allow. If a target has
-different requirements for memory operands for different instructions,
-it is better to define target-specific predicates which enforce the
-hardware's requirements explicitly.
-@end defun
-
-@defun push_operand
-This predicate allows a memory reference suitable for pushing a value
-onto the stack. This will be a @code{MEM} which refers to
-@code{stack_pointer_rtx}, with a side effect in its address expression
-(@pxref{Incdec}); which one is determined by the
-@code{STACK_PUSH_CODE} macro (@pxref{Frame Layout}).
-@end defun
-
-@defun pop_operand
-This predicate allows a memory reference suitable for popping a value
-off the stack. Again, this will be a @code{MEM} referring to
-@code{stack_pointer_rtx}, with a side effect in its address
-expression. However, this time @code{STACK_POP_CODE} is expected.
-@end defun
-
-@noindent
-The fourth category of predicates allow some combination of the above
-operands.
-
-@defun nonmemory_operand
-This predicate allows any immediate or register operand valid for @var{mode}.
-@end defun
-
-@defun nonimmediate_operand
-This predicate allows any register or memory operand valid for @var{mode}.
-@end defun
-
-@defun general_operand
-This predicate allows any immediate, register, or memory operand
-valid for @var{mode}.
-@end defun
-
-@noindent
-Finally, there are two generic operator predicates.
-
-@defun comparison_operator
-This predicate matches any expression which performs an arithmetic
-comparison in @var{mode}; that is, @code{COMPARISON_P} is true for the
-expression code.
-@end defun
-
-@defun ordered_comparison_operator
-This predicate matches any expression which performs an arithmetic
-comparison in @var{mode} and whose expression code is valid for integer
-modes; that is, the expression code will be one of @code{eq}, @code{ne},
-@code{lt}, @code{ltu}, @code{le}, @code{leu}, @code{gt}, @code{gtu},
-@code{ge}, @code{geu}.
-@end defun
-
-@node Defining Predicates
-@subsection Defining Machine-Specific Predicates
-@cindex defining predicates
-@findex define_predicate
-@findex define_special_predicate
-
-Many machines have requirements for their operands that cannot be
-expressed precisely using the generic predicates. You can define
-additional predicates using @code{define_predicate} and
-@code{define_special_predicate} expressions. These expressions have
-three operands:
-
-@itemize @bullet
-@item
-The name of the predicate, as it will be referred to in
-@code{match_operand} or @code{match_operator} expressions.
-
-@item
-An RTL expression which evaluates to true if the predicate allows the
-operand @var{op}, false if it does not. This expression can only use
-the following RTL codes:
-
-@table @code
-@item MATCH_OPERAND
-When written inside a predicate expression, a @code{MATCH_OPERAND}
-expression evaluates to true if the predicate it names would allow
-@var{op}. The operand number and constraint are ignored. Due to
-limitations in @command{genrecog}, you can only refer to generic
-predicates and predicates that have already been defined.
-
-@item MATCH_CODE
-This expression evaluates to true if @var{op} or a specified
-subexpression of @var{op} has one of a given list of RTX codes.
-
-The first operand of this expression is a string constant containing a
-comma-separated list of RTX code names (in lower case). These are the
-codes for which the @code{MATCH_CODE} will be true.
-
-The second operand is a string constant which indicates what
-subexpression of @var{op} to examine. If it is absent or the empty
-string, @var{op} itself is examined. Otherwise, the string constant
-must be a sequence of digits and/or lowercase letters. Each character
-indicates a subexpression to extract from the current expression; for
-the first character this is @var{op}, for the second and subsequent
-characters it is the result of the previous character. A digit
-@var{n} extracts @samp{@w{XEXP (@var{e}, @var{n})}}; a letter @var{l}
-extracts @samp{@w{XVECEXP (@var{e}, 0, @var{n})}} where @var{n} is the
-alphabetic ordinal of @var{l} (0 for `a', 1 for 'b', and so on). The
-@code{MATCH_CODE} then examines the RTX code of the subexpression
-extracted by the complete string. It is not possible to extract
-components of an @code{rtvec} that is not at position 0 within its RTX
-object.
-
-@item MATCH_TEST
-This expression has one operand, a string constant containing a C
-expression. The predicate's arguments, @var{op} and @var{mode}, are
-available with those names in the C expression. The @code{MATCH_TEST}
-evaluates to true if the C expression evaluates to a nonzero value.
-@code{MATCH_TEST} expressions must not have side effects.
-
-@item AND
-@itemx IOR
-@itemx NOT
-@itemx IF_THEN_ELSE
-The basic @samp{MATCH_} expressions can be combined using these
-logical operators, which have the semantics of the C operators
-@samp{&&}, @samp{||}, @samp{!}, and @samp{@w{? :}} respectively. As
-in Common Lisp, you may give an @code{AND} or @code{IOR} expression an
-arbitrary number of arguments; this has exactly the same effect as
-writing a chain of two-argument @code{AND} or @code{IOR} expressions.
-@end table
-
-@item
-An optional block of C code, which should execute
-@samp{@w{return true}} if the predicate is found to match and
-@samp{@w{return false}} if it does not. It must not have any side
-effects. The predicate arguments, @var{op} and @var{mode}, are
-available with those names.
-
-If a code block is present in a predicate definition, then the RTL
-expression must evaluate to true @emph{and} the code block must
-execute @samp{@w{return true}} for the predicate to allow the operand.
-The RTL expression is evaluated first; do not re-check anything in the
-code block that was checked in the RTL expression.
-@end itemize
-
-The program @command{genrecog} scans @code{define_predicate} and
-@code{define_special_predicate} expressions to determine which RTX
-codes are possibly allowed. You should always make this explicit in
-the RTL predicate expression, using @code{MATCH_OPERAND} and
-@code{MATCH_CODE}.
-
-Here is an example of a simple predicate definition, from the IA64
-machine description:
-
-@smallexample
-@group
-;; @r{True if @var{op} is a @code{SYMBOL_REF} which refers to the sdata section.}
-(define_predicate "small_addr_symbolic_operand"
- (and (match_code "symbol_ref")
- (match_test "SYMBOL_REF_SMALL_ADDR_P (op)")))
-@end group
-@end smallexample
-
-@noindent
-And here is another, showing the use of the C block.
-
-@smallexample
-@group
-;; @r{True if @var{op} is a register operand that is (or could be) a GR reg.}
-(define_predicate "gr_register_operand"
- (match_operand 0 "register_operand")
-@{
- unsigned int regno;
- if (GET_CODE (op) == SUBREG)
- op = SUBREG_REG (op);
-
- regno = REGNO (op);
- return (regno >= FIRST_PSEUDO_REGISTER || GENERAL_REGNO_P (regno));
-@})
-@end group
-@end smallexample
-
-Predicates written with @code{define_predicate} automatically include
-a test that @var{mode} is @code{VOIDmode}, or @var{op} has the same
-mode as @var{mode}, or @var{op} is a @code{CONST_INT} or
-@code{CONST_DOUBLE}. They do @emph{not} check specifically for
-integer @code{CONST_DOUBLE}, nor do they test that the value of either
-kind of constant fits in the requested mode. This is because
-target-specific predicates that take constants usually have to do more
-stringent value checks anyway. If you need the exact same treatment
-of @code{CONST_INT} or @code{CONST_DOUBLE} that the generic predicates
-provide, use a @code{MATCH_OPERAND} subexpression to call
-@code{const_int_operand}, @code{const_double_operand}, or
-@code{immediate_operand}.
-
-Predicates written with @code{define_special_predicate} do not get any
-automatic mode checks, and are treated as having special mode handling
-by @command{genrecog}.
-
-The program @command{genpreds} is responsible for generating code to
-test predicates. It also writes a header file containing function
-declarations for all machine-specific predicates. It is not necessary
-to declare these predicates in @file{@var{cpu}-protos.h}.
-@end ifset
-
-@c Most of this node appears by itself (in a different place) even
-@c when the INTERNALS flag is clear. Passages that require the internals
-@c manual's context are conditionalized to appear only in the internals manual.
-@ifset INTERNALS
-@node Constraints
-@section Operand Constraints
-@cindex operand constraints
-@cindex constraints
-
-Each @code{match_operand} in an instruction pattern can specify
-constraints for the operands allowed. The constraints allow you to
-fine-tune matching within the set of operands allowed by the
-predicate.
-
-@end ifset
-@ifclear INTERNALS
-@node Constraints
-@section Constraints for @code{asm} Operands
-@cindex operand constraints, @code{asm}
-@cindex constraints, @code{asm}
-@cindex @code{asm} constraints
-
-Here are specific details on what constraint letters you can use with
-@code{asm} operands.
-@end ifclear
-Constraints can say whether
-an operand may be in a register, and which kinds of register; whether the
-operand can be a memory reference, and which kinds of address; whether the
-operand may be an immediate constant, and which possible values it may
-have. Constraints can also require two operands to match.
-Side-effects aren't allowed in operands of inline @code{asm}, unless
-@samp{<} or @samp{>} constraints are used, because there is no guarantee
-that the side effects will happen exactly once in an instruction that can update
-the addressing register.
-
-@ifset INTERNALS
-@menu
-* Simple Constraints:: Basic use of constraints.
-* Multi-Alternative:: When an insn has two alternative constraint-patterns.
-* Class Preferences:: Constraints guide which hard register to put things in.
-* Modifiers:: More precise control over effects of constraints.
-* Machine Constraints:: Existing constraints for some particular machines.
-* Disable Insn Alternatives:: Disable insn alternatives using attributes.
-* Define Constraints:: How to define machine-specific constraints.
-* C Constraint Interface:: How to test constraints from C code.
-@end menu
-@end ifset
-
-@ifclear INTERNALS
-@menu
-* Simple Constraints:: Basic use of constraints.
-* Multi-Alternative:: When an insn has two alternative constraint-patterns.
-* Modifiers:: More precise control over effects of constraints.
-* Machine Constraints:: Special constraints for some particular machines.
-@end menu
-@end ifclear
-
-@node Simple Constraints
-@subsection Simple Constraints
-@cindex simple constraints
-
-The simplest kind of constraint is a string full of letters, each of
-which describes one kind of operand that is permitted. Here are
-the letters that are allowed:
-
-@table @asis
-@item whitespace
-Whitespace characters are ignored and can be inserted at any position
-except the first. This enables each alternative for different operands to
-be visually aligned in the machine description even if they have different
-number of constraints and modifiers.
-
-@cindex @samp{m} in constraint
-@cindex memory references in constraints
-@item @samp{m}
-A memory operand is allowed, with any kind of address that the machine
-supports in general.
-Note that the letter used for the general memory constraint can be
-re-defined by a back end using the @code{TARGET_MEM_CONSTRAINT} macro.
-
-@cindex offsettable address
-@cindex @samp{o} in constraint
-@item @samp{o}
-A memory operand is allowed, but only if the address is
-@dfn{offsettable}. This means that adding a small integer (actually,
-the width in bytes of the operand, as determined by its machine mode)
-may be added to the address and the result is also a valid memory
-address.
-
-@cindex autoincrement/decrement addressing
-For example, an address which is constant is offsettable; so is an
-address that is the sum of a register and a constant (as long as a
-slightly larger constant is also within the range of address-offsets
-supported by the machine); but an autoincrement or autodecrement
-address is not offsettable. More complicated indirect/indexed
-addresses may or may not be offsettable depending on the other
-addressing modes that the machine supports.
-
-Note that in an output operand which can be matched by another
-operand, the constraint letter @samp{o} is valid only when accompanied
-by both @samp{<} (if the target machine has predecrement addressing)
-and @samp{>} (if the target machine has preincrement addressing).
-
-@cindex @samp{V} in constraint
-@item @samp{V}
-A memory operand that is not offsettable. In other words, anything that
-would fit the @samp{m} constraint but not the @samp{o} constraint.
-
-@cindex @samp{<} in constraint
-@item @samp{<}
-A memory operand with autodecrement addressing (either predecrement or
-postdecrement) is allowed. In inline @code{asm} this constraint is only
-allowed if the operand is used exactly once in an instruction that can
-handle the side effects. Not using an operand with @samp{<} in constraint
-string in the inline @code{asm} pattern at all or using it in multiple
-instructions isn't valid, because the side effects wouldn't be performed
-or would be performed more than once. Furthermore, on some targets
-the operand with @samp{<} in constraint string must be accompanied by
-special instruction suffixes like @code{%U0} instruction suffix on PowerPC
-or @code{%P0} on IA-64.
-
-@cindex @samp{>} in constraint
-@item @samp{>}
-A memory operand with autoincrement addressing (either preincrement or
-postincrement) is allowed. In inline @code{asm} the same restrictions
-as for @samp{<} apply.
-
-@cindex @samp{r} in constraint
-@cindex registers in constraints
-@item @samp{r}
-A register operand is allowed provided that it is in a general
-register.
-
-@cindex constants in constraints
-@cindex @samp{i} in constraint
-@item @samp{i}
-An immediate integer operand (one with constant value) is allowed.
-This includes symbolic constants whose values will be known only at
-assembly time or later.
-
-@cindex @samp{n} in constraint
-@item @samp{n}
-An immediate integer operand with a known numeric value is allowed.
-Many systems cannot support assembly-time constants for operands less
-than a word wide. Constraints for these operands should use @samp{n}
-rather than @samp{i}.
-
-@cindex @samp{I} in constraint
-@item @samp{I}, @samp{J}, @samp{K}, @dots{} @samp{P}
-Other letters in the range @samp{I} through @samp{P} may be defined in
-a machine-dependent fashion to permit immediate integer operands with
-explicit integer values in specified ranges. For example, on the
-68000, @samp{I} is defined to stand for the range of values 1 to 8.
-This is the range permitted as a shift count in the shift
-instructions.
-
-@cindex @samp{E} in constraint
-@item @samp{E}
-An immediate floating operand (expression code @code{const_double}) is
-allowed, but only if the target floating point format is the same as
-that of the host machine (on which the compiler is running).
-
-@cindex @samp{F} in constraint
-@item @samp{F}
-An immediate floating operand (expression code @code{const_double} or
-@code{const_vector}) is allowed.
-
-@cindex @samp{G} in constraint
-@cindex @samp{H} in constraint
-@item @samp{G}, @samp{H}
-@samp{G} and @samp{H} may be defined in a machine-dependent fashion to
-permit immediate floating operands in particular ranges of values.
-
-@cindex @samp{s} in constraint
-@item @samp{s}
-An immediate integer operand whose value is not an explicit integer is
-allowed.
-
-This might appear strange; if an insn allows a constant operand with a
-value not known at compile time, it certainly must allow any known
-value. So why use @samp{s} instead of @samp{i}? Sometimes it allows
-better code to be generated.
-
-For example, on the 68000 in a fullword instruction it is possible to
-use an immediate operand; but if the immediate value is between @minus{}128
-and 127, better code results from loading the value into a register and
-using the register. This is because the load into the register can be
-done with a @samp{moveq} instruction. We arrange for this to happen
-by defining the letter @samp{K} to mean ``any integer outside the
-range @minus{}128 to 127'', and then specifying @samp{Ks} in the operand
-constraints.
-
-@cindex @samp{g} in constraint
-@item @samp{g}
-Any register, memory or immediate integer operand is allowed, except for
-registers that are not general registers.
-
-@cindex @samp{X} in constraint
-@item @samp{X}
-@ifset INTERNALS
-Any operand whatsoever is allowed, even if it does not satisfy
-@code{general_operand}. This is normally used in the constraint of
-a @code{match_scratch} when certain alternatives will not actually
-require a scratch register.
-@end ifset
-@ifclear INTERNALS
-Any operand whatsoever is allowed.
-@end ifclear
-
-@cindex @samp{0} in constraint
-@cindex digits in constraint
-@item @samp{0}, @samp{1}, @samp{2}, @dots{} @samp{9}
-An operand that matches the specified operand number is allowed. If a
-digit is used together with letters within the same alternative, the
-digit should come last.
-
-This number is allowed to be more than a single digit. If multiple
-digits are encountered consecutively, they are interpreted as a single
-decimal integer. There is scant chance for ambiguity, since to-date
-it has never been desirable that @samp{10} be interpreted as matching
-either operand 1 @emph{or} operand 0. Should this be desired, one
-can use multiple alternatives instead.
-
-@cindex matching constraint
-@cindex constraint, matching
-This is called a @dfn{matching constraint} and what it really means is
-that the assembler has only a single operand that fills two roles
-@ifset INTERNALS
-considered separate in the RTL insn. For example, an add insn has two
-input operands and one output operand in the RTL, but on most CISC
-@end ifset
-@ifclear INTERNALS
-which @code{asm} distinguishes. For example, an add instruction uses
-two input operands and an output operand, but on most CISC
-@end ifclear
-machines an add instruction really has only two operands, one of them an
-input-output operand:
-
-@smallexample
-addl #35,r12
-@end smallexample
-
-Matching constraints are used in these circumstances.
-More precisely, the two operands that match must include one input-only
-operand and one output-only operand. Moreover, the digit must be a
-smaller number than the number of the operand that uses it in the
-constraint.
-
-@ifset INTERNALS
-For operands to match in a particular case usually means that they
-are identical-looking RTL expressions. But in a few special cases
-specific kinds of dissimilarity are allowed. For example, @code{*x}
-as an input operand will match @code{*x++} as an output operand.
-For proper results in such cases, the output template should always
-use the output-operand's number when printing the operand.
-@end ifset
-
-@cindex load address instruction
-@cindex push address instruction
-@cindex address constraints
-@cindex @samp{p} in constraint
-@item @samp{p}
-An operand that is a valid memory address is allowed. This is
-for ``load address'' and ``push address'' instructions.
-
-@findex address_operand
-@samp{p} in the constraint must be accompanied by @code{address_operand}
-as the predicate in the @code{match_operand}. This predicate interprets
-the mode specified in the @code{match_operand} as the mode of the memory
-reference for which the address would be valid.
-
-@cindex other register constraints
-@cindex extensible constraints
-@item @var{other-letters}
-Other letters can be defined in machine-dependent fashion to stand for
-particular classes of registers or other arbitrary operand types.
-@samp{d}, @samp{a} and @samp{f} are defined on the 68000/68020 to stand
-for data, address and floating point registers.
-@end table
-
-@ifset INTERNALS
-In order to have valid assembler code, each operand must satisfy
-its constraint. But a failure to do so does not prevent the pattern
-from applying to an insn. Instead, it directs the compiler to modify
-the code so that the constraint will be satisfied. Usually this is
-done by copying an operand into a register.
-
-Contrast, therefore, the two instruction patterns that follow:
-
-@smallexample
-(define_insn ""
- [(set (match_operand:SI 0 "general_operand" "=r")
- (plus:SI (match_dup 0)
- (match_operand:SI 1 "general_operand" "r")))]
- ""
- "@dots{}")
-@end smallexample
-
-@noindent
-which has two operands, one of which must appear in two places, and
-
-@smallexample
-(define_insn ""
- [(set (match_operand:SI 0 "general_operand" "=r")
- (plus:SI (match_operand:SI 1 "general_operand" "0")
- (match_operand:SI 2 "general_operand" "r")))]
- ""
- "@dots{}")
-@end smallexample
-
-@noindent
-which has three operands, two of which are required by a constraint to be
-identical. If we are considering an insn of the form
-
-@smallexample
-(insn @var{n} @var{prev} @var{next}
- (set (reg:SI 3)
- (plus:SI (reg:SI 6) (reg:SI 109)))
- @dots{})
-@end smallexample
-
-@noindent
-the first pattern would not apply at all, because this insn does not
-contain two identical subexpressions in the right place. The pattern would
-say, ``That does not look like an add instruction; try other patterns''.
-The second pattern would say, ``Yes, that's an add instruction, but there
-is something wrong with it''. It would direct the reload pass of the
-compiler to generate additional insns to make the constraint true. The
-results might look like this:
-
-@smallexample
-(insn @var{n2} @var{prev} @var{n}
- (set (reg:SI 3) (reg:SI 6))
- @dots{})
-
-(insn @var{n} @var{n2} @var{next}
- (set (reg:SI 3)
- (plus:SI (reg:SI 3) (reg:SI 109)))
- @dots{})
-@end smallexample
-
-It is up to you to make sure that each operand, in each pattern, has
-constraints that can handle any RTL expression that could be present for
-that operand. (When multiple alternatives are in use, each pattern must,
-for each possible combination of operand expressions, have at least one
-alternative which can handle that combination of operands.) The
-constraints don't need to @emph{allow} any possible operand---when this is
-the case, they do not constrain---but they must at least point the way to
-reloading any possible operand so that it will fit.
-
-@itemize @bullet
-@item
-If the constraint accepts whatever operands the predicate permits,
-there is no problem: reloading is never necessary for this operand.
-
-For example, an operand whose constraints permit everything except
-registers is safe provided its predicate rejects registers.
-
-An operand whose predicate accepts only constant values is safe
-provided its constraints include the letter @samp{i}. If any possible
-constant value is accepted, then nothing less than @samp{i} will do;
-if the predicate is more selective, then the constraints may also be
-more selective.
-
-@item
-Any operand expression can be reloaded by copying it into a register.
-So if an operand's constraints allow some kind of register, it is
-certain to be safe. It need not permit all classes of registers; the
-compiler knows how to copy a register into another register of the
-proper class in order to make an instruction valid.
-
-@cindex nonoffsettable memory reference
-@cindex memory reference, nonoffsettable
-@item
-A nonoffsettable memory reference can be reloaded by copying the
-address into a register. So if the constraint uses the letter
-@samp{o}, all memory references are taken care of.
-
-@item
-A constant operand can be reloaded by allocating space in memory to
-hold it as preinitialized data. Then the memory reference can be used
-in place of the constant. So if the constraint uses the letters
-@samp{o} or @samp{m}, constant operands are not a problem.
-
-@item
-If the constraint permits a constant and a pseudo register used in an insn
-was not allocated to a hard register and is equivalent to a constant,
-the register will be replaced with the constant. If the predicate does
-not permit a constant and the insn is re-recognized for some reason, the
-compiler will crash. Thus the predicate must always recognize any
-objects allowed by the constraint.
-@end itemize
-
-If the operand's predicate can recognize registers, but the constraint does
-not permit them, it can make the compiler crash. When this operand happens
-to be a register, the reload pass will be stymied, because it does not know
-how to copy a register temporarily into memory.
-
-If the predicate accepts a unary operator, the constraint applies to the
-operand. For example, the MIPS processor at ISA level 3 supports an
-instruction which adds two registers in @code{SImode} to produce a
-@code{DImode} result, but only if the registers are correctly sign
-extended. This predicate for the input operands accepts a
-@code{sign_extend} of an @code{SImode} register. Write the constraint
-to indicate the type of register that is required for the operand of the
-@code{sign_extend}.
-@end ifset
-
-@node Multi-Alternative
-@subsection Multiple Alternative Constraints
-@cindex multiple alternative constraints
-
-Sometimes a single instruction has multiple alternative sets of possible
-operands. For example, on the 68000, a logical-or instruction can combine
-register or an immediate value into memory, or it can combine any kind of
-operand into a register; but it cannot combine one memory location into
-another.
-
-These constraints are represented as multiple alternatives. An alternative
-can be described by a series of letters for each operand. The overall
-constraint for an operand is made from the letters for this operand
-from the first alternative, a comma, the letters for this operand from
-the second alternative, a comma, and so on until the last alternative.
-All operands for a single instruction must have the same number of
-alternatives.
-@ifset INTERNALS
-Here is how it is done for fullword logical-or on the 68000:
-
-@smallexample
-(define_insn "iorsi3"
- [(set (match_operand:SI 0 "general_operand" "=m,d")
- (ior:SI (match_operand:SI 1 "general_operand" "%0,0")
- (match_operand:SI 2 "general_operand" "dKs,dmKs")))]
- @dots{})
-@end smallexample
-
-The first alternative has @samp{m} (memory) for operand 0, @samp{0} for
-operand 1 (meaning it must match operand 0), and @samp{dKs} for operand
-2. The second alternative has @samp{d} (data register) for operand 0,
-@samp{0} for operand 1, and @samp{dmKs} for operand 2. The @samp{=} and
-@samp{%} in the constraints apply to all the alternatives; their
-meaning is explained in the next section (@pxref{Class Preferences}).
-
-If all the operands fit any one alternative, the instruction is valid.
-Otherwise, for each alternative, the compiler counts how many instructions
-must be added to copy the operands so that that alternative applies.
-The alternative requiring the least copying is chosen. If two alternatives
-need the same amount of copying, the one that comes first is chosen.
-These choices can be altered with the @samp{?} and @samp{!} characters:
-
-@table @code
-@cindex @samp{?} in constraint
-@cindex question mark
-@item ?
-Disparage slightly the alternative that the @samp{?} appears in,
-as a choice when no alternative applies exactly. The compiler regards
-this alternative as one unit more costly for each @samp{?} that appears
-in it.
-
-@cindex @samp{!} in constraint
-@cindex exclamation point
-@item !
-Disparage severely the alternative that the @samp{!} appears in.
-This alternative can still be used if it fits without reloading,
-but if reloading is needed, some other alternative will be used.
-
-@cindex @samp{^} in constraint
-@cindex caret
-@item ^
-This constraint is analogous to @samp{?} but it disparages slightly
-the alternative only if the operand with the @samp{^} needs a reload.
-
-@cindex @samp{$} in constraint
-@cindex dollar sign
-@item $
-This constraint is analogous to @samp{!} but it disparages severely
-the alternative only if the operand with the @samp{$} needs a reload.
-@end table
-
-When an insn pattern has multiple alternatives in its constraints, often
-the appearance of the assembler code is determined mostly by which
-alternative was matched. When this is so, the C code for writing the
-assembler code can use the variable @code{which_alternative}, which is
-the ordinal number of the alternative that was actually satisfied (0 for
-the first, 1 for the second alternative, etc.). @xref{Output Statement}.
-@end ifset
-@ifclear INTERNALS
-
-So the first alternative for the 68000's logical-or could be written as
-@code{"+m" (output) : "ir" (input)}. The second could be @code{"+r"
-(output): "irm" (input)}. However, the fact that two memory locations
-cannot be used in a single instruction prevents simply using @code{"+rm"
-(output) : "irm" (input)}. Using multi-alternatives, this might be
-written as @code{"+m,r" (output) : "ir,irm" (input)}. This describes
-all the available alternatives to the compiler, allowing it to choose
-the most efficient one for the current conditions.
-
-There is no way within the template to determine which alternative was
-chosen. However you may be able to wrap your @code{asm} statements with
-builtins such as @code{__builtin_constant_p} to achieve the desired results.
-@end ifclear
-
-@ifset INTERNALS
-@node Class Preferences
-@subsection Register Class Preferences
-@cindex class preference constraints
-@cindex register class preference constraints
-
-@cindex voting between constraint alternatives
-The operand constraints have another function: they enable the compiler
-to decide which kind of hardware register a pseudo register is best
-allocated to. The compiler examines the constraints that apply to the
-insns that use the pseudo register, looking for the machine-dependent
-letters such as @samp{d} and @samp{a} that specify classes of registers.
-The pseudo register is put in whichever class gets the most ``votes''.
-The constraint letters @samp{g} and @samp{r} also vote: they vote in
-favor of a general register. The machine description says which registers
-are considered general.
-
-Of course, on some machines all registers are equivalent, and no register
-classes are defined. Then none of this complexity is relevant.
-@end ifset
-
-@node Modifiers
-@subsection Constraint Modifier Characters
-@cindex modifiers in constraints
-@cindex constraint modifier characters
-
-@c prevent bad page break with this line
-Here are constraint modifier characters.
-
-@table @samp
-@cindex @samp{=} in constraint
-@item =
-Means that this operand is written to by this instruction:
-the previous value is discarded and replaced by new data.
-
-@cindex @samp{+} in constraint
-@item +
-Means that this operand is both read and written by the instruction.
-
-When the compiler fixes up the operands to satisfy the constraints,
-it needs to know which operands are read by the instruction and
-which are written by it. @samp{=} identifies an operand which is only
-written; @samp{+} identifies an operand that is both read and written; all
-other operands are assumed to only be read.
-
-If you specify @samp{=} or @samp{+} in a constraint, you put it in the
-first character of the constraint string.
-
-@cindex @samp{&} in constraint
-@cindex earlyclobber operand
-@item &
-Means (in a particular alternative) that this operand is an
-@dfn{earlyclobber} operand, which is written before the instruction is
-finished using the input operands. Therefore, this operand may not lie
-in a register that is read by the instruction or as part of any memory
-address.
-
-@samp{&} applies only to the alternative in which it is written. In
-constraints with multiple alternatives, sometimes one alternative
-requires @samp{&} while others do not. See, for example, the
-@samp{movdf} insn of the 68000.
-
-An operand which is read by the instruction can be tied to an earlyclobber
-operand if its only use as an input occurs before the early result is
-written. Adding alternatives of this form often allows GCC to produce
-better code when only some of the read operands can be affected by the
-earlyclobber. See, for example, the @samp{mulsi3} insn of the ARM@.
-
-Furthermore, if the @dfn{earlyclobber} operand is also a read/write
-operand, then that operand is written only after it's used.
-
-@samp{&} does not obviate the need to write @samp{=} or @samp{+}. As
-@dfn{earlyclobber} operands are always written, a read-only
-@dfn{earlyclobber} operand is ill-formed and will be rejected by the
-compiler.
-
-@cindex @samp{%} in constraint
-@item %
-Declares the instruction to be commutative for this operand and the
-following operand. This means that the compiler may interchange the
-two operands if that is the cheapest way to make all operands fit the
-constraints. @samp{%} applies to all alternatives and must appear as
-the first character in the constraint. Only read-only operands can use
-@samp{%}.
-
-@ifset INTERNALS
-This is often used in patterns for addition instructions
-that really have only two operands: the result must go in one of the
-arguments. Here for example, is how the 68000 halfword-add
-instruction is defined:
-
-@smallexample
-(define_insn "addhi3"
- [(set (match_operand:HI 0 "general_operand" "=m,r")
- (plus:HI (match_operand:HI 1 "general_operand" "%0,0")
- (match_operand:HI 2 "general_operand" "di,g")))]
- @dots{})
-@end smallexample
-@end ifset
-GCC can only handle one commutative pair in an asm; if you use more,
-the compiler may fail. Note that you need not use the modifier if
-the two alternatives are strictly identical; this would only waste
-time in the reload pass.
-@ifset INTERNALS
-The modifier is not operational after
-register allocation, so the result of @code{define_peephole2}
-and @code{define_split}s performed after reload cannot rely on
-@samp{%} to make the intended insn match.
-
-@cindex @samp{#} in constraint
-@item #
-Says that all following characters, up to the next comma, are to be
-ignored as a constraint. They are significant only for choosing
-register preferences.
-
-@cindex @samp{*} in constraint
-@item *
-Says that the following character should be ignored when choosing
-register preferences. @samp{*} has no effect on the meaning of the
-constraint as a constraint, and no effect on reloading. For LRA
-@samp{*} additionally disparages slightly the alternative if the
-following character matches the operand.
-
-Here is an example: the 68000 has an instruction to sign-extend a
-halfword in a data register, and can also sign-extend a value by
-copying it into an address register. While either kind of register is
-acceptable, the constraints on an address-register destination are
-less strict, so it is best if register allocation makes an address
-register its goal. Therefore, @samp{*} is used so that the @samp{d}
-constraint letter (for data register) is ignored when computing
-register preferences.
-
-@smallexample
-(define_insn "extendhisi2"
- [(set (match_operand:SI 0 "general_operand" "=*d,a")
- (sign_extend:SI
- (match_operand:HI 1 "general_operand" "0,g")))]
- @dots{})
-@end smallexample
-@end ifset
-@end table
-
-@node Machine Constraints
-@subsection Constraints for Particular Machines
-@cindex machine specific constraints
-@cindex constraints, machine specific
-
-Whenever possible, you should use the general-purpose constraint letters
-in @code{asm} arguments, since they will convey meaning more readily to
-people reading your code. Failing that, use the constraint letters
-that usually have very similar meanings across architectures. The most
-commonly used constraints are @samp{m} and @samp{r} (for memory and
-general-purpose registers respectively; @pxref{Simple Constraints}), and
-@samp{I}, usually the letter indicating the most common
-immediate-constant format.
-
-Each architecture defines additional constraints. These constraints
-are used by the compiler itself for instruction generation, as well as
-for @code{asm} statements; therefore, some of the constraints are not
-particularly useful for @code{asm}. Here is a summary of some of the
-machine-dependent constraints available on some particular machines;
-it includes both constraints that are useful for @code{asm} and
-constraints that aren't. The compiler source file mentioned in the
-table heading for each architecture is the definitive reference for
-the meanings of that architecture's constraints.
-
-@c Please keep this table alphabetized by target!
-@table @emph
-@item AArch64 family---@file{config/aarch64/constraints.md}
-@table @code
-@item k
-The stack pointer register (@code{SP})
-
-@item w
-Floating point register, Advanced SIMD vector register or SVE vector register
-
-@item x
-Like @code{w}, but restricted to registers 0 to 15 inclusive.
-
-@item y
-Like @code{w}, but restricted to registers 0 to 7 inclusive.
-
-@item Upl
-One of the low eight SVE predicate registers (@code{P0} to @code{P7})
-
-@item Upa
-Any of the SVE predicate registers (@code{P0} to @code{P15})
-
-@item I
-Integer constant that is valid as an immediate operand in an @code{ADD}
-instruction
-
-@item J
-Integer constant that is valid as an immediate operand in a @code{SUB}
-instruction (once negated)
-
-@item K
-Integer constant that can be used with a 32-bit logical instruction
-
-@item L
-Integer constant that can be used with a 64-bit logical instruction
-
-@item M
-Integer constant that is valid as an immediate operand in a 32-bit @code{MOV}
-pseudo instruction. The @code{MOV} may be assembled to one of several different
-machine instructions depending on the value
-
-@item N
-Integer constant that is valid as an immediate operand in a 64-bit @code{MOV}
-pseudo instruction
-
-@item S
-An absolute symbolic address or a label reference
-
-@item Y
-Floating point constant zero
-
-@item Z
-Integer constant zero
-
-@item Ush
-The high part (bits 12 and upwards) of the pc-relative address of a symbol
-within 4GB of the instruction
-
-@item Q
-A memory address which uses a single base register with no offset
-
-@item Ump
-A memory address suitable for a load/store pair instruction in SI, DI, SF and
-DF modes
-
-@end table
-
-
-@item AMD GCN ---@file{config/gcn/constraints.md}
-@table @code
-@item I
-Immediate integer in the range @minus{}16 to 64
-
-@item J
-Immediate 16-bit signed integer
-
-@item Kf
-Immediate constant @minus{}1
-
-@item L
-Immediate 15-bit unsigned integer
-
-@item A
-Immediate constant that can be inlined in an instruction encoding: integer
-@minus{}16..64, or float 0.0, +/@minus{}0.5, +/@minus{}1.0, +/@minus{}2.0,
-+/@minus{}4.0, 1.0/(2.0*PI)
-
-@item B
-Immediate 32-bit signed integer that can be attached to an instruction encoding
-
-@item C
-Immediate 32-bit integer in range @minus{}16..4294967295 (i.e. 32-bit unsigned
-integer or @samp{A} constraint)
-
-@item DA
-Immediate 64-bit constant that can be split into two @samp{A} constants
-
-@item DB
-Immediate 64-bit constant that can be split into two @samp{B} constants
-
-@item U
-Any @code{unspec}
-
-@item Y
-Any @code{symbol_ref} or @code{label_ref}
-
-@item v
-VGPR register
-
-@item Sg
-SGPR register
-
-@item SD
-SGPR registers valid for instruction destinations, including VCC, M0 and EXEC
-
-@item SS
-SGPR registers valid for instruction sources, including VCC, M0, EXEC and SCC
-
-@item Sm
-SGPR registers valid as a source for scalar memory instructions (excludes M0
-and EXEC)
-
-@item Sv
-SGPR registers valid as a source or destination for vector instructions
-(excludes EXEC)
-
-@item ca
-All condition registers: SCC, VCCZ, EXECZ
-
-@item cs
-Scalar condition register: SCC
-
-@item cV
-Vector condition register: VCC, VCC_LO, VCC_HI
-
-@item e
-EXEC register (EXEC_LO and EXEC_HI)
-
-@item RB
-Memory operand with address space suitable for @code{buffer_*} instructions
-
-@item RF
-Memory operand with address space suitable for @code{flat_*} instructions
-
-@item RS
-Memory operand with address space suitable for @code{s_*} instructions
-
-@item RL
-Memory operand with address space suitable for @code{ds_*} LDS instructions
-
-@item RG
-Memory operand with address space suitable for @code{ds_*} GDS instructions
-
-@item RD
-Memory operand with address space suitable for any @code{ds_*} instructions
-
-@item RM
-Memory operand with address space suitable for @code{global_*} instructions
-
-@end table
-
-
-@item ARC ---@file{config/arc/constraints.md}
-@table @code
-@item q
-Registers usable in ARCompact 16-bit instructions: @code{r0}-@code{r3},
-@code{r12}-@code{r15}. This constraint can only match when the @option{-mq}
-option is in effect.
-
-@item e
-Registers usable as base-regs of memory addresses in ARCompact 16-bit memory
-instructions: @code{r0}-@code{r3}, @code{r12}-@code{r15}, @code{sp}.
-This constraint can only match when the @option{-mq}
-option is in effect.
-@item D
-ARC FPX (dpfp) 64-bit registers. @code{D0}, @code{D1}.
-
-@item I
-A signed 12-bit integer constant.
-
-@item Cal
-constant for arithmetic/logical operations. This might be any constant
-that can be put into a long immediate by the assmbler or linker without
-involving a PIC relocation.
-
-@item K
-A 3-bit unsigned integer constant.
-
-@item L
-A 6-bit unsigned integer constant.
-
-@item CnL
-One's complement of a 6-bit unsigned integer constant.
-
-@item CmL
-Two's complement of a 6-bit unsigned integer constant.
-
-@item M
-A 5-bit unsigned integer constant.
-
-@item O
-A 7-bit unsigned integer constant.
-
-@item P
-A 8-bit unsigned integer constant.
-
-@item H
-Any const_double value.
-@end table
-
-@item ARM family---@file{config/arm/constraints.md}
-@table @code
-
-@item h
-In Thumb state, the core registers @code{r8}-@code{r15}.
-
-@item k
-The stack pointer register.
-
-@item l
-In Thumb State the core registers @code{r0}-@code{r7}. In ARM state this
-is an alias for the @code{r} constraint.
-
-@item t
-VFP floating-point registers @code{s0}-@code{s31}. Used for 32 bit values.
-
-@item w
-VFP floating-point registers @code{d0}-@code{d31} and the appropriate
-subset @code{d0}-@code{d15} based on command line options.
-Used for 64 bit values only. Not valid for Thumb1.
-
-@item y
-The iWMMX co-processor registers.
-
-@item z
-The iWMMX GR registers.
-
-@item G
-The floating-point constant 0.0
-
-@item I
-Integer that is valid as an immediate operand in a data processing
-instruction. That is, an integer in the range 0 to 255 rotated by a
-multiple of 2
-
-@item J
-Integer in the range @minus{}4095 to 4095
-
-@item K
-Integer that satisfies constraint @samp{I} when inverted (ones complement)
-
-@item L
-Integer that satisfies constraint @samp{I} when negated (twos complement)
-
-@item M
-Integer in the range 0 to 32
-
-@item Q
-A memory reference where the exact address is in a single register
-(`@samp{m}' is preferable for @code{asm} statements)
-
-@item R
-An item in the constant pool
-
-@item S
-A symbol in the text segment of the current file
-
-@item Uv
-A memory reference suitable for VFP load/store insns (reg+constant offset)
-
-@item Uy
-A memory reference suitable for iWMMXt load/store instructions.
-
-@item Uq
-A memory reference suitable for the ARMv4 ldrsb instruction.
-@end table
-
-@item AVR family---@file{config/avr/constraints.md}
-@table @code
-@item l
-Registers from r0 to r15
-
-@item a
-Registers from r16 to r23
-
-@item d
-Registers from r16 to r31
-
-@item w
-Registers from r24 to r31. These registers can be used in @samp{adiw} command
-
-@item e
-Pointer register (r26--r31)
-
-@item b
-Base pointer register (r28--r31)
-
-@item q
-Stack pointer register (SPH:SPL)
-
-@item t
-Temporary register r0
-
-@item x
-Register pair X (r27:r26)
-
-@item y
-Register pair Y (r29:r28)
-
-@item z
-Register pair Z (r31:r30)
-
-@item I
-Constant greater than @minus{}1, less than 64
-
-@item J
-Constant greater than @minus{}64, less than 1
-
-@item K
-Constant integer 2
-
-@item L
-Constant integer 0
-
-@item M
-Constant that fits in 8 bits
-
-@item N
-Constant integer @minus{}1
-
-@item O
-Constant integer 8, 16, or 24
-
-@item P
-Constant integer 1
-
-@item G
-A floating point constant 0.0
-
-@item Q
-A memory address based on Y or Z pointer with displacement.
-@end table
-
-@item Blackfin family---@file{config/bfin/constraints.md}
-@table @code
-@item a
-P register
-
-@item d
-D register
-
-@item z
-A call clobbered P register.
-
-@item q@var{n}
-A single register. If @var{n} is in the range 0 to 7, the corresponding D
-register. If it is @code{A}, then the register P0.
-
-@item D
-Even-numbered D register
-
-@item W
-Odd-numbered D register
-
-@item e
-Accumulator register.
-
-@item A
-Even-numbered accumulator register.
-
-@item B
-Odd-numbered accumulator register.
-
-@item b
-I register
-
-@item v
-B register
-
-@item f
-M register
-
-@item c
-Registers used for circular buffering, i.e.@: I, B, or L registers.
-
-@item C
-The CC register.
-
-@item t
-LT0 or LT1.
-
-@item k
-LC0 or LC1.
-
-@item u
-LB0 or LB1.
-
-@item x
-Any D, P, B, M, I or L register.
-
-@item y
-Additional registers typically used only in prologues and epilogues: RETS,
-RETN, RETI, RETX, RETE, ASTAT, SEQSTAT and USP.
-
-@item w
-Any register except accumulators or CC.
-
-@item Ksh
-Signed 16 bit integer (in the range @minus{}32768 to 32767)
-
-@item Kuh
-Unsigned 16 bit integer (in the range 0 to 65535)
-
-@item Ks7
-Signed 7 bit integer (in the range @minus{}64 to 63)
-
-@item Ku7
-Unsigned 7 bit integer (in the range 0 to 127)
-
-@item Ku5
-Unsigned 5 bit integer (in the range 0 to 31)
-
-@item Ks4
-Signed 4 bit integer (in the range @minus{}8 to 7)
-
-@item Ks3
-Signed 3 bit integer (in the range @minus{}3 to 4)
-
-@item Ku3
-Unsigned 3 bit integer (in the range 0 to 7)
-
-@item P@var{n}
-Constant @var{n}, where @var{n} is a single-digit constant in the range 0 to 4.
-
-@item PA
-An integer equal to one of the MACFLAG_XXX constants that is suitable for
-use with either accumulator.
-
-@item PB
-An integer equal to one of the MACFLAG_XXX constants that is suitable for
-use only with accumulator A1.
-
-@item M1
-Constant 255.
-
-@item M2
-Constant 65535.
-
-@item J
-An integer constant with exactly a single bit set.
-
-@item L
-An integer constant with all bits set except exactly one.
-
-@item H
-
-@item Q
-Any SYMBOL_REF.
-@end table
-
-@item C-SKY---@file{config/csky/constraints.md}
-@table @code
-
-@item a
-The mini registers r0 - r7.
-
-@item b
-The low registers r0 - r15.
-
-@item c
-C register.
-
-@item y
-HI and LO registers.
-
-@item l
-LO register.
-
-@item h
-HI register.
-
-@item v
-Vector registers.
-
-@item z
-Stack pointer register (SP).
-
-@item Q
-A memory address which uses a base register with a short offset
-or with a index register with its scale.
-
-@item W
-A memory address which uses a base register with a index register
-with its scale.
-@end table
-
-@ifset INTERNALS
-The C-SKY back end supports a large set of additional constraints
-that are only useful for instruction selection or splitting rather
-than inline asm, such as constraints representing constant integer
-ranges accepted by particular instruction encodings.
-Refer to the source code for details.
-@end ifset
-
-@item Epiphany---@file{config/epiphany/constraints.md}
-@table @code
-@item U16
-An unsigned 16-bit constant.
-
-@item K
-An unsigned 5-bit constant.
-
-@item L
-A signed 11-bit constant.
-
-@item Cm1
-A signed 11-bit constant added to @minus{}1.
-Can only match when the @option{-m1reg-@var{reg}} option is active.
-
-@item Cl1
-Left-shift of @minus{}1, i.e., a bit mask with a block of leading ones, the rest
-being a block of trailing zeroes.
-Can only match when the @option{-m1reg-@var{reg}} option is active.
-
-@item Cr1
-Right-shift of @minus{}1, i.e., a bit mask with a trailing block of ones, the
-rest being zeroes. Or to put it another way, one less than a power of two.
-Can only match when the @option{-m1reg-@var{reg}} option is active.
-
-@item Cal
-Constant for arithmetic/logical operations.
-This is like @code{i}, except that for position independent code,
-no symbols / expressions needing relocations are allowed.
-
-@item Csy
-Symbolic constant for call/jump instruction.
-
-@item Rcs
-The register class usable in short insns. This is a register class
-constraint, and can thus drive register allocation.
-This constraint won't match unless @option{-mprefer-short-insn-regs} is
-in effect.
-
-@item Rsc
-The register class of registers that can be used to hold a
-sibcall call address. I.e., a caller-saved register.
-
-@item Rct
-Core control register class.
-
-@item Rgs
-The register group usable in short insns.
-This constraint does not use a register class, so that it only
-passively matches suitable registers, and doesn't drive register allocation.
-
-@ifset INTERNALS
-@item Car
-Constant suitable for the addsi3_r pattern. This is a valid offset
-For byte, halfword, or word addressing.
-@end ifset
-
-@item Rra
-Matches the return address if it can be replaced with the link register.
-
-@item Rcc
-Matches the integer condition code register.
-
-@item Sra
-Matches the return address if it is in a stack slot.
-
-@item Cfm
-Matches control register values to switch fp mode, which are encapsulated in
-@code{UNSPEC_FP_MODE}.
-@end table
-
-@item FRV---@file{config/frv/frv.h}
-@table @code
-@item a
-Register in the class @code{ACC_REGS} (@code{acc0} to @code{acc7}).
-
-@item b
-Register in the class @code{EVEN_ACC_REGS} (@code{acc0} to @code{acc7}).
-
-@item c
-Register in the class @code{CC_REGS} (@code{fcc0} to @code{fcc3} and
-@code{icc0} to @code{icc3}).
-
-@item d
-Register in the class @code{GPR_REGS} (@code{gr0} to @code{gr63}).
-
-@item e
-Register in the class @code{EVEN_REGS} (@code{gr0} to @code{gr63}).
-Odd registers are excluded not in the class but through the use of a machine
-mode larger than 4 bytes.
-
-@item f
-Register in the class @code{FPR_REGS} (@code{fr0} to @code{fr63}).
-
-@item h
-Register in the class @code{FEVEN_REGS} (@code{fr0} to @code{fr63}).
-Odd registers are excluded not in the class but through the use of a machine
-mode larger than 4 bytes.
-
-@item l
-Register in the class @code{LR_REG} (the @code{lr} register).
-
-@item q
-Register in the class @code{QUAD_REGS} (@code{gr2} to @code{gr63}).
-Register numbers not divisible by 4 are excluded not in the class but through
-the use of a machine mode larger than 8 bytes.
-
-@item t
-Register in the class @code{ICC_REGS} (@code{icc0} to @code{icc3}).
-
-@item u
-Register in the class @code{FCC_REGS} (@code{fcc0} to @code{fcc3}).
-
-@item v
-Register in the class @code{ICR_REGS} (@code{cc4} to @code{cc7}).
-
-@item w
-Register in the class @code{FCR_REGS} (@code{cc0} to @code{cc3}).
-
-@item x
-Register in the class @code{QUAD_FPR_REGS} (@code{fr0} to @code{fr63}).
-Register numbers not divisible by 4 are excluded not in the class but through
-the use of a machine mode larger than 8 bytes.
-
-@item z
-Register in the class @code{SPR_REGS} (@code{lcr} and @code{lr}).
-
-@item A
-Register in the class @code{QUAD_ACC_REGS} (@code{acc0} to @code{acc7}).
-
-@item B
-Register in the class @code{ACCG_REGS} (@code{accg0} to @code{accg7}).
-
-@item C
-Register in the class @code{CR_REGS} (@code{cc0} to @code{cc7}).
-
-@item G
-Floating point constant zero
-
-@item I
-6-bit signed integer constant
-
-@item J
-10-bit signed integer constant
-
-@item L
-16-bit signed integer constant
-
-@item M
-16-bit unsigned integer constant
-
-@item N
-12-bit signed integer constant that is negative---i.e.@: in the
-range of @minus{}2048 to @minus{}1
-
-@item O
-Constant zero
-
-@item P
-12-bit signed integer constant that is greater than zero---i.e.@: in the
-range of 1 to 2047.
-
-@end table
-
-@item FT32---@file{config/ft32/constraints.md}
-@table @code
-@item A
-An absolute address
-
-@item B
-An offset address
-
-@item W
-A register indirect memory operand
-
-@item e
-An offset address.
-
-@item f
-An offset address.
-
-@item O
-The constant zero or one
-
-@item I
-A 16-bit signed constant (@minus{}32768 @dots{} 32767)
-
-@item w
-A bitfield mask suitable for bext or bins
-
-@item x
-An inverted bitfield mask suitable for bext or bins
-
-@item L
-A 16-bit unsigned constant, multiple of 4 (0 @dots{} 65532)
-
-@item S
-A 20-bit signed constant (@minus{}524288 @dots{} 524287)
-
-@item b
-A constant for a bitfield width (1 @dots{} 16)
-
-@item KA
-A 10-bit signed constant (@minus{}512 @dots{} 511)
-
-@end table
-
-@item Hewlett-Packard PA-RISC---@file{config/pa/pa.h}
-@table @code
-@item a
-General register 1
-
-@item f
-Floating point register
-
-@item q
-Shift amount register
-
-@item x
-Floating point register (deprecated)
-
-@item y
-Upper floating point register (32-bit), floating point register (64-bit)
-
-@item Z
-Any register
-
-@item I
-Signed 11-bit integer constant
-
-@item J
-Signed 14-bit integer constant
-
-@item K
-Integer constant that can be deposited with a @code{zdepi} instruction
-
-@item L
-Signed 5-bit integer constant
-
-@item M
-Integer constant 0
-
-@item N
-Integer constant that can be loaded with a @code{ldil} instruction
-
-@item O
-Integer constant whose value plus one is a power of 2
-
-@item P
-Integer constant that can be used for @code{and} operations in @code{depi}
-and @code{extru} instructions
-
-@item S
-Integer constant 31
-
-@item U
-Integer constant 63
-
-@item G
-Floating-point constant 0.0
-
-@item A
-A @code{lo_sum} data-linkage-table memory operand
-
-@item Q
-A memory operand that can be used as the destination operand of an
-integer store instruction
-
-@item R
-A scaled or unscaled indexed memory operand
-
-@item T
-A memory operand for floating-point loads and stores
-
-@item W
-A register indirect memory operand
-@end table
-
-@item Intel IA-64---@file{config/ia64/ia64.h}
-@table @code
-@item a
-General register @code{r0} to @code{r3} for @code{addl} instruction
-
-@item b
-Branch register
-
-@item c
-Predicate register (@samp{c} as in ``conditional'')
-
-@item d
-Application register residing in M-unit
-
-@item e
-Application register residing in I-unit
-
-@item f
-Floating-point register
-
-@item m
-Memory operand. If used together with @samp{<} or @samp{>},
-the operand can have postincrement and postdecrement which
-require printing with @samp{%Pn} on IA-64.
-
-@item G
-Floating-point constant 0.0 or 1.0
-
-@item I
-14-bit signed integer constant
-
-@item J
-22-bit signed integer constant
-
-@item K
-8-bit signed integer constant for logical instructions
-
-@item L
-8-bit adjusted signed integer constant for compare pseudo-ops
-
-@item M
-6-bit unsigned integer constant for shift counts
-
-@item N
-9-bit signed integer constant for load and store postincrements
-
-@item O
-The constant zero
-
-@item P
-0 or @minus{}1 for @code{dep} instruction
-
-@item Q
-Non-volatile memory for floating-point loads and stores
-
-@item R
-Integer constant in the range 1 to 4 for @code{shladd} instruction
-
-@item S
-Memory operand except postincrement and postdecrement. This is
-now roughly the same as @samp{m} when not used together with @samp{<}
-or @samp{>}.
-@end table
-
-@item M32C---@file{config/m32c/m32c.cc}
-@table @code
-@item Rsp
-@itemx Rfb
-@itemx Rsb
-@samp{$sp}, @samp{$fb}, @samp{$sb}.
-
-@item Rcr
-Any control register, when they're 16 bits wide (nothing if control
-registers are 24 bits wide)
-
-@item Rcl
-Any control register, when they're 24 bits wide.
-
-@item R0w
-@itemx R1w
-@itemx R2w
-@itemx R3w
-$r0, $r1, $r2, $r3.
-
-@item R02
-$r0 or $r2, or $r2r0 for 32 bit values.
-
-@item R13
-$r1 or $r3, or $r3r1 for 32 bit values.
-
-@item Rdi
-A register that can hold a 64 bit value.
-
-@item Rhl
-$r0 or $r1 (registers with addressable high/low bytes)
-
-@item R23
-$r2 or $r3
-
-@item Raa
-Address registers
-
-@item Raw
-Address registers when they're 16 bits wide.
-
-@item Ral
-Address registers when they're 24 bits wide.
-
-@item Rqi
-Registers that can hold QI values.
-
-@item Rad
-Registers that can be used with displacements ($a0, $a1, $sb).
-
-@item Rsi
-Registers that can hold 32 bit values.
-
-@item Rhi
-Registers that can hold 16 bit values.
-
-@item Rhc
-Registers chat can hold 16 bit values, including all control
-registers.
-
-@item Rra
-$r0 through R1, plus $a0 and $a1.
-
-@item Rfl
-The flags register.
-
-@item Rmm
-The memory-based pseudo-registers $mem0 through $mem15.
-
-@item Rpi
-Registers that can hold pointers (16 bit registers for r8c, m16c; 24
-bit registers for m32cm, m32c).
-
-@item Rpa
-Matches multiple registers in a PARALLEL to form a larger register.
-Used to match function return values.
-
-@item Is3
-@minus{}8 @dots{} 7
-
-@item IS1
-@minus{}128 @dots{} 127
-
-@item IS2
-@minus{}32768 @dots{} 32767
-
-@item IU2
-0 @dots{} 65535
-
-@item In4
-@minus{}8 @dots{} @minus{}1 or 1 @dots{} 8
-
-@item In5
-@minus{}16 @dots{} @minus{}1 or 1 @dots{} 16
-
-@item In6
-@minus{}32 @dots{} @minus{}1 or 1 @dots{} 32
-
-@item IM2
-@minus{}65536 @dots{} @minus{}1
-
-@item Ilb
-An 8 bit value with exactly one bit set.
-
-@item Ilw
-A 16 bit value with exactly one bit set.
-
-@item Sd
-The common src/dest memory addressing modes.
-
-@item Sa
-Memory addressed using $a0 or $a1.
-
-@item Si
-Memory addressed with immediate addresses.
-
-@item Ss
-Memory addressed using the stack pointer ($sp).
-
-@item Sf
-Memory addressed using the frame base register ($fb).
-
-@item Ss
-Memory addressed using the small base register ($sb).
-
-@item S1
-$r1h
-@end table
-
-@item LoongArch---@file{config/loongarch/constraints.md}
-@table @code
-@item f
-A floating-point register (if available).
-@item k
-A memory operand whose address is formed by a base register and
-(optionally scaled) index register.
-@item l
-A signed 16-bit constant.
-@item m
-A memory operand whose address is formed by a base register and offset
-that is suitable for use in instructions with the same addressing mode
-as @code{st.w} and @code{ld.w}.
-@item I
-A signed 12-bit constant (for arithmetic instructions).
-@item K
-An unsigned 12-bit constant (for logic instructions).
-@item ZB
-An address that is held in a general-purpose register.
-The offset is zero.
-@item ZC
-A memory operand whose address is formed by a base register and offset
-that is suitable for use in instructions with the same addressing mode
-as @code{ll.w} and @code{sc.w}.
-@end table
-
-@item MicroBlaze---@file{config/microblaze/constraints.md}
-@table @code
-@item d
-A general register (@code{r0} to @code{r31}).
-
-@item z
-A status register (@code{rmsr}, @code{$fcc1} to @code{$fcc7}).
-
-@end table
-
-@item MIPS---@file{config/mips/constraints.md}
-@table @code
-@item d
-A general-purpose register. This is equivalent to @code{r} unless
-generating MIPS16 code, in which case the MIPS16 register set is used.
-
-@item f
-A floating-point register (if available).
-
-@item h
-Formerly the @code{hi} register. This constraint is no longer supported.
-
-@item l
-The @code{lo} register. Use this register to store values that are
-no bigger than a word.
-
-@item x
-The concatenated @code{hi} and @code{lo} registers. Use this register
-to store doubleword values.
-
-@item c
-A register suitable for use in an indirect jump. This will always be
-@code{$25} for @option{-mabicalls}.
-
-@item v
-Register @code{$3}. Do not use this constraint in new code;
-it is retained only for compatibility with glibc.
-
-@item y
-Equivalent to @code{r}; retained for backwards compatibility.
-
-@item z
-A floating-point condition code register.
-
-@item I
-A signed 16-bit constant (for arithmetic instructions).
-
-@item J
-Integer zero.
-
-@item K
-An unsigned 16-bit constant (for logic instructions).
-
-@item L
-A signed 32-bit constant in which the lower 16 bits are zero.
-Such constants can be loaded using @code{lui}.
-
-@item M
-A constant that cannot be loaded using @code{lui}, @code{addiu}
-or @code{ori}.
-
-@item N
-A constant in the range @minus{}65535 to @minus{}1 (inclusive).
-
-@item O
-A signed 15-bit constant.
-
-@item P
-A constant in the range 1 to 65535 (inclusive).
-
-@item G
-Floating-point zero.
-
-@item R
-An address that can be used in a non-macro load or store.
-
-@item ZC
-A memory operand whose address is formed by a base register and offset
-that is suitable for use in instructions with the same addressing mode
-as @code{ll} and @code{sc}.
-
-@item ZD
-An address suitable for a @code{prefetch} instruction, or for any other
-instruction with the same addressing mode as @code{prefetch}.
-@end table
-
-@item Motorola 680x0---@file{config/m68k/constraints.md}
-@table @code
-@item a
-Address register
-
-@item d
-Data register
-
-@item f
-68881 floating-point register, if available
-
-@item I
-Integer in the range 1 to 8
-
-@item J
-16-bit signed number
-
-@item K
-Signed number whose magnitude is greater than 0x80
-
-@item L
-Integer in the range @minus{}8 to @minus{}1
-
-@item M
-Signed number whose magnitude is greater than 0x100
-
-@item N
-Range 24 to 31, rotatert:SI 8 to 1 expressed as rotate
-
-@item O
-16 (for rotate using swap)
-
-@item P
-Range 8 to 15, rotatert:HI 8 to 1 expressed as rotate
-
-@item R
-Numbers that mov3q can handle
-
-@item G
-Floating point constant that is not a 68881 constant
-
-@item S
-Operands that satisfy 'm' when -mpcrel is in effect
-
-@item T
-Operands that satisfy 's' when -mpcrel is not in effect
-
-@item Q
-Address register indirect addressing mode
-
-@item U
-Register offset addressing
-
-@item W
-const_call_operand
-
-@item Cs
-symbol_ref or const
-
-@item Ci
-const_int
-
-@item C0
-const_int 0
-
-@item Cj
-Range of signed numbers that don't fit in 16 bits
-
-@item Cmvq
-Integers valid for mvq
-
-@item Capsw
-Integers valid for a moveq followed by a swap
-
-@item Cmvz
-Integers valid for mvz
-
-@item Cmvs
-Integers valid for mvs
-
-@item Ap
-push_operand
-
-@item Ac
-Non-register operands allowed in clr
-
-@end table
-
-@item Moxie---@file{config/moxie/constraints.md}
-@table @code
-@item A
-An absolute address
-
-@item B
-An offset address
-
-@item W
-A register indirect memory operand
-
-@item I
-A constant in the range of 0 to 255.
-
-@item N
-A constant in the range of 0 to @minus{}255.
-
-@end table
-
-@item MSP430--@file{config/msp430/constraints.md}
-@table @code
-
-@item R12
-Register R12.
-
-@item R13
-Register R13.
-
-@item K
-Integer constant 1.
-
-@item L
-Integer constant -1^20..1^19.
-
-@item M
-Integer constant 1-4.
-
-@item Ya
-Memory references which do not require an extended MOVX instruction.
-
-@item Yl
-Memory reference, labels only.
-
-@item Ys
-Memory reference, stack only.
-
-@end table
-
-@item NDS32---@file{config/nds32/constraints.md}
-@table @code
-@item w
-LOW register class $r0 to $r7 constraint for V3/V3M ISA.
-@item l
-LOW register class $r0 to $r7.
-@item d
-MIDDLE register class $r0 to $r11, $r16 to $r19.
-@item h
-HIGH register class $r12 to $r14, $r20 to $r31.
-@item t
-Temporary assist register $ta (i.e.@: $r15).
-@item k
-Stack register $sp.
-@item Iu03
-Unsigned immediate 3-bit value.
-@item In03
-Negative immediate 3-bit value in the range of @minus{}7--0.
-@item Iu04
-Unsigned immediate 4-bit value.
-@item Is05
-Signed immediate 5-bit value.
-@item Iu05
-Unsigned immediate 5-bit value.
-@item In05
-Negative immediate 5-bit value in the range of @minus{}31--0.
-@item Ip05
-Unsigned immediate 5-bit value for movpi45 instruction with range 16--47.
-@item Iu06
-Unsigned immediate 6-bit value constraint for addri36.sp instruction.
-@item Iu08
-Unsigned immediate 8-bit value.
-@item Iu09
-Unsigned immediate 9-bit value.
-@item Is10
-Signed immediate 10-bit value.
-@item Is11
-Signed immediate 11-bit value.
-@item Is15
-Signed immediate 15-bit value.
-@item Iu15
-Unsigned immediate 15-bit value.
-@item Ic15
-A constant which is not in the range of imm15u but ok for bclr instruction.
-@item Ie15
-A constant which is not in the range of imm15u but ok for bset instruction.
-@item It15
-A constant which is not in the range of imm15u but ok for btgl instruction.
-@item Ii15
-A constant whose compliment value is in the range of imm15u
-and ok for bitci instruction.
-@item Is16
-Signed immediate 16-bit value.
-@item Is17
-Signed immediate 17-bit value.
-@item Is19
-Signed immediate 19-bit value.
-@item Is20
-Signed immediate 20-bit value.
-@item Ihig
-The immediate value that can be simply set high 20-bit.
-@item Izeb
-The immediate value 0xff.
-@item Izeh
-The immediate value 0xffff.
-@item Ixls
-The immediate value 0x01.
-@item Ix11
-The immediate value 0x7ff.
-@item Ibms
-The immediate value with power of 2.
-@item Ifex
-The immediate value with power of 2 minus 1.
-@item U33
-Memory constraint for 333 format.
-@item U45
-Memory constraint for 45 format.
-@item U37
-Memory constraint for 37 format.
-@end table
-
-@item Nios II family---@file{config/nios2/constraints.md}
-@table @code
-
-@item I
-Integer that is valid as an immediate operand in an
-instruction taking a signed 16-bit number. Range
-@minus{}32768 to 32767.
-
-@item J
-Integer that is valid as an immediate operand in an
-instruction taking an unsigned 16-bit number. Range
-0 to 65535.
-
-@item K
-Integer that is valid as an immediate operand in an
-instruction taking only the upper 16-bits of a
-32-bit number. Range 32-bit numbers with the lower
-16-bits being 0.
-
-@item L
-Integer that is valid as an immediate operand for a
-shift instruction. Range 0 to 31.
-
-@item M
-Integer that is valid as an immediate operand for
-only the value 0. Can be used in conjunction with
-the format modifier @code{z} to use @code{r0}
-instead of @code{0} in the assembly output.
-
-@item N
-Integer that is valid as an immediate operand for
-a custom instruction opcode. Range 0 to 255.
-
-@item P
-An immediate operand for R2 andchi/andci instructions.
-
-@item S
-Matches immediates which are addresses in the small
-data section and therefore can be added to @code{gp}
-as a 16-bit immediate to re-create their 32-bit value.
-
-@item U
-Matches constants suitable as an operand for the rdprs and
-cache instructions.
-
-@item v
-A memory operand suitable for Nios II R2 load/store
-exclusive instructions.
-
-@item w
-A memory operand suitable for load/store IO and cache
-instructions.
-
-@ifset INTERNALS
-@item T
-A @code{const} wrapped @code{UNSPEC} expression,
-representing a supported PIC or TLS relocation.
-@end ifset
-
-@end table
-
-@item OpenRISC---@file{config/or1k/constraints.md}
-@table @code
-@item I
-Integer that is valid as an immediate operand in an
-instruction taking a signed 16-bit number. Range
-@minus{}32768 to 32767.
-
-@item K
-Integer that is valid as an immediate operand in an
-instruction taking an unsigned 16-bit number. Range
-0 to 65535.
-
-@item M
-Signed 16-bit constant shifted left 16 bits. (Used with @code{l.movhi})
-
-@item O
-Zero
-
-@ifset INTERNALS
-@item c
-Register usable for sibcalls.
-@end ifset
-
-@end table
-
-@item PDP-11---@file{config/pdp11/constraints.md}
-@table @code
-@item a
-Floating point registers AC0 through AC3. These can be loaded from/to
-memory with a single instruction.
-
-@item d
-Odd numbered general registers (R1, R3, R5). These are used for
-16-bit multiply operations.
-
-@item D
-A memory reference that is encoded within the opcode, but not
-auto-increment or auto-decrement.
-
-@item f
-Any of the floating point registers (AC0 through AC5).
-
-@item G
-Floating point constant 0.
-
-@item h
-Floating point registers AC4 and AC5. These cannot be loaded from/to
-memory with a single instruction.
-
-@item I
-An integer constant that fits in 16 bits.
-
-@item J
-An integer constant whose low order 16 bits are zero.
-
-@item K
-An integer constant that does not meet the constraints for codes
-@samp{I} or @samp{J}.
-
-@item L
-The integer constant 1.
-
-@item M
-The integer constant @minus{}1.
-
-@item N
-The integer constant 0.
-
-@item O
-Integer constants 0 through 3; shifts by these
-amounts are handled as multiple single-bit shifts rather than a single
-variable-length shift.
-
-@item Q
-A memory reference which requires an additional word (address or
-offset) after the opcode.
-
-@item R
-A memory reference that is encoded within the opcode.
-
-@end table
-
-@item PowerPC and IBM RS6000---@file{config/rs6000/constraints.md}
-@table @code
-@item r
-A general purpose register (GPR), @code{r0}@dots{}@code{r31}.
-
-@item b
-A base register. Like @code{r}, but @code{r0} is not allowed, so
-@code{r1}@dots{}@code{r31}.
-
-@item f
-A floating point register (FPR), @code{f0}@dots{}@code{f31}.
-
-@item d
-A floating point register. This is the same as @code{f} nowadays;
-historically @code{f} was for single-precision and @code{d} was for
-double-precision floating point.
-
-@item v
-An Altivec vector register (VR), @code{v0}@dots{}@code{v31}.
-
-@item wa
-A VSX register (VSR), @code{vs0}@dots{}@code{vs63}. This is either an
-FPR (@code{vs0}@dots{}@code{vs31} are @code{f0}@dots{}@code{f31}) or a VR
-(@code{vs32}@dots{}@code{vs63} are @code{v0}@dots{}@code{v31}).
-
-When using @code{wa}, you should use the @code{%x} output modifier, so that
-the correct register number is printed. For example:
-
-@smallexample
-asm ("xvadddp %x0,%x1,%x2"
- : "=wa" (v1)
- : "wa" (v2), "wa" (v3));
-@end smallexample
-
-You should not use @code{%x} for @code{v} operands:
-
-@smallexample
-asm ("xsaddqp %0,%1,%2"
- : "=v" (v1)
- : "v" (v2), "v" (v3));
-@end smallexample
-
-@ifset INTERNALS
-@item h
-A special register (@code{vrsave}, @code{ctr}, or @code{lr}).
-@end ifset
-
-@item c
-The count register, @code{ctr}.
-
-@item l
-The link register, @code{lr}.
-
-@item x
-Condition register field 0, @code{cr0}.
-
-@item y
-Any condition register field, @code{cr0}@dots{}@code{cr7}.
-
-@ifset INTERNALS
-@item z
-The carry bit, @code{XER[CA]}.
-
-@item we
-Like @code{wa}, if @option{-mpower9-vector} and @option{-m64} are used;
-otherwise, @code{NO_REGS}.
-
-@item wn
-No register (@code{NO_REGS}).
-
-@item wr
-Like @code{r}, if @option{-mpowerpc64} is used; otherwise, @code{NO_REGS}.
-
-@item wx
-Like @code{d}, if @option{-mpowerpc-gfxopt} is used; otherwise, @code{NO_REGS}.
-
-@item wA
-Like @code{b}, if @option{-mpowerpc64} is used; otherwise, @code{NO_REGS}.
-
-@item wB
-Signed 5-bit constant integer that can be loaded into an Altivec register.
-
-@item wE
-Vector constant that can be loaded with the XXSPLTIB instruction.
-
-@item wF
-Memory operand suitable for power8 GPR load fusion.
-
-@item wL
-Int constant that is the element number mfvsrld accesses in a vector.
-
-@item wM
-Match vector constant with all 1's if the XXLORC instruction is available.
-
-@item wO
-Memory operand suitable for the ISA 3.0 vector d-form instructions.
-
-@item wQ
-Memory operand suitable for the load/store quad instructions.
-
-@item wS
-Vector constant that can be loaded with XXSPLTIB & sign extension.
-
-@item wY
-A memory operand for a DS-form instruction.
-
-@item wZ
-An indexed or indirect memory operand, ignoring the bottom 4 bits.
-@end ifset
-
-@item I
-A signed 16-bit constant.
-
-@item J
-An unsigned 16-bit constant shifted left 16 bits (use @code{L} instead
-for @code{SImode} constants).
-
-@item K
-An unsigned 16-bit constant.
-
-@item L
-A signed 16-bit constant shifted left 16 bits.
-
-@ifset INTERNALS
-@item M
-An integer constant greater than 31.
-
-@item N
-An exact power of 2.
-
-@item O
-The integer constant zero.
-
-@item P
-A constant whose negation is a signed 16-bit constant.
-@end ifset
-
-@item eI
-A signed 34-bit integer constant if prefixed instructions are supported.
-
-@item eP
-A scalar floating point constant or a vector constant that can be
-loaded to a VSX register with one prefixed instruction.
-
-@item eQ
-An IEEE 128-bit constant that can be loaded into a VSX register with
-the @code{lxvkq} instruction.
-
-@ifset INTERNALS
-@item G
-A floating point constant that can be loaded into a register with one
-instruction per word.
-
-@item H
-A floating point constant that can be loaded into a register using
-three instructions.
-@end ifset
-
-@item m
-A memory operand.
-Normally, @code{m} does not allow addresses that update the base register.
-If the @code{<} or @code{>} constraint is also used, they are allowed and
-therefore on PowerPC targets in that case it is only safe
-to use @code{m<>} in an @code{asm} statement if that @code{asm} statement
-accesses the operand exactly once. The @code{asm} statement must also
-use @code{%U@var{<opno>}} as a placeholder for the ``update'' flag in the
-corresponding load or store instruction. For example:
-
-@smallexample
-asm ("st%U0 %1,%0" : "=m<>" (mem) : "r" (val));
-@end smallexample
-
-is correct but:
-
-@smallexample
-asm ("st %1,%0" : "=m<>" (mem) : "r" (val));
-@end smallexample
-
-is not.
-
-@ifset INTERNALS
-@item es
-A ``stable'' memory operand; that is, one which does not include any
-automodification of the base register. This used to be useful when
-@code{m} allowed automodification of the base register, but as those
-are now only allowed when @code{<} or @code{>} is used, @code{es} is
-basically the same as @code{m} without @code{<} and @code{>}.
-@end ifset
-
-@item Q
-A memory operand addressed by just a base register.
-
-@ifset INTERNALS
-@item Y
-A memory operand for a DQ-form instruction.
-@end ifset
-
-@item Z
-A memory operand accessed with indexed or indirect addressing.
-
-@ifset INTERNALS
-@item R
-An AIX TOC entry.
-@end ifset
-
-@item a
-An indexed or indirect address.
-
-@ifset INTERNALS
-@item U
-A V.4 small data reference.
-
-@item W
-A vector constant that does not require memory.
-
-@item j
-The zero vector constant.
-@end ifset
-
-@end table
-
-@item PRU---@file{config/pru/constraints.md}
-@table @code
-@item I
-An unsigned 8-bit integer constant.
-
-@item J
-An unsigned 16-bit integer constant.
-
-@item L
-An unsigned 5-bit integer constant (for shift counts).
-
-@item T
-A text segment (program memory) constant label.
-
-@item Z
-Integer constant zero.
-
-@end table
-
-@item RL78---@file{config/rl78/constraints.md}
-@table @code
-
-@item Int3
-An integer constant in the range 1 @dots{} 7.
-@item Int8
-An integer constant in the range 0 @dots{} 255.
-@item J
-An integer constant in the range @minus{}255 @dots{} 0
-@item K
-The integer constant 1.
-@item L
-The integer constant -1.
-@item M
-The integer constant 0.
-@item N
-The integer constant 2.
-@item O
-The integer constant -2.
-@item P
-An integer constant in the range 1 @dots{} 15.
-@item Qbi
-The built-in compare types--eq, ne, gtu, ltu, geu, and leu.
-@item Qsc
-The synthetic compare types--gt, lt, ge, and le.
-@item Wab
-A memory reference with an absolute address.
-@item Wbc
-A memory reference using @code{BC} as a base register, with an optional offset.
-@item Wca
-A memory reference using @code{AX}, @code{BC}, @code{DE}, or @code{HL} for the address, for calls.
-@item Wcv
-A memory reference using any 16-bit register pair for the address, for calls.
-@item Wd2
-A memory reference using @code{DE} as a base register, with an optional offset.
-@item Wde
-A memory reference using @code{DE} as a base register, without any offset.
-@item Wfr
-Any memory reference to an address in the far address space.
-@item Wh1
-A memory reference using @code{HL} as a base register, with an optional one-byte offset.
-@item Whb
-A memory reference using @code{HL} as a base register, with @code{B} or @code{C} as the index register.
-@item Whl
-A memory reference using @code{HL} as a base register, without any offset.
-@item Ws1
-A memory reference using @code{SP} as a base register, with an optional one-byte offset.
-@item Y
-Any memory reference to an address in the near address space.
-@item A
-The @code{AX} register.
-@item B
-The @code{BC} register.
-@item D
-The @code{DE} register.
-@item R
-@code{A} through @code{L} registers.
-@item S
-The @code{SP} register.
-@item T
-The @code{HL} register.
-@item Z08W
-The 16-bit @code{R8} register.
-@item Z10W
-The 16-bit @code{R10} register.
-@item Zint
-The registers reserved for interrupts (@code{R24} to @code{R31}).
-@item a
-The @code{A} register.
-@item b
-The @code{B} register.
-@item c
-The @code{C} register.
-@item d
-The @code{D} register.
-@item e
-The @code{E} register.
-@item h
-The @code{H} register.
-@item l
-The @code{L} register.
-@item v
-The virtual registers.
-@item w
-The @code{PSW} register.
-@item x
-The @code{X} register.
-
-@end table
-
-@item RISC-V---@file{config/riscv/constraints.md}
-@table @code
-
-@item f
-A floating-point register (if available).
-
-@item I
-An I-type 12-bit signed immediate.
-
-@item J
-Integer zero.
-
-@item K
-A 5-bit unsigned immediate for CSR access instructions.
-
-@item A
-An address that is held in a general-purpose register.
-
-@item S
-A constraint that matches an absolute symbolic address.
-
-@end table
-
-@item RX---@file{config/rx/constraints.md}
-@table @code
-@item Q
-An address which does not involve register indirect addressing or
-pre/post increment/decrement addressing.
-
-@item Symbol
-A symbol reference.
-
-@item Int08
-A constant in the range @minus{}256 to 255, inclusive.
-
-@item Sint08
-A constant in the range @minus{}128 to 127, inclusive.
-
-@item Sint16
-A constant in the range @minus{}32768 to 32767, inclusive.
-
-@item Sint24
-A constant in the range @minus{}8388608 to 8388607, inclusive.
-
-@item Uint04
-A constant in the range 0 to 15, inclusive.
-
-@end table
-
-@item S/390 and zSeries---@file{config/s390/s390.h}
-@table @code
-@item a
-Address register (general purpose register except r0)
-
-@item c
-Condition code register
-
-@item d
-Data register (arbitrary general purpose register)
-
-@item f
-Floating-point register
-
-@item I
-Unsigned 8-bit constant (0--255)
-
-@item J
-Unsigned 12-bit constant (0--4095)
-
-@item K
-Signed 16-bit constant (@minus{}32768--32767)
-
-@item L
-Value appropriate as displacement.
-@table @code
-@item (0..4095)
-for short displacement
-@item (@minus{}524288..524287)
-for long displacement
-@end table
-
-@item M
-Constant integer with a value of 0x7fffffff.
-
-@item N
-Multiple letter constraint followed by 4 parameter letters.
-@table @code
-@item 0..9:
-number of the part counting from most to least significant
-@item H,Q:
-mode of the part
-@item D,S,H:
-mode of the containing operand
-@item 0,F:
-value of the other parts (F---all bits set)
-@end table
-The constraint matches if the specified part of a constant
-has a value different from its other parts.
-
-@item Q
-Memory reference without index register and with short displacement.
-
-@item R
-Memory reference with index register and short displacement.
-
-@item S
-Memory reference without index register but with long displacement.
-
-@item T
-Memory reference with index register and long displacement.
-
-@item U
-Pointer with short displacement.
-
-@item W
-Pointer with long displacement.
-
-@item Y
-Shift count operand.
-
-@end table
-
-@need 1000
-@item SPARC---@file{config/sparc/sparc.h}
-@table @code
-@item f
-Floating-point register on the SPARC-V8 architecture and
-lower floating-point register on the SPARC-V9 architecture.
-
-@item e
-Floating-point register. It is equivalent to @samp{f} on the
-SPARC-V8 architecture and contains both lower and upper
-floating-point registers on the SPARC-V9 architecture.
-
-@item c
-Floating-point condition code register.
-
-@item d
-Lower floating-point register. It is only valid on the SPARC-V9
-architecture when the Visual Instruction Set is available.
-
-@item b
-Floating-point register. It is only valid on the SPARC-V9 architecture
-when the Visual Instruction Set is available.
-
-@item h
-64-bit global or out register for the SPARC-V8+ architecture.
-
-@item C
-The constant all-ones, for floating-point.
-
-@item A
-Signed 5-bit constant
-
-@item D
-A vector constant
-
-@item I
-Signed 13-bit constant
-
-@item J
-Zero
-
-@item K
-32-bit constant with the low 12 bits clear (a constant that can be
-loaded with the @code{sethi} instruction)
-
-@item L
-A constant in the range supported by @code{movcc} instructions (11-bit
-signed immediate)
-
-@item M
-A constant in the range supported by @code{movrcc} instructions (10-bit
-signed immediate)
-
-@item N
-Same as @samp{K}, except that it verifies that bits that are not in the
-lower 32-bit range are all zero. Must be used instead of @samp{K} for
-modes wider than @code{SImode}
-
-@item O
-The constant 4096
-
-@item G
-Floating-point zero
-
-@item H
-Signed 13-bit constant, sign-extended to 32 or 64 bits
-
-@item P
-The constant -1
-
-@item Q
-Floating-point constant whose integral representation can
-be moved into an integer register using a single sethi
-instruction
-
-@item R
-Floating-point constant whose integral representation can
-be moved into an integer register using a single mov
-instruction
-
-@item S
-Floating-point constant whose integral representation can
-be moved into an integer register using a high/lo_sum
-instruction sequence
-
-@item T
-Memory address aligned to an 8-byte boundary
-
-@item U
-Even register
-
-@item W
-Memory address for @samp{e} constraint registers
-
-@item w
-Memory address with only a base register
-
-@item Y
-Vector zero
-
-@end table
-
-@item TI C6X family---@file{config/c6x/constraints.md}
-@table @code
-@item a
-Register file A (A0--A31).
-
-@item b
-Register file B (B0--B31).
-
-@item A
-Predicate registers in register file A (A0--A2 on C64X and
-higher, A1 and A2 otherwise).
-
-@item B
-Predicate registers in register file B (B0--B2).
-
-@item C
-A call-used register in register file B (B0--B9, B16--B31).
-
-@item Da
-Register file A, excluding predicate registers (A3--A31,
-plus A0 if not C64X or higher).
-
-@item Db
-Register file B, excluding predicate registers (B3--B31).
-
-@item Iu4
-Integer constant in the range 0 @dots{} 15.
-
-@item Iu5
-Integer constant in the range 0 @dots{} 31.
-
-@item In5
-Integer constant in the range @minus{}31 @dots{} 0.
-
-@item Is5
-Integer constant in the range @minus{}16 @dots{} 15.
-
-@item I5x
-Integer constant that can be the operand of an ADDA or a SUBA insn.
-
-@item IuB
-Integer constant in the range 0 @dots{} 65535.
-
-@item IsB
-Integer constant in the range @minus{}32768 @dots{} 32767.
-
-@item IsC
-Integer constant in the range @math{-2^{20}} @dots{} @math{2^{20} - 1}.
-
-@item Jc
-Integer constant that is a valid mask for the clr instruction.
-
-@item Js
-Integer constant that is a valid mask for the set instruction.
-
-@item Q
-Memory location with A base register.
-
-@item R
-Memory location with B base register.
-
-@ifset INTERNALS
-@item S0
-On C64x+ targets, a GP-relative small data reference.
-
-@item S1
-Any kind of @code{SYMBOL_REF}, for use in a call address.
-
-@item Si
-Any kind of immediate operand, unless it matches the S0 constraint.
-
-@item T
-Memory location with B base register, but not using a long offset.
-
-@item W
-A memory operand with an address that cannot be used in an unaligned access.
-
-@end ifset
-@item Z
-Register B14 (aka DP).
-
-@end table
-
-@item Visium---@file{config/visium/constraints.md}
-@table @code
-@item b
-EAM register @code{mdb}
-
-@item c
-EAM register @code{mdc}
-
-@item f
-Floating point register
-
-@ifset INTERNALS
-@item k
-Register for sibcall optimization
-@end ifset
-
-@item l
-General register, but not @code{r29}, @code{r30} and @code{r31}
-
-@item t
-Register @code{r1}
-
-@item u
-Register @code{r2}
-
-@item v
-Register @code{r3}
-
-@item G
-Floating-point constant 0.0
-
-@item J
-Integer constant in the range 0 .. 65535 (16-bit immediate)
-
-@item K
-Integer constant in the range 1 .. 31 (5-bit immediate)
-
-@item L
-Integer constant in the range @minus{}65535 .. @minus{}1 (16-bit negative immediate)
-
-@item M
-Integer constant @minus{}1
-
-@item O
-Integer constant 0
-
-@item P
-Integer constant 32
-@end table
-
-@item x86 family---@file{config/i386/constraints.md}
-@table @code
-@item R
-Legacy register---the eight integer registers available on all
-i386 processors (@code{a}, @code{b}, @code{c}, @code{d},
-@code{si}, @code{di}, @code{bp}, @code{sp}).
-
-@item q
-Any register accessible as @code{@var{r}l}. In 32-bit mode, @code{a},
-@code{b}, @code{c}, and @code{d}; in 64-bit mode, any integer register.
-
-@item Q
-Any register accessible as @code{@var{r}h}: @code{a}, @code{b},
-@code{c}, and @code{d}.
-
-@ifset INTERNALS
-@item l
-Any register that can be used as the index in a base+index memory
-access: that is, any general register except the stack pointer.
-@end ifset
-
-@item a
-The @code{a} register.
-
-@item b
-The @code{b} register.
-
-@item c
-The @code{c} register.
-
-@item d
-The @code{d} register.
-
-@item S
-The @code{si} register.
-
-@item D
-The @code{di} register.
-
-@item A
-The @code{a} and @code{d} registers. This class is used for instructions
-that return double word results in the @code{ax:dx} register pair. Single
-word values will be allocated either in @code{ax} or @code{dx}.
-For example on i386 the following implements @code{rdtsc}:
-
-@smallexample
-unsigned long long rdtsc (void)
-@{
- unsigned long long tick;
- __asm__ __volatile__("rdtsc":"=A"(tick));
- return tick;
-@}
-@end smallexample
-
-This is not correct on x86-64 as it would allocate tick in either @code{ax}
-or @code{dx}. You have to use the following variant instead:
-
-@smallexample
-unsigned long long rdtsc (void)
-@{
- unsigned int tickl, tickh;
- __asm__ __volatile__("rdtsc":"=a"(tickl),"=d"(tickh));
- return ((unsigned long long)tickh << 32)|tickl;
-@}
-@end smallexample
-
-@item U
-The call-clobbered integer registers.
-
-@item f
-Any 80387 floating-point (stack) register.
-
-@item t
-Top of 80387 floating-point stack (@code{%st(0)}).
-
-@item u
-Second from top of 80387 floating-point stack (@code{%st(1)}).
-
-@ifset INTERNALS
-@item Yk
-Any mask register that can be used as a predicate, i.e.@: @code{k1-k7}.
-
-@item k
-Any mask register.
-@end ifset
-
-@item y
-Any MMX register.
-
-@item x
-Any SSE register.
-
-@item v
-Any EVEX encodable SSE register (@code{%xmm0-%xmm31}).
-
-@ifset INTERNALS
-@item w
-Any bound register.
-@end ifset
-
-@item Yz
-First SSE register (@code{%xmm0}).
-
-@ifset INTERNALS
-@item Yi
-Any SSE register, when SSE2 and inter-unit moves are enabled.
-
-@item Yj
-Any SSE register, when SSE2 and inter-unit moves from vector registers are enabled.
-
-@item Ym
-Any MMX register, when inter-unit moves are enabled.
-
-@item Yn
-Any MMX register, when inter-unit moves from vector registers are enabled.
-
-@item Yp
-Any integer register when @code{TARGET_PARTIAL_REG_STALL} is disabled.
-
-@item Ya
-Any integer register when zero extensions with @code{AND} are disabled.
-
-@item Yb
-Any register that can be used as the GOT base when calling@*
-@code{___tls_get_addr}: that is, any general register except @code{a}
-and @code{sp} registers, for @option{-fno-plt} if linker supports it.
-Otherwise, @code{b} register.
-
-@item Yf
-Any x87 register when 80387 floating-point arithmetic is enabled.
-
-@item Yr
-Lower SSE register when avoiding REX prefix and all SSE registers otherwise.
-
-@item Yv
-For AVX512VL, any EVEX-encodable SSE register (@code{%xmm0-%xmm31}),
-otherwise any SSE register.
-
-@item Yh
-Any EVEX-encodable SSE register, that has number factor of four.
-
-@item Bf
-Flags register operand.
-
-@item Bg
-GOT memory operand.
-
-@item Bm
-Vector memory operand.
-
-@item Bc
-Constant memory operand.
-
-@item Bn
-Memory operand without REX prefix.
-
-@item Bs
-Sibcall memory operand.
-
-@item Bw
-Call memory operand.
-
-@item Bz
-Constant call address operand.
-
-@item BC
-SSE constant -1 operand.
-@end ifset
-
-@item I
-Integer constant in the range 0 @dots{} 31, for 32-bit shifts.
-
-@item J
-Integer constant in the range 0 @dots{} 63, for 64-bit shifts.
-
-@item K
-Signed 8-bit integer constant.
-
-@item L
-@code{0xFF} or @code{0xFFFF}, for andsi as a zero-extending move.
-
-@item M
-0, 1, 2, or 3 (shifts for the @code{lea} instruction).
-
-@item N
-Unsigned 8-bit integer constant (for @code{in} and @code{out}
-instructions).
-
-@ifset INTERNALS
-@item O
-Integer constant in the range 0 @dots{} 127, for 128-bit shifts.
-@end ifset
-
-@item G
-Standard 80387 floating point constant.
-
-@item C
-SSE constant zero operand.
-
-@item e
-32-bit signed integer constant, or a symbolic reference known
-to fit that range (for immediate operands in sign-extending x86-64
-instructions).
-
-@item We
-32-bit signed integer constant, or a symbolic reference known
-to fit that range (for sign-extending conversion operations that
-require non-@code{VOIDmode} immediate operands).
-
-@item Wz
-32-bit unsigned integer constant, or a symbolic reference known
-to fit that range (for zero-extending conversion operations that
-require non-@code{VOIDmode} immediate operands).
-
-@item Wd
-128-bit integer constant where both the high and low 64-bit word
-satisfy the @code{e} constraint.
-
-@item Z
-32-bit unsigned integer constant, or a symbolic reference known
-to fit that range (for immediate operands in zero-extending x86-64
-instructions).
-
-@item Tv
-VSIB address operand.
-
-@item Ts
-Address operand without segment register.
-
-@end table
-
-@item Xstormy16---@file{config/stormy16/stormy16.h}
-@table @code
-@item a
-Register r0.
-
-@item b
-Register r1.
-
-@item c
-Register r2.
-
-@item d
-Register r8.
-
-@item e
-Registers r0 through r7.
-
-@item t
-Registers r0 and r1.
-
-@item y
-The carry register.
-
-@item z
-Registers r8 and r9.
-
-@item I
-A constant between 0 and 3 inclusive.
-
-@item J
-A constant that has exactly one bit set.
-
-@item K
-A constant that has exactly one bit clear.
-
-@item L
-A constant between 0 and 255 inclusive.
-
-@item M
-A constant between @minus{}255 and 0 inclusive.
-
-@item N
-A constant between @minus{}3 and 0 inclusive.
-
-@item O
-A constant between 1 and 4 inclusive.
-
-@item P
-A constant between @minus{}4 and @minus{}1 inclusive.
-
-@item Q
-A memory reference that is a stack push.
-
-@item R
-A memory reference that is a stack pop.
-
-@item S
-A memory reference that refers to a constant address of known value.
-
-@item T
-The register indicated by Rx (not implemented yet).
-
-@item U
-A constant that is not between 2 and 15 inclusive.
-
-@item Z
-The constant 0.
-
-@end table
-
-@item Xtensa---@file{config/xtensa/constraints.md}
-@table @code
-@item a
-General-purpose 32-bit register
-
-@item b
-One-bit boolean register
-
-@item A
-MAC16 40-bit accumulator register
-
-@item I
-Signed 12-bit integer constant, for use in MOVI instructions
-
-@item J
-Signed 8-bit integer constant, for use in ADDI instructions
-
-@item K
-Integer constant valid for BccI instructions
-
-@item L
-Unsigned constant valid for BccUI instructions
-
-@end table
-
-@end table
-
-@ifset INTERNALS
-@node Disable Insn Alternatives
-@subsection Disable insn alternatives using the @code{enabled} attribute
-@cindex enabled
-
-There are three insn attributes that may be used to selectively disable
-instruction alternatives:
-
-@table @code
-@item enabled
-Says whether an alternative is available on the current subtarget.
-
-@item preferred_for_size
-Says whether an enabled alternative should be used in code that is
-optimized for size.
-
-@item preferred_for_speed
-Says whether an enabled alternative should be used in code that is
-optimized for speed.
-@end table
-
-All these attributes should use @code{(const_int 1)} to allow an alternative
-or @code{(const_int 0)} to disallow it. The attributes must be a static
-property of the subtarget; they cannot for example depend on the
-current operands, on the current optimization level, on the location
-of the insn within the body of a loop, on whether register allocation
-has finished, or on the current compiler pass.
-
-The @code{enabled} attribute is a correctness property. It tells GCC to act
-as though the disabled alternatives were never defined in the first place.
-This is useful when adding new instructions to an existing pattern in
-cases where the new instructions are only available for certain cpu
-architecture levels (typically mapped to the @code{-march=} command-line
-option).
-
-In contrast, the @code{preferred_for_size} and @code{preferred_for_speed}
-attributes are strong optimization hints rather than correctness properties.
-@code{preferred_for_size} tells GCC which alternatives to consider when
-adding or modifying an instruction that GCC wants to optimize for size.
-@code{preferred_for_speed} does the same thing for speed. Note that things
-like code motion can lead to cases where code optimized for size uses
-alternatives that are not preferred for size, and similarly for speed.
-
-Although @code{define_insn}s can in principle specify the @code{enabled}
-attribute directly, it is often clearer to have subsiduary attributes
-for each architectural feature of interest. The @code{define_insn}s
-can then use these subsiduary attributes to say which alternatives
-require which features. The example below does this for @code{cpu_facility}.
-
-E.g. the following two patterns could easily be merged using the @code{enabled}
-attribute:
-
-@smallexample
-
-(define_insn "*movdi_old"
- [(set (match_operand:DI 0 "register_operand" "=d")
- (match_operand:DI 1 "register_operand" " d"))]
- "!TARGET_NEW"
- "lgr %0,%1")
-
-(define_insn "*movdi_new"
- [(set (match_operand:DI 0 "register_operand" "=d,f,d")
- (match_operand:DI 1 "register_operand" " d,d,f"))]
- "TARGET_NEW"
- "@@
- lgr %0,%1
- ldgr %0,%1
- lgdr %0,%1")
-
-@end smallexample
-
-to:
-
-@smallexample
-
-(define_insn "*movdi_combined"
- [(set (match_operand:DI 0 "register_operand" "=d,f,d")
- (match_operand:DI 1 "register_operand" " d,d,f"))]
- ""
- "@@
- lgr %0,%1
- ldgr %0,%1
- lgdr %0,%1"
- [(set_attr "cpu_facility" "*,new,new")])
-
-@end smallexample
-
-with the @code{enabled} attribute defined like this:
-
-@smallexample
-
-(define_attr "cpu_facility" "standard,new" (const_string "standard"))
-
-(define_attr "enabled" ""
- (cond [(eq_attr "cpu_facility" "standard") (const_int 1)
- (and (eq_attr "cpu_facility" "new")
- (ne (symbol_ref "TARGET_NEW") (const_int 0)))
- (const_int 1)]
- (const_int 0)))
-
-@end smallexample
-
-@end ifset
-
-@ifset INTERNALS
-@node Define Constraints
-@subsection Defining Machine-Specific Constraints
-@cindex defining constraints
-@cindex constraints, defining
-
-Machine-specific constraints fall into two categories: register and
-non-register constraints. Within the latter category, constraints
-which allow subsets of all possible memory or address operands should
-be specially marked, to give @code{reload} more information.
-
-Machine-specific constraints can be given names of arbitrary length,
-but they must be entirely composed of letters, digits, underscores
-(@samp{_}), and angle brackets (@samp{< >}). Like C identifiers, they
-must begin with a letter or underscore.
-
-In order to avoid ambiguity in operand constraint strings, no
-constraint can have a name that begins with any other constraint's
-name. For example, if @code{x} is defined as a constraint name,
-@code{xy} may not be, and vice versa. As a consequence of this rule,
-no constraint may begin with one of the generic constraint letters:
-@samp{E F V X g i m n o p r s}.
-
-Register constraints correspond directly to register classes.
-@xref{Register Classes}. There is thus not much flexibility in their
-definitions.
-
-@deffn {MD Expression} define_register_constraint name regclass docstring
-All three arguments are string constants.
-@var{name} is the name of the constraint, as it will appear in
-@code{match_operand} expressions. If @var{name} is a multi-letter
-constraint its length shall be the same for all constraints starting
-with the same letter. @var{regclass} can be either the
-name of the corresponding register class (@pxref{Register Classes}),
-or a C expression which evaluates to the appropriate register class.
-If it is an expression, it must have no side effects, and it cannot
-look at the operand. The usual use of expressions is to map some
-register constraints to @code{NO_REGS} when the register class
-is not available on a given subarchitecture.
-
-@var{docstring} is a sentence documenting the meaning of the
-constraint. Docstrings are explained further below.
-@end deffn
-
-Non-register constraints are more like predicates: the constraint
-definition gives a boolean expression which indicates whether the
-constraint matches.
-
-@deffn {MD Expression} define_constraint name docstring exp
-The @var{name} and @var{docstring} arguments are the same as for
-@code{define_register_constraint}, but note that the docstring comes
-immediately after the name for these expressions. @var{exp} is an RTL
-expression, obeying the same rules as the RTL expressions in predicate
-definitions. @xref{Defining Predicates}, for details. If it
-evaluates true, the constraint matches; if it evaluates false, it
-doesn't. Constraint expressions should indicate which RTL codes they
-might match, just like predicate expressions.
-
-@code{match_test} C expressions have access to the
-following variables:
-
-@table @var
-@item op
-The RTL object defining the operand.
-@item mode
-The machine mode of @var{op}.
-@item ival
-@samp{INTVAL (@var{op})}, if @var{op} is a @code{const_int}.
-@item hval
-@samp{CONST_DOUBLE_HIGH (@var{op})}, if @var{op} is an integer
-@code{const_double}.
-@item lval
-@samp{CONST_DOUBLE_LOW (@var{op})}, if @var{op} is an integer
-@code{const_double}.
-@item rval
-@samp{CONST_DOUBLE_REAL_VALUE (@var{op})}, if @var{op} is a floating-point
-@code{const_double}.
-@end table
-
-The @var{*val} variables should only be used once another piece of the
-expression has verified that @var{op} is the appropriate kind of RTL
-object.
-@end deffn
-
-Most non-register constraints should be defined with
-@code{define_constraint}. The remaining two definition expressions
-are only appropriate for constraints that should be handled specially
-by @code{reload} if they fail to match.
-
-@deffn {MD Expression} define_memory_constraint name docstring exp
-Use this expression for constraints that match a subset of all memory
-operands: that is, @code{reload} can make them match by converting the
-operand to the form @samp{@w{(mem (reg @var{X}))}}, where @var{X} is a
-base register (from the register class specified by
-@code{BASE_REG_CLASS}, @pxref{Register Classes}).
-
-For example, on the S/390, some instructions do not accept arbitrary
-memory references, but only those that do not make use of an index
-register. The constraint letter @samp{Q} is defined to represent a
-memory address of this type. If @samp{Q} is defined with
-@code{define_memory_constraint}, a @samp{Q} constraint can handle any
-memory operand, because @code{reload} knows it can simply copy the
-memory address into a base register if required. This is analogous to
-the way an @samp{o} constraint can handle any memory operand.
-
-The syntax and semantics are otherwise identical to
-@code{define_constraint}.
-@end deffn
-
-@deffn {MD Expression} define_special_memory_constraint name docstring exp
-Use this expression for constraints that match a subset of all memory
-operands: that is, @code{reload} cannot make them match by reloading
-the address as it is described for @code{define_memory_constraint} or
-such address reload is undesirable with the performance point of view.
-
-For example, @code{define_special_memory_constraint} can be useful if
-specifically aligned memory is necessary or desirable for some insn
-operand.
-
-The syntax and semantics are otherwise identical to
-@code{define_memory_constraint}.
-@end deffn
-
-@deffn {MD Expression} define_relaxed_memory_constraint name docstring exp
-The test expression in a @code{define_memory_constraint} can assume
-that @code{TARGET_LEGITIMATE_ADDRESS_P} holds for the address inside
-a @code{mem} rtx and so it does not need to test this condition itself.
-In other words, a @code{define_memory_constraint} test of the form:
-
-@smallexample
-(match_test "mem")
-@end smallexample
-
-is enough to test whether an rtx is a @code{mem} @emph{and} whether
-its address satisfies @code{TARGET_MEM_CONSTRAINT} (which is usually
-@samp{'m'}). Thus the conditions imposed by a @code{define_memory_constraint}
-always apply on top of the conditions imposed by @code{TARGET_MEM_CONSTRAINT}.
-
-However, it is sometimes useful to define memory constraints that allow
-addresses beyond those accepted by @code{TARGET_LEGITIMATE_ADDRESS_P}.
-@code{define_relaxed_memory_constraint} exists for this case.
-The test expression in a @code{define_relaxed_memory_constraint} is
-applied with no preconditions, so that the expression can determine
-``from scratch'' exactly which addresses are valid and which are not.
-
-The syntax and semantics are otherwise identical to
-@code{define_memory_constraint}.
-@end deffn
-
-@deffn {MD Expression} define_address_constraint name docstring exp
-Use this expression for constraints that match a subset of all address
-operands: that is, @code{reload} can make the constraint match by
-converting the operand to the form @samp{@w{(reg @var{X})}}, again
-with @var{X} a base register.
-
-Constraints defined with @code{define_address_constraint} can only be
-used with the @code{address_operand} predicate, or machine-specific
-predicates that work the same way. They are treated analogously to
-the generic @samp{p} constraint.
-
-The syntax and semantics are otherwise identical to
-@code{define_constraint}.
-@end deffn
-
-For historical reasons, names beginning with the letters @samp{G H}
-are reserved for constraints that match only @code{const_double}s, and
-names beginning with the letters @samp{I J K L M N O P} are reserved
-for constraints that match only @code{const_int}s. This may change in
-the future. For the time being, constraints with these names must be
-written in a stylized form, so that @code{genpreds} can tell you did
-it correctly:
-
-@smallexample
-@group
-(define_constraint "[@var{GHIJKLMNOP}]@dots{}"
- "@var{doc}@dots{}"
- (and (match_code "const_int") ; @r{@code{const_double} for G/H}
- @var{condition}@dots{})) ; @r{usually a @code{match_test}}
-@end group
-@end smallexample
-@c the semicolons line up in the formatted manual
-
-It is fine to use names beginning with other letters for constraints
-that match @code{const_double}s or @code{const_int}s.
-
-Each docstring in a constraint definition should be one or more complete
-sentences, marked up in Texinfo format. @emph{They are currently unused.}
-In the future they will be copied into the GCC manual, in @ref{Machine
-Constraints}, replacing the hand-maintained tables currently found in
-that section. Also, in the future the compiler may use this to give
-more helpful diagnostics when poor choice of @code{asm} constraints
-causes a reload failure.
-
-If you put the pseudo-Texinfo directive @samp{@@internal} at the
-beginning of a docstring, then (in the future) it will appear only in
-the internals manual's version of the machine-specific constraint tables.
-Use this for constraints that should not appear in @code{asm} statements.
-
-@node C Constraint Interface
-@subsection Testing constraints from C
-@cindex testing constraints
-@cindex constraints, testing
-
-It is occasionally useful to test a constraint from C code rather than
-implicitly via the constraint string in a @code{match_operand}. The
-generated file @file{tm_p.h} declares a few interfaces for working
-with constraints. At present these are defined for all constraints
-except @code{g} (which is equivalent to @code{general_operand}).
-
-Some valid constraint names are not valid C identifiers, so there is a
-mangling scheme for referring to them from C@. Constraint names that
-do not contain angle brackets or underscores are left unchanged.
-Underscores are doubled, each @samp{<} is replaced with @samp{_l}, and
-each @samp{>} with @samp{_g}. Here are some examples:
-
-@c the @c's prevent double blank lines in the printed manual.
-@example
-@multitable {Original} {Mangled}
-@item @strong{Original} @tab @strong{Mangled} @c
-@item @code{x} @tab @code{x} @c
-@item @code{P42x} @tab @code{P42x} @c
-@item @code{P4_x} @tab @code{P4__x} @c
-@item @code{P4>x} @tab @code{P4_gx} @c
-@item @code{P4>>} @tab @code{P4_g_g} @c
-@item @code{P4_g>} @tab @code{P4__g_g} @c
-@end multitable
-@end example
-
-Throughout this section, the variable @var{c} is either a constraint
-in the abstract sense, or a constant from @code{enum constraint_num};
-the variable @var{m} is a mangled constraint name (usually as part of
-a larger identifier).
-
-@deftp Enum constraint_num
-For each constraint except @code{g}, there is a corresponding
-enumeration constant: @samp{CONSTRAINT_} plus the mangled name of the
-constraint. Functions that take an @code{enum constraint_num} as an
-argument expect one of these constants.
-@end deftp
-
-@deftypefun {inline bool} satisfies_constraint_@var{m} (rtx @var{exp})
-For each non-register constraint @var{m} except @code{g}, there is
-one of these functions; it returns @code{true} if @var{exp} satisfies the
-constraint. These functions are only visible if @file{rtl.h} was included
-before @file{tm_p.h}.
-@end deftypefun
-
-@deftypefun bool constraint_satisfied_p (rtx @var{exp}, enum constraint_num @var{c})
-Like the @code{satisfies_constraint_@var{m}} functions, but the
-constraint to test is given as an argument, @var{c}. If @var{c}
-specifies a register constraint, this function will always return
-@code{false}.
-@end deftypefun
-
-@deftypefun {enum reg_class} reg_class_for_constraint (enum constraint_num @var{c})
-Returns the register class associated with @var{c}. If @var{c} is not
-a register constraint, or those registers are not available for the
-currently selected subtarget, returns @code{NO_REGS}.
-@end deftypefun
-
-Here is an example use of @code{satisfies_constraint_@var{m}}. In
-peephole optimizations (@pxref{Peephole Definitions}), operand
-constraint strings are ignored, so if there are relevant constraints,
-they must be tested in the C condition. In the example, the
-optimization is applied if operand 2 does @emph{not} satisfy the
-@samp{K} constraint. (This is a simplified version of a peephole
-definition from the i386 machine description.)
-
-@smallexample
-(define_peephole2
- [(match_scratch:SI 3 "r")
- (set (match_operand:SI 0 "register_operand" "")
- (mult:SI (match_operand:SI 1 "memory_operand" "")
- (match_operand:SI 2 "immediate_operand" "")))]
-
- "!satisfies_constraint_K (operands[2])"
-
- [(set (match_dup 3) (match_dup 1))
- (set (match_dup 0) (mult:SI (match_dup 3) (match_dup 2)))]
-
- "")
-@end smallexample
-
-@node Standard Names
-@section Standard Pattern Names For Generation
-@cindex standard pattern names
-@cindex pattern names
-@cindex names, pattern
-
-Here is a table of the instruction names that are meaningful in the RTL
-generation pass of the compiler. Giving one of these names to an
-instruction pattern tells the RTL generation pass that it can use the
-pattern to accomplish a certain task.
-
-@table @asis
-@cindex @code{mov@var{m}} instruction pattern
-@item @samp{mov@var{m}}
-Here @var{m} stands for a two-letter machine mode name, in lowercase.
-This instruction pattern moves data with that machine mode from operand
-1 to operand 0. For example, @samp{movsi} moves full-word data.
-
-If operand 0 is a @code{subreg} with mode @var{m} of a register whose
-own mode is wider than @var{m}, the effect of this instruction is
-to store the specified value in the part of the register that corresponds
-to mode @var{m}. Bits outside of @var{m}, but which are within the
-same target word as the @code{subreg} are undefined. Bits which are
-outside the target word are left unchanged.
-
-This class of patterns is special in several ways. First of all, each
-of these names up to and including full word size @emph{must} be defined,
-because there is no other way to copy a datum from one place to another.
-If there are patterns accepting operands in larger modes,
-@samp{mov@var{m}} must be defined for integer modes of those sizes.
-
-Second, these patterns are not used solely in the RTL generation pass.
-Even the reload pass can generate move insns to copy values from stack
-slots into temporary registers. When it does so, one of the operands is
-a hard register and the other is an operand that can need to be reloaded
-into a register.
-
-@findex force_reg
-Therefore, when given such a pair of operands, the pattern must generate
-RTL which needs no reloading and needs no temporary registers---no
-registers other than the operands. For example, if you support the
-pattern with a @code{define_expand}, then in such a case the
-@code{define_expand} mustn't call @code{force_reg} or any other such
-function which might generate new pseudo registers.
-
-This requirement exists even for subword modes on a RISC machine where
-fetching those modes from memory normally requires several insns and
-some temporary registers.
-
-@findex change_address
-During reload a memory reference with an invalid address may be passed
-as an operand. Such an address will be replaced with a valid address
-later in the reload pass. In this case, nothing may be done with the
-address except to use it as it stands. If it is copied, it will not be
-replaced with a valid address. No attempt should be made to make such
-an address into a valid address and no routine (such as
-@code{change_address}) that will do so may be called. Note that
-@code{general_operand} will fail when applied to such an address.
-
-@findex reload_in_progress
-The global variable @code{reload_in_progress} (which must be explicitly
-declared if required) can be used to determine whether such special
-handling is required.
-
-The variety of operands that have reloads depends on the rest of the
-machine description, but typically on a RISC machine these can only be
-pseudo registers that did not get hard registers, while on other
-machines explicit memory references will get optional reloads.
-
-If a scratch register is required to move an object to or from memory,
-it can be allocated using @code{gen_reg_rtx} prior to life analysis.
-
-If there are cases which need scratch registers during or after reload,
-you must provide an appropriate secondary_reload target hook.
-
-@findex can_create_pseudo_p
-The macro @code{can_create_pseudo_p} can be used to determine if it
-is unsafe to create new pseudo registers. If this variable is nonzero, then
-it is unsafe to call @code{gen_reg_rtx} to allocate a new pseudo.
-
-The constraints on a @samp{mov@var{m}} must permit moving any hard
-register to any other hard register provided that
-@code{TARGET_HARD_REGNO_MODE_OK} permits mode @var{m} in both registers and
-@code{TARGET_REGISTER_MOVE_COST} applied to their classes returns a value
-of 2.
-
-It is obligatory to support floating point @samp{mov@var{m}}
-instructions into and out of any registers that can hold fixed point
-values, because unions and structures (which have modes @code{SImode} or
-@code{DImode}) can be in those registers and they may have floating
-point members.
-
-There may also be a need to support fixed point @samp{mov@var{m}}
-instructions in and out of floating point registers. Unfortunately, I
-have forgotten why this was so, and I don't know whether it is still
-true. If @code{TARGET_HARD_REGNO_MODE_OK} rejects fixed point values in
-floating point registers, then the constraints of the fixed point
-@samp{mov@var{m}} instructions must be designed to avoid ever trying to
-reload into a floating point register.
-
-@cindex @code{reload_in} instruction pattern
-@cindex @code{reload_out} instruction pattern
-@item @samp{reload_in@var{m}}
-@itemx @samp{reload_out@var{m}}
-These named patterns have been obsoleted by the target hook
-@code{secondary_reload}.
-
-Like @samp{mov@var{m}}, but used when a scratch register is required to
-move between operand 0 and operand 1. Operand 2 describes the scratch
-register. See the discussion of the @code{SECONDARY_RELOAD_CLASS}
-macro in @pxref{Register Classes}.
-
-There are special restrictions on the form of the @code{match_operand}s
-used in these patterns. First, only the predicate for the reload
-operand is examined, i.e., @code{reload_in} examines operand 1, but not
-the predicates for operand 0 or 2. Second, there may be only one
-alternative in the constraints. Third, only a single register class
-letter may be used for the constraint; subsequent constraint letters
-are ignored. As a special exception, an empty constraint string
-matches the @code{ALL_REGS} register class. This may relieve ports
-of the burden of defining an @code{ALL_REGS} constraint letter just
-for these patterns.
-
-@cindex @code{movstrict@var{m}} instruction pattern
-@item @samp{movstrict@var{m}}
-Like @samp{mov@var{m}} except that if operand 0 is a @code{subreg}
-with mode @var{m} of a register whose natural mode is wider,
-the @samp{movstrict@var{m}} instruction is guaranteed not to alter
-any of the register except the part which belongs to mode @var{m}.
-
-@cindex @code{movmisalign@var{m}} instruction pattern
-@item @samp{movmisalign@var{m}}
-This variant of a move pattern is designed to load or store a value
-from a memory address that is not naturally aligned for its mode.
-For a store, the memory will be in operand 0; for a load, the memory
-will be in operand 1. The other operand is guaranteed not to be a
-memory, so that it's easy to tell whether this is a load or store.
-
-This pattern is used by the autovectorizer, and when expanding a
-@code{MISALIGNED_INDIRECT_REF} expression.
-
-@cindex @code{load_multiple} instruction pattern
-@item @samp{load_multiple}
-Load several consecutive memory locations into consecutive registers.
-Operand 0 is the first of the consecutive registers, operand 1
-is the first memory location, and operand 2 is a constant: the
-number of consecutive registers.
-
-Define this only if the target machine really has such an instruction;
-do not define this if the most efficient way of loading consecutive
-registers from memory is to do them one at a time.
-
-On some machines, there are restrictions as to which consecutive
-registers can be stored into memory, such as particular starting or
-ending register numbers or only a range of valid counts. For those
-machines, use a @code{define_expand} (@pxref{Expander Definitions})
-and make the pattern fail if the restrictions are not met.
-
-Write the generated insn as a @code{parallel} with elements being a
-@code{set} of one register from the appropriate memory location (you may
-also need @code{use} or @code{clobber} elements). Use a
-@code{match_parallel} (@pxref{RTL Template}) to recognize the insn. See
-@file{rs6000.md} for examples of the use of this insn pattern.
-
-@cindex @samp{store_multiple} instruction pattern
-@item @samp{store_multiple}
-Similar to @samp{load_multiple}, but store several consecutive registers
-into consecutive memory locations. Operand 0 is the first of the
-consecutive memory locations, operand 1 is the first register, and
-operand 2 is a constant: the number of consecutive registers.
-
-@cindex @code{vec_load_lanes@var{m}@var{n}} instruction pattern
-@item @samp{vec_load_lanes@var{m}@var{n}}
-Perform an interleaved load of several vectors from memory operand 1
-into register operand 0. Both operands have mode @var{m}. The register
-operand is viewed as holding consecutive vectors of mode @var{n},
-while the memory operand is a flat array that contains the same number
-of elements. The operation is equivalent to:
-
-@smallexample
-int c = GET_MODE_SIZE (@var{m}) / GET_MODE_SIZE (@var{n});
-for (j = 0; j < GET_MODE_NUNITS (@var{n}); j++)
- for (i = 0; i < c; i++)
- operand0[i][j] = operand1[j * c + i];
-@end smallexample
-
-For example, @samp{vec_load_lanestiv4hi} loads 8 16-bit values
-from memory into a register of mode @samp{TI}@. The register
-contains two consecutive vectors of mode @samp{V4HI}@.
-
-This pattern can only be used if:
-@smallexample
-TARGET_ARRAY_MODE_SUPPORTED_P (@var{n}, @var{c})
-@end smallexample
-is true. GCC assumes that, if a target supports this kind of
-instruction for some mode @var{n}, it also supports unaligned
-loads for vectors of mode @var{n}.
-
-This pattern is not allowed to @code{FAIL}.
-
-@cindex @code{vec_mask_load_lanes@var{m}@var{n}} instruction pattern
-@item @samp{vec_mask_load_lanes@var{m}@var{n}}
-Like @samp{vec_load_lanes@var{m}@var{n}}, but takes an additional
-mask operand (operand 2) that specifies which elements of the destination
-vectors should be loaded. Other elements of the destination
-vectors are set to zero. The operation is equivalent to:
-
-@smallexample
-int c = GET_MODE_SIZE (@var{m}) / GET_MODE_SIZE (@var{n});
-for (j = 0; j < GET_MODE_NUNITS (@var{n}); j++)
- if (operand2[j])
- for (i = 0; i < c; i++)
- operand0[i][j] = operand1[j * c + i];
- else
- for (i = 0; i < c; i++)
- operand0[i][j] = 0;
-@end smallexample
-
-This pattern is not allowed to @code{FAIL}.
-
-@cindex @code{vec_store_lanes@var{m}@var{n}} instruction pattern
-@item @samp{vec_store_lanes@var{m}@var{n}}
-Equivalent to @samp{vec_load_lanes@var{m}@var{n}}, with the memory
-and register operands reversed. That is, the instruction is
-equivalent to:
-
-@smallexample
-int c = GET_MODE_SIZE (@var{m}) / GET_MODE_SIZE (@var{n});
-for (j = 0; j < GET_MODE_NUNITS (@var{n}); j++)
- for (i = 0; i < c; i++)
- operand0[j * c + i] = operand1[i][j];
-@end smallexample
-
-for a memory operand 0 and register operand 1.
-
-This pattern is not allowed to @code{FAIL}.
-
-@cindex @code{vec_mask_store_lanes@var{m}@var{n}} instruction pattern
-@item @samp{vec_mask_store_lanes@var{m}@var{n}}
-Like @samp{vec_store_lanes@var{m}@var{n}}, but takes an additional
-mask operand (operand 2) that specifies which elements of the source
-vectors should be stored. The operation is equivalent to:
-
-@smallexample
-int c = GET_MODE_SIZE (@var{m}) / GET_MODE_SIZE (@var{n});
-for (j = 0; j < GET_MODE_NUNITS (@var{n}); j++)
- if (operand2[j])
- for (i = 0; i < c; i++)
- operand0[j * c + i] = operand1[i][j];
-@end smallexample
-
-This pattern is not allowed to @code{FAIL}.
-
-@cindex @code{gather_load@var{m}@var{n}} instruction pattern
-@item @samp{gather_load@var{m}@var{n}}
-Load several separate memory locations into a vector of mode @var{m}.
-Operand 1 is a scalar base address and operand 2 is a vector of mode @var{n}
-containing offsets from that base. Operand 0 is a destination vector with
-the same number of elements as @var{n}. For each element index @var{i}:
-
-@itemize @bullet
-@item
-extend the offset element @var{i} to address width, using zero
-extension if operand 3 is 1 and sign extension if operand 3 is zero;
-@item
-multiply the extended offset by operand 4;
-@item
-add the result to the base; and
-@item
-load the value at that address into element @var{i} of operand 0.
-@end itemize
-
-The value of operand 3 does not matter if the offsets are already
-address width.
-
-@cindex @code{mask_gather_load@var{m}@var{n}} instruction pattern
-@item @samp{mask_gather_load@var{m}@var{n}}
-Like @samp{gather_load@var{m}@var{n}}, but takes an extra mask operand as
-operand 5. Bit @var{i} of the mask is set if element @var{i}
-of the result should be loaded from memory and clear if element @var{i}
-of the result should be set to zero.
-
-@cindex @code{scatter_store@var{m}@var{n}} instruction pattern
-@item @samp{scatter_store@var{m}@var{n}}
-Store a vector of mode @var{m} into several distinct memory locations.
-Operand 0 is a scalar base address and operand 1 is a vector of mode
-@var{n} containing offsets from that base. Operand 4 is the vector of
-values that should be stored, which has the same number of elements as
-@var{n}. For each element index @var{i}:
-
-@itemize @bullet
-@item
-extend the offset element @var{i} to address width, using zero
-extension if operand 2 is 1 and sign extension if operand 2 is zero;
-@item
-multiply the extended offset by operand 3;
-@item
-add the result to the base; and
-@item
-store element @var{i} of operand 4 to that address.
-@end itemize
-
-The value of operand 2 does not matter if the offsets are already
-address width.
-
-@cindex @code{mask_scatter_store@var{m}@var{n}} instruction pattern
-@item @samp{mask_scatter_store@var{m}@var{n}}
-Like @samp{scatter_store@var{m}@var{n}}, but takes an extra mask operand as
-operand 5. Bit @var{i} of the mask is set if element @var{i}
-of the result should be stored to memory.
-
-@cindex @code{vec_set@var{m}} instruction pattern
-@item @samp{vec_set@var{m}}
-Set given field in the vector value. Operand 0 is the vector to modify,
-operand 1 is new value of field and operand 2 specify the field index.
-
-@cindex @code{vec_extract@var{m}@var{n}} instruction pattern
-@item @samp{vec_extract@var{m}@var{n}}
-Extract given field from the vector value. Operand 1 is the vector, operand 2
-specify field index and operand 0 place to store value into. The
-@var{n} mode is the mode of the field or vector of fields that should be
-extracted, should be either element mode of the vector mode @var{m}, or
-a vector mode with the same element mode and smaller number of elements.
-If @var{n} is a vector mode, the index is counted in units of that mode.
-
-@cindex @code{vec_init@var{m}@var{n}} instruction pattern
-@item @samp{vec_init@var{m}@var{n}}
-Initialize the vector to given values. Operand 0 is the vector to initialize
-and operand 1 is parallel containing values for individual fields. The
-@var{n} mode is the mode of the elements, should be either element mode of
-the vector mode @var{m}, or a vector mode with the same element mode and
-smaller number of elements.
-
-@cindex @code{vec_duplicate@var{m}} instruction pattern
-@item @samp{vec_duplicate@var{m}}
-Initialize vector output operand 0 so that each element has the value given
-by scalar input operand 1. The vector has mode @var{m} and the scalar has
-the mode appropriate for one element of @var{m}.
-
-This pattern only handles duplicates of non-constant inputs. Constant
-vectors go through the @code{mov@var{m}} pattern instead.
-
-This pattern is not allowed to @code{FAIL}.
-
-@cindex @code{vec_series@var{m}} instruction pattern
-@item @samp{vec_series@var{m}}
-Initialize vector output operand 0 so that element @var{i} is equal to
-operand 1 plus @var{i} times operand 2. In other words, create a linear
-series whose base value is operand 1 and whose step is operand 2.
-
-The vector output has mode @var{m} and the scalar inputs have the mode
-appropriate for one element of @var{m}. This pattern is not used for
-floating-point vectors, in order to avoid having to specify the
-rounding behavior for @var{i} > 1.
-
-This pattern is not allowed to @code{FAIL}.
-
-@cindex @code{while_ult@var{m}@var{n}} instruction pattern
-@item @code{while_ult@var{m}@var{n}}
-Set operand 0 to a mask that is true while incrementing operand 1
-gives a value that is less than operand 2, for a vector length up to operand 3.
-Operand 0 has mode @var{n} and operands 1 and 2 are scalar integers of mode
-@var{m}. Operand 3 should be omitted when @var{n} is a vector mode, and
-a @code{CONST_INT} otherwise. The operation for vector modes is equivalent to:
-
-@smallexample
-operand0[0] = operand1 < operand2;
-for (i = 1; i < GET_MODE_NUNITS (@var{n}); i++)
- operand0[i] = operand0[i - 1] && (operand1 + i < operand2);
-@end smallexample
-
-And for non-vector modes the operation is equivalent to:
-
-@smallexample
-operand0[0] = operand1 < operand2;
-for (i = 1; i < operand3; i++)
- operand0[i] = operand0[i - 1] && (operand1 + i < operand2);
-@end smallexample
-
-@cindex @code{check_raw_ptrs@var{m}} instruction pattern
-@item @samp{check_raw_ptrs@var{m}}
-Check whether, given two pointers @var{a} and @var{b} and a length @var{len},
-a write of @var{len} bytes at @var{a} followed by a read of @var{len} bytes
-at @var{b} can be split into interleaved byte accesses
-@samp{@var{a}[0], @var{b}[0], @var{a}[1], @var{b}[1], @dots{}}
-without affecting the dependencies between the bytes. Set operand 0
-to true if the split is possible and false otherwise.
-
-Operands 1, 2 and 3 provide the values of @var{a}, @var{b} and @var{len}
-respectively. Operand 4 is a constant integer that provides the known
-common alignment of @var{a} and @var{b}. All inputs have mode @var{m}.
-
-This split is possible if:
-
-@smallexample
-@var{a} == @var{b} || @var{a} + @var{len} <= @var{b} || @var{b} + @var{len} <= @var{a}
-@end smallexample
-
-You should only define this pattern if the target has a way of accelerating
-the test without having to do the individual comparisons.
-
-@cindex @code{check_war_ptrs@var{m}} instruction pattern
-@item @samp{check_war_ptrs@var{m}}
-Like @samp{check_raw_ptrs@var{m}}, but with the read and write swapped round.
-The split is possible in this case if:
-
-@smallexample
-@var{b} <= @var{a} || @var{a} + @var{len} <= @var{b}
-@end smallexample
-
-@cindex @code{vec_cmp@var{m}@var{n}} instruction pattern
-@item @samp{vec_cmp@var{m}@var{n}}
-Output a vector comparison. Operand 0 of mode @var{n} is the destination for
-predicate in operand 1 which is a signed vector comparison with operands of
-mode @var{m} in operands 2 and 3. Predicate is computed by element-wise
-evaluation of the vector comparison with a truth value of all-ones and a false
-value of all-zeros.
-
-@cindex @code{vec_cmpu@var{m}@var{n}} instruction pattern
-@item @samp{vec_cmpu@var{m}@var{n}}
-Similar to @code{vec_cmp@var{m}@var{n}} but perform unsigned vector comparison.
-
-@cindex @code{vec_cmpeq@var{m}@var{n}} instruction pattern
-@item @samp{vec_cmpeq@var{m}@var{n}}
-Similar to @code{vec_cmp@var{m}@var{n}} but perform equality or non-equality
-vector comparison only. If @code{vec_cmp@var{m}@var{n}}
-or @code{vec_cmpu@var{m}@var{n}} instruction pattern is supported,
-it will be preferred over @code{vec_cmpeq@var{m}@var{n}}, so there is
-no need to define this instruction pattern if the others are supported.
-
-@cindex @code{vcond@var{m}@var{n}} instruction pattern
-@item @samp{vcond@var{m}@var{n}}
-Output a conditional vector move. Operand 0 is the destination to
-receive a combination of operand 1 and operand 2, which are of mode @var{m},
-dependent on the outcome of the predicate in operand 3 which is a signed
-vector comparison with operands of mode @var{n} in operands 4 and 5. The
-modes @var{m} and @var{n} should have the same size. Operand 0
-will be set to the value @var{op1} & @var{msk} | @var{op2} & ~@var{msk}
-where @var{msk} is computed by element-wise evaluation of the vector
-comparison with a truth value of all-ones and a false value of all-zeros.
-
-@cindex @code{vcondu@var{m}@var{n}} instruction pattern
-@item @samp{vcondu@var{m}@var{n}}
-Similar to @code{vcond@var{m}@var{n}} but performs unsigned vector
-comparison.
-
-@cindex @code{vcondeq@var{m}@var{n}} instruction pattern
-@item @samp{vcondeq@var{m}@var{n}}
-Similar to @code{vcond@var{m}@var{n}} but performs equality or
-non-equality vector comparison only. If @code{vcond@var{m}@var{n}}
-or @code{vcondu@var{m}@var{n}} instruction pattern is supported,
-it will be preferred over @code{vcondeq@var{m}@var{n}}, so there is
-no need to define this instruction pattern if the others are supported.
-
-@cindex @code{vcond_mask_@var{m}@var{n}} instruction pattern
-@item @samp{vcond_mask_@var{m}@var{n}}
-Similar to @code{vcond@var{m}@var{n}} but operand 3 holds a pre-computed
-result of vector comparison.
-
-@cindex @code{maskload@var{m}@var{n}} instruction pattern
-@item @samp{maskload@var{m}@var{n}}
-Perform a masked load of vector from memory operand 1 of mode @var{m}
-into register operand 0. Mask is provided in register operand 2 of
-mode @var{n}.
-
-This pattern is not allowed to @code{FAIL}.
-
-@cindex @code{maskstore@var{m}@var{n}} instruction pattern
-@item @samp{maskstore@var{m}@var{n}}
-Perform a masked store of vector from register operand 1 of mode @var{m}
-into memory operand 0. Mask is provided in register operand 2 of
-mode @var{n}.
-
-This pattern is not allowed to @code{FAIL}.
-
-@cindex @code{len_load_@var{m}} instruction pattern
-@item @samp{len_load_@var{m}}
-Load (operand 2 - operand 3) elements from vector memory operand 1
-into vector register operand 0, setting the other elements of
-operand 0 to undefined values. Operands 0 and 1 have mode @var{m},
-which must be a vector mode. Operand 2 has whichever integer mode the
-target prefers. Operand 3 conceptually has mode @code{QI}.
-
-Operand 2 can be a variable or a constant amount. Operand 3 specifies a
-constant bias: it is either a constant 0 or a constant -1. The predicate on
-operand 3 must only accept the bias values that the target actually supports.
-GCC handles a bias of 0 more efficiently than a bias of -1.
-
-If (operand 2 - operand 3) exceeds the number of elements in mode
-@var{m}, the behavior is undefined.
-
-If the target prefers the length to be measured in bytes rather than
-elements, it should only implement this pattern for vectors of @code{QI}
-elements.
-
-This pattern is not allowed to @code{FAIL}.
-
-@cindex @code{len_store_@var{m}} instruction pattern
-@item @samp{len_store_@var{m}}
-Store (operand 2 - operand 3) vector elements from vector register operand 1
-into memory operand 0, leaving the other elements of
-operand 0 unchanged. Operands 0 and 1 have mode @var{m}, which must be
-a vector mode. Operand 2 has whichever integer mode the target prefers.
-Operand 3 conceptually has mode @code{QI}.
-
-Operand 2 can be a variable or a constant amount. Operand 3 specifies a
-constant bias: it is either a constant 0 or a constant -1. The predicate on
-operand 3 must only accept the bias values that the target actually supports.
-GCC handles a bias of 0 more efficiently than a bias of -1.
-
-If (operand 2 - operand 3) exceeds the number of elements in mode
-@var{m}, the behavior is undefined.
-
-If the target prefers the length to be measured in bytes
-rather than elements, it should only implement this pattern for vectors
-of @code{QI} elements.
-
-This pattern is not allowed to @code{FAIL}.
-
-@cindex @code{vec_perm@var{m}} instruction pattern
-@item @samp{vec_perm@var{m}}
-Output a (variable) vector permutation. Operand 0 is the destination
-to receive elements from operand 1 and operand 2, which are of mode
-@var{m}. Operand 3 is the @dfn{selector}. It is an integral mode
-vector of the same width and number of elements as mode @var{m}.
-
-The input elements are numbered from 0 in operand 1 through
-@math{2*@var{N}-1} in operand 2. The elements of the selector must
-be computed modulo @math{2*@var{N}}. Note that if
-@code{rtx_equal_p(operand1, operand2)}, this can be implemented
-with just operand 1 and selector elements modulo @var{N}.
-
-In order to make things easy for a number of targets, if there is no
-@samp{vec_perm} pattern for mode @var{m}, but there is for mode @var{q}
-where @var{q} is a vector of @code{QImode} of the same width as @var{m},
-the middle-end will lower the mode @var{m} @code{VEC_PERM_EXPR} to
-mode @var{q}.
-
-See also @code{TARGET_VECTORIZER_VEC_PERM_CONST}, which performs
-the analogous operation for constant selectors.
-
-@cindex @code{push@var{m}1} instruction pattern
-@item @samp{push@var{m}1}
-Output a push instruction. Operand 0 is value to push. Used only when
-@code{PUSH_ROUNDING} is defined. For historical reason, this pattern may be
-missing and in such case an @code{mov} expander is used instead, with a
-@code{MEM} expression forming the push operation. The @code{mov} expander
-method is deprecated.
-
-@cindex @code{add@var{m}3} instruction pattern
-@item @samp{add@var{m}3}
-Add operand 2 and operand 1, storing the result in operand 0. All operands
-must have mode @var{m}. This can be used even on two-address machines, by
-means of constraints requiring operands 1 and 0 to be the same location.
-
-@cindex @code{ssadd@var{m}3} instruction pattern
-@cindex @code{usadd@var{m}3} instruction pattern
-@cindex @code{sub@var{m}3} instruction pattern
-@cindex @code{sssub@var{m}3} instruction pattern
-@cindex @code{ussub@var{m}3} instruction pattern
-@cindex @code{mul@var{m}3} instruction pattern
-@cindex @code{ssmul@var{m}3} instruction pattern
-@cindex @code{usmul@var{m}3} instruction pattern
-@cindex @code{div@var{m}3} instruction pattern
-@cindex @code{ssdiv@var{m}3} instruction pattern
-@cindex @code{udiv@var{m}3} instruction pattern
-@cindex @code{usdiv@var{m}3} instruction pattern
-@cindex @code{mod@var{m}3} instruction pattern
-@cindex @code{umod@var{m}3} instruction pattern
-@cindex @code{umin@var{m}3} instruction pattern
-@cindex @code{umax@var{m}3} instruction pattern
-@cindex @code{and@var{m}3} instruction pattern
-@cindex @code{ior@var{m}3} instruction pattern
-@cindex @code{xor@var{m}3} instruction pattern
-@item @samp{ssadd@var{m}3}, @samp{usadd@var{m}3}
-@itemx @samp{sub@var{m}3}, @samp{sssub@var{m}3}, @samp{ussub@var{m}3}
-@itemx @samp{mul@var{m}3}, @samp{ssmul@var{m}3}, @samp{usmul@var{m}3}
-@itemx @samp{div@var{m}3}, @samp{ssdiv@var{m}3}
-@itemx @samp{udiv@var{m}3}, @samp{usdiv@var{m}3}
-@itemx @samp{mod@var{m}3}, @samp{umod@var{m}3}
-@itemx @samp{umin@var{m}3}, @samp{umax@var{m}3}
-@itemx @samp{and@var{m}3}, @samp{ior@var{m}3}, @samp{xor@var{m}3}
-Similar, for other arithmetic operations.
-
-@cindex @code{addv@var{m}4} instruction pattern
-@item @samp{addv@var{m}4}
-Like @code{add@var{m}3} but takes a @code{code_label} as operand 3 and
-emits code to jump to it if signed overflow occurs during the addition.
-This pattern is used to implement the built-in functions performing
-signed integer addition with overflow checking.
-
-@cindex @code{subv@var{m}4} instruction pattern
-@cindex @code{mulv@var{m}4} instruction pattern
-@item @samp{subv@var{m}4}, @samp{mulv@var{m}4}
-Similar, for other signed arithmetic operations.
-
-@cindex @code{uaddv@var{m}4} instruction pattern
-@item @samp{uaddv@var{m}4}
-Like @code{addv@var{m}4} but for unsigned addition. That is to
-say, the operation is the same as signed addition but the jump
-is taken only on unsigned overflow.
-
-@cindex @code{usubv@var{m}4} instruction pattern
-@cindex @code{umulv@var{m}4} instruction pattern
-@item @samp{usubv@var{m}4}, @samp{umulv@var{m}4}
-Similar, for other unsigned arithmetic operations.
-
-@cindex @code{addptr@var{m}3} instruction pattern
-@item @samp{addptr@var{m}3}
-Like @code{add@var{m}3} but is guaranteed to only be used for address
-calculations. The expanded code is not allowed to clobber the
-condition code. It only needs to be defined if @code{add@var{m}3}
-sets the condition code. If adds used for address calculations and
-normal adds are not compatible it is required to expand a distinct
-pattern (e.g.@: using an unspec). The pattern is used by LRA to emit
-address calculations. @code{add@var{m}3} is used if
-@code{addptr@var{m}3} is not defined.
-
-@cindex @code{fma@var{m}4} instruction pattern
-@item @samp{fma@var{m}4}
-Multiply operand 2 and operand 1, then add operand 3, storing the
-result in operand 0 without doing an intermediate rounding step. All
-operands must have mode @var{m}. This pattern is used to implement
-the @code{fma}, @code{fmaf}, and @code{fmal} builtin functions from
-the ISO C99 standard.
-
-@cindex @code{fms@var{m}4} instruction pattern
-@item @samp{fms@var{m}4}
-Like @code{fma@var{m}4}, except operand 3 subtracted from the
-product instead of added to the product. This is represented
-in the rtl as
-
-@smallexample
-(fma:@var{m} @var{op1} @var{op2} (neg:@var{m} @var{op3}))
-@end smallexample
-
-@cindex @code{fnma@var{m}4} instruction pattern
-@item @samp{fnma@var{m}4}
-Like @code{fma@var{m}4} except that the intermediate product
-is negated before being added to operand 3. This is represented
-in the rtl as
-
-@smallexample
-(fma:@var{m} (neg:@var{m} @var{op1}) @var{op2} @var{op3})
-@end smallexample
-
-@cindex @code{fnms@var{m}4} instruction pattern
-@item @samp{fnms@var{m}4}
-Like @code{fms@var{m}4} except that the intermediate product
-is negated before subtracting operand 3. This is represented
-in the rtl as
-
-@smallexample
-(fma:@var{m} (neg:@var{m} @var{op1}) @var{op2} (neg:@var{m} @var{op3}))
-@end smallexample
-
-@cindex @code{min@var{m}3} instruction pattern
-@cindex @code{max@var{m}3} instruction pattern
-@item @samp{smin@var{m}3}, @samp{smax@var{m}3}
-Signed minimum and maximum operations. When used with floating point,
-if both operands are zeros, or if either operand is @code{NaN}, then
-it is unspecified which of the two operands is returned as the result.
-
-@cindex @code{fmin@var{m}3} instruction pattern
-@cindex @code{fmax@var{m}3} instruction pattern
-@item @samp{fmin@var{m}3}, @samp{fmax@var{m}3}
-IEEE-conformant minimum and maximum operations. If one operand is a quiet
-@code{NaN}, then the other operand is returned. If both operands are quiet
-@code{NaN}, then a quiet @code{NaN} is returned. In the case when gcc supports
-signaling @code{NaN} (-fsignaling-nans) an invalid floating point exception is
-raised and a quiet @code{NaN} is returned.
-
-All operands have mode @var{m}, which is a scalar or vector
-floating-point mode. These patterns are not allowed to @code{FAIL}.
-
-@cindex @code{reduc_smin_scal_@var{m}} instruction pattern
-@cindex @code{reduc_smax_scal_@var{m}} instruction pattern
-@item @samp{reduc_smin_scal_@var{m}}, @samp{reduc_smax_scal_@var{m}}
-Find the signed minimum/maximum of the elements of a vector. The vector is
-operand 1, and operand 0 is the scalar result, with mode equal to the mode of
-the elements of the input vector.
-
-@cindex @code{reduc_umin_scal_@var{m}} instruction pattern
-@cindex @code{reduc_umax_scal_@var{m}} instruction pattern
-@item @samp{reduc_umin_scal_@var{m}}, @samp{reduc_umax_scal_@var{m}}
-Find the unsigned minimum/maximum of the elements of a vector. The vector is
-operand 1, and operand 0 is the scalar result, with mode equal to the mode of
-the elements of the input vector.
-
-@cindex @code{reduc_fmin_scal_@var{m}} instruction pattern
-@cindex @code{reduc_fmax_scal_@var{m}} instruction pattern
-@item @samp{reduc_fmin_scal_@var{m}}, @samp{reduc_fmax_scal_@var{m}}
-Find the floating-point minimum/maximum of the elements of a vector,
-using the same rules as @code{fmin@var{m}3} and @code{fmax@var{m}3}.
-Operand 1 is a vector of mode @var{m} and operand 0 is the scalar
-result, which has mode @code{GET_MODE_INNER (@var{m})}.
-
-@cindex @code{reduc_plus_scal_@var{m}} instruction pattern
-@item @samp{reduc_plus_scal_@var{m}}
-Compute the sum of the elements of a vector. The vector is operand 1, and
-operand 0 is the scalar result, with mode equal to the mode of the elements of
-the input vector.
-
-@cindex @code{reduc_and_scal_@var{m}} instruction pattern
-@item @samp{reduc_and_scal_@var{m}}
-@cindex @code{reduc_ior_scal_@var{m}} instruction pattern
-@itemx @samp{reduc_ior_scal_@var{m}}
-@cindex @code{reduc_xor_scal_@var{m}} instruction pattern
-@itemx @samp{reduc_xor_scal_@var{m}}
-Compute the bitwise @code{AND}/@code{IOR}/@code{XOR} reduction of the elements
-of a vector of mode @var{m}. Operand 1 is the vector input and operand 0
-is the scalar result. The mode of the scalar result is the same as one
-element of @var{m}.
-
-@cindex @code{extract_last_@var{m}} instruction pattern
-@item @code{extract_last_@var{m}}
-Find the last set bit in mask operand 1 and extract the associated element
-of vector operand 2. Store the result in scalar operand 0. Operand 2
-has vector mode @var{m} while operand 0 has the mode appropriate for one
-element of @var{m}. Operand 1 has the usual mask mode for vectors of mode
-@var{m}; see @code{TARGET_VECTORIZE_GET_MASK_MODE}.
-
-@cindex @code{fold_extract_last_@var{m}} instruction pattern
-@item @code{fold_extract_last_@var{m}}
-If any bits of mask operand 2 are set, find the last set bit, extract
-the associated element from vector operand 3, and store the result
-in operand 0. Store operand 1 in operand 0 otherwise. Operand 3
-has mode @var{m} and operands 0 and 1 have the mode appropriate for
-one element of @var{m}. Operand 2 has the usual mask mode for vectors
-of mode @var{m}; see @code{TARGET_VECTORIZE_GET_MASK_MODE}.
-
-@cindex @code{fold_left_plus_@var{m}} instruction pattern
-@item @code{fold_left_plus_@var{m}}
-Take scalar operand 1 and successively add each element from vector
-operand 2. Store the result in scalar operand 0. The vector has
-mode @var{m} and the scalars have the mode appropriate for one
-element of @var{m}. The operation is strictly in-order: there is
-no reassociation.
-
-@cindex @code{mask_fold_left_plus_@var{m}} instruction pattern
-@item @code{mask_fold_left_plus_@var{m}}
-Like @samp{fold_left_plus_@var{m}}, but takes an additional mask operand
-(operand 3) that specifies which elements of the source vector should be added.
-
-@cindex @code{sdot_prod@var{m}} instruction pattern
-@item @samp{sdot_prod@var{m}}
-
-Compute the sum of the products of two signed elements.
-Operand 1 and operand 2 are of the same mode. Their
-product, which is of a wider mode, is computed and added to operand 3.
-Operand 3 is of a mode equal or wider than the mode of the product. The
-result is placed in operand 0, which is of the same mode as operand 3.
-
-Semantically the expressions perform the multiplication in the following signs
-
-@smallexample
-sdot<signed op0, signed op1, signed op2, signed op3> ==
- op0 = sign-ext (op1) * sign-ext (op2) + op3
-@dots{}
-@end smallexample
-
-@cindex @code{udot_prod@var{m}} instruction pattern
-@item @samp{udot_prod@var{m}}
-
-Compute the sum of the products of two unsigned elements.
-Operand 1 and operand 2 are of the same mode. Their
-product, which is of a wider mode, is computed and added to operand 3.
-Operand 3 is of a mode equal or wider than the mode of the product. The
-result is placed in operand 0, which is of the same mode as operand 3.
-
-Semantically the expressions perform the multiplication in the following signs
-
-@smallexample
-udot<unsigned op0, unsigned op1, unsigned op2, unsigned op3> ==
- op0 = zero-ext (op1) * zero-ext (op2) + op3
-@dots{}
-@end smallexample
-
-@cindex @code{usdot_prod@var{m}} instruction pattern
-@item @samp{usdot_prod@var{m}}
-Compute the sum of the products of elements of different signs.
-Operand 1 must be unsigned and operand 2 signed. Their
-product, which is of a wider mode, is computed and added to operand 3.
-Operand 3 is of a mode equal or wider than the mode of the product. The
-result is placed in operand 0, which is of the same mode as operand 3.
-
-Semantically the expressions perform the multiplication in the following signs
-
-@smallexample
-usdot<signed op0, unsigned op1, signed op2, signed op3> ==
- op0 = ((signed-conv) zero-ext (op1)) * sign-ext (op2) + op3
-@dots{}
-@end smallexample
-
-@cindex @code{ssad@var{m}} instruction pattern
-@item @samp{ssad@var{m}}
-@cindex @code{usad@var{m}} instruction pattern
-@item @samp{usad@var{m}}
-Compute the sum of absolute differences of two signed/unsigned elements.
-Operand 1 and operand 2 are of the same mode. Their absolute difference, which
-is of a wider mode, is computed and added to operand 3. Operand 3 is of a mode
-equal or wider than the mode of the absolute difference. The result is placed
-in operand 0, which is of the same mode as operand 3.
-
-@cindex @code{widen_ssum@var{m3}} instruction pattern
-@item @samp{widen_ssum@var{m3}}
-@cindex @code{widen_usum@var{m3}} instruction pattern
-@itemx @samp{widen_usum@var{m3}}
-Operands 0 and 2 are of the same mode, which is wider than the mode of
-operand 1. Add operand 1 to operand 2 and place the widened result in
-operand 0. (This is used express accumulation of elements into an accumulator
-of a wider mode.)
-
-@cindex @code{smulhs@var{m3}} instruction pattern
-@item @samp{smulhs@var{m3}}
-@cindex @code{umulhs@var{m3}} instruction pattern
-@itemx @samp{umulhs@var{m3}}
-Signed/unsigned multiply high with scale. This is equivalent to the C code:
-@smallexample
-narrow op0, op1, op2;
-@dots{}
-op0 = (narrow) (((wide) op1 * (wide) op2) >> (N / 2 - 1));
-@end smallexample
-where the sign of @samp{narrow} determines whether this is a signed
-or unsigned operation, and @var{N} is the size of @samp{wide} in bits.
-
-@cindex @code{smulhrs@var{m3}} instruction pattern
-@item @samp{smulhrs@var{m3}}
-@cindex @code{umulhrs@var{m3}} instruction pattern
-@itemx @samp{umulhrs@var{m3}}
-Signed/unsigned multiply high with round and scale. This is
-equivalent to the C code:
-@smallexample
-narrow op0, op1, op2;
-@dots{}
-op0 = (narrow) (((((wide) op1 * (wide) op2) >> (N / 2 - 2)) + 1) >> 1);
-@end smallexample
-where the sign of @samp{narrow} determines whether this is a signed
-or unsigned operation, and @var{N} is the size of @samp{wide} in bits.
-
-@cindex @code{sdiv_pow2@var{m3}} instruction pattern
-@item @samp{sdiv_pow2@var{m3}}
-@cindex @code{sdiv_pow2@var{m3}} instruction pattern
-@itemx @samp{sdiv_pow2@var{m3}}
-Signed division by power-of-2 immediate. Equivalent to:
-@smallexample
-signed op0, op1;
-@dots{}
-op0 = op1 / (1 << imm);
-@end smallexample
-
-@cindex @code{vec_shl_insert_@var{m}} instruction pattern
-@item @samp{vec_shl_insert_@var{m}}
-Shift the elements in vector input operand 1 left one element (i.e.@:
-away from element 0) and fill the vacated element 0 with the scalar
-in operand 2. Store the result in vector output operand 0. Operands
-0 and 1 have mode @var{m} and operand 2 has the mode appropriate for
-one element of @var{m}.
-
-@cindex @code{vec_shl_@var{m}} instruction pattern
-@item @samp{vec_shl_@var{m}}
-Whole vector left shift in bits, i.e.@: away from element 0.
-Operand 1 is a vector to be shifted.
-Operand 2 is an integer shift amount in bits.
-Operand 0 is where the resulting shifted vector is stored.
-The output and input vectors should have the same modes.
-
-@cindex @code{vec_shr_@var{m}} instruction pattern
-@item @samp{vec_shr_@var{m}}
-Whole vector right shift in bits, i.e.@: towards element 0.
-Operand 1 is a vector to be shifted.
-Operand 2 is an integer shift amount in bits.
-Operand 0 is where the resulting shifted vector is stored.
-The output and input vectors should have the same modes.
-
-@cindex @code{vec_pack_trunc_@var{m}} instruction pattern
-@item @samp{vec_pack_trunc_@var{m}}
-Narrow (demote) and merge the elements of two vectors. Operands 1 and 2
-are vectors of the same mode having N integral or floating point elements
-of size S@. Operand 0 is the resulting vector in which 2*N elements of
-size S/2 are concatenated after narrowing them down using truncation.
-
-@cindex @code{vec_pack_sbool_trunc_@var{m}} instruction pattern
-@item @samp{vec_pack_sbool_trunc_@var{m}}
-Narrow and merge the elements of two vectors. Operands 1 and 2 are vectors
-of the same type having N boolean elements. Operand 0 is the resulting
-vector in which 2*N elements are concatenated. The last operand (operand 3)
-is the number of elements in the output vector 2*N as a @code{CONST_INT}.
-This instruction pattern is used when all the vector input and output
-operands have the same scalar mode @var{m} and thus using
-@code{vec_pack_trunc_@var{m}} would be ambiguous.
-
-@cindex @code{vec_pack_ssat_@var{m}} instruction pattern
-@cindex @code{vec_pack_usat_@var{m}} instruction pattern
-@item @samp{vec_pack_ssat_@var{m}}, @samp{vec_pack_usat_@var{m}}
-Narrow (demote) and merge the elements of two vectors. Operands 1 and 2
-are vectors of the same mode having N integral elements of size S.
-Operand 0 is the resulting vector in which the elements of the two input
-vectors are concatenated after narrowing them down using signed/unsigned
-saturating arithmetic.
-
-@cindex @code{vec_pack_sfix_trunc_@var{m}} instruction pattern
-@cindex @code{vec_pack_ufix_trunc_@var{m}} instruction pattern
-@item @samp{vec_pack_sfix_trunc_@var{m}}, @samp{vec_pack_ufix_trunc_@var{m}}
-Narrow, convert to signed/unsigned integral type and merge the elements
-of two vectors. Operands 1 and 2 are vectors of the same mode having N
-floating point elements of size S@. Operand 0 is the resulting vector
-in which 2*N elements of size S/2 are concatenated.
-
-@cindex @code{vec_packs_float_@var{m}} instruction pattern
-@cindex @code{vec_packu_float_@var{m}} instruction pattern
-@item @samp{vec_packs_float_@var{m}}, @samp{vec_packu_float_@var{m}}
-Narrow, convert to floating point type and merge the elements
-of two vectors. Operands 1 and 2 are vectors of the same mode having N
-signed/unsigned integral elements of size S@. Operand 0 is the resulting vector
-in which 2*N elements of size S/2 are concatenated.
-
-@cindex @code{vec_unpacks_hi_@var{m}} instruction pattern
-@cindex @code{vec_unpacks_lo_@var{m}} instruction pattern
-@item @samp{vec_unpacks_hi_@var{m}}, @samp{vec_unpacks_lo_@var{m}}
-Extract and widen (promote) the high/low part of a vector of signed
-integral or floating point elements. The input vector (operand 1) has N
-elements of size S@. Widen (promote) the high/low elements of the vector
-using signed or floating point extension and place the resulting N/2
-values of size 2*S in the output vector (operand 0).
-
-@cindex @code{vec_unpacku_hi_@var{m}} instruction pattern
-@cindex @code{vec_unpacku_lo_@var{m}} instruction pattern
-@item @samp{vec_unpacku_hi_@var{m}}, @samp{vec_unpacku_lo_@var{m}}
-Extract and widen (promote) the high/low part of a vector of unsigned
-integral elements. The input vector (operand 1) has N elements of size S.
-Widen (promote) the high/low elements of the vector using zero extension and
-place the resulting N/2 values of size 2*S in the output vector (operand 0).
-
-@cindex @code{vec_unpacks_sbool_hi_@var{m}} instruction pattern
-@cindex @code{vec_unpacks_sbool_lo_@var{m}} instruction pattern
-@item @samp{vec_unpacks_sbool_hi_@var{m}}, @samp{vec_unpacks_sbool_lo_@var{m}}
-Extract the high/low part of a vector of boolean elements that have scalar
-mode @var{m}. The input vector (operand 1) has N elements, the output
-vector (operand 0) has N/2 elements. The last operand (operand 2) is the
-number of elements of the input vector N as a @code{CONST_INT}. These
-patterns are used if both the input and output vectors have the same scalar
-mode @var{m} and thus using @code{vec_unpacks_hi_@var{m}} or
-@code{vec_unpacks_lo_@var{m}} would be ambiguous.
-
-@cindex @code{vec_unpacks_float_hi_@var{m}} instruction pattern
-@cindex @code{vec_unpacks_float_lo_@var{m}} instruction pattern
-@cindex @code{vec_unpacku_float_hi_@var{m}} instruction pattern
-@cindex @code{vec_unpacku_float_lo_@var{m}} instruction pattern
-@item @samp{vec_unpacks_float_hi_@var{m}}, @samp{vec_unpacks_float_lo_@var{m}}
-@itemx @samp{vec_unpacku_float_hi_@var{m}}, @samp{vec_unpacku_float_lo_@var{m}}
-Extract, convert to floating point type and widen the high/low part of a
-vector of signed/unsigned integral elements. The input vector (operand 1)
-has N elements of size S@. Convert the high/low elements of the vector using
-floating point conversion and place the resulting N/2 values of size 2*S in
-the output vector (operand 0).
-
-@cindex @code{vec_unpack_sfix_trunc_hi_@var{m}} instruction pattern
-@cindex @code{vec_unpack_sfix_trunc_lo_@var{m}} instruction pattern
-@cindex @code{vec_unpack_ufix_trunc_hi_@var{m}} instruction pattern
-@cindex @code{vec_unpack_ufix_trunc_lo_@var{m}} instruction pattern
-@item @samp{vec_unpack_sfix_trunc_hi_@var{m}},
-@itemx @samp{vec_unpack_sfix_trunc_lo_@var{m}}
-@itemx @samp{vec_unpack_ufix_trunc_hi_@var{m}}
-@itemx @samp{vec_unpack_ufix_trunc_lo_@var{m}}
-Extract, convert to signed/unsigned integer type and widen the high/low part of a
-vector of floating point elements. The input vector (operand 1)
-has N elements of size S@. Convert the high/low elements of the vector
-to integers and place the resulting N/2 values of size 2*S in
-the output vector (operand 0).
-
-@cindex @code{vec_widen_umult_hi_@var{m}} instruction pattern
-@cindex @code{vec_widen_umult_lo_@var{m}} instruction pattern
-@cindex @code{vec_widen_smult_hi_@var{m}} instruction pattern
-@cindex @code{vec_widen_smult_lo_@var{m}} instruction pattern
-@cindex @code{vec_widen_umult_even_@var{m}} instruction pattern
-@cindex @code{vec_widen_umult_odd_@var{m}} instruction pattern
-@cindex @code{vec_widen_smult_even_@var{m}} instruction pattern
-@cindex @code{vec_widen_smult_odd_@var{m}} instruction pattern
-@item @samp{vec_widen_umult_hi_@var{m}}, @samp{vec_widen_umult_lo_@var{m}}
-@itemx @samp{vec_widen_smult_hi_@var{m}}, @samp{vec_widen_smult_lo_@var{m}}
-@itemx @samp{vec_widen_umult_even_@var{m}}, @samp{vec_widen_umult_odd_@var{m}}
-@itemx @samp{vec_widen_smult_even_@var{m}}, @samp{vec_widen_smult_odd_@var{m}}
-Signed/Unsigned widening multiplication. The two inputs (operands 1 and 2)
-are vectors with N signed/unsigned elements of size S@. Multiply the high/low
-or even/odd elements of the two vectors, and put the N/2 products of size 2*S
-in the output vector (operand 0). A target shouldn't implement even/odd pattern
-pair if it is less efficient than lo/hi one.
-
-@cindex @code{vec_widen_ushiftl_hi_@var{m}} instruction pattern
-@cindex @code{vec_widen_ushiftl_lo_@var{m}} instruction pattern
-@cindex @code{vec_widen_sshiftl_hi_@var{m}} instruction pattern
-@cindex @code{vec_widen_sshiftl_lo_@var{m}} instruction pattern
-@item @samp{vec_widen_ushiftl_hi_@var{m}}, @samp{vec_widen_ushiftl_lo_@var{m}}
-@itemx @samp{vec_widen_sshiftl_hi_@var{m}}, @samp{vec_widen_sshiftl_lo_@var{m}}
-Signed/Unsigned widening shift left. The first input (operand 1) is a vector
-with N signed/unsigned elements of size S@. Operand 2 is a constant. Shift
-the high/low elements of operand 1, and put the N/2 results of size 2*S in the
-output vector (operand 0).
-
-@cindex @code{vec_widen_saddl_hi_@var{m}} instruction pattern
-@cindex @code{vec_widen_saddl_lo_@var{m}} instruction pattern
-@cindex @code{vec_widen_uaddl_hi_@var{m}} instruction pattern
-@cindex @code{vec_widen_uaddl_lo_@var{m}} instruction pattern
-@item @samp{vec_widen_uaddl_hi_@var{m}}, @samp{vec_widen_uaddl_lo_@var{m}}
-@itemx @samp{vec_widen_saddl_hi_@var{m}}, @samp{vec_widen_saddl_lo_@var{m}}
-Signed/Unsigned widening add long. Operands 1 and 2 are vectors with N
-signed/unsigned elements of size S@. Add the high/low elements of 1 and 2
-together, widen the resulting elements and put the N/2 results of size 2*S in
-the output vector (operand 0).
-
-@cindex @code{vec_widen_ssubl_hi_@var{m}} instruction pattern
-@cindex @code{vec_widen_ssubl_lo_@var{m}} instruction pattern
-@cindex @code{vec_widen_usubl_hi_@var{m}} instruction pattern
-@cindex @code{vec_widen_usubl_lo_@var{m}} instruction pattern
-@item @samp{vec_widen_usubl_hi_@var{m}}, @samp{vec_widen_usubl_lo_@var{m}}
-@itemx @samp{vec_widen_ssubl_hi_@var{m}}, @samp{vec_widen_ssubl_lo_@var{m}}
-Signed/Unsigned widening subtract long. Operands 1 and 2 are vectors with N
-signed/unsigned elements of size S@. Subtract the high/low elements of 2 from
-1 and widen the resulting elements. Put the N/2 results of size 2*S in the
-output vector (operand 0).
-
-@cindex @code{vec_addsub@var{m}3} instruction pattern
-@item @samp{vec_addsub@var{m}3}
-Alternating subtract, add with even lanes doing subtract and odd
-lanes doing addition. Operands 1 and 2 and the outout operand are vectors
-with mode @var{m}.
-
-@cindex @code{vec_fmaddsub@var{m}4} instruction pattern
-@item @samp{vec_fmaddsub@var{m}4}
-Alternating multiply subtract, add with even lanes doing subtract and odd
-lanes doing addition of the third operand to the multiplication result
-of the first two operands. Operands 1, 2 and 3 and the outout operand are vectors
-with mode @var{m}.
-
-@cindex @code{vec_fmsubadd@var{m}4} instruction pattern
-@item @samp{vec_fmsubadd@var{m}4}
-Alternating multiply add, subtract with even lanes doing addition and odd
-lanes doing subtraction of the third operand to the multiplication result
-of the first two operands. Operands 1, 2 and 3 and the outout operand are vectors
-with mode @var{m}.
-
-These instructions are not allowed to @code{FAIL}.
-
-@cindex @code{mulhisi3} instruction pattern
-@item @samp{mulhisi3}
-Multiply operands 1 and 2, which have mode @code{HImode}, and store
-a @code{SImode} product in operand 0.
-
-@cindex @code{mulqihi3} instruction pattern
-@cindex @code{mulsidi3} instruction pattern
-@item @samp{mulqihi3}, @samp{mulsidi3}
-Similar widening-multiplication instructions of other widths.
-
-@cindex @code{umulqihi3} instruction pattern
-@cindex @code{umulhisi3} instruction pattern
-@cindex @code{umulsidi3} instruction pattern
-@item @samp{umulqihi3}, @samp{umulhisi3}, @samp{umulsidi3}
-Similar widening-multiplication instructions that do unsigned
-multiplication.
-
-@cindex @code{usmulqihi3} instruction pattern
-@cindex @code{usmulhisi3} instruction pattern
-@cindex @code{usmulsidi3} instruction pattern
-@item @samp{usmulqihi3}, @samp{usmulhisi3}, @samp{usmulsidi3}
-Similar widening-multiplication instructions that interpret the first
-operand as unsigned and the second operand as signed, then do a signed
-multiplication.
-
-@cindex @code{smul@var{m}3_highpart} instruction pattern
-@item @samp{smul@var{m}3_highpart}
-Perform a signed multiplication of operands 1 and 2, which have mode
-@var{m}, and store the most significant half of the product in operand 0.
-The least significant half of the product is discarded. This may be
-represented in RTL using a @code{smul_highpart} RTX expression.
-
-@cindex @code{umul@var{m}3_highpart} instruction pattern
-@item @samp{umul@var{m}3_highpart}
-Similar, but the multiplication is unsigned. This may be represented
-in RTL using an @code{umul_highpart} RTX expression.
-
-@cindex @code{madd@var{m}@var{n}4} instruction pattern
-@item @samp{madd@var{m}@var{n}4}
-Multiply operands 1 and 2, sign-extend them to mode @var{n}, add
-operand 3, and store the result in operand 0. Operands 1 and 2
-have mode @var{m} and operands 0 and 3 have mode @var{n}.
-Both modes must be integer or fixed-point modes and @var{n} must be twice
-the size of @var{m}.
-
-In other words, @code{madd@var{m}@var{n}4} is like
-@code{mul@var{m}@var{n}3} except that it also adds operand 3.
-
-These instructions are not allowed to @code{FAIL}.
-
-@cindex @code{umadd@var{m}@var{n}4} instruction pattern
-@item @samp{umadd@var{m}@var{n}4}
-Like @code{madd@var{m}@var{n}4}, but zero-extend the multiplication
-operands instead of sign-extending them.
-
-@cindex @code{ssmadd@var{m}@var{n}4} instruction pattern
-@item @samp{ssmadd@var{m}@var{n}4}
-Like @code{madd@var{m}@var{n}4}, but all involved operations must be
-signed-saturating.
-
-@cindex @code{usmadd@var{m}@var{n}4} instruction pattern
-@item @samp{usmadd@var{m}@var{n}4}
-Like @code{umadd@var{m}@var{n}4}, but all involved operations must be
-unsigned-saturating.
-
-@cindex @code{msub@var{m}@var{n}4} instruction pattern
-@item @samp{msub@var{m}@var{n}4}
-Multiply operands 1 and 2, sign-extend them to mode @var{n}, subtract the
-result from operand 3, and store the result in operand 0. Operands 1 and 2
-have mode @var{m} and operands 0 and 3 have mode @var{n}.
-Both modes must be integer or fixed-point modes and @var{n} must be twice
-the size of @var{m}.
-
-In other words, @code{msub@var{m}@var{n}4} is like
-@code{mul@var{m}@var{n}3} except that it also subtracts the result
-from operand 3.
-
-These instructions are not allowed to @code{FAIL}.
-
-@cindex @code{umsub@var{m}@var{n}4} instruction pattern
-@item @samp{umsub@var{m}@var{n}4}
-Like @code{msub@var{m}@var{n}4}, but zero-extend the multiplication
-operands instead of sign-extending them.
-
-@cindex @code{ssmsub@var{m}@var{n}4} instruction pattern
-@item @samp{ssmsub@var{m}@var{n}4}
-Like @code{msub@var{m}@var{n}4}, but all involved operations must be
-signed-saturating.
-
-@cindex @code{usmsub@var{m}@var{n}4} instruction pattern
-@item @samp{usmsub@var{m}@var{n}4}
-Like @code{umsub@var{m}@var{n}4}, but all involved operations must be
-unsigned-saturating.
-
-@cindex @code{divmod@var{m}4} instruction pattern
-@item @samp{divmod@var{m}4}
-Signed division that produces both a quotient and a remainder.
-Operand 1 is divided by operand 2 to produce a quotient stored
-in operand 0 and a remainder stored in operand 3.
-
-For machines with an instruction that produces both a quotient and a
-remainder, provide a pattern for @samp{divmod@var{m}4} but do not
-provide patterns for @samp{div@var{m}3} and @samp{mod@var{m}3}. This
-allows optimization in the relatively common case when both the quotient
-and remainder are computed.
-
-If an instruction that just produces a quotient or just a remainder
-exists and is more efficient than the instruction that produces both,
-write the output routine of @samp{divmod@var{m}4} to call
-@code{find_reg_note} and look for a @code{REG_UNUSED} note on the
-quotient or remainder and generate the appropriate instruction.
-
-@cindex @code{udivmod@var{m}4} instruction pattern
-@item @samp{udivmod@var{m}4}
-Similar, but does unsigned division.
-
-@anchor{shift patterns}
-@cindex @code{ashl@var{m}3} instruction pattern
-@cindex @code{ssashl@var{m}3} instruction pattern
-@cindex @code{usashl@var{m}3} instruction pattern
-@item @samp{ashl@var{m}3}, @samp{ssashl@var{m}3}, @samp{usashl@var{m}3}
-Arithmetic-shift operand 1 left by a number of bits specified by operand
-2, and store the result in operand 0. Here @var{m} is the mode of
-operand 0 and operand 1; operand 2's mode is specified by the
-instruction pattern, and the compiler will convert the operand to that
-mode before generating the instruction. The shift or rotate expander
-or instruction pattern should explicitly specify the mode of the operand 2,
-it should never be @code{VOIDmode}. The meaning of out-of-range shift
-counts can optionally be specified by @code{TARGET_SHIFT_TRUNCATION_MASK}.
-@xref{TARGET_SHIFT_TRUNCATION_MASK}. Operand 2 is always a scalar type.
-
-@cindex @code{ashr@var{m}3} instruction pattern
-@cindex @code{lshr@var{m}3} instruction pattern
-@cindex @code{rotl@var{m}3} instruction pattern
-@cindex @code{rotr@var{m}3} instruction pattern
-@item @samp{ashr@var{m}3}, @samp{lshr@var{m}3}, @samp{rotl@var{m}3}, @samp{rotr@var{m}3}
-Other shift and rotate instructions, analogous to the
-@code{ashl@var{m}3} instructions. Operand 2 is always a scalar type.
-
-@cindex @code{vashl@var{m}3} instruction pattern
-@cindex @code{vashr@var{m}3} instruction pattern
-@cindex @code{vlshr@var{m}3} instruction pattern
-@cindex @code{vrotl@var{m}3} instruction pattern
-@cindex @code{vrotr@var{m}3} instruction pattern
-@item @samp{vashl@var{m}3}, @samp{vashr@var{m}3}, @samp{vlshr@var{m}3}, @samp{vrotl@var{m}3}, @samp{vrotr@var{m}3}
-Vector shift and rotate instructions that take vectors as operand 2
-instead of a scalar type.
-
-@cindex @code{avg@var{m}3_floor} instruction pattern
-@cindex @code{uavg@var{m}3_floor} instruction pattern
-@item @samp{avg@var{m}3_floor}
-@itemx @samp{uavg@var{m}3_floor}
-Signed and unsigned average instructions. These instructions add
-operands 1 and 2 without truncation, divide the result by 2,
-round towards -Inf, and store the result in operand 0. This is
-equivalent to the C code:
-@smallexample
-narrow op0, op1, op2;
-@dots{}
-op0 = (narrow) (((wide) op1 + (wide) op2) >> 1);
-@end smallexample
-where the sign of @samp{narrow} determines whether this is a signed
-or unsigned operation.
-
-@cindex @code{avg@var{m}3_ceil} instruction pattern
-@cindex @code{uavg@var{m}3_ceil} instruction pattern
-@item @samp{avg@var{m}3_ceil}
-@itemx @samp{uavg@var{m}3_ceil}
-Like @samp{avg@var{m}3_floor} and @samp{uavg@var{m}3_floor}, but round
-towards +Inf. This is equivalent to the C code:
-@smallexample
-narrow op0, op1, op2;
-@dots{}
-op0 = (narrow) (((wide) op1 + (wide) op2 + 1) >> 1);
-@end smallexample
-
-@cindex @code{bswap@var{m}2} instruction pattern
-@item @samp{bswap@var{m}2}
-Reverse the order of bytes of operand 1 and store the result in operand 0.
-
-@cindex @code{neg@var{m}2} instruction pattern
-@cindex @code{ssneg@var{m}2} instruction pattern
-@cindex @code{usneg@var{m}2} instruction pattern
-@item @samp{neg@var{m}2}, @samp{ssneg@var{m}2}, @samp{usneg@var{m}2}
-Negate operand 1 and store the result in operand 0.
-
-@cindex @code{negv@var{m}3} instruction pattern
-@item @samp{negv@var{m}3}
-Like @code{neg@var{m}2} but takes a @code{code_label} as operand 2 and
-emits code to jump to it if signed overflow occurs during the negation.
-
-@cindex @code{abs@var{m}2} instruction pattern
-@item @samp{abs@var{m}2}
-Store the absolute value of operand 1 into operand 0.
-
-@cindex @code{sqrt@var{m}2} instruction pattern
-@item @samp{sqrt@var{m}2}
-Store the square root of operand 1 into operand 0. Both operands have
-mode @var{m}, which is a scalar or vector floating-point mode.
-
-This pattern is not allowed to @code{FAIL}.
-
-@cindex @code{rsqrt@var{m}2} instruction pattern
-@item @samp{rsqrt@var{m}2}
-Store the reciprocal of the square root of operand 1 into operand 0.
-Both operands have mode @var{m}, which is a scalar or vector
-floating-point mode.
-
-On most architectures this pattern is only approximate, so either
-its C condition or the @code{TARGET_OPTAB_SUPPORTED_P} hook should
-check for the appropriate math flags. (Using the C condition is
-more direct, but using @code{TARGET_OPTAB_SUPPORTED_P} can be useful
-if a target-specific built-in also uses the @samp{rsqrt@var{m}2}
-pattern.)
-
-This pattern is not allowed to @code{FAIL}.
-
-@cindex @code{fmod@var{m}3} instruction pattern
-@item @samp{fmod@var{m}3}
-Store the remainder of dividing operand 1 by operand 2 into
-operand 0, rounded towards zero to an integer. All operands have
-mode @var{m}, which is a scalar or vector floating-point mode.
-
-This pattern is not allowed to @code{FAIL}.
-
-@cindex @code{remainder@var{m}3} instruction pattern
-@item @samp{remainder@var{m}3}
-Store the remainder of dividing operand 1 by operand 2 into
-operand 0, rounded to the nearest integer. All operands have
-mode @var{m}, which is a scalar or vector floating-point mode.
-
-This pattern is not allowed to @code{FAIL}.
-
-@cindex @code{scalb@var{m}3} instruction pattern
-@item @samp{scalb@var{m}3}
-Raise @code{FLT_RADIX} to the power of operand 2, multiply it by
-operand 1, and store the result in operand 0. All operands have
-mode @var{m}, which is a scalar or vector floating-point mode.
-
-This pattern is not allowed to @code{FAIL}.
-
-@cindex @code{ldexp@var{m}3} instruction pattern
-@item @samp{ldexp@var{m}3}
-Raise 2 to the power of operand 2, multiply it by operand 1, and store
-the result in operand 0. Operands 0 and 1 have mode @var{m}, which is
-a scalar or vector floating-point mode. Operand 2's mode has
-the same number of elements as @var{m} and each element is wide
-enough to store an @code{int}. The integers are signed.
-
-This pattern is not allowed to @code{FAIL}.
-
-@cindex @code{cos@var{m}2} instruction pattern
-@item @samp{cos@var{m}2}
-Store the cosine of operand 1 into operand 0. Both operands have
-mode @var{m}, which is a scalar or vector floating-point mode.
-
-This pattern is not allowed to @code{FAIL}.
-
-@cindex @code{sin@var{m}2} instruction pattern
-@item @samp{sin@var{m}2}
-Store the sine of operand 1 into operand 0. Both operands have
-mode @var{m}, which is a scalar or vector floating-point mode.
-
-This pattern is not allowed to @code{FAIL}.
-
-@cindex @code{sincos@var{m}3} instruction pattern
-@item @samp{sincos@var{m}3}
-Store the cosine of operand 2 into operand 0 and the sine of
-operand 2 into operand 1. All operands have mode @var{m},
-which is a scalar or vector floating-point mode.
-
-Targets that can calculate the sine and cosine simultaneously can
-implement this pattern as opposed to implementing individual
-@code{sin@var{m}2} and @code{cos@var{m}2} patterns. The @code{sin}
-and @code{cos} built-in functions will then be expanded to the
-@code{sincos@var{m}3} pattern, with one of the output values
-left unused.
-
-@cindex @code{tan@var{m}2} instruction pattern
-@item @samp{tan@var{m}2}
-Store the tangent of operand 1 into operand 0. Both operands have
-mode @var{m}, which is a scalar or vector floating-point mode.
-
-This pattern is not allowed to @code{FAIL}.
-
-@cindex @code{asin@var{m}2} instruction pattern
-@item @samp{asin@var{m}2}
-Store the arc sine of operand 1 into operand 0. Both operands have
-mode @var{m}, which is a scalar or vector floating-point mode.
-
-This pattern is not allowed to @code{FAIL}.
-
-@cindex @code{acos@var{m}2} instruction pattern
-@item @samp{acos@var{m}2}
-Store the arc cosine of operand 1 into operand 0. Both operands have
-mode @var{m}, which is a scalar or vector floating-point mode.
-
-This pattern is not allowed to @code{FAIL}.
-
-@cindex @code{atan@var{m}2} instruction pattern
-@item @samp{atan@var{m}2}
-Store the arc tangent of operand 1 into operand 0. Both operands have
-mode @var{m}, which is a scalar or vector floating-point mode.
-
-This pattern is not allowed to @code{FAIL}.
-
-@cindex @code{fegetround@var{m}} instruction pattern
-@item @samp{fegetround@var{m}}
-Store the current machine floating-point rounding mode into operand 0.
-Operand 0 has mode @var{m}, which is scalar. This pattern is used to
-implement the @code{fegetround} function from the ISO C99 standard.
-
-@cindex @code{feclearexcept@var{m}} instruction pattern
-@cindex @code{feraiseexcept@var{m}} instruction pattern
-@item @samp{feclearexcept@var{m}}
-@item @samp{feraiseexcept@var{m}}
-Clears or raises the supported machine floating-point exceptions
-represented by the bits in operand 1. Error status is stored as
-nonzero value in operand 0. Both operands have mode @var{m}, which is
-a scalar. These patterns are used to implement the
-@code{feclearexcept} and @code{feraiseexcept} functions from the ISO
-C99 standard.
-
-@cindex @code{exp@var{m}2} instruction pattern
-@item @samp{exp@var{m}2}
-Raise e (the base of natural logarithms) to the power of operand 1
-and store the result in operand 0. Both operands have mode @var{m},
-which is a scalar or vector floating-point mode.
-
-This pattern is not allowed to @code{FAIL}.
-
-@cindex @code{expm1@var{m}2} instruction pattern
-@item @samp{expm1@var{m}2}
-Raise e (the base of natural logarithms) to the power of operand 1,
-subtract 1, and store the result in operand 0. Both operands have
-mode @var{m}, which is a scalar or vector floating-point mode.
-
-For inputs close to zero, the pattern is expected to be more
-accurate than a separate @code{exp@var{m}2} and @code{sub@var{m}3}
-would be.
-
-This pattern is not allowed to @code{FAIL}.
-
-@cindex @code{exp10@var{m}2} instruction pattern
-@item @samp{exp10@var{m}2}
-Raise 10 to the power of operand 1 and store the result in operand 0.
-Both operands have mode @var{m}, which is a scalar or vector
-floating-point mode.
-
-This pattern is not allowed to @code{FAIL}.
-
-@cindex @code{exp2@var{m}2} instruction pattern
-@item @samp{exp2@var{m}2}
-Raise 2 to the power of operand 1 and store the result in operand 0.
-Both operands have mode @var{m}, which is a scalar or vector
-floating-point mode.
-
-This pattern is not allowed to @code{FAIL}.
-
-@cindex @code{log@var{m}2} instruction pattern
-@item @samp{log@var{m}2}
-Store the natural logarithm of operand 1 into operand 0. Both operands
-have mode @var{m}, which is a scalar or vector floating-point mode.
-
-This pattern is not allowed to @code{FAIL}.
-
-@cindex @code{log1p@var{m}2} instruction pattern
-@item @samp{log1p@var{m}2}
-Add 1 to operand 1, compute the natural logarithm, and store
-the result in operand 0. Both operands have mode @var{m}, which is
-a scalar or vector floating-point mode.
-
-For inputs close to zero, the pattern is expected to be more
-accurate than a separate @code{add@var{m}3} and @code{log@var{m}2}
-would be.
-
-This pattern is not allowed to @code{FAIL}.
-
-@cindex @code{log10@var{m}2} instruction pattern
-@item @samp{log10@var{m}2}
-Store the base-10 logarithm of operand 1 into operand 0. Both operands
-have mode @var{m}, which is a scalar or vector floating-point mode.
-
-This pattern is not allowed to @code{FAIL}.
-
-@cindex @code{log2@var{m}2} instruction pattern
-@item @samp{log2@var{m}2}
-Store the base-2 logarithm of operand 1 into operand 0. Both operands
-have mode @var{m}, which is a scalar or vector floating-point mode.
-
-This pattern is not allowed to @code{FAIL}.
-
-@cindex @code{logb@var{m}2} instruction pattern
-@item @samp{logb@var{m}2}
-Store the base-@code{FLT_RADIX} logarithm of operand 1 into operand 0.
-Both operands have mode @var{m}, which is a scalar or vector
-floating-point mode.
-
-This pattern is not allowed to @code{FAIL}.
-
-@cindex @code{significand@var{m}2} instruction pattern
-@item @samp{significand@var{m}2}
-Store the significand of floating-point operand 1 in operand 0.
-Both operands have mode @var{m}, which is a scalar or vector
-floating-point mode.
-
-This pattern is not allowed to @code{FAIL}.
-
-@cindex @code{pow@var{m}3} instruction pattern
-@item @samp{pow@var{m}3}
-Store the value of operand 1 raised to the exponent operand 2
-into operand 0. All operands have mode @var{m}, which is a scalar
-or vector floating-point mode.
-
-This pattern is not allowed to @code{FAIL}.
-
-@cindex @code{atan2@var{m}3} instruction pattern
-@item @samp{atan2@var{m}3}
-Store the arc tangent (inverse tangent) of operand 1 divided by
-operand 2 into operand 0, using the signs of both arguments to
-determine the quadrant of the result. All operands have mode
-@var{m}, which is a scalar or vector floating-point mode.
-
-This pattern is not allowed to @code{FAIL}.
-
-@cindex @code{floor@var{m}2} instruction pattern
-@item @samp{floor@var{m}2}
-Store the largest integral value not greater than operand 1 in operand 0.
-Both operands have mode @var{m}, which is a scalar or vector
-floating-point mode. If @option{-ffp-int-builtin-inexact} is in
-effect, the ``inexact'' exception may be raised for noninteger
-operands; otherwise, it may not.
-
-This pattern is not allowed to @code{FAIL}.
-
-@cindex @code{btrunc@var{m}2} instruction pattern
-@item @samp{btrunc@var{m}2}
-Round operand 1 to an integer, towards zero, and store the result in
-operand 0. Both operands have mode @var{m}, which is a scalar or
-vector floating-point mode. If @option{-ffp-int-builtin-inexact} is
-in effect, the ``inexact'' exception may be raised for noninteger
-operands; otherwise, it may not.
-
-This pattern is not allowed to @code{FAIL}.
-
-@cindex @code{round@var{m}2} instruction pattern
-@item @samp{round@var{m}2}
-Round operand 1 to the nearest integer, rounding away from zero in the
-event of a tie, and store the result in operand 0. Both operands have
-mode @var{m}, which is a scalar or vector floating-point mode. If
-@option{-ffp-int-builtin-inexact} is in effect, the ``inexact''
-exception may be raised for noninteger operands; otherwise, it may
-not.
-
-This pattern is not allowed to @code{FAIL}.
-
-@cindex @code{ceil@var{m}2} instruction pattern
-@item @samp{ceil@var{m}2}
-Store the smallest integral value not less than operand 1 in operand 0.
-Both operands have mode @var{m}, which is a scalar or vector
-floating-point mode. If @option{-ffp-int-builtin-inexact} is in
-effect, the ``inexact'' exception may be raised for noninteger
-operands; otherwise, it may not.
-
-This pattern is not allowed to @code{FAIL}.
-
-@cindex @code{nearbyint@var{m}2} instruction pattern
-@item @samp{nearbyint@var{m}2}
-Round operand 1 to an integer, using the current rounding mode, and
-store the result in operand 0. Do not raise an inexact condition when
-the result is different from the argument. Both operands have mode
-@var{m}, which is a scalar or vector floating-point mode.
-
-This pattern is not allowed to @code{FAIL}.
-
-@cindex @code{rint@var{m}2} instruction pattern
-@item @samp{rint@var{m}2}
-Round operand 1 to an integer, using the current rounding mode, and
-store the result in operand 0. Raise an inexact condition when
-the result is different from the argument. Both operands have mode
-@var{m}, which is a scalar or vector floating-point mode.
-
-This pattern is not allowed to @code{FAIL}.
-
-@cindex @code{lrint@var{m}@var{n}2}
-@item @samp{lrint@var{m}@var{n}2}
-Convert operand 1 (valid for floating point mode @var{m}) to fixed
-point mode @var{n} as a signed number according to the current
-rounding mode and store in operand 0 (which has mode @var{n}).
-
-@cindex @code{lround@var{m}@var{n}2}
-@item @samp{lround@var{m}@var{n}2}
-Convert operand 1 (valid for floating point mode @var{m}) to fixed
-point mode @var{n} as a signed number rounding to nearest and away
-from zero and store in operand 0 (which has mode @var{n}).
-
-@cindex @code{lfloor@var{m}@var{n}2}
-@item @samp{lfloor@var{m}@var{n}2}
-Convert operand 1 (valid for floating point mode @var{m}) to fixed
-point mode @var{n} as a signed number rounding down and store in
-operand 0 (which has mode @var{n}).
-
-@cindex @code{lceil@var{m}@var{n}2}
-@item @samp{lceil@var{m}@var{n}2}
-Convert operand 1 (valid for floating point mode @var{m}) to fixed
-point mode @var{n} as a signed number rounding up and store in
-operand 0 (which has mode @var{n}).
-
-@cindex @code{copysign@var{m}3} instruction pattern
-@item @samp{copysign@var{m}3}
-Store a value with the magnitude of operand 1 and the sign of operand
-2 into operand 0. All operands have mode @var{m}, which is a scalar or
-vector floating-point mode.
-
-This pattern is not allowed to @code{FAIL}.
-
-@cindex @code{xorsign@var{m}3} instruction pattern
-@item @samp{xorsign@var{m}3}
-Equivalent to @samp{op0 = op1 * copysign (1.0, op2)}: store a value with
-the magnitude of operand 1 and the sign of operand 2 into operand 0.
-All operands have mode @var{m}, which is a scalar or vector
-floating-point mode.
-
-This pattern is not allowed to @code{FAIL}.
-
-@cindex @code{issignaling@var{m}2} instruction pattern
-@item @samp{issignaling@var{m}2}
-Set operand 0 to 1 if operand 1 is a signaling NaN and to 0 otherwise.
-
-@cindex @code{cadd90@var{m}3} instruction pattern
-@item @samp{cadd90@var{m}3}
-Perform vector add and subtract on even/odd number pairs. The operation being
-matched is semantically described as
-
-@smallexample
- for (int i = 0; i < N; i += 2)
- @{
- c[i] = a[i] - b[i+1];
- c[i+1] = a[i+1] + b[i];
- @}
-@end smallexample
-
-This operation is semantically equivalent to performing a vector addition of
-complex numbers in operand 1 with operand 2 rotated by 90 degrees around
-the argand plane and storing the result in operand 0.
-
-In GCC lane ordering the real part of the number must be in the even lanes with
-the imaginary part in the odd lanes.
-
-The operation is only supported for vector modes @var{m}.
-
-This pattern is not allowed to @code{FAIL}.
-
-@cindex @code{cadd270@var{m}3} instruction pattern
-@item @samp{cadd270@var{m}3}
-Perform vector add and subtract on even/odd number pairs. The operation being
-matched is semantically described as
-
-@smallexample
- for (int i = 0; i < N; i += 2)
- @{
- c[i] = a[i] + b[i+1];
- c[i+1] = a[i+1] - b[i];
- @}
-@end smallexample
-
-This operation is semantically equivalent to performing a vector addition of
-complex numbers in operand 1 with operand 2 rotated by 270 degrees around
-the argand plane and storing the result in operand 0.
-
-In GCC lane ordering the real part of the number must be in the even lanes with
-the imaginary part in the odd lanes.
-
-The operation is only supported for vector modes @var{m}.
-
-This pattern is not allowed to @code{FAIL}.
-
-@cindex @code{cmla@var{m}4} instruction pattern
-@item @samp{cmla@var{m}4}
-Perform a vector multiply and accumulate that is semantically the same as
-a multiply and accumulate of complex numbers.
-
-@smallexample
- complex TYPE op0[N];
- complex TYPE op1[N];
- complex TYPE op2[N];
- complex TYPE op3[N];
- for (int i = 0; i < N; i += 1)
- @{
- op0[i] = op1[i] * op2[i] + op3[i];
- @}
-@end smallexample
-
-In GCC lane ordering the real part of the number must be in the even lanes with
-the imaginary part in the odd lanes.
-
-The operation is only supported for vector modes @var{m}.
-
-This pattern is not allowed to @code{FAIL}.
-
-@cindex @code{cmla_conj@var{m}4} instruction pattern
-@item @samp{cmla_conj@var{m}4}
-Perform a vector multiply by conjugate and accumulate that is semantically
-the same as a multiply and accumulate of complex numbers where the second
-multiply arguments is conjugated.
-
-@smallexample
- complex TYPE op0[N];
- complex TYPE op1[N];
- complex TYPE op2[N];
- complex TYPE op3[N];
- for (int i = 0; i < N; i += 1)
- @{
- op0[i] = op1[i] * conj (op2[i]) + op3[i];
- @}
-@end smallexample
-
-In GCC lane ordering the real part of the number must be in the even lanes with
-the imaginary part in the odd lanes.
-
-The operation is only supported for vector modes @var{m}.
-
-This pattern is not allowed to @code{FAIL}.
-
-@cindex @code{cmls@var{m}4} instruction pattern
-@item @samp{cmls@var{m}4}
-Perform a vector multiply and subtract that is semantically the same as
-a multiply and subtract of complex numbers.
-
-@smallexample
- complex TYPE op0[N];
- complex TYPE op1[N];
- complex TYPE op2[N];
- complex TYPE op3[N];
- for (int i = 0; i < N; i += 1)
- @{
- op0[i] = op1[i] * op2[i] - op3[i];
- @}
-@end smallexample
-
-In GCC lane ordering the real part of the number must be in the even lanes with
-the imaginary part in the odd lanes.
-
-The operation is only supported for vector modes @var{m}.
-
-This pattern is not allowed to @code{FAIL}.
-
-@cindex @code{cmls_conj@var{m}4} instruction pattern
-@item @samp{cmls_conj@var{m}4}
-Perform a vector multiply by conjugate and subtract that is semantically
-the same as a multiply and subtract of complex numbers where the second
-multiply arguments is conjugated.
-
-@smallexample
- complex TYPE op0[N];
- complex TYPE op1[N];
- complex TYPE op2[N];
- complex TYPE op3[N];
- for (int i = 0; i < N; i += 1)
- @{
- op0[i] = op1[i] * conj (op2[i]) - op3[i];
- @}
-@end smallexample
-
-In GCC lane ordering the real part of the number must be in the even lanes with
-the imaginary part in the odd lanes.
-
-The operation is only supported for vector modes @var{m}.
-
-This pattern is not allowed to @code{FAIL}.
-
-@cindex @code{cmul@var{m}4} instruction pattern
-@item @samp{cmul@var{m}4}
-Perform a vector multiply that is semantically the same as multiply of
-complex numbers.
-
-@smallexample
- complex TYPE op0[N];
- complex TYPE op1[N];
- complex TYPE op2[N];
- for (int i = 0; i < N; i += 1)
- @{
- op0[i] = op1[i] * op2[i];
- @}
-@end smallexample
-
-In GCC lane ordering the real part of the number must be in the even lanes with
-the imaginary part in the odd lanes.
-
-The operation is only supported for vector modes @var{m}.
-
-This pattern is not allowed to @code{FAIL}.
-
-@cindex @code{cmul_conj@var{m}4} instruction pattern
-@item @samp{cmul_conj@var{m}4}
-Perform a vector multiply by conjugate that is semantically the same as a
-multiply of complex numbers where the second multiply arguments is conjugated.
-
-@smallexample
- complex TYPE op0[N];
- complex TYPE op1[N];
- complex TYPE op2[N];
- for (int i = 0; i < N; i += 1)
- @{
- op0[i] = op1[i] * conj (op2[i]);
- @}
-@end smallexample
-
-In GCC lane ordering the real part of the number must be in the even lanes with
-the imaginary part in the odd lanes.
-
-The operation is only supported for vector modes @var{m}.
-
-This pattern is not allowed to @code{FAIL}.
-
-@cindex @code{ffs@var{m}2} instruction pattern
-@item @samp{ffs@var{m}2}
-Store into operand 0 one plus the index of the least significant 1-bit
-of operand 1. If operand 1 is zero, store zero.
-
-@var{m} is either a scalar or vector integer mode. When it is a scalar,
-operand 1 has mode @var{m} but operand 0 can have whatever scalar
-integer mode is suitable for the target. The compiler will insert
-conversion instructions as necessary (typically to convert the result
-to the same width as @code{int}). When @var{m} is a vector, both
-operands must have mode @var{m}.
-
-This pattern is not allowed to @code{FAIL}.
-
-@cindex @code{clrsb@var{m}2} instruction pattern
-@item @samp{clrsb@var{m}2}
-Count leading redundant sign bits.
-Store into operand 0 the number of redundant sign bits in operand 1, starting
-at the most significant bit position.
-A redundant sign bit is defined as any sign bit after the first. As such,
-this count will be one less than the count of leading sign bits.
-
-@var{m} is either a scalar or vector integer mode. When it is a scalar,
-operand 1 has mode @var{m} but operand 0 can have whatever scalar
-integer mode is suitable for the target. The compiler will insert
-conversion instructions as necessary (typically to convert the result
-to the same width as @code{int}). When @var{m} is a vector, both
-operands must have mode @var{m}.
-
-This pattern is not allowed to @code{FAIL}.
-
-@cindex @code{clz@var{m}2} instruction pattern
-@item @samp{clz@var{m}2}
-Store into operand 0 the number of leading 0-bits in operand 1, starting
-at the most significant bit position. If operand 1 is 0, the
-@code{CLZ_DEFINED_VALUE_AT_ZERO} (@pxref{Misc}) macro defines if
-the result is undefined or has a useful value.
-
-@var{m} is either a scalar or vector integer mode. When it is a scalar,
-operand 1 has mode @var{m} but operand 0 can have whatever scalar
-integer mode is suitable for the target. The compiler will insert
-conversion instructions as necessary (typically to convert the result
-to the same width as @code{int}). When @var{m} is a vector, both
-operands must have mode @var{m}.
-
-This pattern is not allowed to @code{FAIL}.
-
-@cindex @code{ctz@var{m}2} instruction pattern
-@item @samp{ctz@var{m}2}
-Store into operand 0 the number of trailing 0-bits in operand 1, starting
-at the least significant bit position. If operand 1 is 0, the
-@code{CTZ_DEFINED_VALUE_AT_ZERO} (@pxref{Misc}) macro defines if
-the result is undefined or has a useful value.
-
-@var{m} is either a scalar or vector integer mode. When it is a scalar,
-operand 1 has mode @var{m} but operand 0 can have whatever scalar
-integer mode is suitable for the target. The compiler will insert
-conversion instructions as necessary (typically to convert the result
-to the same width as @code{int}). When @var{m} is a vector, both
-operands must have mode @var{m}.
-
-This pattern is not allowed to @code{FAIL}.
-
-@cindex @code{popcount@var{m}2} instruction pattern
-@item @samp{popcount@var{m}2}
-Store into operand 0 the number of 1-bits in operand 1.
-
-@var{m} is either a scalar or vector integer mode. When it is a scalar,
-operand 1 has mode @var{m} but operand 0 can have whatever scalar
-integer mode is suitable for the target. The compiler will insert
-conversion instructions as necessary (typically to convert the result
-to the same width as @code{int}). When @var{m} is a vector, both
-operands must have mode @var{m}.
-
-This pattern is not allowed to @code{FAIL}.
-
-@cindex @code{parity@var{m}2} instruction pattern
-@item @samp{parity@var{m}2}
-Store into operand 0 the parity of operand 1, i.e.@: the number of 1-bits
-in operand 1 modulo 2.
-
-@var{m} is either a scalar or vector integer mode. When it is a scalar,
-operand 1 has mode @var{m} but operand 0 can have whatever scalar
-integer mode is suitable for the target. The compiler will insert
-conversion instructions as necessary (typically to convert the result
-to the same width as @code{int}). When @var{m} is a vector, both
-operands must have mode @var{m}.
-
-This pattern is not allowed to @code{FAIL}.
-
-@cindex @code{one_cmpl@var{m}2} instruction pattern
-@item @samp{one_cmpl@var{m}2}
-Store the bitwise-complement of operand 1 into operand 0.
-
-@cindex @code{cpymem@var{m}} instruction pattern
-@item @samp{cpymem@var{m}}
-Block copy instruction. The destination and source blocks of memory
-are the first two operands, and both are @code{mem:BLK}s with an
-address in mode @code{Pmode}.
-
-The number of bytes to copy is the third operand, in mode @var{m}.
-Usually, you specify @code{Pmode} for @var{m}. However, if you can
-generate better code knowing the range of valid lengths is smaller than
-those representable in a full Pmode pointer, you should provide
-a pattern with a
-mode corresponding to the range of values you can handle efficiently
-(e.g., @code{QImode} for values in the range 0--127; note we avoid numbers
-that appear negative) and also a pattern with @code{Pmode}.
-
-The fourth operand is the known shared alignment of the source and
-destination, in the form of a @code{const_int} rtx. Thus, if the
-compiler knows that both source and destination are word-aligned,
-it may provide the value 4 for this operand.
-
-Optional operands 5 and 6 specify expected alignment and size of block
-respectively. The expected alignment differs from alignment in operand 4
-in a way that the blocks are not required to be aligned according to it in
-all cases. This expected alignment is also in bytes, just like operand 4.
-Expected size, when unknown, is set to @code{(const_int -1)}.
-
-Descriptions of multiple @code{cpymem@var{m}} patterns can only be
-beneficial if the patterns for smaller modes have fewer restrictions
-on their first, second and fourth operands. Note that the mode @var{m}
-in @code{cpymem@var{m}} does not impose any restriction on the mode of
-individually copied data units in the block.
-
-The @code{cpymem@var{m}} patterns need not give special consideration
-to the possibility that the source and destination strings might
-overlap. These patterns are used to do inline expansion of
-@code{__builtin_memcpy}.
-
-@cindex @code{movmem@var{m}} instruction pattern
-@item @samp{movmem@var{m}}
-Block move instruction. The destination and source blocks of memory
-are the first two operands, and both are @code{mem:BLK}s with an
-address in mode @code{Pmode}.
-
-The number of bytes to copy is the third operand, in mode @var{m}.
-Usually, you specify @code{Pmode} for @var{m}. However, if you can
-generate better code knowing the range of valid lengths is smaller than
-those representable in a full Pmode pointer, you should provide
-a pattern with a
-mode corresponding to the range of values you can handle efficiently
-(e.g., @code{QImode} for values in the range 0--127; note we avoid numbers
-that appear negative) and also a pattern with @code{Pmode}.
-
-The fourth operand is the known shared alignment of the source and
-destination, in the form of a @code{const_int} rtx. Thus, if the
-compiler knows that both source and destination are word-aligned,
-it may provide the value 4 for this operand.
-
-Optional operands 5 and 6 specify expected alignment and size of block
-respectively. The expected alignment differs from alignment in operand 4
-in a way that the blocks are not required to be aligned according to it in
-all cases. This expected alignment is also in bytes, just like operand 4.
-Expected size, when unknown, is set to @code{(const_int -1)}.
-
-Descriptions of multiple @code{movmem@var{m}} patterns can only be
-beneficial if the patterns for smaller modes have fewer restrictions
-on their first, second and fourth operands. Note that the mode @var{m}
-in @code{movmem@var{m}} does not impose any restriction on the mode of
-individually copied data units in the block.
-
-The @code{movmem@var{m}} patterns must correctly handle the case where
-the source and destination strings overlap. These patterns are used to
-do inline expansion of @code{__builtin_memmove}.
-
-@cindex @code{movstr} instruction pattern
-@item @samp{movstr}
-String copy instruction, with @code{stpcpy} semantics. Operand 0 is
-an output operand in mode @code{Pmode}. The addresses of the
-destination and source strings are operands 1 and 2, and both are
-@code{mem:BLK}s with addresses in mode @code{Pmode}. The execution of
-the expansion of this pattern should store in operand 0 the address in
-which the @code{NUL} terminator was stored in the destination string.
-
-This pattern has also several optional operands that are same as in
-@code{setmem}.
-
-@cindex @code{setmem@var{m}} instruction pattern
-@item @samp{setmem@var{m}}
-Block set instruction. The destination string is the first operand,
-given as a @code{mem:BLK} whose address is in mode @code{Pmode}. The
-number of bytes to set is the second operand, in mode @var{m}. The value to
-initialize the memory with is the third operand. Targets that only support the
-clearing of memory should reject any value that is not the constant 0. See
-@samp{cpymem@var{m}} for a discussion of the choice of mode.
-
-The fourth operand is the known alignment of the destination, in the form
-of a @code{const_int} rtx. Thus, if the compiler knows that the
-destination is word-aligned, it may provide the value 4 for this
-operand.
-
-Optional operands 5 and 6 specify expected alignment and size of block
-respectively. The expected alignment differs from alignment in operand 4
-in a way that the blocks are not required to be aligned according to it in
-all cases. This expected alignment is also in bytes, just like operand 4.
-Expected size, when unknown, is set to @code{(const_int -1)}.
-Operand 7 is the minimal size of the block and operand 8 is the
-maximal size of the block (NULL if it cannot be represented as CONST_INT).
-Operand 9 is the probable maximal size (i.e.@: we cannot rely on it for
-correctness, but it can be used for choosing proper code sequence for a
-given size).
-
-The use for multiple @code{setmem@var{m}} is as for @code{cpymem@var{m}}.
-
-@cindex @code{cmpstrn@var{m}} instruction pattern
-@item @samp{cmpstrn@var{m}}
-String compare instruction, with five operands. Operand 0 is the output;
-it has mode @var{m}. The remaining four operands are like the operands
-of @samp{cpymem@var{m}}. The two memory blocks specified are compared
-byte by byte in lexicographic order starting at the beginning of each
-string. The instruction is not allowed to prefetch more than one byte
-at a time since either string may end in the first byte and reading past
-that may access an invalid page or segment and cause a fault. The
-comparison terminates early if the fetched bytes are different or if
-they are equal to zero. The effect of the instruction is to store a
-value in operand 0 whose sign indicates the result of the comparison.
-
-@cindex @code{cmpstr@var{m}} instruction pattern
-@item @samp{cmpstr@var{m}}
-String compare instruction, without known maximum length. Operand 0 is the
-output; it has mode @var{m}. The second and third operand are the blocks of
-memory to be compared; both are @code{mem:BLK} with an address in mode
-@code{Pmode}.
-
-The fourth operand is the known shared alignment of the source and
-destination, in the form of a @code{const_int} rtx. Thus, if the
-compiler knows that both source and destination are word-aligned,
-it may provide the value 4 for this operand.
-
-The two memory blocks specified are compared byte by byte in lexicographic
-order starting at the beginning of each string. The instruction is not allowed
-to prefetch more than one byte at a time since either string may end in the
-first byte and reading past that may access an invalid page or segment and
-cause a fault. The comparison will terminate when the fetched bytes
-are different or if they are equal to zero. The effect of the
-instruction is to store a value in operand 0 whose sign indicates the
-result of the comparison.
-
-@cindex @code{cmpmem@var{m}} instruction pattern
-@item @samp{cmpmem@var{m}}
-Block compare instruction, with five operands like the operands
-of @samp{cmpstr@var{m}}. The two memory blocks specified are compared
-byte by byte in lexicographic order starting at the beginning of each
-block. Unlike @samp{cmpstr@var{m}} the instruction can prefetch
-any bytes in the two memory blocks. Also unlike @samp{cmpstr@var{m}}
-the comparison will not stop if both bytes are zero. The effect of
-the instruction is to store a value in operand 0 whose sign indicates
-the result of the comparison.
-
-@cindex @code{strlen@var{m}} instruction pattern
-@item @samp{strlen@var{m}}
-Compute the length of a string, with three operands.
-Operand 0 is the result (of mode @var{m}), operand 1 is
-a @code{mem} referring to the first character of the string,
-operand 2 is the character to search for (normally zero),
-and operand 3 is a constant describing the known alignment
-of the beginning of the string.
-
-@cindex @code{rawmemchr@var{m}} instruction pattern
-@item @samp{rawmemchr@var{m}}
-Scan memory referred to by operand 1 for the first occurrence of operand 2.
-Operand 1 is a @code{mem} and operand 2 a @code{const_int} of mode @var{m}.
-Operand 0 is the result, i.e., a pointer to the first occurrence of operand 2
-in the memory block given by operand 1.
-
-@cindex @code{float@var{m}@var{n}2} instruction pattern
-@item @samp{float@var{m}@var{n}2}
-Convert signed integer operand 1 (valid for fixed point mode @var{m}) to
-floating point mode @var{n} and store in operand 0 (which has mode
-@var{n}).
-
-@cindex @code{floatuns@var{m}@var{n}2} instruction pattern
-@item @samp{floatuns@var{m}@var{n}2}
-Convert unsigned integer operand 1 (valid for fixed point mode @var{m})
-to floating point mode @var{n} and store in operand 0 (which has mode
-@var{n}).
-
-@cindex @code{fix@var{m}@var{n}2} instruction pattern
-@item @samp{fix@var{m}@var{n}2}
-Convert operand 1 (valid for floating point mode @var{m}) to fixed
-point mode @var{n} as a signed number and store in operand 0 (which
-has mode @var{n}). This instruction's result is defined only when
-the value of operand 1 is an integer.
-
-If the machine description defines this pattern, it also needs to
-define the @code{ftrunc} pattern.
-
-@cindex @code{fixuns@var{m}@var{n}2} instruction pattern
-@item @samp{fixuns@var{m}@var{n}2}
-Convert operand 1 (valid for floating point mode @var{m}) to fixed
-point mode @var{n} as an unsigned number and store in operand 0 (which
-has mode @var{n}). This instruction's result is defined only when the
-value of operand 1 is an integer.
-
-@cindex @code{ftrunc@var{m}2} instruction pattern
-@item @samp{ftrunc@var{m}2}
-Convert operand 1 (valid for floating point mode @var{m}) to an
-integer value, still represented in floating point mode @var{m}, and
-store it in operand 0 (valid for floating point mode @var{m}).
-
-@cindex @code{fix_trunc@var{m}@var{n}2} instruction pattern
-@item @samp{fix_trunc@var{m}@var{n}2}
-Like @samp{fix@var{m}@var{n}2} but works for any floating point value
-of mode @var{m} by converting the value to an integer.
-
-@cindex @code{fixuns_trunc@var{m}@var{n}2} instruction pattern
-@item @samp{fixuns_trunc@var{m}@var{n}2}
-Like @samp{fixuns@var{m}@var{n}2} but works for any floating point
-value of mode @var{m} by converting the value to an integer.
-
-@cindex @code{trunc@var{m}@var{n}2} instruction pattern
-@item @samp{trunc@var{m}@var{n}2}
-Truncate operand 1 (valid for mode @var{m}) to mode @var{n} and
-store in operand 0 (which has mode @var{n}). Both modes must be fixed
-point or both floating point.
-
-@cindex @code{extend@var{m}@var{n}2} instruction pattern
-@item @samp{extend@var{m}@var{n}2}
-Sign-extend operand 1 (valid for mode @var{m}) to mode @var{n} and
-store in operand 0 (which has mode @var{n}). Both modes must be fixed
-point or both floating point.
-
-@cindex @code{zero_extend@var{m}@var{n}2} instruction pattern
-@item @samp{zero_extend@var{m}@var{n}2}
-Zero-extend operand 1 (valid for mode @var{m}) to mode @var{n} and
-store in operand 0 (which has mode @var{n}). Both modes must be fixed
-point.
-
-@cindex @code{fract@var{m}@var{n}2} instruction pattern
-@item @samp{fract@var{m}@var{n}2}
-Convert operand 1 of mode @var{m} to mode @var{n} and store in
-operand 0 (which has mode @var{n}). Mode @var{m} and mode @var{n}
-could be fixed-point to fixed-point, signed integer to fixed-point,
-fixed-point to signed integer, floating-point to fixed-point,
-or fixed-point to floating-point.
-When overflows or underflows happen, the results are undefined.
-
-@cindex @code{satfract@var{m}@var{n}2} instruction pattern
-@item @samp{satfract@var{m}@var{n}2}
-Convert operand 1 of mode @var{m} to mode @var{n} and store in
-operand 0 (which has mode @var{n}). Mode @var{m} and mode @var{n}
-could be fixed-point to fixed-point, signed integer to fixed-point,
-or floating-point to fixed-point.
-When overflows or underflows happen, the instruction saturates the
-results to the maximum or the minimum.
-
-@cindex @code{fractuns@var{m}@var{n}2} instruction pattern
-@item @samp{fractuns@var{m}@var{n}2}
-Convert operand 1 of mode @var{m} to mode @var{n} and store in
-operand 0 (which has mode @var{n}). Mode @var{m} and mode @var{n}
-could be unsigned integer to fixed-point, or
-fixed-point to unsigned integer.
-When overflows or underflows happen, the results are undefined.
-
-@cindex @code{satfractuns@var{m}@var{n}2} instruction pattern
-@item @samp{satfractuns@var{m}@var{n}2}
-Convert unsigned integer operand 1 of mode @var{m} to fixed-point mode
-@var{n} and store in operand 0 (which has mode @var{n}).
-When overflows or underflows happen, the instruction saturates the
-results to the maximum or the minimum.
-
-@cindex @code{extv@var{m}} instruction pattern
-@item @samp{extv@var{m}}
-Extract a bit-field from register operand 1, sign-extend it, and store
-it in operand 0. Operand 2 specifies the width of the field in bits
-and operand 3 the starting bit, which counts from the most significant
-bit if @samp{BITS_BIG_ENDIAN} is true and from the least significant bit
-otherwise.
-
-Operands 0 and 1 both have mode @var{m}. Operands 2 and 3 have a
-target-specific mode.
-
-@cindex @code{extvmisalign@var{m}} instruction pattern
-@item @samp{extvmisalign@var{m}}
-Extract a bit-field from memory operand 1, sign extend it, and store
-it in operand 0. Operand 2 specifies the width in bits and operand 3
-the starting bit. The starting bit is always somewhere in the first byte of
-operand 1; it counts from the most significant bit if @samp{BITS_BIG_ENDIAN}
-is true and from the least significant bit otherwise.
-
-Operand 0 has mode @var{m} while operand 1 has @code{BLK} mode.
-Operands 2 and 3 have a target-specific mode.
-
-The instruction must not read beyond the last byte of the bit-field.
-
-@cindex @code{extzv@var{m}} instruction pattern
-@item @samp{extzv@var{m}}
-Like @samp{extv@var{m}} except that the bit-field value is zero-extended.
-
-@cindex @code{extzvmisalign@var{m}} instruction pattern
-@item @samp{extzvmisalign@var{m}}
-Like @samp{extvmisalign@var{m}} except that the bit-field value is
-zero-extended.
-
-@cindex @code{insv@var{m}} instruction pattern
-@item @samp{insv@var{m}}
-Insert operand 3 into a bit-field of register operand 0. Operand 1
-specifies the width of the field in bits and operand 2 the starting bit,
-which counts from the most significant bit if @samp{BITS_BIG_ENDIAN}
-is true and from the least significant bit otherwise.
-
-Operands 0 and 3 both have mode @var{m}. Operands 1 and 2 have a
-target-specific mode.
-
-@cindex @code{insvmisalign@var{m}} instruction pattern
-@item @samp{insvmisalign@var{m}}
-Insert operand 3 into a bit-field of memory operand 0. Operand 1
-specifies the width of the field in bits and operand 2 the starting bit.
-The starting bit is always somewhere in the first byte of operand 0;
-it counts from the most significant bit if @samp{BITS_BIG_ENDIAN}
-is true and from the least significant bit otherwise.
-
-Operand 3 has mode @var{m} while operand 0 has @code{BLK} mode.
-Operands 1 and 2 have a target-specific mode.
-
-The instruction must not read or write beyond the last byte of the bit-field.
-
-@cindex @code{extv} instruction pattern
-@item @samp{extv}
-Extract a bit-field from operand 1 (a register or memory operand), where
-operand 2 specifies the width in bits and operand 3 the starting bit,
-and store it in operand 0. Operand 0 must have mode @code{word_mode}.
-Operand 1 may have mode @code{byte_mode} or @code{word_mode}; often
-@code{word_mode} is allowed only for registers. Operands 2 and 3 must
-be valid for @code{word_mode}.
-
-The RTL generation pass generates this instruction only with constants
-for operands 2 and 3 and the constant is never zero for operand 2.
-
-The bit-field value is sign-extended to a full word integer
-before it is stored in operand 0.
-
-This pattern is deprecated; please use @samp{extv@var{m}} and
-@code{extvmisalign@var{m}} instead.
-
-@cindex @code{extzv} instruction pattern
-@item @samp{extzv}
-Like @samp{extv} except that the bit-field value is zero-extended.
-
-This pattern is deprecated; please use @samp{extzv@var{m}} and
-@code{extzvmisalign@var{m}} instead.
-
-@cindex @code{insv} instruction pattern
-@item @samp{insv}
-Store operand 3 (which must be valid for @code{word_mode}) into a
-bit-field in operand 0, where operand 1 specifies the width in bits and
-operand 2 the starting bit. Operand 0 may have mode @code{byte_mode} or
-@code{word_mode}; often @code{word_mode} is allowed only for registers.
-Operands 1 and 2 must be valid for @code{word_mode}.
-
-The RTL generation pass generates this instruction only with constants
-for operands 1 and 2 and the constant is never zero for operand 1.
-
-This pattern is deprecated; please use @samp{insv@var{m}} and
-@code{insvmisalign@var{m}} instead.
-
-@cindex @code{mov@var{mode}cc} instruction pattern
-@item @samp{mov@var{mode}cc}
-Conditionally move operand 2 or operand 3 into operand 0 according to the
-comparison in operand 1. If the comparison is true, operand 2 is moved
-into operand 0, otherwise operand 3 is moved.
-
-The mode of the operands being compared need not be the same as the operands
-being moved. Some machines, sparc64 for example, have instructions that
-conditionally move an integer value based on the floating point condition
-codes and vice versa.
-
-If the machine does not have conditional move instructions, do not
-define these patterns.
-
-@cindex @code{add@var{mode}cc} instruction pattern
-@item @samp{add@var{mode}cc}
-Similar to @samp{mov@var{mode}cc} but for conditional addition. Conditionally
-move operand 2 or (operands 2 + operand 3) into operand 0 according to the
-comparison in operand 1. If the comparison is false, operand 2 is moved into
-operand 0, otherwise (operand 2 + operand 3) is moved.
-
-@cindex @code{cond_add@var{mode}} instruction pattern
-@cindex @code{cond_sub@var{mode}} instruction pattern
-@cindex @code{cond_mul@var{mode}} instruction pattern
-@cindex @code{cond_div@var{mode}} instruction pattern
-@cindex @code{cond_udiv@var{mode}} instruction pattern
-@cindex @code{cond_mod@var{mode}} instruction pattern
-@cindex @code{cond_umod@var{mode}} instruction pattern
-@cindex @code{cond_and@var{mode}} instruction pattern
-@cindex @code{cond_ior@var{mode}} instruction pattern
-@cindex @code{cond_xor@var{mode}} instruction pattern
-@cindex @code{cond_smin@var{mode}} instruction pattern
-@cindex @code{cond_smax@var{mode}} instruction pattern
-@cindex @code{cond_umin@var{mode}} instruction pattern
-@cindex @code{cond_umax@var{mode}} instruction pattern
-@cindex @code{cond_fmin@var{mode}} instruction pattern
-@cindex @code{cond_fmax@var{mode}} instruction pattern
-@cindex @code{cond_ashl@var{mode}} instruction pattern
-@cindex @code{cond_ashr@var{mode}} instruction pattern
-@cindex @code{cond_lshr@var{mode}} instruction pattern
-@item @samp{cond_add@var{mode}}
-@itemx @samp{cond_sub@var{mode}}
-@itemx @samp{cond_mul@var{mode}}
-@itemx @samp{cond_div@var{mode}}
-@itemx @samp{cond_udiv@var{mode}}
-@itemx @samp{cond_mod@var{mode}}
-@itemx @samp{cond_umod@var{mode}}
-@itemx @samp{cond_and@var{mode}}
-@itemx @samp{cond_ior@var{mode}}
-@itemx @samp{cond_xor@var{mode}}
-@itemx @samp{cond_smin@var{mode}}
-@itemx @samp{cond_smax@var{mode}}
-@itemx @samp{cond_umin@var{mode}}
-@itemx @samp{cond_umax@var{mode}}
-@itemx @samp{cond_fmin@var{mode}}
-@itemx @samp{cond_fmax@var{mode}}
-@itemx @samp{cond_ashl@var{mode}}
-@itemx @samp{cond_ashr@var{mode}}
-@itemx @samp{cond_lshr@var{mode}}
-When operand 1 is true, perform an operation on operands 2 and 3 and
-store the result in operand 0, otherwise store operand 4 in operand 0.
-The operation works elementwise if the operands are vectors.
-
-The scalar case is equivalent to:
-
-@smallexample
-op0 = op1 ? op2 @var{op} op3 : op4;
-@end smallexample
-
-while the vector case is equivalent to:
-
-@smallexample
-for (i = 0; i < GET_MODE_NUNITS (@var{m}); i++)
- op0[i] = op1[i] ? op2[i] @var{op} op3[i] : op4[i];
-@end smallexample
-
-where, for example, @var{op} is @code{+} for @samp{cond_add@var{mode}}.
-
-When defined for floating-point modes, the contents of @samp{op3[i]}
-are not interpreted if @samp{op1[i]} is false, just like they would not
-be in a normal C @samp{?:} condition.
-
-Operands 0, 2, 3 and 4 all have mode @var{m}. Operand 1 is a scalar
-integer if @var{m} is scalar, otherwise it has the mode returned by
-@code{TARGET_VECTORIZE_GET_MASK_MODE}.
-
-@samp{cond_@var{op}@var{mode}} generally corresponds to a conditional
-form of @samp{@var{op}@var{mode}3}. As an exception, the vector forms
-of shifts correspond to patterns like @code{vashl@var{mode}3} rather
-than patterns like @code{ashl@var{mode}3}.
-
-@cindex @code{cond_fma@var{mode}} instruction pattern
-@cindex @code{cond_fms@var{mode}} instruction pattern
-@cindex @code{cond_fnma@var{mode}} instruction pattern
-@cindex @code{cond_fnms@var{mode}} instruction pattern
-@item @samp{cond_fma@var{mode}}
-@itemx @samp{cond_fms@var{mode}}
-@itemx @samp{cond_fnma@var{mode}}
-@itemx @samp{cond_fnms@var{mode}}
-Like @samp{cond_add@var{m}}, except that the conditional operation
-takes 3 operands rather than two. For example, the vector form of
-@samp{cond_fma@var{mode}} is equivalent to:
-
-@smallexample
-for (i = 0; i < GET_MODE_NUNITS (@var{m}); i++)
- op0[i] = op1[i] ? fma (op2[i], op3[i], op4[i]) : op5[i];
-@end smallexample
-
-@cindex @code{neg@var{mode}cc} instruction pattern
-@item @samp{neg@var{mode}cc}
-Similar to @samp{mov@var{mode}cc} but for conditional negation. Conditionally
-move the negation of operand 2 or the unchanged operand 3 into operand 0
-according to the comparison in operand 1. If the comparison is true, the negation
-of operand 2 is moved into operand 0, otherwise operand 3 is moved.
-
-@cindex @code{not@var{mode}cc} instruction pattern
-@item @samp{not@var{mode}cc}
-Similar to @samp{neg@var{mode}cc} but for conditional complement.
-Conditionally move the bitwise complement of operand 2 or the unchanged
-operand 3 into operand 0 according to the comparison in operand 1.
-If the comparison is true, the complement of operand 2 is moved into
-operand 0, otherwise operand 3 is moved.
-
-@cindex @code{cstore@var{mode}4} instruction pattern
-@item @samp{cstore@var{mode}4}
-Store zero or nonzero in operand 0 according to whether a comparison
-is true. Operand 1 is a comparison operator. Operand 2 and operand 3
-are the first and second operand of the comparison, respectively.
-You specify the mode that operand 0 must have when you write the
-@code{match_operand} expression. The compiler automatically sees which
-mode you have used and supplies an operand of that mode.
-
-The value stored for a true condition must have 1 as its low bit, or
-else must be negative. Otherwise the instruction is not suitable and
-you should omit it from the machine description. You describe to the
-compiler exactly which value is stored by defining the macro
-@code{STORE_FLAG_VALUE} (@pxref{Misc}). If a description cannot be
-found that can be used for all the possible comparison operators, you
-should pick one and use a @code{define_expand} to map all results
-onto the one you chose.
-
-These operations may @code{FAIL}, but should do so only in relatively
-uncommon cases; if they would @code{FAIL} for common cases involving
-integer comparisons, it is best to restrict the predicates to not
-allow these operands. Likewise if a given comparison operator will
-always fail, independent of the operands (for floating-point modes, the
-@code{ordered_comparison_operator} predicate is often useful in this case).
-
-If this pattern is omitted, the compiler will generate a conditional
-branch---for example, it may copy a constant one to the target and branching
-around an assignment of zero to the target---or a libcall. If the predicate
-for operand 1 only rejects some operators, it will also try reordering the
-operands and/or inverting the result value (e.g.@: by an exclusive OR).
-These possibilities could be cheaper or equivalent to the instructions
-used for the @samp{cstore@var{mode}4} pattern followed by those required
-to convert a positive result from @code{STORE_FLAG_VALUE} to 1; in this
-case, you can and should make operand 1's predicate reject some operators
-in the @samp{cstore@var{mode}4} pattern, or remove the pattern altogether
-from the machine description.
-
-@cindex @code{cbranch@var{mode}4} instruction pattern
-@item @samp{cbranch@var{mode}4}
-Conditional branch instruction combined with a compare instruction.
-Operand 0 is a comparison operator. Operand 1 and operand 2 are the
-first and second operands of the comparison, respectively. Operand 3
-is the @code{code_label} to jump to.
-
-@cindex @code{jump} instruction pattern
-@item @samp{jump}
-A jump inside a function; an unconditional branch. Operand 0 is the
-@code{code_label} to jump to. This pattern name is mandatory on all
-machines.
-
-@cindex @code{call} instruction pattern
-@item @samp{call}
-Subroutine call instruction returning no value. Operand 0 is the
-function to call; operand 1 is the number of bytes of arguments pushed
-as a @code{const_int}. Operand 2 is the result of calling the target
-hook @code{TARGET_FUNCTION_ARG} with the second argument @code{arg}
-yielding true for @code{arg.end_marker_p ()}, in a call after all
-parameters have been passed to that hook. By default this is the first
-register beyond those used for arguments in the call, or @code{NULL} if
-all the argument-registers are used in the call.
-
-On most machines, operand 2 is not actually stored into the RTL
-pattern. It is supplied for the sake of some RISC machines which need
-to put this information into the assembler code; they can put it in
-the RTL instead of operand 1.
-
-Operand 0 should be a @code{mem} RTX whose address is the address of the
-function. Note, however, that this address can be a @code{symbol_ref}
-expression even if it would not be a legitimate memory address on the
-target machine. If it is also not a valid argument for a call
-instruction, the pattern for this operation should be a
-@code{define_expand} (@pxref{Expander Definitions}) that places the
-address into a register and uses that register in the call instruction.
-
-@cindex @code{call_value} instruction pattern
-@item @samp{call_value}
-Subroutine call instruction returning a value. Operand 0 is the hard
-register in which the value is returned. There are three more
-operands, the same as the three operands of the @samp{call}
-instruction (but with numbers increased by one).
-
-Subroutines that return @code{BLKmode} objects use the @samp{call}
-insn.
-
-@cindex @code{call_pop} instruction pattern
-@cindex @code{call_value_pop} instruction pattern
-@item @samp{call_pop}, @samp{call_value_pop}
-Similar to @samp{call} and @samp{call_value}, except used if defined and
-if @code{RETURN_POPS_ARGS} is nonzero. They should emit a @code{parallel}
-that contains both the function call and a @code{set} to indicate the
-adjustment made to the frame pointer.
-
-For machines where @code{RETURN_POPS_ARGS} can be nonzero, the use of these
-patterns increases the number of functions for which the frame pointer
-can be eliminated, if desired.
-
-@cindex @code{untyped_call} instruction pattern
-@item @samp{untyped_call}
-Subroutine call instruction returning a value of any type. Operand 0 is
-the function to call; operand 1 is a memory location where the result of
-calling the function is to be stored; operand 2 is a @code{parallel}
-expression where each element is a @code{set} expression that indicates
-the saving of a function return value into the result block.
-
-This instruction pattern should be defined to support
-@code{__builtin_apply} on machines where special instructions are needed
-to call a subroutine with arbitrary arguments or to save the value
-returned. This instruction pattern is required on machines that have
-multiple registers that can hold a return value
-(i.e.@: @code{FUNCTION_VALUE_REGNO_P} is true for more than one register).
-
-@cindex @code{return} instruction pattern
-@item @samp{return}
-Subroutine return instruction. This instruction pattern name should be
-defined only if a single instruction can do all the work of returning
-from a function.
-
-Like the @samp{mov@var{m}} patterns, this pattern is also used after the
-RTL generation phase. In this case it is to support machines where
-multiple instructions are usually needed to return from a function, but
-some class of functions only requires one instruction to implement a
-return. Normally, the applicable functions are those which do not need
-to save any registers or allocate stack space.
-
-It is valid for this pattern to expand to an instruction using
-@code{simple_return} if no epilogue is required.
-
-@cindex @code{simple_return} instruction pattern
-@item @samp{simple_return}
-Subroutine return instruction. This instruction pattern name should be
-defined only if a single instruction can do all the work of returning
-from a function on a path where no epilogue is required. This pattern
-is very similar to the @code{return} instruction pattern, but it is emitted
-only by the shrink-wrapping optimization on paths where the function
-prologue has not been executed, and a function return should occur without
-any of the effects of the epilogue. Additional uses may be introduced on
-paths where both the prologue and the epilogue have executed.
-
-@findex reload_completed
-@findex leaf_function_p
-For such machines, the condition specified in this pattern should only
-be true when @code{reload_completed} is nonzero and the function's
-epilogue would only be a single instruction. For machines with register
-windows, the routine @code{leaf_function_p} may be used to determine if
-a register window push is required.
-
-Machines that have conditional return instructions should define patterns
-such as
-
-@smallexample
-(define_insn ""
- [(set (pc)
- (if_then_else (match_operator
- 0 "comparison_operator"
- [(reg:CC CC_REG) (const_int 0)])
- (return)
- (pc)))]
- "@var{condition}"
- "@dots{}")
-@end smallexample
-
-where @var{condition} would normally be the same condition specified on the
-named @samp{return} pattern.
-
-@cindex @code{untyped_return} instruction pattern
-@item @samp{untyped_return}
-Untyped subroutine return instruction. This instruction pattern should
-be defined to support @code{__builtin_return} on machines where special
-instructions are needed to return a value of any type.
-
-Operand 0 is a memory location where the result of calling a function
-with @code{__builtin_apply} is stored; operand 1 is a @code{parallel}
-expression where each element is a @code{set} expression that indicates
-the restoring of a function return value from the result block.
-
-@cindex @code{nop} instruction pattern
-@item @samp{nop}
-No-op instruction. This instruction pattern name should always be defined
-to output a no-op in assembler code. @code{(const_int 0)} will do as an
-RTL pattern.
-
-@cindex @code{indirect_jump} instruction pattern
-@item @samp{indirect_jump}
-An instruction to jump to an address which is operand zero.
-This pattern name is mandatory on all machines.
-
-@cindex @code{casesi} instruction pattern
-@item @samp{casesi}
-Instruction to jump through a dispatch table, including bounds checking.
-This instruction takes five operands:
-
-@enumerate
-@item
-The index to dispatch on, which has mode @code{SImode}.
-
-@item
-The lower bound for indices in the table, an integer constant.
-
-@item
-The total range of indices in the table---the largest index
-minus the smallest one (both inclusive).
-
-@item
-A label that precedes the table itself.
-
-@item
-A label to jump to if the index has a value outside the bounds.
-@end enumerate
-
-The table is an @code{addr_vec} or @code{addr_diff_vec} inside of a
-@code{jump_table_data}. The number of elements in the table is one plus the
-difference between the upper bound and the lower bound.
-
-@cindex @code{tablejump} instruction pattern
-@item @samp{tablejump}
-Instruction to jump to a variable address. This is a low-level
-capability which can be used to implement a dispatch table when there
-is no @samp{casesi} pattern.
-
-This pattern requires two operands: the address or offset, and a label
-which should immediately precede the jump table. If the macro
-@code{CASE_VECTOR_PC_RELATIVE} evaluates to a nonzero value then the first
-operand is an offset which counts from the address of the table; otherwise,
-it is an absolute address to jump to. In either case, the first operand has
-mode @code{Pmode}.
-
-The @samp{tablejump} insn is always the last insn before the jump
-table it uses. Its assembler code normally has no need to use the
-second operand, but you should incorporate it in the RTL pattern so
-that the jump optimizer will not delete the table as unreachable code.
-
-
-@cindex @code{doloop_end} instruction pattern
-@item @samp{doloop_end}
-Conditional branch instruction that decrements a register and
-jumps if the register is nonzero. Operand 0 is the register to
-decrement and test; operand 1 is the label to jump to if the
-register is nonzero.
-@xref{Looping Patterns}.
-
-This optional instruction pattern should be defined for machines with
-low-overhead looping instructions as the loop optimizer will try to
-modify suitable loops to utilize it. The target hook
-@code{TARGET_CAN_USE_DOLOOP_P} controls the conditions under which
-low-overhead loops can be used.
-
-@cindex @code{doloop_begin} instruction pattern
-@item @samp{doloop_begin}
-Companion instruction to @code{doloop_end} required for machines that
-need to perform some initialization, such as loading a special counter
-register. Operand 1 is the associated @code{doloop_end} pattern and
-operand 0 is the register that it decrements.
-
-If initialization insns do not always need to be emitted, use a
-@code{define_expand} (@pxref{Expander Definitions}) and make it fail.
-
-@cindex @code{canonicalize_funcptr_for_compare} instruction pattern
-@item @samp{canonicalize_funcptr_for_compare}
-Canonicalize the function pointer in operand 1 and store the result
-into operand 0.
-
-Operand 0 is always a @code{reg} and has mode @code{Pmode}; operand 1
-may be a @code{reg}, @code{mem}, @code{symbol_ref}, @code{const_int}, etc
-and also has mode @code{Pmode}.
-
-Canonicalization of a function pointer usually involves computing
-the address of the function which would be called if the function
-pointer were used in an indirect call.
-
-Only define this pattern if function pointers on the target machine
-can have different values but still call the same function when
-used in an indirect call.
-
-@cindex @code{save_stack_block} instruction pattern
-@cindex @code{save_stack_function} instruction pattern
-@cindex @code{save_stack_nonlocal} instruction pattern
-@cindex @code{restore_stack_block} instruction pattern
-@cindex @code{restore_stack_function} instruction pattern
-@cindex @code{restore_stack_nonlocal} instruction pattern
-@item @samp{save_stack_block}
-@itemx @samp{save_stack_function}
-@itemx @samp{save_stack_nonlocal}
-@itemx @samp{restore_stack_block}
-@itemx @samp{restore_stack_function}
-@itemx @samp{restore_stack_nonlocal}
-Most machines save and restore the stack pointer by copying it to or
-from an object of mode @code{Pmode}. Do not define these patterns on
-such machines.
-
-Some machines require special handling for stack pointer saves and
-restores. On those machines, define the patterns corresponding to the
-non-standard cases by using a @code{define_expand} (@pxref{Expander
-Definitions}) that produces the required insns. The three types of
-saves and restores are:
-
-@enumerate
-@item
-@samp{save_stack_block} saves the stack pointer at the start of a block
-that allocates a variable-sized object, and @samp{restore_stack_block}
-restores the stack pointer when the block is exited.
-
-@item
-@samp{save_stack_function} and @samp{restore_stack_function} do a
-similar job for the outermost block of a function and are used when the
-function allocates variable-sized objects or calls @code{alloca}. Only
-the epilogue uses the restored stack pointer, allowing a simpler save or
-restore sequence on some machines.
-
-@item
-@samp{save_stack_nonlocal} is used in functions that contain labels
-branched to by nested functions. It saves the stack pointer in such a
-way that the inner function can use @samp{restore_stack_nonlocal} to
-restore the stack pointer. The compiler generates code to restore the
-frame and argument pointer registers, but some machines require saving
-and restoring additional data such as register window information or
-stack backchains. Place insns in these patterns to save and restore any
-such required data.
-@end enumerate
-
-When saving the stack pointer, operand 0 is the save area and operand 1
-is the stack pointer. The mode used to allocate the save area defaults
-to @code{Pmode} but you can override that choice by defining the
-@code{STACK_SAVEAREA_MODE} macro (@pxref{Storage Layout}). You must
-specify an integral mode, or @code{VOIDmode} if no save area is needed
-for a particular type of save (either because no save is needed or
-because a machine-specific save area can be used). Operand 0 is the
-stack pointer and operand 1 is the save area for restore operations. If
-@samp{save_stack_block} is defined, operand 0 must not be
-@code{VOIDmode} since these saves can be arbitrarily nested.
-
-A save area is a @code{mem} that is at a constant offset from
-@code{virtual_stack_vars_rtx} when the stack pointer is saved for use by
-nonlocal gotos and a @code{reg} in the other two cases.
-
-@cindex @code{allocate_stack} instruction pattern
-@item @samp{allocate_stack}
-Subtract (or add if @code{STACK_GROWS_DOWNWARD} is undefined) operand 1 from
-the stack pointer to create space for dynamically allocated data.
-
-Store the resultant pointer to this space into operand 0. If you
-are allocating space from the main stack, do this by emitting a
-move insn to copy @code{virtual_stack_dynamic_rtx} to operand 0.
-If you are allocating the space elsewhere, generate code to copy the
-location of the space to operand 0. In the latter case, you must
-ensure this space gets freed when the corresponding space on the main
-stack is free.
-
-Do not define this pattern if all that must be done is the subtraction.
-Some machines require other operations such as stack probes or
-maintaining the back chain. Define this pattern to emit those
-operations in addition to updating the stack pointer.
-
-@cindex @code{check_stack} instruction pattern
-@item @samp{check_stack}
-If stack checking (@pxref{Stack Checking}) cannot be done on your system by
-probing the stack, define this pattern to perform the needed check and signal
-an error if the stack has overflowed. The single operand is the address in
-the stack farthest from the current stack pointer that you need to validate.
-Normally, on platforms where this pattern is needed, you would obtain the
-stack limit from a global or thread-specific variable or register.
-
-@cindex @code{probe_stack_address} instruction pattern
-@item @samp{probe_stack_address}
-If stack checking (@pxref{Stack Checking}) can be done on your system by
-probing the stack but without the need to actually access it, define this
-pattern and signal an error if the stack has overflowed. The single operand
-is the memory address in the stack that needs to be probed.
-
-@cindex @code{probe_stack} instruction pattern
-@item @samp{probe_stack}
-If stack checking (@pxref{Stack Checking}) can be done on your system by
-probing the stack but doing it with a ``store zero'' instruction is not valid
-or optimal, define this pattern to do the probing differently and signal an
-error if the stack has overflowed. The single operand is the memory reference
-in the stack that needs to be probed.
-
-@cindex @code{nonlocal_goto} instruction pattern
-@item @samp{nonlocal_goto}
-Emit code to generate a non-local goto, e.g., a jump from one function
-to a label in an outer function. This pattern has four arguments,
-each representing a value to be used in the jump. The first
-argument is to be loaded into the frame pointer, the second is
-the address to branch to (code to dispatch to the actual label),
-the third is the address of a location where the stack is saved,
-and the last is the address of the label, to be placed in the
-location for the incoming static chain.
-
-On most machines you need not define this pattern, since GCC will
-already generate the correct code, which is to load the frame pointer
-and static chain, restore the stack (using the
-@samp{restore_stack_nonlocal} pattern, if defined), and jump indirectly
-to the dispatcher. You need only define this pattern if this code will
-not work on your machine.
-
-@cindex @code{nonlocal_goto_receiver} instruction pattern
-@item @samp{nonlocal_goto_receiver}
-This pattern, if defined, contains code needed at the target of a
-nonlocal goto after the code already generated by GCC@. You will not
-normally need to define this pattern. A typical reason why you might
-need this pattern is if some value, such as a pointer to a global table,
-must be restored when the frame pointer is restored. Note that a nonlocal
-goto only occurs within a unit-of-translation, so a global table pointer
-that is shared by all functions of a given module need not be restored.
-There are no arguments.
-
-@cindex @code{exception_receiver} instruction pattern
-@item @samp{exception_receiver}
-This pattern, if defined, contains code needed at the site of an
-exception handler that isn't needed at the site of a nonlocal goto. You
-will not normally need to define this pattern. A typical reason why you
-might need this pattern is if some value, such as a pointer to a global
-table, must be restored after control flow is branched to the handler of
-an exception. There are no arguments.
-
-@cindex @code{builtin_setjmp_setup} instruction pattern
-@item @samp{builtin_setjmp_setup}
-This pattern, if defined, contains additional code needed to initialize
-the @code{jmp_buf}. You will not normally need to define this pattern.
-A typical reason why you might need this pattern is if some value, such
-as a pointer to a global table, must be restored. Though it is
-preferred that the pointer value be recalculated if possible (given the
-address of a label for instance). The single argument is a pointer to
-the @code{jmp_buf}. Note that the buffer is five words long and that
-the first three are normally used by the generic mechanism.
-
-@cindex @code{builtin_setjmp_receiver} instruction pattern
-@item @samp{builtin_setjmp_receiver}
-This pattern, if defined, contains code needed at the site of a
-built-in setjmp that isn't needed at the site of a nonlocal goto. You
-will not normally need to define this pattern. A typical reason why you
-might need this pattern is if some value, such as a pointer to a global
-table, must be restored. It takes one argument, which is the label
-to which builtin_longjmp transferred control; this pattern may be emitted
-at a small offset from that label.
-
-@cindex @code{builtin_longjmp} instruction pattern
-@item @samp{builtin_longjmp}
-This pattern, if defined, performs the entire action of the longjmp.
-You will not normally need to define this pattern unless you also define
-@code{builtin_setjmp_setup}. The single argument is a pointer to the
-@code{jmp_buf}.
-
-@cindex @code{eh_return} instruction pattern
-@item @samp{eh_return}
-This pattern, if defined, affects the way @code{__builtin_eh_return},
-and thence the call frame exception handling library routines, are
-built. It is intended to handle non-trivial actions needed along
-the abnormal return path.
-
-The address of the exception handler to which the function should return
-is passed as operand to this pattern. It will normally need to copied by
-the pattern to some special register or memory location.
-If the pattern needs to determine the location of the target call
-frame in order to do so, it may use @code{EH_RETURN_STACKADJ_RTX},
-if defined; it will have already been assigned.
-
-If this pattern is not defined, the default action will be to simply
-copy the return address to @code{EH_RETURN_HANDLER_RTX}. Either
-that macro or this pattern needs to be defined if call frame exception
-handling is to be used.
-
-@cindex @code{prologue} instruction pattern
-@anchor{prologue instruction pattern}
-@item @samp{prologue}
-This pattern, if defined, emits RTL for entry to a function. The function
-entry is responsible for setting up the stack frame, initializing the frame
-pointer register, saving callee saved registers, etc.
-
-Using a prologue pattern is generally preferred over defining
-@code{TARGET_ASM_FUNCTION_PROLOGUE} to emit assembly code for the prologue.
-
-The @code{prologue} pattern is particularly useful for targets which perform
-instruction scheduling.
-
-@cindex @code{window_save} instruction pattern
-@anchor{window_save instruction pattern}
-@item @samp{window_save}
-This pattern, if defined, emits RTL for a register window save. It should
-be defined if the target machine has register windows but the window events
-are decoupled from calls to subroutines. The canonical example is the SPARC
-architecture.
-
-@cindex @code{epilogue} instruction pattern
-@anchor{epilogue instruction pattern}
-@item @samp{epilogue}
-This pattern emits RTL for exit from a function. The function
-exit is responsible for deallocating the stack frame, restoring callee saved
-registers and emitting the return instruction.
-
-Using an epilogue pattern is generally preferred over defining
-@code{TARGET_ASM_FUNCTION_EPILOGUE} to emit assembly code for the epilogue.
-
-The @code{epilogue} pattern is particularly useful for targets which perform
-instruction scheduling or which have delay slots for their return instruction.
-
-@cindex @code{sibcall_epilogue} instruction pattern
-@item @samp{sibcall_epilogue}
-This pattern, if defined, emits RTL for exit from a function without the final
-branch back to the calling function. This pattern will be emitted before any
-sibling call (aka tail call) sites.
-
-The @code{sibcall_epilogue} pattern must not clobber any arguments used for
-parameter passing or any stack slots for arguments passed to the current
-function.
-
-@cindex @code{trap} instruction pattern
-@item @samp{trap}
-This pattern, if defined, signals an error, typically by causing some
-kind of signal to be raised.
-
-@cindex @code{ctrap@var{MM}4} instruction pattern
-@item @samp{ctrap@var{MM}4}
-Conditional trap instruction. Operand 0 is a piece of RTL which
-performs a comparison, and operands 1 and 2 are the arms of the
-comparison. Operand 3 is the trap code, an integer.
-
-A typical @code{ctrap} pattern looks like
-
-@smallexample
-(define_insn "ctrapsi4"
- [(trap_if (match_operator 0 "trap_operator"
- [(match_operand 1 "register_operand")
- (match_operand 2 "immediate_operand")])
- (match_operand 3 "const_int_operand" "i"))]
- ""
- "@dots{}")
-@end smallexample
-
-@cindex @code{prefetch} instruction pattern
-@item @samp{prefetch}
-This pattern, if defined, emits code for a non-faulting data prefetch
-instruction. Operand 0 is the address of the memory to prefetch. Operand 1
-is a constant 1 if the prefetch is preparing for a write to the memory
-address, or a constant 0 otherwise. Operand 2 is the expected degree of
-temporal locality of the data and is a value between 0 and 3, inclusive; 0
-means that the data has no temporal locality, so it need not be left in the
-cache after the access; 3 means that the data has a high degree of temporal
-locality and should be left in all levels of cache possible; 1 and 2 mean,
-respectively, a low or moderate degree of temporal locality.
-
-Targets that do not support write prefetches or locality hints can ignore
-the values of operands 1 and 2.
-
-@cindex @code{blockage} instruction pattern
-@item @samp{blockage}
-This pattern defines a pseudo insn that prevents the instruction
-scheduler and other passes from moving instructions and using register
-equivalences across the boundary defined by the blockage insn.
-This needs to be an UNSPEC_VOLATILE pattern or a volatile ASM.
-
-@cindex @code{memory_blockage} instruction pattern
-@item @samp{memory_blockage}
-This pattern, if defined, represents a compiler memory barrier, and will be
-placed at points across which RTL passes may not propagate memory accesses.
-This instruction needs to read and write volatile BLKmode memory. It does
-not need to generate any machine instruction. If this pattern is not defined,
-the compiler falls back to emitting an instruction corresponding
-to @code{asm volatile ("" ::: "memory")}.
-
-@cindex @code{memory_barrier} instruction pattern
-@item @samp{memory_barrier}
-If the target memory model is not fully synchronous, then this pattern
-should be defined to an instruction that orders both loads and stores
-before the instruction with respect to loads and stores after the instruction.
-This pattern has no operands.
-
-@cindex @code{speculation_barrier} instruction pattern
-@item @samp{speculation_barrier}
-If the target can support speculative execution, then this pattern should
-be defined to an instruction that will block subsequent execution until
-any prior speculation conditions has been resolved. The pattern must also
-ensure that the compiler cannot move memory operations past the barrier,
-so it needs to be an UNSPEC_VOLATILE pattern. The pattern has no
-operands.
-
-If this pattern is not defined then the default expansion of
-@code{__builtin_speculation_safe_value} will emit a warning. You can
-suppress this warning by defining this pattern with a final condition
-of @code{0} (zero), which tells the compiler that a speculation
-barrier is not needed for this target.
-
-@cindex @code{sync_compare_and_swap@var{mode}} instruction pattern
-@item @samp{sync_compare_and_swap@var{mode}}
-This pattern, if defined, emits code for an atomic compare-and-swap
-operation. Operand 1 is the memory on which the atomic operation is
-performed. Operand 2 is the ``old'' value to be compared against the
-current contents of the memory location. Operand 3 is the ``new'' value
-to store in the memory if the compare succeeds. Operand 0 is the result
-of the operation; it should contain the contents of the memory
-before the operation. If the compare succeeds, this should obviously be
-a copy of operand 2.
-
-This pattern must show that both operand 0 and operand 1 are modified.
-
-This pattern must issue any memory barrier instructions such that all
-memory operations before the atomic operation occur before the atomic
-operation and all memory operations after the atomic operation occur
-after the atomic operation.
-
-For targets where the success or failure of the compare-and-swap
-operation is available via the status flags, it is possible to
-avoid a separate compare operation and issue the subsequent
-branch or store-flag operation immediately after the compare-and-swap.
-To this end, GCC will look for a @code{MODE_CC} set in the
-output of @code{sync_compare_and_swap@var{mode}}; if the machine
-description includes such a set, the target should also define special
-@code{cbranchcc4} and/or @code{cstorecc4} instructions. GCC will then
-be able to take the destination of the @code{MODE_CC} set and pass it
-to the @code{cbranchcc4} or @code{cstorecc4} pattern as the first
-operand of the comparison (the second will be @code{(const_int 0)}).
-
-For targets where the operating system may provide support for this
-operation via library calls, the @code{sync_compare_and_swap_optab}
-may be initialized to a function with the same interface as the
-@code{__sync_val_compare_and_swap_@var{n}} built-in. If the entire
-set of @var{__sync} builtins are supported via library calls, the
-target can initialize all of the optabs at once with
-@code{init_sync_libfuncs}.
-For the purposes of C++11 @code{std::atomic::is_lock_free}, it is
-assumed that these library calls do @emph{not} use any kind of
-interruptable locking.
-
-@cindex @code{sync_add@var{mode}} instruction pattern
-@cindex @code{sync_sub@var{mode}} instruction pattern
-@cindex @code{sync_ior@var{mode}} instruction pattern
-@cindex @code{sync_and@var{mode}} instruction pattern
-@cindex @code{sync_xor@var{mode}} instruction pattern
-@cindex @code{sync_nand@var{mode}} instruction pattern
-@item @samp{sync_add@var{mode}}, @samp{sync_sub@var{mode}}
-@itemx @samp{sync_ior@var{mode}}, @samp{sync_and@var{mode}}
-@itemx @samp{sync_xor@var{mode}}, @samp{sync_nand@var{mode}}
-These patterns emit code for an atomic operation on memory.
-Operand 0 is the memory on which the atomic operation is performed.
-Operand 1 is the second operand to the binary operator.
-
-This pattern must issue any memory barrier instructions such that all
-memory operations before the atomic operation occur before the atomic
-operation and all memory operations after the atomic operation occur
-after the atomic operation.
-
-If these patterns are not defined, the operation will be constructed
-from a compare-and-swap operation, if defined.
-
-@cindex @code{sync_old_add@var{mode}} instruction pattern
-@cindex @code{sync_old_sub@var{mode}} instruction pattern
-@cindex @code{sync_old_ior@var{mode}} instruction pattern
-@cindex @code{sync_old_and@var{mode}} instruction pattern
-@cindex @code{sync_old_xor@var{mode}} instruction pattern
-@cindex @code{sync_old_nand@var{mode}} instruction pattern
-@item @samp{sync_old_add@var{mode}}, @samp{sync_old_sub@var{mode}}
-@itemx @samp{sync_old_ior@var{mode}}, @samp{sync_old_and@var{mode}}
-@itemx @samp{sync_old_xor@var{mode}}, @samp{sync_old_nand@var{mode}}
-These patterns emit code for an atomic operation on memory,
-and return the value that the memory contained before the operation.
-Operand 0 is the result value, operand 1 is the memory on which the
-atomic operation is performed, and operand 2 is the second operand
-to the binary operator.
-
-This pattern must issue any memory barrier instructions such that all
-memory operations before the atomic operation occur before the atomic
-operation and all memory operations after the atomic operation occur
-after the atomic operation.
-
-If these patterns are not defined, the operation will be constructed
-from a compare-and-swap operation, if defined.
-
-@cindex @code{sync_new_add@var{mode}} instruction pattern
-@cindex @code{sync_new_sub@var{mode}} instruction pattern
-@cindex @code{sync_new_ior@var{mode}} instruction pattern
-@cindex @code{sync_new_and@var{mode}} instruction pattern
-@cindex @code{sync_new_xor@var{mode}} instruction pattern
-@cindex @code{sync_new_nand@var{mode}} instruction pattern
-@item @samp{sync_new_add@var{mode}}, @samp{sync_new_sub@var{mode}}
-@itemx @samp{sync_new_ior@var{mode}}, @samp{sync_new_and@var{mode}}
-@itemx @samp{sync_new_xor@var{mode}}, @samp{sync_new_nand@var{mode}}
-These patterns are like their @code{sync_old_@var{op}} counterparts,
-except that they return the value that exists in the memory location
-after the operation, rather than before the operation.
-
-@cindex @code{sync_lock_test_and_set@var{mode}} instruction pattern
-@item @samp{sync_lock_test_and_set@var{mode}}
-This pattern takes two forms, based on the capabilities of the target.
-In either case, operand 0 is the result of the operand, operand 1 is
-the memory on which the atomic operation is performed, and operand 2
-is the value to set in the lock.
-
-In the ideal case, this operation is an atomic exchange operation, in
-which the previous value in memory operand is copied into the result
-operand, and the value operand is stored in the memory operand.
-
-For less capable targets, any value operand that is not the constant 1
-should be rejected with @code{FAIL}. In this case the target may use
-an atomic test-and-set bit operation. The result operand should contain
-1 if the bit was previously set and 0 if the bit was previously clear.
-The true contents of the memory operand are implementation defined.
-
-This pattern must issue any memory barrier instructions such that the
-pattern as a whole acts as an acquire barrier, that is all memory
-operations after the pattern do not occur until the lock is acquired.
-
-If this pattern is not defined, the operation will be constructed from
-a compare-and-swap operation, if defined.
-
-@cindex @code{sync_lock_release@var{mode}} instruction pattern
-@item @samp{sync_lock_release@var{mode}}
-This pattern, if defined, releases a lock set by
-@code{sync_lock_test_and_set@var{mode}}. Operand 0 is the memory
-that contains the lock; operand 1 is the value to store in the lock.
-
-If the target doesn't implement full semantics for
-@code{sync_lock_test_and_set@var{mode}}, any value operand which is not
-the constant 0 should be rejected with @code{FAIL}, and the true contents
-of the memory operand are implementation defined.
-
-This pattern must issue any memory barrier instructions such that the
-pattern as a whole acts as a release barrier, that is the lock is
-released only after all previous memory operations have completed.
-
-If this pattern is not defined, then a @code{memory_barrier} pattern
-will be emitted, followed by a store of the value to the memory operand.
-
-@cindex @code{atomic_compare_and_swap@var{mode}} instruction pattern
-@item @samp{atomic_compare_and_swap@var{mode}}
-This pattern, if defined, emits code for an atomic compare-and-swap
-operation with memory model semantics. Operand 2 is the memory on which
-the atomic operation is performed. Operand 0 is an output operand which
-is set to true or false based on whether the operation succeeded. Operand
-1 is an output operand which is set to the contents of the memory before
-the operation was attempted. Operand 3 is the value that is expected to
-be in memory. Operand 4 is the value to put in memory if the expected
-value is found there. Operand 5 is set to 1 if this compare and swap is to
-be treated as a weak operation. Operand 6 is the memory model to be used
-if the operation is a success. Operand 7 is the memory model to be used
-if the operation fails.
-
-If memory referred to in operand 2 contains the value in operand 3, then
-operand 4 is stored in memory pointed to by operand 2 and fencing based on
-the memory model in operand 6 is issued.
-
-If memory referred to in operand 2 does not contain the value in operand 3,
-then fencing based on the memory model in operand 7 is issued.
-
-If a target does not support weak compare-and-swap operations, or the port
-elects not to implement weak operations, the argument in operand 5 can be
-ignored. Note a strong implementation must be provided.
-
-If this pattern is not provided, the @code{__atomic_compare_exchange}
-built-in functions will utilize the legacy @code{sync_compare_and_swap}
-pattern with an @code{__ATOMIC_SEQ_CST} memory model.
-
-@cindex @code{atomic_load@var{mode}} instruction pattern
-@item @samp{atomic_load@var{mode}}
-This pattern implements an atomic load operation with memory model
-semantics. Operand 1 is the memory address being loaded from. Operand 0
-is the result of the load. Operand 2 is the memory model to be used for
-the load operation.
-
-If not present, the @code{__atomic_load} built-in function will either
-resort to a normal load with memory barriers, or a compare-and-swap
-operation if a normal load would not be atomic.
-
-@cindex @code{atomic_store@var{mode}} instruction pattern
-@item @samp{atomic_store@var{mode}}
-This pattern implements an atomic store operation with memory model
-semantics. Operand 0 is the memory address being stored to. Operand 1
-is the value to be written. Operand 2 is the memory model to be used for
-the operation.
-
-If not present, the @code{__atomic_store} built-in function will attempt to
-perform a normal store and surround it with any required memory fences. If
-the store would not be atomic, then an @code{__atomic_exchange} is
-attempted with the result being ignored.
-
-@cindex @code{atomic_exchange@var{mode}} instruction pattern
-@item @samp{atomic_exchange@var{mode}}
-This pattern implements an atomic exchange operation with memory model
-semantics. Operand 1 is the memory location the operation is performed on.
-Operand 0 is an output operand which is set to the original value contained
-in the memory pointed to by operand 1. Operand 2 is the value to be
-stored. Operand 3 is the memory model to be used.
-
-If this pattern is not present, the built-in function
-@code{__atomic_exchange} will attempt to preform the operation with a
-compare and swap loop.
-
-@cindex @code{atomic_add@var{mode}} instruction pattern
-@cindex @code{atomic_sub@var{mode}} instruction pattern
-@cindex @code{atomic_or@var{mode}} instruction pattern
-@cindex @code{atomic_and@var{mode}} instruction pattern
-@cindex @code{atomic_xor@var{mode}} instruction pattern
-@cindex @code{atomic_nand@var{mode}} instruction pattern
-@item @samp{atomic_add@var{mode}}, @samp{atomic_sub@var{mode}}
-@itemx @samp{atomic_or@var{mode}}, @samp{atomic_and@var{mode}}
-@itemx @samp{atomic_xor@var{mode}}, @samp{atomic_nand@var{mode}}
-These patterns emit code for an atomic operation on memory with memory
-model semantics. Operand 0 is the memory on which the atomic operation is
-performed. Operand 1 is the second operand to the binary operator.
-Operand 2 is the memory model to be used by the operation.
-
-If these patterns are not defined, attempts will be made to use legacy
-@code{sync} patterns, or equivalent patterns which return a result. If
-none of these are available a compare-and-swap loop will be used.
-
-@cindex @code{atomic_fetch_add@var{mode}} instruction pattern
-@cindex @code{atomic_fetch_sub@var{mode}} instruction pattern
-@cindex @code{atomic_fetch_or@var{mode}} instruction pattern
-@cindex @code{atomic_fetch_and@var{mode}} instruction pattern
-@cindex @code{atomic_fetch_xor@var{mode}} instruction pattern
-@cindex @code{atomic_fetch_nand@var{mode}} instruction pattern
-@item @samp{atomic_fetch_add@var{mode}}, @samp{atomic_fetch_sub@var{mode}}
-@itemx @samp{atomic_fetch_or@var{mode}}, @samp{atomic_fetch_and@var{mode}}
-@itemx @samp{atomic_fetch_xor@var{mode}}, @samp{atomic_fetch_nand@var{mode}}
-These patterns emit code for an atomic operation on memory with memory
-model semantics, and return the original value. Operand 0 is an output
-operand which contains the value of the memory location before the
-operation was performed. Operand 1 is the memory on which the atomic
-operation is performed. Operand 2 is the second operand to the binary
-operator. Operand 3 is the memory model to be used by the operation.
-
-If these patterns are not defined, attempts will be made to use legacy
-@code{sync} patterns. If none of these are available a compare-and-swap
-loop will be used.
-
-@cindex @code{atomic_add_fetch@var{mode}} instruction pattern
-@cindex @code{atomic_sub_fetch@var{mode}} instruction pattern
-@cindex @code{atomic_or_fetch@var{mode}} instruction pattern
-@cindex @code{atomic_and_fetch@var{mode}} instruction pattern
-@cindex @code{atomic_xor_fetch@var{mode}} instruction pattern
-@cindex @code{atomic_nand_fetch@var{mode}} instruction pattern
-@item @samp{atomic_add_fetch@var{mode}}, @samp{atomic_sub_fetch@var{mode}}
-@itemx @samp{atomic_or_fetch@var{mode}}, @samp{atomic_and_fetch@var{mode}}
-@itemx @samp{atomic_xor_fetch@var{mode}}, @samp{atomic_nand_fetch@var{mode}}
-These patterns emit code for an atomic operation on memory with memory
-model semantics and return the result after the operation is performed.
-Operand 0 is an output operand which contains the value after the
-operation. Operand 1 is the memory on which the atomic operation is
-performed. Operand 2 is the second operand to the binary operator.
-Operand 3 is the memory model to be used by the operation.
-
-If these patterns are not defined, attempts will be made to use legacy
-@code{sync} patterns, or equivalent patterns which return the result before
-the operation followed by the arithmetic operation required to produce the
-result. If none of these are available a compare-and-swap loop will be
-used.
-
-@cindex @code{atomic_test_and_set} instruction pattern
-@item @samp{atomic_test_and_set}
-This pattern emits code for @code{__builtin_atomic_test_and_set}.
-Operand 0 is an output operand which is set to true if the previous
-previous contents of the byte was "set", and false otherwise. Operand 1
-is the @code{QImode} memory to be modified. Operand 2 is the memory
-model to be used.
-
-The specific value that defines "set" is implementation defined, and
-is normally based on what is performed by the native atomic test and set
-instruction.
-
-@cindex @code{atomic_bit_test_and_set@var{mode}} instruction pattern
-@cindex @code{atomic_bit_test_and_complement@var{mode}} instruction pattern
-@cindex @code{atomic_bit_test_and_reset@var{mode}} instruction pattern
-@item @samp{atomic_bit_test_and_set@var{mode}}
-@itemx @samp{atomic_bit_test_and_complement@var{mode}}
-@itemx @samp{atomic_bit_test_and_reset@var{mode}}
-These patterns emit code for an atomic bitwise operation on memory with memory
-model semantics, and return the original value of the specified bit.
-Operand 0 is an output operand which contains the value of the specified bit
-from the memory location before the operation was performed. Operand 1 is the
-memory on which the atomic operation is performed. Operand 2 is the bit within
-the operand, starting with least significant bit. Operand 3 is the memory model
-to be used by the operation. Operand 4 is a flag - it is @code{const1_rtx}
-if operand 0 should contain the original value of the specified bit in the
-least significant bit of the operand, and @code{const0_rtx} if the bit should
-be in its original position in the operand.
-@code{atomic_bit_test_and_set@var{mode}} atomically sets the specified bit after
-remembering its original value, @code{atomic_bit_test_and_complement@var{mode}}
-inverts the specified bit and @code{atomic_bit_test_and_reset@var{mode}} clears
-the specified bit.
-
-If these patterns are not defined, attempts will be made to use
-@code{atomic_fetch_or@var{mode}}, @code{atomic_fetch_xor@var{mode}} or
-@code{atomic_fetch_and@var{mode}} instruction patterns, or their @code{sync}
-counterparts. If none of these are available a compare-and-swap
-loop will be used.
-
-@cindex @code{atomic_add_fetch_cmp_0@var{mode}} instruction pattern
-@cindex @code{atomic_sub_fetch_cmp_0@var{mode}} instruction pattern
-@cindex @code{atomic_and_fetch_cmp_0@var{mode}} instruction pattern
-@cindex @code{atomic_or_fetch_cmp_0@var{mode}} instruction pattern
-@cindex @code{atomic_xor_fetch_cmp_0@var{mode}} instruction pattern
-@item @samp{atomic_add_fetch_cmp_0@var{mode}}
-@itemx @samp{atomic_sub_fetch_cmp_0@var{mode}}
-@itemx @samp{atomic_and_fetch_cmp_0@var{mode}}
-@itemx @samp{atomic_or_fetch_cmp_0@var{mode}}
-@itemx @samp{atomic_xor_fetch_cmp_0@var{mode}}
-These patterns emit code for an atomic operation on memory with memory
-model semantics if the fetch result is used only in a comparison against
-zero.
-Operand 0 is an output operand which contains a boolean result of comparison
-of the value after the operation against zero. Operand 1 is the memory on
-which the atomic operation is performed. Operand 2 is the second operand
-to the binary operator. Operand 3 is the memory model to be used by the
-operation. Operand 4 is an integer holding the comparison code, one of
-@code{EQ}, @code{NE}, @code{LT}, @code{GT}, @code{LE} or @code{GE}.
-
-If these patterns are not defined, attempts will be made to use separate
-atomic operation and fetch pattern followed by comparison of the result
-against zero.
-
-@cindex @code{mem_thread_fence} instruction pattern
-@item @samp{mem_thread_fence}
-This pattern emits code required to implement a thread fence with
-memory model semantics. Operand 0 is the memory model to be used.
-
-For the @code{__ATOMIC_RELAXED} model no instructions need to be issued
-and this expansion is not invoked.
-
-The compiler always emits a compiler memory barrier regardless of what
-expanding this pattern produced.
-
-If this pattern is not defined, the compiler falls back to expanding the
-@code{memory_barrier} pattern, then to emitting @code{__sync_synchronize}
-library call, and finally to just placing a compiler memory barrier.
-
-@cindex @code{get_thread_pointer@var{mode}} instruction pattern
-@cindex @code{set_thread_pointer@var{mode}} instruction pattern
-@item @samp{get_thread_pointer@var{mode}}
-@itemx @samp{set_thread_pointer@var{mode}}
-These patterns emit code that reads/sets the TLS thread pointer. Currently,
-these are only needed if the target needs to support the
-@code{__builtin_thread_pointer} and @code{__builtin_set_thread_pointer}
-builtins.
-
-The get/set patterns have a single output/input operand respectively,
-with @var{mode} intended to be @code{Pmode}.
-
-@cindex @code{stack_protect_combined_set} instruction pattern
-@item @samp{stack_protect_combined_set}
-This pattern, if defined, moves a @code{ptr_mode} value from an address
-whose declaration RTX is given in operand 1 to the memory in operand 0
-without leaving the value in a register afterward. If several
-instructions are needed by the target to perform the operation (eg. to
-load the address from a GOT entry then load the @code{ptr_mode} value
-and finally store it), it is the backend's responsibility to ensure no
-intermediate result gets spilled. This is to avoid leaking the value
-some place that an attacker might use to rewrite the stack guard slot
-after having clobbered it.
-
-If this pattern is not defined, then the address declaration is
-expanded first in the standard way and a @code{stack_protect_set}
-pattern is then generated to move the value from that address to the
-address in operand 0.
-
-@cindex @code{stack_protect_set} instruction pattern
-@item @samp{stack_protect_set}
-This pattern, if defined, moves a @code{ptr_mode} value from the valid
-memory location in operand 1 to the memory in operand 0 without leaving
-the value in a register afterward. This is to avoid leaking the value
-some place that an attacker might use to rewrite the stack guard slot
-after having clobbered it.
-
-Note: on targets where the addressing modes do not allow to load
-directly from stack guard address, the address is expanded in a standard
-way first which could cause some spills.
-
-If this pattern is not defined, then a plain move pattern is generated.
-
-@cindex @code{stack_protect_combined_test} instruction pattern
-@item @samp{stack_protect_combined_test}
-This pattern, if defined, compares a @code{ptr_mode} value from an
-address whose declaration RTX is given in operand 1 with the memory in
-operand 0 without leaving the value in a register afterward and
-branches to operand 2 if the values were equal. If several
-instructions are needed by the target to perform the operation (eg. to
-load the address from a GOT entry then load the @code{ptr_mode} value
-and finally store it), it is the backend's responsibility to ensure no
-intermediate result gets spilled. This is to avoid leaking the value
-some place that an attacker might use to rewrite the stack guard slot
-after having clobbered it.
-
-If this pattern is not defined, then the address declaration is
-expanded first in the standard way and a @code{stack_protect_test}
-pattern is then generated to compare the value from that address to the
-value at the memory in operand 0.
-
-@cindex @code{stack_protect_test} instruction pattern
-@item @samp{stack_protect_test}
-This pattern, if defined, compares a @code{ptr_mode} value from the
-valid memory location in operand 1 with the memory in operand 0 without
-leaving the value in a register afterward and branches to operand 2 if
-the values were equal.
-
-If this pattern is not defined, then a plain compare pattern and
-conditional branch pattern is used.
-
-@cindex @code{clear_cache} instruction pattern
-@item @samp{clear_cache}
-This pattern, if defined, flushes the instruction cache for a region of
-memory. The region is bounded to by the Pmode pointers in operand 0
-inclusive and operand 1 exclusive.
-
-If this pattern is not defined, a call to the library function
-@code{__clear_cache} is used.
-
-@cindex @code{spaceship@var{m}3} instruction pattern
-@item @samp{spaceship@var{m}3}
-Initialize output operand 0 with mode of integer type to -1, 0, 1 or 2
-if operand 1 with mode @var{m} compares less than operand 2, equal to
-operand 2, greater than operand 2 or is unordered with operand 2.
-@var{m} should be a scalar floating point mode.
-
-This pattern is not allowed to @code{FAIL}.
-
-@end table
-
-@end ifset
-@c Each of the following nodes are wrapped in separate
-@c "@ifset INTERNALS" to work around memory limits for the default
-@c configuration in older tetex distributions. Known to not work:
-@c tetex-1.0.7, known to work: tetex-2.0.2.
-@ifset INTERNALS
-@node Pattern Ordering
-@section When the Order of Patterns Matters
-@cindex Pattern Ordering
-@cindex Ordering of Patterns
-
-Sometimes an insn can match more than one instruction pattern. Then the
-pattern that appears first in the machine description is the one used.
-Therefore, more specific patterns (patterns that will match fewer things)
-and faster instructions (those that will produce better code when they
-do match) should usually go first in the description.
-
-In some cases the effect of ordering the patterns can be used to hide
-a pattern when it is not valid. For example, the 68000 has an
-instruction for converting a fullword to floating point and another
-for converting a byte to floating point. An instruction converting
-an integer to floating point could match either one. We put the
-pattern to convert the fullword first to make sure that one will
-be used rather than the other. (Otherwise a large integer might
-be generated as a single-byte immediate quantity, which would not work.)
-Instead of using this pattern ordering it would be possible to make the
-pattern for convert-a-byte smart enough to deal properly with any
-constant value.
-
-@end ifset
-@ifset INTERNALS
-@node Dependent Patterns
-@section Interdependence of Patterns
-@cindex Dependent Patterns
-@cindex Interdependence of Patterns
-
-In some cases machines support instructions identical except for the
-machine mode of one or more operands. For example, there may be
-``sign-extend halfword'' and ``sign-extend byte'' instructions whose
-patterns are
-
-@smallexample
-(set (match_operand:SI 0 @dots{})
- (extend:SI (match_operand:HI 1 @dots{})))
-
-(set (match_operand:SI 0 @dots{})
- (extend:SI (match_operand:QI 1 @dots{})))
-@end smallexample
-
-@noindent
-Constant integers do not specify a machine mode, so an instruction to
-extend a constant value could match either pattern. The pattern it
-actually will match is the one that appears first in the file. For correct
-results, this must be the one for the widest possible mode (@code{HImode},
-here). If the pattern matches the @code{QImode} instruction, the results
-will be incorrect if the constant value does not actually fit that mode.
-
-Such instructions to extend constants are rarely generated because they are
-optimized away, but they do occasionally happen in nonoptimized
-compilations.
-
-If a constraint in a pattern allows a constant, the reload pass may
-replace a register with a constant permitted by the constraint in some
-cases. Similarly for memory references. Because of this substitution,
-you should not provide separate patterns for increment and decrement
-instructions. Instead, they should be generated from the same pattern
-that supports register-register add insns by examining the operands and
-generating the appropriate machine instruction.
-
-@end ifset
-@ifset INTERNALS
-@node Jump Patterns
-@section Defining Jump Instruction Patterns
-@cindex jump instruction patterns
-@cindex defining jump instruction patterns
-
-GCC does not assume anything about how the machine realizes jumps.
-The machine description should define a single pattern, usually
-a @code{define_expand}, which expands to all the required insns.
-
-Usually, this would be a comparison insn to set the condition code
-and a separate branch insn testing the condition code and branching
-or not according to its value. For many machines, however,
-separating compares and branches is limiting, which is why the
-more flexible approach with one @code{define_expand} is used in GCC.
-The machine description becomes clearer for architectures that
-have compare-and-branch instructions but no condition code. It also
-works better when different sets of comparison operators are supported
-by different kinds of conditional branches (e.g.@: integer vs.@:
-floating-point), or by conditional branches with respect to conditional stores.
-
-Two separate insns are always used on most machines that use a separate
-condition code register (@pxref{Condition Code}).
-
-Even in this case having a single entry point for conditional branches
-is advantageous, because it handles equally well the case where a single
-comparison instruction records the results of both signed and unsigned
-comparison of the given operands (with the branch insns coming in distinct
-signed and unsigned flavors) as in the x86 or SPARC, and the case where
-there are distinct signed and unsigned compare instructions and only
-one set of conditional branch instructions as in the PowerPC.
-
-@end ifset
-@ifset INTERNALS
-@node Looping Patterns
-@section Defining Looping Instruction Patterns
-@cindex looping instruction patterns
-@cindex defining looping instruction patterns
-
-Some machines have special jump instructions that can be utilized to
-make loops more efficient. A common example is the 68000 @samp{dbra}
-instruction which performs a decrement of a register and a branch if the
-result was greater than zero. Other machines, in particular digital
-signal processors (DSPs), have special block repeat instructions to
-provide low-overhead loop support. For example, the TI TMS320C3x/C4x
-DSPs have a block repeat instruction that loads special registers to
-mark the top and end of a loop and to count the number of loop
-iterations. This avoids the need for fetching and executing a
-@samp{dbra}-like instruction and avoids pipeline stalls associated with
-the jump.
-
-GCC has two special named patterns to support low overhead looping.
-They are @samp{doloop_begin} and @samp{doloop_end}. These are emitted
-by the loop optimizer for certain well-behaved loops with a finite
-number of loop iterations using information collected during strength
-reduction.
-
-The @samp{doloop_end} pattern describes the actual looping instruction
-(or the implicit looping operation) and the @samp{doloop_begin} pattern
-is an optional companion pattern that can be used for initialization
-needed for some low-overhead looping instructions.
-
-Note that some machines require the actual looping instruction to be
-emitted at the top of the loop (e.g., the TMS320C3x/C4x DSPs). Emitting
-the true RTL for a looping instruction at the top of the loop can cause
-problems with flow analysis. So instead, a dummy @code{doloop} insn is
-emitted at the end of the loop. The machine dependent reorg pass checks
-for the presence of this @code{doloop} insn and then searches back to
-the top of the loop, where it inserts the true looping insn (provided
-there are no instructions in the loop which would cause problems). Any
-additional labels can be emitted at this point. In addition, if the
-desired special iteration counter register was not allocated, this
-machine dependent reorg pass could emit a traditional compare and jump
-instruction pair.
-
-For the @samp{doloop_end} pattern, the loop optimizer allocates an
-additional pseudo register as an iteration counter. This pseudo
-register cannot be used within the loop (i.e., general induction
-variables cannot be derived from it), however, in many cases the loop
-induction variable may become redundant and removed by the flow pass.
-
-The @samp{doloop_end} pattern must have a specific structure to be
-handled correctly by GCC. The example below is taken (slightly
-simplified) from the PDP-11 target:
-
-@smallexample
-@group
-(define_expand "doloop_end"
- [(parallel [(set (pc)
- (if_then_else
- (ne (match_operand:HI 0 "nonimmediate_operand" "+r,!m")
- (const_int 1))
- (label_ref (match_operand 1 "" ""))
- (pc)))
- (set (match_dup 0)
- (plus:HI (match_dup 0)
- (const_int -1)))])]
- ""
- "@{
- if (GET_MODE (operands[0]) != HImode)
- FAIL;
- @}")
-
-(define_insn "doloop_end_insn"
- [(set (pc)
- (if_then_else
- (ne (match_operand:HI 0 "nonimmediate_operand" "+r,!m")
- (const_int 1))
- (label_ref (match_operand 1 "" ""))
- (pc)))
- (set (match_dup 0)
- (plus:HI (match_dup 0)
- (const_int -1)))]
- ""
-
- @{
- if (which_alternative == 0)
- return "sob %0,%l1";
-
- /* emulate sob */
- output_asm_insn ("dec %0", operands);
- return "bne %l1";
- @})
-@end group
-@end smallexample
-
-The first part of the pattern describes the branch condition. GCC
-supports three cases for the way the target machine handles the loop
-counter:
-@itemize @bullet
-@item Loop terminates when the loop register decrements to zero. This
-is represented by a @code{ne} comparison of the register (its old value)
-with constant 1 (as in the example above).
-@item Loop terminates when the loop register decrements to @minus{}1.
-This is represented by a @code{ne} comparison of the register with
-constant zero.
-@item Loop terminates when the loop register decrements to a negative
-value. This is represented by a @code{ge} comparison of the register
-with constant zero. For this case, GCC will attach a @code{REG_NONNEG}
-note to the @code{doloop_end} insn if it can determine that the register
-will be non-negative.
-@end itemize
-
-Since the @code{doloop_end} insn is a jump insn that also has an output,
-the reload pass does not handle the output operand. Therefore, the
-constraint must allow for that operand to be in memory rather than a
-register. In the example shown above, that is handled (in the
-@code{doloop_end_insn} pattern) by using a loop instruction sequence
-that can handle memory operands when the memory alternative appears.
-
-GCC does not check the mode of the loop register operand when generating
-the @code{doloop_end} pattern. If the pattern is only valid for some
-modes but not others, the pattern should be a @code{define_expand}
-pattern that checks the operand mode in the preparation code, and issues
-@code{FAIL} if an unsupported mode is found. The example above does
-this, since the machine instruction to be used only exists for
-@code{HImode}.
-
-If the @code{doloop_end} pattern is a @code{define_expand}, there must
-also be a @code{define_insn} or @code{define_insn_and_split} matching
-the generated pattern. Otherwise, the compiler will fail during loop
-optimization.
-
-@end ifset
-@ifset INTERNALS
-@node Insn Canonicalizations
-@section Canonicalization of Instructions
-@cindex canonicalization of instructions
-@cindex insn canonicalization
-
-There are often cases where multiple RTL expressions could represent an
-operation performed by a single machine instruction. This situation is
-most commonly encountered with logical, branch, and multiply-accumulate
-instructions. In such cases, the compiler attempts to convert these
-multiple RTL expressions into a single canonical form to reduce the
-number of insn patterns required.
-
-In addition to algebraic simplifications, following canonicalizations
-are performed:
-
-@itemize @bullet
-@item
-For commutative and comparison operators, a constant is always made the
-second operand. If a machine only supports a constant as the second
-operand, only patterns that match a constant in the second operand need
-be supplied.
-
-@item
-For associative operators, a sequence of operators will always chain
-to the left; for instance, only the left operand of an integer @code{plus}
-can itself be a @code{plus}. @code{and}, @code{ior}, @code{xor},
-@code{plus}, @code{mult}, @code{smin}, @code{smax}, @code{umin}, and
-@code{umax} are associative when applied to integers, and sometimes to
-floating-point.
-
-@item
-@cindex @code{neg}, canonicalization of
-@cindex @code{not}, canonicalization of
-@cindex @code{mult}, canonicalization of
-@cindex @code{plus}, canonicalization of
-@cindex @code{minus}, canonicalization of
-For these operators, if only one operand is a @code{neg}, @code{not},
-@code{mult}, @code{plus}, or @code{minus} expression, it will be the
-first operand.
-
-@item
-In combinations of @code{neg}, @code{mult}, @code{plus}, and
-@code{minus}, the @code{neg} operations (if any) will be moved inside
-the operations as far as possible. For instance,
-@code{(neg (mult A B))} is canonicalized as @code{(mult (neg A) B)}, but
-@code{(plus (mult (neg B) C) A)} is canonicalized as
-@code{(minus A (mult B C))}.
-
-@cindex @code{compare}, canonicalization of
-@item
-For the @code{compare} operator, a constant is always the second operand
-if the first argument is a condition code register.
-
-@item
-For instructions that inherently set a condition code register, the
-@code{compare} operator is always written as the first RTL expression of
-the @code{parallel} instruction pattern. For example,
-
-@smallexample
-(define_insn ""
- [(set (reg:CCZ FLAGS_REG)
- (compare:CCZ
- (plus:SI
- (match_operand:SI 1 "register_operand" "%r")
- (match_operand:SI 2 "register_operand" "r"))
- (const_int 0)))
- (set (match_operand:SI 0 "register_operand" "=r")
- (plus:SI (match_dup 1) (match_dup 2)))]
- ""
- "addl %0, %1, %2")
-@end smallexample
-
-@item
-An operand of @code{neg}, @code{not}, @code{mult}, @code{plus}, or
-@code{minus} is made the first operand under the same conditions as
-above.
-
-@item
-@code{(ltu (plus @var{a} @var{b}) @var{b})} is converted to
-@code{(ltu (plus @var{a} @var{b}) @var{a})}. Likewise with @code{geu} instead
-of @code{ltu}.
-
-@item
-@code{(minus @var{x} (const_int @var{n}))} is converted to
-@code{(plus @var{x} (const_int @var{-n}))}.
-
-@item
-Within address computations (i.e., inside @code{mem}), a left shift is
-converted into the appropriate multiplication by a power of two.
-
-@cindex @code{ior}, canonicalization of
-@cindex @code{and}, canonicalization of
-@cindex De Morgan's law
-@item
-De Morgan's Law is used to move bitwise negation inside a bitwise
-logical-and or logical-or operation. If this results in only one
-operand being a @code{not} expression, it will be the first one.
-
-A machine that has an instruction that performs a bitwise logical-and of one
-operand with the bitwise negation of the other should specify the pattern
-for that instruction as
-
-@smallexample
-(define_insn ""
- [(set (match_operand:@var{m} 0 @dots{})
- (and:@var{m} (not:@var{m} (match_operand:@var{m} 1 @dots{}))
- (match_operand:@var{m} 2 @dots{})))]
- "@dots{}"
- "@dots{}")
-@end smallexample
-
-@noindent
-Similarly, a pattern for a ``NAND'' instruction should be written
-
-@smallexample
-(define_insn ""
- [(set (match_operand:@var{m} 0 @dots{})
- (ior:@var{m} (not:@var{m} (match_operand:@var{m} 1 @dots{}))
- (not:@var{m} (match_operand:@var{m} 2 @dots{}))))]
- "@dots{}"
- "@dots{}")
-@end smallexample
-
-In both cases, it is not necessary to include patterns for the many
-logically equivalent RTL expressions.
-
-@cindex @code{xor}, canonicalization of
-@item
-The only possible RTL expressions involving both bitwise exclusive-or
-and bitwise negation are @code{(xor:@var{m} @var{x} @var{y})}
-and @code{(not:@var{m} (xor:@var{m} @var{x} @var{y}))}.
-
-@item
-The sum of three items, one of which is a constant, will only appear in
-the form
-
-@smallexample
-(plus:@var{m} (plus:@var{m} @var{x} @var{y}) @var{constant})
-@end smallexample
-
-@cindex @code{zero_extract}, canonicalization of
-@cindex @code{sign_extract}, canonicalization of
-@item
-Equality comparisons of a group of bits (usually a single bit) with zero
-will be written using @code{zero_extract} rather than the equivalent
-@code{and} or @code{sign_extract} operations.
-
-@cindex @code{mult}, canonicalization of
-@item
-@code{(sign_extend:@var{m1} (mult:@var{m2} (sign_extend:@var{m2} @var{x})
-(sign_extend:@var{m2} @var{y})))} is converted to @code{(mult:@var{m1}
-(sign_extend:@var{m1} @var{x}) (sign_extend:@var{m1} @var{y}))}, and likewise
-for @code{zero_extend}.
-
-@item
-@code{(sign_extend:@var{m1} (mult:@var{m2} (ashiftrt:@var{m2}
-@var{x} @var{s}) (sign_extend:@var{m2} @var{y})))} is converted
-to @code{(mult:@var{m1} (sign_extend:@var{m1} (ashiftrt:@var{m2}
-@var{x} @var{s})) (sign_extend:@var{m1} @var{y}))}, and likewise for
-patterns using @code{zero_extend} and @code{lshiftrt}. If the second
-operand of @code{mult} is also a shift, then that is extended also.
-This transformation is only applied when it can be proven that the
-original operation had sufficient precision to prevent overflow.
-
-@end itemize
-
-Further canonicalization rules are defined in the function
-@code{commutative_operand_precedence} in @file{gcc/rtlanal.cc}.
-
-@end ifset
-@ifset INTERNALS
-@node Expander Definitions
-@section Defining RTL Sequences for Code Generation
-@cindex expander definitions
-@cindex code generation RTL sequences
-@cindex defining RTL sequences for code generation
-
-On some target machines, some standard pattern names for RTL generation
-cannot be handled with single insn, but a sequence of RTL insns can
-represent them. For these target machines, you can write a
-@code{define_expand} to specify how to generate the sequence of RTL@.
-
-@findex define_expand
-A @code{define_expand} is an RTL expression that looks almost like a
-@code{define_insn}; but, unlike the latter, a @code{define_expand} is used
-only for RTL generation and it can produce more than one RTL insn.
-
-A @code{define_expand} RTX has four operands:
-
-@itemize @bullet
-@item
-The name. Each @code{define_expand} must have a name, since the only
-use for it is to refer to it by name.
-
-@item
-The RTL template. This is a vector of RTL expressions representing
-a sequence of separate instructions. Unlike @code{define_insn}, there
-is no implicit surrounding @code{PARALLEL}.
-
-@item
-The condition, a string containing a C expression. This expression is
-used to express how the availability of this pattern depends on
-subclasses of target machine, selected by command-line options when GCC
-is run. This is just like the condition of a @code{define_insn} that
-has a standard name. Therefore, the condition (if present) may not
-depend on the data in the insn being matched, but only the
-target-machine-type flags. The compiler needs to test these conditions
-during initialization in order to learn exactly which named instructions
-are available in a particular run.
-
-@item
-The preparation statements, a string containing zero or more C
-statements which are to be executed before RTL code is generated from
-the RTL template.
-
-Usually these statements prepare temporary registers for use as
-internal operands in the RTL template, but they can also generate RTL
-insns directly by calling routines such as @code{emit_insn}, etc.
-Any such insns precede the ones that come from the RTL template.
-
-@item
-Optionally, a vector containing the values of attributes. @xref{Insn
-Attributes}.
-@end itemize
-
-Every RTL insn emitted by a @code{define_expand} must match some
-@code{define_insn} in the machine description. Otherwise, the compiler
-will crash when trying to generate code for the insn or trying to optimize
-it.
-
-The RTL template, in addition to controlling generation of RTL insns,
-also describes the operands that need to be specified when this pattern
-is used. In particular, it gives a predicate for each operand.
-
-A true operand, which needs to be specified in order to generate RTL from
-the pattern, should be described with a @code{match_operand} in its first
-occurrence in the RTL template. This enters information on the operand's
-predicate into the tables that record such things. GCC uses the
-information to preload the operand into a register if that is required for
-valid RTL code. If the operand is referred to more than once, subsequent
-references should use @code{match_dup}.
-
-The RTL template may also refer to internal ``operands'' which are
-temporary registers or labels used only within the sequence made by the
-@code{define_expand}. Internal operands are substituted into the RTL
-template with @code{match_dup}, never with @code{match_operand}. The
-values of the internal operands are not passed in as arguments by the
-compiler when it requests use of this pattern. Instead, they are computed
-within the pattern, in the preparation statements. These statements
-compute the values and store them into the appropriate elements of
-@code{operands} so that @code{match_dup} can find them.
-
-There are two special macros defined for use in the preparation statements:
-@code{DONE} and @code{FAIL}. Use them with a following semicolon,
-as a statement.
-
-@table @code
-
-@findex DONE
-@item DONE
-Use the @code{DONE} macro to end RTL generation for the pattern. The
-only RTL insns resulting from the pattern on this occasion will be
-those already emitted by explicit calls to @code{emit_insn} within the
-preparation statements; the RTL template will not be generated.
-
-@findex FAIL
-@item FAIL
-Make the pattern fail on this occasion. When a pattern fails, it means
-that the pattern was not truly available. The calling routines in the
-compiler will try other strategies for code generation using other patterns.
-
-Failure is currently supported only for binary (addition, multiplication,
-shifting, etc.) and bit-field (@code{extv}, @code{extzv}, and @code{insv})
-operations.
-@end table
-
-If the preparation falls through (invokes neither @code{DONE} nor
-@code{FAIL}), then the @code{define_expand} acts like a
-@code{define_insn} in that the RTL template is used to generate the
-insn.
-
-The RTL template is not used for matching, only for generating the
-initial insn list. If the preparation statement always invokes
-@code{DONE} or @code{FAIL}, the RTL template may be reduced to a simple
-list of operands, such as this example:
-
-@smallexample
-@group
-(define_expand "addsi3"
- [(match_operand:SI 0 "register_operand" "")
- (match_operand:SI 1 "register_operand" "")
- (match_operand:SI 2 "register_operand" "")]
- ""
- "
-@{
- handle_add (operands[0], operands[1], operands[2]);
- DONE;
-@}")
-@end group
-@end smallexample
-
-Here is an example, the definition of left-shift for the SPUR chip:
-
-@smallexample
-@group
-(define_expand "ashlsi3"
- [(set (match_operand:SI 0 "register_operand" "")
- (ashift:SI
- (match_operand:SI 1 "register_operand" "")
- (match_operand:SI 2 "nonmemory_operand" "")))]
- ""
- "
-@{
- if (GET_CODE (operands[2]) != CONST_INT
- || (unsigned) INTVAL (operands[2]) > 3)
- FAIL;
-@}")
-@end group
-@end smallexample
-
-@noindent
-This example uses @code{define_expand} so that it can generate an RTL insn
-for shifting when the shift-count is in the supported range of 0 to 3 but
-fail in other cases where machine insns aren't available. When it fails,
-the compiler tries another strategy using different patterns (such as, a
-library call).
-
-If the compiler were able to handle nontrivial condition-strings in
-patterns with names, then it would be possible to use a
-@code{define_insn} in that case. Here is another case (zero-extension
-on the 68000) which makes more use of the power of @code{define_expand}:
-
-@smallexample
-(define_expand "zero_extendhisi2"
- [(set (match_operand:SI 0 "general_operand" "")
- (const_int 0))
- (set (strict_low_part
- (subreg:HI
- (match_dup 0)
- 0))
- (match_operand:HI 1 "general_operand" ""))]
- ""
- "operands[1] = make_safe_from (operands[1], operands[0]);")
-@end smallexample
-
-@noindent
-@findex make_safe_from
-Here two RTL insns are generated, one to clear the entire output operand
-and the other to copy the input operand into its low half. This sequence
-is incorrect if the input operand refers to [the old value of] the output
-operand, so the preparation statement makes sure this isn't so. The
-function @code{make_safe_from} copies the @code{operands[1]} into a
-temporary register if it refers to @code{operands[0]}. It does this
-by emitting another RTL insn.
-
-Finally, a third example shows the use of an internal operand.
-Zero-extension on the SPUR chip is done by @code{and}-ing the result
-against a halfword mask. But this mask cannot be represented by a
-@code{const_int} because the constant value is too large to be legitimate
-on this machine. So it must be copied into a register with
-@code{force_reg} and then the register used in the @code{and}.
-
-@smallexample
-(define_expand "zero_extendhisi2"
- [(set (match_operand:SI 0 "register_operand" "")
- (and:SI (subreg:SI
- (match_operand:HI 1 "register_operand" "")
- 0)
- (match_dup 2)))]
- ""
- "operands[2]
- = force_reg (SImode, GEN_INT (65535)); ")
-@end smallexample
-
-@emph{Note:} If the @code{define_expand} is used to serve a
-standard binary or unary arithmetic operation or a bit-field operation,
-then the last insn it generates must not be a @code{code_label},
-@code{barrier} or @code{note}. It must be an @code{insn},
-@code{jump_insn} or @code{call_insn}. If you don't need a real insn
-at the end, emit an insn to copy the result of the operation into
-itself. Such an insn will generate no code, but it can avoid problems
-in the compiler.
-
-@end ifset
-@ifset INTERNALS
-@node Insn Splitting
-@section Defining How to Split Instructions
-@cindex insn splitting
-@cindex instruction splitting
-@cindex splitting instructions
-
-There are two cases where you should specify how to split a pattern
-into multiple insns. On machines that have instructions requiring
-delay slots (@pxref{Delay Slots}) or that have instructions whose
-output is not available for multiple cycles (@pxref{Processor pipeline
-description}), the compiler phases that optimize these cases need to
-be able to move insns into one-instruction delay slots. However, some
-insns may generate more than one machine instruction. These insns
-cannot be placed into a delay slot.
-
-Often you can rewrite the single insn as a list of individual insns,
-each corresponding to one machine instruction. The disadvantage of
-doing so is that it will cause the compilation to be slower and require
-more space. If the resulting insns are too complex, it may also
-suppress some optimizations. The compiler splits the insn if there is a
-reason to believe that it might improve instruction or delay slot
-scheduling.
-
-The insn combiner phase also splits putative insns. If three insns are
-merged into one insn with a complex expression that cannot be matched by
-some @code{define_insn} pattern, the combiner phase attempts to split
-the complex pattern into two insns that are recognized. Usually it can
-break the complex pattern into two patterns by splitting out some
-subexpression. However, in some other cases, such as performing an
-addition of a large constant in two insns on a RISC machine, the way to
-split the addition into two insns is machine-dependent.
-
-@findex define_split
-The @code{define_split} definition tells the compiler how to split a
-complex insn into several simpler insns. It looks like this:
-
-@smallexample
-(define_split
- [@var{insn-pattern}]
- "@var{condition}"
- [@var{new-insn-pattern-1}
- @var{new-insn-pattern-2}
- @dots{}]
- "@var{preparation-statements}")
-@end smallexample
-
-@var{insn-pattern} is a pattern that needs to be split and
-@var{condition} is the final condition to be tested, as in a
-@code{define_insn}. When an insn matching @var{insn-pattern} and
-satisfying @var{condition} is found, it is replaced in the insn list
-with the insns given by @var{new-insn-pattern-1},
-@var{new-insn-pattern-2}, etc.
-
-The @var{preparation-statements} are similar to those statements that
-are specified for @code{define_expand} (@pxref{Expander Definitions})
-and are executed before the new RTL is generated to prepare for the
-generated code or emit some insns whose pattern is not fixed. Unlike
-those in @code{define_expand}, however, these statements must not
-generate any new pseudo-registers. Once reload has completed, they also
-must not allocate any space in the stack frame.
-
-There are two special macros defined for use in the preparation statements:
-@code{DONE} and @code{FAIL}. Use them with a following semicolon,
-as a statement.
-
-@table @code
-
-@findex DONE
-@item DONE
-Use the @code{DONE} macro to end RTL generation for the splitter. The
-only RTL insns generated as replacement for the matched input insn will
-be those already emitted by explicit calls to @code{emit_insn} within
-the preparation statements; the replacement pattern is not used.
-
-@findex FAIL
-@item FAIL
-Make the @code{define_split} fail on this occasion. When a @code{define_split}
-fails, it means that the splitter was not truly available for the inputs
-it was given, and the input insn will not be split.
-@end table
-
-If the preparation falls through (invokes neither @code{DONE} nor
-@code{FAIL}), then the @code{define_split} uses the replacement
-template.
-
-Patterns are matched against @var{insn-pattern} in two different
-circumstances. If an insn needs to be split for delay slot scheduling
-or insn scheduling, the insn is already known to be valid, which means
-that it must have been matched by some @code{define_insn} and, if
-@code{reload_completed} is nonzero, is known to satisfy the constraints
-of that @code{define_insn}. In that case, the new insn patterns must
-also be insns that are matched by some @code{define_insn} and, if
-@code{reload_completed} is nonzero, must also satisfy the constraints
-of those definitions.
-
-As an example of this usage of @code{define_split}, consider the following
-example from @file{a29k.md}, which splits a @code{sign_extend} from
-@code{HImode} to @code{SImode} into a pair of shift insns:
-
-@smallexample
-(define_split
- [(set (match_operand:SI 0 "gen_reg_operand" "")
- (sign_extend:SI (match_operand:HI 1 "gen_reg_operand" "")))]
- ""
- [(set (match_dup 0)
- (ashift:SI (match_dup 1)
- (const_int 16)))
- (set (match_dup 0)
- (ashiftrt:SI (match_dup 0)
- (const_int 16)))]
- "
-@{ operands[1] = gen_lowpart (SImode, operands[1]); @}")
-@end smallexample
-
-When the combiner phase tries to split an insn pattern, it is always the
-case that the pattern is @emph{not} matched by any @code{define_insn}.
-The combiner pass first tries to split a single @code{set} expression
-and then the same @code{set} expression inside a @code{parallel}, but
-followed by a @code{clobber} of a pseudo-reg to use as a scratch
-register. In these cases, the combiner expects exactly one or two new insn
-patterns to be generated. It will verify that these patterns match some
-@code{define_insn} definitions, so you need not do this test in the
-@code{define_split} (of course, there is no point in writing a
-@code{define_split} that will never produce insns that match).
-
-Here is an example of this use of @code{define_split}, taken from
-@file{rs6000.md}:
-
-@smallexample
-(define_split
- [(set (match_operand:SI 0 "gen_reg_operand" "")
- (plus:SI (match_operand:SI 1 "gen_reg_operand" "")
- (match_operand:SI 2 "non_add_cint_operand" "")))]
- ""
- [(set (match_dup 0) (plus:SI (match_dup 1) (match_dup 3)))
- (set (match_dup 0) (plus:SI (match_dup 0) (match_dup 4)))]
-"
-@{
- int low = INTVAL (operands[2]) & 0xffff;
- int high = (unsigned) INTVAL (operands[2]) >> 16;
-
- if (low & 0x8000)
- high++, low |= 0xffff0000;
-
- operands[3] = GEN_INT (high << 16);
- operands[4] = GEN_INT (low);
-@}")
-@end smallexample
-
-Here the predicate @code{non_add_cint_operand} matches any
-@code{const_int} that is @emph{not} a valid operand of a single add
-insn. The add with the smaller displacement is written so that it
-can be substituted into the address of a subsequent operation.
-
-An example that uses a scratch register, from the same file, generates
-an equality comparison of a register and a large constant:
-
-@smallexample
-(define_split
- [(set (match_operand:CC 0 "cc_reg_operand" "")
- (compare:CC (match_operand:SI 1 "gen_reg_operand" "")
- (match_operand:SI 2 "non_short_cint_operand" "")))
- (clobber (match_operand:SI 3 "gen_reg_operand" ""))]
- "find_single_use (operands[0], insn, 0)
- && (GET_CODE (*find_single_use (operands[0], insn, 0)) == EQ
- || GET_CODE (*find_single_use (operands[0], insn, 0)) == NE)"
- [(set (match_dup 3) (xor:SI (match_dup 1) (match_dup 4)))
- (set (match_dup 0) (compare:CC (match_dup 3) (match_dup 5)))]
- "
-@{
- /* @r{Get the constant we are comparing against, C, and see what it
- looks like sign-extended to 16 bits. Then see what constant
- could be XOR'ed with C to get the sign-extended value.} */
-
- int c = INTVAL (operands[2]);
- int sextc = (c << 16) >> 16;
- int xorv = c ^ sextc;
-
- operands[4] = GEN_INT (xorv);
- operands[5] = GEN_INT (sextc);
-@}")
-@end smallexample
-
-To avoid confusion, don't write a single @code{define_split} that
-accepts some insns that match some @code{define_insn} as well as some
-insns that don't. Instead, write two separate @code{define_split}
-definitions, one for the insns that are valid and one for the insns that
-are not valid.
-
-The splitter is allowed to split jump instructions into sequence of
-jumps or create new jumps in while splitting non-jump instructions. As
-the control flow graph and branch prediction information needs to be updated,
-several restriction apply.
-
-Splitting of jump instruction into sequence that over by another jump
-instruction is always valid, as compiler expect identical behavior of new
-jump. When new sequence contains multiple jump instructions or new labels,
-more assistance is needed. Splitter is required to create only unconditional
-jumps, or simple conditional jump instructions. Additionally it must attach a
-@code{REG_BR_PROB} note to each conditional jump. A global variable
-@code{split_branch_probability} holds the probability of the original branch in case
-it was a simple conditional jump, @minus{}1 otherwise. To simplify
-recomputing of edge frequencies, the new sequence is required to have only
-forward jumps to the newly created labels.
-
-@findex define_insn_and_split
-For the common case where the pattern of a define_split exactly matches the
-pattern of a define_insn, use @code{define_insn_and_split}. It looks like
-this:
-
-@smallexample
-(define_insn_and_split
- [@var{insn-pattern}]
- "@var{condition}"
- "@var{output-template}"
- "@var{split-condition}"
- [@var{new-insn-pattern-1}
- @var{new-insn-pattern-2}
- @dots{}]
- "@var{preparation-statements}"
- [@var{insn-attributes}])
-
-@end smallexample
-
-@var{insn-pattern}, @var{condition}, @var{output-template}, and
-@var{insn-attributes} are used as in @code{define_insn}. The
-@var{new-insn-pattern} vector and the @var{preparation-statements} are used as
-in a @code{define_split}. The @var{split-condition} is also used as in
-@code{define_split}, with the additional behavior that if the condition starts
-with @samp{&&}, the condition used for the split will be the constructed as a
-logical ``and'' of the split condition with the insn condition. For example,
-from i386.md:
-
-@smallexample
-(define_insn_and_split "zero_extendhisi2_and"
- [(set (match_operand:SI 0 "register_operand" "=r")
- (zero_extend:SI (match_operand:HI 1 "register_operand" "0")))
- (clobber (reg:CC 17))]
- "TARGET_ZERO_EXTEND_WITH_AND && !optimize_size"
- "#"
- "&& reload_completed"
- [(parallel [(set (match_dup 0)
- (and:SI (match_dup 0) (const_int 65535)))
- (clobber (reg:CC 17))])]
- ""
- [(set_attr "type" "alu1")])
-
-@end smallexample
-
-In this case, the actual split condition will be
-@samp{TARGET_ZERO_EXTEND_WITH_AND && !optimize_size && reload_completed}.
-
-The @code{define_insn_and_split} construction provides exactly the same
-functionality as two separate @code{define_insn} and @code{define_split}
-patterns. It exists for compactness, and as a maintenance tool to prevent
-having to ensure the two patterns' templates match.
-
-@findex define_insn_and_rewrite
-It is sometimes useful to have a @code{define_insn_and_split}
-that replaces specific operands of an instruction but leaves the
-rest of the instruction pattern unchanged. You can do this directly
-with a @code{define_insn_and_split}, but it requires a
-@var{new-insn-pattern-1} that repeats most of the original @var{insn-pattern}.
-There is also the complication that an implicit @code{parallel} in
-@var{insn-pattern} must become an explicit @code{parallel} in
-@var{new-insn-pattern-1}, which is easy to overlook.
-A simpler alternative is to use @code{define_insn_and_rewrite}, which
-is a form of @code{define_insn_and_split} that automatically generates
-@var{new-insn-pattern-1} by replacing each @code{match_operand}
-in @var{insn-pattern} with a corresponding @code{match_dup}, and each
-@code{match_operator} in the pattern with a corresponding @code{match_op_dup}.
-The arguments are otherwise identical to @code{define_insn_and_split}:
-
-@smallexample
-(define_insn_and_rewrite
- [@var{insn-pattern}]
- "@var{condition}"
- "@var{output-template}"
- "@var{split-condition}"
- "@var{preparation-statements}"
- [@var{insn-attributes}])
-@end smallexample
-
-The @code{match_dup}s and @code{match_op_dup}s in the new
-instruction pattern use any new operand values that the
-@var{preparation-statements} store in the @code{operands} array,
-as for a normal @code{define_insn_and_split}. @var{preparation-statements}
-can also emit additional instructions before the new instruction.
-They can even emit an entirely different sequence of instructions and
-use @code{DONE} to avoid emitting a new form of the original
-instruction.
-
-The split in a @code{define_insn_and_rewrite} is only intended
-to apply to existing instructions that match @var{insn-pattern}.
-@var{split-condition} must therefore start with @code{&&},
-so that the split condition applies on top of @var{condition}.
-
-Here is an example from the AArch64 SVE port, in which operand 1 is
-known to be equivalent to an all-true constant and isn't used by the
-output template:
-
-@smallexample
-(define_insn_and_rewrite "*while_ult<GPI:mode><PRED_ALL:mode>_cc"
- [(set (reg:CC CC_REGNUM)
- (compare:CC
- (unspec:SI [(match_operand:PRED_ALL 1)
- (unspec:PRED_ALL
- [(match_operand:GPI 2 "aarch64_reg_or_zero" "rZ")
- (match_operand:GPI 3 "aarch64_reg_or_zero" "rZ")]
- UNSPEC_WHILE_LO)]
- UNSPEC_PTEST_PTRUE)
- (const_int 0)))
- (set (match_operand:PRED_ALL 0 "register_operand" "=Upa")
- (unspec:PRED_ALL [(match_dup 2)
- (match_dup 3)]
- UNSPEC_WHILE_LO))]
- "TARGET_SVE"
- "whilelo\t%0.<PRED_ALL:Vetype>, %<w>2, %<w>3"
- ;; Force the compiler to drop the unused predicate operand, so that we
- ;; don't have an unnecessary PTRUE.
- "&& !CONSTANT_P (operands[1])"
- @{
- operands[1] = CONSTM1_RTX (<MODE>mode);
- @}
-)
-@end smallexample
-
-The splitter in this case simply replaces operand 1 with the constant
-value that it is known to have. The equivalent @code{define_insn_and_split}
-would be:
-
-@smallexample
-(define_insn_and_split "*while_ult<GPI:mode><PRED_ALL:mode>_cc"
- [(set (reg:CC CC_REGNUM)
- (compare:CC
- (unspec:SI [(match_operand:PRED_ALL 1)
- (unspec:PRED_ALL
- [(match_operand:GPI 2 "aarch64_reg_or_zero" "rZ")
- (match_operand:GPI 3 "aarch64_reg_or_zero" "rZ")]
- UNSPEC_WHILE_LO)]
- UNSPEC_PTEST_PTRUE)
- (const_int 0)))
- (set (match_operand:PRED_ALL 0 "register_operand" "=Upa")
- (unspec:PRED_ALL [(match_dup 2)
- (match_dup 3)]
- UNSPEC_WHILE_LO))]
- "TARGET_SVE"
- "whilelo\t%0.<PRED_ALL:Vetype>, %<w>2, %<w>3"
- ;; Force the compiler to drop the unused predicate operand, so that we
- ;; don't have an unnecessary PTRUE.
- "&& !CONSTANT_P (operands[1])"
- [(parallel
- [(set (reg:CC CC_REGNUM)
- (compare:CC
- (unspec:SI [(match_dup 1)
- (unspec:PRED_ALL [(match_dup 2)
- (match_dup 3)]
- UNSPEC_WHILE_LO)]
- UNSPEC_PTEST_PTRUE)
- (const_int 0)))
- (set (match_dup 0)
- (unspec:PRED_ALL [(match_dup 2)
- (match_dup 3)]
- UNSPEC_WHILE_LO))])]
- @{
- operands[1] = CONSTM1_RTX (<MODE>mode);
- @}
-)
-@end smallexample
-
-@end ifset
-@ifset INTERNALS
-@node Including Patterns
-@section Including Patterns in Machine Descriptions.
-@cindex insn includes
-
-@findex include
-The @code{include} pattern tells the compiler tools where to
-look for patterns that are in files other than in the file
-@file{.md}. This is used only at build time and there is no preprocessing allowed.
-
-It looks like:
-
-@smallexample
-
-(include
- @var{pathname})
-@end smallexample
-
-For example:
-
-@smallexample
-
-(include "filestuff")
-
-@end smallexample
-
-Where @var{pathname} is a string that specifies the location of the file,
-specifies the include file to be in @file{gcc/config/target/filestuff}. The
-directory @file{gcc/config/target} is regarded as the default directory.
-
-
-Machine descriptions may be split up into smaller more manageable subsections
-and placed into subdirectories.
-
-By specifying:
-
-@smallexample
-
-(include "BOGUS/filestuff")
-
-@end smallexample
-
-the include file is specified to be in @file{gcc/config/@var{target}/BOGUS/filestuff}.
-
-Specifying an absolute path for the include file such as;
-@smallexample
-
-(include "/u2/BOGUS/filestuff")
-
-@end smallexample
-is permitted but is not encouraged.
-
-@subsection RTL Generation Tool Options for Directory Search
-@cindex directory options .md
-@cindex options, directory search
-@cindex search options
-
-The @option{-I@var{dir}} option specifies directories to search for machine descriptions.
-For example:
-
-@smallexample
-
-genrecog -I/p1/abc/proc1 -I/p2/abcd/pro2 target.md
-
-@end smallexample
-
-
-Add the directory @var{dir} to the head of the list of directories to be
-searched for header files. This can be used to override a system machine definition
-file, substituting your own version, since these directories are
-searched before the default machine description file directories. If you use more than
-one @option{-I} option, the directories are scanned in left-to-right
-order; the standard default directory come after.
-
-
-@end ifset
-@ifset INTERNALS
-@node Peephole Definitions
-@section Machine-Specific Peephole Optimizers
-@cindex peephole optimizer definitions
-@cindex defining peephole optimizers
-
-In addition to instruction patterns the @file{md} file may contain
-definitions of machine-specific peephole optimizations.
-
-The combiner does not notice certain peephole optimizations when the data
-flow in the program does not suggest that it should try them. For example,
-sometimes two consecutive insns related in purpose can be combined even
-though the second one does not appear to use a register computed in the
-first one. A machine-specific peephole optimizer can detect such
-opportunities.
-
-There are two forms of peephole definitions that may be used. The
-original @code{define_peephole} is run at assembly output time to
-match insns and substitute assembly text. Use of @code{define_peephole}
-is deprecated.
-
-A newer @code{define_peephole2} matches insns and substitutes new
-insns. The @code{peephole2} pass is run after register allocation
-but before scheduling, which may result in much better code for
-targets that do scheduling.
-
-@menu
-* define_peephole:: RTL to Text Peephole Optimizers
-* define_peephole2:: RTL to RTL Peephole Optimizers
-@end menu
-
-@end ifset
-@ifset INTERNALS
-@node define_peephole
-@subsection RTL to Text Peephole Optimizers
-@findex define_peephole
-
-@need 1000
-A definition looks like this:
-
-@smallexample
-(define_peephole
- [@var{insn-pattern-1}
- @var{insn-pattern-2}
- @dots{}]
- "@var{condition}"
- "@var{template}"
- "@var{optional-insn-attributes}")
-@end smallexample
-
-@noindent
-The last string operand may be omitted if you are not using any
-machine-specific information in this machine description. If present,
-it must obey the same rules as in a @code{define_insn}.
-
-In this skeleton, @var{insn-pattern-1} and so on are patterns to match
-consecutive insns. The optimization applies to a sequence of insns when
-@var{insn-pattern-1} matches the first one, @var{insn-pattern-2} matches
-the next, and so on.
-
-Each of the insns matched by a peephole must also match a
-@code{define_insn}. Peepholes are checked only at the last stage just
-before code generation, and only optionally. Therefore, any insn which
-would match a peephole but no @code{define_insn} will cause a crash in code
-generation in an unoptimized compilation, or at various optimization
-stages.
-
-The operands of the insns are matched with @code{match_operands},
-@code{match_operator}, and @code{match_dup}, as usual. What is not
-usual is that the operand numbers apply to all the insn patterns in the
-definition. So, you can check for identical operands in two insns by
-using @code{match_operand} in one insn and @code{match_dup} in the
-other.
-
-The operand constraints used in @code{match_operand} patterns do not have
-any direct effect on the applicability of the peephole, but they will
-be validated afterward, so make sure your constraints are general enough
-to apply whenever the peephole matches. If the peephole matches
-but the constraints are not satisfied, the compiler will crash.
-
-It is safe to omit constraints in all the operands of the peephole; or
-you can write constraints which serve as a double-check on the criteria
-previously tested.
-
-Once a sequence of insns matches the patterns, the @var{condition} is
-checked. This is a C expression which makes the final decision whether to
-perform the optimization (we do so if the expression is nonzero). If
-@var{condition} is omitted (in other words, the string is empty) then the
-optimization is applied to every sequence of insns that matches the
-patterns.
-
-The defined peephole optimizations are applied after register allocation
-is complete. Therefore, the peephole definition can check which
-operands have ended up in which kinds of registers, just by looking at
-the operands.
-
-@findex prev_active_insn
-The way to refer to the operands in @var{condition} is to write
-@code{operands[@var{i}]} for operand number @var{i} (as matched by
-@code{(match_operand @var{i} @dots{})}). Use the variable @code{insn}
-to refer to the last of the insns being matched; use
-@code{prev_active_insn} to find the preceding insns.
-
-@findex dead_or_set_p
-When optimizing computations with intermediate results, you can use
-@var{condition} to match only when the intermediate results are not used
-elsewhere. Use the C expression @code{dead_or_set_p (@var{insn},
-@var{op})}, where @var{insn} is the insn in which you expect the value
-to be used for the last time (from the value of @code{insn}, together
-with use of @code{prev_nonnote_insn}), and @var{op} is the intermediate
-value (from @code{operands[@var{i}]}).
-
-Applying the optimization means replacing the sequence of insns with one
-new insn. The @var{template} controls ultimate output of assembler code
-for this combined insn. It works exactly like the template of a
-@code{define_insn}. Operand numbers in this template are the same ones
-used in matching the original sequence of insns.
-
-The result of a defined peephole optimizer does not need to match any of
-the insn patterns in the machine description; it does not even have an
-opportunity to match them. The peephole optimizer definition itself serves
-as the insn pattern to control how the insn is output.
-
-Defined peephole optimizers are run as assembler code is being output,
-so the insns they produce are never combined or rearranged in any way.
-
-Here is an example, taken from the 68000 machine description:
-
-@smallexample
-(define_peephole
- [(set (reg:SI 15) (plus:SI (reg:SI 15) (const_int 4)))
- (set (match_operand:DF 0 "register_operand" "=f")
- (match_operand:DF 1 "register_operand" "ad"))]
- "FP_REG_P (operands[0]) && ! FP_REG_P (operands[1])"
-@{
- rtx xoperands[2];
- xoperands[1] = gen_rtx_REG (SImode, REGNO (operands[1]) + 1);
-#ifdef MOTOROLA
- output_asm_insn ("move.l %1,(sp)", xoperands);
- output_asm_insn ("move.l %1,-(sp)", operands);
- return "fmove.d (sp)+,%0";
-#else
- output_asm_insn ("movel %1,sp@@", xoperands);
- output_asm_insn ("movel %1,sp@@-", operands);
- return "fmoved sp@@+,%0";
-#endif
-@})
-@end smallexample
-
-@need 1000
-The effect of this optimization is to change
-
-@smallexample
-@group
-jbsr _foobar
-addql #4,sp
-movel d1,sp@@-
-movel d0,sp@@-
-fmoved sp@@+,fp0
-@end group
-@end smallexample
-
-@noindent
-into
-
-@smallexample
-@group
-jbsr _foobar
-movel d1,sp@@
-movel d0,sp@@-
-fmoved sp@@+,fp0
-@end group
-@end smallexample
-
-@ignore
-@findex CC_REVERSED
-If a peephole matches a sequence including one or more jump insns, you must
-take account of the flags such as @code{CC_REVERSED} which specify that the
-condition codes are represented in an unusual manner. The compiler
-automatically alters any ordinary conditional jumps which occur in such
-situations, but the compiler cannot alter jumps which have been replaced by
-peephole optimizations. So it is up to you to alter the assembler code
-that the peephole produces. Supply C code to write the assembler output,
-and in this C code check the condition code status flags and change the
-assembler code as appropriate.
-@end ignore
-
-@var{insn-pattern-1} and so on look @emph{almost} like the second
-operand of @code{define_insn}. There is one important difference: the
-second operand of @code{define_insn} consists of one or more RTX's
-enclosed in square brackets. Usually, there is only one: then the same
-action can be written as an element of a @code{define_peephole}. But
-when there are multiple actions in a @code{define_insn}, they are
-implicitly enclosed in a @code{parallel}. Then you must explicitly
-write the @code{parallel}, and the square brackets within it, in the
-@code{define_peephole}. Thus, if an insn pattern looks like this,
-
-@smallexample
-(define_insn "divmodsi4"
- [(set (match_operand:SI 0 "general_operand" "=d")
- (div:SI (match_operand:SI 1 "general_operand" "0")
- (match_operand:SI 2 "general_operand" "dmsK")))
- (set (match_operand:SI 3 "general_operand" "=d")
- (mod:SI (match_dup 1) (match_dup 2)))]
- "TARGET_68020"
- "divsl%.l %2,%3:%0")
-@end smallexample
-
-@noindent
-then the way to mention this insn in a peephole is as follows:
-
-@smallexample
-(define_peephole
- [@dots{}
- (parallel
- [(set (match_operand:SI 0 "general_operand" "=d")
- (div:SI (match_operand:SI 1 "general_operand" "0")
- (match_operand:SI 2 "general_operand" "dmsK")))
- (set (match_operand:SI 3 "general_operand" "=d")
- (mod:SI (match_dup 1) (match_dup 2)))])
- @dots{}]
- @dots{})
-@end smallexample
-
-@end ifset
-@ifset INTERNALS
-@node define_peephole2
-@subsection RTL to RTL Peephole Optimizers
-@findex define_peephole2
-
-The @code{define_peephole2} definition tells the compiler how to
-substitute one sequence of instructions for another sequence,
-what additional scratch registers may be needed and what their
-lifetimes must be.
-
-@smallexample
-(define_peephole2
- [@var{insn-pattern-1}
- @var{insn-pattern-2}
- @dots{}]
- "@var{condition}"
- [@var{new-insn-pattern-1}
- @var{new-insn-pattern-2}
- @dots{}]
- "@var{preparation-statements}")
-@end smallexample
-
-The definition is almost identical to @code{define_split}
-(@pxref{Insn Splitting}) except that the pattern to match is not a
-single instruction, but a sequence of instructions.
-
-It is possible to request additional scratch registers for use in the
-output template. If appropriate registers are not free, the pattern
-will simply not match.
-
-@findex match_scratch
-@findex match_dup
-Scratch registers are requested with a @code{match_scratch} pattern at
-the top level of the input pattern. The allocated register (initially) will
-be dead at the point requested within the original sequence. If the scratch
-is used at more than a single point, a @code{match_dup} pattern at the
-top level of the input pattern marks the last position in the input sequence
-at which the register must be available.
-
-Here is an example from the IA-32 machine description:
-
-@smallexample
-(define_peephole2
- [(match_scratch:SI 2 "r")
- (parallel [(set (match_operand:SI 0 "register_operand" "")
- (match_operator:SI 3 "arith_or_logical_operator"
- [(match_dup 0)
- (match_operand:SI 1 "memory_operand" "")]))
- (clobber (reg:CC 17))])]
- "! optimize_size && ! TARGET_READ_MODIFY"
- [(set (match_dup 2) (match_dup 1))
- (parallel [(set (match_dup 0)
- (match_op_dup 3 [(match_dup 0) (match_dup 2)]))
- (clobber (reg:CC 17))])]
- "")
-@end smallexample
-
-@noindent
-This pattern tries to split a load from its use in the hopes that we'll be
-able to schedule around the memory load latency. It allocates a single
-@code{SImode} register of class @code{GENERAL_REGS} (@code{"r"}) that needs
-to be live only at the point just before the arithmetic.
-
-A real example requiring extended scratch lifetimes is harder to come by,
-so here's a silly made-up example:
-
-@smallexample
-(define_peephole2
- [(match_scratch:SI 4 "r")
- (set (match_operand:SI 0 "" "") (match_operand:SI 1 "" ""))
- (set (match_operand:SI 2 "" "") (match_dup 1))
- (match_dup 4)
- (set (match_operand:SI 3 "" "") (match_dup 1))]
- "/* @r{determine 1 does not overlap 0 and 2} */"
- [(set (match_dup 4) (match_dup 1))
- (set (match_dup 0) (match_dup 4))
- (set (match_dup 2) (match_dup 4))
- (set (match_dup 3) (match_dup 4))]
- "")
-@end smallexample
-
-There are two special macros defined for use in the preparation statements:
-@code{DONE} and @code{FAIL}. Use them with a following semicolon,
-as a statement.
-
-@table @code
-
-@findex DONE
-@item DONE
-Use the @code{DONE} macro to end RTL generation for the peephole. The
-only RTL insns generated as replacement for the matched input insn will
-be those already emitted by explicit calls to @code{emit_insn} within
-the preparation statements; the replacement pattern is not used.
-
-@findex FAIL
-@item FAIL
-Make the @code{define_peephole2} fail on this occasion. When a @code{define_peephole2}
-fails, it means that the replacement was not truly available for the
-particular inputs it was given. In that case, GCC may still apply a
-later @code{define_peephole2} that also matches the given insn pattern.
-(Note that this is different from @code{define_split}, where @code{FAIL}
-prevents the input insn from being split at all.)
-@end table
-
-If the preparation falls through (invokes neither @code{DONE} nor
-@code{FAIL}), then the @code{define_peephole2} uses the replacement
-template.
-
-@noindent
-If we had not added the @code{(match_dup 4)} in the middle of the input
-sequence, it might have been the case that the register we chose at the
-beginning of the sequence is killed by the first or second @code{set}.
-
-@end ifset
-@ifset INTERNALS
-@node Insn Attributes
-@section Instruction Attributes
-@cindex insn attributes
-@cindex instruction attributes
-
-In addition to describing the instruction supported by the target machine,
-the @file{md} file also defines a group of @dfn{attributes} and a set of
-values for each. Every generated insn is assigned a value for each attribute.
-One possible attribute would be the effect that the insn has on the machine's
-condition code.
-
-@menu
-* Defining Attributes:: Specifying attributes and their values.
-* Expressions:: Valid expressions for attribute values.
-* Tagging Insns:: Assigning attribute values to insns.
-* Attr Example:: An example of assigning attributes.
-* Insn Lengths:: Computing the length of insns.
-* Constant Attributes:: Defining attributes that are constant.
-* Mnemonic Attribute:: Obtain the instruction mnemonic as attribute value.
-* Delay Slots:: Defining delay slots required for a machine.
-* Processor pipeline description:: Specifying information for insn scheduling.
-@end menu
-
-@end ifset
-@ifset INTERNALS
-@node Defining Attributes
-@subsection Defining Attributes and their Values
-@cindex defining attributes and their values
-@cindex attributes, defining
-
-@findex define_attr
-The @code{define_attr} expression is used to define each attribute required
-by the target machine. It looks like:
-
-@smallexample
-(define_attr @var{name} @var{list-of-values} @var{default})
-@end smallexample
-
-@var{name} is a string specifying the name of the attribute being
-defined. Some attributes are used in a special way by the rest of the
-compiler. The @code{enabled} attribute can be used to conditionally
-enable or disable insn alternatives (@pxref{Disable Insn
-Alternatives}). The @code{predicable} attribute, together with a
-suitable @code{define_cond_exec} (@pxref{Conditional Execution}), can
-be used to automatically generate conditional variants of instruction
-patterns. The @code{mnemonic} attribute can be used to check for the
-instruction mnemonic (@pxref{Mnemonic Attribute}). The compiler
-internally uses the names @code{ce_enabled} and @code{nonce_enabled},
-so they should not be used elsewhere as alternative names.
-
-@var{list-of-values} is either a string that specifies a comma-separated
-list of values that can be assigned to the attribute, or a null string to
-indicate that the attribute takes numeric values.
-
-@var{default} is an attribute expression that gives the value of this
-attribute for insns that match patterns whose definition does not include
-an explicit value for this attribute. @xref{Attr Example}, for more
-information on the handling of defaults. @xref{Constant Attributes},
-for information on attributes that do not depend on any particular insn.
-
-@findex insn-attr.h
-For each defined attribute, a number of definitions are written to the
-@file{insn-attr.h} file. For cases where an explicit set of values is
-specified for an attribute, the following are defined:
-
-@itemize @bullet
-@item
-A @samp{#define} is written for the symbol @samp{HAVE_ATTR_@var{name}}.
-
-@item
-An enumerated class is defined for @samp{attr_@var{name}} with
-elements of the form @samp{@var{upper-name}_@var{upper-value}} where
-the attribute name and value are first converted to uppercase.
-
-@item
-A function @samp{get_attr_@var{name}} is defined that is passed an insn and
-returns the attribute value for that insn.
-@end itemize
-
-For example, if the following is present in the @file{md} file:
-
-@smallexample
-(define_attr "type" "branch,fp,load,store,arith" @dots{})
-@end smallexample
-
-@noindent
-the following lines will be written to the file @file{insn-attr.h}.
-
-@smallexample
-#define HAVE_ATTR_type 1
-enum attr_type @{TYPE_BRANCH, TYPE_FP, TYPE_LOAD,
- TYPE_STORE, TYPE_ARITH@};
-extern enum attr_type get_attr_type ();
-@end smallexample
-
-If the attribute takes numeric values, no @code{enum} type will be
-defined and the function to obtain the attribute's value will return
-@code{int}.
-
-There are attributes which are tied to a specific meaning. These
-attributes are not free to use for other purposes:
-
-@table @code
-@item length
-The @code{length} attribute is used to calculate the length of emitted
-code chunks. This is especially important when verifying branch
-distances. @xref{Insn Lengths}.
-
-@item enabled
-The @code{enabled} attribute can be defined to prevent certain
-alternatives of an insn definition from being used during code
-generation. @xref{Disable Insn Alternatives}.
-
-@item mnemonic
-The @code{mnemonic} attribute can be defined to implement instruction
-specific checks in e.g.@: the pipeline description.
-@xref{Mnemonic Attribute}.
-@end table
-
-For each of these special attributes, the corresponding
-@samp{HAVE_ATTR_@var{name}} @samp{#define} is also written when the
-attribute is not defined; in that case, it is defined as @samp{0}.
-
-@findex define_enum_attr
-@anchor{define_enum_attr}
-Another way of defining an attribute is to use:
-
-@smallexample
-(define_enum_attr "@var{attr}" "@var{enum}" @var{default})
-@end smallexample
-
-This works in just the same way as @code{define_attr}, except that
-the list of values is taken from a separate enumeration called
-@var{enum} (@pxref{define_enum}). This form allows you to use
-the same list of values for several attributes without having to
-repeat the list each time. For example:
-
-@smallexample
-(define_enum "processor" [
- model_a
- model_b
- @dots{}
-])
-(define_enum_attr "arch" "processor"
- (const (symbol_ref "target_arch")))
-(define_enum_attr "tune" "processor"
- (const (symbol_ref "target_tune")))
-@end smallexample
-
-defines the same attributes as:
-
-@smallexample
-(define_attr "arch" "model_a,model_b,@dots{}"
- (const (symbol_ref "target_arch")))
-(define_attr "tune" "model_a,model_b,@dots{}"
- (const (symbol_ref "target_tune")))
-@end smallexample
-
-but without duplicating the processor list. The second example defines two
-separate C enums (@code{attr_arch} and @code{attr_tune}) whereas the first
-defines a single C enum (@code{processor}).
-@end ifset
-@ifset INTERNALS
-@node Expressions
-@subsection Attribute Expressions
-@cindex attribute expressions
-
-RTL expressions used to define attributes use the codes described above
-plus a few specific to attribute definitions, to be discussed below.
-Attribute value expressions must have one of the following forms:
-
-@table @code
-@cindex @code{const_int} and attributes
-@item (const_int @var{i})
-The integer @var{i} specifies the value of a numeric attribute. @var{i}
-must be non-negative.
-
-The value of a numeric attribute can be specified either with a
-@code{const_int}, or as an integer represented as a string in
-@code{const_string}, @code{eq_attr} (see below), @code{attr},
-@code{symbol_ref}, simple arithmetic expressions, and @code{set_attr}
-overrides on specific instructions (@pxref{Tagging Insns}).
-
-@cindex @code{const_string} and attributes
-@item (const_string @var{value})
-The string @var{value} specifies a constant attribute value.
-If @var{value} is specified as @samp{"*"}, it means that the default value of
-the attribute is to be used for the insn containing this expression.
-@samp{"*"} obviously cannot be used in the @var{default} expression
-of a @code{define_attr}.
-
-If the attribute whose value is being specified is numeric, @var{value}
-must be a string containing a non-negative integer (normally
-@code{const_int} would be used in this case). Otherwise, it must
-contain one of the valid values for the attribute.
-
-@cindex @code{if_then_else} and attributes
-@item (if_then_else @var{test} @var{true-value} @var{false-value})
-@var{test} specifies an attribute test, whose format is defined below.
-The value of this expression is @var{true-value} if @var{test} is true,
-otherwise it is @var{false-value}.
-
-@cindex @code{cond} and attributes
-@item (cond [@var{test1} @var{value1} @dots{}] @var{default})
-The first operand of this expression is a vector containing an even
-number of expressions and consisting of pairs of @var{test} and @var{value}
-expressions. The value of the @code{cond} expression is that of the
-@var{value} corresponding to the first true @var{test} expression. If
-none of the @var{test} expressions are true, the value of the @code{cond}
-expression is that of the @var{default} expression.
-@end table
-
-@var{test} expressions can have one of the following forms:
-
-@table @code
-@cindex @code{const_int} and attribute tests
-@item (const_int @var{i})
-This test is true if @var{i} is nonzero and false otherwise.
-
-@cindex @code{not} and attributes
-@cindex @code{ior} and attributes
-@cindex @code{and} and attributes
-@item (not @var{test})
-@itemx (ior @var{test1} @var{test2})
-@itemx (and @var{test1} @var{test2})
-These tests are true if the indicated logical function is true.
-
-@cindex @code{match_operand} and attributes
-@item (match_operand:@var{m} @var{n} @var{pred} @var{constraints})
-This test is true if operand @var{n} of the insn whose attribute value
-is being determined has mode @var{m} (this part of the test is ignored
-if @var{m} is @code{VOIDmode}) and the function specified by the string
-@var{pred} returns a nonzero value when passed operand @var{n} and mode
-@var{m} (this part of the test is ignored if @var{pred} is the null
-string).
-
-The @var{constraints} operand is ignored and should be the null string.
-
-@cindex @code{match_test} and attributes
-@item (match_test @var{c-expr})
-The test is true if C expression @var{c-expr} is true. In non-constant
-attributes, @var{c-expr} has access to the following variables:
-
-@table @var
-@item insn
-The rtl instruction under test.
-@item which_alternative
-The @code{define_insn} alternative that @var{insn} matches.
-@xref{Output Statement}.
-@item operands
-An array of @var{insn}'s rtl operands.
-@end table
-
-@var{c-expr} behaves like the condition in a C @code{if} statement,
-so there is no need to explicitly convert the expression into a boolean
-0 or 1 value. For example, the following two tests are equivalent:
-
-@smallexample
-(match_test "x & 2")
-(match_test "(x & 2) != 0")
-@end smallexample
-
-@cindex @code{le} and attributes
-@cindex @code{leu} and attributes
-@cindex @code{lt} and attributes
-@cindex @code{gt} and attributes
-@cindex @code{gtu} and attributes
-@cindex @code{ge} and attributes
-@cindex @code{geu} and attributes
-@cindex @code{ne} and attributes
-@cindex @code{eq} and attributes
-@cindex @code{plus} and attributes
-@cindex @code{minus} and attributes
-@cindex @code{mult} and attributes
-@cindex @code{div} and attributes
-@cindex @code{mod} and attributes
-@cindex @code{abs} and attributes
-@cindex @code{neg} and attributes
-@cindex @code{ashift} and attributes
-@cindex @code{lshiftrt} and attributes
-@cindex @code{ashiftrt} and attributes
-@item (le @var{arith1} @var{arith2})
-@itemx (leu @var{arith1} @var{arith2})
-@itemx (lt @var{arith1} @var{arith2})
-@itemx (ltu @var{arith1} @var{arith2})
-@itemx (gt @var{arith1} @var{arith2})
-@itemx (gtu @var{arith1} @var{arith2})
-@itemx (ge @var{arith1} @var{arith2})
-@itemx (geu @var{arith1} @var{arith2})
-@itemx (ne @var{arith1} @var{arith2})
-@itemx (eq @var{arith1} @var{arith2})
-These tests are true if the indicated comparison of the two arithmetic
-expressions is true. Arithmetic expressions are formed with
-@code{plus}, @code{minus}, @code{mult}, @code{div}, @code{mod},
-@code{abs}, @code{neg}, @code{and}, @code{ior}, @code{xor}, @code{not},
-@code{ashift}, @code{lshiftrt}, and @code{ashiftrt} expressions.
-
-@findex get_attr
-@code{const_int} and @code{symbol_ref} are always valid terms (@pxref{Insn
-Lengths},for additional forms). @code{symbol_ref} is a string
-denoting a C expression that yields an @code{int} when evaluated by the
-@samp{get_attr_@dots{}} routine. It should normally be a global
-variable.
-
-@findex eq_attr
-@item (eq_attr @var{name} @var{value})
-@var{name} is a string specifying the name of an attribute.
-
-@var{value} is a string that is either a valid value for attribute
-@var{name}, a comma-separated list of values, or @samp{!} followed by a
-value or list. If @var{value} does not begin with a @samp{!}, this
-test is true if the value of the @var{name} attribute of the current
-insn is in the list specified by @var{value}. If @var{value} begins
-with a @samp{!}, this test is true if the attribute's value is
-@emph{not} in the specified list.
-
-For example,
-
-@smallexample
-(eq_attr "type" "load,store")
-@end smallexample
-
-@noindent
-is equivalent to
-
-@smallexample
-(ior (eq_attr "type" "load") (eq_attr "type" "store"))
-@end smallexample
-
-If @var{name} specifies an attribute of @samp{alternative}, it refers to the
-value of the compiler variable @code{which_alternative}
-(@pxref{Output Statement}) and the values must be small integers. For
-example,
-
-@smallexample
-(eq_attr "alternative" "2,3")
-@end smallexample
-
-@noindent
-is equivalent to
-
-@smallexample
-(ior (eq (symbol_ref "which_alternative") (const_int 2))
- (eq (symbol_ref "which_alternative") (const_int 3)))
-@end smallexample
-
-Note that, for most attributes, an @code{eq_attr} test is simplified in cases
-where the value of the attribute being tested is known for all insns matching
-a particular pattern. This is by far the most common case.
-
-@findex attr_flag
-@item (attr_flag @var{name})
-The value of an @code{attr_flag} expression is true if the flag
-specified by @var{name} is true for the @code{insn} currently being
-scheduled.
-
-@var{name} is a string specifying one of a fixed set of flags to test.
-Test the flags @code{forward} and @code{backward} to determine the
-direction of a conditional branch.
-
-This example describes a conditional branch delay slot which
-can be nullified for forward branches that are taken (annul-true) or
-for backward branches which are not taken (annul-false).
-
-@smallexample
-(define_delay (eq_attr "type" "cbranch")
- [(eq_attr "in_branch_delay" "true")
- (and (eq_attr "in_branch_delay" "true")
- (attr_flag "forward"))
- (and (eq_attr "in_branch_delay" "true")
- (attr_flag "backward"))])
-@end smallexample
-
-The @code{forward} and @code{backward} flags are false if the current
-@code{insn} being scheduled is not a conditional branch.
-
-@code{attr_flag} is only used during delay slot scheduling and has no
-meaning to other passes of the compiler.
-
-@findex attr
-@item (attr @var{name})
-The value of another attribute is returned. This is most useful
-for numeric attributes, as @code{eq_attr} and @code{attr_flag}
-produce more efficient code for non-numeric attributes.
-@end table
-
-@end ifset
-@ifset INTERNALS
-@node Tagging Insns
-@subsection Assigning Attribute Values to Insns
-@cindex tagging insns
-@cindex assigning attribute values to insns
-
-The value assigned to an attribute of an insn is primarily determined by
-which pattern is matched by that insn (or which @code{define_peephole}
-generated it). Every @code{define_insn} and @code{define_peephole} can
-have an optional last argument to specify the values of attributes for
-matching insns. The value of any attribute not specified in a particular
-insn is set to the default value for that attribute, as specified in its
-@code{define_attr}. Extensive use of default values for attributes
-permits the specification of the values for only one or two attributes
-in the definition of most insn patterns, as seen in the example in the
-next section.
-
-The optional last argument of @code{define_insn} and
-@code{define_peephole} is a vector of expressions, each of which defines
-the value for a single attribute. The most general way of assigning an
-attribute's value is to use a @code{set} expression whose first operand is an
-@code{attr} expression giving the name of the attribute being set. The
-second operand of the @code{set} is an attribute expression
-(@pxref{Expressions}) giving the value of the attribute.
-
-When the attribute value depends on the @samp{alternative} attribute
-(i.e., which is the applicable alternative in the constraint of the
-insn), the @code{set_attr_alternative} expression can be used. It
-allows the specification of a vector of attribute expressions, one for
-each alternative.
-
-@findex set_attr
-When the generality of arbitrary attribute expressions is not required,
-the simpler @code{set_attr} expression can be used, which allows
-specifying a string giving either a single attribute value or a list
-of attribute values, one for each alternative.
-
-The form of each of the above specifications is shown below. In each case,
-@var{name} is a string specifying the attribute to be set.
-
-@table @code
-@item (set_attr @var{name} @var{value-string})
-@var{value-string} is either a string giving the desired attribute value,
-or a string containing a comma-separated list giving the values for
-succeeding alternatives. The number of elements must match the number
-of alternatives in the constraint of the insn pattern.
-
-Note that it may be useful to specify @samp{*} for some alternative, in
-which case the attribute will assume its default value for insns matching
-that alternative.
-
-@findex set_attr_alternative
-@item (set_attr_alternative @var{name} [@var{value1} @var{value2} @dots{}])
-Depending on the alternative of the insn, the value will be one of the
-specified values. This is a shorthand for using a @code{cond} with
-tests on the @samp{alternative} attribute.
-
-@findex attr
-@item (set (attr @var{name}) @var{value})
-The first operand of this @code{set} must be the special RTL expression
-@code{attr}, whose sole operand is a string giving the name of the
-attribute being set. @var{value} is the value of the attribute.
-@end table
-
-The following shows three different ways of representing the same
-attribute value specification:
-
-@smallexample
-(set_attr "type" "load,store,arith")
-
-(set_attr_alternative "type"
- [(const_string "load") (const_string "store")
- (const_string "arith")])
-
-(set (attr "type")
- (cond [(eq_attr "alternative" "1") (const_string "load")
- (eq_attr "alternative" "2") (const_string "store")]
- (const_string "arith")))
-@end smallexample
-
-@need 1000
-@findex define_asm_attributes
-The @code{define_asm_attributes} expression provides a mechanism to
-specify the attributes assigned to insns produced from an @code{asm}
-statement. It has the form:
-
-@smallexample
-(define_asm_attributes [@var{attr-sets}])
-@end smallexample
-
-@noindent
-where @var{attr-sets} is specified the same as for both the
-@code{define_insn} and the @code{define_peephole} expressions.
-
-These values will typically be the ``worst case'' attribute values. For
-example, they might indicate that the condition code will be clobbered.
-
-A specification for a @code{length} attribute is handled specially. The
-way to compute the length of an @code{asm} insn is to multiply the
-length specified in the expression @code{define_asm_attributes} by the
-number of machine instructions specified in the @code{asm} statement,
-determined by counting the number of semicolons and newlines in the
-string. Therefore, the value of the @code{length} attribute specified
-in a @code{define_asm_attributes} should be the maximum possible length
-of a single machine instruction.
-
-@end ifset
-@ifset INTERNALS
-@node Attr Example
-@subsection Example of Attribute Specifications
-@cindex attribute specifications example
-@cindex attribute specifications
-
-The judicious use of defaulting is important in the efficient use of
-insn attributes. Typically, insns are divided into @dfn{types} and an
-attribute, customarily called @code{type}, is used to represent this
-value. This attribute is normally used only to define the default value
-for other attributes. An example will clarify this usage.
-
-Assume we have a RISC machine with a condition code and in which only
-full-word operations are performed in registers. Let us assume that we
-can divide all insns into loads, stores, (integer) arithmetic
-operations, floating point operations, and branches.
-
-Here we will concern ourselves with determining the effect of an insn on
-the condition code and will limit ourselves to the following possible
-effects: The condition code can be set unpredictably (clobbered), not
-be changed, be set to agree with the results of the operation, or only
-changed if the item previously set into the condition code has been
-modified.
-
-Here is part of a sample @file{md} file for such a machine:
-
-@smallexample
-(define_attr "type" "load,store,arith,fp,branch" (const_string "arith"))
-
-(define_attr "cc" "clobber,unchanged,set,change0"
- (cond [(eq_attr "type" "load")
- (const_string "change0")
- (eq_attr "type" "store,branch")
- (const_string "unchanged")
- (eq_attr "type" "arith")
- (if_then_else (match_operand:SI 0 "" "")
- (const_string "set")
- (const_string "clobber"))]
- (const_string "clobber")))
-
-(define_insn ""
- [(set (match_operand:SI 0 "general_operand" "=r,r,m")
- (match_operand:SI 1 "general_operand" "r,m,r"))]
- ""
- "@@
- move %0,%1
- load %0,%1
- store %0,%1"
- [(set_attr "type" "arith,load,store")])
-@end smallexample
-
-Note that we assume in the above example that arithmetic operations
-performed on quantities smaller than a machine word clobber the condition
-code since they will set the condition code to a value corresponding to the
-full-word result.
-
-@end ifset
-@ifset INTERNALS
-@node Insn Lengths
-@subsection Computing the Length of an Insn
-@cindex insn lengths, computing
-@cindex computing the length of an insn
-
-For many machines, multiple types of branch instructions are provided, each
-for different length branch displacements. In most cases, the assembler
-will choose the correct instruction to use. However, when the assembler
-cannot do so, GCC can when a special attribute, the @code{length}
-attribute, is defined. This attribute must be defined to have numeric
-values by specifying a null string in its @code{define_attr}.
-
-In the case of the @code{length} attribute, two additional forms of
-arithmetic terms are allowed in test expressions:
-
-@table @code
-@cindex @code{match_dup} and attributes
-@item (match_dup @var{n})
-This refers to the address of operand @var{n} of the current insn, which
-must be a @code{label_ref}.
-
-@cindex @code{pc} and attributes
-@item (pc)
-For non-branch instructions and backward branch instructions, this refers
-to the address of the current insn. But for forward branch instructions,
-this refers to the address of the next insn, because the length of the
-current insn is to be computed.
-@end table
-
-@cindex @code{addr_vec}, length of
-@cindex @code{addr_diff_vec}, length of
-For normal insns, the length will be determined by value of the
-@code{length} attribute. In the case of @code{addr_vec} and
-@code{addr_diff_vec} insn patterns, the length is computed as
-the number of vectors multiplied by the size of each vector.
-
-Lengths are measured in addressable storage units (bytes).
-
-Note that it is possible to call functions via the @code{symbol_ref}
-mechanism to compute the length of an insn. However, if you use this
-mechanism you must provide dummy clauses to express the maximum length
-without using the function call. You can see an example of this in the
-@code{pa} machine description for the @code{call_symref} pattern.
-
-The following macros can be used to refine the length computation:
-
-@table @code
-@findex ADJUST_INSN_LENGTH
-@item ADJUST_INSN_LENGTH (@var{insn}, @var{length})
-If defined, modifies the length assigned to instruction @var{insn} as a
-function of the context in which it is used. @var{length} is an lvalue
-that contains the initially computed length of the insn and should be
-updated with the correct length of the insn.
-
-This macro will normally not be required. A case in which it is
-required is the ROMP@. On this machine, the size of an @code{addr_vec}
-insn must be increased by two to compensate for the fact that alignment
-may be required.
-@end table
-
-@findex get_attr_length
-The routine that returns @code{get_attr_length} (the value of the
-@code{length} attribute) can be used by the output routine to
-determine the form of the branch instruction to be written, as the
-example below illustrates.
-
-As an example of the specification of variable-length branches, consider
-the IBM 360. If we adopt the convention that a register will be set to
-the starting address of a function, we can jump to labels within 4k of
-the start using a four-byte instruction. Otherwise, we need a six-byte
-sequence to load the address from memory and then branch to it.
-
-On such a machine, a pattern for a branch instruction might be specified
-as follows:
-
-@smallexample
-(define_insn "jump"
- [(set (pc)
- (label_ref (match_operand 0 "" "")))]
- ""
-@{
- return (get_attr_length (insn) == 4
- ? "b %l0" : "l r15,=a(%l0); br r15");
-@}
- [(set (attr "length")
- (if_then_else (lt (match_dup 0) (const_int 4096))
- (const_int 4)
- (const_int 6)))])
-@end smallexample
-
-@end ifset
-@ifset INTERNALS
-@node Constant Attributes
-@subsection Constant Attributes
-@cindex constant attributes
-
-A special form of @code{define_attr}, where the expression for the
-default value is a @code{const} expression, indicates an attribute that
-is constant for a given run of the compiler. Constant attributes may be
-used to specify which variety of processor is used. For example,
-
-@smallexample
-(define_attr "cpu" "m88100,m88110,m88000"
- (const
- (cond [(symbol_ref "TARGET_88100") (const_string "m88100")
- (symbol_ref "TARGET_88110") (const_string "m88110")]
- (const_string "m88000"))))
-
-(define_attr "memory" "fast,slow"
- (const
- (if_then_else (symbol_ref "TARGET_FAST_MEM")
- (const_string "fast")
- (const_string "slow"))))
-@end smallexample
-
-The routine generated for constant attributes has no parameters as it
-does not depend on any particular insn. RTL expressions used to define
-the value of a constant attribute may use the @code{symbol_ref} form,
-but may not use either the @code{match_operand} form or @code{eq_attr}
-forms involving insn attributes.
-
-@end ifset
-@ifset INTERNALS
-@node Mnemonic Attribute
-@subsection Mnemonic Attribute
-@cindex mnemonic attribute
-
-The @code{mnemonic} attribute is a string type attribute holding the
-instruction mnemonic for an insn alternative. The attribute values
-will automatically be generated by the machine description parser if
-there is an attribute definition in the md file:
-
-@smallexample
-(define_attr "mnemonic" "unknown" (const_string "unknown"))
-@end smallexample
-
-The default value can be freely chosen as long as it does not collide
-with any of the instruction mnemonics. This value will be used
-whenever the machine description parser is not able to determine the
-mnemonic string. This might be the case for output templates
-containing more than a single instruction as in
-@code{"mvcle\t%0,%1,0\;jo\t.-4"}.
-
-The @code{mnemonic} attribute set is not generated automatically if the
-instruction string is generated via C code.
-
-An existing @code{mnemonic} attribute set in an insn definition will not
-be overriden by the md file parser. That way it is possible to
-manually set the instruction mnemonics for the cases where the md file
-parser fails to determine it automatically.
-
-The @code{mnemonic} attribute is useful for dealing with instruction
-specific properties in the pipeline description without defining
-additional insn attributes.
-
-@smallexample
-(define_attr "ooo_expanded" ""
- (cond [(eq_attr "mnemonic" "dlr,dsgr,d,dsgf,stam,dsgfr,dlgr")
- (const_int 1)]
- (const_int 0)))
-@end smallexample
-
-@end ifset
-@ifset INTERNALS
-@node Delay Slots
-@subsection Delay Slot Scheduling
-@cindex delay slots, defining
-
-The insn attribute mechanism can be used to specify the requirements for
-delay slots, if any, on a target machine. An instruction is said to
-require a @dfn{delay slot} if some instructions that are physically
-after the instruction are executed as if they were located before it.
-Classic examples are branch and call instructions, which often execute
-the following instruction before the branch or call is performed.
-
-On some machines, conditional branch instructions can optionally
-@dfn{annul} instructions in the delay slot. This means that the
-instruction will not be executed for certain branch outcomes. Both
-instructions that annul if the branch is true and instructions that
-annul if the branch is false are supported.
-
-Delay slot scheduling differs from instruction scheduling in that
-determining whether an instruction needs a delay slot is dependent only
-on the type of instruction being generated, not on data flow between the
-instructions. See the next section for a discussion of data-dependent
-instruction scheduling.
-
-@findex define_delay
-The requirement of an insn needing one or more delay slots is indicated
-via the @code{define_delay} expression. It has the following form:
-
-@smallexample
-(define_delay @var{test}
- [@var{delay-1} @var{annul-true-1} @var{annul-false-1}
- @var{delay-2} @var{annul-true-2} @var{annul-false-2}
- @dots{}])
-@end smallexample
-
-@var{test} is an attribute test that indicates whether this
-@code{define_delay} applies to a particular insn. If so, the number of
-required delay slots is determined by the length of the vector specified
-as the second argument. An insn placed in delay slot @var{n} must
-satisfy attribute test @var{delay-n}. @var{annul-true-n} is an
-attribute test that specifies which insns may be annulled if the branch
-is true. Similarly, @var{annul-false-n} specifies which insns in the
-delay slot may be annulled if the branch is false. If annulling is not
-supported for that delay slot, @code{(nil)} should be coded.
-
-For example, in the common case where branch and call insns require
-a single delay slot, which may contain any insn other than a branch or
-call, the following would be placed in the @file{md} file:
-
-@smallexample
-(define_delay (eq_attr "type" "branch,call")
- [(eq_attr "type" "!branch,call") (nil) (nil)])
-@end smallexample
-
-Multiple @code{define_delay} expressions may be specified. In this
-case, each such expression specifies different delay slot requirements
-and there must be no insn for which tests in two @code{define_delay}
-expressions are both true.
-
-For example, if we have a machine that requires one delay slot for branches
-but two for calls, no delay slot can contain a branch or call insn,
-and any valid insn in the delay slot for the branch can be annulled if the
-branch is true, we might represent this as follows:
-
-@smallexample
-(define_delay (eq_attr "type" "branch")
- [(eq_attr "type" "!branch,call")
- (eq_attr "type" "!branch,call")
- (nil)])
-
-(define_delay (eq_attr "type" "call")
- [(eq_attr "type" "!branch,call") (nil) (nil)
- (eq_attr "type" "!branch,call") (nil) (nil)])
-@end smallexample
-@c the above is *still* too long. --mew 4feb93
-
-@end ifset
-@ifset INTERNALS
-@node Processor pipeline description
-@subsection Specifying processor pipeline description
-@cindex processor pipeline description
-@cindex processor functional units
-@cindex instruction latency time
-@cindex interlock delays
-@cindex data dependence delays
-@cindex reservation delays
-@cindex pipeline hazard recognizer
-@cindex automaton based pipeline description
-@cindex regular expressions
-@cindex deterministic finite state automaton
-@cindex automaton based scheduler
-@cindex RISC
-@cindex VLIW
-
-To achieve better performance, most modern processors
-(super-pipelined, superscalar @acronym{RISC}, and @acronym{VLIW}
-processors) have many @dfn{functional units} on which several
-instructions can be executed simultaneously. An instruction starts
-execution if its issue conditions are satisfied. If not, the
-instruction is stalled until its conditions are satisfied. Such
-@dfn{interlock (pipeline) delay} causes interruption of the fetching
-of successor instructions (or demands nop instructions, e.g.@: for some
-MIPS processors).
-
-There are two major kinds of interlock delays in modern processors.
-The first one is a data dependence delay determining @dfn{instruction
-latency time}. The instruction execution is not started until all
-source data have been evaluated by prior instructions (there are more
-complex cases when the instruction execution starts even when the data
-are not available but will be ready in given time after the
-instruction execution start). Taking the data dependence delays into
-account is simple. The data dependence (true, output, and
-anti-dependence) delay between two instructions is given by a
-constant. In most cases this approach is adequate. The second kind
-of interlock delays is a reservation delay. The reservation delay
-means that two instructions under execution will be in need of shared
-processors resources, i.e.@: buses, internal registers, and/or
-functional units, which are reserved for some time. Taking this kind
-of delay into account is complex especially for modern @acronym{RISC}
-processors.
-
-The task of exploiting more processor parallelism is solved by an
-instruction scheduler. For a better solution to this problem, the
-instruction scheduler has to have an adequate description of the
-processor parallelism (or @dfn{pipeline description}). GCC
-machine descriptions describe processor parallelism and functional
-unit reservations for groups of instructions with the aid of
-@dfn{regular expressions}.
-
-The GCC instruction scheduler uses a @dfn{pipeline hazard recognizer} to
-figure out the possibility of the instruction issue by the processor
-on a given simulated processor cycle. The pipeline hazard recognizer is
-automatically generated from the processor pipeline description. The
-pipeline hazard recognizer generated from the machine description
-is based on a deterministic finite state automaton (@acronym{DFA}):
-the instruction issue is possible if there is a transition from one
-automaton state to another one. This algorithm is very fast, and
-furthermore, its speed is not dependent on processor
-complexity@footnote{However, the size of the automaton depends on
-processor complexity. To limit this effect, machine descriptions
-can split orthogonal parts of the machine description among several
-automata: but then, since each of these must be stepped independently,
-this does cause a small decrease in the algorithm's performance.}.
-
-@cindex automaton based pipeline description
-The rest of this section describes the directives that constitute
-an automaton-based processor pipeline description. The order of
-these constructions within the machine description file is not
-important.
-
-@findex define_automaton
-@cindex pipeline hazard recognizer
-The following optional construction describes names of automata
-generated and used for the pipeline hazards recognition. Sometimes
-the generated finite state automaton used by the pipeline hazard
-recognizer is large. If we use more than one automaton and bind functional
-units to the automata, the total size of the automata is usually
-less than the size of the single automaton. If there is no one such
-construction, only one finite state automaton is generated.
-
-@smallexample
-(define_automaton @var{automata-names})
-@end smallexample
-
-@var{automata-names} is a string giving names of the automata. The
-names are separated by commas. All the automata should have unique names.
-The automaton name is used in the constructions @code{define_cpu_unit} and
-@code{define_query_cpu_unit}.
-
-@findex define_cpu_unit
-@cindex processor functional units
-Each processor functional unit used in the description of instruction
-reservations should be described by the following construction.
-
-@smallexample
-(define_cpu_unit @var{unit-names} [@var{automaton-name}])
-@end smallexample
-
-@var{unit-names} is a string giving the names of the functional units
-separated by commas. Don't use name @samp{nothing}, it is reserved
-for other goals.
-
-@var{automaton-name} is a string giving the name of the automaton with
-which the unit is bound. The automaton should be described in
-construction @code{define_automaton}. You should give
-@dfn{automaton-name}, if there is a defined automaton.
-
-The assignment of units to automata are constrained by the uses of the
-units in insn reservations. The most important constraint is: if a
-unit reservation is present on a particular cycle of an alternative
-for an insn reservation, then some unit from the same automaton must
-be present on the same cycle for the other alternatives of the insn
-reservation. The rest of the constraints are mentioned in the
-description of the subsequent constructions.
-
-@findex define_query_cpu_unit
-@cindex querying function unit reservations
-The following construction describes CPU functional units analogously
-to @code{define_cpu_unit}. The reservation of such units can be
-queried for an automaton state. The instruction scheduler never
-queries reservation of functional units for given automaton state. So
-as a rule, you don't need this construction. This construction could
-be used for future code generation goals (e.g.@: to generate
-@acronym{VLIW} insn templates).
-
-@smallexample
-(define_query_cpu_unit @var{unit-names} [@var{automaton-name}])
-@end smallexample
-
-@var{unit-names} is a string giving names of the functional units
-separated by commas.
-
-@var{automaton-name} is a string giving the name of the automaton with
-which the unit is bound.
-
-@findex define_insn_reservation
-@cindex instruction latency time
-@cindex regular expressions
-@cindex data bypass
-The following construction is the major one to describe pipeline
-characteristics of an instruction.
-
-@smallexample
-(define_insn_reservation @var{insn-name} @var{default_latency}
- @var{condition} @var{regexp})
-@end smallexample
-
-@var{default_latency} is a number giving latency time of the
-instruction. There is an important difference between the old
-description and the automaton based pipeline description. The latency
-time is used for all dependencies when we use the old description. In
-the automaton based pipeline description, the given latency time is only
-used for true dependencies. The cost of anti-dependencies is always
-zero and the cost of output dependencies is the difference between
-latency times of the producing and consuming insns (if the difference
-is negative, the cost is considered to be zero). You can always
-change the default costs for any description by using the target hook
-@code{TARGET_SCHED_ADJUST_COST} (@pxref{Scheduling}).
-
-@var{insn-name} is a string giving the internal name of the insn. The
-internal names are used in constructions @code{define_bypass} and in
-the automaton description file generated for debugging. The internal
-name has nothing in common with the names in @code{define_insn}. It is a
-good practice to use insn classes described in the processor manual.
-
-@var{condition} defines what RTL insns are described by this
-construction. You should remember that you will be in trouble if
-@var{condition} for two or more different
-@code{define_insn_reservation} constructions is TRUE for an insn. In
-this case what reservation will be used for the insn is not defined.
-Such cases are not checked during generation of the pipeline hazards
-recognizer because in general recognizing that two conditions may have
-the same value is quite difficult (especially if the conditions
-contain @code{symbol_ref}). It is also not checked during the
-pipeline hazard recognizer work because it would slow down the
-recognizer considerably.
-
-@var{regexp} is a string describing the reservation of the cpu's functional
-units by the instruction. The reservations are described by a regular
-expression according to the following syntax:
-
-@smallexample
- regexp = regexp "," oneof
- | oneof
-
- oneof = oneof "|" allof
- | allof
-
- allof = allof "+" repeat
- | repeat
-
- repeat = element "*" number
- | element
-
- element = cpu_function_unit_name
- | reservation_name
- | result_name
- | "nothing"
- | "(" regexp ")"
-@end smallexample
-
-@itemize @bullet
-@item
-@samp{,} is used for describing the start of the next cycle in
-the reservation.
-
-@item
-@samp{|} is used for describing a reservation described by the first
-regular expression @strong{or} a reservation described by the second
-regular expression @strong{or} etc.
-
-@item
-@samp{+} is used for describing a reservation described by the first
-regular expression @strong{and} a reservation described by the
-second regular expression @strong{and} etc.
-
-@item
-@samp{*} is used for convenience and simply means a sequence in which
-the regular expression are repeated @var{number} times with cycle
-advancing (see @samp{,}).
-
-@item
-@samp{cpu_function_unit_name} denotes reservation of the named
-functional unit.
-
-@item
-@samp{reservation_name} --- see description of construction
-@samp{define_reservation}.
-
-@item
-@samp{nothing} denotes no unit reservations.
-@end itemize
-
-@findex define_reservation
-Sometimes unit reservations for different insns contain common parts.
-In such case, you can simplify the pipeline description by describing
-the common part by the following construction
-
-@smallexample
-(define_reservation @var{reservation-name} @var{regexp})
-@end smallexample
-
-@var{reservation-name} is a string giving name of @var{regexp}.
-Functional unit names and reservation names are in the same name
-space. So the reservation names should be different from the
-functional unit names and cannot be the reserved name @samp{nothing}.
-
-@findex define_bypass
-@cindex instruction latency time
-@cindex data bypass
-The following construction is used to describe exceptions in the
-latency time for given instruction pair. This is so called bypasses.
-
-@smallexample
-(define_bypass @var{number} @var{out_insn_names} @var{in_insn_names}
- [@var{guard}])
-@end smallexample
-
-@var{number} defines when the result generated by the instructions
-given in string @var{out_insn_names} will be ready for the
-instructions given in string @var{in_insn_names}. Each of these
-strings is a comma-separated list of filename-style globs and
-they refer to the names of @code{define_insn_reservation}s.
-For example:
-@smallexample
-(define_bypass 1 "cpu1_load_*, cpu1_store_*" "cpu1_load_*")
-@end smallexample
-defines a bypass between instructions that start with
-@samp{cpu1_load_} or @samp{cpu1_store_} and those that start with
-@samp{cpu1_load_}.
-
-@var{guard} is an optional string giving the name of a C function which
-defines an additional guard for the bypass. The function will get the
-two insns as parameters. If the function returns zero the bypass will
-be ignored for this case. The additional guard is necessary to
-recognize complicated bypasses, e.g.@: when the consumer is only an address
-of insn @samp{store} (not a stored value).
-
-If there are more one bypass with the same output and input insns, the
-chosen bypass is the first bypass with a guard in description whose
-guard function returns nonzero. If there is no such bypass, then
-bypass without the guard function is chosen.
-
-@findex exclusion_set
-@findex presence_set
-@findex final_presence_set
-@findex absence_set
-@findex final_absence_set
-@cindex VLIW
-@cindex RISC
-The following five constructions are usually used to describe
-@acronym{VLIW} processors, or more precisely, to describe a placement
-of small instructions into @acronym{VLIW} instruction slots. They
-can be used for @acronym{RISC} processors, too.
-
-@smallexample
-(exclusion_set @var{unit-names} @var{unit-names})
-(presence_set @var{unit-names} @var{patterns})
-(final_presence_set @var{unit-names} @var{patterns})
-(absence_set @var{unit-names} @var{patterns})
-(final_absence_set @var{unit-names} @var{patterns})
-@end smallexample
-
-@var{unit-names} is a string giving names of functional units
-separated by commas.
-
-@var{patterns} is a string giving patterns of functional units
-separated by comma. Currently pattern is one unit or units
-separated by white-spaces.
-
-The first construction (@samp{exclusion_set}) means that each
-functional unit in the first string cannot be reserved simultaneously
-with a unit whose name is in the second string and vice versa. For
-example, the construction is useful for describing processors
-(e.g.@: some SPARC processors) with a fully pipelined floating point
-functional unit which can execute simultaneously only single floating
-point insns or only double floating point insns.
-
-The second construction (@samp{presence_set}) means that each
-functional unit in the first string cannot be reserved unless at
-least one of pattern of units whose names are in the second string is
-reserved. This is an asymmetric relation. For example, it is useful
-for description that @acronym{VLIW} @samp{slot1} is reserved after
-@samp{slot0} reservation. We could describe it by the following
-construction
-
-@smallexample
-(presence_set "slot1" "slot0")
-@end smallexample
-
-Or @samp{slot1} is reserved only after @samp{slot0} and unit @samp{b0}
-reservation. In this case we could write
-
-@smallexample
-(presence_set "slot1" "slot0 b0")
-@end smallexample
-
-The third construction (@samp{final_presence_set}) is analogous to
-@samp{presence_set}. The difference between them is when checking is
-done. When an instruction is issued in given automaton state
-reflecting all current and planned unit reservations, the automaton
-state is changed. The first state is a source state, the second one
-is a result state. Checking for @samp{presence_set} is done on the
-source state reservation, checking for @samp{final_presence_set} is
-done on the result reservation. This construction is useful to
-describe a reservation which is actually two subsequent reservations.
-For example, if we use
-
-@smallexample
-(presence_set "slot1" "slot0")
-@end smallexample
-
-the following insn will be never issued (because @samp{slot1} requires
-@samp{slot0} which is absent in the source state).
-
-@smallexample
-(define_reservation "insn_and_nop" "slot0 + slot1")
-@end smallexample
-
-but it can be issued if we use analogous @samp{final_presence_set}.
-
-The forth construction (@samp{absence_set}) means that each functional
-unit in the first string can be reserved only if each pattern of units
-whose names are in the second string is not reserved. This is an
-asymmetric relation (actually @samp{exclusion_set} is analogous to
-this one but it is symmetric). For example it might be useful in a
-@acronym{VLIW} description to say that @samp{slot0} cannot be reserved
-after either @samp{slot1} or @samp{slot2} have been reserved. This
-can be described as:
-
-@smallexample
-(absence_set "slot0" "slot1, slot2")
-@end smallexample
-
-Or @samp{slot2} cannot be reserved if @samp{slot0} and unit @samp{b0}
-are reserved or @samp{slot1} and unit @samp{b1} are reserved. In
-this case we could write
-
-@smallexample
-(absence_set "slot2" "slot0 b0, slot1 b1")
-@end smallexample
-
-All functional units mentioned in a set should belong to the same
-automaton.
-
-The last construction (@samp{final_absence_set}) is analogous to
-@samp{absence_set} but checking is done on the result (state)
-reservation. See comments for @samp{final_presence_set}.
-
-@findex automata_option
-@cindex deterministic finite state automaton
-@cindex nondeterministic finite state automaton
-@cindex finite state automaton minimization
-You can control the generator of the pipeline hazard recognizer with
-the following construction.
-
-@smallexample
-(automata_option @var{options})
-@end smallexample
-
-@var{options} is a string giving options which affect the generated
-code. Currently there are the following options:
-
-@itemize @bullet
-@item
-@dfn{no-minimization} makes no minimization of the automaton. This is
-only worth to do when we are debugging the description and need to
-look more accurately at reservations of states.
-
-@item
-@dfn{time} means printing time statistics about the generation of
-automata.
-
-@item
-@dfn{stats} means printing statistics about the generated automata
-such as the number of DFA states, NDFA states and arcs.
-
-@item
-@dfn{v} means a generation of the file describing the result automata.
-The file has suffix @samp{.dfa} and can be used for the description
-verification and debugging.
-
-@item
-@dfn{w} means a generation of warning instead of error for
-non-critical errors.
-
-@item
-@dfn{no-comb-vect} prevents the automaton generator from generating
-two data structures and comparing them for space efficiency. Using
-a comb vector to represent transitions may be better, but it can be
-very expensive to construct. This option is useful if the build
-process spends an unacceptably long time in genautomata.
-
-@item
-@dfn{ndfa} makes nondeterministic finite state automata. This affects
-the treatment of operator @samp{|} in the regular expressions. The
-usual treatment of the operator is to try the first alternative and,
-if the reservation is not possible, the second alternative. The
-nondeterministic treatment means trying all alternatives, some of them
-may be rejected by reservations in the subsequent insns.
-
-@item
-@dfn{collapse-ndfa} modifies the behavior of the generator when
-producing an automaton. An additional state transition to collapse a
-nondeterministic @acronym{NDFA} state to a deterministic @acronym{DFA}
-state is generated. It can be triggered by passing @code{const0_rtx} to
-state_transition. In such an automaton, cycle advance transitions are
-available only for these collapsed states. This option is useful for
-ports that want to use the @code{ndfa} option, but also want to use
-@code{define_query_cpu_unit} to assign units to insns issued in a cycle.
-
-@item
-@dfn{progress} means output of a progress bar showing how many states
-were generated so far for automaton being processed. This is useful
-during debugging a @acronym{DFA} description. If you see too many
-generated states, you could interrupt the generator of the pipeline
-hazard recognizer and try to figure out a reason for generation of the
-huge automaton.
-@end itemize
-
-As an example, consider a superscalar @acronym{RISC} machine which can
-issue three insns (two integer insns and one floating point insn) on
-the cycle but can finish only two insns. To describe this, we define
-the following functional units.
-
-@smallexample
-(define_cpu_unit "i0_pipeline, i1_pipeline, f_pipeline")
-(define_cpu_unit "port0, port1")
-@end smallexample
-
-All simple integer insns can be executed in any integer pipeline and
-their result is ready in two cycles. The simple integer insns are
-issued into the first pipeline unless it is reserved, otherwise they
-are issued into the second pipeline. Integer division and
-multiplication insns can be executed only in the second integer
-pipeline and their results are ready correspondingly in 9 and 4
-cycles. The integer division is not pipelined, i.e.@: the subsequent
-integer division insn cannot be issued until the current division
-insn finished. Floating point insns are fully pipelined and their
-results are ready in 3 cycles. Where the result of a floating point
-insn is used by an integer insn, an additional delay of one cycle is
-incurred. To describe all of this we could specify
-
-@smallexample
-(define_cpu_unit "div")
-
-(define_insn_reservation "simple" 2 (eq_attr "type" "int")
- "(i0_pipeline | i1_pipeline), (port0 | port1)")
-
-(define_insn_reservation "mult" 4 (eq_attr "type" "mult")
- "i1_pipeline, nothing*2, (port0 | port1)")
-
-(define_insn_reservation "div" 9 (eq_attr "type" "div")
- "i1_pipeline, div*7, div + (port0 | port1)")
-
-(define_insn_reservation "float" 3 (eq_attr "type" "float")
- "f_pipeline, nothing, (port0 | port1))
-
-(define_bypass 4 "float" "simple,mult,div")
-@end smallexample
-
-To simplify the description we could describe the following reservation
-
-@smallexample
-(define_reservation "finish" "port0|port1")
-@end smallexample
-
-and use it in all @code{define_insn_reservation} as in the following
-construction
-
-@smallexample
-(define_insn_reservation "simple" 2 (eq_attr "type" "int")
- "(i0_pipeline | i1_pipeline), finish")
-@end smallexample
-
-
-@end ifset
-@ifset INTERNALS
-@node Conditional Execution
-@section Conditional Execution
-@cindex conditional execution
-@cindex predication
-
-A number of architectures provide for some form of conditional
-execution, or predication. The hallmark of this feature is the
-ability to nullify most of the instructions in the instruction set.
-When the instruction set is large and not entirely symmetric, it
-can be quite tedious to describe these forms directly in the
-@file{.md} file. An alternative is the @code{define_cond_exec} template.
-
-@findex define_cond_exec
-@smallexample
-(define_cond_exec
- [@var{predicate-pattern}]
- "@var{condition}"
- "@var{output-template}"
- "@var{optional-insn-attribues}")
-@end smallexample
-
-@var{predicate-pattern} is the condition that must be true for the
-insn to be executed at runtime and should match a relational operator.
-One can use @code{match_operator} to match several relational operators
-at once. Any @code{match_operand} operands must have no more than one
-alternative.
-
-@var{condition} is a C expression that must be true for the generated
-pattern to match.
-
-@findex current_insn_predicate
-@var{output-template} is a string similar to the @code{define_insn}
-output template (@pxref{Output Template}), except that the @samp{*}
-and @samp{@@} special cases do not apply. This is only useful if the
-assembly text for the predicate is a simple prefix to the main insn.
-In order to handle the general case, there is a global variable
-@code{current_insn_predicate} that will contain the entire predicate
-if the current insn is predicated, and will otherwise be @code{NULL}.
-
-@var{optional-insn-attributes} is an optional vector of attributes that gets
-appended to the insn attributes of the produced cond_exec rtx. It can
-be used to add some distinguishing attribute to cond_exec rtxs produced
-that way. An example usage would be to use this attribute in conjunction
-with attributes on the main pattern to disable particular alternatives under
-certain conditions.
-
-When @code{define_cond_exec} is used, an implicit reference to
-the @code{predicable} instruction attribute is made.
-@xref{Insn Attributes}. This attribute must be a boolean (i.e.@: have
-exactly two elements in its @var{list-of-values}), with the possible
-values being @code{no} and @code{yes}. The default and all uses in
-the insns must be a simple constant, not a complex expressions. It
-may, however, depend on the alternative, by using a comma-separated
-list of values. If that is the case, the port should also define an
-@code{enabled} attribute (@pxref{Disable Insn Alternatives}), which
-should also allow only @code{no} and @code{yes} as its values.
-
-For each @code{define_insn} for which the @code{predicable}
-attribute is true, a new @code{define_insn} pattern will be
-generated that matches a predicated version of the instruction.
-For example,
-
-@smallexample
-(define_insn "addsi"
- [(set (match_operand:SI 0 "register_operand" "r")
- (plus:SI (match_operand:SI 1 "register_operand" "r")
- (match_operand:SI 2 "register_operand" "r")))]
- "@var{test1}"
- "add %2,%1,%0")
-
-(define_cond_exec
- [(ne (match_operand:CC 0 "register_operand" "c")
- (const_int 0))]
- "@var{test2}"
- "(%0)")
-@end smallexample
-
-@noindent
-generates a new pattern
-
-@smallexample
-(define_insn ""
- [(cond_exec
- (ne (match_operand:CC 3 "register_operand" "c") (const_int 0))
- (set (match_operand:SI 0 "register_operand" "r")
- (plus:SI (match_operand:SI 1 "register_operand" "r")
- (match_operand:SI 2 "register_operand" "r"))))]
- "(@var{test2}) && (@var{test1})"
- "(%3) add %2,%1,%0")
-@end smallexample
-
-@end ifset
-@ifset INTERNALS
-@node Define Subst
-@section RTL Templates Transformations
-@cindex define_subst
-
-For some hardware architectures there are common cases when the RTL
-templates for the instructions can be derived from the other RTL
-templates using simple transformations. E.g., @file{i386.md} contains
-an RTL template for the ordinary @code{sub} instruction---
-@code{*subsi_1}, and for the @code{sub} instruction with subsequent
-zero-extension---@code{*subsi_1_zext}. Such cases can be easily
-implemented by a single meta-template capable of generating a modified
-case based on the initial one:
-
-@findex define_subst
-@smallexample
-(define_subst "@var{name}"
- [@var{input-template}]
- "@var{condition}"
- [@var{output-template}])
-@end smallexample
-@var{input-template} is a pattern describing the source RTL template,
-which will be transformed.
-
-@var{condition} is a C expression that is conjunct with the condition
-from the input-template to generate a condition to be used in the
-output-template.
-
-@var{output-template} is a pattern that will be used in the resulting
-template.
-
-@code{define_subst} mechanism is tightly coupled with the notion of the
-subst attribute (@pxref{Subst Iterators}). The use of
-@code{define_subst} is triggered by a reference to a subst attribute in
-the transforming RTL template. This reference initiates duplication of
-the source RTL template and substitution of the attributes with their
-values. The source RTL template is left unchanged, while the copy is
-transformed by @code{define_subst}. This transformation can fail in the
-case when the source RTL template is not matched against the
-input-template of the @code{define_subst}. In such case the copy is
-deleted.
-
-@code{define_subst} can be used only in @code{define_insn} and
-@code{define_expand}, it cannot be used in other expressions (e.g.@: in
-@code{define_insn_and_split}).
-
-@menu
-* Define Subst Example:: Example of @code{define_subst} work.
-* Define Subst Pattern Matching:: Process of template comparison.
-* Define Subst Output Template:: Generation of output template.
-@end menu
-
-@node Define Subst Example
-@subsection @code{define_subst} Example
-@cindex define_subst
-
-To illustrate how @code{define_subst} works, let us examine a simple
-template transformation.
-
-Suppose there are two kinds of instructions: one that touches flags and
-the other that does not. The instructions of the second type could be
-generated with the following @code{define_subst}:
-
-@smallexample
-(define_subst "add_clobber_subst"
- [(set (match_operand:SI 0 "" "")
- (match_operand:SI 1 "" ""))]
- ""
- [(set (match_dup 0)
- (match_dup 1))
- (clobber (reg:CC FLAGS_REG))])
-@end smallexample
-
-This @code{define_subst} can be applied to any RTL pattern containing
-@code{set} of mode SI and generates a copy with clobber when it is
-applied.
-
-Assume there is an RTL template for a @code{max} instruction to be used
-in @code{define_subst} mentioned above:
-
-@smallexample
-(define_insn "maxsi"
- [(set (match_operand:SI 0 "register_operand" "=r")
- (max:SI
- (match_operand:SI 1 "register_operand" "r")
- (match_operand:SI 2 "register_operand" "r")))]
- ""
- "max\t@{%2, %1, %0|%0, %1, %2@}"
- [@dots{}])
-@end smallexample
-
-To mark the RTL template for @code{define_subst} application,
-subst-attributes are used. They should be declared in advance:
-
-@smallexample
-(define_subst_attr "add_clobber_name" "add_clobber_subst" "_noclobber" "_clobber")
-@end smallexample
-
-Here @samp{add_clobber_name} is the attribute name,
-@samp{add_clobber_subst} is the name of the corresponding
-@code{define_subst}, the third argument (@samp{_noclobber}) is the
-attribute value that would be substituted into the unchanged version of
-the source RTL template, and the last argument (@samp{_clobber}) is the
-value that would be substituted into the second, transformed,
-version of the RTL template.
-
-Once the subst-attribute has been defined, it should be used in RTL
-templates which need to be processed by the @code{define_subst}. So,
-the original RTL template should be changed:
-
-@smallexample
-(define_insn "maxsi<add_clobber_name>"
- [(set (match_operand:SI 0 "register_operand" "=r")
- (max:SI
- (match_operand:SI 1 "register_operand" "r")
- (match_operand:SI 2 "register_operand" "r")))]
- ""
- "max\t@{%2, %1, %0|%0, %1, %2@}"
- [@dots{}])
-@end smallexample
-
-The result of the @code{define_subst} usage would look like the following:
-
-@smallexample
-(define_insn "maxsi_noclobber"
- [(set (match_operand:SI 0 "register_operand" "=r")
- (max:SI
- (match_operand:SI 1 "register_operand" "r")
- (match_operand:SI 2 "register_operand" "r")))]
- ""
- "max\t@{%2, %1, %0|%0, %1, %2@}"
- [@dots{}])
-(define_insn "maxsi_clobber"
- [(set (match_operand:SI 0 "register_operand" "=r")
- (max:SI
- (match_operand:SI 1 "register_operand" "r")
- (match_operand:SI 2 "register_operand" "r")))
- (clobber (reg:CC FLAGS_REG))]
- ""
- "max\t@{%2, %1, %0|%0, %1, %2@}"
- [@dots{}])
-@end smallexample
-
-@node Define Subst Pattern Matching
-@subsection Pattern Matching in @code{define_subst}
-@cindex define_subst
-
-All expressions, allowed in @code{define_insn} or @code{define_expand},
-are allowed in the input-template of @code{define_subst}, except
-@code{match_par_dup}, @code{match_scratch}, @code{match_parallel}. The
-meanings of expressions in the input-template were changed:
-
-@code{match_operand} matches any expression (possibly, a subtree in
-RTL-template), if modes of the @code{match_operand} and this expression
-are the same, or mode of the @code{match_operand} is @code{VOIDmode}, or
-this expression is @code{match_dup}, @code{match_op_dup}. If the
-expression is @code{match_operand} too, and predicate of
-@code{match_operand} from the input pattern is not empty, then the
-predicates are compared. That can be used for more accurate filtering
-of accepted RTL-templates.
-
-@code{match_operator} matches common operators (like @code{plus},
-@code{minus}), @code{unspec}, @code{unspec_volatile} operators and
-@code{match_operator}s from the original pattern if the modes match and
-@code{match_operator} from the input pattern has the same number of
-operands as the operator from the original pattern.
-
-@node Define Subst Output Template
-@subsection Generation of output template in @code{define_subst}
-@cindex define_subst
-
-If all necessary checks for @code{define_subst} application pass, a new
-RTL-pattern, based on the output-template, is created to replace the old
-template. Like in input-patterns, meanings of some RTL expressions are
-changed when they are used in output-patterns of a @code{define_subst}.
-Thus, @code{match_dup} is used for copying the whole expression from the
-original pattern, which matched corresponding @code{match_operand} from
-the input pattern.
-
-@code{match_dup N} is used in the output template to be replaced with
-the expression from the original pattern, which matched
-@code{match_operand N} from the input pattern. As a consequence,
-@code{match_dup} cannot be used to point to @code{match_operand}s from
-the output pattern, it should always refer to a @code{match_operand}
-from the input pattern. If a @code{match_dup N} occurs more than once
-in the output template, its first occurrence is replaced with the
-expression from the original pattern, and the subsequent expressions
-are replaced with @code{match_dup N}, i.e., a reference to the first
-expression.
-
-In the output template one can refer to the expressions from the
-original pattern and create new ones. For instance, some operands could
-be added by means of standard @code{match_operand}.
-
-After replacing @code{match_dup} with some RTL-subtree from the original
-pattern, it could happen that several @code{match_operand}s in the
-output pattern have the same indexes. It is unknown, how many and what
-indexes would be used in the expression which would replace
-@code{match_dup}, so such conflicts in indexes are inevitable. To
-overcome this issue, @code{match_operands} and @code{match_operators},
-which were introduced into the output pattern, are renumerated when all
-@code{match_dup}s are replaced.
-
-Number of alternatives in @code{match_operand}s introduced into the
-output template @code{M} could differ from the number of alternatives in
-the original pattern @code{N}, so in the resultant pattern there would
-be @code{N*M} alternatives. Thus, constraints from the original pattern
-would be duplicated @code{N} times, constraints from the output pattern
-would be duplicated @code{M} times, producing all possible combinations.
-@end ifset
-
-@ifset INTERNALS
-@node Constant Definitions
-@section Constant Definitions
-@cindex constant definitions
-@findex define_constants
-
-Using literal constants inside instruction patterns reduces legibility and
-can be a maintenance problem.
-
-To overcome this problem, you may use the @code{define_constants}
-expression. It contains a vector of name-value pairs. From that
-point on, wherever any of the names appears in the MD file, it is as
-if the corresponding value had been written instead. You may use
-@code{define_constants} multiple times; each appearance adds more
-constants to the table. It is an error to redefine a constant with
-a different value.
-
-To come back to the a29k load multiple example, instead of
-
-@smallexample
-(define_insn ""
- [(match_parallel 0 "load_multiple_operation"
- [(set (match_operand:SI 1 "gpc_reg_operand" "=r")
- (match_operand:SI 2 "memory_operand" "m"))
- (use (reg:SI 179))
- (clobber (reg:SI 179))])]
- ""
- "loadm 0,0,%1,%2")
-@end smallexample
-
-You could write:
-
-@smallexample
-(define_constants [
- (R_BP 177)
- (R_FC 178)
- (R_CR 179)
- (R_Q 180)
-])
-
-(define_insn ""
- [(match_parallel 0 "load_multiple_operation"
- [(set (match_operand:SI 1 "gpc_reg_operand" "=r")
- (match_operand:SI 2 "memory_operand" "m"))
- (use (reg:SI R_CR))
- (clobber (reg:SI R_CR))])]
- ""
- "loadm 0,0,%1,%2")
-@end smallexample
-
-The constants that are defined with a define_constant are also output
-in the insn-codes.h header file as #defines.
-
-@cindex enumerations
-@findex define_c_enum
-You can also use the machine description file to define enumerations.
-Like the constants defined by @code{define_constant}, these enumerations
-are visible to both the machine description file and the main C code.
-
-The syntax is as follows:
-
-@smallexample
-(define_c_enum "@var{name}" [
- @var{value0}
- @var{value1}
- (@var{value32} 32)
- @var{value33}
- @dots{}
- @var{valuen}
-])
-@end smallexample
-
-This definition causes the equivalent of the following C code to appear
-in @file{insn-constants.h}:
-
-@smallexample
-enum @var{name} @{
- @var{value0} = 0,
- @var{value1} = 1,
- @var{value32} = 32,
- @var{value33} = 33,
- @dots{}
- @var{valuen} = @var{n}
-@};
-#define NUM_@var{cname}_VALUES (@var{n} + 1)
-@end smallexample
-
-where @var{cname} is the capitalized form of @var{name}.
-It also makes each @var{valuei} available in the machine description
-file, just as if it had been declared with:
-
-@smallexample
-(define_constants [(@var{valuei} @var{i})])
-@end smallexample
-
-Each @var{valuei} is usually an upper-case identifier and usually
-begins with @var{cname}.
-
-You can split the enumeration definition into as many statements as
-you like. The above example is directly equivalent to:
-
-@smallexample
-(define_c_enum "@var{name}" [@var{value0}])
-(define_c_enum "@var{name}" [@var{value1}])
-@dots{}
-(define_c_enum "@var{name}" [@var{valuen}])
-@end smallexample
-
-Splitting the enumeration helps to improve the modularity of each
-individual @code{.md} file. For example, if a port defines its
-synchronization instructions in a separate @file{sync.md} file,
-it is convenient to define all synchronization-specific enumeration
-values in @file{sync.md} rather than in the main @file{.md} file.
-
-Some enumeration names have special significance to GCC:
-
-@table @code
-@item unspecv
-@findex unspec_volatile
-If an enumeration called @code{unspecv} is defined, GCC will use it
-when printing out @code{unspec_volatile} expressions. For example:
-
-@smallexample
-(define_c_enum "unspecv" [
- UNSPECV_BLOCKAGE
-])
-@end smallexample
-
-causes GCC to print @samp{(unspec_volatile @dots{} 0)} as:
-
-@smallexample
-(unspec_volatile ... UNSPECV_BLOCKAGE)
-@end smallexample
-
-@item unspec
-@findex unspec
-If an enumeration called @code{unspec} is defined, GCC will use
-it when printing out @code{unspec} expressions. GCC will also use
-it when printing out @code{unspec_volatile} expressions unless an
-@code{unspecv} enumeration is also defined. You can therefore
-decide whether to keep separate enumerations for volatile and
-non-volatile expressions or whether to use the same enumeration
-for both.
-@end table
-
-@findex define_enum
-@anchor{define_enum}
-Another way of defining an enumeration is to use @code{define_enum}:
-
-@smallexample
-(define_enum "@var{name}" [
- @var{value0}
- @var{value1}
- @dots{}
- @var{valuen}
-])
-@end smallexample
-
-This directive implies:
-
-@smallexample
-(define_c_enum "@var{name}" [
- @var{cname}_@var{cvalue0}
- @var{cname}_@var{cvalue1}
- @dots{}
- @var{cname}_@var{cvaluen}
-])
-@end smallexample
-
-@findex define_enum_attr
-where @var{cvaluei} is the capitalized form of @var{valuei}.
-However, unlike @code{define_c_enum}, the enumerations defined
-by @code{define_enum} can be used in attribute specifications
-(@pxref{define_enum_attr}).
-@end ifset
-@ifset INTERNALS
-@node Iterators
-@section Iterators
-@cindex iterators in @file{.md} files
-
-Ports often need to define similar patterns for more than one machine
-mode or for more than one rtx code. GCC provides some simple iterator
-facilities to make this process easier.
-
-@menu
-* Mode Iterators:: Generating variations of patterns for different modes.
-* Code Iterators:: Doing the same for codes.
-* Int Iterators:: Doing the same for integers.
-* Subst Iterators:: Generating variations of patterns for define_subst.
-* Parameterized Names:: Specifying iterator values in C++ code.
-@end menu
-
-@node Mode Iterators
-@subsection Mode Iterators
-@cindex mode iterators in @file{.md} files
-
-Ports often need to define similar patterns for two or more different modes.
-For example:
-
-@itemize @bullet
-@item
-If a processor has hardware support for both single and double
-floating-point arithmetic, the @code{SFmode} patterns tend to be
-very similar to the @code{DFmode} ones.
-
-@item
-If a port uses @code{SImode} pointers in one configuration and
-@code{DImode} pointers in another, it will usually have very similar
-@code{SImode} and @code{DImode} patterns for manipulating pointers.
-@end itemize
-
-Mode iterators allow several patterns to be instantiated from one
-@file{.md} file template. They can be used with any type of
-rtx-based construct, such as a @code{define_insn},
-@code{define_split}, or @code{define_peephole2}.
-
-@menu
-* Defining Mode Iterators:: Defining a new mode iterator.
-* Substitutions:: Combining mode iterators with substitutions
-* Examples:: Examples
-@end menu
-
-@node Defining Mode Iterators
-@subsubsection Defining Mode Iterators
-@findex define_mode_iterator
-
-The syntax for defining a mode iterator is:
-
-@smallexample
-(define_mode_iterator @var{name} [(@var{mode1} "@var{cond1}") @dots{} (@var{moden} "@var{condn}")])
-@end smallexample
-
-This allows subsequent @file{.md} file constructs to use the mode suffix
-@code{:@var{name}}. Every construct that does so will be expanded
-@var{n} times, once with every use of @code{:@var{name}} replaced by
-@code{:@var{mode1}}, once with every use replaced by @code{:@var{mode2}},
-and so on. In the expansion for a particular @var{modei}, every
-C condition will also require that @var{condi} be true.
-
-For example:
-
-@smallexample
-(define_mode_iterator P [(SI "Pmode == SImode") (DI "Pmode == DImode")])
-@end smallexample
-
-defines a new mode suffix @code{:P}. Every construct that uses
-@code{:P} will be expanded twice, once with every @code{:P} replaced
-by @code{:SI} and once with every @code{:P} replaced by @code{:DI}.
-The @code{:SI} version will only apply if @code{Pmode == SImode} and
-the @code{:DI} version will only apply if @code{Pmode == DImode}.
-
-As with other @file{.md} conditions, an empty string is treated
-as ``always true''. @code{(@var{mode} "")} can also be abbreviated
-to @code{@var{mode}}. For example:
-
-@smallexample
-(define_mode_iterator GPR [SI (DI "TARGET_64BIT")])
-@end smallexample
-
-means that the @code{:DI} expansion only applies if @code{TARGET_64BIT}
-but that the @code{:SI} expansion has no such constraint.
-
-Iterators are applied in the order they are defined. This can be
-significant if two iterators are used in a construct that requires
-substitutions. @xref{Substitutions}.
-
-@node Substitutions
-@subsubsection Substitution in Mode Iterators
-@findex define_mode_attr
-
-If an @file{.md} file construct uses mode iterators, each version of the
-construct will often need slightly different strings or modes. For
-example:
-
-@itemize @bullet
-@item
-When a @code{define_expand} defines several @code{add@var{m}3} patterns
-(@pxref{Standard Names}), each expander will need to use the
-appropriate mode name for @var{m}.
-
-@item
-When a @code{define_insn} defines several instruction patterns,
-each instruction will often use a different assembler mnemonic.
-
-@item
-When a @code{define_insn} requires operands with different modes,
-using an iterator for one of the operand modes usually requires a specific
-mode for the other operand(s).
-@end itemize
-
-GCC supports such variations through a system of ``mode attributes''.
-There are two standard attributes: @code{mode}, which is the name of
-the mode in lower case, and @code{MODE}, which is the same thing in
-upper case. You can define other attributes using:
-
-@smallexample
-(define_mode_attr @var{name} [(@var{mode1} "@var{value1}") @dots{} (@var{moden} "@var{valuen}")])
-@end smallexample
-
-where @var{name} is the name of the attribute and @var{valuei}
-is the value associated with @var{modei}.
-
-When GCC replaces some @var{:iterator} with @var{:mode}, it will scan
-each string and mode in the pattern for sequences of the form
-@code{<@var{iterator}:@var{attr}>}, where @var{attr} is the name of a
-mode attribute. If the attribute is defined for @var{mode}, the whole
-@code{<@dots{}>} sequence will be replaced by the appropriate attribute
-value.
-
-For example, suppose an @file{.md} file has:
-
-@smallexample
-(define_mode_iterator P [(SI "Pmode == SImode") (DI "Pmode == DImode")])
-(define_mode_attr load [(SI "lw") (DI "ld")])
-@end smallexample
-
-If one of the patterns that uses @code{:P} contains the string
-@code{"<P:load>\t%0,%1"}, the @code{SI} version of that pattern
-will use @code{"lw\t%0,%1"} and the @code{DI} version will use
-@code{"ld\t%0,%1"}.
-
-Here is an example of using an attribute for a mode:
-
-@smallexample
-(define_mode_iterator LONG [SI DI])
-(define_mode_attr SHORT [(SI "HI") (DI "SI")])
-(define_insn @dots{}
- (sign_extend:LONG (match_operand:<LONG:SHORT> @dots{})) @dots{})
-@end smallexample
-
-The @code{@var{iterator}:} prefix may be omitted, in which case the
-substitution will be attempted for every iterator expansion.
-
-@node Examples
-@subsubsection Mode Iterator Examples
-
-Here is an example from the MIPS port. It defines the following
-modes and attributes (among others):
-
-@smallexample
-(define_mode_iterator GPR [SI (DI "TARGET_64BIT")])
-(define_mode_attr d [(SI "") (DI "d")])
-@end smallexample
-
-and uses the following template to define both @code{subsi3}
-and @code{subdi3}:
-
-@smallexample
-(define_insn "sub<mode>3"
- [(set (match_operand:GPR 0 "register_operand" "=d")
- (minus:GPR (match_operand:GPR 1 "register_operand" "d")
- (match_operand:GPR 2 "register_operand" "d")))]
- ""
- "<d>subu\t%0,%1,%2"
- [(set_attr "type" "arith")
- (set_attr "mode" "<MODE>")])
-@end smallexample
-
-This is exactly equivalent to:
-
-@smallexample
-(define_insn "subsi3"
- [(set (match_operand:SI 0 "register_operand" "=d")
- (minus:SI (match_operand:SI 1 "register_operand" "d")
- (match_operand:SI 2 "register_operand" "d")))]
- ""
- "subu\t%0,%1,%2"
- [(set_attr "type" "arith")
- (set_attr "mode" "SI")])
-
-(define_insn "subdi3"
- [(set (match_operand:DI 0 "register_operand" "=d")
- (minus:DI (match_operand:DI 1 "register_operand" "d")
- (match_operand:DI 2 "register_operand" "d")))]
- "TARGET_64BIT"
- "dsubu\t%0,%1,%2"
- [(set_attr "type" "arith")
- (set_attr "mode" "DI")])
-@end smallexample
-
-@node Code Iterators
-@subsection Code Iterators
-@cindex code iterators in @file{.md} files
-@findex define_code_iterator
-@findex define_code_attr
-
-Code iterators operate in a similar way to mode iterators. @xref{Mode Iterators}.
-
-The construct:
-
-@smallexample
-(define_code_iterator @var{name} [(@var{code1} "@var{cond1}") @dots{} (@var{coden} "@var{condn}")])
-@end smallexample
-
-defines a pseudo rtx code @var{name} that can be instantiated as
-@var{codei} if condition @var{condi} is true. Each @var{codei}
-must have the same rtx format. @xref{RTL Classes}.
-
-As with mode iterators, each pattern that uses @var{name} will be
-expanded @var{n} times, once with all uses of @var{name} replaced by
-@var{code1}, once with all uses replaced by @var{code2}, and so on.
-@xref{Defining Mode Iterators}.
-
-It is possible to define attributes for codes as well as for modes.
-There are two standard code attributes: @code{code}, the name of the
-code in lower case, and @code{CODE}, the name of the code in upper case.
-Other attributes are defined using:
-
-@smallexample
-(define_code_attr @var{name} [(@var{code1} "@var{value1}") @dots{} (@var{coden} "@var{valuen}")])
-@end smallexample
-
-Instruction patterns can use code attributes as rtx codes, which can be
-useful if two sets of codes act in tandem. For example, the following
-@code{define_insn} defines two patterns, one calculating a signed absolute
-difference and another calculating an unsigned absolute difference:
-
-@smallexample
-(define_code_iterator any_max [smax umax])
-(define_code_attr paired_min [(smax "smin") (umax "umin")])
-(define_insn @dots{}
- [(set (match_operand:SI 0 @dots{})
- (minus:SI (any_max:SI (match_operand:SI 1 @dots{})
- (match_operand:SI 2 @dots{}))
- (<paired_min>:SI (match_dup 1) (match_dup 2))))]
- @dots{})
-@end smallexample
-
-The signed version of the instruction uses @code{smax} and @code{smin}
-while the unsigned version uses @code{umax} and @code{umin}. There
-are no versions that pair @code{smax} with @code{umin} or @code{umax}
-with @code{smin}.
-
-Here's an example of code iterators in action, taken from the MIPS port:
-
-@smallexample
-(define_code_iterator any_cond [unordered ordered unlt unge uneq ltgt unle ungt
- eq ne gt ge lt le gtu geu ltu leu])
-
-(define_expand "b<code>"
- [(set (pc)
- (if_then_else (any_cond:CC (cc0)
- (const_int 0))
- (label_ref (match_operand 0 ""))
- (pc)))]
- ""
-@{
- gen_conditional_branch (operands, <CODE>);
- DONE;
-@})
-@end smallexample
-
-This is equivalent to:
-
-@smallexample
-(define_expand "bunordered"
- [(set (pc)
- (if_then_else (unordered:CC (cc0)
- (const_int 0))
- (label_ref (match_operand 0 ""))
- (pc)))]
- ""
-@{
- gen_conditional_branch (operands, UNORDERED);
- DONE;
-@})
-
-(define_expand "bordered"
- [(set (pc)
- (if_then_else (ordered:CC (cc0)
- (const_int 0))
- (label_ref (match_operand 0 ""))
- (pc)))]
- ""
-@{
- gen_conditional_branch (operands, ORDERED);
- DONE;
-@})
-
-@dots{}
-@end smallexample
-
-@node Int Iterators
-@subsection Int Iterators
-@cindex int iterators in @file{.md} files
-@findex define_int_iterator
-@findex define_int_attr
-
-Int iterators operate in a similar way to code iterators. @xref{Code Iterators}.
-
-The construct:
-
-@smallexample
-(define_int_iterator @var{name} [(@var{int1} "@var{cond1}") @dots{} (@var{intn} "@var{condn}")])
-@end smallexample
-
-defines a pseudo integer constant @var{name} that can be instantiated as
-@var{inti} if condition @var{condi} is true. Each @var{int} must have the
-same rtx format. @xref{RTL Classes}. Int iterators can appear in only
-those rtx fields that have 'i', 'n', 'w', or 'p' as the specifier. This
-means that each @var{int} has to be a constant defined using define_constant
-or define_c_enum.
-
-As with mode and code iterators, each pattern that uses @var{name} will be
-expanded @var{n} times, once with all uses of @var{name} replaced by
-@var{int1}, once with all uses replaced by @var{int2}, and so on.
-@xref{Defining Mode Iterators}.
-
-It is possible to define attributes for ints as well as for codes and modes.
-Attributes are defined using:
-
-@smallexample
-(define_int_attr @var{name} [(@var{int1} "@var{value1}") @dots{} (@var{intn} "@var{valuen}")])
-@end smallexample
-
-Here's an example of int iterators in action, taken from the ARM port:
-
-@smallexample
-(define_int_iterator QABSNEG [UNSPEC_VQABS UNSPEC_VQNEG])
-
-(define_int_attr absneg [(UNSPEC_VQABS "abs") (UNSPEC_VQNEG "neg")])
-
-(define_insn "neon_vq<absneg><mode>"
- [(set (match_operand:VDQIW 0 "s_register_operand" "=w")
- (unspec:VDQIW [(match_operand:VDQIW 1 "s_register_operand" "w")
- (match_operand:SI 2 "immediate_operand" "i")]
- QABSNEG))]
- "TARGET_NEON"
- "vq<absneg>.<V_s_elem>\t%<V_reg>0, %<V_reg>1"
- [(set_attr "type" "neon_vqneg_vqabs")]
-)
-
-@end smallexample
-
-This is equivalent to:
-
-@smallexample
-(define_insn "neon_vqabs<mode>"
- [(set (match_operand:VDQIW 0 "s_register_operand" "=w")
- (unspec:VDQIW [(match_operand:VDQIW 1 "s_register_operand" "w")
- (match_operand:SI 2 "immediate_operand" "i")]
- UNSPEC_VQABS))]
- "TARGET_NEON"
- "vqabs.<V_s_elem>\t%<V_reg>0, %<V_reg>1"
- [(set_attr "type" "neon_vqneg_vqabs")]
-)
-
-(define_insn "neon_vqneg<mode>"
- [(set (match_operand:VDQIW 0 "s_register_operand" "=w")
- (unspec:VDQIW [(match_operand:VDQIW 1 "s_register_operand" "w")
- (match_operand:SI 2 "immediate_operand" "i")]
- UNSPEC_VQNEG))]
- "TARGET_NEON"
- "vqneg.<V_s_elem>\t%<V_reg>0, %<V_reg>1"
- [(set_attr "type" "neon_vqneg_vqabs")]
-)
-
-@end smallexample
-
-@node Subst Iterators
-@subsection Subst Iterators
-@cindex subst iterators in @file{.md} files
-@findex define_subst
-@findex define_subst_attr
-
-Subst iterators are special type of iterators with the following
-restrictions: they could not be declared explicitly, they always have
-only two values, and they do not have explicit dedicated name.
-Subst-iterators are triggered only when corresponding subst-attribute is
-used in RTL-pattern.
-
-Subst iterators transform templates in the following way: the templates
-are duplicated, the subst-attributes in these templates are replaced
-with the corresponding values, and a new attribute is implicitly added
-to the given @code{define_insn}/@code{define_expand}. The name of the
-added attribute matches the name of @code{define_subst}. Such
-attributes are declared implicitly, and it is not allowed to have a
-@code{define_attr} named as a @code{define_subst}.
-
-Each subst iterator is linked to a @code{define_subst}. It is declared
-implicitly by the first appearance of the corresponding
-@code{define_subst_attr}, and it is not allowed to define it explicitly.
-
-Declarations of subst-attributes have the following syntax:
-
-@findex define_subst_attr
-@smallexample
-(define_subst_attr "@var{name}"
- "@var{subst-name}"
- "@var{no-subst-value}"
- "@var{subst-applied-value}")
-@end smallexample
-
-@var{name} is a string with which the given subst-attribute could be
-referred to.
-
-@var{subst-name} shows which @code{define_subst} should be applied to an
-RTL-template if the given subst-attribute is present in the
-RTL-template.
-
-@var{no-subst-value} is a value with which subst-attribute would be
-replaced in the first copy of the original RTL-template.
-
-@var{subst-applied-value} is a value with which subst-attribute would be
-replaced in the second copy of the original RTL-template.
-
-@node Parameterized Names
-@subsection Parameterized Names
-@cindex @samp{@@} in instruction pattern names
-Ports sometimes need to apply iterators using C++ code, in order to
-get the code or RTL pattern for a specific instruction. For example,
-suppose we have the @samp{neon_vq<absneg><mode>} pattern given above:
-
-@smallexample
-(define_int_iterator QABSNEG [UNSPEC_VQABS UNSPEC_VQNEG])
-
-(define_int_attr absneg [(UNSPEC_VQABS "abs") (UNSPEC_VQNEG "neg")])
-
-(define_insn "neon_vq<absneg><mode>"
- [(set (match_operand:VDQIW 0 "s_register_operand" "=w")
- (unspec:VDQIW [(match_operand:VDQIW 1 "s_register_operand" "w")
- (match_operand:SI 2 "immediate_operand" "i")]
- QABSNEG))]
- @dots{}
-)
-@end smallexample
-
-A port might need to generate this pattern for a variable
-@samp{QABSNEG} value and a variable @samp{VDQIW} mode. There are two
-ways of doing this. The first is to build the rtx for the pattern
-directly from C++ code; this is a valid technique and avoids any risk
-of combinatorial explosion. The second is to prefix the instruction
-name with the special character @samp{@@}, which tells GCC to generate
-the four additional functions below. In each case, @var{name} is the
-name of the instruction without the leading @samp{@@} character,
-without the @samp{<@dots{}>} placeholders, and with any underscore
-before a @samp{<@dots{}>} placeholder removed if keeping it would
-lead to a double or trailing underscore.
-
-@table @samp
-@item insn_code maybe_code_for_@var{name} (@var{i1}, @var{i2}, @dots{})
-See whether replacing the first @samp{<@dots{}>} placeholder with
-iterator value @var{i1}, the second with iterator value @var{i2}, and
-so on, gives a valid instruction. Return its code if so, otherwise
-return @code{CODE_FOR_nothing}.
-
-@item insn_code code_for_@var{name} (@var{i1}, @var{i2}, @dots{})
-Same, but abort the compiler if the requested instruction does not exist.
-
-@item rtx maybe_gen_@var{name} (@var{i1}, @var{i2}, @dots{}, @var{op0}, @var{op1}, @dots{})
-Check for a valid instruction in the same way as
-@code{maybe_code_for_@var{name}}. If the instruction exists,
-generate an instance of it using the operand values given by @var{op0},
-@var{op1}, and so on, otherwise return null.
-
-@item rtx gen_@var{name} (@var{i1}, @var{i2}, @dots{}, @var{op0}, @var{op1}, @dots{})
-Same, but abort the compiler if the requested instruction does not exist,
-or if the instruction generator invoked the @code{FAIL} macro.
-@end table
-
-For example, changing the pattern above to:
-
-@smallexample
-(define_insn "@@neon_vq<absneg><mode>"
- [(set (match_operand:VDQIW 0 "s_register_operand" "=w")
- (unspec:VDQIW [(match_operand:VDQIW 1 "s_register_operand" "w")
- (match_operand:SI 2 "immediate_operand" "i")]
- QABSNEG))]
- @dots{}
-)
-@end smallexample
-
-would define the same patterns as before, but in addition would generate
-the four functions below:
-
-@smallexample
-insn_code maybe_code_for_neon_vq (int, machine_mode);
-insn_code code_for_neon_vq (int, machine_mode);
-rtx maybe_gen_neon_vq (int, machine_mode, rtx, rtx, rtx);
-rtx gen_neon_vq (int, machine_mode, rtx, rtx, rtx);
-@end smallexample
-
-Calling @samp{code_for_neon_vq (UNSPEC_VQABS, V8QImode)}
-would then give @code{CODE_FOR_neon_vqabsv8qi}.
-
-It is possible to have multiple @samp{@@} patterns with the same
-name and same types of iterator. For example:
-
-@smallexample
-(define_insn "@@some_arithmetic_op<mode>"
- [(set (match_operand:INTEGER_MODES 0 "register_operand") @dots{})]
- @dots{}
-)
-
-(define_insn "@@some_arithmetic_op<mode>"
- [(set (match_operand:FLOAT_MODES 0 "register_operand") @dots{})]
- @dots{}
-)
-@end smallexample
-
-would produce a single set of functions that handles both
-@code{INTEGER_MODES} and @code{FLOAT_MODES}.
-
-It is also possible for these @samp{@@} patterns to have different
-numbers of operands from each other. For example, patterns with
-a binary rtl code might take three operands (one output and two inputs)
-while patterns with a ternary rtl code might take four operands (one
-output and three inputs). This combination would produce separate
-@samp{maybe_gen_@var{name}} and @samp{gen_@var{name}} functions for
-each operand count, but it would still produce a single
-@samp{maybe_code_for_@var{name}} and a single @samp{code_for_@var{name}}.
-
-@end ifset
+++ /dev/null
-@c Copyright (C) 1988-2022 Free Software Foundation, Inc.
-@c This is part of the GCC manual.
-@c For copying conditions, see the file gcc.texi.
-
-@node Objective-C
-@comment node-name, next, previous, up
-
-@chapter GNU Objective-C Features
-
-This document is meant to describe some of the GNU Objective-C
-features. It is not intended to teach you Objective-C. There are
-several resources on the Internet that present the language.
-
-@menu
-* GNU Objective-C runtime API::
-* Executing code before main::
-* Type encoding::
-* Garbage Collection::
-* Constant string objects::
-* compatibility_alias::
-* Exceptions::
-* Synchronization::
-* Fast enumeration::
-* Messaging with the GNU Objective-C runtime::
-@end menu
-
-@c =========================================================================
-@node GNU Objective-C runtime API
-@section GNU Objective-C Runtime API
-
-This section is specific for the GNU Objective-C runtime. If you are
-using a different runtime, you can skip it.
-
-The GNU Objective-C runtime provides an API that allows you to
-interact with the Objective-C runtime system, querying the live
-runtime structures and even manipulating them. This allows you for
-example to inspect and navigate classes, methods and protocols; to
-define new classes or new methods, and even to modify existing classes
-or protocols.
-
-If you are using a ``Foundation'' library such as GNUstep-Base, this
-library will provide you with a rich set of functionality to do most
-of the inspection tasks, and you probably will only need direct access
-to the GNU Objective-C runtime API to define new classes or methods.
-
-@menu
-* Modern GNU Objective-C runtime API::
-* Traditional GNU Objective-C runtime API::
-@end menu
-
-@c =========================================================================
-@node Modern GNU Objective-C runtime API
-@subsection Modern GNU Objective-C Runtime API
-
-The GNU Objective-C runtime provides an API which is similar to the
-one provided by the ``Objective-C 2.0'' Apple/NeXT Objective-C
-runtime. The API is documented in the public header files of the GNU
-Objective-C runtime:
-
-@itemize @bullet
-
-@item
-@file{objc/objc.h}: this is the basic Objective-C header file,
-defining the basic Objective-C types such as @code{id}, @code{Class}
-and @code{BOOL}. You have to include this header to do almost
-anything with Objective-C.
-
-@item
-@file{objc/runtime.h}: this header declares most of the public runtime
-API functions allowing you to inspect and manipulate the Objective-C
-runtime data structures. These functions are fairly standardized
-across Objective-C runtimes and are almost identical to the Apple/NeXT
-Objective-C runtime ones. It does not declare functions in some
-specialized areas (constructing and forwarding message invocations,
-threading) which are in the other headers below. You have to include
-@file{objc/objc.h} and @file{objc/runtime.h} to use any of the
-functions, such as @code{class_getName()}, declared in
-@file{objc/runtime.h}.
-
-@item
-@file{objc/message.h}: this header declares public functions used to
-construct, deconstruct and forward message invocations. Because
-messaging is done in quite a different way on different runtimes,
-functions in this header are specific to the GNU Objective-C runtime
-implementation.
-
-@item
-@file{objc/objc-exception.h}: this header declares some public
-functions related to Objective-C exceptions. For example functions in
-this header allow you to throw an Objective-C exception from plain
-C/C++ code.
-
-@item
-@file{objc/objc-sync.h}: this header declares some public functions
-related to the Objective-C @code{@@synchronized()} syntax, allowing
-you to emulate an Objective-C @code{@@synchronized()} block in plain
-C/C++ code.
-
-@item
-@file{objc/thr.h}: this header declares a public runtime API threading
-layer that is only provided by the GNU Objective-C runtime. It
-declares functions such as @code{objc_mutex_lock()}, which provide a
-platform-independent set of threading functions.
-
-@end itemize
-
-The header files contain detailed documentation for each function in
-the GNU Objective-C runtime API.
-
-@c =========================================================================
-@node Traditional GNU Objective-C runtime API
-@subsection Traditional GNU Objective-C Runtime API
-
-The GNU Objective-C runtime used to provide a different API, which we
-call the ``traditional'' GNU Objective-C runtime API. Functions
-belonging to this API are easy to recognize because they use a
-different naming convention, such as @code{class_get_super_class()}
-(traditional API) instead of @code{class_getSuperclass()} (modern
-API). Software using this API includes the file
-@file{objc/objc-api.h} where it is declared.
-
-Starting with GCC 4.7.0, the traditional GNU runtime API is no longer
-available.
-
-@c =========================================================================
-@node Executing code before main
-@section @code{+load}: Executing Code before @code{main}
-
-This section is specific for the GNU Objective-C runtime. If you are
-using a different runtime, you can skip it.
-
-The GNU Objective-C runtime provides a way that allows you to execute
-code before the execution of the program enters the @code{main}
-function. The code is executed on a per-class and a per-category basis,
-through a special class method @code{+load}.
-
-This facility is very useful if you want to initialize global variables
-which can be accessed by the program directly, without sending a message
-to the class first. The usual way to initialize global variables, in the
-@code{+initialize} method, might not be useful because
-@code{+initialize} is only called when the first message is sent to a
-class object, which in some cases could be too late.
-
-Suppose for example you have a @code{FileStream} class that declares
-@code{Stdin}, @code{Stdout} and @code{Stderr} as global variables, like
-below:
-
-@smallexample
-
-FileStream *Stdin = nil;
-FileStream *Stdout = nil;
-FileStream *Stderr = nil;
-
-@@implementation FileStream
-
-+ (void)initialize
-@{
- Stdin = [[FileStream new] initWithFd:0];
- Stdout = [[FileStream new] initWithFd:1];
- Stderr = [[FileStream new] initWithFd:2];
-@}
-
-/* @r{Other methods here} */
-@@end
-
-@end smallexample
-
-In this example, the initialization of @code{Stdin}, @code{Stdout} and
-@code{Stderr} in @code{+initialize} occurs too late. The programmer can
-send a message to one of these objects before the variables are actually
-initialized, thus sending messages to the @code{nil} object. The
-@code{+initialize} method which actually initializes the global
-variables is not invoked until the first message is sent to the class
-object. The solution would require these variables to be initialized
-just before entering @code{main}.
-
-The correct solution of the above problem is to use the @code{+load}
-method instead of @code{+initialize}:
-
-@smallexample
-
-@@implementation FileStream
-
-+ (void)load
-@{
- Stdin = [[FileStream new] initWithFd:0];
- Stdout = [[FileStream new] initWithFd:1];
- Stderr = [[FileStream new] initWithFd:2];
-@}
-
-/* @r{Other methods here} */
-@@end
-
-@end smallexample
-
-The @code{+load} is a method that is not overridden by categories. If a
-class and a category of it both implement @code{+load}, both methods are
-invoked. This allows some additional initializations to be performed in
-a category.
-
-This mechanism is not intended to be a replacement for @code{+initialize}.
-You should be aware of its limitations when you decide to use it
-instead of @code{+initialize}.
-
-@menu
-* What you can and what you cannot do in +load::
-@end menu
-
-
-@node What you can and what you cannot do in +load
-@subsection What You Can and Cannot Do in @code{+load}
-
-@code{+load} is to be used only as a last resort. Because it is
-executed very early, most of the Objective-C runtime machinery will
-not be ready when @code{+load} is executed; hence @code{+load} works
-best for executing C code that is independent on the Objective-C
-runtime.
-
-The @code{+load} implementation in the GNU runtime guarantees you the
-following things:
-
-@itemize @bullet
-
-@item
-you can write whatever C code you like;
-
-@item
-you can allocate and send messages to objects whose class is implemented
-in the same file;
-
-@item
-the @code{+load} implementation of all super classes of a class are
-executed before the @code{+load} of that class is executed;
-
-@item
-the @code{+load} implementation of a class is executed before the
-@code{+load} implementation of any category.
-
-@end itemize
-
-In particular, the following things, even if they can work in a
-particular case, are not guaranteed:
-
-@itemize @bullet
-
-@item
-allocation of or sending messages to arbitrary objects;
-
-@item
-allocation of or sending messages to objects whose classes have a
-category implemented in the same file;
-
-@item
-sending messages to Objective-C constant strings (@code{@@"this is a
-constant string"});
-
-@end itemize
-
-You should make no assumptions about receiving @code{+load} in sibling
-classes when you write @code{+load} of a class. The order in which
-sibling classes receive @code{+load} is not guaranteed.
-
-The order in which @code{+load} and @code{+initialize} are called could
-be problematic if this matters. If you don't allocate objects inside
-@code{+load}, it is guaranteed that @code{+load} is called before
-@code{+initialize}. If you create an object inside @code{+load} the
-@code{+initialize} method of object's class is invoked even if
-@code{+load} was not invoked. Note if you explicitly call @code{+load}
-on a class, @code{+initialize} will be called first. To avoid possible
-problems try to implement only one of these methods.
-
-The @code{+load} method is also invoked when a bundle is dynamically
-loaded into your running program. This happens automatically without any
-intervening operation from you. When you write bundles and you need to
-write @code{+load} you can safely create and send messages to objects whose
-classes already exist in the running program. The same restrictions as
-above apply to classes defined in bundle.
-
-
-
-@node Type encoding
-@section Type Encoding
-
-This is an advanced section. Type encodings are used extensively by
-the compiler and by the runtime, but you generally do not need to know
-about them to use Objective-C.
-
-The Objective-C compiler generates type encodings for all the types.
-These type encodings are used at runtime to find out information about
-selectors and methods and about objects and classes.
-
-The types are encoded in the following way:
-
-@c @sp 1
-
-@multitable @columnfractions .25 .75
-@item @code{_Bool}
-@tab @code{B}
-@item @code{char}
-@tab @code{c}
-@item @code{unsigned char}
-@tab @code{C}
-@item @code{short}
-@tab @code{s}
-@item @code{unsigned short}
-@tab @code{S}
-@item @code{int}
-@tab @code{i}
-@item @code{unsigned int}
-@tab @code{I}
-@item @code{long}
-@tab @code{l}
-@item @code{unsigned long}
-@tab @code{L}
-@item @code{long long}
-@tab @code{q}
-@item @code{unsigned long long}
-@tab @code{Q}
-@item @code{float}
-@tab @code{f}
-@item @code{double}
-@tab @code{d}
-@item @code{long double}
-@tab @code{D}
-@item @code{void}
-@tab @code{v}
-@item @code{id}
-@tab @code{@@}
-@item @code{Class}
-@tab @code{#}
-@item @code{SEL}
-@tab @code{:}
-@item @code{char*}
-@tab @code{*}
-@item @code{enum}
-@tab an @code{enum} is encoded exactly as the integer type that the compiler uses for it, which depends on the enumeration
-values. Often the compiler users @code{unsigned int}, which is then encoded as @code{I}.
-@item unknown type
-@tab @code{?}
-@item Complex types
-@tab @code{j} followed by the inner type. For example @code{_Complex double} is encoded as "jd".
-@item bit-fields
-@tab @code{b} followed by the starting position of the bit-field, the type of the bit-field and the size of the bit-field (the bit-fields encoding was changed from the NeXT's compiler encoding, see below)
-@end multitable
-
-@c @sp 1
-
-The encoding of bit-fields has changed to allow bit-fields to be
-properly handled by the runtime functions that compute sizes and
-alignments of types that contain bit-fields. The previous encoding
-contained only the size of the bit-field. Using only this information
-it is not possible to reliably compute the size occupied by the
-bit-field. This is very important in the presence of the Boehm's
-garbage collector because the objects are allocated using the typed
-memory facility available in this collector. The typed memory
-allocation requires information about where the pointers are located
-inside the object.
-
-The position in the bit-field is the position, counting in bits, of the
-bit closest to the beginning of the structure.
-
-The non-atomic types are encoded as follows:
-
-@c @sp 1
-
-@multitable @columnfractions .2 .8
-@item pointers
-@tab @samp{^} followed by the pointed type.
-@item arrays
-@tab @samp{[} followed by the number of elements in the array followed by the type of the elements followed by @samp{]}
-@item structures
-@tab @samp{@{} followed by the name of the structure (or @samp{?} if the structure is unnamed), the @samp{=} sign, the type of the members and by @samp{@}}
-@item unions
-@tab @samp{(} followed by the name of the structure (or @samp{?} if the union is unnamed), the @samp{=} sign, the type of the members followed by @samp{)}
-@item vectors
-@tab @samp{![} followed by the vector_size (the number of bytes composing the vector) followed by a comma, followed by the alignment (in bytes) of the vector, followed by the type of the elements followed by @samp{]}
-@end multitable
-
-Here are some types and their encodings, as they are generated by the
-compiler on an i386 machine:
-
-@sp 1
-
-@multitable @columnfractions .60 .40
-@headitem Objective-C type
-@tab Compiler encoding
-@item
-@smallexample
-int a[10];
-@end smallexample
-@tab @code{[10i]}
-@item
-@smallexample
-struct @{
- int i;
- float f[3];
- int a:3;
- int b:2;
- char c;
-@}
-@end smallexample
-@tab @code{@{?=i[3f]b128i3b131i2c@}}
-@item
-@smallexample
-int a __attribute__ ((vector_size (16)));
-@end smallexample
-@tab @code{![16,16i]} (alignment depends on the machine)
-@end multitable
-
-@sp 1
-
-In addition to the types the compiler also encodes the type
-specifiers. The table below describes the encoding of the current
-Objective-C type specifiers:
-
-@sp 1
-
-@multitable @columnfractions .25 .75
-@headitem Specifier
-@tab Encoding
-@item @code{const}
-@tab @code{r}
-@item @code{in}
-@tab @code{n}
-@item @code{inout}
-@tab @code{N}
-@item @code{out}
-@tab @code{o}
-@item @code{bycopy}
-@tab @code{O}
-@item @code{byref}
-@tab @code{R}
-@item @code{oneway}
-@tab @code{V}
-@end multitable
-
-@sp 1
-
-The type specifiers are encoded just before the type. Unlike types
-however, the type specifiers are only encoded when they appear in method
-argument types.
-
-Note how @code{const} interacts with pointers:
-
-@sp 1
-
-@multitable @columnfractions .25 .75
-@headitem Objective-C type
-@tab Compiler encoding
-@item
-@smallexample
-const int
-@end smallexample
-@tab @code{ri}
-@item
-@smallexample
-const int*
-@end smallexample
-@tab @code{^ri}
-@item
-@smallexample
-int *const
-@end smallexample
-@tab @code{r^i}
-@end multitable
-
-@sp 1
-
-@code{const int*} is a pointer to a @code{const int}, and so is
-encoded as @code{^ri}. @code{int* const}, instead, is a @code{const}
-pointer to an @code{int}, and so is encoded as @code{r^i}.
-
-Finally, there is a complication when encoding @code{const char *}
-versus @code{char * const}. Because @code{char *} is encoded as
-@code{*} and not as @code{^c}, there is no way to express the fact
-that @code{r} applies to the pointer or to the pointee.
-
-Hence, it is assumed as a convention that @code{r*} means @code{const
-char *} (since it is what is most often meant), and there is no way to
-encode @code{char *const}. @code{char *const} would simply be encoded
-as @code{*}, and the @code{const} is lost.
-
-@menu
-* Legacy type encoding::
-* @@encode::
-* Method signatures::
-@end menu
-
-@node Legacy type encoding
-@subsection Legacy Type Encoding
-
-Unfortunately, historically GCC used to have a number of bugs in its
-encoding code. The NeXT runtime expects GCC to emit type encodings in
-this historical format (compatible with GCC-3.3), so when using the
-NeXT runtime, GCC will introduce on purpose a number of incorrect
-encodings:
-
-@itemize @bullet
-
-@item
-the read-only qualifier of the pointee gets emitted before the '^'.
-The read-only qualifier of the pointer itself gets ignored, unless it
-is a typedef. Also, the 'r' is only emitted for the outermost type.
-
-@item
-32-bit longs are encoded as 'l' or 'L', but not always. For typedefs,
-the compiler uses 'i' or 'I' instead if encoding a struct field or a
-pointer.
-
-@item
-@code{enum}s are always encoded as 'i' (int) even if they are actually
-unsigned or long.
-
-@end itemize
-
-In addition to that, the NeXT runtime uses a different encoding for
-bitfields. It encodes them as @code{b} followed by the size, without
-a bit offset or the underlying field type.
-
-@node @@encode
-@subsection @code{@@encode}
-
-GNU Objective-C supports the @code{@@encode} syntax that allows you to
-create a type encoding from a C/Objective-C type. For example,
-@code{@@encode(int)} is compiled by the compiler into @code{"i"}.
-
-@code{@@encode} does not support type qualifiers other than
-@code{const}. For example, @code{@@encode(const char*)} is valid and
-is compiled into @code{"r*"}, while @code{@@encode(bycopy char *)} is
-invalid and will cause a compilation error.
-
-@node Method signatures
-@subsection Method Signatures
-
-This section documents the encoding of method types, which is rarely
-needed to use Objective-C. You should skip it at a first reading; the
-runtime provides functions that will work on methods and can walk
-through the list of parameters and interpret them for you. These
-functions are part of the public ``API'' and are the preferred way to
-interact with method signatures from user code.
-
-But if you need to debug a problem with method signatures and need to
-know how they are implemented (i.e., the ``ABI''), read on.
-
-Methods have their ``signature'' encoded and made available to the
-runtime. The ``signature'' encodes all the information required to
-dynamically build invocations of the method at runtime: return type
-and arguments.
-
-The ``signature'' is a null-terminated string, composed of the following:
-
-@itemize @bullet
-
-@item
-The return type, including type qualifiers. For example, a method
-returning @code{int} would have @code{i} here.
-
-@item
-The total size (in bytes) required to pass all the parameters. This
-includes the two hidden parameters (the object @code{self} and the
-method selector @code{_cmd}).
-
-@item
-Each argument, with the type encoding, followed by the offset (in
-bytes) of the argument in the list of parameters.
-
-@end itemize
-
-For example, a method with no arguments and returning @code{int} would
-have the signature @code{i8@@0:4} if the size of a pointer is 4. The
-signature is interpreted as follows: the @code{i} is the return type
-(an @code{int}), the @code{8} is the total size of the parameters in
-bytes (two pointers each of size 4), the @code{@@0} is the first
-parameter (an object at byte offset @code{0}) and @code{:4} is the
-second parameter (a @code{SEL} at byte offset @code{4}).
-
-You can easily find more examples by running the ``strings'' program
-on an Objective-C object file compiled by GCC. You'll see a lot of
-strings that look very much like @code{i8@@0:4}. They are signatures
-of Objective-C methods.
-
-
-@node Garbage Collection
-@section Garbage Collection
-
-This section is specific for the GNU Objective-C runtime. If you are
-using a different runtime, you can skip it.
-
-Support for garbage collection with the GNU runtime has been added by
-using a powerful conservative garbage collector, known as the
-Boehm-Demers-Weiser conservative garbage collector.
-
-To enable the support for it you have to configure the compiler using
-an additional argument, @w{@option{--enable-objc-gc}}. This will
-build the boehm-gc library, and build an additional runtime library
-which has several enhancements to support the garbage collector. The
-new library has a new name, @file{libobjc_gc.a} to not conflict with
-the non-garbage-collected library.
-
-When the garbage collector is used, the objects are allocated using the
-so-called typed memory allocation mechanism available in the
-Boehm-Demers-Weiser collector. This mode requires precise information on
-where pointers are located inside objects. This information is computed
-once per class, immediately after the class has been initialized.
-
-There is a new runtime function @code{class_ivar_set_gcinvisible()}
-which can be used to declare a so-called @dfn{weak pointer}
-reference. Such a pointer is basically hidden for the garbage collector;
-this can be useful in certain situations, especially when you want to
-keep track of the allocated objects, yet allow them to be
-collected. This kind of pointers can only be members of objects, you
-cannot declare a global pointer as a weak reference. Every type which is
-a pointer type can be declared a weak pointer, including @code{id},
-@code{Class} and @code{SEL}.
-
-Here is an example of how to use this feature. Suppose you want to
-implement a class whose instances hold a weak pointer reference; the
-following class does this:
-
-@smallexample
-
-@@interface WeakPointer : Object
-@{
- const void* weakPointer;
-@}
-
-- initWithPointer:(const void*)p;
-- (const void*)weakPointer;
-@@end
-
-
-@@implementation WeakPointer
-
-+ (void)initialize
-@{
- if (self == objc_lookUpClass ("WeakPointer"))
- class_ivar_set_gcinvisible (self, "weakPointer", YES);
-@}
-
-- initWithPointer:(const void*)p
-@{
- weakPointer = p;
- return self;
-@}
-
-- (const void*)weakPointer
-@{
- return weakPointer;
-@}
-
-@@end
-
-@end smallexample
-
-Weak pointers are supported through a new type character specifier
-represented by the @samp{!} character. The
-@code{class_ivar_set_gcinvisible()} function adds or removes this
-specifier to the string type description of the instance variable named
-as argument.
-
-@c =========================================================================
-@node Constant string objects
-@section Constant String Objects
-
-GNU Objective-C provides constant string objects that are generated
-directly by the compiler. You declare a constant string object by
-prefixing a C constant string with the character @samp{@@}:
-
-@smallexample
- id myString = @@"this is a constant string object";
-@end smallexample
-
-The constant string objects are by default instances of the
-@code{NXConstantString} class which is provided by the GNU Objective-C
-runtime. To get the definition of this class you must include the
-@file{objc/NXConstStr.h} header file.
-
-User defined libraries may want to implement their own constant string
-class. To be able to support them, the GNU Objective-C compiler provides
-a new command line options @option{-fconstant-string-class=@var{class-name}}.
-The provided class should adhere to a strict structure, the same
-as @code{NXConstantString}'s structure:
-
-@smallexample
-
-@@interface MyConstantStringClass
-@{
- Class isa;
- char *c_string;
- unsigned int len;
-@}
-@@end
-
-@end smallexample
-
-@code{NXConstantString} inherits from @code{Object}; user class
-libraries may choose to inherit the customized constant string class
-from a different class than @code{Object}. There is no requirement in
-the methods the constant string class has to implement, but the final
-ivar layout of the class must be the compatible with the given
-structure.
-
-When the compiler creates the statically allocated constant string
-object, the @code{c_string} field will be filled by the compiler with
-the string; the @code{length} field will be filled by the compiler with
-the string length; the @code{isa} pointer will be filled with
-@code{NULL} by the compiler, and it will later be fixed up automatically
-at runtime by the GNU Objective-C runtime library to point to the class
-which was set by the @option{-fconstant-string-class} option when the
-object file is loaded (if you wonder how it works behind the scenes, the
-name of the class to use, and the list of static objects to fixup, are
-stored by the compiler in the object file in a place where the GNU
-runtime library will find them at runtime).
-
-As a result, when a file is compiled with the
-@option{-fconstant-string-class} option, all the constant string objects
-will be instances of the class specified as argument to this option. It
-is possible to have multiple compilation units referring to different
-constant string classes, neither the compiler nor the linker impose any
-restrictions in doing this.
-
-@c =========================================================================
-@node compatibility_alias
-@section @code{compatibility_alias}
-
-The keyword @code{@@compatibility_alias} allows you to define a class name
-as equivalent to another class name. For example:
-
-@smallexample
-@@compatibility_alias WOApplication GSWApplication;
-@end smallexample
-
-tells the compiler that each time it encounters @code{WOApplication} as
-a class name, it should replace it with @code{GSWApplication} (that is,
-@code{WOApplication} is just an alias for @code{GSWApplication}).
-
-There are some constraints on how this can be used---
-
-@itemize @bullet
-
-@item @code{WOApplication} (the alias) must not be an existing class;
-
-@item @code{GSWApplication} (the real class) must be an existing class.
-
-@end itemize
-
-@c =========================================================================
-@node Exceptions
-@section Exceptions
-
-GNU Objective-C provides exception support built into the language, as
-in the following example:
-
-@smallexample
- @@try @{
- @dots{}
- @@throw expr;
- @dots{}
- @}
- @@catch (AnObjCClass *exc) @{
- @dots{}
- @@throw expr;
- @dots{}
- @@throw;
- @dots{}
- @}
- @@catch (AnotherClass *exc) @{
- @dots{}
- @}
- @@catch (id allOthers) @{
- @dots{}
- @}
- @@finally @{
- @dots{}
- @@throw expr;
- @dots{}
- @}
-@end smallexample
-
-The @code{@@throw} statement may appear anywhere in an Objective-C or
-Objective-C++ program; when used inside of a @code{@@catch} block, the
-@code{@@throw} may appear without an argument (as shown above), in
-which case the object caught by the @code{@@catch} will be rethrown.
-
-Note that only (pointers to) Objective-C objects may be thrown and
-caught using this scheme. When an object is thrown, it will be caught
-by the nearest @code{@@catch} clause capable of handling objects of
-that type, analogously to how @code{catch} blocks work in C++ and
-Java. A @code{@@catch(id @dots{})} clause (as shown above) may also
-be provided to catch any and all Objective-C exceptions not caught by
-previous @code{@@catch} clauses (if any).
-
-The @code{@@finally} clause, if present, will be executed upon exit
-from the immediately preceding @code{@@try @dots{} @@catch} section.
-This will happen regardless of whether any exceptions are thrown,
-caught or rethrown inside the @code{@@try @dots{} @@catch} section,
-analogously to the behavior of the @code{finally} clause in Java.
-
-There are several caveats to using the new exception mechanism:
-
-@itemize @bullet
-@item
-The @option{-fobjc-exceptions} command line option must be used when
-compiling Objective-C files that use exceptions.
-
-@item
-With the GNU runtime, exceptions are always implemented as ``native''
-exceptions and it is recommended that the @option{-fexceptions} and
-@option{-shared-libgcc} options are used when linking.
-
-@item
-With the NeXT runtime, although currently designed to be binary
-compatible with @code{NS_HANDLER}-style idioms provided by the
-@code{NSException} class, the new exceptions can only be used on Mac
-OS X 10.3 (Panther) and later systems, due to additional functionality
-needed in the NeXT Objective-C runtime.
-
-@item
-As mentioned above, the new exceptions do not support handling
-types other than Objective-C objects. Furthermore, when used from
-Objective-C++, the Objective-C exception model does not interoperate with C++
-exceptions at this time. This means you cannot @code{@@throw} an exception
-from Objective-C and @code{catch} it in C++, or vice versa
-(i.e., @code{throw @dots{} @@catch}).
-@end itemize
-
-@c =========================================================================
-@node Synchronization
-@section Synchronization
-
-GNU Objective-C provides support for synchronized blocks:
-
-@smallexample
- @@synchronized (ObjCClass *guard) @{
- @dots{}
- @}
-@end smallexample
-
-Upon entering the @code{@@synchronized} block, a thread of execution
-shall first check whether a lock has been placed on the corresponding
-@code{guard} object by another thread. If it has, the current thread
-shall wait until the other thread relinquishes its lock. Once
-@code{guard} becomes available, the current thread will place its own
-lock on it, execute the code contained in the @code{@@synchronized}
-block, and finally relinquish the lock (thereby making @code{guard}
-available to other threads).
-
-Unlike Java, Objective-C does not allow for entire methods to be
-marked @code{@@synchronized}. Note that throwing exceptions out of
-@code{@@synchronized} blocks is allowed, and will cause the guarding
-object to be unlocked properly.
-
-Because of the interactions between synchronization and exception
-handling, you can only use @code{@@synchronized} when compiling with
-exceptions enabled, that is with the command line option
-@option{-fobjc-exceptions}.
-
-
-@c =========================================================================
-@node Fast enumeration
-@section Fast Enumeration
-
-@menu
-* Using fast enumeration::
-* c99-like fast enumeration syntax::
-* Fast enumeration details::
-* Fast enumeration protocol::
-@end menu
-
-@c ================================
-@node Using fast enumeration
-@subsection Using Fast Enumeration
-
-GNU Objective-C provides support for the fast enumeration syntax:
-
-@smallexample
- id array = @dots{};
- id object;
-
- for (object in array)
- @{
- /* Do something with 'object' */
- @}
-@end smallexample
-
-@code{array} needs to be an Objective-C object (usually a collection
-object, for example an array, a dictionary or a set) which implements
-the ``Fast Enumeration Protocol'' (see below). If you are using a
-Foundation library such as GNUstep Base or Apple Cocoa Foundation, all
-collection objects in the library implement this protocol and can be
-used in this way.
-
-The code above would iterate over all objects in @code{array}. For
-each of them, it assigns it to @code{object}, then executes the
-@code{Do something with 'object'} statements.
-
-Here is a fully worked-out example using a Foundation library (which
-provides the implementation of @code{NSArray}, @code{NSString} and
-@code{NSLog}):
-
-@smallexample
- NSArray *array = [NSArray arrayWithObjects: @@"1", @@"2", @@"3", nil];
- NSString *object;
-
- for (object in array)
- NSLog (@@"Iterating over %@@", object);
-@end smallexample
-
-
-@c ================================
-@node c99-like fast enumeration syntax
-@subsection C99-Like Fast Enumeration Syntax
-
-A c99-like declaration syntax is also allowed:
-
-@smallexample
- id array = @dots{};
-
- for (id object in array)
- @{
- /* Do something with 'object' */
- @}
-@end smallexample
-
-this is completely equivalent to:
-
-@smallexample
- id array = @dots{};
-
- @{
- id object;
- for (object in array)
- @{
- /* Do something with 'object' */
- @}
- @}
-@end smallexample
-
-but can save some typing.
-
-Note that the option @option{-std=c99} is not required to allow this
-syntax in Objective-C.
-
-@c ================================
-@node Fast enumeration details
-@subsection Fast Enumeration Details
-
-Here is a more technical description with the gory details. Consider the code
-
-@smallexample
- for (@var{object expression} in @var{collection expression})
- @{
- @var{statements}
- @}
-@end smallexample
-
-here is what happens when you run it:
-
-@itemize @bullet
-@item
-@code{@var{collection expression}} is evaluated exactly once and the
-result is used as the collection object to iterate over. This means
-it is safe to write code such as @code{for (object in [NSDictionary
-keyEnumerator]) @dots{}}.
-
-@item
-the iteration is implemented by the compiler by repeatedly getting
-batches of objects from the collection object using the fast
-enumeration protocol (see below), then iterating over all objects in
-the batch. This is faster than a normal enumeration where objects are
-retrieved one by one (hence the name ``fast enumeration'').
-
-@item
-if there are no objects in the collection, then
-@code{@var{object expression}} is set to @code{nil} and the loop
-immediately terminates.
-
-@item
-if there are objects in the collection, then for each object in the
-collection (in the order they are returned) @code{@var{object expression}}
-is set to the object, then @code{@var{statements}} are executed.
-
-@item
-@code{@var{statements}} can contain @code{break} and @code{continue}
-commands, which will abort the iteration or skip to the next loop
-iteration as expected.
-
-@item
-when the iteration ends because there are no more objects to iterate
-over, @code{@var{object expression}} is set to @code{nil}. This allows
-you to determine whether the iteration finished because a @code{break}
-command was used (in which case @code{@var{object expression}} will remain
-set to the last object that was iterated over) or because it iterated
-over all the objects (in which case @code{@var{object expression}} will be
-set to @code{nil}).
-
-@item
-@code{@var{statements}} must not make any changes to the collection
-object; if they do, it is a hard error and the fast enumeration
-terminates by invoking @code{objc_enumerationMutation}, a runtime
-function that normally aborts the program but which can be customized
-by Foundation libraries via @code{objc_set_mutation_handler} to do
-something different, such as raising an exception.
-
-@end itemize
-
-@c ================================
-@node Fast enumeration protocol
-@subsection Fast Enumeration Protocol
-
-If you want your own collection object to be usable with fast
-enumeration, you need to have it implement the method
-
-@smallexample
-- (unsigned long) countByEnumeratingWithState: (NSFastEnumerationState *)state
- objects: (id *)objects
- count: (unsigned long)len;
-@end smallexample
-
-where @code{NSFastEnumerationState} must be defined in your code as follows:
-
-@smallexample
-typedef struct
-@{
- unsigned long state;
- id *itemsPtr;
- unsigned long *mutationsPtr;
- unsigned long extra[5];
-@} NSFastEnumerationState;
-@end smallexample
-
-If no @code{NSFastEnumerationState} is defined in your code, the
-compiler will automatically replace @code{NSFastEnumerationState *}
-with @code{struct __objcFastEnumerationState *}, where that type is
-silently defined by the compiler in an identical way. This can be
-confusing and we recommend that you define
-@code{NSFastEnumerationState} (as shown above) instead.
-
-The method is called repeatedly during a fast enumeration to retrieve
-batches of objects. Each invocation of the method should retrieve the
-next batch of objects.
-
-The return value of the method is the number of objects in the current
-batch; this should not exceed @code{len}, which is the maximum size of
-a batch as requested by the caller. The batch itself is returned in
-the @code{itemsPtr} field of the @code{NSFastEnumerationState} struct.
-
-To help with returning the objects, the @code{objects} array is a C
-array preallocated by the caller (on the stack) of size @code{len}.
-In many cases you can put the objects you want to return in that
-@code{objects} array, then do @code{itemsPtr = objects}. But you
-don't have to; if your collection already has the objects to return in
-some form of C array, it could return them from there instead.
-
-The @code{state} and @code{extra} fields of the
-@code{NSFastEnumerationState} structure allows your collection object
-to keep track of the state of the enumeration. In a simple array
-implementation, @code{state} may keep track of the index of the last
-object that was returned, and @code{extra} may be unused.
-
-The @code{mutationsPtr} field of the @code{NSFastEnumerationState} is
-used to keep track of mutations. It should point to a number; before
-working on each object, the fast enumeration loop will check that this
-number has not changed. If it has, a mutation has happened and the
-fast enumeration will abort. So, @code{mutationsPtr} could be set to
-point to some sort of version number of your collection, which is
-increased by one every time there is a change (for example when an
-object is added or removed). Or, if you are content with less strict
-mutation checks, it could point to the number of objects in your
-collection or some other value that can be checked to perform an
-approximate check that the collection has not been mutated.
-
-Finally, note how we declared the @code{len} argument and the return
-value to be of type @code{unsigned long}. They could also be declared
-to be of type @code{unsigned int} and everything would still work.
-
-@c =========================================================================
-@node Messaging with the GNU Objective-C runtime
-@section Messaging with the GNU Objective-C Runtime
-
-This section is specific for the GNU Objective-C runtime. If you are
-using a different runtime, you can skip it.
-
-The implementation of messaging in the GNU Objective-C runtime is
-designed to be portable, and so is based on standard C.
-
-Sending a message in the GNU Objective-C runtime is composed of two
-separate steps. First, there is a call to the lookup function,
-@code{objc_msg_lookup ()} (or, in the case of messages to super,
-@code{objc_msg_lookup_super ()}). This runtime function takes as
-argument the receiver and the selector of the method to be called; it
-returns the @code{IMP}, that is a pointer to the function implementing
-the method. The second step of method invocation consists of casting
-this pointer function to the appropriate function pointer type, and
-calling the function pointed to it with the right arguments.
-
-For example, when the compiler encounters a method invocation such as
-@code{[object init]}, it compiles it into a call to
-@code{objc_msg_lookup (object, @@selector(init))} followed by a cast
-of the returned value to the appropriate function pointer type, and
-then it calls it.
-
-@menu
-* Dynamically registering methods::
-* Forwarding hook::
-@end menu
-
-@c =========================================================================
-@node Dynamically registering methods
-@subsection Dynamically Registering Methods
-
-If @code{objc_msg_lookup()} does not find a suitable method
-implementation, because the receiver does not implement the required
-method, it tries to see if the class can dynamically register the
-method.
-
-To do so, the runtime checks if the class of the receiver implements
-the method
-
-@smallexample
-+ (BOOL) resolveInstanceMethod: (SEL)selector;
-@end smallexample
-
-in the case of an instance method, or
-
-@smallexample
-+ (BOOL) resolveClassMethod: (SEL)selector;
-@end smallexample
-
-in the case of a class method. If the class implements it, the
-runtime invokes it, passing as argument the selector of the original
-method, and if it returns @code{YES}, the runtime tries the lookup
-again, which could now succeed if a matching method was added
-dynamically by @code{+resolveInstanceMethod:} or
-@code{+resolveClassMethod:}.
-
-This allows classes to dynamically register methods (by adding them to
-the class using @code{class_addMethod}) when they are first called.
-To do so, a class should implement @code{+resolveInstanceMethod:} (or,
-depending on the case, @code{+resolveClassMethod:}) and have it
-recognize the selectors of methods that can be registered dynamically
-at runtime, register them, and return @code{YES}. It should return
-@code{NO} for methods that it does not dynamically registered at
-runtime.
-
-If @code{+resolveInstanceMethod:} (or @code{+resolveClassMethod:}) is
-not implemented or returns @code{NO}, the runtime then tries the
-forwarding hook.
-
-Support for @code{+resolveInstanceMethod:} and
-@code{resolveClassMethod:} was added to the GNU Objective-C runtime in
-GCC version 4.6.
-
-@c =========================================================================
-@node Forwarding hook
-@subsection Forwarding Hook
-
-The GNU Objective-C runtime provides a hook, called
-@code{__objc_msg_forward2}, which is called by
-@code{objc_msg_lookup()} when it cannot find a method implementation in
-the runtime tables and after calling @code{+resolveInstanceMethod:}
-and @code{+resolveClassMethod:} has been attempted and did not succeed
-in dynamically registering the method.
-
-To configure the hook, you set the global variable
-@code{__objc_msg_forward2} to a function with the same argument and
-return types of @code{objc_msg_lookup()}. When
-@code{objc_msg_lookup()} cannot find a method implementation, it
-invokes the hook function you provided to get a method implementation
-to return. So, in practice @code{__objc_msg_forward2} allows you to
-extend @code{objc_msg_lookup()} by adding some custom code that is
-called to do a further lookup when no standard method implementation
-can be found using the normal lookup.
-
-This hook is generally reserved for ``Foundation'' libraries such as
-GNUstep Base, which use it to implement their high-level method
-forwarding API, typically based around the @code{forwardInvocation:}
-method. So, unless you are implementing your own ``Foundation''
-library, you should not set this hook.
-
-In a typical forwarding implementation, the @code{__objc_msg_forward2}
-hook function determines the argument and return type of the method
-that is being looked up, and then creates a function that takes these
-arguments and has that return type, and returns it to the caller.
-Creating this function is non-trivial and is typically performed using
-a dedicated library such as @code{libffi}.
-
-The forwarding method implementation thus created is returned by
-@code{objc_msg_lookup()} and is executed as if it was a normal method
-implementation. When the forwarding method implementation is called,
-it is usually expected to pack all arguments into some sort of object
-(typically, an @code{NSInvocation} in a ``Foundation'' library), and
-hand it over to the programmer (@code{forwardInvocation:}) who is then
-allowed to manipulate the method invocation using a high-level API
-provided by the ``Foundation'' library. For example, the programmer
-may want to examine the method invocation arguments and name and
-potentially change them before forwarding the method invocation to one
-or more local objects (@code{performInvocation:}) or even to remote
-objects (by using Distributed Objects or some other mechanism). When
-all this completes, the return value is passed back and must be
-returned correctly to the original caller.
-
-Note that the GNU Objective-C runtime currently provides no support
-for method forwarding or method invocations other than the
-@code{__objc_msg_forward2} hook.
-
-If the forwarding hook does not exist or returns @code{NULL}, the
-runtime currently attempts forwarding using an older, deprecated API,
-and if that fails, it aborts the program. In future versions of the
-GNU Objective-C runtime, the runtime will immediately abort.
+++ /dev/null
-@c Copyright (C) 2013-2022 Free Software Foundation, Inc.
-@c This is part of the GCC manual.
-@c For copying conditions, see the file gcc.texi.
-
-@cindex optimization dumps
-
-This section is describes dump infrastructure which is common to both
-pass dumps as well as optimization dumps. The goal for this
-infrastructure is to provide both gcc developers and users detailed
-information about various compiler transformations and optimizations.
-
-@menu
-* Dump setup:: Setup of optimization dumps.
-* Optimization groups:: Groups made up of optimization passes.
-* Dump files and streams:: Dump output file names and streams.
-* Dump output verbosity:: How much information to dump.
-* Dump types:: Various types of dump functions.
-* Dump examples:: Sample usage.
-@end menu
-
-@node Dump setup
-@subsection Dump setup
-@cindex dump setup
-
-A dump_manager class is defined in @file{dumpfile.h}. Various passes
-register dumping pass-specific information via @code{dump_register} in
-@file{passes.cc}. During the registration, an optimization pass can
-select its optimization group (@pxref{Optimization groups}). After
-that optimization information corresponding to the entire group
-(presumably from multiple passes) can be output via command-line
-switches. Note that if a pass does not fit into any of the pre-defined
-groups, it can select @code{OPTGROUP_NONE}.
-
-Note that in general, a pass need not know its dump output file name,
-whether certain flags are enabled, etc. However, for legacy reasons,
-passes could also call @code{dump_begin} which returns a stream in
-case the particular pass has optimization dumps enabled. A pass could
-call @code{dump_end} when the dump has ended. These methods should go
-away once all the passes are converted to use the new dump
-infrastructure.
-
-The recommended way to setup the dump output is via @code{dump_start}
-and @code{dump_end}.
-
-@node Optimization groups
-@subsection Optimization groups
-@cindex optimization groups
-The optimization passes are grouped into several categories. Currently
-defined categories in @file{dumpfile.h} are
-
-@ftable @code
-
-@item OPTGROUP_IPA
-IPA optimization passes. Enabled by @option{-ipa}
-
-@item OPTGROUP_LOOP
-Loop optimization passes. Enabled by @option{-loop}.
-
-@item OPTGROUP_INLINE
-Inlining passes. Enabled by @option{-inline}.
-
-@item OPTGROUP_OMP
-OMP (Offloading and Multi Processing) passes. Enabled by
-@option{-omp}.
-
-@item OPTGROUP_VEC
-Vectorization passes. Enabled by @option{-vec}.
-
-@item OPTGROUP_OTHER
-All other optimization passes which do not fall into one of the above.
-
-@item OPTGROUP_ALL
-All optimization passes. Enabled by @option{-optall}.
-
-@end ftable
-
-By using groups a user could selectively enable optimization
-information only for a group of passes. By default, the optimization
-information for all the passes is dumped.
-
-@node Dump files and streams
-@subsection Dump files and streams
-@cindex optimization info file names
-
-There are two separate output streams available for outputting
-optimization information from passes. Note that both these streams
-accept @code{stderr} and @code{stdout} as valid streams and thus it is
-possible to dump output to standard output or error. This is specially
-handy for outputting all available information in a single file by
-redirecting @code{stderr}.
-
-@table @code
-@item @code{pstream}
-This stream is for pass-specific dump output. For example,
-@option{-fdump-tree-vect=foo.v} dumps tree vectorization pass output
-into the given file name @file{foo.v}. If the file name is not provided,
-the default file name is based on the source file and pass number. Note
-that one could also use special file names @code{stdout} and
-@code{stderr} for dumping to standard output and standard error
-respectively.
-
-@item @code{alt_stream}
-This steam is used for printing optimization specific output in
-response to the @option{-fopt-info}. Again a file name can be given. If
-the file name is not given, it defaults to @code{stderr}.
-@end table
-
-@node Dump output verbosity
-@subsection Dump output verbosity
-@cindex dump verbosity
-
-The dump verbosity has the following options
-
-@table @samp
-@item optimized
-Print information when an optimization is successfully applied. It is
-up to a pass to decide which information is relevant. For example, the
-vectorizer passes print the source location of loops which got
-successfully vectorized.
-
-@item missed
-Print information about missed optimizations. Individual passes
-control which information to include in the output. For example,
-
-@smallexample
-gcc -O2 -ftree-vectorize -fopt-info-vec-missed
-@end smallexample
-
-will print information about missed optimization opportunities from
-vectorization passes on stderr.
-
-@item note
-Print verbose information about optimizations, such as certain
-transformations, more detailed messages about decisions etc.
-
-@item all
-Print detailed optimization information. This includes
-@var{optimized}, @var{missed}, and @var{note}.
-@end table
-
-@node Dump types
-@subsection Dump types
-@cindex dump types
-
-@ftable @code
-
-@item dump_printf
-
-This is a generic method for doing formatted output. It takes an
-additional argument @code{dump_kind} which signifies the type of
-dump. This method outputs information only when the dumps are enabled
-for this particular @code{dump_kind}. Note that the caller doesn't
-need to know if the particular dump is enabled or not, or even the
-file name. The caller only needs to decide which dump output
-information is relevant, and under what conditions. This determines
-the associated flags.
-
-Consider the following example from @file{loop-unroll.cc} where an
-informative message about a loop (along with its location) is printed
-when any of the following flags is enabled
-@itemize @minus
-
-@item optimization messages
-@item RTL dumps
-@item detailed dumps
-
-@end itemize
-
-@example
-int report_flags = MSG_OPTIMIZED_LOCATIONS | TDF_RTL | TDF_DETAILS;
-dump_printf_loc (report_flags, insn,
- "loop turned into non-loop; it never loops.\n");
-@end example
-
-@item dump_basic_block
-Output basic block.
-@item dump_generic_expr
-Output generic expression.
-@item dump_gimple_stmt
-Output gimple statement.
-
-Note that the above methods also have variants prefixed with
-@code{_loc}, such as @code{dump_printf_loc}, which are similar except
-they also output the source location information. The @code{_loc} variants
-take a @code{const dump_location_t &}. This class can be constructed from
-a @code{gimple *} or from a @code{rtx_insn *}, and so callers can pass
-a @code{gimple *} or a @code{rtx_insn *} as the @code{_loc} argument.
-The @code{dump_location_t} constructor will extract the source location
-from the statement or instruction, along with the profile count, and
-the location in GCC's own source code (or the plugin) from which the dump
-call was emitted. Only the source location is currently used.
-There is also a @code{dump_user_location_t} class, capturing the
-source location and profile count, but not the dump emission location,
-so that locations in the user's code can be passed around. This
-can also be constructed from a @code{gimple *} and from a @code{rtx_insn *},
-and it too can be passed as the @code{_loc} argument.
-
-@end ftable
-
-@node Dump examples
-@subsection Dump examples
-@cindex dump examples
-
-@smallexample
-gcc -O3 -fopt-info-missed=missed.all
-@end smallexample
-
-outputs missed optimization report from all the passes into
-@file{missed.all}.
-
-As another example,
-@smallexample
-gcc -O3 -fopt-info-inline-optimized-missed=inline.txt
-@end smallexample
-
-will output information about missed optimizations as well as
-optimized locations from all the inlining passes into
-@file{inline.txt}.
-
-If the @var{filename} is provided, then the dumps from all the
-applicable optimizations are concatenated into the @file{filename}.
-Otherwise the dump is output onto @file{stderr}. If @var{options} is
-omitted, it defaults to @option{optimized-optall}, which means dump
-all information about successful optimizations from all the passes.
-In the following example, the optimization information is output on
-to @file{stderr}.
-
-@smallexample
-gcc -O3 -fopt-info
-@end smallexample
-
-Note that @option{-fopt-info-vec-missed} behaves the same as
-@option{-fopt-info-missed-vec}. The order of the optimization group
-names and message types listed after @option{-fopt-info} does not matter.
-
-As another example, consider
-
-@smallexample
-gcc -fopt-info-vec-missed=vec.miss -fopt-info-loop-optimized=loop.opt
-@end smallexample
-
-Here the two output file names @file{vec.miss} and @file{loop.opt} are
-in conflict since only one output file is allowed. In this case, only
-the first option takes effect and the subsequent options are
-ignored. Thus only the @file{vec.miss} is produced which containts
-dumps from the vectorizer about missed opportunities.
+++ /dev/null
-@c Copyright (C) 2003-2022 Free Software Foundation, Inc.
-@c This is part of the GCC manual.
-@c For copying conditions, see the file gcc.texi.
-
-@node Options
-@chapter Option specification files
-@cindex option specification files
-@cindex @samp{optc-gen.awk}
-
-Most GCC command-line options are described by special option
-definition files, the names of which conventionally end in
-@code{.opt}. This chapter describes the format of these files.
-
-@menu
-* Option file format:: The general layout of the files
-* Option properties:: Supported option properties
-@end menu
-
-@node Option file format
-@section Option file format
-
-Option files are a simple list of records in which each field occupies
-its own line and in which the records themselves are separated by
-blank lines. Comments may appear on their own line anywhere within
-the file and are preceded by semicolons. Whitespace is allowed before
-the semicolon.
-
-The files can contain the following types of record:
-
-@itemize @bullet
-@item
-A language definition record. These records have two fields: the
-string @samp{Language} and the name of the language. Once a language
-has been declared in this way, it can be used as an option property.
-@xref{Option properties}.
-
-@item
-A target specific save record to save additional information. These
-records have two fields: the string @samp{TargetSave}, and a
-declaration type to go in the @code{cl_target_option} structure.
-
-@item
-A variable record to define a variable used to store option
-information. These records have two fields: the string
-@samp{Variable}, and a declaration of the type and name of the
-variable, optionally with an initializer (but without any trailing
-@samp{;}). These records may be used for variables used for many
-options where declaring the initializer in a single option definition
-record, or duplicating it in many records, would be inappropriate, or
-for variables set in option handlers rather than referenced by
-@code{Var} properties.
-
-@item
-A variable record to define a variable used to store option
-information. These records have two fields: the string
-@samp{TargetVariable}, and a declaration of the type and name of the
-variable, optionally with an initializer (but without any trailing
-@samp{;}). @samp{TargetVariable} is a combination of @samp{Variable}
-and @samp{TargetSave} records in that the variable is defined in the
-@code{gcc_options} structure, but these variables are also stored in
-the @code{cl_target_option} structure. The variables are saved in the
-target save code and restored in the target restore code.
-
-@item
-A variable record to record any additional files that the
-@file{options.h} file should include. This is useful to provide
-enumeration or structure definitions needed for target variables.
-These records have two fields: the string @samp{HeaderInclude} and the
-name of the include file.
-
-@item
-A variable record to record any additional files that the
-@file{options.cc} or @file{options-save.cc} file should include. This
-is useful to provide
-inline functions needed for target variables and/or @code{#ifdef}
-sequences to properly set up the initialization. These records have
-two fields: the string @samp{SourceInclude} and the name of the
-include file.
-
-@item
-An enumeration record to define a set of strings that may be used as
-arguments to an option or options. These records have three fields:
-the string @samp{Enum}, a space-separated list of properties and help
-text used to describe the set of strings in @option{--help} output.
-Properties use the same format as option properties; the following are
-valid:
-@table @code
-@item Name(@var{name})
-This property is required; @var{name} must be a name (suitable for use
-in C identifiers) used to identify the set of strings in @code{Enum}
-option properties.
-
-@item Type(@var{type})
-This property is required; @var{type} is the C type for variables set
-by options using this enumeration together with @code{Var}.
-
-@item UnknownError(@var{message})
-The message @var{message} will be used as an error message if the
-argument is invalid; for enumerations without @code{UnknownError}, a
-generic error message is used. @var{message} should contain a single
-@samp{%qs} format, which will be used to format the invalid argument.
-@end table
-
-@item
-An enumeration value record to define one of the strings in a set
-given in an @samp{Enum} record. These records have two fields: the
-string @samp{EnumValue} and a space-separated list of properties.
-Properties use the same format as option properties; the following are
-valid:
-@table @code
-@item Enum(@var{name})
-This property is required; @var{name} says which @samp{Enum} record
-this @samp{EnumValue} record corresponds to.
-
-@item String(@var{string})
-This property is required; @var{string} is the string option argument
-being described by this record.
-
-@item Value(@var{value})
-This property is required; it says what value (representable as
-@code{int}) should be used for the given string.
-
-@item Canonical
-This property is optional. If present, it says the present string is
-the canonical one among all those with the given value. Other strings
-yielding that value will be mapped to this one so specs do not need to
-handle them.
-
-@item DriverOnly
-This property is optional. If present, the present string will only
-be accepted by the driver. This is used for cases such as
-@option{-march=native} that are processed by the driver so that
-@samp{gcc -v} shows how the options chosen depended on the system on
-which the compiler was run.
-
-@item Set(@var{number})
-This property is optional, required for enumerations used in
-@code{EnumSet} options. @var{number} should be decimal number between
-1 and 64 inclusive and divides the enumeration into a set of
-sets of mutually exclusive arguments. Arguments with the same
-@var{number} can't be specified together in the same option, but
-arguments with different @var{number} can. @var{value} needs to be
-chosen such that a mask of all @var{value} values from the same set
-@var{number} bitwise ored doesn't overlap with masks for other sets.
-When @code{-foption=arg_from_set1,arg_from_set4} and
-@code{-fno-option=arg_from_set3} are used, the effect is that previous
-value of the @code{Var} will get bits from set 1 and 4 masks cleared,
-ored @code{Value} of @code{arg_from_set1} and @code{arg_from_set4}
-and then will get bits from set 3 mask cleared.
-@end table
-
-@item
-An option definition record. These records have the following fields:
-@enumerate
-@item
-the name of the option, with the leading ``-'' removed
-@item
-a space-separated list of option properties (@pxref{Option properties})
-@item
-the help text to use for @option{--help} (omitted if the second field
-contains the @code{Undocumented} property).
-@end enumerate
-
-By default, all options beginning with ``f'', ``W'' or ``m'' are
-implicitly assumed to take a ``no-'' form. This form should not be
-listed separately. If an option beginning with one of these letters
-does not have a ``no-'' form, you can use the @code{RejectNegative}
-property to reject it.
-
-The help text is automatically line-wrapped before being displayed.
-Normally the name of the option is printed on the left-hand side of
-the output and the help text is printed on the right. However, if the
-help text contains a tab character, the text to the left of the tab is
-used instead of the option's name and the text to the right of the
-tab forms the help text. This allows you to elaborate on what type
-of argument the option takes.
-
-There is no support for different help texts for different languages.
-If an option is supported for multiple languages, use a generic
-description that is correct for all of them.
-
-If an option has multiple option definition records (in different
-front ends' @file{*.opt} files, and/or @file{gcc/common.opt}, for
-example), convention is to not duplicate the help text for each of
-them, but instead put a comment like @code{; documented in common.opt}
-in place of the help text for all but one of the multiple option
-definition records.
-
-@item
-A target mask record. These records have one field of the form
-@samp{Mask(@var{x})}. The options-processing script will automatically
-allocate a bit in @code{target_flags} (@pxref{Run-time Target}) for
-each mask name @var{x} and set the macro @code{MASK_@var{x}} to the
-appropriate bitmask. It will also declare a @code{TARGET_@var{x}}
-macro that has the value 1 when bit @code{MASK_@var{x}} is set and
-0 otherwise.
-
-They are primarily intended to declare target masks that are not
-associated with user options, either because these masks represent
-internal switches or because the options are not available on all
-configurations and yet the masks always need to be defined.
-@end itemize
-
-@node Option properties
-@section Option properties
-
-The second field of an option record can specify any of the following
-properties. When an option takes an argument, it is enclosed in parentheses
-following the option property name. The parser that handles option files
-is quite simplistic, and will be tricked by any nested parentheses within
-the argument text itself; in this case, the entire option argument can
-be wrapped in curly braces within the parentheses to demarcate it, e.g.:
-
-@smallexample
-Condition(@{defined (USE_CYGWIN_LIBSTDCXX_WRAPPERS)@})
-@end smallexample
-
-@table @code
-@item Common
-The option is available for all languages and targets.
-
-@item Target
-The option is available for all languages but is target-specific.
-
-@item Driver
-The option is handled by the compiler driver using code not shared
-with the compilers proper (@file{cc1} etc.).
-
-@item @var{language}
-The option is available when compiling for the given language.
-
-It is possible to specify several different languages for the same
-option. Each @var{language} must have been declared by an earlier
-@code{Language} record. @xref{Option file format}.
-
-@item RejectDriver
-The option is only handled by the compilers proper (@file{cc1} etc.)@:
-and should not be accepted by the driver.
-
-@item RejectNegative
-The option does not have a ``no-'' form. All options beginning with
-``f'', ``W'' or ``m'' are assumed to have a ``no-'' form unless this
-property is used.
-
-@item Negative(@var{othername})
-The option will turn off another option @var{othername}, which is
-the option name with the leading ``-'' removed. This chain action will
-propagate through the @code{Negative} property of the option to be
-turned off. The driver will prune options, removing those that are
-turned off by some later option. This pruning is not done for options
-with @code{Joined} or @code{JoinedOrMissing} properties, unless the
-options have both the @code{RejectNegative} property and the @code{Negative}
-property mentions itself.
-
-As a consequence, if you have a group of mutually-exclusive
-options, their @code{Negative} properties should form a circular chain.
-For example, if options @option{-@var{a}}, @option{-@var{b}} and
-@option{-@var{c}} are mutually exclusive, their respective @code{Negative}
-properties should be @samp{Negative(@var{b})}, @samp{Negative(@var{c})}
-and @samp{Negative(@var{a})}.
-
-@item Joined
-@itemx Separate
-The option takes a mandatory argument. @code{Joined} indicates
-that the option and argument can be included in the same @code{argv}
-entry (as with @code{-mflush-func=@var{name}}, for example).
-@code{Separate} indicates that the option and argument can be
-separate @code{argv} entries (as with @code{-o}). An option is
-allowed to have both of these properties.
-
-@item JoinedOrMissing
-The option takes an optional argument. If the argument is given,
-it will be part of the same @code{argv} entry as the option itself.
-
-This property cannot be used alongside @code{Joined} or @code{Separate}.
-
-@item MissingArgError(@var{message})
-For an option marked @code{Joined} or @code{Separate}, the message
-@var{message} will be used as an error message if the mandatory
-argument is missing; for options without @code{MissingArgError}, a
-generic error message is used. @var{message} should contain a single
-@samp{%qs} format, which will be used to format the name of the option
-passed.
-
-@item Args(@var{n})
-For an option marked @code{Separate}, indicate that it takes @var{n}
-arguments. The default is 1.
-
-@item UInteger
-The option's argument is a non-negative integer consisting of either
-decimal or hexadecimal digits interpreted as @code{int}. Hexadecimal
-integers may optionally start with the @code{0x} or @code{0X} prefix.
-The option parser validates and converts the argument before passing
-it to the relevant option handler. @code{UInteger} should also be used
-with options like @code{-falign-loops} where both @code{-falign-loops}
-and @code{-falign-loops}=@var{n} are supported to make sure the saved
-options are given a full integer. Positive values of the argument in
-excess of @code{INT_MAX} wrap around zero.
-
-@item Host_Wide_Int
-The option's argument is a non-negative integer consisting of either
-decimal or hexadecimal digits interpreted as the widest integer type
-on the host. As with an @code{UInteger} argument, hexadecimal integers
-may optionally start with the @code{0x} or @code{0X} prefix. The option
-parser validates and converts the argument before passing it to
-the relevant option handler. @code{Host_Wide_Int} should be used with
-options that need to accept very large values. Positive values of
-the argument in excess of @code{HOST_WIDE_INT_M1U} are assigned
-@code{HOST_WIDE_INT_M1U}.
-
-@item IntegerRange(@var{n}, @var{m})
-The options's arguments are integers of type @code{int}. The option's
-parser validates that the value of an option integer argument is within
-the closed range [@var{n}, @var{m}].
-
-@item ByteSize
-A property applicable only to @code{UInteger} or @code{Host_Wide_Int}
-arguments. The option's integer argument is interpreted as if in infinite
-precision using saturation arithmetic in the corresponding type. The argument
-may be followed by a @samp{byte-size} suffix designating a multiple of bytes
-such as @code{kB} and @code{KiB} for kilobyte and kibibyte, respectively,
-@code{MB} and @code{MiB} for megabyte and mebibyte, @code{GB} and @code{GiB}
-for gigabyte and gigibyte, and so on. @code{ByteSize} should be used for
-with options that take a very large argument representing a size in bytes,
-such as @option{-Wlarger-than=}.
-
-@item ToLower
-The option's argument should be converted to lowercase as part of
-putting it in canonical form, and before comparing with the strings
-indicated by any @code{Enum} property.
-
-@item NoDriverArg
-For an option marked @code{Separate}, the option only takes an
-argument in the compiler proper, not in the driver. This is for
-compatibility with existing options that are used both directly and
-via @option{-Wp,}; new options should not have this property.
-
-@item Var(@var{var})
-The state of this option should be stored in variable @var{var}
-(actually a macro for @code{global_options.x_@var{var}}).
-The way that the state is stored depends on the type of option:
-
-@item WarnRemoved
-The option is removed and every usage of such option will
-result in a warning. We use it option backward compatibility.
-
-@item Var(@var{var}, @var{set})
-The option controls an integer variable @var{var} and is active when
-@var{var} equals @var{set}. The option parser will set @var{var} to
-@var{set} when the positive form of the option is used and @code{!@var{set}}
-when the ``no-'' form is used.
-
-@var{var} is declared in the same way as for the single-argument form
-described above.
-
-@itemize @bullet
-@item
-If the option uses the @code{Mask} or @code{InverseMask} properties,
-@var{var} is the integer variable that contains the mask.
-
-@item
-If the option is a normal on/off switch, @var{var} is an integer
-variable that is nonzero when the option is enabled. The options
-parser will set the variable to 1 when the positive form of the
-option is used and 0 when the ``no-'' form is used.
-
-@item
-If the option takes an argument and has the @code{UInteger} property,
-@var{var} is an integer variable that stores the value of the argument.
-
-@item
-If the option takes an argument and has the @code{Enum} property,
-@var{var} is a variable (type given in the @code{Type} property of the
-@samp{Enum} record whose @code{Name} property has the same argument as
-the @code{Enum} property of this option) that stores the value of the
-argument.
-
-@item
-If the option has the @code{Defer} property, @var{var} is a pointer to
-a @code{VEC(cl_deferred_option,heap)} that stores the option for later
-processing. (@var{var} is declared with type @code{void *} and needs
-to be cast to @code{VEC(cl_deferred_option,heap)} before use.)
-
-@item
-Otherwise, if the option takes an argument, @var{var} is a pointer to
-the argument string. The pointer will be null if the argument is optional
-and wasn't given.
-@end itemize
-
-The option-processing script will usually zero-initialize @var{var}.
-You can modify this behavior using @code{Init}.
-
-@item Init(@var{value})
-The variable specified by the @code{Var} property should be statically
-initialized to @var{value}. If more than one option using the same
-variable specifies @code{Init}, all must specify the same initializer.
-
-@item Mask(@var{name})
-The option is associated with a bit in the @code{target_flags}
-variable (@pxref{Run-time Target}) and is active when that bit is set.
-You may also specify @code{Var} to select a variable other than
-@code{target_flags}.
-
-The options-processing script will automatically allocate a unique bit
-for the option. If the option is attached to @samp{target_flags},
-the script will set the macro @code{MASK_@var{name}} to the appropriate
-bitmask. It will also declare a @code{TARGET_@var{name}} macro that has
-the value 1 when the option is active and 0 otherwise. If you use @code{Var}
-to attach the option to a different variable, the bitmask macro with be
-called @code{OPTION_MASK_@var{name}}.
-
-@item InverseMask(@var{othername})
-@itemx InverseMask(@var{othername}, @var{thisname})
-The option is the inverse of another option that has the
-@code{Mask(@var{othername})} property. If @var{thisname} is given,
-the options-processing script will declare a @code{TARGET_@var{thisname}}
-macro that is 1 when the option is active and 0 otherwise.
-
-@item Enum(@var{name})
-The option's argument is a string from the set of strings associated
-with the corresponding @samp{Enum} record. The string is checked and
-converted to the integer specified in the corresponding
-@samp{EnumValue} record before being passed to option handlers.
-
-@item EnumSet
-Must be used together with the @code{Enum(@var{name})} property.
-Corresponding @samp{Enum} record must use @code{Set} properties.
-The option's argument is either a string from the set like for
-@code{Enum(@var{name})}, but with a slightly different behavior that
-the whole @code{Var} isn't overwritten, but only the bits in all the
-enumeration values with the same set bitwise ored together.
-Or option's argument can be a comma separated list of strings where
-each string is from a different @code{Set(@var{number})}.
-
-@item EnumBitSet
-Must be used together with the @code{Enum(@var{name})} property.
-Similar to @samp{EnumSet}, but corresponding @samp{Enum} record must
-not use @code{Set} properties, each @code{EnumValue} should have
-@code{Value} that is a power of 2, each value is treated as its own
-set and its value as the set's mask, so there are no mutually
-exclusive arguments.
-
-@item Defer
-The option should be stored in a vector, specified with @code{Var},
-for later processing.
-
-@item Alias(@var{opt})
-@itemx Alias(@var{opt}, @var{arg})
-@itemx Alias(@var{opt}, @var{posarg}, @var{negarg})
-The option is an alias for @option{-@var{opt}} (or the negative form
-of that option, depending on @code{NegativeAlias}). In the first form,
-any argument passed to the alias is considered to be passed to
-@option{-@var{opt}}, and @option{-@var{opt}} is considered to be
-negated if the alias is used in negated form. In the second form, the
-alias may not be negated or have an argument, and @var{posarg} is
-considered to be passed as an argument to @option{-@var{opt}}. In the
-third form, the alias may not have an argument, if the alias is used
-in the positive form then @var{posarg} is considered to be passed to
-@option{-@var{opt}}, and if the alias is used in the negative form
-then @var{negarg} is considered to be passed to @option{-@var{opt}}.
-
-Aliases should not specify @code{Var} or @code{Mask} or
-@code{UInteger}. Aliases should normally specify the same languages
-as the target of the alias; the flags on the target will be used to
-determine any diagnostic for use of an option for the wrong language,
-while those on the alias will be used to identify what command-line
-text is the option and what text is any argument to that option.
-
-When an @code{Alias} definition is used for an option, driver specs do
-not need to handle it and no @samp{OPT_} enumeration value is defined
-for it; only the canonical form of the option will be seen in those
-places.
-
-@item NegativeAlias
-For an option marked with @code{Alias(@var{opt})}, the option is
-considered to be an alias for the positive form of @option{-@var{opt}}
-if negated and for the negative form of @option{-@var{opt}} if not
-negated. @code{NegativeAlias} may not be used with the forms of
-@code{Alias} taking more than one argument.
-
-@item Ignore
-This option is ignored apart from printing any warning specified using
-@code{Warn}. The option will not be seen by specs and no @samp{OPT_}
-enumeration value is defined for it.
-
-@item SeparateAlias
-For an option marked with @code{Joined}, @code{Separate} and
-@code{Alias}, the option only acts as an alias when passed a separate
-argument; with a joined argument it acts as a normal option, with an
-@samp{OPT_} enumeration value. This is for compatibility with the
-Java @option{-d} option and should not be used for new options.
-
-@item Warn(@var{message})
-If this option is used, output the warning @var{message}.
-@var{message} is a format string, either taking a single operand with
-a @samp{%qs} format which is the option name, or not taking any
-operands, which is passed to the @samp{warning} function. If an alias
-is marked @code{Warn}, the target of the alias must not also be marked
-@code{Warn}.
-
-@item Warning
-This is a warning option and should be shown as such in
-@option{--help} output. This flag does not currently affect anything
-other than @option{--help}.
-
-@item Optimization
-This is an optimization option. It should be shown as such in
-@option{--help} output, and any associated variable named using
-@code{Var} should be saved and restored when the optimization level is
-changed with @code{optimize} attributes.
-
-@item PerFunction
-This is an option that can be overridden on a per-function basis.
-@code{Optimization} implies @code{PerFunction}, but options that do not
-affect executable code generation may use this flag instead, so that the
-option is not taken into account in ways that might affect executable
-code generation.
-
-@item Param
-This is an option that is a parameter.
-
-@item Undocumented
-The option is deliberately missing documentation and should not
-be included in the @option{--help} output.
-
-@item Condition(@var{cond})
-The option should only be accepted if preprocessor condition
-@var{cond} is true. Note that any C declarations associated with the
-option will be present even if @var{cond} is false; @var{cond} simply
-controls whether the option is accepted and whether it is printed in
-the @option{--help} output.
-
-@item Save
-Build the @code{cl_target_option} structure to hold a copy of the
-option, add the functions @code{cl_target_option_save} and
-@code{cl_target_option_restore} to save and restore the options.
-
-@item SetByCombined
-The option may also be set by a combined option such as
-@option{-ffast-math}. This causes the @code{gcc_options} struct to
-have a field @code{frontend_set_@var{name}}, where @code{@var{name}}
-is the name of the field holding the value of this option (without the
-leading @code{x_}). This gives the front end a way to indicate that
-the value has been set explicitly and should not be changed by the
-combined option. For example, some front ends use this to prevent
-@option{-ffast-math} and @option{-fno-fast-math} from changing the
-value of @option{-fmath-errno} for languages that do not use
-@code{errno}.
-
-@item EnabledBy(@var{opt})
-@itemx EnabledBy(@var{opt} || @var{opt2})
-@itemx EnabledBy(@var{opt} && @var{opt2})
-If not explicitly set, the option is set to the value of
-@option{-@var{opt}}; multiple options can be given, separated by
-@code{||}. The third form using @code{&&} specifies that the option is
-only set if both @var{opt} and @var{opt2} are set. The options @var{opt}
-and @var{opt2} must have the @code{Common} property; otherwise, use
-@code{LangEnabledBy}.
-
-@item LangEnabledBy(@var{language}, @var{opt})
-@itemx LangEnabledBy(@var{language}, @var{opt}, @var{posarg}, @var{negarg})
-When compiling for the given language, the option is set to the value
-of @option{-@var{opt}}, if not explicitly set. @var{opt} can be also a list
-of @code{||} separated options. In the second form, if
-@var{opt} is used in the positive form then @var{posarg} is considered
-to be passed to the option, and if @var{opt} is used in the negative
-form then @var{negarg} is considered to be passed to the option. It
-is possible to specify several different languages. Each
-@var{language} must have been declared by an earlier @code{Language}
-record. @xref{Option file format}.
-
-@item NoDWARFRecord
-The option is omitted from the producer string written by
-@option{-grecord-gcc-switches}.
-
-@item PchIgnore
-Even if this is a target option, this option will not be recorded / compared
-to determine if a precompiled header file matches.
-
-@item CPP(@var{var})
-The state of this option should be kept in sync with the preprocessor
-option @var{var}. If this property is set, then properties @code{Var}
-and @code{Init} must be set as well.
-
-@item CppReason(@var{CPP_W_Enum})
-This warning option corresponds to @code{cpplib.h} warning reason code
-@var{CPP_W_Enum}. This should only be used for warning options of the
-C-family front-ends.
-
-@end table
+++ /dev/null
-@c markers: BUG TODO
-
-@c Copyright (C) 1988-2022 Free Software Foundation, Inc.
-@c This is part of the GCC manual.
-@c For copying conditions, see the file gcc.texi.
-
-@node Passes
-@chapter Passes and Files of the Compiler
-@cindex passes and files of the compiler
-@cindex files and passes of the compiler
-@cindex compiler passes and files
-@cindex pass dumps
-
-This chapter is dedicated to giving an overview of the optimization and
-code generation passes of the compiler. In the process, it describes
-some of the language front end interface, though this description is no
-where near complete.
-
-@menu
-* Parsing pass:: The language front end turns text into bits.
-* Gimplification pass:: The bits are turned into something we can optimize.
-* Pass manager:: Sequencing the optimization passes.
-* IPA passes:: Inter-procedural optimizations.
-* Tree SSA passes:: Optimizations on a high-level representation.
-* RTL passes:: Optimizations on a low-level representation.
-* Optimization info:: Dumping optimization information from passes.
-@end menu
-
-@node Parsing pass
-@section Parsing pass
-@cindex GENERIC
-@findex lang_hooks.parse_file
-The language front end is invoked only once, via
-@code{lang_hooks.parse_file}, to parse the entire input. The language
-front end may use any intermediate language representation deemed
-appropriate. The C front end uses GENERIC trees (@pxref{GENERIC}), plus
-a double handful of language specific tree codes defined in
-@file{c-common.def}. The Fortran front end uses a completely different
-private representation.
-
-@cindex GIMPLE
-@cindex gimplification
-@cindex gimplifier
-@cindex language-independent intermediate representation
-@cindex intermediate representation lowering
-@cindex lowering, language-dependent intermediate representation
-At some point the front end must translate the representation used in the
-front end to a representation understood by the language-independent
-portions of the compiler. Current practice takes one of two forms.
-The C front end manually invokes the gimplifier (@pxref{GIMPLE}) on each function,
-and uses the gimplifier callbacks to convert the language-specific tree
-nodes directly to GIMPLE before passing the function off to be compiled.
-The Fortran front end converts from a private representation to GENERIC,
-which is later lowered to GIMPLE when the function is compiled. Which
-route to choose probably depends on how well GENERIC (plus extensions)
-can be made to match up with the source language and necessary parsing
-data structures.
-
-BUG: Gimplification must occur before nested function lowering,
-and nested function lowering must be done by the front end before
-passing the data off to cgraph.
-
-TODO: Cgraph should control nested function lowering. It would
-only be invoked when it is certain that the outer-most function
-is used.
-
-TODO: Cgraph needs a gimplify_function callback. It should be
-invoked when (1) it is certain that the function is used, (2)
-warning flags specified by the user require some amount of
-compilation in order to honor, (3) the language indicates that
-semantic analysis is not complete until gimplification occurs.
-Hum@dots{} this sounds overly complicated. Perhaps we should just
-have the front end gimplify always; in most cases it's only one
-function call.
-
-The front end needs to pass all function definitions and top level
-declarations off to the middle-end so that they can be compiled and
-emitted to the object file. For a simple procedural language, it is
-usually most convenient to do this as each top level declaration or
-definition is seen. There is also a distinction to be made between
-generating functional code and generating complete debug information.
-The only thing that is absolutely required for functional code is that
-function and data @emph{definitions} be passed to the middle-end. For
-complete debug information, function, data and type declarations
-should all be passed as well.
-
-@findex rest_of_decl_compilation
-@findex rest_of_type_compilation
-@findex cgraph_finalize_function
-In any case, the front end needs each complete top-level function or
-data declaration, and each data definition should be passed to
-@code{rest_of_decl_compilation}. Each complete type definition should
-be passed to @code{rest_of_type_compilation}. Each function definition
-should be passed to @code{cgraph_finalize_function}.
-
-TODO: I know rest_of_compilation currently has all sorts of
-RTL generation semantics. I plan to move all code generation
-bits (both Tree and RTL) to compile_function. Should we hide
-cgraph from the front ends and move back to rest_of_compilation
-as the official interface? Possibly we should rename all three
-interfaces such that the names match in some meaningful way and
-that is more descriptive than "rest_of".
-
-The middle-end will, at its option, emit the function and data
-definitions immediately or queue them for later processing.
-
-@node Gimplification pass
-@section Gimplification pass
-
-@cindex gimplification
-@cindex GIMPLE
-@dfn{Gimplification} is a whimsical term for the process of converting
-the intermediate representation of a function into the GIMPLE language
-(@pxref{GIMPLE}). The term stuck, and so words like ``gimplification'',
-``gimplify'', ``gimplifier'' and the like are sprinkled throughout this
-section of code.
-
-While a front end may certainly choose to generate GIMPLE directly if
-it chooses, this can be a moderately complex process unless the
-intermediate language used by the front end is already fairly simple.
-Usually it is easier to generate GENERIC trees plus extensions
-and let the language-independent gimplifier do most of the work.
-
-@findex gimplify_function_tree
-@findex gimplify_expr
-@findex lang_hooks.gimplify_expr
-The main entry point to this pass is @code{gimplify_function_tree}
-located in @file{gimplify.cc}. From here we process the entire
-function gimplifying each statement in turn. The main workhorse
-for this pass is @code{gimplify_expr}. Approximately everything
-passes through here at least once, and it is from here that we
-invoke the @code{lang_hooks.gimplify_expr} callback.
-
-The callback should examine the expression in question and return
-@code{GS_UNHANDLED} if the expression is not a language specific
-construct that requires attention. Otherwise it should alter the
-expression in some way to such that forward progress is made toward
-producing valid GIMPLE@. If the callback is certain that the
-transformation is complete and the expression is valid GIMPLE, it
-should return @code{GS_ALL_DONE}. Otherwise it should return
-@code{GS_OK}, which will cause the expression to be processed again.
-If the callback encounters an error during the transformation (because
-the front end is relying on the gimplification process to finish
-semantic checks), it should return @code{GS_ERROR}.
-
-@node Pass manager
-@section Pass manager
-
-The pass manager is located in @file{passes.cc}, @file{tree-optimize.c}
-and @file{tree-pass.h}.
-It processes passes as described in @file{passes.def}.
-Its job is to run all of the individual passes in the correct order,
-and take care of standard bookkeeping that applies to every pass.
-
-The theory of operation is that each pass defines a structure that
-represents everything we need to know about that pass---when it
-should be run, how it should be run, what intermediate language
-form or on-the-side data structures it needs. We register the pass
-to be run in some particular order, and the pass manager arranges
-for everything to happen in the correct order.
-
-The actuality doesn't completely live up to the theory at present.
-Command-line switches and @code{timevar_id_t} enumerations must still
-be defined elsewhere. The pass manager validates constraints but does
-not attempt to (re-)generate data structures or lower intermediate
-language form based on the requirements of the next pass. Nevertheless,
-what is present is useful, and a far sight better than nothing at all.
-
-Each pass should have a unique name.
-Each pass may have its own dump file (for GCC debugging purposes).
-Passes with a name starting with a star do not dump anything.
-Sometimes passes are supposed to share a dump file / option name.
-To still give these unique names, you can use a prefix that is delimited
-by a space from the part that is used for the dump file / option name.
-E.g. When the pass name is "ud dce", the name used for dump file/options
-is "dce".
-
-TODO: describe the global variables set up by the pass manager,
-and a brief description of how a new pass should use it.
-I need to look at what info RTL passes use first@enddots{}
-
-@node IPA passes
-@section Inter-procedural optimization passes
-@cindex IPA passes
-@cindex inter-procedural optimization passes
-
-The inter-procedural optimization (IPA) passes use call graph
-information to perform transformations across function boundaries.
-IPA is a critical part of link-time optimization (LTO) and
-whole-program (WHOPR) optimization, and these passes are structured
-with the needs of LTO and WHOPR in mind by dividing their operations
-into stages. For detailed discussion of the LTO/WHOPR IPA pass stages
-and interfaces, see @ref{IPA}.
-
-The following briefly describes the inter-procedural optimization (IPA)
-passes, which are split into small IPA passes, regular IPA passes,
-and late IPA passes, according to the LTO/WHOPR processing model.
-
-@menu
-* Small IPA passes::
-* Regular IPA passes::
-* Late IPA passes::
-@end menu
-
-@node Small IPA passes
-@subsection Small IPA passes
-@cindex small IPA passes
-A small IPA pass is a pass derived from @code{simple_ipa_opt_pass}.
-As described in @ref{IPA}, it does everything at once and
-defines only the @emph{Execute} stage. During this
-stage it accesses and modifies the function bodies.
-No @code{generate_summary}, @code{read_summary}, or @code{write_summary}
-hooks are defined.
-
-@itemize @bullet
-@item IPA free lang data
-
-This pass frees resources that are used by the front end but are
-not needed once it is done. It is located in @file{tree.cc} and is described by
-@code{pass_ipa_free_lang_data}.
-
-@item IPA function and variable visibility
-
-This is a local function pass handling visibilities of all symbols. This
-happens before LTO streaming, so @option{-fwhole-program} should be ignored
-at this level. It is located in @file{ipa-visibility.cc} and is described by
-@code{pass_ipa_function_and_variable_visibility}.
-
-@item IPA remove symbols
-
-This pass performs reachability analysis and reclaims all unreachable nodes.
-It is located in @file{passes.cc} and is described by
-@code{pass_ipa_remove_symbols}.
-
-@item IPA OpenACC
-
-This is a pass group for OpenACC processing. It is located in
-@file{tree-ssa-loop.cc} and is described by @code{pass_ipa_oacc}.
-
-@item IPA points-to analysis
-
-This is a tree-based points-to analysis pass. The idea behind this analyzer
-is to generate set constraints from the program, then solve the resulting
-constraints in order to generate the points-to sets. It is located in
-@file{tree-ssa-structalias.cc} and is described by @code{pass_ipa_pta}.
-
-@item IPA OpenACC kernels
-
-This is a pass group for processing OpenACC kernels regions. It is a
-subpass of the IPA OpenACC pass group that runs on offloaded functions
-containing OpenACC kernels loops. It is located in
-@file{tree-ssa-loop.cc} and is described by
-@code{pass_ipa_oacc_kernels}.
-
-@item Target clone
-
-This is a pass for parsing functions with multiple target attributes.
-It is located in @file{multiple_target.cc} and is described by
-@code{pass_target_clone}.
-
-@item IPA auto profile
-
-This pass uses AutoFDO profiling data to annotate the control flow graph.
-It is located in @file{auto-profile.cc} and is described by
-@code{pass_ipa_auto_profile}.
-
-@item IPA tree profile
-
-This pass does profiling for all functions in the call graph.
-It calculates branch
-probabilities and basic block execution counts. It is located
-in @file{tree-profile.cc} and is described by @code{pass_ipa_tree_profile}.
-
-@item IPA free function summary
-
-This pass is a small IPA pass when argument @code{small_p} is true.
-It releases inline function summaries and call summaries.
-It is located in @file{ipa-fnsummary.cc} and is described by
-@code{pass_ipa_free_free_fn_summary}.
-
-@item IPA increase alignment
-
-This pass increases the alignment of global arrays to improve
-vectorization. It is located in @file{tree-vectorizer.cc}
-and is described by @code{pass_ipa_increase_alignment}.
-
-@item IPA transactional memory
-
-This pass is for transactional memory support.
-It is located in @file{trans-mem.cc} and is described by
-@code{pass_ipa_tm}.
-
-@item IPA lower emulated TLS
-
-This pass lowers thread-local storage (TLS) operations
-to emulation functions provided by libgcc.
-It is located in @file{tree-emutls.cc} and is described by
-@code{pass_ipa_lower_emutls}.
-
-@end itemize
-
-@node Regular IPA passes
-@subsection Regular IPA passes
-@cindex regular IPA passes
-
-A regular IPA pass is a pass derived from @code{ipa_opt_pass_d} that
-is executed in WHOPR compilation. Regular IPA passes may have summary
-hooks implemented in any of the LGEN, WPA or LTRANS stages (@pxref{IPA}).
-
-@itemize @bullet
-@item IPA whole program visibility
-
-This pass performs various optimizations involving symbol visibility
-with @option{-fwhole-program}, including symbol privatization,
-discovering local functions, and dismantling comdat groups. It is
-located in @file{ipa-visibility.cc} and is described by
-@code{pass_ipa_whole_program_visibility}.
-
-@item IPA profile
-
-The IPA profile pass propagates profiling frequencies across the call
-graph. It is located in @file{ipa-profile.cc} and is described by
-@code{pass_ipa_profile}.
-
-@item IPA identical code folding
-
-This is the inter-procedural identical code folding pass.
-The goal of this transformation is to discover functions
-and read-only variables that have exactly the same semantics. It is
-located in @file{ipa-icf.cc} and is described by @code{pass_ipa_icf}.
-
-@item IPA devirtualization
-
-This pass performs speculative devirtualization based on the type
-inheritance graph. When a polymorphic call has only one likely target
-in the unit, it is turned into a speculative call. It is located in
-@file{ipa-devirt.cc} and is described by @code{pass_ipa_devirt}.
-
-@item IPA constant propagation
-
-The goal of this pass is to discover functions that are always invoked
-with some arguments with the same known constant values and to modify
-the functions accordingly. It can also do partial specialization and
-type-based devirtualization. It is located in @file{ipa-cp.cc} and is
-described by @code{pass_ipa_cp}.
-
-@item IPA scalar replacement of aggregates
-
-This pass can replace an aggregate parameter with a set of other parameters
-representing part of the original, turning those passed by reference
-into new ones which pass the value directly. It also removes unused
-function return values and unused function parameters. This pass is
-located in @file{ipa-sra.cc} and is described by @code{pass_ipa_sra}.
-
-@item IPA constructor/destructor merge
-
-This pass merges multiple constructors and destructors for static
-objects into single functions. It's only run at LTO time unless the
-target doesn't support constructors and destructors natively. The
-pass is located in @file{ipa.cc} and is described by
-@code{pass_ipa_cdtor_merge}.
-
-@item IPA function summary
-
-This pass provides function analysis for inter-procedural passes.
-It collects estimates of function body size, execution time, and frame
-size for each function. It also estimates information about function
-calls: call statement size, time and how often the parameters change
-for each call. It is located in @file{ipa-fnsummary.cc} and is
-described by @code{pass_ipa_fn_summary}.
-
-@item IPA inline
-
-The IPA inline pass handles function inlining with whole-program
-knowledge. Small functions that are candidates for inlining are
-ordered in increasing badness, bounded by unit growth parameters.
-Unreachable functions are removed from the call graph. Functions called
-once and not exported from the unit are inlined. This pass is located in
-@file{ipa-inline.cc} and is described by @code{pass_ipa_inline}.
-
-@item IPA pure/const analysis
-
-This pass marks functions as being either const (@code{TREE_READONLY}) or
-pure (@code{DECL_PURE_P}). The per-function information is produced
-by @code{pure_const_generate_summary}, then the global information is computed
-by performing a transitive closure over the call graph. It is located in
-@file{ipa-pure-const.cc} and is described by @code{pass_ipa_pure_const}.
-
-@item IPA free function summary
-
-This pass is a regular IPA pass when argument @code{small_p} is false.
-It releases inline function summaries and call summaries.
-It is located in @file{ipa-fnsummary.cc} and is described by
-@code{pass_ipa_free_fn_summary}.
-
-@item IPA reference
-
-This pass gathers information about how variables whose scope is
-confined to the compilation unit are used. It is located in
-@file{ipa-reference.cc} and is described by @code{pass_ipa_reference}.
-
-@item IPA single use
-
-This pass checks whether variables are used by a single function.
-It is located in @file{ipa.cc} and is described by
-@code{pass_ipa_single_use}.
-
-@item IPA comdats
-
-This pass looks for static symbols that are used exclusively
-within one comdat group, and moves them into that comdat group. It is
-located in @file{ipa-comdats.cc} and is described by
-@code{pass_ipa_comdats}.
-
-@end itemize
-
-@node Late IPA passes
-@subsection Late IPA passes
-@cindex late IPA passes
-
-Late IPA passes are simple IPA passes executed after
-the regular passes. In WHOPR mode the passes are executed after
-partitioning and thus see just parts of the compiled unit.
-
-@itemize @bullet
-@item Materialize all clones
-
-Once all functions from compilation unit are in memory, produce all clones
-and update all calls. It is located in @file{ipa.cc} and is described by
-@code{pass_materialize_all_clones}.
-
-@item IPA points-to analysis
-
-Points-to analysis; this is the same as the points-to-analysis pass
-run with the small IPA passes (@pxref{Small IPA passes}).
-
-@item OpenMP simd clone
-
-This is the OpenMP constructs' SIMD clone pass. It creates the appropriate
-SIMD clones for functions tagged as elemental SIMD functions.
-It is located in @file{omp-simd-clone.cc} and is described by
-@code{pass_omp_simd_clone}.
-
-@end itemize
-
-@node Tree SSA passes
-@section Tree SSA passes
-
-The following briefly describes the Tree optimization passes that are
-run after gimplification and what source files they are located in.
-
-@itemize @bullet
-@item Remove useless statements
-
-This pass is an extremely simple sweep across the gimple code in which
-we identify obviously dead code and remove it. Here we do things like
-simplify @code{if} statements with constant conditions, remove
-exception handling constructs surrounding code that obviously cannot
-throw, remove lexical bindings that contain no variables, and other
-assorted simplistic cleanups. The idea is to get rid of the obvious
-stuff quickly rather than wait until later when it's more work to get
-rid of it. This pass is located in @file{tree-cfg.cc} and described by
-@code{pass_remove_useless_stmts}.
-
-@item OpenMP lowering
-
-If OpenMP generation (@option{-fopenmp}) is enabled, this pass lowers
-OpenMP constructs into GIMPLE.
-
-Lowering of OpenMP constructs involves creating replacement
-expressions for local variables that have been mapped using data
-sharing clauses, exposing the control flow of most synchronization
-directives and adding region markers to facilitate the creation of the
-control flow graph. The pass is located in @file{omp-low.cc} and is
-described by @code{pass_lower_omp}.
-
-@item OpenMP expansion
-
-If OpenMP generation (@option{-fopenmp}) is enabled, this pass expands
-parallel regions into their own functions to be invoked by the thread
-library. The pass is located in @file{omp-low.cc} and is described by
-@code{pass_expand_omp}.
-
-@item Lower control flow
-
-This pass flattens @code{if} statements (@code{COND_EXPR})
-and moves lexical bindings (@code{BIND_EXPR}) out of line. After
-this pass, all @code{if} statements will have exactly two @code{goto}
-statements in its @code{then} and @code{else} arms. Lexical binding
-information for each statement will be found in @code{TREE_BLOCK} rather
-than being inferred from its position under a @code{BIND_EXPR}. This
-pass is found in @file{gimple-low.cc} and is described by
-@code{pass_lower_cf}.
-
-@item Lower exception handling control flow
-
-This pass decomposes high-level exception handling constructs
-(@code{TRY_FINALLY_EXPR} and @code{TRY_CATCH_EXPR}) into a form
-that explicitly represents the control flow involved. After this
-pass, @code{lookup_stmt_eh_region} will return a non-negative
-number for any statement that may have EH control flow semantics;
-examine @code{tree_can_throw_internal} or @code{tree_can_throw_external}
-for exact semantics. Exact control flow may be extracted from
-@code{foreach_reachable_handler}. The EH region nesting tree is defined
-in @file{except.h} and built in @file{except.cc}. The lowering pass
-itself is in @file{tree-eh.cc} and is described by @code{pass_lower_eh}.
-
-@item Build the control flow graph
-
-This pass decomposes a function into basic blocks and creates all of
-the edges that connect them. It is located in @file{tree-cfg.cc} and
-is described by @code{pass_build_cfg}.
-
-@item Find all referenced variables
-
-This pass walks the entire function and collects an array of all
-variables referenced in the function, @code{referenced_vars}. The
-index at which a variable is found in the array is used as a UID
-for the variable within this function. This data is needed by the
-SSA rewriting routines. The pass is located in @file{tree-dfa.cc}
-and is described by @code{pass_referenced_vars}.
-
-@item Enter static single assignment form
-
-This pass rewrites the function such that it is in SSA form. After
-this pass, all @code{is_gimple_reg} variables will be referenced by
-@code{SSA_NAME}, and all occurrences of other variables will be
-annotated with @code{VDEFS} and @code{VUSES}; PHI nodes will have
-been inserted as necessary for each basic block. This pass is
-located in @file{tree-ssa.cc} and is described by @code{pass_build_ssa}.
-
-@item Warn for uninitialized variables
-
-This pass scans the function for uses of @code{SSA_NAME}s that
-are fed by default definition. For non-parameter variables, such
-uses are uninitialized. The pass is run twice, before and after
-optimization (if turned on). In the first pass we only warn for uses that are
-positively uninitialized; in the second pass we warn for uses that
-are possibly uninitialized. The pass is located in @file{tree-ssa.cc}
-and is defined by @code{pass_early_warn_uninitialized} and
-@code{pass_late_warn_uninitialized}.
-
-@item Dead code elimination
-
-This pass scans the function for statements without side effects whose
-result is unused. It does not do memory life analysis, so any value
-that is stored in memory is considered used. The pass is run multiple
-times throughout the optimization process. It is located in
-@file{tree-ssa-dce.cc} and is described by @code{pass_dce}.
-
-@item Dominator optimizations
-
-This pass performs trivial dominator-based copy and constant propagation,
-expression simplification, and jump threading. It is run multiple times
-throughout the optimization process. It is located in @file{tree-ssa-dom.cc}
-and is described by @code{pass_dominator}.
-
-@item Forward propagation of single-use variables
-
-This pass attempts to remove redundant computation by substituting
-variables that are used once into the expression that uses them and
-seeing if the result can be simplified. It is located in
-@file{tree-ssa-forwprop.cc} and is described by @code{pass_forwprop}.
-
-@item Copy Renaming
-
-This pass attempts to change the name of compiler temporaries involved in
-copy operations such that SSA->normal can coalesce the copy away. When compiler
-temporaries are copies of user variables, it also renames the compiler
-temporary to the user variable resulting in better use of user symbols. It is
-located in @file{tree-ssa-copyrename.c} and is described by
-@code{pass_copyrename}.
-
-@item PHI node optimizations
-
-This pass recognizes forms of PHI inputs that can be represented as
-conditional expressions and rewrites them into straight line code.
-It is located in @file{tree-ssa-phiopt.cc} and is described by
-@code{pass_phiopt}.
-
-@item May-alias optimization
-
-This pass performs a flow sensitive SSA-based points-to analysis.
-The resulting may-alias, must-alias, and escape analysis information
-is used to promote variables from in-memory addressable objects to
-non-aliased variables that can be renamed into SSA form. We also
-update the @code{VDEF}/@code{VUSE} memory tags for non-renameable
-aggregates so that we get fewer false kills. The pass is located
-in @file{tree-ssa-alias.cc} and is described by @code{pass_may_alias}.
-
-Interprocedural points-to information is located in
-@file{tree-ssa-structalias.cc} and described by @code{pass_ipa_pta}.
-
-@item Profiling
-
-This pass instruments the function in order to collect runtime block
-and value profiling data. Such data may be fed back into the compiler
-on a subsequent run so as to allow optimization based on expected
-execution frequencies. The pass is located in @file{tree-profile.cc} and
-is described by @code{pass_ipa_tree_profile}.
-
-@item Static profile estimation
-
-This pass implements series of heuristics to guess propababilities
-of branches. The resulting predictions are turned into edge profile
-by propagating branches across the control flow graphs.
-The pass is located in @file{tree-profile.cc} and is described by
-@code{pass_profile}.
-
-@item Lower complex arithmetic
-
-This pass rewrites complex arithmetic operations into their component
-scalar arithmetic operations. The pass is located in @file{tree-complex.cc}
-and is described by @code{pass_lower_complex}.
-
-@item Scalar replacement of aggregates
-
-This pass rewrites suitable non-aliased local aggregate variables into
-a set of scalar variables. The resulting scalar variables are
-rewritten into SSA form, which allows subsequent optimization passes
-to do a significantly better job with them. The pass is located in
-@file{tree-sra.cc} and is described by @code{pass_sra}.
-
-@item Dead store elimination
-
-This pass eliminates stores to memory that are subsequently overwritten
-by another store, without any intervening loads. The pass is located
-in @file{tree-ssa-dse.cc} and is described by @code{pass_dse}.
-
-@item Tail recursion elimination
-
-This pass transforms tail recursion into a loop. It is located in
-@file{tree-tailcall.cc} and is described by @code{pass_tail_recursion}.
-
-@item Forward store motion
-
-This pass sinks stores and assignments down the flowgraph closer to their
-use point. The pass is located in @file{tree-ssa-sink.cc} and is
-described by @code{pass_sink_code}.
-
-@item Partial redundancy elimination
-
-This pass eliminates partially redundant computations, as well as
-performing load motion. The pass is located in @file{tree-ssa-pre.cc}
-and is described by @code{pass_pre}.
-
-Just before partial redundancy elimination, if
-@option{-funsafe-math-optimizations} is on, GCC tries to convert
-divisions to multiplications by the reciprocal. The pass is located
-in @file{tree-ssa-math-opts.cc} and is described by
-@code{pass_cse_reciprocal}.
-
-@item Full redundancy elimination
-
-This is a simpler form of PRE that only eliminates redundancies that
-occur on all paths. It is located in @file{tree-ssa-pre.cc} and
-described by @code{pass_fre}.
-
-@item Loop optimization
-
-The main driver of the pass is placed in @file{tree-ssa-loop.cc}
-and described by @code{pass_loop}.
-
-The optimizations performed by this pass are:
-
-Loop invariant motion. This pass moves only invariants that
-would be hard to handle on RTL level (function calls, operations that expand to
-nontrivial sequences of insns). With @option{-funswitch-loops} it also moves
-operands of conditions that are invariant out of the loop, so that we can use
-just trivial invariantness analysis in loop unswitching. The pass also includes
-store motion. The pass is implemented in @file{tree-ssa-loop-im.cc}.
-
-Canonical induction variable creation. This pass creates a simple counter
-for number of iterations of the loop and replaces the exit condition of the
-loop using it, in case when a complicated analysis is necessary to determine
-the number of iterations. Later optimizations then may determine the number
-easily. The pass is implemented in @file{tree-ssa-loop-ivcanon.cc}.
-
-Induction variable optimizations. This pass performs standard induction
-variable optimizations, including strength reduction, induction variable
-merging and induction variable elimination. The pass is implemented in
-@file{tree-ssa-loop-ivopts.cc}.
-
-Loop unswitching. This pass moves the conditional jumps that are invariant
-out of the loops. To achieve this, a duplicate of the loop is created for
-each possible outcome of conditional jump(s). The pass is implemented in
-@file{tree-ssa-loop-unswitch.cc}.
-
-Loop splitting. If a loop contains a conditional statement that is
-always true for one part of the iteration space and false for the other
-this pass splits the loop into two, one dealing with one side the other
-only with the other, thereby removing one inner-loop conditional. The
-pass is implemented in @file{tree-ssa-loop-split.cc}.
-
-The optimizations also use various utility functions contained in
-@file{tree-ssa-loop-manip.cc}, @file{cfgloop.cc}, @file{cfgloopanal.cc} and
-@file{cfgloopmanip.cc}.
-
-Vectorization. This pass transforms loops to operate on vector types
-instead of scalar types. Data parallelism across loop iterations is exploited
-to group data elements from consecutive iterations into a vector and operate
-on them in parallel. Depending on available target support the loop is
-conceptually unrolled by a factor @code{VF} (vectorization factor), which is
-the number of elements operated upon in parallel in each iteration, and the
-@code{VF} copies of each scalar operation are fused to form a vector operation.
-Additional loop transformations such as peeling and versioning may take place
-to align the number of iterations, and to align the memory accesses in the
-loop.
-The pass is implemented in @file{tree-vectorizer.cc} (the main driver),
-@file{tree-vect-loop.cc} and @file{tree-vect-loop-manip.cc} (loop specific parts
-and general loop utilities), @file{tree-vect-slp} (loop-aware SLP
-functionality), @file{tree-vect-stmts.cc}, @file{tree-vect-data-refs.cc} and
-@file{tree-vect-slp-patterns.cc} containing the SLP pattern matcher.
-Analysis of data references is in @file{tree-data-ref.cc}.
-
-SLP Vectorization. This pass performs vectorization of straight-line code. The
-pass is implemented in @file{tree-vectorizer.cc} (the main driver),
-@file{tree-vect-slp.cc}, @file{tree-vect-stmts.cc} and
-@file{tree-vect-data-refs.cc}.
-
-Autoparallelization. This pass splits the loop iteration space to run
-into several threads. The pass is implemented in @file{tree-parloops.cc}.
-
-Graphite is a loop transformation framework based on the polyhedral
-model. Graphite stands for Gimple Represented as Polyhedra. The
-internals of this infrastructure are documented in
-@w{@uref{https://gcc.gnu.org/wiki/Graphite}}. The passes working on
-this representation are implemented in the various @file{graphite-*}
-files.
-
-@item Tree level if-conversion for vectorizer
-
-This pass applies if-conversion to simple loops to help vectorizer.
-We identify if convertible loops, if-convert statements and merge
-basic blocks in one big block. The idea is to present loop in such
-form so that vectorizer can have one to one mapping between statements
-and available vector operations. This pass is located in
-@file{tree-if-conv.cc} and is described by @code{pass_if_conversion}.
-
-@item Conditional constant propagation
-
-This pass relaxes a lattice of values in order to identify those
-that must be constant even in the presence of conditional branches.
-The pass is located in @file{tree-ssa-ccp.cc} and is described
-by @code{pass_ccp}.
-
-A related pass that works on memory loads and stores, and not just
-register values, is located in @file{tree-ssa-ccp.cc} and described by
-@code{pass_store_ccp}.
-
-@item Conditional copy propagation
-
-This is similar to constant propagation but the lattice of values is
-the ``copy-of'' relation. It eliminates redundant copies from the
-code. The pass is located in @file{tree-ssa-copy.cc} and described by
-@code{pass_copy_prop}.
-
-A related pass that works on memory copies, and not just register
-copies, is located in @file{tree-ssa-copy.cc} and described by
-@code{pass_store_copy_prop}.
-
-@item Value range propagation
-
-This transformation is similar to constant propagation but
-instead of propagating single constant values, it propagates
-known value ranges. The implementation is based on Patterson's
-range propagation algorithm (Accurate Static Branch Prediction by
-Value Range Propagation, J. R. C. Patterson, PLDI '95). In
-contrast to Patterson's algorithm, this implementation does not
-propagate branch probabilities nor it uses more than a single
-range per SSA name. This means that the current implementation
-cannot be used for branch prediction (though adapting it would
-not be difficult). The pass is located in @file{tree-vrp.cc} and is
-described by @code{pass_vrp}.
-
-@item Folding built-in functions
-
-This pass simplifies built-in functions, as applicable, with constant
-arguments or with inferable string lengths. It is located in
-@file{tree-ssa-ccp.cc} and is described by @code{pass_fold_builtins}.
-
-@item Split critical edges
-
-This pass identifies critical edges and inserts empty basic blocks
-such that the edge is no longer critical. The pass is located in
-@file{tree-cfg.cc} and is described by @code{pass_split_crit_edges}.
-
-@item Control dependence dead code elimination
-
-This pass is a stronger form of dead code elimination that can
-eliminate unnecessary control flow statements. It is located
-in @file{tree-ssa-dce.cc} and is described by @code{pass_cd_dce}.
-
-@item Tail call elimination
-
-This pass identifies function calls that may be rewritten into
-jumps. No code transformation is actually applied here, but the
-data and control flow problem is solved. The code transformation
-requires target support, and so is delayed until RTL@. In the
-meantime @code{CALL_EXPR_TAILCALL} is set indicating the possibility.
-The pass is located in @file{tree-tailcall.cc} and is described by
-@code{pass_tail_calls}. The RTL transformation is handled by
-@code{fixup_tail_calls} in @file{calls.cc}.
-
-@item Warn for function return without value
-
-For non-void functions, this pass locates return statements that do
-not specify a value and issues a warning. Such a statement may have
-been injected by falling off the end of the function. This pass is
-run last so that we have as much time as possible to prove that the
-statement is not reachable. It is located in @file{tree-cfg.cc} and
-is described by @code{pass_warn_function_return}.
-
-@item Leave static single assignment form
-
-This pass rewrites the function such that it is in normal form. At
-the same time, we eliminate as many single-use temporaries as possible,
-so the intermediate language is no longer GIMPLE, but GENERIC@. The
-pass is located in @file{tree-outof-ssa.cc} and is described by
-@code{pass_del_ssa}.
-
-@item Merge PHI nodes that feed into one another
-
-This is part of the CFG cleanup passes. It attempts to join PHI nodes
-from a forwarder CFG block into another block with PHI nodes. The
-pass is located in @file{tree-cfgcleanup.cc} and is described by
-@code{pass_merge_phi}.
-
-@item Return value optimization
-
-If a function always returns the same local variable, and that local
-variable is an aggregate type, then the variable is replaced with the
-return value for the function (i.e., the function's DECL_RESULT). This
-is equivalent to the C++ named return value optimization applied to
-GIMPLE@. The pass is located in @file{tree-nrv.cc} and is described by
-@code{pass_nrv}.
-
-@item Return slot optimization
-
-If a function returns a memory object and is called as @code{var =
-foo()}, this pass tries to change the call so that the address of
-@code{var} is sent to the caller to avoid an extra memory copy. This
-pass is located in @code{tree-nrv.cc} and is described by
-@code{pass_return_slot}.
-
-@item Optimize calls to @code{__builtin_object_size}
-
-This is a propagation pass similar to CCP that tries to remove calls
-to @code{__builtin_object_size} when the size of the object can be
-computed at compile-time. This pass is located in
-@file{tree-object-size.cc} and is described by
-@code{pass_object_sizes}.
-
-@item Loop invariant motion
-
-This pass removes expensive loop-invariant computations out of loops.
-The pass is located in @file{tree-ssa-loop.cc} and described by
-@code{pass_lim}.
-
-@item Loop nest optimizations
-
-This is a family of loop transformations that works on loop nests. It
-includes loop interchange, scaling, skewing and reversal and they are
-all geared to the optimization of data locality in array traversals
-and the removal of dependencies that hamper optimizations such as loop
-parallelization and vectorization. The pass is located in
-@file{tree-loop-linear.c} and described by
-@code{pass_linear_transform}.
-
-@item Removal of empty loops
-
-This pass removes loops with no code in them. The pass is located in
-@file{tree-ssa-loop-ivcanon.cc} and described by
-@code{pass_empty_loop}.
-
-@item Unrolling of small loops
-
-This pass completely unrolls loops with few iterations. The pass
-is located in @file{tree-ssa-loop-ivcanon.cc} and described by
-@code{pass_complete_unroll}.
-
-@item Predictive commoning
-
-This pass makes the code reuse the computations from the previous
-iterations of the loops, especially loads and stores to memory.
-It does so by storing the values of these computations to a bank
-of temporary variables that are rotated at the end of loop. To avoid
-the need for this rotation, the loop is then unrolled and the copies
-of the loop body are rewritten to use the appropriate version of
-the temporary variable. This pass is located in @file{tree-predcom.cc}
-and described by @code{pass_predcom}.
-
-@item Array prefetching
-
-This pass issues prefetch instructions for array references inside
-loops. The pass is located in @file{tree-ssa-loop-prefetch.cc} and
-described by @code{pass_loop_prefetch}.
-
-@item Reassociation
-
-This pass rewrites arithmetic expressions to enable optimizations that
-operate on them, like redundancy elimination and vectorization. The
-pass is located in @file{tree-ssa-reassoc.cc} and described by
-@code{pass_reassoc}.
-
-@item Optimization of @code{stdarg} functions
-
-This pass tries to avoid the saving of register arguments into the
-stack on entry to @code{stdarg} functions. If the function doesn't
-use any @code{va_start} macros, no registers need to be saved. If
-@code{va_start} macros are used, the @code{va_list} variables don't
-escape the function, it is only necessary to save registers that will
-be used in @code{va_arg} macros. For instance, if @code{va_arg} is
-only used with integral types in the function, floating point
-registers don't need to be saved. This pass is located in
-@code{tree-stdarg.cc} and described by @code{pass_stdarg}.
-
-@end itemize
-
-@node RTL passes
-@section RTL passes
-
-The following briefly describes the RTL generation and optimization
-passes that are run after the Tree optimization passes.
-
-@itemize @bullet
-@item RTL generation
-
-@c Avoiding overfull is tricky here.
-The source files for RTL generation include
-@file{stmt.cc},
-@file{calls.cc},
-@file{expr.cc},
-@file{explow.cc},
-@file{expmed.cc},
-@file{function.cc},
-@file{optabs.cc}
-and @file{emit-rtl.cc}.
-Also, the file
-@file{insn-emit.cc}, generated from the machine description by the
-program @code{genemit}, is used in this pass. The header file
-@file{expr.h} is used for communication within this pass.
-
-@findex genflags
-@findex gencodes
-The header files @file{insn-flags.h} and @file{insn-codes.h},
-generated from the machine description by the programs @code{genflags}
-and @code{gencodes}, tell this pass which standard names are available
-for use and which patterns correspond to them.
-
-@item Generation of exception landing pads
-
-This pass generates the glue that handles communication between the
-exception handling library routines and the exception handlers within
-the function. Entry points in the function that are invoked by the
-exception handling library are called @dfn{landing pads}. The code
-for this pass is located in @file{except.cc}.
-
-@item Control flow graph cleanup
-
-This pass removes unreachable code, simplifies jumps to next, jumps to
-jump, jumps across jumps, etc. The pass is run multiple times.
-For historical reasons, it is occasionally referred to as the ``jump
-optimization pass''. The bulk of the code for this pass is in
-@file{cfgcleanup.cc}, and there are support routines in @file{cfgrtl.cc}
-and @file{jump.cc}.
-
-@item Forward propagation of single-def values
-
-This pass attempts to remove redundant computation by substituting
-variables that come from a single definition, and
-seeing if the result can be simplified. It performs copy propagation
-and addressing mode selection. The pass is run twice, with values
-being propagated into loops only on the second run. The code is
-located in @file{fwprop.cc}.
-
-@item Common subexpression elimination
-
-This pass removes redundant computation within basic blocks, and
-optimizes addressing modes based on cost. The pass is run twice.
-The code for this pass is located in @file{cse.cc}.
-
-@item Global common subexpression elimination
-
-This pass performs two
-different types of GCSE depending on whether you are optimizing for
-size or not (LCM based GCSE tends to increase code size for a gain in
-speed, while Morel-Renvoise based GCSE does not).
-When optimizing for size, GCSE is done using Morel-Renvoise Partial
-Redundancy Elimination, with the exception that it does not try to move
-invariants out of loops---that is left to the loop optimization pass.
-If MR PRE GCSE is done, code hoisting (aka unification) is also done, as
-well as load motion.
-If you are optimizing for speed, LCM (lazy code motion) based GCSE is
-done. LCM is based on the work of Knoop, Ruthing, and Steffen. LCM
-based GCSE also does loop invariant code motion. We also perform load
-and store motion when optimizing for speed.
-Regardless of which type of GCSE is used, the GCSE pass also performs
-global constant and copy propagation.
-The source file for this pass is @file{gcse.cc}, and the LCM routines
-are in @file{lcm.cc}.
-
-@item Loop optimization
-
-This pass performs several loop related optimizations.
-The source files @file{cfgloopanal.cc} and @file{cfgloopmanip.cc} contain
-generic loop analysis and manipulation code. Initialization and finalization
-of loop structures is handled by @file{loop-init.cc}.
-A loop invariant motion pass is implemented in @file{loop-invariant.cc}.
-Basic block level optimizations---unrolling, and peeling loops---
-are implemented in @file{loop-unroll.cc}.
-Replacing of the exit condition of loops by special machine-dependent
-instructions is handled by @file{loop-doloop.cc}.
-
-@item Jump bypassing
-
-This pass is an aggressive form of GCSE that transforms the control
-flow graph of a function by propagating constants into conditional
-branch instructions. The source file for this pass is @file{gcse.cc}.
-
-@item If conversion
-
-This pass attempts to replace conditional branches and surrounding
-assignments with arithmetic, boolean value producing comparison
-instructions, and conditional move instructions. In the very last
-invocation after reload/LRA, it will generate predicated instructions
-when supported by the target. The code is located in @file{ifcvt.cc}.
-
-@item Web construction
-
-This pass splits independent uses of each pseudo-register. This can
-improve effect of the other transformation, such as CSE or register
-allocation. The code for this pass is located in @file{web.cc}.
-
-@item Instruction combination
-
-This pass attempts to combine groups of two or three instructions that
-are related by data flow into single instructions. It combines the
-RTL expressions for the instructions by substitution, simplifies the
-result using algebra, and then attempts to match the result against
-the machine description. The code is located in @file{combine.cc}.
-
-@item Mode switching optimization
-
-This pass looks for instructions that require the processor to be in a
-specific ``mode'' and minimizes the number of mode changes required to
-satisfy all users. What these modes are, and what they apply to are
-completely target-specific. The code for this pass is located in
-@file{mode-switching.cc}.
-
-@cindex modulo scheduling
-@cindex sms, swing, software pipelining
-@item Modulo scheduling
-
-This pass looks at innermost loops and reorders their instructions
-by overlapping different iterations. Modulo scheduling is performed
-immediately before instruction scheduling. The code for this pass is
-located in @file{modulo-sched.cc}.
-
-@item Instruction scheduling
-
-This pass looks for instructions whose output will not be available by
-the time that it is used in subsequent instructions. Memory loads and
-floating point instructions often have this behavior on RISC machines.
-It re-orders instructions within a basic block to try to separate the
-definition and use of items that otherwise would cause pipeline
-stalls. This pass is performed twice, before and after register
-allocation. The code for this pass is located in @file{haifa-sched.cc},
-@file{sched-deps.cc}, @file{sched-ebb.cc}, @file{sched-rgn.cc} and
-@file{sched-vis.c}.
-
-@item Register allocation
-
-These passes make sure that all occurrences of pseudo registers are
-eliminated, either by allocating them to a hard register, replacing
-them by an equivalent expression (e.g.@: a constant) or by placing
-them on the stack. This is done in several subpasses:
-
-@itemize @bullet
-@item
-The integrated register allocator (@acronym{IRA}). It is called
-integrated because coalescing, register live range splitting, and hard
-register preferencing are done on-the-fly during coloring. It also
-has better integration with the reload/LRA pass. Pseudo-registers spilled
-by the allocator or the reload/LRA have still a chance to get
-hard-registers if the reload/LRA evicts some pseudo-registers from
-hard-registers. The allocator helps to choose better pseudos for
-spilling based on their live ranges and to coalesce stack slots
-allocated for the spilled pseudo-registers. IRA is a regional
-register allocator which is transformed into Chaitin-Briggs allocator
-if there is one region. By default, IRA chooses regions using
-register pressure but the user can force it to use one region or
-regions corresponding to all loops.
-
-Source files of the allocator are @file{ira.cc}, @file{ira-build.cc},
-@file{ira-costs.cc}, @file{ira-conflicts.cc}, @file{ira-color.cc},
-@file{ira-emit.cc}, @file{ira-lives}, plus header files @file{ira.h}
-and @file{ira-int.h} used for the communication between the allocator
-and the rest of the compiler and between the IRA files.
-
-@cindex reloading
-@item
-Reloading. This pass renumbers pseudo registers with the hardware
-registers numbers they were allocated. Pseudo registers that did not
-get hard registers are replaced with stack slots. Then it finds
-instructions that are invalid because a value has failed to end up in
-a register, or has ended up in a register of the wrong kind. It fixes
-up these instructions by reloading the problematical values
-temporarily into registers. Additional instructions are generated to
-do the copying.
-
-The reload pass also optionally eliminates the frame pointer and inserts
-instructions to save and restore call-clobbered registers around calls.
-
-Source files are @file{reload.cc} and @file{reload1.cc}, plus the header
-@file{reload.h} used for communication between them.
-
-@cindex Local Register Allocator (LRA)
-@item
-This pass is a modern replacement of the reload pass. Source files
-are @file{lra.cc}, @file{lra-assign.c}, @file{lra-coalesce.cc},
-@file{lra-constraints.cc}, @file{lra-eliminations.cc},
-@file{lra-lives.cc}, @file{lra-remat.cc}, @file{lra-spills.cc}, the
-header @file{lra-int.h} used for communication between them, and the
-header @file{lra.h} used for communication between LRA and the rest of
-compiler.
-
-Unlike the reload pass, intermediate LRA decisions are reflected in
-RTL as much as possible. This reduces the number of target-dependent
-macros and hooks, leaving instruction constraints as the primary
-source of control.
-
-LRA is run on targets for which TARGET_LRA_P returns true.
-@end itemize
-
-@item Basic block reordering
-
-This pass implements profile guided code positioning. If profile
-information is not available, various types of static analysis are
-performed to make the predictions normally coming from the profile
-feedback (IE execution frequency, branch probability, etc). It is
-implemented in the file @file{bb-reorder.cc}, and the various
-prediction routines are in @file{predict.cc}.
-
-@item Variable tracking
-
-This pass computes where the variables are stored at each
-position in code and generates notes describing the variable locations
-to RTL code. The location lists are then generated according to these
-notes to debug information if the debugging information format supports
-location lists. The code is located in @file{var-tracking.cc}.
-
-@item Delayed branch scheduling
-
-This optional pass attempts to find instructions that can go into the
-delay slots of other instructions, usually jumps and calls. The code
-for this pass is located in @file{reorg.cc}.
-
-@item Branch shortening
-
-On many RISC machines, branch instructions have a limited range.
-Thus, longer sequences of instructions must be used for long branches.
-In this pass, the compiler figures out what how far each instruction
-will be from each other instruction, and therefore whether the usual
-instructions, or the longer sequences, must be used for each branch.
-The code for this pass is located in @file{final.cc}.
-
-@item Register-to-stack conversion
-
-Conversion from usage of some hard registers to usage of a register
-stack may be done at this point. Currently, this is supported only
-for the floating-point registers of the Intel 80387 coprocessor. The
-code for this pass is located in @file{reg-stack.cc}.
-
-@item Final
-
-This pass outputs the assembler code for the function. The source files
-are @file{final.cc} plus @file{insn-output.cc}; the latter is generated
-automatically from the machine description by the tool @file{genoutput}.
-The header file @file{conditions.h} is used for communication between
-these files.
-
-@item Debugging information output
-
-This is run after final because it must output the stack slot offsets
-for pseudo registers that did not get hard registers. Source files
-are @file{dwarfout.c} for
-DWARF symbol table format, files @file{dwarf2out.cc} and @file{dwarf2asm.cc}
-for DWARF2 symbol table format, and @file{vmsdbgout.cc} for VMS debug
-symbol table format.
-
-@end itemize
-
-@node Optimization info
-@section Optimization info
-@include optinfo.texi
+++ /dev/null
-@c Copyright (C) 2009-2022 Free Software Foundation, Inc.
-@c Free Software Foundation, Inc.
-@c This is part of the GCC manual.
-@c For copying conditions, see the file gcc.texi.
-
-@node Plugins
-@chapter Plugins
-@cindex Plugins
-
-GCC plugins are loadable modules that provide extra features to the
-compiler. Like GCC itself they can be distributed in source and
-binary forms.
-
-GCC plugins provide developers with a rich subset of
-the GCC API to allow them to extend GCC as they see fit.
-Whether it is writing an additional optimization pass,
-transforming code, or analyzing information, plugins
-can be quite useful.
-
-@menu
-* Plugins loading:: How can we load plugins.
-* Plugin API:: The APIs for plugins.
-* Plugins pass:: How a plugin interact with the pass manager.
-* Plugins GC:: How a plugin Interact with GCC Garbage Collector.
-* Plugins description:: Giving information about a plugin itself.
-* Plugins attr:: Registering custom attributes or pragmas.
-* Plugins recording:: Recording information about pass execution.
-* Plugins gate:: Controlling which passes are being run.
-* Plugins tracking:: Keeping track of available passes.
-* Plugins building:: How can we build a plugin.
-@end menu
-
-@node Plugins loading
-@section Loading Plugins
-
-Plugins are supported on platforms that support @option{-ldl
--rdynamic} as well as Windows/MinGW. They are loaded by the compiler
-using @code{dlopen} or equivalent and invoked at pre-determined
-locations in the compilation process.
-
-Plugins are loaded with
-
-@option{-fplugin=/path/to/@var{name}.@var{ext}} @option{-fplugin-arg-@var{name}-@var{key1}[=@var{value1}]}
-
-Where @var{name} is the plugin name and @var{ext} is the platform-specific
-dynamic library extension. It should be @code{dll} on Windows/MinGW,
-@code{dylib} on Darwin/Mac OS X, and @code{so} on all other platforms.
-The plugin arguments are parsed by GCC and passed to respective
-plugins as key-value pairs. Multiple plugins can be invoked by
-specifying multiple @option{-fplugin} arguments.
-
-A plugin can be simply given by its short name (no dots or
-slashes). When simply passing @option{-fplugin=@var{name}}, the plugin is
-loaded from the @file{plugin} directory, so @option{-fplugin=@var{name}} is
-the same as @option{-fplugin=`gcc -print-file-name=plugin`/@var{name}.@var{ext}},
-using backquote shell syntax to query the @file{plugin} directory.
-
-@node Plugin API
-@section Plugin API
-
-Plugins are activated by the compiler at specific events as defined in
-@file{gcc-plugin.h}. For each event of interest, the plugin should
-call @code{register_callback} specifying the name of the event and
-address of the callback function that will handle that event.
-
-The header @file{gcc-plugin.h} must be the first gcc header to be included.
-
-@subsection Plugin license check
-
-Every plugin should define the global symbol @code{plugin_is_GPL_compatible}
-to assert that it has been licensed under a GPL-compatible license.
-If this symbol does not exist, the compiler will emit a fatal error
-and exit with the error message:
-
-@smallexample
-fatal error: plugin @var{name} is not licensed under a GPL-compatible license
-@var{name}: undefined symbol: plugin_is_GPL_compatible
-compilation terminated
-@end smallexample
-
-The declared type of the symbol should be int, to match a forward declaration
-in @file{gcc-plugin.h} that suppresses C++ mangling. It does not need to be in
-any allocated section, though. The compiler merely asserts that
-the symbol exists in the global scope. Something like this is enough:
-
-@smallexample
-int plugin_is_GPL_compatible;
-@end smallexample
-
-@subsection Plugin initialization
-
-Every plugin should export a function called @code{plugin_init} that
-is called right after the plugin is loaded. This function is
-responsible for registering all the callbacks required by the plugin
-and do any other required initialization.
-
-This function is called from @code{compile_file} right before invoking
-the parser. The arguments to @code{plugin_init} are:
-
-@itemize @bullet
-@item @code{plugin_info}: Plugin invocation information.
-@item @code{version}: GCC version.
-@end itemize
-
-The @code{plugin_info} struct is defined as follows:
-
-@smallexample
-struct plugin_name_args
-@{
- char *base_name; /* Short name of the plugin
- (filename without .so suffix). */
- const char *full_name; /* Path to the plugin as specified with
- -fplugin=. */
- int argc; /* Number of arguments specified with
- -fplugin-arg-.... */
- struct plugin_argument *argv; /* Array of ARGC key-value pairs. */
- const char *version; /* Version string provided by plugin. */
- const char *help; /* Help string provided by plugin. */
-@}
-@end smallexample
-
-If initialization fails, @code{plugin_init} must return a non-zero
-value. Otherwise, it should return 0.
-
-The version of the GCC compiler loading the plugin is described by the
-following structure:
-
-@smallexample
-struct plugin_gcc_version
-@{
- const char *basever;
- const char *datestamp;
- const char *devphase;
- const char *revision;
- const char *configuration_arguments;
-@};
-@end smallexample
-
-The function @code{plugin_default_version_check} takes two pointers to
-such structure and compare them field by field. It can be used by the
-plugin's @code{plugin_init} function.
-
-The version of GCC used to compile the plugin can be found in the symbol
-@code{gcc_version} defined in the header @file{plugin-version.h}. The
-recommended version check to perform looks like
-
-@smallexample
-#include "plugin-version.h"
-...
-
-int
-plugin_init (struct plugin_name_args *plugin_info,
- struct plugin_gcc_version *version)
-@{
- if (!plugin_default_version_check (version, &gcc_version))
- return 1;
-
-@}
-@end smallexample
-
-but you can also check the individual fields if you want a less strict check.
-
-@subsection Plugin callbacks
-
-Callback functions have the following prototype:
-
-@smallexample
-/* The prototype for a plugin callback function.
- gcc_data - event-specific data provided by GCC
- user_data - plugin-specific data provided by the plug-in. */
-typedef void (*plugin_callback_func)(void *gcc_data, void *user_data);
-@end smallexample
-
-Callbacks can be invoked at the following pre-determined events:
-
-
-@smallexample
-enum plugin_event
-@{
- PLUGIN_START_PARSE_FUNCTION, /* Called before parsing the body of a function. */
- PLUGIN_FINISH_PARSE_FUNCTION, /* After finishing parsing a function. */
- PLUGIN_PASS_MANAGER_SETUP, /* To hook into pass manager. */
- PLUGIN_FINISH_TYPE, /* After finishing parsing a type. */
- PLUGIN_FINISH_DECL, /* After finishing parsing a declaration. */
- PLUGIN_FINISH_UNIT, /* Useful for summary processing. */
- PLUGIN_PRE_GENERICIZE, /* Allows to see low level AST in C and C++ frontends. */
- PLUGIN_FINISH, /* Called before GCC exits. */
- PLUGIN_INFO, /* Information about the plugin. */
- PLUGIN_GGC_START, /* Called at start of GCC Garbage Collection. */
- PLUGIN_GGC_MARKING, /* Extend the GGC marking. */
- PLUGIN_GGC_END, /* Called at end of GGC. */
- PLUGIN_REGISTER_GGC_ROOTS, /* Register an extra GGC root table. */
- PLUGIN_ATTRIBUTES, /* Called during attribute registration */
- PLUGIN_START_UNIT, /* Called before processing a translation unit. */
- PLUGIN_PRAGMAS, /* Called during pragma registration. */
- /* Called before first pass from all_passes. */
- PLUGIN_ALL_PASSES_START,
- /* Called after last pass from all_passes. */
- PLUGIN_ALL_PASSES_END,
- /* Called before first ipa pass. */
- PLUGIN_ALL_IPA_PASSES_START,
- /* Called after last ipa pass. */
- PLUGIN_ALL_IPA_PASSES_END,
- /* Allows to override pass gate decision for current_pass. */
- PLUGIN_OVERRIDE_GATE,
- /* Called before executing a pass. */
- PLUGIN_PASS_EXECUTION,
- /* Called before executing subpasses of a GIMPLE_PASS in
- execute_ipa_pass_list. */
- PLUGIN_EARLY_GIMPLE_PASSES_START,
- /* Called after executing subpasses of a GIMPLE_PASS in
- execute_ipa_pass_list. */
- PLUGIN_EARLY_GIMPLE_PASSES_END,
- /* Called when a pass is first instantiated. */
- PLUGIN_NEW_PASS,
-/* Called when a file is #include-d or given via the #line directive.
- This could happen many times. The event data is the included file path,
- as a const char* pointer. */
- PLUGIN_INCLUDE_FILE,
-
- /* Called when -fanalyzer starts. The event data is an
- ana::plugin_analyzer_init_iface *. */
- PLUGIN_ANALYZER_INIT,
-
- PLUGIN_EVENT_FIRST_DYNAMIC /* Dummy event used for indexing callback
- array. */
-@};
-@end smallexample
-
-In addition, plugins can also look up the enumerator of a named event,
-and / or generate new events dynamically, by calling the function
-@code{get_named_event_id}.
-
-To register a callback, the plugin calls @code{register_callback} with
-the arguments:
-
-@itemize
-@item @code{char *name}: Plugin name.
-@item @code{int event}: The event code.
-@item @code{plugin_callback_func callback}: The function that handles @code{event}.
-@item @code{void *user_data}: Pointer to plugin-specific data.
-@end itemize
-
-For the @i{PLUGIN_PASS_MANAGER_SETUP}, @i{PLUGIN_INFO}, and
-@i{PLUGIN_REGISTER_GGC_ROOTS} pseudo-events the @code{callback} should be null,
-and the @code{user_data} is specific.
-
-When the @i{PLUGIN_PRAGMAS} event is triggered (with a null pointer as
-data from GCC), plugins may register their own pragmas. Notice that
-pragmas are not available from @file{lto1}, so plugins used with
-@code{-flto} option to GCC during link-time optimization cannot use
-pragmas and do not even see functions like @code{c_register_pragma} or
-@code{pragma_lex}.
-
-The @i{PLUGIN_INCLUDE_FILE} event, with a @code{const char*} file path as
-GCC data, is triggered for processing of @code{#include} or
-@code{#line} directives.
-
-The @i{PLUGIN_FINISH} event is the last time that plugins can call GCC
-functions, notably emit diagnostics with @code{warning}, @code{error}
-etc.
-
-
-@node Plugins pass
-@section Interacting with the pass manager
-
-There needs to be a way to add/reorder/remove passes dynamically. This
-is useful for both analysis plugins (plugging in after a certain pass
-such as CFG or an IPA pass) and optimization plugins.
-
-Basic support for inserting new passes or replacing existing passes is
-provided. A plugin registers a new pass with GCC by calling
-@code{register_callback} with the @code{PLUGIN_PASS_MANAGER_SETUP}
-event and a pointer to a @code{struct register_pass_info} object defined as follows
-
-@smallexample
-enum pass_positioning_ops
-@{
- PASS_POS_INSERT_AFTER, // Insert after the reference pass.
- PASS_POS_INSERT_BEFORE, // Insert before the reference pass.
- PASS_POS_REPLACE // Replace the reference pass.
-@};
-
-struct register_pass_info
-@{
- struct opt_pass *pass; /* New pass provided by the plugin. */
- const char *reference_pass_name; /* Name of the reference pass for hooking
- up the new pass. */
- int ref_pass_instance_number; /* Insert the pass at the specified
- instance number of the reference pass. */
- /* Do it for every instance if it is 0. */
- enum pass_positioning_ops pos_op; /* how to insert the new pass. */
-@};
-
-
-/* Sample plugin code that registers a new pass. */
-int
-plugin_init (struct plugin_name_args *plugin_info,
- struct plugin_gcc_version *version)
-@{
- struct register_pass_info pass_info;
-
- ...
-
- /* Code to fill in the pass_info object with new pass information. */
-
- ...
-
- /* Register the new pass. */
- register_callback (plugin_info->base_name, PLUGIN_PASS_MANAGER_SETUP, NULL, &pass_info);
-
- ...
-@}
-@end smallexample
-
-
-@node Plugins GC
-@section Interacting with the GCC Garbage Collector
-
-Some plugins may want to be informed when GGC (the GCC Garbage
-Collector) is running. They can register callbacks for the
-@code{PLUGIN_GGC_START} and @code{PLUGIN_GGC_END} events (for which
-the callback is called with a null @code{gcc_data}) to be notified of
-the start or end of the GCC garbage collection.
-
-Some plugins may need to have GGC mark additional data. This can be
-done by registering a callback (called with a null @code{gcc_data})
-for the @code{PLUGIN_GGC_MARKING} event. Such callbacks can call the
-@code{ggc_set_mark} routine, preferably through the @code{ggc_mark} macro
-(and conversely, these routines should usually not be used in plugins
-outside of the @code{PLUGIN_GGC_MARKING} event). Plugins that wish to hold
-weak references to gc data may also use this event to drop weak references when
-the object is about to be collected. The @code{ggc_marked_p} function can be
-used to tell if an object is marked, or is about to be collected. The
-@code{gt_clear_cache} overloads which some types define may also be of use in
-managing weak references.
-
-Some plugins may need to add extra GGC root tables, e.g.@: to handle their own
-@code{GTY}-ed data. This can be done with the @code{PLUGIN_REGISTER_GGC_ROOTS}
-pseudo-event with a null callback and the extra root table (of type @code{struct
-ggc_root_tab*}) as @code{user_data}. Running the
- @code{gengtype -p @var{source-dir} @var{file-list} @var{plugin*.c} ...}
-utility generates these extra root tables.
-
-You should understand the details of memory management inside GCC
-before using @code{PLUGIN_GGC_MARKING} or @code{PLUGIN_REGISTER_GGC_ROOTS}.
-
-
-@node Plugins description
-@section Giving information about a plugin
-
-A plugin should give some information to the user about itself. This
-uses the following structure:
-
-@smallexample
-struct plugin_info
-@{
- const char *version;
- const char *help;
-@};
-@end smallexample
-
-Such a structure is passed as the @code{user_data} by the plugin's
-init routine using @code{register_callback} with the
-@code{PLUGIN_INFO} pseudo-event and a null callback.
-
-@node Plugins attr
-@section Registering custom attributes or pragmas
-
-For analysis (or other) purposes it is useful to be able to add custom
-attributes or pragmas.
-
-The @code{PLUGIN_ATTRIBUTES} callback is called during attribute
-registration. Use the @code{register_attribute} function to register
-custom attributes.
-
-@smallexample
-/* Attribute handler callback */
-static tree
-handle_user_attribute (tree *node, tree name, tree args,
- int flags, bool *no_add_attrs)
-@{
- return NULL_TREE;
-@}
-
-/* Attribute definition */
-static struct attribute_spec user_attr =
- @{ "user", 1, 1, false, false, false, false, handle_user_attribute, NULL @};
-
-/* Plugin callback called during attribute registration.
-Registered with register_callback (plugin_name, PLUGIN_ATTRIBUTES, register_attributes, NULL)
-*/
-static void
-register_attributes (void *event_data, void *data)
-@{
- warning (0, G_("Callback to register attributes"));
- register_attribute (&user_attr);
-@}
-
-@end smallexample
-
-
-The @i{PLUGIN_PRAGMAS} callback is called once during pragmas
-registration. Use the @code{c_register_pragma},
-@code{c_register_pragma_with_data},
-@code{c_register_pragma_with_expansion},
-@code{c_register_pragma_with_expansion_and_data} functions to register
-custom pragmas and their handlers (which often want to call
-@code{pragma_lex}) from @file{c-family/c-pragma.h}.
-
-@smallexample
-/* Plugin callback called during pragmas registration. Registered with
- register_callback (plugin_name, PLUGIN_PRAGMAS,
- register_my_pragma, NULL);
-*/
-static void
-register_my_pragma (void *event_data, void *data)
-@{
- warning (0, G_("Callback to register pragmas"));
- c_register_pragma ("GCCPLUGIN", "sayhello", handle_pragma_sayhello);
-@}
-@end smallexample
-
-It is suggested to pass @code{"GCCPLUGIN"} (or a short name identifying
-your plugin) as the ``space'' argument of your pragma.
-
-Pragmas registered with @code{c_register_pragma_with_expansion} or
-@code{c_register_pragma_with_expansion_and_data} support
-preprocessor expansions. For example:
-
-@smallexample
-#define NUMBER 10
-#pragma GCCPLUGIN foothreshold (NUMBER)
-@end smallexample
-
-@node Plugins recording
-@section Recording information about pass execution
-
-The event PLUGIN_PASS_EXECUTION passes the pointer to the executed pass
-(the same as current_pass) as @code{gcc_data} to the callback. You can also
-inspect cfun to find out about which function this pass is executed for.
-Note that this event will only be invoked if the gate check (if
-applicable, modified by PLUGIN_OVERRIDE_GATE) succeeds.
-You can use other hooks, like @code{PLUGIN_ALL_PASSES_START},
-@code{PLUGIN_ALL_PASSES_END}, @code{PLUGIN_ALL_IPA_PASSES_START},
-@code{PLUGIN_ALL_IPA_PASSES_END}, @code{PLUGIN_EARLY_GIMPLE_PASSES_START},
-and/or @code{PLUGIN_EARLY_GIMPLE_PASSES_END} to manipulate global state
-in your plugin(s) in order to get context for the pass execution.
-
-
-@node Plugins gate
-@section Controlling which passes are being run
-
-After the original gate function for a pass is called, its result
-- the gate status - is stored as an integer.
-Then the event @code{PLUGIN_OVERRIDE_GATE} is invoked, with a pointer
-to the gate status in the @code{gcc_data} parameter to the callback function.
-A nonzero value of the gate status means that the pass is to be executed.
-You can both read and write the gate status via the passed pointer.
-
-
-@node Plugins tracking
-@section Keeping track of available passes
-
-When your plugin is loaded, you can inspect the various
-pass lists to determine what passes are available. However, other
-plugins might add new passes. Also, future changes to GCC might cause
-generic passes to be added after plugin loading.
-When a pass is first added to one of the pass lists, the event
-@code{PLUGIN_NEW_PASS} is invoked, with the callback parameter
-@code{gcc_data} pointing to the new pass.
-
-
-@node Plugins building
-@section Building GCC plugins
-
-If plugins are enabled, GCC installs the headers needed to build a
-plugin (somewhere in the installation tree, e.g.@: under
-@file{/usr/local}). In particular a @file{plugin/include} directory
-is installed, containing all the header files needed to build plugins.
-
-On most systems, you can query this @code{plugin} directory by
-invoking @command{gcc -print-file-name=plugin} (replace if needed
-@command{gcc} with the appropriate program path).
-
-Inside plugins, this @code{plugin} directory name can be queried by
-calling @code{default_plugin_dir_name ()}.
-
-Plugins may know, when they are compiled, the GCC version for which
-@file{plugin-version.h} is provided. The constant macros
-@code{GCCPLUGIN_VERSION_MAJOR}, @code{GCCPLUGIN_VERSION_MINOR},
-@code{GCCPLUGIN_VERSION_PATCHLEVEL}, @code{GCCPLUGIN_VERSION} are
-integer numbers, so a plugin could ensure it is built for GCC 4.7 with
-@smallexample
-#if GCCPLUGIN_VERSION != 4007
-#error this GCC plugin is for GCC 4.7
-#endif
-@end smallexample
-
-The following GNU Makefile excerpt shows how to build a simple plugin:
-
-@smallexample
-HOST_GCC=g++
-TARGET_GCC=gcc
-PLUGIN_SOURCE_FILES= plugin1.c plugin2.cc
-GCCPLUGINS_DIR:= $(shell $(TARGET_GCC) -print-file-name=plugin)
-CXXFLAGS+= -I$(GCCPLUGINS_DIR)/include -fPIC -fno-rtti -O2
-
-plugin.so: $(PLUGIN_SOURCE_FILES)
- $(HOST_GCC) -shared $(CXXFLAGS) $^ -o $@@
-@end smallexample
-
-A single source file plugin may be built with @code{g++ -I`gcc
--print-file-name=plugin`/include -fPIC -shared -fno-rtti -O2 plugin.cc -o
-plugin.so}, using backquote shell syntax to query the @file{plugin}
-directory.
-
-Plugin support on Windows/MinGW has a number of limitations and
-additional requirements. When building a plugin on Windows we have to
-link an import library for the corresponding backend executable, for
-example, @file{cc1.exe}, @file{cc1plus.exe}, etc., in order to gain
-access to the symbols provided by GCC. This means that on Windows a
-plugin is language-specific, for example, for C, C++, etc. If you wish
-to use your plugin with multiple languages, then you will need to
-build multiple plugin libraries and either instruct your users on how
-to load the correct version or provide a compiler wrapper that does
-this automatically.
-
-Additionally, on Windows the plugin library has to export the
-@code{plugin_is_GPL_compatible} and @code{plugin_init} symbols. If you
-do not wish to modify the source code of your plugin, then you can use
-the @option{-Wl,--export-all-symbols} option or provide a suitable DEF
-file. Alternatively, you can export just these two symbols by decorating
-them with @code{__declspec(dllexport)}, for example:
-
-@smallexample
-#ifdef _WIN32
-__declspec(dllexport)
-#endif
-int plugin_is_GPL_compatible;
-
-#ifdef _WIN32
-__declspec(dllexport)
-#endif
-int plugin_init (plugin_name_args *, plugin_gcc_version *)
-@end smallexample
-
-The import libraries are installed into the @code{plugin} directory
-and their names are derived by appending the @code{.a} extension to
-the backend executable names, for example, @file{cc1.exe.a},
-@file{cc1plus.exe.a}, etc. The following command line shows how to
-build the single source file plugin on Windows to be used with the C++
-compiler:
-
-@smallexample
-g++ -I`gcc -print-file-name=plugin`/include -shared -Wl,--export-all-symbols \
--o plugin.dll plugin.cc `gcc -print-file-name=plugin`/cc1plus.exe.a
-@end smallexample
-
-When a plugin needs to use @command{gengtype}, be sure that both
-@file{gengtype} and @file{gtype.state} have the same version as the
-GCC for which the plugin is built.
+++ /dev/null
-@node poly_int
-@chapter Sizes and offsets as runtime invariants
-@cindex polynomial integers
-@findex poly_int
-
-GCC allows the size of a hardware register to be a runtime invariant
-rather than a compile-time constant. This in turn means that various
-sizes and offsets must also be runtime invariants rather than
-compile-time constants, such as:
-
-@itemize @bullet
-@item
-the size of a general @code{machine_mode} (@pxref{Machine Modes});
-
-@item
-the size of a spill slot;
-
-@item
-the offset of something within a stack frame;
-
-@item
-the number of elements in a vector;
-
-@item
-the size and offset of a @code{mem} rtx (@pxref{Regs and Memory}); and
-
-@item
-the byte offset in a @code{subreg} rtx (@pxref{Regs and Memory}).
-@end itemize
-
-The motivating example is the Arm SVE ISA, whose vector registers can be
-any multiple of 128 bits between 128 and 2048 inclusive. The compiler
-normally produces code that works for all SVE register sizes, with the
-actual size only being known at runtime.
-
-GCC's main representation of such runtime invariants is the
-@code{poly_int} class. This chapter describes what @code{poly_int}
-does, lists the available operations, and gives some general
-usage guidelines.
-
-@menu
-* Overview of @code{poly_int}::
-* Consequences of using @code{poly_int}::
-* Comparisons involving @code{poly_int}::
-* Arithmetic on @code{poly_int}s::
-* Alignment of @code{poly_int}s::
-* Computing bounds on @code{poly_int}s::
-* Converting @code{poly_int}s::
-* Miscellaneous @code{poly_int} routines::
-* Guidelines for using @code{poly_int}::
-@end menu
-
-@node Overview of @code{poly_int}
-@section Overview of @code{poly_int}
-
-@cindex @code{poly_int}, runtime value
-We define indeterminates @var{x1}, @dots{}, @var{xn} whose values are
-only known at runtime and use polynomials of the form:
-
-@smallexample
-@var{c0} + @var{c1} * @var{x1} + @dots{} + @var{cn} * @var{xn}
-@end smallexample
-
-to represent a size or offset whose value might depend on some
-of these indeterminates. The coefficients @var{c0}, @dots{}, @var{cn}
-are always known at compile time, with the @var{c0} term being the
-``constant'' part that does not depend on any runtime value.
-
-GCC uses the @code{poly_int} class to represent these coefficients.
-The class has two template parameters: the first specifies the number of
-coefficients (@var{n} + 1) and the second specifies the type of the
-coefficients. For example, @samp{poly_int<2, unsigned short>} represents
-a polynomial with two coefficients (and thus one indeterminate), with each
-coefficient having type @code{unsigned short}. When @var{n} is 0,
-the class degenerates to a single compile-time constant @var{c0}.
-
-@cindex @code{poly_int}, template parameters
-@findex NUM_POLY_INT_COEFFS
-The number of coefficients needed for compilation is a fixed
-property of each target and is specified by the configuration macro
-@code{NUM_POLY_INT_COEFFS}. The default value is 1, since most targets
-do not have such runtime invariants. Targets that need a different
-value should @code{#define} the macro in their @file{@var{cpu}-modes.def}
-file. @xref{Back End}.
-
-@cindex @code{poly_int}, invariant range
-@code{poly_int} makes the simplifying requirement that each indeterminate
-must be a nonnegative integer. An indeterminate value of 0 should usually
-represent the minimum possible runtime value, with @var{c0} specifying
-the value in that case.
-
-For example, when targetting the Arm SVE ISA, the single indeterminate
-represents the number of 128-bit blocks in a vector @emph{beyond the minimum
-length of 128 bits}. Thus the number of 64-bit doublewords in a vector
-is 2 + 2 * @var{x1}. If an aggregate has a single SVE vector and 16
-additional bytes, its total size is 32 + 16 * @var{x1} bytes.
-
-The header file @file{poly-int-types.h} provides typedefs for the
-most common forms of @code{poly_int}, all having
-@code{NUM_POLY_INT_COEFFS} coefficients:
-
-@cindex @code{poly_int}, main typedefs
-@table @code
-@item poly_uint16
-a @samp{poly_int} with @code{unsigned short} coefficients.
-
-@item poly_int64
-a @samp{poly_int} with @code{HOST_WIDE_INT} coefficients.
-
-@item poly_uint64
-a @samp{poly_int} with @code{unsigned HOST_WIDE_INT} coefficients.
-
-@item poly_offset_int
-a @samp{poly_int} with @code{offset_int} coefficients.
-
-@item poly_wide_int
-a @samp{poly_int} with @code{wide_int} coefficients.
-
-@item poly_widest_int
-a @samp{poly_int} with @code{widest_int} coefficients.
-@end table
-
-Since the main purpose of @code{poly_int} is to represent sizes and
-offsets, the last two typedefs are only rarely used.
-
-@node Consequences of using @code{poly_int}
-@section Consequences of using @code{poly_int}
-
-The two main consequences of using polynomial sizes and offsets are that:
-
-@itemize
-@item
-there is no total ordering between the values at compile time, and
-
-@item
-some operations might yield results that cannot be expressed as a
-@code{poly_int}.
-@end itemize
-
-For example, if @var{x} is a runtime invariant, we cannot tell at
-compile time whether:
-
-@smallexample
-3 + 4@var{x} <= 1 + 5@var{x}
-@end smallexample
-
-since the condition is false when @var{x} <= 1 and true when @var{x} >= 2.
-
-Similarly, @code{poly_int} cannot represent the result of:
-
-@smallexample
-(3 + 4@var{x}) * (1 + 5@var{x})
-@end smallexample
-
-since it cannot (and in practice does not need to) store powers greater
-than one. It also cannot represent the result of:
-
-@smallexample
-(3 + 4@var{x}) / (1 + 5@var{x})
-@end smallexample
-
-The following sections describe how we deal with these restrictions.
-
-@cindex @code{poly_int}, use in target-independent code
-As described earlier, a @code{poly_int<1, @var{T}>} has no indeterminates
-and so degenerates to a compile-time constant of type @var{T}. It would
-be possible in that case to do all normal arithmetic on the @var{T},
-and to compare the @var{T} using the normal C++ operators. We deliberately
-prevent target-independent code from doing this, since the compiler needs
-to support other @code{poly_int<@var{n}, @var{T}>} as well, regardless of
-the current target's @code{NUM_POLY_INT_COEFFS}.
-
-@cindex @code{poly_int}, use in target-specific code
-However, it would be very artificial to force target-specific code
-to follow these restrictions if the target has no runtime indeterminates.
-There is therefore an implicit conversion from @code{poly_int<1, @var{T}>}
-to @var{T} when compiling target-specific translation units.
-
-@node Comparisons involving @code{poly_int}
-@section Comparisons involving @code{poly_int}
-
-In general we need to compare sizes and offsets in two situations:
-those in which the values need to be ordered, and those in which
-the values can be unordered. More loosely, the distinction is often
-between values that have a definite link (usually because they refer to the
-same underlying register or memory location) and values that have
-no definite link. An example of the former is the relationship between
-the inner and outer sizes of a subreg, where we must know at compile time
-whether the subreg is paradoxical, partial, or complete. An example of
-the latter is alias analysis: we might want to check whether two
-arbitrary memory references overlap.
-
-Referring back to the examples in the previous section, it makes sense
-to ask whether a memory reference of size @samp{3 + 4@var{x}} overlaps
-one of size @samp{1 + 5@var{x}}, but it does not make sense to have a
-subreg in which the outer mode has @samp{3 + 4@var{x}} bytes and the
-inner mode has @samp{1 + 5@var{x}} bytes (or vice versa). Such subregs
-are always invalid and should trigger an internal compiler error
-if formed.
-
-The underlying operators are the same in both cases, but the distinction
-affects how they are used.
-
-@menu
-* Comparison functions for @code{poly_int}::
-* Properties of the @code{poly_int} comparisons::
-* Comparing potentially-unordered @code{poly_int}s::
-* Comparing ordered @code{poly_int}s::
-* Checking for a @code{poly_int} marker value::
-* Range checks on @code{poly_int}s::
-* Sorting @code{poly_int}s::
-@end menu
-
-@node Comparison functions for @code{poly_int}
-@subsection Comparison functions for @code{poly_int}
-
-@code{poly_int} provides the following routines for checking whether
-a particular condition ``may be'' (might be) true:
-
-@example
-maybe_lt maybe_le maybe_eq maybe_ge maybe_gt
- maybe_ne
-@end example
-
-The functions have their natural meaning:
-
-@table @samp
-@item maybe_lt(@var{a}, @var{b})
-Return true if @var{a} might be less than @var{b}.
-
-@item maybe_le(@var{a}, @var{b})
-Return true if @var{a} might be less than or equal to @var{b}.
-
-@item maybe_eq(@var{a}, @var{b})
-Return true if @var{a} might be equal to @var{b}.
-
-@item maybe_ne(@var{a}, @var{b})
-Return true if @var{a} might not be equal to @var{b}.
-
-@item maybe_ge(@var{a}, @var{b})
-Return true if @var{a} might be greater than or equal to @var{b}.
-
-@item maybe_gt(@var{a}, @var{b})
-Return true if @var{a} might be greater than @var{b}.
-@end table
-
-For readability, @code{poly_int} also provides ``known'' inverses of these
-functions:
-
-@example
-known_lt (@var{a}, @var{b}) == !maybe_ge (@var{a}, @var{b})
-known_le (@var{a}, @var{b}) == !maybe_gt (@var{a}, @var{b})
-known_eq (@var{a}, @var{b}) == !maybe_ne (@var{a}, @var{b})
-known_ge (@var{a}, @var{b}) == !maybe_lt (@var{a}, @var{b})
-known_gt (@var{a}, @var{b}) == !maybe_le (@var{a}, @var{b})
-known_ne (@var{a}, @var{b}) == !maybe_eq (@var{a}, @var{b})
-@end example
-
-@node Properties of the @code{poly_int} comparisons
-@subsection Properties of the @code{poly_int} comparisons
-
-All ``maybe'' relations except @code{maybe_ne} are transitive, so for example:
-
-@smallexample
-maybe_lt (@var{a}, @var{b}) && maybe_lt (@var{b}, @var{c}) implies maybe_lt (@var{a}, @var{c})
-@end smallexample
-
-for all @var{a}, @var{b} and @var{c}. @code{maybe_lt}, @code{maybe_gt}
-and @code{maybe_ne} are irreflexive, so for example:
-
-@smallexample
-!maybe_lt (@var{a}, @var{a})
-@end smallexample
-
-is true for all @var{a}. @code{maybe_le}, @code{maybe_eq} and @code{maybe_ge}
-are reflexive, so for example:
-
-@smallexample
-maybe_le (@var{a}, @var{a})
-@end smallexample
-
-is true for all @var{a}. @code{maybe_eq} and @code{maybe_ne} are symmetric, so:
-
-@smallexample
-maybe_eq (@var{a}, @var{b}) == maybe_eq (@var{b}, @var{a})
-maybe_ne (@var{a}, @var{b}) == maybe_ne (@var{b}, @var{a})
-@end smallexample
-
-for all @var{a} and @var{b}. In addition:
-
-@smallexample
-maybe_le (@var{a}, @var{b}) == maybe_lt (@var{a}, @var{b}) || maybe_eq (@var{a}, @var{b})
-maybe_ge (@var{a}, @var{b}) == maybe_gt (@var{a}, @var{b}) || maybe_eq (@var{a}, @var{b})
-maybe_lt (@var{a}, @var{b}) == maybe_gt (@var{b}, @var{a})
-maybe_le (@var{a}, @var{b}) == maybe_ge (@var{b}, @var{a})
-@end smallexample
-
-However:
-
-@smallexample
-maybe_le (@var{a}, @var{b}) && maybe_le (@var{b}, @var{a}) does not imply !maybe_ne (@var{a}, @var{b}) [== known_eq (@var{a}, @var{b})]
-maybe_ge (@var{a}, @var{b}) && maybe_ge (@var{b}, @var{a}) does not imply !maybe_ne (@var{a}, @var{b}) [== known_eq (@var{a}, @var{b})]
-@end smallexample
-
-One example is again @samp{@var{a} == 3 + 4@var{x}}
-and @samp{@var{b} == 1 + 5@var{x}}, where @samp{maybe_le (@var{a}, @var{b})},
-@samp{maybe_ge (@var{a}, @var{b})} and @samp{maybe_ne (@var{a}, @var{b})}
-all hold. @code{maybe_le} and @code{maybe_ge} are therefore not antisymetric
-and do not form a partial order.
-
-From the above, it follows that:
-
-@itemize @bullet
-@item
-All ``known'' relations except @code{known_ne} are transitive.
-
-@item
-@code{known_lt}, @code{known_ne} and @code{known_gt} are irreflexive.
-
-@item
-@code{known_le}, @code{known_eq} and @code{known_ge} are reflexive.
-@end itemize
-
-Also:
-
-@smallexample
-known_lt (@var{a}, @var{b}) == known_gt (@var{b}, @var{a})
-known_le (@var{a}, @var{b}) == known_ge (@var{b}, @var{a})
-known_lt (@var{a}, @var{b}) implies !known_lt (@var{b}, @var{a}) [asymmetry]
-known_gt (@var{a}, @var{b}) implies !known_gt (@var{b}, @var{a})
-known_le (@var{a}, @var{b}) && known_le (@var{b}, @var{a}) == known_eq (@var{a}, @var{b}) [== !maybe_ne (@var{a}, @var{b})]
-known_ge (@var{a}, @var{b}) && known_ge (@var{b}, @var{a}) == known_eq (@var{a}, @var{b}) [== !maybe_ne (@var{a}, @var{b})]
-@end smallexample
-
-@code{known_le} and @code{known_ge} are therefore antisymmetric and are
-partial orders. However:
-
-@smallexample
-known_le (@var{a}, @var{b}) does not imply known_lt (@var{a}, @var{b}) || known_eq (@var{a}, @var{b})
-known_ge (@var{a}, @var{b}) does not imply known_gt (@var{a}, @var{b}) || known_eq (@var{a}, @var{b})
-@end smallexample
-
-For example, @samp{known_le (4, 4 + 4@var{x})} holds because the runtime
-indeterminate @var{x} is a nonnegative integer, but neither
-@code{known_lt (4, 4 + 4@var{x})} nor @code{known_eq (4, 4 + 4@var{x})} hold.
-
-@node Comparing potentially-unordered @code{poly_int}s
-@subsection Comparing potentially-unordered @code{poly_int}s
-
-In cases where there is no definite link between two @code{poly_int}s,
-we can usually make a conservatively-correct assumption. For example,
-the conservative assumption for alias analysis is that two references
-@emph{might} alias.
-
-One way of checking whether [@var{begin1}, @var{end1}) might overlap
-[@var{begin2}, @var{end2}) using the @code{poly_int} comparisons is:
-
-@smallexample
-maybe_gt (@var{end1}, @var{begin2}) && maybe_gt (@var{end2}, @var{begin1})
-@end smallexample
-
-and another (equivalent) way is:
-
-@smallexample
-!(known_le (@var{end1}, @var{begin2}) || known_le (@var{end2}, @var{begin1}))
-@end smallexample
-
-However, in this particular example, it is better to use the range helper
-functions instead. @xref{Range checks on @code{poly_int}s}.
-
-@node Comparing ordered @code{poly_int}s
-@subsection Comparing ordered @code{poly_int}s
-
-In cases where there is a definite link between two @code{poly_int}s,
-such as the outer and inner sizes of subregs, we usually require the sizes
-to be ordered by the @code{known_le} partial order. @code{poly_int} provides
-the following utility functions for ordered values:
-
-@table @samp
-@item ordered_p (@var{a}, @var{b})
-Return true if @var{a} and @var{b} are ordered by the @code{known_le}
-partial order.
-
-@item ordered_min (@var{a}, @var{b})
-Assert that @var{a} and @var{b} are ordered by @code{known_le} and return the
-minimum of the two. When using this function, please add a comment explaining
-why the values are known to be ordered.
-
-@item ordered_max (@var{a}, @var{b})
-Assert that @var{a} and @var{b} are ordered by @code{known_le} and return the
-maximum of the two. When using this function, please add a comment explaining
-why the values are known to be ordered.
-@end table
-
-For example, if a subreg has an outer mode of size @var{outer} and an
-inner mode of size @var{inner}:
-
-@itemize @bullet
-@item
-the subreg is complete if known_eq (@var{inner}, @var{outer})
-
-@item
-otherwise, the subreg is paradoxical if known_le (@var{inner}, @var{outer})
-
-@item
-otherwise, the subreg is partial if known_le (@var{outer}, @var{inner})
-
-@item
-otherwise, the subreg is ill-formed
-@end itemize
-
-Thus the subreg is only valid if
-@samp{ordered_p (@var{outer}, @var{inner})} is true. If this condition
-is already known to be true then:
-
-@itemize @bullet
-@item
-the subreg is complete if known_eq (@var{inner}, @var{outer})
-
-@item
-the subreg is paradoxical if maybe_lt (@var{inner}, @var{outer})
-
-@item
-the subreg is partial if maybe_lt (@var{outer}, @var{inner})
-@end itemize
-
-with the three conditions being mutually exclusive.
-
-Code that checks whether a subreg is valid would therefore generally
-check whether @code{ordered_p} holds (in addition to whatever other
-checks are required for subreg validity). Code that is dealing
-with existing subregs can assert that @code{ordered_p} holds
-and use either of the classifications above.
-
-@node Checking for a @code{poly_int} marker value
-@subsection Checking for a @code{poly_int} marker value
-
-It is sometimes useful to have a special ``marker value'' that is not
-meant to be taken literally. For example, some code uses a size
-of -1 to represent an unknown size, rather than having to carry around
-a separate boolean to say whether the size is known.
-
-The best way of checking whether something is a marker value is
-@code{known_eq}. Conversely the best way of checking whether something
-is @emph{not} a marker value is @code{maybe_ne}.
-
-Thus in the size example just mentioned, @samp{known_eq (size, -1)} would
-check for an unknown size and @samp{maybe_ne (size, -1)} would check for a
-known size.
-
-@node Range checks on @code{poly_int}s
-@subsection Range checks on @code{poly_int}s
-
-As well as the core comparisons
-(@pxref{Comparison functions for @code{poly_int}}), @code{poly_int} provides
-utilities for various kinds of range check. In each case the range
-is represented by a start position and a size rather than a start
-position and an end position; this is because the former is used
-much more often than the latter in GCC@. Also, the sizes can be
--1 (or all ones for unsigned sizes) to indicate a range with a known
-start position but an unknown size. All other sizes must be nonnegative.
-A range of size 0 does not contain anything or overlap anything.
-
-@table @samp
-@item known_size_p (@var{size})
-Return true if @var{size} represents a known range size, false if it
-is -1 or all ones (for signed and unsigned types respectively).
-
-@item ranges_maybe_overlap_p (@var{pos1}, @var{size1}, @var{pos2}, @var{size2})
-Return true if the range described by @var{pos1} and @var{size1} @emph{might}
-overlap the range described by @var{pos2} and @var{size2} (in other words,
-return true if we cannot prove that the ranges are disjoint).
-
-@item ranges_known_overlap_p (@var{pos1}, @var{size1}, @var{pos2}, @var{size2})
-Return true if the range described by @var{pos1} and @var{size1} is known to
-overlap the range described by @var{pos2} and @var{size2}.
-
-@item known_subrange_p (@var{pos1}, @var{size1}, @var{pos2}, @var{size2})
-Return true if the range described by @var{pos1} and @var{size1} is known to
-be contained in the range described by @var{pos2} and @var{size2}.
-
-@item maybe_in_range_p (@var{value}, @var{pos}, @var{size})
-Return true if @var{value} @emph{might} be in the range described by
-@var{pos} and @var{size} (in other words, return true if we cannot
-prove that @var{value} is outside that range).
-
-@item known_in_range_p (@var{value}, @var{pos}, @var{size})
-Return true if @var{value} is known to be in the range described
-by @var{pos} and @var{size}.
-
-@item endpoint_representable_p (@var{pos}, @var{size})
-Return true if the range described by @var{pos} and @var{size} is
-open-ended or if the endpoint (@var{pos} + @var{size}) is representable
-in the same type as @var{pos} and @var{size}. The function returns false
-if adding @var{size} to @var{pos} makes conceptual sense but could overflow.
-@end table
-
-There is also a @code{poly_int} version of the @code{IN_RANGE_P} macro:
-
-@table @samp
-@item coeffs_in_range_p (@var{x}, @var{lower}, @var{upper})
-Return true if every coefficient of @var{x} is in the inclusive range
-[@var{lower}, @var{upper}]. This function can be useful when testing
-whether an operation would cause the values of coefficients to
-overflow.
-
-Note that the function does not indicate whether @var{x} itself is in the
-given range. @var{x} can be either a constant or a @code{poly_int}.
-@end table
-
-@node Sorting @code{poly_int}s
-@subsection Sorting @code{poly_int}s
-
-@code{poly_int} provides the following routine for sorting:
-
-@table @samp
-@item compare_sizes_for_sort (@var{a}, @var{b})
-Compare @var{a} and @var{b} in reverse lexicographical order (that is,
-compare the highest-indexed coefficients first). This can be useful when
-sorting data structures, since it has the effect of separating constant
-and non-constant values. If all values are nonnegative, the constant
-values come first.
-
-Note that the values do not necessarily end up in numerical order.
-For example, @samp{1 + 1@var{x}} would come after @samp{100} in the sort order,
-but may well be less than @samp{100} at run time.
-@end table
-
-@node Arithmetic on @code{poly_int}s
-@section Arithmetic on @code{poly_int}s
-
-Addition, subtraction, negation and bit inversion all work normally for
-@code{poly_int}s. Multiplication by a constant multiplier and left
-shifting by a constant shift amount also work normally. General
-multiplication of two @code{poly_int}s is not supported and is not
-useful in practice.
-
-Other operations are only conditionally supported: the operation
-might succeed or might fail, depending on the inputs.
-
-This section describes both types of operation.
-
-@menu
-* Using @code{poly_int} with C++ arithmetic operators::
-* @code{wi} arithmetic on @code{poly_int}s::
-* Division of @code{poly_int}s::
-* Other @code{poly_int} arithmetic::
-@end menu
-
-@node Using @code{poly_int} with C++ arithmetic operators
-@subsection Using @code{poly_int} with C++ arithmetic operators
-
-The following C++ expressions are supported, where @var{p1} and @var{p2}
-are @code{poly_int}s and where @var{c1} and @var{c2} are scalars:
-
-@smallexample
--@var{p1}
-~@var{p1}
-
-@var{p1} + @var{p2}
-@var{p1} + @var{c2}
-@var{c1} + @var{p2}
-
-@var{p1} - @var{p2}
-@var{p1} - @var{c2}
-@var{c1} - @var{p2}
-
-@var{c1} * @var{p2}
-@var{p1} * @var{c2}
-
-@var{p1} << @var{c2}
-
-@var{p1} += @var{p2}
-@var{p1} += @var{c2}
-
-@var{p1} -= @var{p2}
-@var{p1} -= @var{c2}
-
-@var{p1} *= @var{c2}
-@var{p1} <<= @var{c2}
-@end smallexample
-
-These arithmetic operations handle integer ranks in a similar way
-to C++. The main difference is that every coefficient narrower than
-@code{HOST_WIDE_INT} promotes to @code{HOST_WIDE_INT}, whereas in
-C++ everything narrower than @code{int} promotes to @code{int}.
-For example:
-
-@smallexample
-poly_uint16 + int -> poly_int64
-unsigned int + poly_uint16 -> poly_int64
-poly_int64 + int -> poly_int64
-poly_int32 + poly_uint64 -> poly_uint64
-uint64 + poly_int64 -> poly_uint64
-poly_offset_int + int32 -> poly_offset_int
-offset_int + poly_uint16 -> poly_offset_int
-@end smallexample
-
-In the first two examples, both coefficients are narrower than
-@code{HOST_WIDE_INT}, so the result has coefficients of type
-@code{HOST_WIDE_INT}. In the other examples, the coefficient
-with the highest rank ``wins''.
-
-If one of the operands is @code{wide_int} or @code{poly_wide_int},
-the rules are the same as for @code{wide_int} arithmetic.
-
-@node @code{wi} arithmetic on @code{poly_int}s
-@subsection @code{wi} arithmetic on @code{poly_int}s
-
-As well as the C++ operators, @code{poly_int} supports the following
-@code{wi} routines:
-
-@smallexample
-wi::neg (@var{p1}, &@var{overflow})
-
-wi::add (@var{p1}, @var{p2})
-wi::add (@var{p1}, @var{c2})
-wi::add (@var{c1}, @var{p1})
-wi::add (@var{p1}, @var{p2}, @var{sign}, &@var{overflow})
-
-wi::sub (@var{p1}, @var{p2})
-wi::sub (@var{p1}, @var{c2})
-wi::sub (@var{c1}, @var{p1})
-wi::sub (@var{p1}, @var{p2}, @var{sign}, &@var{overflow})
-
-wi::mul (@var{p1}, @var{c2})
-wi::mul (@var{c1}, @var{p1})
-wi::mul (@var{p1}, @var{c2}, @var{sign}, &@var{overflow})
-
-wi::lshift (@var{p1}, @var{c2})
-@end smallexample
-
-These routines just check whether overflow occurs on any individual
-coefficient; it is not possible to know at compile time whether the
-final runtime value would overflow.
-
-@node Division of @code{poly_int}s
-@subsection Division of @code{poly_int}s
-
-Division of @code{poly_int}s is possible for certain inputs. The functions
-for division return true if the operation is possible and in most cases
-return the results by pointer. The routines are:
-
-@table @samp
-@item multiple_p (@var{a}, @var{b})
-@itemx multiple_p (@var{a}, @var{b}, &@var{quotient})
-Return true if @var{a} is an exact multiple of @var{b}, storing the result
-in @var{quotient} if so. There are overloads for various combinations
-of polynomial and constant @var{a}, @var{b} and @var{quotient}.
-
-@item constant_multiple_p (@var{a}, @var{b})
-@itemx constant_multiple_p (@var{a}, @var{b}, &@var{quotient})
-Like @code{multiple_p}, but also test whether the multiple is a
-compile-time constant.
-
-@item can_div_trunc_p (@var{a}, @var{b}, &@var{quotient})
-@itemx can_div_trunc_p (@var{a}, @var{b}, &@var{quotient}, &@var{remainder})
-Return true if we can calculate @samp{trunc (@var{a} / @var{b})} at compile
-time, storing the result in @var{quotient} and @var{remainder} if so.
-
-@item can_div_away_from_zero_p (@var{a}, @var{b}, &@var{quotient})
-Return true if we can calculate @samp{@var{a} / @var{b}} at compile time,
-rounding away from zero. Store the result in @var{quotient} if so.
-
-Note that this is true if and only if @code{can_div_trunc_p} is true.
-The only difference is in the rounding of the result.
-@end table
-
-There is also an asserting form of division:
-
-@table @samp
-@item exact_div (@var{a}, @var{b})
-Assert that @var{a} is a multiple of @var{b} and return
-@samp{@var{a} / @var{b}}. The result is a @code{poly_int} if @var{a}
-is a @code{poly_int}.
-@end table
-
-@node Other @code{poly_int} arithmetic
-@subsection Other @code{poly_int} arithmetic
-
-There are tentative routines for other operations besides division:
-
-@table @samp
-@item can_ior_p (@var{a}, @var{b}, &@var{result})
-Return true if we can calculate @samp{@var{a} | @var{b}} at compile time,
-storing the result in @var{result} if so.
-@end table
-
-Also, ANDs with a value @samp{(1 << @var{y}) - 1} or its inverse can be
-treated as alignment operations. @xref{Alignment of @code{poly_int}s}.
-
-In addition, the following miscellaneous routines are available:
-
-@table @samp
-@item coeff_gcd (@var{a})
-Return the greatest common divisor of all nonzero coefficients in
-@var{a}, or zero if @var{a} is known to be zero.
-
-@item common_multiple (@var{a}, @var{b})
-Return a value that is a multiple of both @var{a} and @var{b}, where
-one value is a @code{poly_int} and the other is a scalar. The result
-will be the least common multiple for some indeterminate values but
-not necessarily for all.
-
-@item force_common_multiple (@var{a}, @var{b})
-Return a value that is a multiple of both @code{poly_int} @var{a} and
-@code{poly_int} @var{b}, asserting that such a value exists. The
-result will be the least common multiple for some indeterminate values
-but not necessarily for all.
-
-When using this routine, please add a comment explaining why the
-assertion is known to hold.
-@end table
-
-Please add any other operations that you find to be useful.
-
-@node Alignment of @code{poly_int}s
-@section Alignment of @code{poly_int}s
-
-@code{poly_int} provides various routines for aligning values and for querying
-misalignments. In each case the alignment must be a power of 2.
-
-@table @samp
-@item can_align_p (@var{value}, @var{align})
-Return true if we can align @var{value} up or down to the nearest multiple
-of @var{align} at compile time. The answer is the same for both directions.
-
-@item can_align_down (@var{value}, @var{align}, &@var{aligned})
-Return true if @code{can_align_p}; if so, set @var{aligned} to the greatest
-aligned value that is less than or equal to @var{value}.
-
-@item can_align_up (@var{value}, @var{align}, &@var{aligned})
-Return true if @code{can_align_p}; if so, set @var{aligned} to the lowest
-aligned value that is greater than or equal to @var{value}.
-
-@item known_equal_after_align_down (@var{a}, @var{b}, @var{align})
-Return true if we can align @var{a} and @var{b} down to the nearest
-@var{align} boundary at compile time and if the two results are equal.
-
-@item known_equal_after_align_up (@var{a}, @var{b}, @var{align})
-Return true if we can align @var{a} and @var{b} up to the nearest
-@var{align} boundary at compile time and if the two results are equal.
-
-@item aligned_lower_bound (@var{value}, @var{align})
-Return a result that is no greater than @var{value} and that is aligned
-to @var{align}. The result will the closest aligned value for some
-indeterminate values but not necessarily for all.
-
-For example, suppose we are allocating an object of @var{size} bytes
-in a downward-growing stack whose current limit is given by @var{limit}.
-If the object requires @var{align} bytes of alignment, the new stack
-limit is given by:
-
-@smallexample
-aligned_lower_bound (@var{limit} - @var{size}, @var{align})
-@end smallexample
-
-@item aligned_upper_bound (@var{value}, @var{align})
-Likewise return a result that is no less than @var{value} and that is
-aligned to @var{align}. This is the routine that would be used for
-upward-growing stacks in the scenario just described.
-
-@item known_misalignment (@var{value}, @var{align}, &@var{misalign})
-Return true if we can calculate the misalignment of @var{value}
-with respect to @var{align} at compile time, storing the result in
-@var{misalign} if so.
-
-@item known_alignment (@var{value})
-Return the minimum alignment that @var{value} is known to have
-(in other words, the largest alignment that can be guaranteed
-whatever the values of the indeterminates turn out to be).
-Return 0 if @var{value} is known to be 0.
-
-@item force_align_down (@var{value}, @var{align})
-Assert that @var{value} can be aligned down to @var{align} at compile
-time and return the result. When using this routine, please add a
-comment explaining why the assertion is known to hold.
-
-@item force_align_up (@var{value}, @var{align})
-Likewise, but aligning up.
-
-@item force_align_down_and_div (@var{value}, @var{align})
-Divide the result of @code{force_align_down} by @var{align}. Again,
-please add a comment explaining why the assertion in @code{force_align_down}
-is known to hold.
-
-@item force_align_up_and_div (@var{value}, @var{align})
-Likewise for @code{force_align_up}.
-
-@item force_get_misalignment (@var{value}, @var{align})
-Assert that we can calculate the misalignment of @var{value} with
-respect to @var{align} at compile time and return the misalignment.
-When using this function, please add a comment explaining why
-the assertion is known to hold.
-@end table
-
-@node Computing bounds on @code{poly_int}s
-@section Computing bounds on @code{poly_int}s
-
-@code{poly_int} also provides routines for calculating lower and upper bounds:
-
-@table @samp
-@item constant_lower_bound (@var{a})
-Assert that @var{a} is nonnegative and return the smallest value it can have.
-
-@item constant_lower_bound_with_limit (@var{a}, @var{b})
-Return the least value @var{a} can have, given that the context in
-which @var{a} appears guarantees that the answer is no less than @var{b}.
-In other words, the caller is asserting that @var{a} is greater than or
-equal to @var{b} even if @samp{known_ge (@var{a}, @var{b})} doesn't hold.
-
-@item constant_upper_bound_with_limit (@var{a}, @var{b})
-Return the greatest value @var{a} can have, given that the context in
-which @var{a} appears guarantees that the answer is no greater than @var{b}.
-In other words, the caller is asserting that @var{a} is less than or equal
-to @var{b} even if @samp{known_le (@var{a}, @var{b})} doesn't hold.
-
-@item lower_bound (@var{a}, @var{b})
-Return a value that is always less than or equal to both @var{a} and @var{b}.
-It will be the greatest such value for some indeterminate values
-but necessarily for all.
-
-@item upper_bound (@var{a}, @var{b})
-Return a value that is always greater than or equal to both @var{a} and
-@var{b}. It will be the least such value for some indeterminate values
-but necessarily for all.
-@end table
-
-@node Converting @code{poly_int}s
-@section Converting @code{poly_int}s
-
-A @code{poly_int<@var{n}, @var{T}>} can be constructed from up to
-@var{n} individual @var{T} coefficients, with the remaining coefficients
-being implicitly zero. In particular, this means that every
-@code{poly_int<@var{n}, @var{T}>} can be constructed from a single
-scalar @var{T}, or something compatible with @var{T}.
-
-Also, a @code{poly_int<@var{n}, @var{T}>} can be constructed from
-a @code{poly_int<@var{n}, @var{U}>} if @var{T} can be constructed
-from @var{U}.
-
-The following functions provide other forms of conversion,
-or test whether such a conversion would succeed.
-
-@table @samp
-@item @var{value}.is_constant ()
-Return true if @code{poly_int} @var{value} is a compile-time constant.
-
-@item @var{value}.is_constant (&@var{c1})
-Return true if @code{poly_int} @var{value} is a compile-time constant,
-storing it in @var{c1} if so. @var{c1} must be able to hold all
-constant values of @var{value} without loss of precision.
-
-@item @var{value}.to_constant ()
-Assert that @var{value} is a compile-time constant and return its value.
-When using this function, please add a comment explaining why the
-condition is known to hold (for example, because an earlier phase
-of analysis rejected non-constants).
-
-@item @var{value}.to_shwi (&@var{p2})
-Return true if @samp{poly_int<@var{N}, @var{T}>} @var{value} can be
-represented without loss of precision as a
-@samp{poly_int<@var{N}, @code{HOST_WIDE_INT}>}, storing it in that
-form in @var{p2} if so.
-
-@item @var{value}.to_uhwi (&@var{p2})
-Return true if @samp{poly_int<@var{N}, @var{T}>} @var{value} can be
-represented without loss of precision as a
-@samp{poly_int<@var{N}, @code{unsigned HOST_WIDE_INT}>}, storing it in that
-form in @var{p2} if so.
-
-@item @var{value}.force_shwi ()
-Forcibly convert each coefficient of @samp{poly_int<@var{N}, @var{T}>}
-@var{value} to @code{HOST_WIDE_INT}, truncating any that are out of range.
-Return the result as a @samp{poly_int<@var{N}, @code{HOST_WIDE_INT}>}.
-
-@item @var{value}.force_uhwi ()
-Forcibly convert each coefficient of @samp{poly_int<@var{N}, @var{T}>}
-@var{value} to @code{unsigned HOST_WIDE_INT}, truncating any that are
-out of range. Return the result as a
-@samp{poly_int<@var{N}, @code{unsigned HOST_WIDE_INT}>}.
-
-@item wi::shwi (@var{value}, @var{precision})
-Return a @code{poly_int} with the same value as @var{value}, but with
-the coefficients converted from @code{HOST_WIDE_INT} to @code{wide_int}.
-@var{precision} specifies the precision of the @code{wide_int} cofficients;
-if this is wider than a @code{HOST_WIDE_INT}, the coefficients of
-@var{value} will be sign-extended to fit.
-
-@item wi::uhwi (@var{value}, @var{precision})
-Like @code{wi::shwi}, except that @var{value} has coefficients of
-type @code{unsigned HOST_WIDE_INT}. If @var{precision} is wider than
-a @code{HOST_WIDE_INT}, the coefficients of @var{value} will be
-zero-extended to fit.
-
-@item wi::sext (@var{value}, @var{precision})
-Return a @code{poly_int} of the same type as @var{value}, sign-extending
-every coefficient from the low @var{precision} bits. This in effect
-applies @code{wi::sext} to each coefficient individually.
-
-@item wi::zext (@var{value}, @var{precision})
-Like @code{wi::sext}, but for zero extension.
-
-@item poly_wide_int::from (@var{value}, @var{precision}, @var{sign})
-Convert @var{value} to a @code{poly_wide_int} in which each coefficient
-has @var{precision} bits. Extend the coefficients according to
-@var{sign} if the coefficients have fewer bits.
-
-@item poly_offset_int::from (@var{value}, @var{sign})
-Convert @var{value} to a @code{poly_offset_int}, extending its coefficients
-according to @var{sign} if they have fewer bits than @code{offset_int}.
-
-@item poly_widest_int::from (@var{value}, @var{sign})
-Convert @var{value} to a @code{poly_widest_int}, extending its coefficients
-according to @var{sign} if they have fewer bits than @code{widest_int}.
-@end table
-
-@node Miscellaneous @code{poly_int} routines
-@section Miscellaneous @code{poly_int} routines
-
-@table @samp
-@item print_dec (@var{value}, @var{file}, @var{sign})
-@itemx print_dec (@var{value}, @var{file})
-Print @var{value} to @var{file} as a decimal value, interpreting
-the coefficients according to @var{sign}. The final argument is
-optional if @var{value} has an inherent sign; for example,
-@code{poly_int64} values print as signed by default and
-@code{poly_uint64} values print as unsigned by default.
-
-This is a simply a @code{poly_int} version of a wide-int routine.
-@end table
-
-@node Guidelines for using @code{poly_int}
-@section Guidelines for using @code{poly_int}
-
-One of the main design goals of @code{poly_int} was to make it easy
-to write target-independent code that handles variable-sized registers
-even when the current target has fixed-sized registers. There are two
-aspects to this:
-
-@itemize
-@item
-The set of @code{poly_int} operations should be complete enough that
-the question in most cases becomes ``Can we do this operation on these
-particular @code{poly_int} values? If not, bail out'' rather than
-``Are these @code{poly_int} values constant? If so, do the operation,
-otherwise bail out''.
-
-@item
-If target-independent code compiles and runs correctly on a target
-with one value of @code{NUM_POLY_INT_COEFFS}, and if the code does not
-use asserting functions like @code{to_constant}, it is reasonable to
-assume that the code also works on targets with other values of
-@code{NUM_POLY_INT_COEFFS}. There is no need to check this during
-everyday development.
-@end itemize
-
-So the general principle is: if target-independent code is dealing
-with a @code{poly_int} value, it is better to operate on it as a
-@code{poly_int} if at all possible, choosing conservatively-correct
-behavior if a particular operation fails. For example, the following
-code handles an index @code{pos} into a sequence of vectors that each
-have @code{nunits} elements:
-
-@smallexample
-/* Calculate which vector contains the result, and which lane of
- that vector we need. */
-if (!can_div_trunc_p (pos, nunits, &vec_entry, &vec_index))
- @{
- if (dump_enabled_p ())
- dump_printf_loc (MSG_MISSED_OPTIMIZATION, vect_location,
- "Cannot determine which vector holds the"
- " final result.\n");
- return false;
- @}
-@end smallexample
-
-However, there are some contexts in which operating on a
-@code{poly_int} is not possible or does not make sense. One example
-is when handling static initializers, since no current target supports
-the concept of a variable-length static initializer. In these
-situations, a reasonable fallback is:
-
-@smallexample
-if (@var{poly_value}.is_constant (&@var{const_value}))
- @{
- @dots{}
- /* Operate on @var{const_value}. */
- @dots{}
- @}
-else
- @{
- @dots{}
- /* Conservatively correct fallback. */
- @dots{}
- @}
-@end smallexample
-
-@code{poly_int} also provides some asserting functions like
-@code{to_constant}. Please only use these functions if there is a
-good theoretical reason to believe that the assertion cannot fire.
-For example, if some work is divided into an analysis phase and an
-implementation phase, the analysis phase might reject inputs that are
-not @code{is_constant}, in which case the implementation phase can
-reasonably use @code{to_constant} on the remaining inputs. The assertions
-should not be used to discover whether a condition ever occurs ``in the
-field''; in other words, they should not be used to restrict code to
-constants at first, with the intention of only implementing a
-@code{poly_int} version if a user hits the assertion.
-
-If a particular asserting function like @code{to_constant} is needed
-more than once for the same reason, it is probably worth adding a
-helper function or macro for that situation, so that the justification
-only needs to be given once. For example:
-
-@smallexample
-/* Return the size of an element in a vector of size SIZE, given that
- the vector has NELTS elements. The return value is in the same units
- as SIZE (either bits or bytes).
-
- to_constant () is safe in this situation because vector elements are
- always constant-sized scalars. */
-#define vector_element_size(SIZE, NELTS) \
- (exact_div (SIZE, NELTS).to_constant ())
-@end smallexample
-
-Target-specific code in @file{config/@var{cpu}} only needs to handle
-non-constant @code{poly_int}s if @code{NUM_POLY_INT_COEFFS} is greater
-than one. For other targets, @code{poly_int} degenerates to a compile-time
-constant and is often interchangable with a normal scalar integer.
-There are two main exceptions:
-
-@itemize
-@item
-Sometimes an explicit cast to an integer type might be needed, such as to
-resolve ambiguities in a @code{?:} expression, or when passing values
-through @code{...} to things like print functions.
-
-@item
-Target macros are included in target-independent code and so do not
-have access to the implicit conversion to a scalar integer.
-If this becomes a problem for a particular target macro, the
-possible solutions, in order of preference, are:
-
-@itemize
-@item
-Convert the target macro to a target hook (for all targets).
-
-@item
-Put the target's implementation of the target macro in its
-@file{@var{cpu}.c} file and call it from the target macro in the
-@file{@var{cpu}.h} file.
-
-@item
-Add @code{to_constant ()} calls where necessary. The previous option
-is preferable because it will help with any future conversion of the
-macro to a hook.
-@end itemize
-@end itemize
-
+++ /dev/null
-@c Copyright (C) 1988-2022 Free Software Foundation, Inc.
-@c This is part of the GCC manual.
-@c For copying conditions, see the file gcc.texi.
-
-@node Portability
-@chapter GCC and Portability
-@cindex portability
-@cindex GCC and portability
-
-GCC itself aims to be portable to any machine where @code{int} is at least
-a 32-bit type. It aims to target machines with a flat (non-segmented) byte
-addressed data address space (the code address space can be separate).
-Target ABIs may have 8, 16, 32 or 64-bit @code{int} type. @code{char}
-can be wider than 8 bits.
-
-GCC gets most of the information about the target machine from a machine
-description which gives an algebraic formula for each of the machine's
-instructions. This is a very clean way to describe the target. But when
-the compiler needs information that is difficult to express in this
-fashion, ad-hoc parameters have been defined for machine descriptions.
-The purpose of portability is to reduce the total work needed on the
-compiler; it was not of interest for its own sake.
-
-@cindex endianness
-@cindex autoincrement addressing, availability
-@findex abort
-GCC does not contain machine dependent code, but it does contain code
-that depends on machine parameters such as endianness (whether the most
-significant byte has the highest or lowest address of the bytes in a word)
-and the availability of autoincrement addressing. In the RTL-generation
-pass, it is often necessary to have multiple strategies for generating code
-for a particular kind of syntax tree, strategies that are usable for different
-combinations of parameters. Often, not all possible cases have been
-addressed, but only the common ones or only the ones that have been
-encountered. As a result, a new target may require additional
-strategies. You will know
-if this happens because the compiler will call @code{abort}. Fortunately,
-the new strategies can be added in a machine-independent fashion, and will
-affect only the target machines that need them.
+++ /dev/null
-@c Copyright (C) 1988-2022 Free Software Foundation, Inc.
-@c This is part of the GCC manual.
-@c For copying conditions, see the file gcc.texi.
-
-@node RTL
-@chapter RTL Representation
-@cindex RTL representation
-@cindex representation of RTL
-@cindex Register Transfer Language (RTL)
-
-The last part of the compiler work is done on a low-level intermediate
-representation called Register Transfer Language. In this language, the
-instructions to be output are described, pretty much one by one, in an
-algebraic form that describes what the instruction does.
-
-RTL is inspired by Lisp lists. It has both an internal form, made up of
-structures that point at other structures, and a textual form that is used
-in the machine description and in printed debugging dumps. The textual
-form uses nested parentheses to indicate the pointers in the internal form.
-
-@menu
-* RTL Objects:: Expressions vs vectors vs strings vs integers.
-* RTL Classes:: Categories of RTL expression objects, and their structure.
-* Accessors:: Macros to access expression operands or vector elts.
-* Special Accessors:: Macros to access specific annotations on RTL.
-* Flags:: Other flags in an RTL expression.
-* Machine Modes:: Describing the size and format of a datum.
-* Constants:: Expressions with constant values.
-* Regs and Memory:: Expressions representing register contents or memory.
-* Arithmetic:: Expressions representing arithmetic on other expressions.
-* Comparisons:: Expressions representing comparison of expressions.
-* Bit-Fields:: Expressions representing bit-fields in memory or reg.
-* Vector Operations:: Expressions involving vector datatypes.
-* Conversions:: Extending, truncating, floating or fixing.
-* RTL Declarations:: Declaring volatility, constancy, etc.
-* Side Effects:: Expressions for storing in registers, etc.
-* Incdec:: Embedded side-effects for autoincrement addressing.
-* Assembler:: Representing @code{asm} with operands.
-* Debug Information:: Expressions representing debugging information.
-* Insns:: Expression types for entire insns.
-* Calls:: RTL representation of function call insns.
-* RTL SSA:: An on-the-side SSA form for RTL
-* Sharing:: Some expressions are unique; others *must* be copied.
-* Reading RTL:: Reading textual RTL from a file.
-@end menu
-
-@node RTL Objects
-@section RTL Object Types
-@cindex RTL object types
-
-@cindex RTL integers
-@cindex RTL strings
-@cindex RTL vectors
-@cindex RTL expression
-@cindex RTX (See RTL)
-RTL uses five kinds of objects: expressions, integers, wide integers,
-strings and vectors. Expressions are the most important ones. An RTL
-expression (``RTX'', for short) is a C structure, but it is usually
-referred to with a pointer; a type that is given the typedef name
-@code{rtx}.
-
-An integer is simply an @code{int}; their written form uses decimal
-digits. A wide integer is an integral object whose type is
-@code{HOST_WIDE_INT}; their written form uses decimal digits.
-
-A string is a sequence of characters. In core it is represented as a
-@code{char *} in usual C fashion, and it is written in C syntax as well.
-However, strings in RTL may never be null. If you write an empty string in
-a machine description, it is represented in core as a null pointer rather
-than as a pointer to a null character. In certain contexts, these null
-pointers instead of strings are valid. Within RTL code, strings are most
-commonly found inside @code{symbol_ref} expressions, but they appear in
-other contexts in the RTL expressions that make up machine descriptions.
-
-In a machine description, strings are normally written with double
-quotes, as you would in C@. However, strings in machine descriptions may
-extend over many lines, which is invalid C, and adjacent string
-constants are not concatenated as they are in C@. Any string constant
-may be surrounded with a single set of parentheses. Sometimes this
-makes the machine description easier to read.
-
-There is also a special syntax for strings, which can be useful when C
-code is embedded in a machine description. Wherever a string can
-appear, it is also valid to write a C-style brace block. The entire
-brace block, including the outermost pair of braces, is considered to be
-the string constant. Double quote characters inside the braces are not
-special. Therefore, if you write string constants in the C code, you
-need not escape each quote character with a backslash.
-
-A vector contains an arbitrary number of pointers to expressions. The
-number of elements in the vector is explicitly present in the vector.
-The written form of a vector consists of square brackets
-(@samp{[@dots{}]}) surrounding the elements, in sequence and with
-whitespace separating them. Vectors of length zero are not created;
-null pointers are used instead.
-
-@cindex expression codes
-@cindex codes, RTL expression
-@findex GET_CODE
-@findex PUT_CODE
-Expressions are classified by @dfn{expression codes} (also called RTX
-codes). The expression code is a name defined in @file{rtl.def}, which is
-also (in uppercase) a C enumeration constant. The possible expression
-codes and their meanings are machine-independent. The code of an RTX can
-be extracted with the macro @code{GET_CODE (@var{x})} and altered with
-@code{PUT_CODE (@var{x}, @var{newcode})}.
-
-The expression code determines how many operands the expression contains,
-and what kinds of objects they are. In RTL, unlike Lisp, you cannot tell
-by looking at an operand what kind of object it is. Instead, you must know
-from its context---from the expression code of the containing expression.
-For example, in an expression of code @code{subreg}, the first operand is
-to be regarded as an expression and the second operand as a polynomial
-integer. In an expression of code @code{plus}, there are two operands,
-both of which are to be regarded as expressions. In a @code{symbol_ref}
-expression, there is one operand, which is to be regarded as a string.
-
-Expressions are written as parentheses containing the name of the
-expression type, its flags and machine mode if any, and then the operands
-of the expression (separated by spaces).
-
-Expression code names in the @samp{md} file are written in lowercase,
-but when they appear in C code they are written in uppercase. In this
-manual, they are shown as follows: @code{const_int}.
-
-@cindex (nil)
-@cindex nil
-In a few contexts a null pointer is valid where an expression is normally
-wanted. The written form of this is @code{(nil)}.
-
-@node RTL Classes
-@section RTL Classes and Formats
-@cindex RTL classes
-@cindex classes of RTX codes
-@cindex RTX codes, classes of
-@findex GET_RTX_CLASS
-
-The various expression codes are divided into several @dfn{classes},
-which are represented by single characters. You can determine the class
-of an RTX code with the macro @code{GET_RTX_CLASS (@var{code})}.
-Currently, @file{rtl.def} defines these classes:
-
-@table @code
-@item RTX_OBJ
-An RTX code that represents an actual object, such as a register
-(@code{REG}) or a memory location (@code{MEM}, @code{SYMBOL_REF}).
-@code{LO_SUM} is also included; instead, @code{SUBREG} and
-@code{STRICT_LOW_PART} are not in this class, but in class
-@code{RTX_EXTRA}.
-
-@item RTX_CONST_OBJ
-An RTX code that represents a constant object. @code{HIGH} is also
-included in this class.
-
-@item RTX_COMPARE
-An RTX code for a non-symmetric comparison, such as @code{GEU} or
-@code{LT}.
-
-@item RTX_COMM_COMPARE
-An RTX code for a symmetric (commutative) comparison, such as @code{EQ}
-or @code{ORDERED}.
-
-@item RTX_UNARY
-An RTX code for a unary arithmetic operation, such as @code{NEG},
-@code{NOT}, or @code{ABS}. This category also includes value extension
-(sign or zero) and conversions between integer and floating point.
-
-@item RTX_COMM_ARITH
-An RTX code for a commutative binary operation, such as @code{PLUS} or
-@code{AND}. @code{NE} and @code{EQ} are comparisons, so they have class
-@code{RTX_COMM_COMPARE}.
-
-@item RTX_BIN_ARITH
-An RTX code for a non-commutative binary operation, such as @code{MINUS},
-@code{DIV}, or @code{ASHIFTRT}.
-
-@item RTX_BITFIELD_OPS
-An RTX code for a bit-field operation. Currently only
-@code{ZERO_EXTRACT} and @code{SIGN_EXTRACT}. These have three inputs
-and are lvalues (so they can be used for insertion as well).
-@xref{Bit-Fields}.
-
-@item RTX_TERNARY
-An RTX code for other three input operations. Currently only
-@code{IF_THEN_ELSE}, @code{VEC_MERGE}, @code{SIGN_EXTRACT},
-@code{ZERO_EXTRACT}, and @code{FMA}.
-
-@item RTX_INSN
-An RTX code for an entire instruction: @code{INSN}, @code{JUMP_INSN}, and
-@code{CALL_INSN}. @xref{Insns}.
-
-@item RTX_MATCH
-An RTX code for something that matches in insns, such as
-@code{MATCH_DUP}. These only occur in machine descriptions.
-
-@item RTX_AUTOINC
-An RTX code for an auto-increment addressing mode, such as
-@code{POST_INC}. @samp{XEXP (@var{x}, 0)} gives the auto-modified
-register.
-
-@item RTX_EXTRA
-All other RTX codes. This category includes the remaining codes used
-only in machine descriptions (@code{DEFINE_*}, etc.). It also includes
-all the codes describing side effects (@code{SET}, @code{USE},
-@code{CLOBBER}, etc.) and the non-insns that may appear on an insn
-chain, such as @code{NOTE}, @code{BARRIER}, and @code{CODE_LABEL}.
-@code{SUBREG} is also part of this class.
-@end table
-
-@cindex RTL format
-For each expression code, @file{rtl.def} specifies the number of
-contained objects and their kinds using a sequence of characters
-called the @dfn{format} of the expression code. For example,
-the format of @code{subreg} is @samp{ep}.
-
-@cindex RTL format characters
-These are the most commonly used format characters:
-
-@table @code
-@item e
-An expression (actually a pointer to an expression).
-
-@item i
-An integer.
-
-@item w
-A wide integer.
-
-@item s
-A string.
-
-@item E
-A vector of expressions.
-@end table
-
-A few other format characters are used occasionally:
-
-@table @code
-@item u
-@samp{u} is equivalent to @samp{e} except that it is printed differently
-in debugging dumps. It is used for pointers to insns.
-
-@item n
-@samp{n} is equivalent to @samp{i} except that it is printed differently
-in debugging dumps. It is used for the line number or code number of a
-@code{note} insn.
-
-@item S
-@samp{S} indicates a string which is optional. In the RTL objects in
-core, @samp{S} is equivalent to @samp{s}, but when the object is read,
-from an @samp{md} file, the string value of this operand may be omitted.
-An omitted string is taken to be the null string.
-
-@item V
-@samp{V} indicates a vector which is optional. In the RTL objects in
-core, @samp{V} is equivalent to @samp{E}, but when the object is read
-from an @samp{md} file, the vector value of this operand may be omitted.
-An omitted vector is effectively the same as a vector of no elements.
-
-@item B
-@samp{B} indicates a pointer to basic block structure.
-
-@item p
-A polynomial integer. At present this is used only for @code{SUBREG_BYTE}.
-
-@item 0
-@samp{0} means a slot whose contents do not fit any normal category.
-@samp{0} slots are not printed at all in dumps, and are often used in
-special ways by small parts of the compiler.
-@end table
-
-There are macros to get the number of operands and the format
-of an expression code:
-
-@table @code
-@findex GET_RTX_LENGTH
-@item GET_RTX_LENGTH (@var{code})
-Number of operands of an RTX of code @var{code}.
-
-@findex GET_RTX_FORMAT
-@item GET_RTX_FORMAT (@var{code})
-The format of an RTX of code @var{code}, as a C string.
-@end table
-
-Some classes of RTX codes always have the same format. For example, it
-is safe to assume that all comparison operations have format @code{ee}.
-
-@table @code
-@item RTX_UNARY
-All codes of this class have format @code{e}.
-
-@item RTX_BIN_ARITH
-@itemx RTX_COMM_ARITH
-@itemx RTX_COMM_COMPARE
-@itemx RTX_COMPARE
-All codes of these classes have format @code{ee}.
-
-@item RTX_BITFIELD_OPS
-@itemx RTX_TERNARY
-All codes of these classes have format @code{eee}.
-
-@item RTX_INSN
-All codes of this class have formats that begin with @code{iuueiee}.
-@xref{Insns}. Note that not all RTL objects linked onto an insn chain
-are of class @code{RTX_INSN}.
-
-@item RTX_CONST_OBJ
-@itemx RTX_OBJ
-@itemx RTX_MATCH
-@itemx RTX_EXTRA
-You can make no assumptions about the format of these codes.
-@end table
-
-@node Accessors
-@section Access to Operands
-@cindex accessors
-@cindex access to operands
-@cindex operand access
-
-@findex XEXP
-@findex XINT
-@findex XWINT
-@findex XSTR
-Operands of expressions are accessed using the macros @code{XEXP},
-@code{XINT}, @code{XWINT} and @code{XSTR}. Each of these macros takes
-two arguments: an expression-pointer (RTX) and an operand number
-(counting from zero). Thus,
-
-@smallexample
-XEXP (@var{x}, 2)
-@end smallexample
-
-@noindent
-accesses operand 2 of expression @var{x}, as an expression.
-
-@smallexample
-XINT (@var{x}, 2)
-@end smallexample
-
-@noindent
-accesses the same operand as an integer. @code{XSTR}, used in the same
-fashion, would access it as a string.
-
-Any operand can be accessed as an integer, as an expression or as a string.
-You must choose the correct method of access for the kind of value actually
-stored in the operand. You would do this based on the expression code of
-the containing expression. That is also how you would know how many
-operands there are.
-
-For example, if @var{x} is an @code{int_list} expression, you know that it has
-two operands which can be correctly accessed as @code{XINT (@var{x}, 0)}
-and @code{XEXP (@var{x}, 1)}. Incorrect accesses like
-@code{XEXP (@var{x}, 0)} and @code{XINT (@var{x}, 1)} would compile,
-but would trigger an internal compiler error when rtl checking is enabled.
-Nothing stops you from writing @code{XEXP (@var{x}, 28)} either, but
-this will access memory past the end of the expression with
-unpredictable results.
-
-Access to operands which are vectors is more complicated. You can use the
-macro @code{XVEC} to get the vector-pointer itself, or the macros
-@code{XVECEXP} and @code{XVECLEN} to access the elements and length of a
-vector.
-
-@table @code
-@findex XVEC
-@item XVEC (@var{exp}, @var{idx})
-Access the vector-pointer which is operand number @var{idx} in @var{exp}.
-
-@findex XVECLEN
-@item XVECLEN (@var{exp}, @var{idx})
-Access the length (number of elements) in the vector which is
-in operand number @var{idx} in @var{exp}. This value is an @code{int}.
-
-@findex XVECEXP
-@item XVECEXP (@var{exp}, @var{idx}, @var{eltnum})
-Access element number @var{eltnum} in the vector which is
-in operand number @var{idx} in @var{exp}. This value is an RTX@.
-
-It is up to you to make sure that @var{eltnum} is not negative
-and is less than @code{XVECLEN (@var{exp}, @var{idx})}.
-@end table
-
-All the macros defined in this section expand into lvalues and therefore
-can be used to assign the operands, lengths and vector elements as well as
-to access them.
-
-@node Special Accessors
-@section Access to Special Operands
-@cindex access to special operands
-
-Some RTL nodes have special annotations associated with them.
-
-@table @code
-@item MEM
-@table @code
-@findex MEM_ALIAS_SET
-@item MEM_ALIAS_SET (@var{x})
-If 0, @var{x} is not in any alias set, and may alias anything. Otherwise,
-@var{x} can only alias @code{MEM}s in a conflicting alias set. This value
-is set in a language-dependent manner in the front-end, and should not be
-altered in the back-end. In some front-ends, these numbers may correspond
-in some way to types, or other language-level entities, but they need not,
-and the back-end makes no such assumptions.
-These set numbers are tested with @code{alias_sets_conflict_p}.
-
-@findex MEM_EXPR
-@item MEM_EXPR (@var{x})
-If this register is known to hold the value of some user-level
-declaration, this is that tree node. It may also be a
-@code{COMPONENT_REF}, in which case this is some field reference,
-and @code{TREE_OPERAND (@var{x}, 0)} contains the declaration,
-or another @code{COMPONENT_REF}, or null if there is no compile-time
-object associated with the reference.
-
-@findex MEM_OFFSET_KNOWN_P
-@item MEM_OFFSET_KNOWN_P (@var{x})
-True if the offset of the memory reference from @code{MEM_EXPR} is known.
-@samp{MEM_OFFSET (@var{x})} provides the offset if so.
-
-@findex MEM_OFFSET
-@item MEM_OFFSET (@var{x})
-The offset from the start of @code{MEM_EXPR}. The value is only valid if
-@samp{MEM_OFFSET_KNOWN_P (@var{x})} is true.
-
-@findex MEM_SIZE_KNOWN_P
-@item MEM_SIZE_KNOWN_P (@var{x})
-True if the size of the memory reference is known.
-@samp{MEM_SIZE (@var{x})} provides its size if so.
-
-@findex MEM_SIZE
-@item MEM_SIZE (@var{x})
-The size in bytes of the memory reference.
-This is mostly relevant for @code{BLKmode} references as otherwise
-the size is implied by the mode. The value is only valid if
-@samp{MEM_SIZE_KNOWN_P (@var{x})} is true.
-
-@findex MEM_ALIGN
-@item MEM_ALIGN (@var{x})
-The known alignment in bits of the memory reference.
-
-@findex MEM_ADDR_SPACE
-@item MEM_ADDR_SPACE (@var{x})
-The address space of the memory reference. This will commonly be zero
-for the generic address space.
-@end table
-
-@item REG
-@table @code
-@findex ORIGINAL_REGNO
-@item ORIGINAL_REGNO (@var{x})
-This field holds the number the register ``originally'' had; for a
-pseudo register turned into a hard reg this will hold the old pseudo
-register number.
-
-@findex REG_EXPR
-@item REG_EXPR (@var{x})
-If this register is known to hold the value of some user-level
-declaration, this is that tree node.
-
-@findex REG_OFFSET
-@item REG_OFFSET (@var{x})
-If this register is known to hold the value of some user-level
-declaration, this is the offset into that logical storage.
-@end table
-
-@item SYMBOL_REF
-@table @code
-@findex SYMBOL_REF_DECL
-@item SYMBOL_REF_DECL (@var{x})
-If the @code{symbol_ref} @var{x} was created for a @code{VAR_DECL} or
-a @code{FUNCTION_DECL}, that tree is recorded here. If this value is
-null, then @var{x} was created by back end code generation routines,
-and there is no associated front end symbol table entry.
-
-@code{SYMBOL_REF_DECL} may also point to a tree of class @code{'c'},
-that is, some sort of constant. In this case, the @code{symbol_ref}
-is an entry in the per-file constant pool; again, there is no associated
-front end symbol table entry.
-
-@findex SYMBOL_REF_CONSTANT
-@item SYMBOL_REF_CONSTANT (@var{x})
-If @samp{CONSTANT_POOL_ADDRESS_P (@var{x})} is true, this is the constant
-pool entry for @var{x}. It is null otherwise.
-
-@findex SYMBOL_REF_DATA
-@item SYMBOL_REF_DATA (@var{x})
-A field of opaque type used to store @code{SYMBOL_REF_DECL} or
-@code{SYMBOL_REF_CONSTANT}.
-
-@findex SYMBOL_REF_FLAGS
-@item SYMBOL_REF_FLAGS (@var{x})
-In a @code{symbol_ref}, this is used to communicate various predicates
-about the symbol. Some of these are common enough to be computed by
-common code, some are specific to the target. The common bits are:
-
-@table @code
-@findex SYMBOL_REF_FUNCTION_P
-@findex SYMBOL_FLAG_FUNCTION
-@item SYMBOL_FLAG_FUNCTION
-Set if the symbol refers to a function.
-
-@findex SYMBOL_REF_LOCAL_P
-@findex SYMBOL_FLAG_LOCAL
-@item SYMBOL_FLAG_LOCAL
-Set if the symbol is local to this ``module''.
-See @code{TARGET_BINDS_LOCAL_P}.
-
-@findex SYMBOL_REF_EXTERNAL_P
-@findex SYMBOL_FLAG_EXTERNAL
-@item SYMBOL_FLAG_EXTERNAL
-Set if this symbol is not defined in this translation unit.
-Note that this is not the inverse of @code{SYMBOL_FLAG_LOCAL}.
-
-@findex SYMBOL_REF_SMALL_P
-@findex SYMBOL_FLAG_SMALL
-@item SYMBOL_FLAG_SMALL
-Set if the symbol is located in the small data section.
-See @code{TARGET_IN_SMALL_DATA_P}.
-
-@findex SYMBOL_FLAG_TLS_SHIFT
-@findex SYMBOL_REF_TLS_MODEL
-@item SYMBOL_REF_TLS_MODEL (@var{x})
-This is a multi-bit field accessor that returns the @code{tls_model}
-to be used for a thread-local storage symbol. It returns zero for
-non-thread-local symbols.
-
-@findex SYMBOL_REF_HAS_BLOCK_INFO_P
-@findex SYMBOL_FLAG_HAS_BLOCK_INFO
-@item SYMBOL_FLAG_HAS_BLOCK_INFO
-Set if the symbol has @code{SYMBOL_REF_BLOCK} and
-@code{SYMBOL_REF_BLOCK_OFFSET} fields.
-
-@findex SYMBOL_REF_ANCHOR_P
-@findex SYMBOL_FLAG_ANCHOR
-@cindex @option{-fsection-anchors}
-@item SYMBOL_FLAG_ANCHOR
-Set if the symbol is used as a section anchor. ``Section anchors''
-are symbols that have a known position within an @code{object_block}
-and that can be used to access nearby members of that block.
-They are used to implement @option{-fsection-anchors}.
-
-If this flag is set, then @code{SYMBOL_FLAG_HAS_BLOCK_INFO} will be too.
-@end table
-
-Bits beginning with @code{SYMBOL_FLAG_MACH_DEP} are available for
-the target's use.
-@end table
-
-@findex SYMBOL_REF_BLOCK
-@item SYMBOL_REF_BLOCK (@var{x})
-If @samp{SYMBOL_REF_HAS_BLOCK_INFO_P (@var{x})}, this is the
-@samp{object_block} structure to which the symbol belongs,
-or @code{NULL} if it has not been assigned a block.
-
-@findex SYMBOL_REF_BLOCK_OFFSET
-@item SYMBOL_REF_BLOCK_OFFSET (@var{x})
-If @samp{SYMBOL_REF_HAS_BLOCK_INFO_P (@var{x})}, this is the offset of @var{x}
-from the first object in @samp{SYMBOL_REF_BLOCK (@var{x})}. The value is
-negative if @var{x} has not yet been assigned to a block, or it has not
-been given an offset within that block.
-@end table
-
-@node Flags
-@section Flags in an RTL Expression
-@cindex flags in RTL expression
-
-RTL expressions contain several flags (one-bit bit-fields)
-that are used in certain types of expression. Most often they
-are accessed with the following macros, which expand into lvalues.
-
-@table @code
-@findex CROSSING_JUMP_P
-@cindex @code{jump_insn} and @samp{/j}
-@item CROSSING_JUMP_P (@var{x})
-Nonzero in a @code{jump_insn} if it crosses between hot and cold sections,
-which could potentially be very far apart in the executable. The presence
-of this flag indicates to other optimizations that this branching instruction
-should not be ``collapsed'' into a simpler branching construct. It is used
-when the optimization to partition basic blocks into hot and cold sections
-is turned on.
-
-@findex CONSTANT_POOL_ADDRESS_P
-@cindex @code{symbol_ref} and @samp{/u}
-@cindex @code{unchanging}, in @code{symbol_ref}
-@item CONSTANT_POOL_ADDRESS_P (@var{x})
-Nonzero in a @code{symbol_ref} if it refers to part of the current
-function's constant pool. For most targets these addresses are in a
-@code{.rodata} section entirely separate from the function, but for
-some targets the addresses are close to the beginning of the function.
-In either case GCC assumes these addresses can be addressed directly,
-perhaps with the help of base registers.
-Stored in the @code{unchanging} field and printed as @samp{/u}.
-
-@findex INSN_ANNULLED_BRANCH_P
-@cindex @code{jump_insn} and @samp{/u}
-@cindex @code{call_insn} and @samp{/u}
-@cindex @code{insn} and @samp{/u}
-@cindex @code{unchanging}, in @code{jump_insn}, @code{call_insn} and @code{insn}
-@item INSN_ANNULLED_BRANCH_P (@var{x})
-In a @code{jump_insn}, @code{call_insn}, or @code{insn} indicates
-that the branch is an annulling one. See the discussion under
-@code{sequence} below. Stored in the @code{unchanging} field and
-printed as @samp{/u}.
-
-@findex INSN_DELETED_P
-@cindex @code{insn} and @samp{/v}
-@cindex @code{call_insn} and @samp{/v}
-@cindex @code{jump_insn} and @samp{/v}
-@cindex @code{code_label} and @samp{/v}
-@cindex @code{jump_table_data} and @samp{/v}
-@cindex @code{barrier} and @samp{/v}
-@cindex @code{note} and @samp{/v}
-@cindex @code{volatil}, in @code{insn}, @code{call_insn}, @code{jump_insn}, @code{code_label}, @code{jump_table_data}, @code{barrier}, and @code{note}
-@item INSN_DELETED_P (@var{x})
-In an @code{insn}, @code{call_insn}, @code{jump_insn}, @code{code_label},
-@code{jump_table_data}, @code{barrier}, or @code{note},
-nonzero if the insn has been deleted. Stored in the
-@code{volatil} field and printed as @samp{/v}.
-
-@findex INSN_FROM_TARGET_P
-@cindex @code{insn} and @samp{/s}
-@cindex @code{jump_insn} and @samp{/s}
-@cindex @code{call_insn} and @samp{/s}
-@cindex @code{in_struct}, in @code{insn} and @code{jump_insn} and @code{call_insn}
-@item INSN_FROM_TARGET_P (@var{x})
-In an @code{insn} or @code{jump_insn} or @code{call_insn} in a delay
-slot of a branch, indicates that the insn
-is from the target of the branch. If the branch insn has
-@code{INSN_ANNULLED_BRANCH_P} set, this insn will only be executed if
-the branch is taken. For annulled branches with
-@code{INSN_FROM_TARGET_P} clear, the insn will be executed only if the
-branch is not taken. When @code{INSN_ANNULLED_BRANCH_P} is not set,
-this insn will always be executed. Stored in the @code{in_struct}
-field and printed as @samp{/s}.
-
-@findex LABEL_PRESERVE_P
-@cindex @code{code_label} and @samp{/i}
-@cindex @code{note} and @samp{/i}
-@cindex @code{in_struct}, in @code{code_label} and @code{note}
-@item LABEL_PRESERVE_P (@var{x})
-In a @code{code_label} or @code{note}, indicates that the label is referenced by
-code or data not visible to the RTL of a given function.
-Labels referenced by a non-local goto will have this bit set. Stored
-in the @code{in_struct} field and printed as @samp{/s}.
-
-@findex LABEL_REF_NONLOCAL_P
-@cindex @code{label_ref} and @samp{/v}
-@cindex @code{reg_label} and @samp{/v}
-@cindex @code{volatil}, in @code{label_ref} and @code{reg_label}
-@item LABEL_REF_NONLOCAL_P (@var{x})
-In @code{label_ref} and @code{reg_label} expressions, nonzero if this is
-a reference to a non-local label.
-Stored in the @code{volatil} field and printed as @samp{/v}.
-
-@findex MEM_KEEP_ALIAS_SET_P
-@cindex @code{mem} and @samp{/j}
-@cindex @code{jump}, in @code{mem}
-@item MEM_KEEP_ALIAS_SET_P (@var{x})
-In @code{mem} expressions, 1 if we should keep the alias set for this
-mem unchanged when we access a component. Set to 1, for example, when we
-are already in a non-addressable component of an aggregate.
-Stored in the @code{jump} field and printed as @samp{/j}.
-
-@findex MEM_VOLATILE_P
-@cindex @code{mem} and @samp{/v}
-@cindex @code{asm_input} and @samp{/v}
-@cindex @code{asm_operands} and @samp{/v}
-@cindex @code{volatil}, in @code{mem}, @code{asm_operands}, and @code{asm_input}
-@item MEM_VOLATILE_P (@var{x})
-In @code{mem}, @code{asm_operands}, and @code{asm_input} expressions,
-nonzero for volatile memory references.
-Stored in the @code{volatil} field and printed as @samp{/v}.
-
-@findex MEM_NOTRAP_P
-@cindex @code{mem} and @samp{/c}
-@cindex @code{call}, in @code{mem}
-@item MEM_NOTRAP_P (@var{x})
-In @code{mem}, nonzero for memory references that will not trap.
-Stored in the @code{call} field and printed as @samp{/c}.
-
-@findex MEM_POINTER
-@cindex @code{mem} and @samp{/f}
-@cindex @code{frame_related}, in @code{mem}
-@item MEM_POINTER (@var{x})
-Nonzero in a @code{mem} if the memory reference holds a pointer.
-Stored in the @code{frame_related} field and printed as @samp{/f}.
-
-@findex MEM_READONLY_P
-@cindex @code{mem} and @samp{/u}
-@cindex @code{unchanging}, in @code{mem}
-@item MEM_READONLY_P (@var{x})
-Nonzero in a @code{mem}, if the memory is statically allocated and read-only.
-
-Read-only in this context means never modified during the lifetime of the
-program, not necessarily in ROM or in write-disabled pages. A common
-example of the later is a shared library's global offset table. This
-table is initialized by the runtime loader, so the memory is technically
-writable, but after control is transferred from the runtime loader to the
-application, this memory will never be subsequently modified.
-
-Stored in the @code{unchanging} field and printed as @samp{/u}.
-
-@findex PREFETCH_SCHEDULE_BARRIER_P
-@cindex @code{prefetch} and @samp{/v}
-@cindex @code{volatile}, in @code{prefetch}
-@item PREFETCH_SCHEDULE_BARRIER_P (@var{x})
-In a @code{prefetch}, indicates that the prefetch is a scheduling barrier.
-No other INSNs will be moved over it.
-Stored in the @code{volatil} field and printed as @samp{/v}.
-
-@findex REG_FUNCTION_VALUE_P
-@cindex @code{reg} and @samp{/i}
-@cindex @code{return_val}, in @code{reg}
-@item REG_FUNCTION_VALUE_P (@var{x})
-Nonzero in a @code{reg} if it is the place in which this function's
-value is going to be returned. (This happens only in a hard
-register.) Stored in the @code{return_val} field and printed as
-@samp{/i}.
-
-@findex REG_POINTER
-@cindex @code{reg} and @samp{/f}
-@cindex @code{frame_related}, in @code{reg}
-@item REG_POINTER (@var{x})
-Nonzero in a @code{reg} if the register holds a pointer. Stored in the
-@code{frame_related} field and printed as @samp{/f}.
-
-@findex REG_USERVAR_P
-@cindex @code{reg} and @samp{/v}
-@cindex @code{volatil}, in @code{reg}
-@item REG_USERVAR_P (@var{x})
-In a @code{reg}, nonzero if it corresponds to a variable present in
-the user's source code. Zero for temporaries generated internally by
-the compiler. Stored in the @code{volatil} field and printed as
-@samp{/v}.
-
-The same hard register may be used also for collecting the values of
-functions called by this one, but @code{REG_FUNCTION_VALUE_P} is zero
-in this kind of use.
-
-@findex RTL_CONST_CALL_P
-@cindex @code{call_insn} and @samp{/u}
-@cindex @code{unchanging}, in @code{call_insn}
-@item RTL_CONST_CALL_P (@var{x})
-In a @code{call_insn} indicates that the insn represents a call to a
-const function. Stored in the @code{unchanging} field and printed as
-@samp{/u}.
-
-@findex RTL_PURE_CALL_P
-@cindex @code{call_insn} and @samp{/i}
-@cindex @code{return_val}, in @code{call_insn}
-@item RTL_PURE_CALL_P (@var{x})
-In a @code{call_insn} indicates that the insn represents a call to a
-pure function. Stored in the @code{return_val} field and printed as
-@samp{/i}.
-
-@findex RTL_CONST_OR_PURE_CALL_P
-@cindex @code{call_insn} and @samp{/u} or @samp{/i}
-@item RTL_CONST_OR_PURE_CALL_P (@var{x})
-In a @code{call_insn}, true if @code{RTL_CONST_CALL_P} or
-@code{RTL_PURE_CALL_P} is true.
-
-@findex RTL_LOOPING_CONST_OR_PURE_CALL_P
-@cindex @code{call_insn} and @samp{/c}
-@cindex @code{call}, in @code{call_insn}
-@item RTL_LOOPING_CONST_OR_PURE_CALL_P (@var{x})
-In a @code{call_insn} indicates that the insn represents a possibly
-infinite looping call to a const or pure function. Stored in the
-@code{call} field and printed as @samp{/c}. Only true if one of
-@code{RTL_CONST_CALL_P} or @code{RTL_PURE_CALL_P} is true.
-
-@findex RTX_FRAME_RELATED_P
-@cindex @code{insn} and @samp{/f}
-@cindex @code{call_insn} and @samp{/f}
-@cindex @code{jump_insn} and @samp{/f}
-@cindex @code{barrier} and @samp{/f}
-@cindex @code{set} and @samp{/f}
-@cindex @code{frame_related}, in @code{insn}, @code{call_insn}, @code{jump_insn}, @code{barrier}, and @code{set}
-@item RTX_FRAME_RELATED_P (@var{x})
-Nonzero in an @code{insn}, @code{call_insn}, @code{jump_insn},
-@code{barrier}, or @code{set} which is part of a function prologue
-and sets the stack pointer, sets the frame pointer, or saves a register.
-This flag should also be set on an instruction that sets up a temporary
-register to use in place of the frame pointer.
-Stored in the @code{frame_related} field and printed as @samp{/f}.
-
-In particular, on RISC targets where there are limits on the sizes of
-immediate constants, it is sometimes impossible to reach the register
-save area directly from the stack pointer. In that case, a temporary
-register is used that is near enough to the register save area, and the
-Canonical Frame Address, i.e., DWARF2's logical frame pointer, register
-must (temporarily) be changed to be this temporary register. So, the
-instruction that sets this temporary register must be marked as
-@code{RTX_FRAME_RELATED_P}.
-
-If the marked instruction is overly complex (defined in terms of what
-@code{dwarf2out_frame_debug_expr} can handle), you will also have to
-create a @code{REG_FRAME_RELATED_EXPR} note and attach it to the
-instruction. This note should contain a simple expression of the
-computation performed by this instruction, i.e., one that
-@code{dwarf2out_frame_debug_expr} can handle.
-
-This flag is required for exception handling support on targets with RTL
-prologues.
-
-@findex SCHED_GROUP_P
-@cindex @code{insn} and @samp{/s}
-@cindex @code{call_insn} and @samp{/s}
-@cindex @code{jump_insn} and @samp{/s}
-@cindex @code{jump_table_data} and @samp{/s}
-@cindex @code{in_struct}, in @code{insn}, @code{call_insn}, @code{jump_insn} and @code{jump_table_data}
-@item SCHED_GROUP_P (@var{x})
-During instruction scheduling, in an @code{insn}, @code{call_insn},
-@code{jump_insn} or @code{jump_table_data}, indicates that the
-previous insn must be scheduled together with this insn. This is used to
-ensure that certain groups of instructions will not be split up by the
-instruction scheduling pass, for example, @code{use} insns before
-a @code{call_insn} may not be separated from the @code{call_insn}.
-Stored in the @code{in_struct} field and printed as @samp{/s}.
-
-@findex SET_IS_RETURN_P
-@cindex @code{insn} and @samp{/j}
-@cindex @code{jump}, in @code{insn}
-@item SET_IS_RETURN_P (@var{x})
-For a @code{set}, nonzero if it is for a return.
-Stored in the @code{jump} field and printed as @samp{/j}.
-
-@findex SIBLING_CALL_P
-@cindex @code{call_insn} and @samp{/j}
-@cindex @code{jump}, in @code{call_insn}
-@item SIBLING_CALL_P (@var{x})
-For a @code{call_insn}, nonzero if the insn is a sibling call.
-Stored in the @code{jump} field and printed as @samp{/j}.
-
-@findex STRING_POOL_ADDRESS_P
-@cindex @code{symbol_ref} and @samp{/f}
-@cindex @code{frame_related}, in @code{symbol_ref}
-@item STRING_POOL_ADDRESS_P (@var{x})
-For a @code{symbol_ref} expression, nonzero if it addresses this function's
-string constant pool.
-Stored in the @code{frame_related} field and printed as @samp{/f}.
-
-@findex SUBREG_PROMOTED_UNSIGNED_P
-@cindex @code{subreg} and @samp{/u} and @samp{/v}
-@cindex @code{unchanging}, in @code{subreg}
-@cindex @code{volatil}, in @code{subreg}
-@item SUBREG_PROMOTED_UNSIGNED_P (@var{x})
-Returns a value greater then zero for a @code{subreg} that has
-@code{SUBREG_PROMOTED_VAR_P} nonzero if the object being referenced is kept
-zero-extended, zero if it is kept sign-extended, and less then zero if it is
-extended some other way via the @code{ptr_extend} instruction.
-Stored in the @code{unchanging}
-field and @code{volatil} field, printed as @samp{/u} and @samp{/v}.
-This macro may only be used to get the value it may not be used to change
-the value. Use @code{SUBREG_PROMOTED_UNSIGNED_SET} to change the value.
-
-@findex SUBREG_PROMOTED_UNSIGNED_SET
-@cindex @code{subreg} and @samp{/u}
-@cindex @code{unchanging}, in @code{subreg}
-@cindex @code{volatil}, in @code{subreg}
-@item SUBREG_PROMOTED_UNSIGNED_SET (@var{x})
-Set the @code{unchanging} and @code{volatil} fields in a @code{subreg}
-to reflect zero, sign, or other extension. If @code{volatil} is
-zero, then @code{unchanging} as nonzero means zero extension and as
-zero means sign extension. If @code{volatil} is nonzero then some
-other type of extension was done via the @code{ptr_extend} instruction.
-
-@findex SUBREG_PROMOTED_VAR_P
-@cindex @code{subreg} and @samp{/s}
-@cindex @code{in_struct}, in @code{subreg}
-@item SUBREG_PROMOTED_VAR_P (@var{x})
-Nonzero in a @code{subreg} if it was made when accessing an object that
-was promoted to a wider mode in accord with the @code{PROMOTED_MODE} machine
-description macro (@pxref{Storage Layout}). In this case, the mode of
-the @code{subreg} is the declared mode of the object and the mode of
-@code{SUBREG_REG} is the mode of the register that holds the object.
-Promoted variables are always either sign- or zero-extended to the wider
-mode on every assignment. Stored in the @code{in_struct} field and
-printed as @samp{/s}.
-
-@findex SYMBOL_REF_USED
-@cindex @code{used}, in @code{symbol_ref}
-@item SYMBOL_REF_USED (@var{x})
-In a @code{symbol_ref}, indicates that @var{x} has been used. This is
-normally only used to ensure that @var{x} is only declared external
-once. Stored in the @code{used} field.
-
-@findex SYMBOL_REF_WEAK
-@cindex @code{symbol_ref} and @samp{/i}
-@cindex @code{return_val}, in @code{symbol_ref}
-@item SYMBOL_REF_WEAK (@var{x})
-In a @code{symbol_ref}, indicates that @var{x} has been declared weak.
-Stored in the @code{return_val} field and printed as @samp{/i}.
-
-@findex SYMBOL_REF_FLAG
-@cindex @code{symbol_ref} and @samp{/v}
-@cindex @code{volatil}, in @code{symbol_ref}
-@item SYMBOL_REF_FLAG (@var{x})
-In a @code{symbol_ref}, this is used as a flag for machine-specific purposes.
-Stored in the @code{volatil} field and printed as @samp{/v}.
-
-Most uses of @code{SYMBOL_REF_FLAG} are historic and may be subsumed
-by @code{SYMBOL_REF_FLAGS}. Certainly use of @code{SYMBOL_REF_FLAGS}
-is mandatory if the target requires more than one bit of storage.
-@end table
-
-These are the fields to which the above macros refer:
-
-@table @code
-@findex call
-@cindex @samp{/c} in RTL dump
-@item call
-In a @code{mem}, 1 means that the memory reference will not trap.
-
-In a @code{call}, 1 means that this pure or const call may possibly
-infinite loop.
-
-In an RTL dump, this flag is represented as @samp{/c}.
-
-@findex frame_related
-@cindex @samp{/f} in RTL dump
-@item frame_related
-In an @code{insn} or @code{set} expression, 1 means that it is part of
-a function prologue and sets the stack pointer, sets the frame pointer,
-saves a register, or sets up a temporary register to use in place of the
-frame pointer.
-
-In @code{reg} expressions, 1 means that the register holds a pointer.
-
-In @code{mem} expressions, 1 means that the memory reference holds a pointer.
-
-In @code{symbol_ref} expressions, 1 means that the reference addresses
-this function's string constant pool.
-
-In an RTL dump, this flag is represented as @samp{/f}.
-
-@findex in_struct
-@cindex @samp{/s} in RTL dump
-@item in_struct
-In @code{reg} expressions, it is 1 if the register has its entire life
-contained within the test expression of some loop.
-
-In @code{subreg} expressions, 1 means that the @code{subreg} is accessing
-an object that has had its mode promoted from a wider mode.
-
-In @code{label_ref} expressions, 1 means that the referenced label is
-outside the innermost loop containing the insn in which the @code{label_ref}
-was found.
-
-In @code{code_label} expressions, it is 1 if the label may never be deleted.
-This is used for labels which are the target of non-local gotos. Such a
-label that would have been deleted is replaced with a @code{note} of type
-@code{NOTE_INSN_DELETED_LABEL}.
-
-In an @code{insn} during dead-code elimination, 1 means that the insn is
-dead code.
-
-In an @code{insn} or @code{jump_insn} during reorg for an insn in the
-delay slot of a branch,
-1 means that this insn is from the target of the branch.
-
-In an @code{insn} during instruction scheduling, 1 means that this insn
-must be scheduled as part of a group together with the previous insn.
-
-In an RTL dump, this flag is represented as @samp{/s}.
-
-@findex return_val
-@cindex @samp{/i} in RTL dump
-@item return_val
-In @code{reg} expressions, 1 means the register contains
-the value to be returned by the current function. On
-machines that pass parameters in registers, the same register number
-may be used for parameters as well, but this flag is not set on such
-uses.
-
-In @code{symbol_ref} expressions, 1 means the referenced symbol is weak.
-
-In @code{call} expressions, 1 means the call is pure.
-
-In an RTL dump, this flag is represented as @samp{/i}.
-
-@findex jump
-@cindex @samp{/j} in RTL dump
-@item jump
-In a @code{mem} expression, 1 means we should keep the alias set for this
-mem unchanged when we access a component.
-
-In a @code{set}, 1 means it is for a return.
-
-In a @code{call_insn}, 1 means it is a sibling call.
-
-In a @code{jump_insn}, 1 means it is a crossing jump.
-
-In an RTL dump, this flag is represented as @samp{/j}.
-
-@findex unchanging
-@cindex @samp{/u} in RTL dump
-@item unchanging
-In @code{reg} and @code{mem} expressions, 1 means
-that the value of the expression never changes.
-
-In @code{subreg} expressions, it is 1 if the @code{subreg} references an
-unsigned object whose mode has been promoted to a wider mode.
-
-In an @code{insn} or @code{jump_insn} in the delay slot of a branch
-instruction, 1 means an annulling branch should be used.
-
-In a @code{symbol_ref} expression, 1 means that this symbol addresses
-something in the per-function constant pool.
-
-In a @code{call_insn} 1 means that this instruction is a call to a const
-function.
-
-In an RTL dump, this flag is represented as @samp{/u}.
-
-@findex used
-@item used
-This flag is used directly (without an access macro) at the end of RTL
-generation for a function, to count the number of times an expression
-appears in insns. Expressions that appear more than once are copied,
-according to the rules for shared structure (@pxref{Sharing}).
-
-For a @code{reg}, it is used directly (without an access macro) by the
-leaf register renumbering code to ensure that each register is only
-renumbered once.
-
-In a @code{symbol_ref}, it indicates that an external declaration for
-the symbol has already been written.
-
-@findex volatil
-@cindex @samp{/v} in RTL dump
-@item volatil
-@cindex volatile memory references
-In a @code{mem}, @code{asm_operands}, or @code{asm_input}
-expression, it is 1 if the memory
-reference is volatile. Volatile memory references may not be deleted,
-reordered or combined.
-
-In a @code{symbol_ref} expression, it is used for machine-specific
-purposes.
-
-In a @code{reg} expression, it is 1 if the value is a user-level variable.
-0 indicates an internal compiler temporary.
-
-In an @code{insn}, 1 means the insn has been deleted.
-
-In @code{label_ref} and @code{reg_label} expressions, 1 means a reference
-to a non-local label.
-
-In @code{prefetch} expressions, 1 means that the containing insn is a
-scheduling barrier.
-
-In an RTL dump, this flag is represented as @samp{/v}.
-@end table
-
-@node Machine Modes
-@section Machine Modes
-@cindex machine modes
-
-@findex machine_mode
-A machine mode describes a size of data object and the representation used
-for it. In the C code, machine modes are represented by an enumeration
-type, @code{machine_mode}, defined in @file{machmode.def}. Each RTL
-expression has room for a machine mode and so do certain kinds of tree
-expressions (declarations and types, to be precise).
-
-In debugging dumps and machine descriptions, the machine mode of an RTL
-expression is written after the expression code with a colon to separate
-them. The letters @samp{mode} which appear at the end of each machine mode
-name are omitted. For example, @code{(reg:SI 38)} is a @code{reg}
-expression with machine mode @code{SImode}. If the mode is
-@code{VOIDmode}, it is not written at all.
-
-Here is a table of machine modes. The term ``byte'' below refers to an
-object of @code{BITS_PER_UNIT} bits (@pxref{Storage Layout}).
-
-@table @code
-@findex BImode
-@item BImode
-``Bit'' mode represents a single bit, for predicate registers.
-
-@findex QImode
-@item QImode
-``Quarter-Integer'' mode represents a single byte treated as an integer.
-
-@findex HImode
-@item HImode
-``Half-Integer'' mode represents a two-byte integer.
-
-@findex PSImode
-@item PSImode
-``Partial Single Integer'' mode represents an integer which occupies
-four bytes but which doesn't really use all four. On some machines,
-this is the right mode to use for pointers.
-
-@findex SImode
-@item SImode
-``Single Integer'' mode represents a four-byte integer.
-
-@findex PDImode
-@item PDImode
-``Partial Double Integer'' mode represents an integer which occupies
-eight bytes but which doesn't really use all eight. On some machines,
-this is the right mode to use for certain pointers.
-
-@findex DImode
-@item DImode
-``Double Integer'' mode represents an eight-byte integer.
-
-@findex TImode
-@item TImode
-``Tetra Integer'' (?) mode represents a sixteen-byte integer.
-
-@findex OImode
-@item OImode
-``Octa Integer'' (?) mode represents a thirty-two-byte integer.
-
-@findex XImode
-@item XImode
-``Hexadeca Integer'' (?) mode represents a sixty-four-byte integer.
-
-@findex QFmode
-@item QFmode
-``Quarter-Floating'' mode represents a quarter-precision (single byte)
-floating point number.
-
-@findex HFmode
-@item HFmode
-``Half-Floating'' mode represents a half-precision (two byte) floating
-point number.
-
-@findex TQFmode
-@item TQFmode
-``Three-Quarter-Floating'' (?) mode represents a three-quarter-precision
-(three byte) floating point number.
-
-@findex SFmode
-@item SFmode
-``Single Floating'' mode represents a four byte floating point number.
-In the common case, of a processor with IEEE arithmetic and 8-bit bytes,
-this is a single-precision IEEE floating point number; it can also be
-used for double-precision (on processors with 16-bit bytes) and
-single-precision VAX and IBM types.
-
-@findex DFmode
-@item DFmode
-``Double Floating'' mode represents an eight byte floating point number.
-In the common case, of a processor with IEEE arithmetic and 8-bit bytes,
-this is a double-precision IEEE floating point number.
-
-@findex XFmode
-@item XFmode
-``Extended Floating'' mode represents an IEEE extended floating point
-number. This mode only has 80 meaningful bits (ten bytes). Some
-processors require such numbers to be padded to twelve bytes, others
-to sixteen; this mode is used for either.
-
-@findex SDmode
-@item SDmode
-``Single Decimal Floating'' mode represents a four byte decimal
-floating point number (as distinct from conventional binary floating
-point).
-
-@findex DDmode
-@item DDmode
-``Double Decimal Floating'' mode represents an eight byte decimal
-floating point number.
-
-@findex TDmode
-@item TDmode
-``Tetra Decimal Floating'' mode represents a sixteen byte decimal
-floating point number all 128 of whose bits are meaningful.
-
-@findex TFmode
-@item TFmode
-``Tetra Floating'' mode represents a sixteen byte floating point number
-all 128 of whose bits are meaningful. One common use is the
-IEEE quad-precision format.
-
-@findex QQmode
-@item QQmode
-``Quarter-Fractional'' mode represents a single byte treated as a signed
-fractional number. The default format is ``s.7''.
-
-@findex HQmode
-@item HQmode
-``Half-Fractional'' mode represents a two-byte signed fractional number.
-The default format is ``s.15''.
-
-@findex SQmode
-@item SQmode
-``Single Fractional'' mode represents a four-byte signed fractional number.
-The default format is ``s.31''.
-
-@findex DQmode
-@item DQmode
-``Double Fractional'' mode represents an eight-byte signed fractional number.
-The default format is ``s.63''.
-
-@findex TQmode
-@item TQmode
-``Tetra Fractional'' mode represents a sixteen-byte signed fractional number.
-The default format is ``s.127''.
-
-@findex UQQmode
-@item UQQmode
-``Unsigned Quarter-Fractional'' mode represents a single byte treated as an
-unsigned fractional number. The default format is ``.8''.
-
-@findex UHQmode
-@item UHQmode
-``Unsigned Half-Fractional'' mode represents a two-byte unsigned fractional
-number. The default format is ``.16''.
-
-@findex USQmode
-@item USQmode
-``Unsigned Single Fractional'' mode represents a four-byte unsigned fractional
-number. The default format is ``.32''.
-
-@findex UDQmode
-@item UDQmode
-``Unsigned Double Fractional'' mode represents an eight-byte unsigned
-fractional number. The default format is ``.64''.
-
-@findex UTQmode
-@item UTQmode
-``Unsigned Tetra Fractional'' mode represents a sixteen-byte unsigned
-fractional number. The default format is ``.128''.
-
-@findex HAmode
-@item HAmode
-``Half-Accumulator'' mode represents a two-byte signed accumulator.
-The default format is ``s8.7''.
-
-@findex SAmode
-@item SAmode
-``Single Accumulator'' mode represents a four-byte signed accumulator.
-The default format is ``s16.15''.
-
-@findex DAmode
-@item DAmode
-``Double Accumulator'' mode represents an eight-byte signed accumulator.
-The default format is ``s32.31''.
-
-@findex TAmode
-@item TAmode
-``Tetra Accumulator'' mode represents a sixteen-byte signed accumulator.
-The default format is ``s64.63''.
-
-@findex UHAmode
-@item UHAmode
-``Unsigned Half-Accumulator'' mode represents a two-byte unsigned accumulator.
-The default format is ``8.8''.
-
-@findex USAmode
-@item USAmode
-``Unsigned Single Accumulator'' mode represents a four-byte unsigned
-accumulator. The default format is ``16.16''.
-
-@findex UDAmode
-@item UDAmode
-``Unsigned Double Accumulator'' mode represents an eight-byte unsigned
-accumulator. The default format is ``32.32''.
-
-@findex UTAmode
-@item UTAmode
-``Unsigned Tetra Accumulator'' mode represents a sixteen-byte unsigned
-accumulator. The default format is ``64.64''.
-
-@findex CCmode
-@item CCmode
-``Condition Code'' mode represents the value of a condition code, which
-is a machine-specific set of bits used to represent the result of a
-comparison operation. Other machine-specific modes may also be used for
-the condition code. (@pxref{Condition Code}).
-
-@findex BLKmode
-@item BLKmode
-``Block'' mode represents values that are aggregates to which none of
-the other modes apply. In RTL, only memory references can have this mode,
-and only if they appear in string-move or vector instructions. On machines
-which have no such instructions, @code{BLKmode} will not appear in RTL@.
-
-@findex VOIDmode
-@item VOIDmode
-Void mode means the absence of a mode or an unspecified mode.
-For example, RTL expressions of code @code{const_int} have mode
-@code{VOIDmode} because they can be taken to have whatever mode the context
-requires. In debugging dumps of RTL, @code{VOIDmode} is expressed by
-the absence of any mode.
-
-@findex QCmode
-@findex HCmode
-@findex SCmode
-@findex DCmode
-@findex XCmode
-@findex TCmode
-@item QCmode, HCmode, SCmode, DCmode, XCmode, TCmode
-These modes stand for a complex number represented as a pair of floating
-point values. The floating point values are in @code{QFmode},
-@code{HFmode}, @code{SFmode}, @code{DFmode}, @code{XFmode}, and
-@code{TFmode}, respectively.
-
-@findex CQImode
-@findex CHImode
-@findex CSImode
-@findex CDImode
-@findex CTImode
-@findex COImode
-@findex CPSImode
-@item CQImode, CHImode, CSImode, CDImode, CTImode, COImode, CPSImode
-These modes stand for a complex number represented as a pair of integer
-values. The integer values are in @code{QImode}, @code{HImode},
-@code{SImode}, @code{DImode}, @code{TImode}, @code{OImode}, and @code{PSImode},
-respectively.
-
-@findex BND32mode
-@findex BND64mode
-@item BND32mode BND64mode
-These modes stand for bounds for pointer of 32 and 64 bit size respectively.
-Mode size is double pointer mode size.
-@end table
-
-The machine description defines @code{Pmode} as a C macro which expands
-into the machine mode used for addresses. Normally this is the mode
-whose size is @code{BITS_PER_WORD}, @code{SImode} on 32-bit machines.
-
-The only modes which a machine description @i{must} support are
-@code{QImode}, and the modes corresponding to @code{BITS_PER_WORD},
-@code{FLOAT_TYPE_SIZE} and @code{DOUBLE_TYPE_SIZE}.
-The compiler will attempt to use @code{DImode} for 8-byte structures and
-unions, but this can be prevented by overriding the definition of
-@code{MAX_FIXED_MODE_SIZE}. Alternatively, you can have the compiler
-use @code{TImode} for 16-byte structures and unions. Likewise, you can
-arrange for the C type @code{short int} to avoid using @code{HImode}.
-
-@cindex mode classes
-Very few explicit references to machine modes remain in the compiler and
-these few references will soon be removed. Instead, the machine modes
-are divided into mode classes. These are represented by the enumeration
-type @code{enum mode_class} defined in @file{machmode.h}. The possible
-mode classes are:
-
-@table @code
-@findex MODE_INT
-@item MODE_INT
-Integer modes. By default these are @code{BImode}, @code{QImode},
-@code{HImode}, @code{SImode}, @code{DImode}, @code{TImode}, and
-@code{OImode}.
-
-@findex MODE_PARTIAL_INT
-@item MODE_PARTIAL_INT
-The ``partial integer'' modes, @code{PQImode}, @code{PHImode},
-@code{PSImode} and @code{PDImode}.
-
-@findex MODE_FLOAT
-@item MODE_FLOAT
-Floating point modes. By default these are @code{QFmode},
-@code{HFmode}, @code{TQFmode}, @code{SFmode}, @code{DFmode},
-@code{XFmode} and @code{TFmode}.
-
-@findex MODE_DECIMAL_FLOAT
-@item MODE_DECIMAL_FLOAT
-Decimal floating point modes. By default these are @code{SDmode},
-@code{DDmode} and @code{TDmode}.
-
-@findex MODE_FRACT
-@item MODE_FRACT
-Signed fractional modes. By default these are @code{QQmode}, @code{HQmode},
-@code{SQmode}, @code{DQmode} and @code{TQmode}.
-
-@findex MODE_UFRACT
-@item MODE_UFRACT
-Unsigned fractional modes. By default these are @code{UQQmode}, @code{UHQmode},
-@code{USQmode}, @code{UDQmode} and @code{UTQmode}.
-
-@findex MODE_ACCUM
-@item MODE_ACCUM
-Signed accumulator modes. By default these are @code{HAmode},
-@code{SAmode}, @code{DAmode} and @code{TAmode}.
-
-@findex MODE_UACCUM
-@item MODE_UACCUM
-Unsigned accumulator modes. By default these are @code{UHAmode},
-@code{USAmode}, @code{UDAmode} and @code{UTAmode}.
-
-@findex MODE_COMPLEX_INT
-@item MODE_COMPLEX_INT
-Complex integer modes. (These are not currently implemented).
-
-@findex MODE_COMPLEX_FLOAT
-@item MODE_COMPLEX_FLOAT
-Complex floating point modes. By default these are @code{QCmode},
-@code{HCmode}, @code{SCmode}, @code{DCmode}, @code{XCmode}, and
-@code{TCmode}.
-
-@findex MODE_CC
-@item MODE_CC
-Modes representing condition code values. These are @code{CCmode} plus
-any @code{CC_MODE} modes listed in the @file{@var{machine}-modes.def}.
-@xref{Jump Patterns},
-also see @ref{Condition Code}.
-
-@findex MODE_POINTER_BOUNDS
-@item MODE_POINTER_BOUNDS
-Pointer bounds modes. Used to represent values of pointer bounds type.
-Operations in these modes may be executed as NOPs depending on hardware
-features and environment setup.
-
-@findex MODE_OPAQUE
-@item MODE_OPAQUE
-This is a mode class for modes that don't want to provide operations
-other than register moves, memory moves, loads, stores, and
-@code{unspec}s. They have a size and precision and that's all.
-
-@findex MODE_RANDOM
-@item MODE_RANDOM
-This is a catchall mode class for modes which don't fit into the above
-classes. Currently @code{VOIDmode} and @code{BLKmode} are in
-@code{MODE_RANDOM}.
-@end table
-
-@cindex machine mode wrapper classes
-@code{machmode.h} also defines various wrapper classes that combine a
-@code{machine_mode} with a static assertion that a particular
-condition holds. The classes are:
-
-@table @code
-@findex scalar_int_mode
-@item scalar_int_mode
-A mode that has class @code{MODE_INT} or @code{MODE_PARTIAL_INT}.
-
-@findex scalar_float_mode
-@item scalar_float_mode
-A mode that has class @code{MODE_FLOAT} or @code{MODE_DECIMAL_FLOAT}.
-
-@findex scalar_mode
-@item scalar_mode
-A mode that holds a single numerical value. In practice this means
-that the mode is a @code{scalar_int_mode}, is a @code{scalar_float_mode},
-or has class @code{MODE_FRACT}, @code{MODE_UFRACT}, @code{MODE_ACCUM},
-@code{MODE_UACCUM} or @code{MODE_POINTER_BOUNDS}.
-
-@findex complex_mode
-@item complex_mode
-A mode that has class @code{MODE_COMPLEX_INT} or @code{MODE_COMPLEX_FLOAT}.
-
-@findex fixed_size_mode
-@item fixed_size_mode
-A mode whose size is known at compile time.
-@end table
-
-Named modes use the most constrained of the available wrapper classes,
-if one exists, otherwise they use @code{machine_mode}. For example,
-@code{QImode} is a @code{scalar_int_mode}, @code{SFmode} is a
-@code{scalar_float_mode} and @code{BLKmode} is a plain
-@code{machine_mode}. It is possible to refer to any mode as a raw
-@code{machine_mode} by adding the @code{E_} prefix, where @code{E}
-stands for ``enumeration''. For example, the raw @code{machine_mode}
-names of the modes just mentioned are @code{E_QImode}, @code{E_SFmode}
-and @code{E_BLKmode} respectively.
-
-The wrapper classes implicitly convert to @code{machine_mode} and to any
-wrapper class that represents a more general condition; for example
-@code{scalar_int_mode} and @code{scalar_float_mode} both convert
-to @code{scalar_mode} and all three convert to @code{fixed_size_mode}.
-The classes act like @code{machine_mode}s that accept only certain
-named modes.
-
-@findex opt_mode
-@file{machmode.h} also defines a template class @code{opt_mode<@var{T}>}
-that holds a @code{T} or nothing, where @code{T} can be either
-@code{machine_mode} or one of the wrapper classes above. The main
-operations on an @code{opt_mode<@var{T}>} @var{x} are as follows:
-
-@table @samp
-@item @var{x}.exists ()
-Return true if @var{x} holds a mode rather than nothing.
-
-@item @var{x}.exists (&@var{y})
-Return true if @var{x} holds a mode rather than nothing, storing the
-mode in @var{y} if so. @var{y} must be assignment-compatible with @var{T}.
-
-@item @var{x}.require ()
-Assert that @var{x} holds a mode rather than nothing and return that mode.
-
-@item @var{x} = @var{y}
-Set @var{x} to @var{y}, where @var{y} is a @var{T} or implicitly converts
-to a @var{T}.
-@end table
-
-The default constructor sets an @code{opt_mode<@var{T}>} to nothing.
-There is also a constructor that takes an initial value of type @var{T}.
-
-It is possible to use the @file{is-a.h} accessors on a @code{machine_mode}
-or machine mode wrapper @var{x}:
-
-@table @samp
-@findex is_a
-@item is_a <@var{T}> (@var{x})
-Return true if @var{x} meets the conditions for wrapper class @var{T}.
-
-@item is_a <@var{T}> (@var{x}, &@var{y})
-Return true if @var{x} meets the conditions for wrapper class @var{T},
-storing it in @var{y} if so. @var{y} must be assignment-compatible with
-@var{T}.
-
-@item as_a <@var{T}> (@var{x})
-Assert that @var{x} meets the conditions for wrapper class @var{T}
-and return it as a @var{T}.
-
-@item dyn_cast <@var{T}> (@var{x})
-Return an @code{opt_mode<@var{T}>} that holds @var{x} if @var{x} meets
-the conditions for wrapper class @var{T} and that holds nothing otherwise.
-@end table
-
-The purpose of these wrapper classes is to give stronger static type
-checking. For example, if a function takes a @code{scalar_int_mode},
-a caller that has a general @code{machine_mode} must either check or
-assert that the code is indeed a scalar integer first, using one of
-the functions above.
-
-The wrapper classes are normal C++ classes, with user-defined
-constructors. Sometimes it is useful to have a POD version of
-the same type, particularly if the type appears in a @code{union}.
-The template class @code{pod_mode<@var{T}>} provides a POD version
-of wrapper class @var{T}. It is assignment-compatible with @var{T}
-and implicitly converts to both @code{machine_mode} and @var{T}.
-
-Here are some C macros that relate to machine modes:
-
-@table @code
-@findex GET_MODE
-@item GET_MODE (@var{x})
-Returns the machine mode of the RTX @var{x}.
-
-@findex PUT_MODE
-@item PUT_MODE (@var{x}, @var{newmode})
-Alters the machine mode of the RTX @var{x} to be @var{newmode}.
-
-@findex NUM_MACHINE_MODES
-@item NUM_MACHINE_MODES
-Stands for the number of machine modes available on the target
-machine. This is one greater than the largest numeric value of any
-machine mode.
-
-@findex GET_MODE_NAME
-@item GET_MODE_NAME (@var{m})
-Returns the name of mode @var{m} as a string.
-
-@findex GET_MODE_CLASS
-@item GET_MODE_CLASS (@var{m})
-Returns the mode class of mode @var{m}.
-
-@findex GET_MODE_WIDER_MODE
-@item GET_MODE_WIDER_MODE (@var{m})
-Returns the next wider natural mode. For example, the expression
-@code{GET_MODE_WIDER_MODE (QImode)} returns @code{HImode}.
-
-@findex GET_MODE_SIZE
-@item GET_MODE_SIZE (@var{m})
-Returns the size in bytes of a datum of mode @var{m}.
-
-@findex GET_MODE_BITSIZE
-@item GET_MODE_BITSIZE (@var{m})
-Returns the size in bits of a datum of mode @var{m}.
-
-@findex GET_MODE_IBIT
-@item GET_MODE_IBIT (@var{m})
-Returns the number of integral bits of a datum of fixed-point mode @var{m}.
-
-@findex GET_MODE_FBIT
-@item GET_MODE_FBIT (@var{m})
-Returns the number of fractional bits of a datum of fixed-point mode @var{m}.
-
-@findex GET_MODE_MASK
-@item GET_MODE_MASK (@var{m})
-Returns a bitmask containing 1 for all bits in a word that fit within
-mode @var{m}. This macro can only be used for modes whose bitsize is
-less than or equal to @code{HOST_BITS_PER_INT}.
-
-@findex GET_MODE_ALIGNMENT
-@item GET_MODE_ALIGNMENT (@var{m})
-Return the required alignment, in bits, for an object of mode @var{m}.
-
-@findex GET_MODE_UNIT_SIZE
-@item GET_MODE_UNIT_SIZE (@var{m})
-Returns the size in bytes of the subunits of a datum of mode @var{m}.
-This is the same as @code{GET_MODE_SIZE} except in the case of complex
-modes. For them, the unit size is the size of the real or imaginary
-part.
-
-@findex GET_MODE_NUNITS
-@item GET_MODE_NUNITS (@var{m})
-Returns the number of units contained in a mode, i.e.,
-@code{GET_MODE_SIZE} divided by @code{GET_MODE_UNIT_SIZE}.
-
-@findex GET_CLASS_NARROWEST_MODE
-@item GET_CLASS_NARROWEST_MODE (@var{c})
-Returns the narrowest mode in mode class @var{c}.
-@end table
-
-The following 3 variables are defined on every target. They can be
-used to allocate buffers that are guaranteed to be large enough to
-hold any value that can be represented on the target. The first two
-can be overridden by defining them in the target's mode.def file,
-however, the value must be a constant that can determined very early
-in the compilation process. The third symbol cannot be overridden.
-
-@table @code
-@findex BITS_PER_UNIT
-@item BITS_PER_UNIT
-The number of bits in an addressable storage unit (byte). If you do
-not define this, the default is 8.
-
-@findex MAX_BITSIZE_MODE_ANY_INT
-@item MAX_BITSIZE_MODE_ANY_INT
-The maximum bitsize of any mode that is used in integer math. This
-should be overridden by the target if it uses large integers as
-containers for larger vectors but otherwise never uses the contents to
-compute integer values.
-
-@findex MAX_BITSIZE_MODE_ANY_MODE
-@item MAX_BITSIZE_MODE_ANY_MODE
-The bitsize of the largest mode on the target. The default value is
-the largest mode size given in the mode definition file, which is
-always correct for targets whose modes have a fixed size. Targets
-that might increase the size of a mode beyond this default should define
-@code{MAX_BITSIZE_MODE_ANY_MODE} to the actual upper limit in
-@file{@var{machine}-modes.def}.
-@end table
-
-@findex byte_mode
-@findex word_mode
-The global variables @code{byte_mode} and @code{word_mode} contain modes
-whose classes are @code{MODE_INT} and whose bitsizes are either
-@code{BITS_PER_UNIT} or @code{BITS_PER_WORD}, respectively. On 32-bit
-machines, these are @code{QImode} and @code{SImode}, respectively.
-
-@node Constants
-@section Constant Expression Types
-@cindex RTL constants
-@cindex RTL constant expression types
-
-The simplest RTL expressions are those that represent constant values.
-
-@table @code
-@findex const_int
-@item (const_int @var{i})
-This type of expression represents the integer value @var{i}. @var{i}
-is customarily accessed with the macro @code{INTVAL} as in
-@code{INTVAL (@var{exp})}, which is equivalent to @code{XWINT (@var{exp}, 0)}.
-
-Constants generated for modes with fewer bits than in
-@code{HOST_WIDE_INT} must be sign extended to full width (e.g., with
-@code{gen_int_mode}). For constants for modes with more bits than in
-@code{HOST_WIDE_INT} the implied high order bits of that constant are
-copies of the top bit. Note however that values are neither
-inherently signed nor inherently unsigned; where necessary, signedness
-is determined by the rtl operation instead.
-
-@findex const0_rtx
-@findex const1_rtx
-@findex const2_rtx
-@findex constm1_rtx
-There is only one expression object for the integer value zero; it is
-the value of the variable @code{const0_rtx}. Likewise, the only
-expression for integer value one is found in @code{const1_rtx}, the only
-expression for integer value two is found in @code{const2_rtx}, and the
-only expression for integer value negative one is found in
-@code{constm1_rtx}. Any attempt to create an expression of code
-@code{const_int} and value zero, one, two or negative one will return
-@code{const0_rtx}, @code{const1_rtx}, @code{const2_rtx} or
-@code{constm1_rtx} as appropriate.
-
-@findex const_true_rtx
-Similarly, there is only one object for the integer whose value is
-@code{STORE_FLAG_VALUE}. It is found in @code{const_true_rtx}. If
-@code{STORE_FLAG_VALUE} is one, @code{const_true_rtx} and
-@code{const1_rtx} will point to the same object. If
-@code{STORE_FLAG_VALUE} is @minus{}1, @code{const_true_rtx} and
-@code{constm1_rtx} will point to the same object.
-
-@findex const_double
-@item (const_double:@var{m} @var{i0} @var{i1} @dots{})
-This represents either a floating-point constant of mode @var{m} or
-(on older ports that do not define
-@code{TARGET_SUPPORTS_WIDE_INT}) an integer constant too large to fit
-into @code{HOST_BITS_PER_WIDE_INT} bits but small enough to fit within
-twice that number of bits. In the latter case, @var{m} will be
-@code{VOIDmode}. For integral values constants for modes with more
-bits than twice the number in @code{HOST_WIDE_INT} the implied high
-order bits of that constant are copies of the top bit of
-@code{CONST_DOUBLE_HIGH}. Note however that integral values are
-neither inherently signed nor inherently unsigned; where necessary,
-signedness is determined by the rtl operation instead.
-
-On more modern ports, @code{CONST_DOUBLE} only represents floating
-point values. New ports define @code{TARGET_SUPPORTS_WIDE_INT} to
-make this designation.
-
-@findex CONST_DOUBLE_LOW
-If @var{m} is @code{VOIDmode}, the bits of the value are stored in
-@var{i0} and @var{i1}. @var{i0} is customarily accessed with the macro
-@code{CONST_DOUBLE_LOW} and @var{i1} with @code{CONST_DOUBLE_HIGH}.
-
-If the constant is floating point (regardless of its precision), then
-the number of integers used to store the value depends on the size of
-@code{REAL_VALUE_TYPE} (@pxref{Floating Point}). The integers
-represent a floating point number, but not precisely in the target
-machine's or host machine's floating point format. To convert them to
-the precise bit pattern used by the target machine, use the macro
-@code{REAL_VALUE_TO_TARGET_DOUBLE} and friends (@pxref{Data Output}).
-
-@findex const_double_zero
-The host dependency for the number of integers used to store a double
-value makes it problematic for machine descriptions to use expressions
-of code @code{const_double} and therefore a syntactic alias has been
-provided:
-
-@smallexample
-(const_double_zero:@var{m})
-@end smallexample
-
-standing for:
-
-@smallexample
-(const_double:@var{m} 0 0 @dots{})
-@end smallexample
-
-for matching the floating-point value zero, possibly the only useful one.
-
-@findex CONST_WIDE_INT
-@item (const_wide_int:@var{m} @var{nunits} @var{elt0} @dots{})
-This contains an array of @code{HOST_WIDE_INT}s that is large enough
-to hold any constant that can be represented on the target. This form
-of rtl is only used on targets that define
-@code{TARGET_SUPPORTS_WIDE_INT} to be nonzero and then
-@code{CONST_DOUBLE}s are only used to hold floating-point values. If
-the target leaves @code{TARGET_SUPPORTS_WIDE_INT} defined as 0,
-@code{CONST_WIDE_INT}s are not used and @code{CONST_DOUBLE}s are as
-they were before.
-
-The values are stored in a compressed format. The higher-order
-0s or -1s are not represented if they are just the logical sign
-extension of the number that is represented.
-
-@findex CONST_WIDE_INT_VEC
-@item CONST_WIDE_INT_VEC (@var{code})
-Returns the entire array of @code{HOST_WIDE_INT}s that are used to
-store the value. This macro should be rarely used.
-
-@findex CONST_WIDE_INT_NUNITS
-@item CONST_WIDE_INT_NUNITS (@var{code})
-The number of @code{HOST_WIDE_INT}s used to represent the number.
-Note that this generally is smaller than the number of
-@code{HOST_WIDE_INT}s implied by the mode size.
-
-@findex CONST_WIDE_INT_ELT
-@item CONST_WIDE_INT_ELT (@var{code},@var{i})
-Returns the @code{i}th element of the array. Element 0 is contains
-the low order bits of the constant.
-
-@findex const_fixed
-@item (const_fixed:@var{m} @dots{})
-Represents a fixed-point constant of mode @var{m}.
-The operand is a data structure of type @code{struct fixed_value} and
-is accessed with the macro @code{CONST_FIXED_VALUE}. The high part of
-data is accessed with @code{CONST_FIXED_VALUE_HIGH}; the low part is
-accessed with @code{CONST_FIXED_VALUE_LOW}.
-
-@findex const_poly_int
-@item (const_poly_int:@var{m} [@var{c0} @var{c1} @dots{}])
-Represents a @code{poly_int}-style polynomial integer with coefficients
-@var{c0}, @var{c1}, @dots{}. The coefficients are @code{wide_int}-based
-integers rather than rtxes. @code{CONST_POLY_INT_COEFFS} gives the
-values of individual coefficients (which is mostly only useful in
-low-level routines) and @code{const_poly_int_value} gives the full
-@code{poly_int} value.
-
-@findex const_vector
-@item (const_vector:@var{m} [@var{x0} @var{x1} @dots{}])
-Represents a vector constant. The values in square brackets are
-elements of the vector, which are always @code{const_int},
-@code{const_wide_int}, @code{const_double} or @code{const_fixed}
-expressions.
-
-Each vector constant @var{v} is treated as a specific instance of an
-arbitrary-length sequence that itself contains
-@samp{CONST_VECTOR_NPATTERNS (@var{v})} interleaved patterns. Each
-pattern has the form:
-
-@smallexample
-@{ @var{base0}, @var{base1}, @var{base1} + @var{step}, @var{base1} + @var{step} * 2, @dots{} @}
-@end smallexample
-
-The first three elements in each pattern are enough to determine the
-values of the other elements. However, if all @var{step}s are zero,
-only the first two elements are needed. If in addition each @var{base1}
-is equal to the corresponding @var{base0}, only the first element in
-each pattern is needed. The number of determining elements per pattern
-is given by @samp{CONST_VECTOR_NELTS_PER_PATTERN (@var{v})}.
-
-For example, the constant:
-
-@smallexample
-@{ 0, 1, 2, 6, 3, 8, 4, 10, 5, 12, 6, 14, 7, 16, 8, 18 @}
-@end smallexample
-
-is interpreted as an interleaving of the sequences:
-
-@smallexample
-@{ 0, 2, 3, 4, 5, 6, 7, 8 @}
-@{ 1, 6, 8, 10, 12, 14, 16, 18 @}
-@end smallexample
-
-where the sequences are represented by the following patterns:
-
-@smallexample
-@var{base0} == 0, @var{base1} == 2, @var{step} == 1
-@var{base0} == 1, @var{base1} == 6, @var{step} == 2
-@end smallexample
-
-In this case:
-
-@smallexample
-CONST_VECTOR_NPATTERNS (@var{v}) == 2
-CONST_VECTOR_NELTS_PER_PATTERN (@var{v}) == 3
-@end smallexample
-
-Thus the first 6 elements (@samp{@{ 0, 1, 2, 6, 3, 8 @}}) are enough
-to determine the whole sequence; we refer to them as the ``encoded''
-elements. They are the only elements present in the square brackets
-for variable-length @code{const_vector}s (i.e.@: for
-@code{const_vector}s whose mode @var{m} has a variable number of
-elements). However, as a convenience to code that needs to handle
-both @code{const_vector}s and @code{parallel}s, all elements are
-present in the square brackets for fixed-length @code{const_vector}s;
-the encoding scheme simply reduces the amount of work involved in
-processing constants that follow a regular pattern.
-
-Sometimes this scheme can create two possible encodings of the same
-vector. For example @{ 0, 1 @} could be seen as two patterns with
-one element each or one pattern with two elements (@var{base0} and
-@var{base1}). The canonical encoding is always the one with the
-fewest patterns or (if both encodings have the same number of
-petterns) the one with the fewest encoded elements.
-
-@samp{const_vector_encoding_nelts (@var{v})} gives the total number of
-encoded elements in @var{v}, which is 6 in the example above.
-@code{CONST_VECTOR_ENCODED_ELT (@var{v}, @var{i})} accesses the value
-of encoded element @var{i}.
-
-@samp{CONST_VECTOR_DUPLICATE_P (@var{v})} is true if @var{v} simply contains
-repeated instances of @samp{CONST_VECTOR_NPATTERNS (@var{v})} values. This is
-a shorthand for testing @samp{CONST_VECTOR_NELTS_PER_PATTERN (@var{v}) == 1}.
-
-@samp{CONST_VECTOR_STEPPED_P (@var{v})} is true if at least one
-pattern in @var{v} has a nonzero step. This is a shorthand for
-testing @samp{CONST_VECTOR_NELTS_PER_PATTERN (@var{v}) == 3}.
-
-@code{CONST_VECTOR_NUNITS (@var{v})} gives the total number of elements
-in @var{v}; it is a shorthand for getting the number of units in
-@samp{GET_MODE (@var{v})}.
-
-The utility function @code{const_vector_elt} gives the value of an
-arbitrary element as an @code{rtx}. @code{const_vector_int_elt} gives
-the same value as a @code{wide_int}.
-
-@findex const_string
-@item (const_string @var{str})
-Represents a constant string with value @var{str}. Currently this is
-used only for insn attributes (@pxref{Insn Attributes}) since constant
-strings in C are placed in memory.
-
-@findex symbol_ref
-@item (symbol_ref:@var{mode} @var{symbol})
-Represents the value of an assembler label for data. @var{symbol} is
-a string that describes the name of the assembler label. If it starts
-with a @samp{*}, the label is the rest of @var{symbol} not including
-the @samp{*}. Otherwise, the label is @var{symbol}, usually prefixed
-with @samp{_}.
-
-The @code{symbol_ref} contains a mode, which is usually @code{Pmode}.
-Usually that is the only mode for which a symbol is directly valid.
-
-@findex label_ref
-@item (label_ref:@var{mode} @var{label})
-Represents the value of an assembler label for code. It contains one
-operand, an expression, which must be a @code{code_label} or a @code{note}
-of type @code{NOTE_INSN_DELETED_LABEL} that appears in the instruction
-sequence to identify the place where the label should go.
-
-The reason for using a distinct expression type for code label
-references is so that jump optimization can distinguish them.
-
-The @code{label_ref} contains a mode, which is usually @code{Pmode}.
-Usually that is the only mode for which a label is directly valid.
-
-@findex const
-@item (const:@var{m} @var{exp})
-Represents a constant that is the result of an assembly-time
-arithmetic computation. The operand, @var{exp}, contains only
-@code{const_int}, @code{symbol_ref}, @code{label_ref} or @code{unspec}
-expressions, combined with @code{plus} and @code{minus}. Any such
-@code{unspec}s are target-specific and typically represent some form
-of relocation operator. @var{m} should be a valid address mode.
-
-@findex high
-@item (high:@var{m} @var{exp})
-Represents the high-order bits of @var{exp}.
-The number of bits is machine-dependent and is
-normally the number of bits specified in an instruction that initializes
-the high order bits of a register. It is used with @code{lo_sum} to
-represent the typical two-instruction sequence used in RISC machines to
-reference large immediate values and/or link-time constants such
-as global memory addresses. In the latter case, @var{m} is @code{Pmode}
-and @var{exp} is usually a constant expression involving @code{symbol_ref}.
-@end table
-
-@findex CONST0_RTX
-@findex CONST1_RTX
-@findex CONST2_RTX
-The macro @code{CONST0_RTX (@var{mode})} refers to an expression with
-value 0 in mode @var{mode}. If mode @var{mode} is of mode class
-@code{MODE_INT}, it returns @code{const0_rtx}. If mode @var{mode} is of
-mode class @code{MODE_FLOAT}, it returns a @code{CONST_DOUBLE}
-expression in mode @var{mode}. Otherwise, it returns a
-@code{CONST_VECTOR} expression in mode @var{mode}. Similarly, the macro
-@code{CONST1_RTX (@var{mode})} refers to an expression with value 1 in
-mode @var{mode} and similarly for @code{CONST2_RTX}. The
-@code{CONST1_RTX} and @code{CONST2_RTX} macros are undefined
-for vector modes.
-
-@node Regs and Memory
-@section Registers and Memory
-@cindex RTL register expressions
-@cindex RTL memory expressions
-
-Here are the RTL expression types for describing access to machine
-registers and to main memory.
-
-@table @code
-@findex reg
-@cindex hard registers
-@cindex pseudo registers
-@item (reg:@var{m} @var{n})
-For small values of the integer @var{n} (those that are less than
-@code{FIRST_PSEUDO_REGISTER}), this stands for a reference to machine
-register number @var{n}: a @dfn{hard register}. For larger values of
-@var{n}, it stands for a temporary value or @dfn{pseudo register}.
-The compiler's strategy is to generate code assuming an unlimited
-number of such pseudo registers, and later convert them into hard
-registers or into memory references.
-
-@var{m} is the machine mode of the reference. It is necessary because
-machines can generally refer to each register in more than one mode.
-For example, a register may contain a full word but there may be
-instructions to refer to it as a half word or as a single byte, as
-well as instructions to refer to it as a floating point number of
-various precisions.
-
-Even for a register that the machine can access in only one mode,
-the mode must always be specified.
-
-The symbol @code{FIRST_PSEUDO_REGISTER} is defined by the machine
-description, since the number of hard registers on the machine is an
-invariant characteristic of the machine. Note, however, that not
-all of the machine registers must be general registers. All the
-machine registers that can be used for storage of data are given
-hard register numbers, even those that can be used only in certain
-instructions or can hold only certain types of data.
-
-A hard register may be accessed in various modes throughout one
-function, but each pseudo register is given a natural mode
-and is accessed only in that mode. When it is necessary to describe
-an access to a pseudo register using a nonnatural mode, a @code{subreg}
-expression is used.
-
-A @code{reg} expression with a machine mode that specifies more than
-one word of data may actually stand for several consecutive registers.
-If in addition the register number specifies a hardware register, then
-it actually represents several consecutive hardware registers starting
-with the specified one.
-
-Each pseudo register number used in a function's RTL code is
-represented by a unique @code{reg} expression.
-
-@findex FIRST_VIRTUAL_REGISTER
-@findex LAST_VIRTUAL_REGISTER
-Some pseudo register numbers, those within the range of
-@code{FIRST_VIRTUAL_REGISTER} to @code{LAST_VIRTUAL_REGISTER} only
-appear during the RTL generation phase and are eliminated before the
-optimization phases. These represent locations in the stack frame that
-cannot be determined until RTL generation for the function has been
-completed. The following virtual register numbers are defined:
-
-@table @code
-@findex VIRTUAL_INCOMING_ARGS_REGNUM
-@item VIRTUAL_INCOMING_ARGS_REGNUM
-This points to the first word of the incoming arguments passed on the
-stack. Normally these arguments are placed there by the caller, but the
-callee may have pushed some arguments that were previously passed in
-registers.
-
-@cindex @code{FIRST_PARM_OFFSET} and virtual registers
-@cindex @code{ARG_POINTER_REGNUM} and virtual registers
-When RTL generation is complete, this virtual register is replaced
-by the sum of the register given by @code{ARG_POINTER_REGNUM} and the
-value of @code{FIRST_PARM_OFFSET}.
-
-@findex VIRTUAL_STACK_VARS_REGNUM
-@cindex @code{FRAME_GROWS_DOWNWARD} and virtual registers
-@item VIRTUAL_STACK_VARS_REGNUM
-If @code{FRAME_GROWS_DOWNWARD} is defined to a nonzero value, this points
-to immediately above the first variable on the stack. Otherwise, it points
-to the first variable on the stack.
-
-@cindex @code{TARGET_STARTING_FRAME_OFFSET} and virtual registers
-@cindex @code{FRAME_POINTER_REGNUM} and virtual registers
-@code{VIRTUAL_STACK_VARS_REGNUM} is replaced with the sum of the
-register given by @code{FRAME_POINTER_REGNUM} and the value
-@code{TARGET_STARTING_FRAME_OFFSET}.
-
-@findex VIRTUAL_STACK_DYNAMIC_REGNUM
-@item VIRTUAL_STACK_DYNAMIC_REGNUM
-This points to the location of dynamically allocated memory on the stack
-immediately after the stack pointer has been adjusted by the amount of
-memory desired.
-
-@cindex @code{STACK_DYNAMIC_OFFSET} and virtual registers
-@cindex @code{STACK_POINTER_REGNUM} and virtual registers
-This virtual register is replaced by the sum of the register given by
-@code{STACK_POINTER_REGNUM} and the value @code{STACK_DYNAMIC_OFFSET}.
-
-@findex VIRTUAL_OUTGOING_ARGS_REGNUM
-@item VIRTUAL_OUTGOING_ARGS_REGNUM
-This points to the location in the stack at which outgoing arguments
-should be written when the stack is pre-pushed (arguments pushed using
-push insns should always use @code{STACK_POINTER_REGNUM}).
-
-@cindex @code{STACK_POINTER_OFFSET} and virtual registers
-This virtual register is replaced by the sum of the register given by
-@code{STACK_POINTER_REGNUM} and the value @code{STACK_POINTER_OFFSET}.
-@end table
-
-@findex subreg
-@item (subreg:@var{m1} @var{reg:m2} @var{bytenum})
-
-@code{subreg} expressions are used to refer to a register in a machine
-mode other than its natural one, or to refer to one register of
-a multi-part @code{reg} that actually refers to several registers.
-
-Each pseudo register has a natural mode. If it is necessary to
-operate on it in a different mode, the register must be
-enclosed in a @code{subreg}.
-
-There are currently three supported types for the first operand of a
-@code{subreg}:
-@itemize
-@item pseudo registers
-This is the most common case. Most @code{subreg}s have pseudo
-@code{reg}s as their first operand.
-
-@item mem
-@code{subreg}s of @code{mem} were common in earlier versions of GCC and
-are still supported. During the reload pass these are replaced by plain
-@code{mem}s. On machines that do not do instruction scheduling, use of
-@code{subreg}s of @code{mem} are still used, but this is no longer
-recommended. Such @code{subreg}s are considered to be
-@code{register_operand}s rather than @code{memory_operand}s before and
-during reload. Because of this, the scheduling passes cannot properly
-schedule instructions with @code{subreg}s of @code{mem}, so for machines
-that do scheduling, @code{subreg}s of @code{mem} should never be used.
-To support this, the combine and recog passes have explicit code to
-inhibit the creation of @code{subreg}s of @code{mem} when
-@code{INSN_SCHEDULING} is defined.
-
-The use of @code{subreg}s of @code{mem} after the reload pass is an area
-that is not well understood and should be avoided. There is still some
-code in the compiler to support this, but this code has possibly rotted.
-This use of @code{subreg}s is discouraged and will most likely not be
-supported in the future.
-
-@item hard registers
-It is seldom necessary to wrap hard registers in @code{subreg}s; such
-registers would normally reduce to a single @code{reg} rtx. This use of
-@code{subreg}s is discouraged and may not be supported in the future.
-
-@end itemize
-
-@code{subreg}s of @code{subreg}s are not supported. Using
-@code{simplify_gen_subreg} is the recommended way to avoid this problem.
-
-@code{subreg}s come in two distinct flavors, each having its own
-usage and rules:
-
-@table @asis
-@item Paradoxical subregs
-When @var{m1} is strictly wider than @var{m2}, the @code{subreg}
-expression is called @dfn{paradoxical}. The canonical test for this
-class of @code{subreg} is:
-
-@smallexample
-paradoxical_subreg_p (@var{m1}, @var{m2})
-@end smallexample
-
-Paradoxical @code{subreg}s can be used as both lvalues and rvalues.
-When used as an lvalue, the low-order bits of the source value
-are stored in @var{reg} and the high-order bits are discarded.
-When used as an rvalue, the low-order bits of the @code{subreg} are
-taken from @var{reg} while the high-order bits may or may not be
-defined.
-
-The high-order bits of rvalues are defined in the following circumstances:
-
-@itemize
-@item @code{subreg}s of @code{mem}
-When @var{m2} is smaller than a word, the macro @code{LOAD_EXTEND_OP},
-can control how the high-order bits are defined.
-
-@item @code{subreg} of @code{reg}s
-The upper bits are defined when @code{SUBREG_PROMOTED_VAR_P} is true.
-@code{SUBREG_PROMOTED_UNSIGNED_P} describes what the upper bits hold.
-Such subregs usually represent local variables, register variables
-and parameter pseudo variables that have been promoted to a wider mode.
-
-@end itemize
-
-@var{bytenum} is always zero for a paradoxical @code{subreg}, even on
-big-endian targets.
-
-For example, the paradoxical @code{subreg}:
-
-@smallexample
-(set (subreg:SI (reg:HI @var{x}) 0) @var{y})
-@end smallexample
-
-stores the lower 2 bytes of @var{y} in @var{x} and discards the upper
-2 bytes. A subsequent:
-
-@smallexample
-(set @var{z} (subreg:SI (reg:HI @var{x}) 0))
-@end smallexample
-
-would set the lower two bytes of @var{z} to @var{y} and set the upper
-two bytes to an unknown value assuming @code{SUBREG_PROMOTED_VAR_P} is
-false.
-
-@item Normal subregs
-When @var{m1} is at least as narrow as @var{m2} the @code{subreg}
-expression is called @dfn{normal}.
-
-@findex REGMODE_NATURAL_SIZE
-Normal @code{subreg}s restrict consideration to certain bits of
-@var{reg}. For this purpose, @var{reg} is divided into
-individually-addressable blocks in which each block has:
-
-@smallexample
-REGMODE_NATURAL_SIZE (@var{m2})
-@end smallexample
-
-bytes. Usually the value is @code{UNITS_PER_WORD}; that is,
-most targets usually treat each word of a register as being
-independently addressable.
-
-There are two types of normal @code{subreg}. If @var{m1} is known
-to be no bigger than a block, the @code{subreg} refers to the
-least-significant part (or @dfn{lowpart}) of one block of @var{reg}.
-If @var{m1} is known to be larger than a block, the @code{subreg} refers
-to two or more complete blocks.
-
-When used as an lvalue, @code{subreg} is a block-based accessor.
-Storing to a @code{subreg} modifies all the blocks of @var{reg} that
-overlap the @code{subreg}, but it leaves the other blocks of @var{reg}
-alone.
-
-When storing to a normal @code{subreg} that is smaller than a block,
-the other bits of the referenced block are usually left in an undefined
-state. This laxity makes it easier to generate efficient code for
-such instructions. To represent an instruction that preserves all the
-bits outside of those in the @code{subreg}, use @code{strict_low_part}
-or @code{zero_extract} around the @code{subreg}.
-
-@var{bytenum} must identify the offset of the first byte of the
-@code{subreg} from the start of @var{reg}, assuming that @var{reg} is
-laid out in memory order. The memory order of bytes is defined by
-two target macros, @code{WORDS_BIG_ENDIAN} and @code{BYTES_BIG_ENDIAN}:
-
-@itemize
-@item
-@cindex @code{WORDS_BIG_ENDIAN}, effect on @code{subreg}
-@code{WORDS_BIG_ENDIAN}, if set to 1, says that byte number zero is
-part of the most significant word; otherwise, it is part of the least
-significant word.
-
-@item
-@cindex @code{BYTES_BIG_ENDIAN}, effect on @code{subreg}
-@code{BYTES_BIG_ENDIAN}, if set to 1, says that byte number zero is
-the most significant byte within a word; otherwise, it is the least
-significant byte within a word.
-@end itemize
-
-@cindex @code{FLOAT_WORDS_BIG_ENDIAN}, (lack of) effect on @code{subreg}
-On a few targets, @code{FLOAT_WORDS_BIG_ENDIAN} disagrees with
-@code{WORDS_BIG_ENDIAN}. However, most parts of the compiler treat
-floating point values as if they had the same endianness as integer
-values. This works because they handle them solely as a collection of
-integer values, with no particular numerical value. Only real.cc and
-the runtime libraries care about @code{FLOAT_WORDS_BIG_ENDIAN}.
-
-Thus,
-
-@smallexample
-(subreg:HI (reg:SI @var{x}) 2)
-@end smallexample
-
-on a @code{BYTES_BIG_ENDIAN}, @samp{UNITS_PER_WORD == 4} target is the same as
-
-@smallexample
-(subreg:HI (reg:SI @var{x}) 0)
-@end smallexample
-
-on a little-endian, @samp{UNITS_PER_WORD == 4} target. Both
-@code{subreg}s access the lower two bytes of register @var{x}.
-
-Note that the byte offset is a polynomial integer; it may not be a
-compile-time constant on targets with variable-sized modes. However,
-the restrictions above mean that there are only a certain set of
-acceptable offsets for a given combination of @var{m1} and @var{m2}.
-The compiler can always tell which blocks a valid subreg occupies, and
-whether the subreg is a lowpart of a block.
-
-@end table
-
-A @code{MODE_PARTIAL_INT} mode behaves as if it were as wide as the
-corresponding @code{MODE_INT} mode, except that it has a number of
-undefined bits, which are determined by the precision of the
-mode.
-
-For example, on a little-endian target which defines @code{PSImode}
-to have a precision of 20 bits:
-
-@smallexample
-(subreg:PSI (reg:SI 0) 0)
-@end smallexample
-
-accesses the low 20 bits of @samp{(reg:SI 0)}.
-
-@findex REGMODE_NATURAL_SIZE
-Continuing with a @code{PSImode} precision of 20 bits, if we assume
-@samp{REGMODE_NATURAL_SIZE (DImode) <= 4},
-then the following two @code{subreg}s:
-
-@smallexample
-(subreg:PSI (reg:DI 0) 0)
-(subreg:PSI (reg:DI 0) 4)
-@end smallexample
-
-represent accesses to the low 20 bits of the two halves of
-@samp{(reg:DI 0)}.
-
-If @samp{REGMODE_NATURAL_SIZE (PSImode) <= 2} then these two @code{subreg}s:
-
-@smallexample
-(subreg:HI (reg:PSI 0) 0)
-(subreg:HI (reg:PSI 0) 2)
-@end smallexample
-
-represent independent 2-byte accesses that together span the whole
-of @samp{(reg:PSI 0)}. Storing to the first @code{subreg} does not
-affect the value of the second, and vice versa, so the assignment:
-
-@smallexample
-(set (subreg:HI (reg:PSI 0) 0) (reg:HI 4))
-@end smallexample
-
-sets the low 16 bits of @samp{(reg:PSI 0)} to @samp{(reg:HI 4)}, and
-the high 4 defined bits of @samp{(reg:PSI 0)} retain their
-original value. The behavior here is the same as for
-normal @code{subreg}s, when there are no
-@code{MODE_PARTIAL_INT} modes involved.
-
-@cindex @code{TARGET_CAN_CHANGE_MODE_CLASS} and subreg semantics
-The rules above apply to both pseudo @var{reg}s and hard @var{reg}s.
-If the semantics are not correct for particular combinations of
-@var{m1}, @var{m2} and hard @var{reg}, the target-specific code
-must ensure that those combinations are never used. For example:
-
-@smallexample
-TARGET_CAN_CHANGE_MODE_CLASS (@var{m2}, @var{m1}, @var{class})
-@end smallexample
-
-must be false for every class @var{class} that includes @var{reg}.
-
-GCC must be able to determine at compile time whether a subreg is
-paradoxical, whether it occupies a whole number of blocks, or whether
-it is a lowpart of a block. This means that certain combinations of
-variable-sized mode are not permitted. For example, if @var{m2}
-holds @var{n} @code{SI} values, where @var{n} is greater than zero,
-it is not possible to form a @code{DI} @code{subreg} of it; such a
-@code{subreg} would be paradoxical when @var{n} is 1 but not when
-@var{n} is greater than 1.
-
-@findex SUBREG_REG
-@findex SUBREG_BYTE
-The first operand of a @code{subreg} expression is customarily accessed
-with the @code{SUBREG_REG} macro and the second operand is customarily
-accessed with the @code{SUBREG_BYTE} macro.
-
-It has been several years since a platform in which
-@code{BYTES_BIG_ENDIAN} not equal to @code{WORDS_BIG_ENDIAN} has
-been tested. Anyone wishing to support such a platform in the future
-may be confronted with code rot.
-
-@findex scratch
-@cindex scratch operands
-@item (scratch:@var{m})
-This represents a scratch register that will be required for the
-execution of a single instruction and not used subsequently. It is
-converted into a @code{reg} by either the local register allocator or
-the reload pass.
-
-@code{scratch} is usually present inside a @code{clobber} operation
-(@pxref{Side Effects}).
-
-On some machines, the condition code register is given a register number
-and a @code{reg} is used.
-Other machines store condition codes in general
-registers; in such cases a pseudo register should be used.
-
-Some machines, such as the SPARC and RS/6000, have two sets of
-arithmetic instructions, one that sets and one that does not set the
-condition code. This is best handled by normally generating the
-instruction that does not set the condition code, and making a pattern
-that both performs the arithmetic and sets the condition code register.
-For examples, search for @samp{addcc} and @samp{andcc} in @file{sparc.md}.
-
-@findex pc
-@item (pc)
-@cindex program counter
-This represents the machine's program counter. It has no operands and
-may not have a machine mode. @code{(pc)} may be validly used only in
-certain specific contexts in jump instructions.
-
-@findex pc_rtx
-There is only one expression object of code @code{pc}; it is the value
-of the variable @code{pc_rtx}. Any attempt to create an expression of
-code @code{pc} will return @code{pc_rtx}.
-
-All instructions that do not jump alter the program counter implicitly
-by incrementing it, but there is no need to mention this in the RTL@.
-
-@findex mem
-@item (mem:@var{m} @var{addr} @var{alias})
-This RTX represents a reference to main memory at an address
-represented by the expression @var{addr}. @var{m} specifies how large
-a unit of memory is accessed. @var{alias} specifies an alias set for the
-reference. In general two items are in different alias sets if they cannot
-reference the same memory address.
-
-The construct @code{(mem:BLK (scratch))} is considered to alias all
-other memories. Thus it may be used as a memory barrier in epilogue
-stack deallocation patterns.
-
-@findex concat
-@item (concat@var{m} @var{rtx} @var{rtx})
-This RTX represents the concatenation of two other RTXs. This is used
-for complex values. It should only appear in the RTL attached to
-declarations and during RTL generation. It should not appear in the
-ordinary insn chain.
-
-@findex concatn
-@item (concatn@var{m} [@var{rtx} @dots{}])
-This RTX represents the concatenation of all the @var{rtx} to make a
-single value. Like @code{concat}, this should only appear in
-declarations, and not in the insn chain.
-@end table
-
-@node Arithmetic
-@section RTL Expressions for Arithmetic
-@cindex arithmetic, in RTL
-@cindex math, in RTL
-@cindex RTL expressions for arithmetic
-
-Unless otherwise specified, all the operands of arithmetic expressions
-must be valid for mode @var{m}. An operand is valid for mode @var{m}
-if it has mode @var{m}, or if it is a @code{const_int} or
-@code{const_double} and @var{m} is a mode of class @code{MODE_INT}.
-
-For commutative binary operations, constants should be placed in the
-second operand.
-
-@table @code
-@findex plus
-@findex ss_plus
-@findex us_plus
-@cindex RTL sum
-@cindex RTL addition
-@cindex RTL addition with signed saturation
-@cindex RTL addition with unsigned saturation
-@item (plus:@var{m} @var{x} @var{y})
-@itemx (ss_plus:@var{m} @var{x} @var{y})
-@itemx (us_plus:@var{m} @var{x} @var{y})
-
-These three expressions all represent the sum of the values
-represented by @var{x} and @var{y} carried out in machine mode
-@var{m}. They differ in their behavior on overflow of integer modes.
-@code{plus} wraps round modulo the width of @var{m}; @code{ss_plus}
-saturates at the maximum signed value representable in @var{m};
-@code{us_plus} saturates at the maximum unsigned value.
-
-@c ??? What happens on overflow of floating point modes?
-
-@findex lo_sum
-@item (lo_sum:@var{m} @var{x} @var{y})
-
-This expression represents the sum of @var{x} and the low-order bits
-of @var{y}. It is used with @code{high} (@pxref{Constants}) to
-represent the typical two-instruction sequence used in RISC machines to
-reference large immediate values and/or link-time constants such
-as global memory addresses. In the latter case, @var{m} is @code{Pmode}
-and @var{y} is usually a constant expression involving @code{symbol_ref}.
-
-The number of low order bits is machine-dependent but is
-normally the number of bits in mode @var{m} minus the number of
-bits set by @code{high}.
-
-@findex minus
-@findex ss_minus
-@findex us_minus
-@cindex RTL difference
-@cindex RTL subtraction
-@cindex RTL subtraction with signed saturation
-@cindex RTL subtraction with unsigned saturation
-@item (minus:@var{m} @var{x} @var{y})
-@itemx (ss_minus:@var{m} @var{x} @var{y})
-@itemx (us_minus:@var{m} @var{x} @var{y})
-
-These three expressions represent the result of subtracting @var{y}
-from @var{x}, carried out in mode @var{M}. Behavior on overflow is
-the same as for the three variants of @code{plus} (see above).
-
-@findex compare
-@cindex RTL comparison
-@item (compare:@var{m} @var{x} @var{y})
-Represents the result of subtracting @var{y} from @var{x} for purposes
-of comparison. The result is computed without overflow, as if with
-infinite precision.
-
-Of course, machines cannot really subtract with infinite precision.
-However, they can pretend to do so when only the sign of the result will
-be used, which is the case when the result is stored in the condition
-code. And that is the @emph{only} way this kind of expression may
-validly be used: as a value to be stored in the condition codes, in a
-register. @xref{Comparisons}.
-
-The mode @var{m} is not related to the modes of @var{x} and @var{y}, but
-instead is the mode of the condition code value. It is some mode in class
-@code{MODE_CC}, often @code{CCmode}. @xref{Condition Code}. If @var{m}
-is @code{CCmode}, the operation returns sufficient
-information (in an unspecified format) so that any comparison operator
-can be applied to the result of the @code{COMPARE} operation. For other
-modes in class @code{MODE_CC}, the operation only returns a subset of
-this information.
-
-Normally, @var{x} and @var{y} must have the same mode. Otherwise,
-@code{compare} is valid only if the mode of @var{x} is in class
-@code{MODE_INT} and @var{y} is a @code{const_int} or
-@code{const_double} with mode @code{VOIDmode}. The mode of @var{x}
-determines what mode the comparison is to be done in; thus it must not
-be @code{VOIDmode}.
-
-If one of the operands is a constant, it should be placed in the
-second operand and the comparison code adjusted as appropriate.
-
-A @code{compare} specifying two @code{VOIDmode} constants is not valid
-since there is no way to know in what mode the comparison is to be
-performed; the comparison must either be folded during the compilation
-or the first operand must be loaded into a register while its mode is
-still known.
-
-@findex neg
-@findex ss_neg
-@findex us_neg
-@cindex negation
-@cindex negation with signed saturation
-@cindex negation with unsigned saturation
-@item (neg:@var{m} @var{x})
-@itemx (ss_neg:@var{m} @var{x})
-@itemx (us_neg:@var{m} @var{x})
-These two expressions represent the negation (subtraction from zero) of
-the value represented by @var{x}, carried out in mode @var{m}. They
-differ in the behavior on overflow of integer modes. In the case of
-@code{neg}, the negation of the operand may be a number not representable
-in mode @var{m}, in which case it is truncated to @var{m}. @code{ss_neg}
-and @code{us_neg} ensure that an out-of-bounds result saturates to the
-maximum or minimum signed or unsigned value.
-
-@findex mult
-@findex ss_mult
-@findex us_mult
-@cindex multiplication
-@cindex product
-@cindex multiplication with signed saturation
-@cindex multiplication with unsigned saturation
-@item (mult:@var{m} @var{x} @var{y})
-@itemx (ss_mult:@var{m} @var{x} @var{y})
-@itemx (us_mult:@var{m} @var{x} @var{y})
-Represents the signed product of the values represented by @var{x} and
-@var{y} carried out in machine mode @var{m}.
-@code{ss_mult} and @code{us_mult} ensure that an out-of-bounds result
-saturates to the maximum or minimum signed or unsigned value.
-
-Some machines support a multiplication that generates a product wider
-than the operands. Write the pattern for this as
-
-@smallexample
-(mult:@var{m} (sign_extend:@var{m} @var{x}) (sign_extend:@var{m} @var{y}))
-@end smallexample
-
-where @var{m} is wider than the modes of @var{x} and @var{y}, which need
-not be the same.
-
-For unsigned widening multiplication, use the same idiom, but with
-@code{zero_extend} instead of @code{sign_extend}.
-
-@findex smul_highpart
-@findex umul_highpart
-@cindex high-part multiplication
-@cindex multiplication high part
-@item (smul_highpart:@var{m} @var{x} @var{y})
-@itemx (umul_highpart:@var{m} @var{x} @var{y})
-Represents the high-part multiplication of @var{x} and @var{y} carried
-out in machine mode @var{m}. @code{smul_highpart} returns the high part
-of a signed multiplication, @code{umul_highpart} returns the high part
-of an unsigned multiplication.
-
-@findex fma
-@cindex fused multiply-add
-@item (fma:@var{m} @var{x} @var{y} @var{z})
-Represents the @code{fma}, @code{fmaf}, and @code{fmal} builtin
-functions, which compute @samp{@var{x} * @var{y} + @var{z}}
-without doing an intermediate rounding step.
-
-@findex div
-@findex ss_div
-@cindex division
-@cindex signed division
-@cindex signed division with signed saturation
-@cindex quotient
-@item (div:@var{m} @var{x} @var{y})
-@itemx (ss_div:@var{m} @var{x} @var{y})
-Represents the quotient in signed division of @var{x} by @var{y},
-carried out in machine mode @var{m}. If @var{m} is a floating point
-mode, it represents the exact quotient; otherwise, the integerized
-quotient.
-@code{ss_div} ensures that an out-of-bounds result saturates to the maximum
-or minimum signed value.
-
-Some machines have division instructions in which the operands and
-quotient widths are not all the same; you should represent
-such instructions using @code{truncate} and @code{sign_extend} as in,
-
-@smallexample
-(truncate:@var{m1} (div:@var{m2} @var{x} (sign_extend:@var{m2} @var{y})))
-@end smallexample
-
-@findex udiv
-@cindex unsigned division
-@cindex unsigned division with unsigned saturation
-@cindex division
-@item (udiv:@var{m} @var{x} @var{y})
-@itemx (us_div:@var{m} @var{x} @var{y})
-Like @code{div} but represents unsigned division.
-@code{us_div} ensures that an out-of-bounds result saturates to the maximum
-or minimum unsigned value.
-
-@findex mod
-@findex umod
-@cindex remainder
-@cindex division
-@item (mod:@var{m} @var{x} @var{y})
-@itemx (umod:@var{m} @var{x} @var{y})
-Like @code{div} and @code{udiv} but represent the remainder instead of
-the quotient.
-
-@findex smin
-@findex smax
-@cindex signed minimum
-@cindex signed maximum
-@item (smin:@var{m} @var{x} @var{y})
-@itemx (smax:@var{m} @var{x} @var{y})
-Represents the smaller (for @code{smin}) or larger (for @code{smax}) of
-@var{x} and @var{y}, interpreted as signed values in mode @var{m}.
-When used with floating point, if both operands are zeros, or if either
-operand is @code{NaN}, then it is unspecified which of the two operands
-is returned as the result.
-
-@findex umin
-@findex umax
-@cindex unsigned minimum and maximum
-@item (umin:@var{m} @var{x} @var{y})
-@itemx (umax:@var{m} @var{x} @var{y})
-Like @code{smin} and @code{smax}, but the values are interpreted as unsigned
-integers.
-
-@findex not
-@cindex complement, bitwise
-@cindex bitwise complement
-@item (not:@var{m} @var{x})
-Represents the bitwise complement of the value represented by @var{x},
-carried out in mode @var{m}, which must be a fixed-point machine mode.
-
-@findex and
-@cindex logical-and, bitwise
-@cindex bitwise logical-and
-@item (and:@var{m} @var{x} @var{y})
-Represents the bitwise logical-and of the values represented by
-@var{x} and @var{y}, carried out in machine mode @var{m}, which must be
-a fixed-point machine mode.
-
-@findex ior
-@cindex inclusive-or, bitwise
-@cindex bitwise inclusive-or
-@item (ior:@var{m} @var{x} @var{y})
-Represents the bitwise inclusive-or of the values represented by @var{x}
-and @var{y}, carried out in machine mode @var{m}, which must be a
-fixed-point mode.
-
-@findex xor
-@cindex exclusive-or, bitwise
-@cindex bitwise exclusive-or
-@item (xor:@var{m} @var{x} @var{y})
-Represents the bitwise exclusive-or of the values represented by @var{x}
-and @var{y}, carried out in machine mode @var{m}, which must be a
-fixed-point mode.
-
-@findex ashift
-@findex ss_ashift
-@findex us_ashift
-@cindex left shift
-@cindex shift
-@cindex arithmetic shift
-@cindex arithmetic shift with signed saturation
-@cindex arithmetic shift with unsigned saturation
-@item (ashift:@var{m} @var{x} @var{c})
-@itemx (ss_ashift:@var{m} @var{x} @var{c})
-@itemx (us_ashift:@var{m} @var{x} @var{c})
-These three expressions represent the result of arithmetically shifting @var{x}
-left by @var{c} places. They differ in their behavior on overflow of integer
-modes. An @code{ashift} operation is a plain shift with no special behavior
-in case of a change in the sign bit; @code{ss_ashift} and @code{us_ashift}
-saturates to the minimum or maximum representable value if any of the bits
-shifted out differs from the final sign bit.
-
-@var{x} have mode @var{m}, a fixed-point machine mode. @var{c}
-be a fixed-point mode or be a constant with mode @code{VOIDmode}; which
-mode is determined by the mode called for in the machine description
-entry for the left-shift instruction. For example, on the VAX, the mode
-of @var{c} is @code{QImode} regardless of @var{m}.
-
-@findex lshiftrt
-@cindex right shift
-@findex ashiftrt
-@item (lshiftrt:@var{m} @var{x} @var{c})
-@itemx (ashiftrt:@var{m} @var{x} @var{c})
-Like @code{ashift} but for right shift. Unlike the case for left shift,
-these two operations are distinct.
-
-@findex rotate
-@cindex rotate
-@cindex left rotate
-@findex rotatert
-@cindex right rotate
-@item (rotate:@var{m} @var{x} @var{c})
-@itemx (rotatert:@var{m} @var{x} @var{c})
-Similar but represent left and right rotate. If @var{c} is a constant,
-use @code{rotate}.
-
-@findex abs
-@findex ss_abs
-@cindex absolute value
-@item (abs:@var{m} @var{x})
-@item (ss_abs:@var{m} @var{x})
-Represents the absolute value of @var{x}, computed in mode @var{m}.
-@code{ss_abs} ensures that an out-of-bounds result saturates to the
-maximum signed value.
-
-
-@findex sqrt
-@cindex square root
-@item (sqrt:@var{m} @var{x})
-Represents the square root of @var{x}, computed in mode @var{m}.
-Most often @var{m} will be a floating point mode.
-
-@findex ffs
-@item (ffs:@var{m} @var{x})
-Represents one plus the index of the least significant 1-bit in
-@var{x}, represented as an integer of mode @var{m}. (The value is
-zero if @var{x} is zero.) The mode of @var{x} must be @var{m}
-or @code{VOIDmode}.
-
-@findex clrsb
-@item (clrsb:@var{m} @var{x})
-Represents the number of redundant leading sign bits in @var{x},
-represented as an integer of mode @var{m}, starting at the most
-significant bit position. This is one less than the number of leading
-sign bits (either 0 or 1), with no special cases. The mode of @var{x}
-must be @var{m} or @code{VOIDmode}.
-
-@findex clz
-@item (clz:@var{m} @var{x})
-Represents the number of leading 0-bits in @var{x}, represented as an
-integer of mode @var{m}, starting at the most significant bit position.
-If @var{x} is zero, the value is determined by
-@code{CLZ_DEFINED_VALUE_AT_ZERO} (@pxref{Misc}). Note that this is one of
-the few expressions that is not invariant under widening. The mode of
-@var{x} must be @var{m} or @code{VOIDmode}.
-
-@findex ctz
-@item (ctz:@var{m} @var{x})
-Represents the number of trailing 0-bits in @var{x}, represented as an
-integer of mode @var{m}, starting at the least significant bit position.
-If @var{x} is zero, the value is determined by
-@code{CTZ_DEFINED_VALUE_AT_ZERO} (@pxref{Misc}). Except for this case,
-@code{ctz(x)} is equivalent to @code{ffs(@var{x}) - 1}. The mode of
-@var{x} must be @var{m} or @code{VOIDmode}.
-
-@findex popcount
-@item (popcount:@var{m} @var{x})
-Represents the number of 1-bits in @var{x}, represented as an integer of
-mode @var{m}. The mode of @var{x} must be @var{m} or @code{VOIDmode}.
-
-@findex parity
-@item (parity:@var{m} @var{x})
-Represents the number of 1-bits modulo 2 in @var{x}, represented as an
-integer of mode @var{m}. The mode of @var{x} must be @var{m} or
-@code{VOIDmode}.
-
-@findex bswap
-@item (bswap:@var{m} @var{x})
-Represents the value @var{x} with the order of bytes reversed, carried out
-in mode @var{m}, which must be a fixed-point machine mode.
-The mode of @var{x} must be @var{m} or @code{VOIDmode}.
-@end table
-
-@node Comparisons
-@section Comparison Operations
-@cindex RTL comparison operations
-
-Comparison operators test a relation on two operands and are considered
-to represent a machine-dependent nonzero value described by, but not
-necessarily equal to, @code{STORE_FLAG_VALUE} (@pxref{Misc})
-if the relation holds, or zero if it does not, for comparison operators
-whose results have a `MODE_INT' mode,
-@code{FLOAT_STORE_FLAG_VALUE} (@pxref{Misc}) if the relation holds, or
-zero if it does not, for comparison operators that return floating-point
-values, and a vector of either @code{VECTOR_STORE_FLAG_VALUE} (@pxref{Misc})
-if the relation holds, or of zeros if it does not, for comparison operators
-that return vector results.
-The mode of the comparison operation is independent of the mode
-of the data being compared. If the comparison operation is being tested
-(e.g., the first operand of an @code{if_then_else}), the mode must be
-@code{VOIDmode}.
-
-@cindex condition codes
-A comparison operation compares two data
-objects. The mode of the comparison is determined by the operands; they
-must both be valid for a common machine mode. A comparison with both
-operands constant would be invalid as the machine mode could not be
-deduced from it, but such a comparison should never exist in RTL due to
-constant folding.
-
-Usually only one style
-of comparisons is supported on a particular machine, but the combine
-pass will try to merge operations to produce code like
-@code{(eq @var{x} @var{y})},
-in case it exists in the context of the particular insn involved.
-
-Inequality comparisons come in two flavors, signed and unsigned. Thus,
-there are distinct expression codes @code{gt} and @code{gtu} for signed and
-unsigned greater-than. These can produce different results for the same
-pair of integer values: for example, 1 is signed greater-than @minus{}1 but not
-unsigned greater-than, because @minus{}1 when regarded as unsigned is actually
-@code{0xffffffff} which is greater than 1.
-
-The signed comparisons are also used for floating point values. Floating
-point comparisons are distinguished by the machine modes of the operands.
-
-@table @code
-@findex eq
-@cindex equal
-@item (eq:@var{m} @var{x} @var{y})
-@code{STORE_FLAG_VALUE} if the values represented by @var{x} and @var{y}
-are equal, otherwise 0.
-
-@findex ne
-@cindex not equal
-@item (ne:@var{m} @var{x} @var{y})
-@code{STORE_FLAG_VALUE} if the values represented by @var{x} and @var{y}
-are not equal, otherwise 0.
-
-@findex gt
-@cindex greater than
-@item (gt:@var{m} @var{x} @var{y})
-@code{STORE_FLAG_VALUE} if the @var{x} is greater than @var{y}. If they
-are fixed-point, the comparison is done in a signed sense.
-
-@findex gtu
-@cindex greater than
-@cindex unsigned greater than
-@item (gtu:@var{m} @var{x} @var{y})
-Like @code{gt} but does unsigned comparison, on fixed-point numbers only.
-
-@findex lt
-@cindex less than
-@findex ltu
-@cindex unsigned less than
-@item (lt:@var{m} @var{x} @var{y})
-@itemx (ltu:@var{m} @var{x} @var{y})
-Like @code{gt} and @code{gtu} but test for ``less than''.
-
-@findex ge
-@cindex greater than
-@findex geu
-@cindex unsigned greater than
-@item (ge:@var{m} @var{x} @var{y})
-@itemx (geu:@var{m} @var{x} @var{y})
-Like @code{gt} and @code{gtu} but test for ``greater than or equal''.
-
-@findex le
-@cindex less than or equal
-@findex leu
-@cindex unsigned less than
-@item (le:@var{m} @var{x} @var{y})
-@itemx (leu:@var{m} @var{x} @var{y})
-Like @code{gt} and @code{gtu} but test for ``less than or equal''.
-
-@findex if_then_else
-@item (if_then_else @var{cond} @var{then} @var{else})
-This is not a comparison operation but is listed here because it is
-always used in conjunction with a comparison operation. To be
-precise, @var{cond} is a comparison expression. This expression
-represents a choice, according to @var{cond}, between the value
-represented by @var{then} and the one represented by @var{else}.
-
-On most machines, @code{if_then_else} expressions are valid only
-to express conditional jumps.
-
-@findex cond
-@item (cond [@var{test1} @var{value1} @var{test2} @var{value2} @dots{}] @var{default})
-Similar to @code{if_then_else}, but more general. Each of @var{test1},
-@var{test2}, @dots{} is performed in turn. The result of this expression is
-the @var{value} corresponding to the first nonzero test, or @var{default} if
-none of the tests are nonzero expressions.
-
-This is currently not valid for instruction patterns and is supported only
-for insn attributes. @xref{Insn Attributes}.
-@end table
-
-@node Bit-Fields
-@section Bit-Fields
-@cindex bit-fields
-
-Special expression codes exist to represent bit-field instructions.
-
-@table @code
-@findex sign_extract
-@cindex @code{BITS_BIG_ENDIAN}, effect on @code{sign_extract}
-@item (sign_extract:@var{m} @var{loc} @var{size} @var{pos})
-This represents a reference to a sign-extended bit-field contained or
-starting in @var{loc} (a memory or register reference). The bit-field
-is @var{size} bits wide and starts at bit @var{pos}. The compilation
-option @code{BITS_BIG_ENDIAN} says which end of the memory unit
-@var{pos} counts from.
-
-If @var{loc} is in memory, its mode must be a single-byte integer mode.
-If @var{loc} is in a register, the mode to use is specified by the
-operand of the @code{insv} or @code{extv} pattern
-(@pxref{Standard Names}) and is usually a full-word integer mode,
-which is the default if none is specified.
-
-The mode of @var{pos} is machine-specific and is also specified
-in the @code{insv} or @code{extv} pattern.
-
-The mode @var{m} is the same as the mode that would be used for
-@var{loc} if it were a register.
-
-A @code{sign_extract} cannot appear as an lvalue, or part thereof,
-in RTL.
-
-@findex zero_extract
-@item (zero_extract:@var{m} @var{loc} @var{size} @var{pos})
-Like @code{sign_extract} but refers to an unsigned or zero-extended
-bit-field. The same sequence of bits are extracted, but they
-are filled to an entire word with zeros instead of by sign-extension.
-
-Unlike @code{sign_extract}, this type of expressions can be lvalues
-in RTL; they may appear on the left side of an assignment, indicating
-insertion of a value into the specified bit-field.
-@end table
-
-@node Vector Operations
-@section Vector Operations
-@cindex vector operations
-
-All normal RTL expressions can be used with vector modes; they are
-interpreted as operating on each part of the vector independently.
-Additionally, there are a few new expressions to describe specific vector
-operations.
-
-@table @code
-@findex vec_merge
-@item (vec_merge:@var{m} @var{vec1} @var{vec2} @var{items})
-This describes a merge operation between two vectors. The result is a vector
-of mode @var{m}; its elements are selected from either @var{vec1} or
-@var{vec2}. Which elements are selected is described by @var{items}, which
-is a bit mask represented by a @code{const_int}; a zero bit indicates the
-corresponding element in the result vector is taken from @var{vec2} while
-a set bit indicates it is taken from @var{vec1}.
-
-@findex vec_select
-@item (vec_select:@var{m} @var{vec1} @var{selection})
-This describes an operation that selects parts of a vector. @var{vec1} is
-the source vector, and @var{selection} is a @code{parallel} that contains a
-@code{const_int} (or another expression, if the selection can be made at
-runtime) for each of the subparts of the result vector, giving the number of
-the source subpart that should be stored into it. The result mode @var{m} is
-either the submode for a single element of @var{vec1} (if only one subpart is
-selected), or another vector mode with that element submode (if multiple
-subparts are selected).
-
-@findex vec_concat
-@item (vec_concat:@var{m} @var{x1} @var{x2})
-Describes a vector concat operation. The result is a concatenation of the
-vectors or scalars @var{x1} and @var{x2}; its length is the sum of the
-lengths of the two inputs.
-
-@findex vec_duplicate
-@item (vec_duplicate:@var{m} @var{x})
-This operation converts a scalar into a vector or a small vector into a
-larger one by duplicating the input values. The output vector mode must have
-the same submodes as the input vector mode or the scalar modes, and the
-number of output parts must be an integer multiple of the number of input
-parts.
-
-@findex vec_series
-@item (vec_series:@var{m} @var{base} @var{step})
-This operation creates a vector in which element @var{i} is equal to
-@samp{@var{base} + @var{i}*@var{step}}. @var{m} must be a vector integer mode.
-@end table
-
-@node Conversions
-@section Conversions
-@cindex conversions
-@cindex machine mode conversions
-
-All conversions between machine modes must be represented by
-explicit conversion operations. For example, an expression
-which is the sum of a byte and a full word cannot be written as
-@code{(plus:SI (reg:QI 34) (reg:SI 80))} because the @code{plus}
-operation requires two operands of the same machine mode.
-Therefore, the byte-sized operand is enclosed in a conversion
-operation, as in
-
-@smallexample
-(plus:SI (sign_extend:SI (reg:QI 34)) (reg:SI 80))
-@end smallexample
-
-The conversion operation is not a mere placeholder, because there
-may be more than one way of converting from a given starting mode
-to the desired final mode. The conversion operation code says how
-to do it.
-
-For all conversion operations, @var{x} must not be @code{VOIDmode}
-because the mode in which to do the conversion would not be known.
-The conversion must either be done at compile-time or @var{x}
-must be placed into a register.
-
-@table @code
-@findex sign_extend
-@item (sign_extend:@var{m} @var{x})
-Represents the result of sign-extending the value @var{x}
-to machine mode @var{m}. @var{m} must be a fixed-point mode
-and @var{x} a fixed-point value of a mode narrower than @var{m}.
-
-@findex zero_extend
-@item (zero_extend:@var{m} @var{x})
-Represents the result of zero-extending the value @var{x}
-to machine mode @var{m}. @var{m} must be a fixed-point mode
-and @var{x} a fixed-point value of a mode narrower than @var{m}.
-
-@findex float_extend
-@item (float_extend:@var{m} @var{x})
-Represents the result of extending the value @var{x}
-to machine mode @var{m}. @var{m} must be a floating point mode
-and @var{x} a floating point value of a mode narrower than @var{m}.
-
-@findex truncate
-@item (truncate:@var{m} @var{x})
-Represents the result of truncating the value @var{x}
-to machine mode @var{m}. @var{m} must be a fixed-point mode
-and @var{x} a fixed-point value of a mode wider than @var{m}.
-
-@findex ss_truncate
-@item (ss_truncate:@var{m} @var{x})
-Represents the result of truncating the value @var{x}
-to machine mode @var{m}, using signed saturation in the case of
-overflow. Both @var{m} and the mode of @var{x} must be fixed-point
-modes.
-
-@findex us_truncate
-@item (us_truncate:@var{m} @var{x})
-Represents the result of truncating the value @var{x}
-to machine mode @var{m}, using unsigned saturation in the case of
-overflow. Both @var{m} and the mode of @var{x} must be fixed-point
-modes.
-
-@findex float_truncate
-@item (float_truncate:@var{m} @var{x})
-Represents the result of truncating the value @var{x}
-to machine mode @var{m}. @var{m} must be a floating point mode
-and @var{x} a floating point value of a mode wider than @var{m}.
-
-@findex float
-@item (float:@var{m} @var{x})
-Represents the result of converting fixed point value @var{x},
-regarded as signed, to floating point mode @var{m}.
-
-@findex unsigned_float
-@item (unsigned_float:@var{m} @var{x})
-Represents the result of converting fixed point value @var{x},
-regarded as unsigned, to floating point mode @var{m}.
-
-@findex fix
-@item (fix:@var{m} @var{x})
-When @var{m} is a floating-point mode, represents the result of
-converting floating point value @var{x} (valid for mode @var{m}) to an
-integer, still represented in floating point mode @var{m}, by rounding
-towards zero.
-
-When @var{m} is a fixed-point mode, represents the result of
-converting floating point value @var{x} to mode @var{m}, regarded as
-signed. How rounding is done is not specified, so this operation may
-be used validly in compiling C code only for integer-valued operands.
-
-@findex unsigned_fix
-@item (unsigned_fix:@var{m} @var{x})
-Represents the result of converting floating point value @var{x} to
-fixed point mode @var{m}, regarded as unsigned. How rounding is done
-is not specified.
-
-@findex fract_convert
-@item (fract_convert:@var{m} @var{x})
-Represents the result of converting fixed-point value @var{x} to
-fixed-point mode @var{m}, signed integer value @var{x} to
-fixed-point mode @var{m}, floating-point value @var{x} to
-fixed-point mode @var{m}, fixed-point value @var{x} to integer mode @var{m}
-regarded as signed, or fixed-point value @var{x} to floating-point mode @var{m}.
-When overflows or underflows happen, the results are undefined.
-
-@findex sat_fract
-@item (sat_fract:@var{m} @var{x})
-Represents the result of converting fixed-point value @var{x} to
-fixed-point mode @var{m}, signed integer value @var{x} to
-fixed-point mode @var{m}, or floating-point value @var{x} to
-fixed-point mode @var{m}.
-When overflows or underflows happen, the results are saturated to the
-maximum or the minimum.
-
-@findex unsigned_fract_convert
-@item (unsigned_fract_convert:@var{m} @var{x})
-Represents the result of converting fixed-point value @var{x} to
-integer mode @var{m} regarded as unsigned, or unsigned integer value @var{x} to
-fixed-point mode @var{m}.
-When overflows or underflows happen, the results are undefined.
-
-@findex unsigned_sat_fract
-@item (unsigned_sat_fract:@var{m} @var{x})
-Represents the result of converting unsigned integer value @var{x} to
-fixed-point mode @var{m}.
-When overflows or underflows happen, the results are saturated to the
-maximum or the minimum.
-@end table
-
-@node RTL Declarations
-@section Declarations
-@cindex RTL declarations
-@cindex declarations, RTL
-
-Declaration expression codes do not represent arithmetic operations
-but rather state assertions about their operands.
-
-@table @code
-@findex strict_low_part
-@cindex @code{subreg}, in @code{strict_low_part}
-@item (strict_low_part (subreg:@var{m} (reg:@var{n} @var{r}) 0))
-This expression code is used in only one context: as the destination operand of a
-@code{set} expression. In addition, the operand of this expression
-must be a non-paradoxical @code{subreg} expression.
-
-The presence of @code{strict_low_part} says that the part of the
-register which is meaningful in mode @var{n}, but is not part of
-mode @var{m}, is not to be altered. Normally, an assignment to such
-a subreg is allowed to have undefined effects on the rest of the
-register when @var{m} is smaller than @samp{REGMODE_NATURAL_SIZE (@var{n})}.
-@end table
-
-@node Side Effects
-@section Side Effect Expressions
-@cindex RTL side effect expressions
-
-The expression codes described so far represent values, not actions.
-But machine instructions never produce values; they are meaningful
-only for their side effects on the state of the machine. Special
-expression codes are used to represent side effects.
-
-The body of an instruction is always one of these side effect codes;
-the codes described above, which represent values, appear only as
-the operands of these.
-
-@table @code
-@findex set
-@item (set @var{lval} @var{x})
-Represents the action of storing the value of @var{x} into the place
-represented by @var{lval}. @var{lval} must be an expression
-representing a place that can be stored in: @code{reg} (or @code{subreg},
-@code{strict_low_part} or @code{zero_extract}), @code{mem}, @code{pc},
-or @code{parallel}.
-
-If @var{lval} is a @code{reg}, @code{subreg} or @code{mem}, it has a
-machine mode; then @var{x} must be valid for that mode.
-
-If @var{lval} is a @code{reg} whose machine mode is less than the full
-width of the register, then it means that the part of the register
-specified by the machine mode is given the specified value and the
-rest of the register receives an undefined value. Likewise, if
-@var{lval} is a @code{subreg} whose machine mode is narrower than
-the mode of the register, the rest of the register can be changed in
-an undefined way.
-
-If @var{lval} is a @code{strict_low_part} of a subreg, then the part
-of the register specified by the machine mode of the @code{subreg} is
-given the value @var{x} and the rest of the register is not changed.
-
-If @var{lval} is a @code{zero_extract}, then the referenced part of
-the bit-field (a memory or register reference) specified by the
-@code{zero_extract} is given the value @var{x} and the rest of the
-bit-field is not changed. Note that @code{sign_extract} cannot
-appear in @var{lval}.
-
-If @var{lval} is a @code{parallel}, it is used to represent the case of
-a function returning a structure in multiple registers. Each element
-of the @code{parallel} is an @code{expr_list} whose first operand is a
-@code{reg} and whose second operand is a @code{const_int} representing the
-offset (in bytes) into the structure at which the data in that register
-corresponds. The first element may be null to indicate that the structure
-is also passed partly in memory.
-
-@cindex jump instructions and @code{set}
-@cindex @code{if_then_else} usage
-If @var{lval} is @code{(pc)}, we have a jump instruction, and the
-possibilities for @var{x} are very limited. It may be a
-@code{label_ref} expression (unconditional jump). It may be an
-@code{if_then_else} (conditional jump), in which case either the
-second or the third operand must be @code{(pc)} (for the case which
-does not jump) and the other of the two must be a @code{label_ref}
-(for the case which does jump). @var{x} may also be a @code{mem} or
-@code{(plus:SI (pc) @var{y})}, where @var{y} may be a @code{reg} or a
-@code{mem}; these unusual patterns are used to represent jumps through
-branch tables.
-
-If @var{lval} is not @code{(pc)}, the mode of
-@var{lval} must not be @code{VOIDmode} and the mode of @var{x} must be
-valid for the mode of @var{lval}.
-
-@findex SET_DEST
-@findex SET_SRC
-@var{lval} is customarily accessed with the @code{SET_DEST} macro and
-@var{x} with the @code{SET_SRC} macro.
-
-@findex return
-@item (return)
-As the sole expression in a pattern, represents a return from the
-current function, on machines where this can be done with one
-instruction, such as VAXen. On machines where a multi-instruction
-``epilogue'' must be executed in order to return from the function,
-returning is done by jumping to a label which precedes the epilogue, and
-the @code{return} expression code is never used.
-
-Inside an @code{if_then_else} expression, represents the value to be
-placed in @code{pc} to return to the caller.
-
-Note that an insn pattern of @code{(return)} is logically equivalent to
-@code{(set (pc) (return))}, but the latter form is never used.
-
-@findex simple_return
-@item (simple_return)
-Like @code{(return)}, but truly represents only a function return, while
-@code{(return)} may represent an insn that also performs other functions
-of the function epilogue. Like @code{(return)}, this may also occur in
-conditional jumps.
-
-@findex call
-@item (call @var{function} @var{nargs})
-Represents a function call. @var{function} is a @code{mem} expression
-whose address is the address of the function to be called.
-@var{nargs} is an expression which can be used for two purposes: on
-some machines it represents the number of bytes of stack argument; on
-others, it represents the number of argument registers.
-
-Each machine has a standard machine mode which @var{function} must
-have. The machine description defines macro @code{FUNCTION_MODE} to
-expand into the requisite mode name. The purpose of this mode is to
-specify what kind of addressing is allowed, on machines where the
-allowed kinds of addressing depend on the machine mode being
-addressed.
-
-@findex clobber
-@item (clobber @var{x})
-Represents the storing or possible storing of an unpredictable,
-undescribed value into @var{x}, which must be a @code{reg},
-@code{scratch}, @code{parallel} or @code{mem} expression.
-
-One place this is used is in string instructions that store standard
-values into particular hard registers. It may not be worth the
-trouble to describe the values that are stored, but it is essential to
-inform the compiler that the registers will be altered, lest it
-attempt to keep data in them across the string instruction.
-
-If @var{x} is @code{(mem:BLK (const_int 0))} or
-@code{(mem:BLK (scratch))}, it means that all memory
-locations must be presumed clobbered. If @var{x} is a @code{parallel},
-it has the same meaning as a @code{parallel} in a @code{set} expression.
-
-Note that the machine description classifies certain hard registers as
-``call-clobbered''. All function call instructions are assumed by
-default to clobber these registers, so there is no need to use
-@code{clobber} expressions to indicate this fact. Also, each function
-call is assumed to have the potential to alter any memory location,
-unless the function is declared @code{const}.
-
-If the last group of expressions in a @code{parallel} are each a
-@code{clobber} expression whose arguments are @code{reg} or
-@code{match_scratch} (@pxref{RTL Template}) expressions, the combiner
-phase can add the appropriate @code{clobber} expressions to an insn it
-has constructed when doing so will cause a pattern to be matched.
-
-This feature can be used, for example, on a machine that whose multiply
-and add instructions don't use an MQ register but which has an
-add-accumulate instruction that does clobber the MQ register. Similarly,
-a combined instruction might require a temporary register while the
-constituent instructions might not.
-
-When a @code{clobber} expression for a register appears inside a
-@code{parallel} with other side effects, the register allocator
-guarantees that the register is unoccupied both before and after that
-insn if it is a hard register clobber. For pseudo-register clobber,
-the register allocator and the reload pass do not assign the same hard
-register to the clobber and the input operands if there is an insn
-alternative containing the @samp{&} constraint (@pxref{Modifiers}) for
-the clobber and the hard register is in register classes of the
-clobber in the alternative. You can clobber either a specific hard
-register, a pseudo register, or a @code{scratch} expression; in the
-latter two cases, GCC will allocate a hard register that is available
-there for use as a temporary.
-
-For instructions that require a temporary register, you should use
-@code{scratch} instead of a pseudo-register because this will allow the
-combiner phase to add the @code{clobber} when required. You do this by
-coding (@code{clobber} (@code{match_scratch} @dots{})). If you do
-clobber a pseudo register, use one which appears nowhere else---generate
-a new one each time. Otherwise, you may confuse CSE@.
-
-There is one other known use for clobbering a pseudo register in a
-@code{parallel}: when one of the input operands of the insn is also
-clobbered by the insn. In this case, using the same pseudo register in
-the clobber and elsewhere in the insn produces the expected results.
-
-@findex use
-@item (use @var{x})
-Represents the use of the value of @var{x}. It indicates that the
-value in @var{x} at this point in the program is needed, even though
-it may not be apparent why this is so. Therefore, the compiler will
-not attempt to delete previous instructions whose only effect is to
-store a value in @var{x}. @var{x} must be a @code{reg} expression.
-
-In some situations, it may be tempting to add a @code{use} of a
-register in a @code{parallel} to describe a situation where the value
-of a special register will modify the behavior of the instruction.
-A hypothetical example might be a pattern for an addition that can
-either wrap around or use saturating addition depending on the value
-of a special control register:
-
-@smallexample
-(parallel [(set (reg:SI 2) (unspec:SI [(reg:SI 3)
- (reg:SI 4)] 0))
- (use (reg:SI 1))])
-@end smallexample
-
-@noindent
-
-This will not work, several of the optimizers only look at expressions
-locally; it is very likely that if you have multiple insns with
-identical inputs to the @code{unspec}, they will be optimized away even
-if register 1 changes in between.
-
-This means that @code{use} can @emph{only} be used to describe
-that the register is live. You should think twice before adding
-@code{use} statements, more often you will want to use @code{unspec}
-instead. The @code{use} RTX is most commonly useful to describe that
-a fixed register is implicitly used in an insn. It is also safe to use
-in patterns where the compiler knows for other reasons that the result
-of the whole pattern is variable, such as @samp{cpymem@var{m}} or
-@samp{call} patterns.
-
-During the reload phase, an insn that has a @code{use} as pattern
-can carry a reg_equal note. These @code{use} insns will be deleted
-before the reload phase exits.
-
-During the delayed branch scheduling phase, @var{x} may be an insn.
-This indicates that @var{x} previously was located at this place in the
-code and its data dependencies need to be taken into account. These
-@code{use} insns will be deleted before the delayed branch scheduling
-phase exits.
-
-@findex parallel
-@item (parallel [@var{x0} @var{x1} @dots{}])
-Represents several side effects performed in parallel. The square
-brackets stand for a vector; the operand of @code{parallel} is a
-vector of expressions. @var{x0}, @var{x1} and so on are individual
-side effect expressions---expressions of code @code{set}, @code{call},
-@code{return}, @code{simple_return}, @code{clobber} or @code{use}.
-
-``In parallel'' means that first all the values used in the individual
-side-effects are computed, and second all the actual side-effects are
-performed. For example,
-
-@smallexample
-(parallel [(set (reg:SI 1) (mem:SI (reg:SI 1)))
- (set (mem:SI (reg:SI 1)) (reg:SI 1))])
-@end smallexample
-
-@noindent
-says unambiguously that the values of hard register 1 and the memory
-location addressed by it are interchanged. In both places where
-@code{(reg:SI 1)} appears as a memory address it refers to the value
-in register 1 @emph{before} the execution of the insn.
-
-It follows that it is @emph{incorrect} to use @code{parallel} and
-expect the result of one @code{set} to be available for the next one.
-For example, people sometimes attempt to represent a jump-if-zero
-instruction this way:
-
-@smallexample
-(parallel [(set (reg:CC CC_REG) (reg:SI 34))
- (set (pc) (if_then_else
- (eq (reg:CC CC_REG) (const_int 0))
- (label_ref @dots{})
- (pc)))])
-@end smallexample
-
-@noindent
-But this is incorrect, because it says that the jump condition depends
-on the condition code value @emph{before} this instruction, not on the
-new value that is set by this instruction.
-
-@cindex peephole optimization, RTL representation
-Peephole optimization, which takes place together with final assembly
-code output, can produce insns whose patterns consist of a @code{parallel}
-whose elements are the operands needed to output the resulting
-assembler code---often @code{reg}, @code{mem} or constant expressions.
-This would not be well-formed RTL at any other stage in compilation,
-but it is OK then because no further optimization remains to be done.
-
-@findex cond_exec
-@item (cond_exec [@var{cond} @var{expr}])
-Represents a conditionally executed expression. The @var{expr} is
-executed only if the @var{cond} is nonzero. The @var{cond} expression
-must not have side-effects, but the @var{expr} may very well have
-side-effects.
-
-@findex sequence
-@item (sequence [@var{insns} @dots{}])
-Represents a sequence of insns. If a @code{sequence} appears in the
-chain of insns, then each of the @var{insns} that appears in the sequence
-must be suitable for appearing in the chain of insns, i.e.@: must satisfy
-the @code{INSN_P} predicate.
-
-After delay-slot scheduling is completed, an insn and all the insns that
-reside in its delay slots are grouped together into a @code{sequence}.
-The insn requiring the delay slot is the first insn in the vector;
-subsequent insns are to be placed in the delay slot.
-
-@code{INSN_ANNULLED_BRANCH_P} is set on an insn in a delay slot to
-indicate that a branch insn should be used that will conditionally annul
-the effect of the insns in the delay slots. In such a case,
-@code{INSN_FROM_TARGET_P} indicates that the insn is from the target of
-the branch and should be executed only if the branch is taken; otherwise
-the insn should be executed only if the branch is not taken.
-@xref{Delay Slots}.
-
-Some back ends also use @code{sequence} objects for purposes other than
-delay-slot groups. This is not supported in the common parts of the
-compiler, which treat such sequences as delay-slot groups.
-
-DWARF2 Call Frame Address (CFA) adjustments are sometimes also expressed
-using @code{sequence} objects as the value of a @code{RTX_FRAME_RELATED_P}
-note. This only happens if the CFA adjustments cannot be easily derived
-from the pattern of the instruction to which the note is attached. In
-such cases, the value of the note is used instead of best-guesing the
-semantics of the instruction. The back end can attach notes containing
-a @code{sequence} of @code{set} patterns that express the effect of the
-parent instruction.
-@end table
-
-These expression codes appear in place of a side effect, as the body of
-an insn, though strictly speaking they do not always describe side
-effects as such:
-
-@table @code
-@findex asm_input
-@item (asm_input @var{s})
-Represents literal assembler code as described by the string @var{s}.
-
-@findex unspec
-@findex unspec_volatile
-@item (unspec [@var{operands} @dots{}] @var{index})
-@itemx (unspec_volatile [@var{operands} @dots{}] @var{index})
-Represents a machine-specific operation on @var{operands}. @var{index}
-selects between multiple machine-specific operations.
-@code{unspec_volatile} is used for volatile operations and operations
-that may trap; @code{unspec} is used for other operations.
-
-These codes may appear inside a @code{pattern} of an
-insn, inside a @code{parallel}, or inside an expression.
-
-@findex addr_vec
-@item (addr_vec:@var{m} [@var{lr0} @var{lr1} @dots{}])
-Represents a table of jump addresses. The vector elements @var{lr0},
-etc., are @code{label_ref} expressions. The mode @var{m} specifies
-how much space is given to each address; normally @var{m} would be
-@code{Pmode}.
-
-@findex addr_diff_vec
-@item (addr_diff_vec:@var{m} @var{base} [@var{lr0} @var{lr1} @dots{}] @var{min} @var{max} @var{flags})
-Represents a table of jump addresses expressed as offsets from
-@var{base}. The vector elements @var{lr0}, etc., are @code{label_ref}
-expressions and so is @var{base}. The mode @var{m} specifies how much
-space is given to each address-difference. @var{min} and @var{max}
-are set up by branch shortening and hold a label with a minimum and a
-maximum address, respectively. @var{flags} indicates the relative
-position of @var{base}, @var{min} and @var{max} to the containing insn
-and of @var{min} and @var{max} to @var{base}. See rtl.def for details.
-
-@findex prefetch
-@item (prefetch:@var{m} @var{addr} @var{rw} @var{locality})
-Represents prefetch of memory at address @var{addr}.
-Operand @var{rw} is 1 if the prefetch is for data to be written, 0 otherwise;
-targets that do not support write prefetches should treat this as a normal
-prefetch.
-Operand @var{locality} specifies the amount of temporal locality; 0 if there
-is none or 1, 2, or 3 for increasing levels of temporal locality;
-targets that do not support locality hints should ignore this.
-
-This insn is used to minimize cache-miss latency by moving data into a
-cache before it is accessed. It should use only non-faulting data prefetch
-instructions.
-@end table
-
-@node Incdec
-@section Embedded Side-Effects on Addresses
-@cindex RTL preincrement
-@cindex RTL postincrement
-@cindex RTL predecrement
-@cindex RTL postdecrement
-
-Six special side-effect expression codes appear as memory addresses.
-
-@table @code
-@findex pre_dec
-@item (pre_dec:@var{m} @var{x})
-Represents the side effect of decrementing @var{x} by a standard
-amount and represents also the value that @var{x} has after being
-decremented. @var{x} must be a @code{reg} or @code{mem}, but most
-machines allow only a @code{reg}. @var{m} must be the machine mode
-for pointers on the machine in use. The amount @var{x} is decremented
-by is the length in bytes of the machine mode of the containing memory
-reference of which this expression serves as the address. Here is an
-example of its use:
-
-@smallexample
-(mem:DF (pre_dec:SI (reg:SI 39)))
-@end smallexample
-
-@noindent
-This says to decrement pseudo register 39 by the length of a @code{DFmode}
-value and use the result to address a @code{DFmode} value.
-
-@findex pre_inc
-@item (pre_inc:@var{m} @var{x})
-Similar, but specifies incrementing @var{x} instead of decrementing it.
-
-@findex post_dec
-@item (post_dec:@var{m} @var{x})
-Represents the same side effect as @code{pre_dec} but a different
-value. The value represented here is the value @var{x} has @i{before}
-being decremented.
-
-@findex post_inc
-@item (post_inc:@var{m} @var{x})
-Similar, but specifies incrementing @var{x} instead of decrementing it.
-
-@findex post_modify
-@item (post_modify:@var{m} @var{x} @var{y})
-
-Represents the side effect of setting @var{x} to @var{y} and
-represents @var{x} before @var{x} is modified. @var{x} must be a
-@code{reg} or @code{mem}, but most machines allow only a @code{reg}.
-@var{m} must be the machine mode for pointers on the machine in use.
-
-The expression @var{y} must be one of three forms:
-@code{(plus:@var{m} @var{x} @var{z})},
-@code{(minus:@var{m} @var{x} @var{z})}, or
-@code{(plus:@var{m} @var{x} @var{i})},
-where @var{z} is an index register and @var{i} is a constant.
-
-Here is an example of its use:
-
-@smallexample
-(mem:SF (post_modify:SI (reg:SI 42) (plus (reg:SI 42)
- (reg:SI 48))))
-@end smallexample
-
-This says to modify pseudo register 42 by adding the contents of pseudo
-register 48 to it, after the use of what ever 42 points to.
-
-@findex pre_modify
-@item (pre_modify:@var{m} @var{x} @var{expr})
-Similar except side effects happen before the use.
-@end table
-
-These embedded side effect expressions must be used with care. Instruction
-patterns may not use them. Until the @samp{flow} pass of the compiler,
-they may occur only to represent pushes onto the stack. The @samp{flow}
-pass finds cases where registers are incremented or decremented in one
-instruction and used as an address shortly before or after; these cases are
-then transformed to use pre- or post-increment or -decrement.
-
-If a register used as the operand of these expressions is used in
-another address in an insn, the original value of the register is used.
-Uses of the register outside of an address are not permitted within the
-same insn as a use in an embedded side effect expression because such
-insns behave differently on different machines and hence must be treated
-as ambiguous and disallowed.
-
-An instruction that can be represented with an embedded side effect
-could also be represented using @code{parallel} containing an additional
-@code{set} to describe how the address register is altered. This is not
-done because machines that allow these operations at all typically
-allow them wherever a memory address is called for. Describing them as
-additional parallel stores would require doubling the number of entries
-in the machine description.
-
-@node Assembler
-@section Assembler Instructions as Expressions
-@cindex assembler instructions in RTL
-
-@cindex @code{asm_operands}, usage
-The RTX code @code{asm_operands} represents a value produced by a
-user-specified assembler instruction. It is used to represent
-an @code{asm} statement with arguments. An @code{asm} statement with
-a single output operand, like this:
-
-@smallexample
-asm ("foo %1,%2,%0" : "=a" (outputvar) : "g" (x + y), "di" (*z));
-@end smallexample
-
-@noindent
-is represented using a single @code{asm_operands} RTX which represents
-the value that is stored in @code{outputvar}:
-
-@smallexample
-(set @var{rtx-for-outputvar}
- (asm_operands "foo %1,%2,%0" "a" 0
- [@var{rtx-for-addition-result} @var{rtx-for-*z}]
- [(asm_input:@var{m1} "g")
- (asm_input:@var{m2} "di")]))
-@end smallexample
-
-@noindent
-Here the operands of the @code{asm_operands} RTX are the assembler
-template string, the output-operand's constraint, the index-number of the
-output operand among the output operands specified, a vector of input
-operand RTX's, and a vector of input-operand modes and constraints. The
-mode @var{m1} is the mode of the sum @code{x+y}; @var{m2} is that of
-@code{*z}.
-
-When an @code{asm} statement has multiple output values, its insn has
-several such @code{set} RTX's inside of a @code{parallel}. Each @code{set}
-contains an @code{asm_operands}; all of these share the same assembler
-template and vectors, but each contains the constraint for the respective
-output operand. They are also distinguished by the output-operand index
-number, which is 0, 1, @dots{} for successive output operands.
-
-@node Debug Information
-@section Variable Location Debug Information in RTL
-@cindex Variable Location Debug Information in RTL
-
-Variable tracking relies on @code{MEM_EXPR} and @code{REG_EXPR}
-annotations to determine what user variables memory and register
-references refer to.
-
-Variable tracking at assignments uses these notes only when they refer
-to variables that live at fixed locations (e.g., addressable
-variables, global non-automatic variables). For variables whose
-location may vary, it relies on the following types of notes.
-
-@table @code
-@findex var_location
-@item (var_location:@var{mode} @var{var} @var{exp} @var{stat})
-Binds variable @code{var}, a tree, to value @var{exp}, an RTL
-expression. It appears only in @code{NOTE_INSN_VAR_LOCATION} and
-@code{DEBUG_INSN}s, with slightly different meanings. @var{mode}, if
-present, represents the mode of @var{exp}, which is useful if it is a
-modeless expression. @var{stat} is only meaningful in notes,
-indicating whether the variable is known to be initialized or
-uninitialized.
-
-@findex debug_expr
-@item (debug_expr:@var{mode} @var{decl})
-Stands for the value bound to the @code{DEBUG_EXPR_DECL} @var{decl},
-that points back to it, within value expressions in
-@code{VAR_LOCATION} nodes.
-
-@findex debug_implicit_ptr
-@item (debug_implicit_ptr:@var{mode} @var{decl})
-Stands for the location of a @var{decl} that is no longer addressable.
-
-@findex entry_value
-@item (entry_value:@var{mode} @var{decl})
-Stands for the value a @var{decl} had at the entry point of the
-containing function.
-
-@findex debug_parameter_ref
-@item (debug_parameter_ref:@var{mode} @var{decl})
-Refers to a parameter that was completely optimized out.
-
-@findex debug_marker
-@item (debug_marker:@var{mode})
-Marks a program location. With @code{VOIDmode}, it stands for the
-beginning of a statement, a recommended inspection point logically after
-all prior side effects, and before any subsequent side effects. With
-@code{BLKmode}, it indicates an inline entry point: the lexical block
-encoded in the @code{INSN_LOCATION} is the enclosing block that encloses
-the inlined function.
-
-@end table
-
-@node Insns
-@section Insns
-@cindex insns
-
-The RTL representation of the code for a function is a doubly-linked
-chain of objects called @dfn{insns}. Insns are expressions with
-special codes that are used for no other purpose. Some insns are
-actual instructions; others represent dispatch tables for @code{switch}
-statements; others represent labels to jump to or various sorts of
-declarative information.
-
-In addition to its own specific data, each insn must have a unique
-id-number that distinguishes it from all other insns in the current
-function (after delayed branch scheduling, copies of an insn with the
-same id-number may be present in multiple places in a function, but
-these copies will always be identical and will only appear inside a
-@code{sequence}), and chain pointers to the preceding and following
-insns. These three fields occupy the same position in every insn,
-independent of the expression code of the insn. They could be accessed
-with @code{XEXP} and @code{XINT}, but instead three special macros are
-always used:
-
-@table @code
-@findex INSN_UID
-@item INSN_UID (@var{i})
-Accesses the unique id of insn @var{i}.
-
-@findex PREV_INSN
-@item PREV_INSN (@var{i})
-Accesses the chain pointer to the insn preceding @var{i}.
-If @var{i} is the first insn, this is a null pointer.
-
-@findex NEXT_INSN
-@item NEXT_INSN (@var{i})
-Accesses the chain pointer to the insn following @var{i}.
-If @var{i} is the last insn, this is a null pointer.
-@end table
-
-@findex get_insns
-@findex get_last_insn
-The first insn in the chain is obtained by calling @code{get_insns}; the
-last insn is the result of calling @code{get_last_insn}. Within the
-chain delimited by these insns, the @code{NEXT_INSN} and
-@code{PREV_INSN} pointers must always correspond: if @var{insn} is not
-the first insn,
-
-@smallexample
-NEXT_INSN (PREV_INSN (@var{insn})) == @var{insn}
-@end smallexample
-
-@noindent
-is always true and if @var{insn} is not the last insn,
-
-@smallexample
-PREV_INSN (NEXT_INSN (@var{insn})) == @var{insn}
-@end smallexample
-
-@noindent
-is always true.
-
-After delay slot scheduling, some of the insns in the chain might be
-@code{sequence} expressions, which contain a vector of insns. The value
-of @code{NEXT_INSN} in all but the last of these insns is the next insn
-in the vector; the value of @code{NEXT_INSN} of the last insn in the vector
-is the same as the value of @code{NEXT_INSN} for the @code{sequence} in
-which it is contained. Similar rules apply for @code{PREV_INSN}.
-
-This means that the above invariants are not necessarily true for insns
-inside @code{sequence} expressions. Specifically, if @var{insn} is the
-first insn in a @code{sequence}, @code{NEXT_INSN (PREV_INSN (@var{insn}))}
-is the insn containing the @code{sequence} expression, as is the value
-of @code{PREV_INSN (NEXT_INSN (@var{insn}))} if @var{insn} is the last
-insn in the @code{sequence} expression. You can use these expressions
-to find the containing @code{sequence} expression.
-
-Every insn has one of the following expression codes:
-
-@table @code
-@findex insn
-@item insn
-The expression code @code{insn} is used for instructions that do not jump
-and do not do function calls. @code{sequence} expressions are always
-contained in insns with code @code{insn} even if one of those insns
-should jump or do function calls.
-
-Insns with code @code{insn} have four additional fields beyond the three
-mandatory ones listed above. These four are described in a table below.
-
-@findex jump_insn
-@item jump_insn
-The expression code @code{jump_insn} is used for instructions that may
-jump (or, more generally, may contain @code{label_ref} expressions to
-which @code{pc} can be set in that instruction). If there is an
-instruction to return from the current function, it is recorded as a
-@code{jump_insn}.
-
-@findex JUMP_LABEL
-@code{jump_insn} insns have the same extra fields as @code{insn} insns,
-accessed in the same way and in addition contain a field
-@code{JUMP_LABEL} which is defined once jump optimization has completed.
-
-For simple conditional and unconditional jumps, this field contains
-the @code{code_label} to which this insn will (possibly conditionally)
-branch. In a more complex jump, @code{JUMP_LABEL} records one of the
-labels that the insn refers to; other jump target labels are recorded
-as @code{REG_LABEL_TARGET} notes. The exception is @code{addr_vec}
-and @code{addr_diff_vec}, where @code{JUMP_LABEL} is @code{NULL_RTX}
-and the only way to find the labels is to scan the entire body of the
-insn.
-
-Return insns count as jumps, but their @code{JUMP_LABEL} is @code{RETURN}
-or @code{SIMPLE_RETURN}.
-
-@findex call_insn
-@item call_insn
-The expression code @code{call_insn} is used for instructions that may do
-function calls. It is important to distinguish these instructions because
-they imply that certain registers and memory locations may be altered
-unpredictably.
-
-@findex CALL_INSN_FUNCTION_USAGE
-@code{call_insn} insns have the same extra fields as @code{insn} insns,
-accessed in the same way and in addition contain a field
-@code{CALL_INSN_FUNCTION_USAGE}, which contains a list (chain of
-@code{expr_list} expressions) containing @code{use}, @code{clobber} and
-sometimes @code{set} expressions that denote hard registers and
-@code{mem}s used or clobbered by the called function.
-
-A @code{mem} generally points to a stack slot in which arguments passed
-to the libcall by reference (@pxref{Register Arguments,
-TARGET_PASS_BY_REFERENCE}) are stored. If the argument is
-caller-copied (@pxref{Register Arguments, TARGET_CALLEE_COPIES}),
-the stack slot will be mentioned in @code{clobber} and @code{use}
-entries; if it's callee-copied, only a @code{use} will appear, and the
-@code{mem} may point to addresses that are not stack slots.
-
-Registers occurring inside a @code{clobber} in this list augment
-registers specified in @code{CALL_USED_REGISTERS} (@pxref{Register
-Basics}).
-
-If the list contains a @code{set} involving two registers, it indicates
-that the function returns one of its arguments. Such a @code{set} may
-look like a no-op if the same register holds the argument and the return
-value.
-
-@findex code_label
-@findex CODE_LABEL_NUMBER
-@item code_label
-A @code{code_label} insn represents a label that a jump insn can jump
-to. It contains two special fields of data in addition to the three
-standard ones. @code{CODE_LABEL_NUMBER} is used to hold the @dfn{label
-number}, a number that identifies this label uniquely among all the
-labels in the compilation (not just in the current function).
-Ultimately, the label is represented in the assembler output as an
-assembler label, usually of the form @samp{L@var{n}} where @var{n} is
-the label number.
-
-When a @code{code_label} appears in an RTL expression, it normally
-appears within a @code{label_ref} which represents the address of
-the label, as a number.
-
-Besides as a @code{code_label}, a label can also be represented as a
-@code{note} of type @code{NOTE_INSN_DELETED_LABEL}.
-
-@findex LABEL_NUSES
-The field @code{LABEL_NUSES} is only defined once the jump optimization
-phase is completed. It contains the number of times this label is
-referenced in the current function.
-
-@findex LABEL_KIND
-@findex SET_LABEL_KIND
-@findex LABEL_ALT_ENTRY_P
-@cindex alternate entry points
-The field @code{LABEL_KIND} differentiates four different types of
-labels: @code{LABEL_NORMAL}, @code{LABEL_STATIC_ENTRY},
-@code{LABEL_GLOBAL_ENTRY}, and @code{LABEL_WEAK_ENTRY}. The only labels
-that do not have type @code{LABEL_NORMAL} are @dfn{alternate entry
-points} to the current function. These may be static (visible only in
-the containing translation unit), global (exposed to all translation
-units), or weak (global, but can be overridden by another symbol with the
-same name).
-
-Much of the compiler treats all four kinds of label identically. Some
-of it needs to know whether or not a label is an alternate entry point;
-for this purpose, the macro @code{LABEL_ALT_ENTRY_P} is provided. It is
-equivalent to testing whether @samp{LABEL_KIND (label) == LABEL_NORMAL}.
-The only place that cares about the distinction between static, global,
-and weak alternate entry points, besides the front-end code that creates
-them, is the function @code{output_alternate_entry_point}, in
-@file{final.cc}.
-
-To set the kind of a label, use the @code{SET_LABEL_KIND} macro.
-
-@findex jump_table_data
-@item jump_table_data
-A @code{jump_table_data} insn is a placeholder for the jump-table data
-of a @code{casesi} or @code{tablejump} insn. They are placed after
-a @code{tablejump_p} insn. A @code{jump_table_data} insn is not part o
-a basic blockm but it is associated with the basic block that ends with
-the @code{tablejump_p} insn. The @code{PATTERN} of a @code{jump_table_data}
-is always either an @code{addr_vec} or an @code{addr_diff_vec}, and a
-@code{jump_table_data} insn is always preceded by a @code{code_label}.
-The @code{tablejump_p} insn refers to that @code{code_label} via its
-@code{JUMP_LABEL}.
-
-@findex barrier
-@item barrier
-Barriers are placed in the instruction stream when control cannot flow
-past them. They are placed after unconditional jump instructions to
-indicate that the jumps are unconditional and after calls to
-@code{volatile} functions, which do not return (e.g., @code{exit}).
-They contain no information beyond the three standard fields.
-
-@findex note
-@findex NOTE_LINE_NUMBER
-@findex NOTE_SOURCE_FILE
-@item note
-@code{note} insns are used to represent additional debugging and
-declarative information. They contain two nonstandard fields, an
-integer which is accessed with the macro @code{NOTE_LINE_NUMBER} and a
-string accessed with @code{NOTE_SOURCE_FILE}.
-
-If @code{NOTE_LINE_NUMBER} is positive, the note represents the
-position of a source line and @code{NOTE_SOURCE_FILE} is the source file name
-that the line came from. These notes control generation of line
-number data in the assembler output.
-
-Otherwise, @code{NOTE_LINE_NUMBER} is not really a line number but a
-code with one of the following values (and @code{NOTE_SOURCE_FILE}
-must contain a null pointer):
-
-@table @code
-@findex NOTE_INSN_DELETED
-@item NOTE_INSN_DELETED
-Such a note is completely ignorable. Some passes of the compiler
-delete insns by altering them into notes of this kind.
-
-@findex NOTE_INSN_DELETED_LABEL
-@item NOTE_INSN_DELETED_LABEL
-This marks what used to be a @code{code_label}, but was not used for other
-purposes than taking its address and was transformed to mark that no
-code jumps to it.
-
-@findex NOTE_INSN_BLOCK_BEG
-@findex NOTE_INSN_BLOCK_END
-@item NOTE_INSN_BLOCK_BEG
-@itemx NOTE_INSN_BLOCK_END
-These types of notes indicate the position of the beginning and end
-of a level of scoping of variable names. They control the output
-of debugging information.
-
-@findex NOTE_INSN_EH_REGION_BEG
-@findex NOTE_INSN_EH_REGION_END
-@item NOTE_INSN_EH_REGION_BEG
-@itemx NOTE_INSN_EH_REGION_END
-These types of notes indicate the position of the beginning and end of a
-level of scoping for exception handling. @code{NOTE_EH_HANDLER}
-identifies which region is associated with these notes.
-
-@findex NOTE_INSN_FUNCTION_BEG
-@item NOTE_INSN_FUNCTION_BEG
-Appears at the start of the function body, after the function
-prologue.
-
-@findex NOTE_INSN_VAR_LOCATION
-@findex NOTE_VAR_LOCATION
-@item NOTE_INSN_VAR_LOCATION
-This note is used to generate variable location debugging information.
-It indicates that the user variable in its @code{VAR_LOCATION} operand
-is at the location given in the RTL expression, or holds a value that
-can be computed by evaluating the RTL expression from that static
-point in the program up to the next such note for the same user
-variable.
-
-@findex NOTE_INSN_BEGIN_STMT
-@item NOTE_INSN_BEGIN_STMT
-This note is used to generate @code{is_stmt} markers in line number
-debugging information. It indicates the beginning of a user
-statement.
-
-@findex NOTE_INSN_INLINE_ENTRY
-@item NOTE_INSN_INLINE_ENTRY
-This note is used to generate @code{entry_pc} for inlined subroutines in
-debugging information. It indicates an inspection point at which all
-arguments for the inlined function have been bound, and before its first
-statement.
-
-@end table
-
-These codes are printed symbolically when they appear in debugging dumps.
-
-@findex debug_insn
-@findex INSN_VAR_LOCATION
-@item debug_insn
-The expression code @code{debug_insn} is used for pseudo-instructions
-that hold debugging information for variable tracking at assignments
-(see @option{-fvar-tracking-assignments} option). They are the RTL
-representation of @code{GIMPLE_DEBUG} statements
-(@ref{@code{GIMPLE_DEBUG}}), with a @code{VAR_LOCATION} operand that
-binds a user variable tree to an RTL representation of the
-@code{value} in the corresponding statement. A @code{DEBUG_EXPR} in
-it stands for the value bound to the corresponding
-@code{DEBUG_EXPR_DECL}.
-
-@code{GIMPLE_DEBUG_BEGIN_STMT} and @code{GIMPLE_DEBUG_INLINE_ENTRY} are
-expanded to RTL as a @code{DEBUG_INSN} with a @code{DEBUG_MARKER}
-@code{PATTERN}; the difference is the RTL mode: the former's
-@code{DEBUG_MARKER} is @code{VOIDmode}, whereas the latter is
-@code{BLKmode}; information about the inlined function can be taken from
-the lexical block encoded in the @code{INSN_LOCATION}. These
-@code{DEBUG_INSN}s, that do not carry @code{VAR_LOCATION} information,
-just @code{DEBUG_MARKER}s, can be detected by testing
-@code{DEBUG_MARKER_INSN_P}, whereas those that do can be recognized as
-@code{DEBUG_BIND_INSN_P}.
-
-Throughout optimization passes, @code{DEBUG_INSN}s are not reordered
-with respect to each other, particularly during scheduling. Binding
-information is kept in pseudo-instruction form, so that, unlike notes,
-it gets the same treatment and adjustments that regular instructions
-would. It is the variable tracking pass that turns these
-pseudo-instructions into @code{NOTE_INSN_VAR_LOCATION},
-@code{NOTE_INSN_BEGIN_STMT} and @code{NOTE_INSN_INLINE_ENTRY} notes,
-analyzing control flow, value equivalences and changes to registers and
-memory referenced in value expressions, propagating the values of debug
-temporaries and determining expressions that can be used to compute the
-value of each user variable at as many points (ranges, actually) in the
-program as possible.
-
-Unlike @code{NOTE_INSN_VAR_LOCATION}, the value expression in an
-@code{INSN_VAR_LOCATION} denotes a value at that specific point in the
-program, rather than an expression that can be evaluated at any later
-point before an overriding @code{VAR_LOCATION} is encountered. E.g.,
-if a user variable is bound to a @code{REG} and then a subsequent insn
-modifies the @code{REG}, the note location would keep mapping the user
-variable to the register across the insn, whereas the insn location
-would keep the variable bound to the value, so that the variable
-tracking pass would emit another location note for the variable at the
-point in which the register is modified.
-
-@end table
-
-@cindex @code{TImode}, in @code{insn}
-@cindex @code{HImode}, in @code{insn}
-@cindex @code{QImode}, in @code{insn}
-The machine mode of an insn is normally @code{VOIDmode}, but some
-phases use the mode for various purposes.
-
-The common subexpression elimination pass sets the mode of an insn to
-@code{QImode} when it is the first insn in a block that has already
-been processed.
-
-The second Haifa scheduling pass, for targets that can multiple issue,
-sets the mode of an insn to @code{TImode} when it is believed that the
-instruction begins an issue group. That is, when the instruction
-cannot issue simultaneously with the previous. This may be relied on
-by later passes, in particular machine-dependent reorg.
-
-Here is a table of the extra fields of @code{insn}, @code{jump_insn}
-and @code{call_insn} insns:
-
-@table @code
-@findex PATTERN
-@item PATTERN (@var{i})
-An expression for the side effect performed by this insn. This must
-be one of the following codes: @code{set}, @code{call}, @code{use},
-@code{clobber}, @code{return}, @code{simple_return}, @code{asm_input},
-@code{asm_output}, @code{addr_vec}, @code{addr_diff_vec},
-@code{trap_if}, @code{unspec}, @code{unspec_volatile},
-@code{parallel}, @code{cond_exec}, or @code{sequence}. If it is a
-@code{parallel}, each element of the @code{parallel} must be one these
-codes, except that @code{parallel} expressions cannot be nested and
-@code{addr_vec} and @code{addr_diff_vec} are not permitted inside a
-@code{parallel} expression.
-
-@findex INSN_CODE
-@item INSN_CODE (@var{i})
-An integer that says which pattern in the machine description matches
-this insn, or @minus{}1 if the matching has not yet been attempted.
-
-Such matching is never attempted and this field remains @minus{}1 on an insn
-whose pattern consists of a single @code{use}, @code{clobber},
-@code{asm_input}, @code{addr_vec} or @code{addr_diff_vec} expression.
-
-@findex asm_noperands
-Matching is also never attempted on insns that result from an @code{asm}
-statement. These contain at least one @code{asm_operands} expression.
-The function @code{asm_noperands} returns a non-negative value for
-such insns.
-
-In the debugging output, this field is printed as a number followed by
-a symbolic representation that locates the pattern in the @file{md}
-file as some small positive or negative offset from a named pattern.
-
-@findex REG_NOTES
-@item REG_NOTES (@var{i})
-A list (chain of @code{expr_list}, @code{insn_list} and @code{int_list}
-expressions) giving miscellaneous information about the insn. It is often
-information pertaining to the registers used in this insn.
-@end table
-
-The @code{REG_NOTES} field of an insn is a chain that includes
-@code{expr_list} and @code{int_list} expressions as well as @code{insn_list}
-expressions. There are several
-kinds of register notes, which are distinguished by the machine mode, which
-in a register note is really understood as being an @code{enum reg_note}.
-The first operand @var{op} of the note is data whose meaning depends on
-the kind of note.
-
-@findex REG_NOTE_KIND
-@findex PUT_REG_NOTE_KIND
-The macro @code{REG_NOTE_KIND (@var{x})} returns the kind of
-register note. Its counterpart, the macro @code{PUT_REG_NOTE_KIND
-(@var{x}, @var{newkind})} sets the register note type of @var{x} to be
-@var{newkind}.
-
-Register notes are of three classes: They may say something about an
-input to an insn, they may say something about an output of an insn, or
-they may create a linkage between two insns.
-
-These register notes annotate inputs to an insn:
-
-@table @code
-@findex REG_DEAD
-@item REG_DEAD
-The value in @var{op} dies in this insn; that is to say, altering the
-value immediately after this insn would not affect the future behavior
-of the program.
-
-It does not follow that the register @var{op} has no useful value after
-this insn since @var{op} is not necessarily modified by this insn.
-Rather, no subsequent instruction uses the contents of @var{op}.
-
-@findex REG_UNUSED
-@item REG_UNUSED
-The register @var{op} being set by this insn will not be used in a
-subsequent insn. This differs from a @code{REG_DEAD} note, which
-indicates that the value in an input will not be used subsequently.
-These two notes are independent; both may be present for the same
-register.
-
-@findex REG_INC
-@item REG_INC
-The register @var{op} is incremented (or decremented; at this level
-there is no distinction) by an embedded side effect inside this insn.
-This means it appears in a @code{post_inc}, @code{pre_inc},
-@code{post_dec} or @code{pre_dec} expression.
-
-@findex REG_NONNEG
-@item REG_NONNEG
-The register @var{op} is known to have a nonnegative value when this
-insn is reached. This is used by special looping instructions
-that terminate when the register goes negative.
-
-The @code{REG_NONNEG} note is added only to @samp{doloop_end}
-insns, if its pattern uses a @code{ge} condition.
-
-@findex REG_LABEL_OPERAND
-@item REG_LABEL_OPERAND
-This insn uses @var{op}, a @code{code_label} or a @code{note} of type
-@code{NOTE_INSN_DELETED_LABEL}, but is not a @code{jump_insn}, or it
-is a @code{jump_insn} that refers to the operand as an ordinary
-operand. The label may still eventually be a jump target, but if so
-in an indirect jump in a subsequent insn. The presence of this note
-allows jump optimization to be aware that @var{op} is, in fact, being
-used, and flow optimization to build an accurate flow graph.
-
-@findex REG_LABEL_TARGET
-@item REG_LABEL_TARGET
-This insn is a @code{jump_insn} but not an @code{addr_vec} or
-@code{addr_diff_vec}. It uses @var{op}, a @code{code_label} as a
-direct or indirect jump target. Its purpose is similar to that of
-@code{REG_LABEL_OPERAND}. This note is only present if the insn has
-multiple targets; the last label in the insn (in the highest numbered
-insn-field) goes into the @code{JUMP_LABEL} field and does not have a
-@code{REG_LABEL_TARGET} note. @xref{Insns, JUMP_LABEL}.
-
-@findex REG_SETJMP
-@item REG_SETJMP
-Appears attached to each @code{CALL_INSN} to @code{setjmp} or a
-related function.
-@end table
-
-The following notes describe attributes of outputs of an insn:
-
-@table @code
-@findex REG_EQUIV
-@findex REG_EQUAL
-@item REG_EQUIV
-@itemx REG_EQUAL
-This note is only valid on an insn that sets only one register and
-indicates that that register will be equal to @var{op} at run time; the
-scope of this equivalence differs between the two types of notes. The
-value which the insn explicitly copies into the register may look
-different from @var{op}, but they will be equal at run time. If the
-output of the single @code{set} is a @code{strict_low_part} or
-@code{zero_extract} expression, the note refers to the register that
-is contained in its first operand.
-
-For @code{REG_EQUIV}, the register is equivalent to @var{op} throughout
-the entire function, and could validly be replaced in all its
-occurrences by @var{op}. (``Validly'' here refers to the data flow of
-the program; simple replacement may make some insns invalid.) For
-example, when a constant is loaded into a register that is never
-assigned any other value, this kind of note is used.
-
-When a parameter is copied into a pseudo-register at entry to a function,
-a note of this kind records that the register is equivalent to the stack
-slot where the parameter was passed. Although in this case the register
-may be set by other insns, it is still valid to replace the register
-by the stack slot throughout the function.
-
-A @code{REG_EQUIV} note is also used on an instruction which copies a
-register parameter into a pseudo-register at entry to a function, if
-there is a stack slot where that parameter could be stored. Although
-other insns may set the pseudo-register, it is valid for the compiler to
-replace the pseudo-register by stack slot throughout the function,
-provided the compiler ensures that the stack slot is properly
-initialized by making the replacement in the initial copy instruction as
-well. This is used on machines for which the calling convention
-allocates stack space for register parameters. See
-@code{REG_PARM_STACK_SPACE} in @ref{Stack Arguments}.
-
-In the case of @code{REG_EQUAL}, the register that is set by this insn
-will be equal to @var{op} at run time at the end of this insn but not
-necessarily elsewhere in the function. In this case, @var{op}
-is typically an arithmetic expression. For example, when a sequence of
-insns such as a library call is used to perform an arithmetic operation,
-this kind of note is attached to the insn that produces or copies the
-final value.
-
-These two notes are used in different ways by the compiler passes.
-@code{REG_EQUAL} is used by passes prior to register allocation (such as
-common subexpression elimination and loop optimization) to tell them how
-to think of that value. @code{REG_EQUIV} notes are used by register
-allocation to indicate that there is an available substitute expression
-(either a constant or a @code{mem} expression for the location of a
-parameter on the stack) that may be used in place of a register if
-insufficient registers are available.
-
-Except for stack homes for parameters, which are indicated by a
-@code{REG_EQUIV} note and are not useful to the early optimization
-passes and pseudo registers that are equivalent to a memory location
-throughout their entire life, which is not detected until later in
-the compilation, all equivalences are initially indicated by an attached
-@code{REG_EQUAL} note. In the early stages of register allocation, a
-@code{REG_EQUAL} note is changed into a @code{REG_EQUIV} note if
-@var{op} is a constant and the insn represents the only set of its
-destination register.
-
-Thus, compiler passes prior to register allocation need only check for
-@code{REG_EQUAL} notes and passes subsequent to register allocation
-need only check for @code{REG_EQUIV} notes.
-@end table
-
-These notes describe linkages between insns. They occur in pairs: one
-insn has one of a pair of notes that points to a second insn, which has
-the inverse note pointing back to the first insn.
-
-@table @code
-@findex REG_DEP_TRUE
-@item REG_DEP_TRUE
-This indicates a true dependence (a read after write dependence).
-
-@findex REG_DEP_OUTPUT
-@item REG_DEP_OUTPUT
-This indicates an output dependence (a write after write dependence).
-
-@findex REG_DEP_ANTI
-@item REG_DEP_ANTI
-This indicates an anti dependence (a write after read dependence).
-
-@end table
-
-These notes describe information gathered from gcov profile data. They
-are stored in the @code{REG_NOTES} field of an insn.
-
-@table @code
-@findex REG_BR_PROB
-@item REG_BR_PROB
-This is used to specify the ratio of branches to non-branches of a
-branch insn according to the profile data. The note is represented
-as an @code{int_list} expression whose integer value is an encoding
-of @code{profile_probability} type. @code{profile_probability} provide
-member function @code{from_reg_br_prob_note} and @code{to_reg_br_prob_note}
-to extract and store the probability into the RTL encoding.
-
-@findex REG_BR_PRED
-@item REG_BR_PRED
-These notes are found in JUMP insns after delayed branch scheduling
-has taken place. They indicate both the direction and the likelihood
-of the JUMP@. The format is a bitmask of ATTR_FLAG_* values.
-
-@findex REG_FRAME_RELATED_EXPR
-@item REG_FRAME_RELATED_EXPR
-This is used on an RTX_FRAME_RELATED_P insn wherein the attached expression
-is used in place of the actual insn pattern. This is done in cases where
-the pattern is either complex or misleading.
-@end table
-
-The note @code{REG_CALL_NOCF_CHECK} is used in conjunction with the
-@option{-fcf-protection=branch} option. The note is set if a
-@code{nocf_check} attribute is specified for a function type or a
-pointer to function type. The note is stored in the @code{REG_NOTES}
-field of an insn.
-
-@table @code
-@findex REG_CALL_NOCF_CHECK
-@item REG_CALL_NOCF_CHECK
-Users have control through the @code{nocf_check} attribute to identify
-which calls to a function should be skipped from control-flow instrumentation
-when the option @option{-fcf-protection=branch} is specified. The compiler
-puts a @code{REG_CALL_NOCF_CHECK} note on each @code{CALL_INSN} instruction
-that has a function type marked with a @code{nocf_check} attribute.
-@end table
-
-For convenience, the machine mode in an @code{insn_list} or
-@code{expr_list} is printed using these symbolic codes in debugging dumps.
-
-@findex insn_list
-@findex expr_list
-The only difference between the expression codes @code{insn_list} and
-@code{expr_list} is that the first operand of an @code{insn_list} is
-assumed to be an insn and is printed in debugging dumps as the insn's
-unique id; the first operand of an @code{expr_list} is printed in the
-ordinary way as an expression.
-
-@node Calls
-@section RTL Representation of Function-Call Insns
-@cindex calling functions in RTL
-@cindex RTL function-call insns
-@cindex function-call insns
-
-Insns that call subroutines have the RTL expression code @code{call_insn}.
-These insns must satisfy special rules, and their bodies must use a special
-RTL expression code, @code{call}.
-
-@cindex @code{call} usage
-A @code{call} expression has two operands, as follows:
-
-@smallexample
-(call (mem:@var{fm} @var{addr}) @var{nbytes})
-@end smallexample
-
-@noindent
-Here @var{nbytes} is an operand that represents the number of bytes of
-argument data being passed to the subroutine, @var{fm} is a machine mode
-(which must equal as the definition of the @code{FUNCTION_MODE} macro in
-the machine description) and @var{addr} represents the address of the
-subroutine.
-
-For a subroutine that returns no value, the @code{call} expression as
-shown above is the entire body of the insn, except that the insn might
-also contain @code{use} or @code{clobber} expressions.
-
-@cindex @code{BLKmode}, and function return values
-For a subroutine that returns a value whose mode is not @code{BLKmode},
-the value is returned in a hard register. If this register's number is
-@var{r}, then the body of the call insn looks like this:
-
-@smallexample
-(set (reg:@var{m} @var{r})
- (call (mem:@var{fm} @var{addr}) @var{nbytes}))
-@end smallexample
-
-@noindent
-This RTL expression makes it clear (to the optimizer passes) that the
-appropriate register receives a useful value in this insn.
-
-When a subroutine returns a @code{BLKmode} value, it is handled by
-passing to the subroutine the address of a place to store the value.
-So the call insn itself does not ``return'' any value, and it has the
-same RTL form as a call that returns nothing.
-
-On some machines, the call instruction itself clobbers some register,
-for example to contain the return address. @code{call_insn} insns
-on these machines should have a body which is a @code{parallel}
-that contains both the @code{call} expression and @code{clobber}
-expressions that indicate which registers are destroyed. Similarly,
-if the call instruction requires some register other than the stack
-pointer that is not explicitly mentioned in its RTL, a @code{use}
-subexpression should mention that register.
-
-Functions that are called are assumed to modify all registers listed in
-the configuration macro @code{CALL_USED_REGISTERS} (@pxref{Register
-Basics}) and, with the exception of @code{const} functions and library
-calls, to modify all of memory.
-
-Insns containing just @code{use} expressions directly precede the
-@code{call_insn} insn to indicate which registers contain inputs to the
-function. Similarly, if registers other than those in
-@code{CALL_USED_REGISTERS} are clobbered by the called function, insns
-containing a single @code{clobber} follow immediately after the call to
-indicate which registers.
-
-@node RTL SSA
-@section On-the-Side SSA Form for RTL
-@cindex SSA, RTL form
-@cindex RTL SSA
-
-The patterns of an individual RTL instruction describe which registers
-are inputs to that instruction and which registers are outputs from
-that instruction. However, it is often useful to know where the
-definition of a register input comes from and where the result of
-a register output is used. One way of obtaining this information
-is to use the RTL SSA form, which provides a Static Single Assignment
-representation of the RTL instructions.
-
-The RTL SSA code is located in the @file{rtl-ssa} subdirectory of the GCC
-source tree. This section only gives a brief overview of it; please
-see the comments in the source code for more details.
-
-@menu
-* Using RTL SSA:: What a pass needs to do to use the RTL SSA form
-* RTL SSA Instructions:: How instructions are represented and organized
-* RTL SSA Basic Blocks:: How instructions are grouped into blocks
-* RTL SSA Resources:: How registers and memory are represented
-* RTL SSA Accesses:: How register and memory accesses are represented
-* RTL SSA Phi Nodes:: How multiple sources are combined into one
-* RTL SSA Access Lists:: How accesses are chained together
-* Changing RTL Instructions:: How to use the RTL SSA framework to change insns
-@end menu
-
-@node Using RTL SSA
-@subsection Using RTL SSA in a pass
-
-A pass that wants to use the RTL SSA form should start with the following:
-
-@smallexample
-#define INCLUDE_ALGORITHM
-#define INCLUDE_FUNCTIONAL
-#include "config.h"
-#include "system.h"
-#include "coretypes.h"
-#include "backend.h"
-#include "rtl.h"
-#include "df.h"
-#include "rtl-ssa.h"
-@end smallexample
-
-All the RTL SSA code is contained in the @code{rtl_ssa} namespace,
-so most passes will then want to do:
-
-@smallexample
-using namespace rtl_ssa;
-@end smallexample
-
-However, this is purely a matter of taste, and the examples in the rest of
-this section do not require it.
-
-The RTL SSA represention is an optional on-the-side feature that applies
-on top of the normal RTL instructions. It is currently local to individual
-RTL passes and is not maintained across passes.
-
-However, in order to allow the RTL SSA information to be preserved across
-passes in future, @samp{crtl->ssa} points to the current function's
-SSA form (if any). Passes that want to use the RTL SSA form should
-first do:
-
-@smallexample
-crtl->ssa = new rtl_ssa::function_info (@var{fn});
-@end smallexample
-
-where @var{fn} is the function that the pass is processing.
-(Passes that are @code{using namespace rtl_ssa} do not need
-the @samp{rtl_ssa::}.)
-
-Once the pass has finished with the SSA form, it should do the following:
-
-@smallexample
-free_dominance_info (CDI_DOMINATORS);
-if (crtl->ssa->perform_pending_updates ())
- cleanup_cfg (0);
-
-delete crtl->ssa;
-crtl->ssa = nullptr;
-@end smallexample
-
-The @code{free_dominance_info} call is necessary because
-dominance information is not currently maintained between RTL passes.
-The next two lines commit any changes to the RTL instructions that
-were queued for later; see the comment above the declaration of
-@code{perform_pending_updates} for details. The final two lines
-discard the RTL SSA form and free the associated memory.
-
-@node RTL SSA Instructions
-@subsection RTL SSA Instructions
-
-@cindex RPO
-@cindex reverse postorder
-@cindex instructions, RTL SSA
-@findex rtl_ssa::insn_info
-RTL SSA instructions are represented by an @code{rtl_ssa::insn_info}.
-These instructions are chained together in a single list that follows
-a reverse postorder (RPO) traversal of the function. This means that
-if any path through the function can execute an instruction @var{I1}
-and then later execute an instruction @var{I2} for the first time,
-@var{I1} appears before @var{I2} in the list@footnote{Note that this
-order is different from the order of the underlying RTL instructions,
-which follow machine code order instead.}.
-
-Two RTL SSA instructions can be compared to find which instruction
-occurs earlier than the other in the RPO@. One way to do this is
-to use the C++ comparison operators, such as:
-
-@example
-*@var{insn1} < *@var{insn2}
-@end example
-
-Another way is to use the @code{compare_with} function:
-
-@example
-@var{insn1}->compare_with (@var{insn2})
-@end example
-
-This expression is greater than zero if @var{insn1} comes after @var{insn2}
-in the RPO, less than zero if @var{insn1} comes before @var{insn2} in the
-RPO, or zero if @var{insn1} and @var{insn2} are the same. This order is
-maintained even if instructions are added to the function or moved around.
-
-The main purpose of @code{rtl_ssa::insn_info} is to hold
-SSA information about an instruction. However, it also caches
-certain properties of the instruction, such as whether it is an
-inline assembly instruction, whether it has volatile accesses, and so on.
-
-@node RTL SSA Basic Blocks
-@subsection RTL SSA Basic Blocks
-
-@cindex basic blocks, RTL SSA
-@findex basic_block
-@findex rtl_ssa::bb_info
-RTL SSA instructions (@pxref{RTL SSA Instructions}) are organized into
-basic blocks, with each block being represented by an @code{rtl_ssa:bb_info}.
-There is a one-to-one mapping between these @code{rtl_ssa:bb_info}
-structures and the underlying CFG @code{basic_block} structures
-(@pxref{Basic Blocks}).
-
-@cindex ``real'' instructions, RTL SSA
-@anchor{real RTL SSA insns}
-If a CFG basic block @var{bb} contains an RTL instruction @var{insn},
-the RTL SSA represenation of @var{bb} also contains an RTL SSA representation
-of @var{insn}@footnote{Note that this excludes non-instruction things like
-@code{note}s and @code{barrier}s that also appear in the chain of RTL
-instructions.}. Within RTL SSA, these instructions are referred to as
-``real'' instructions. These real instructions fall into two groups:
-debug instructions and nondebug instructions. Only nondebug instructions
-should affect code generation decisions.
-
-In addition, each RTL SSA basic block has two ``artificial''
-instructions: a ``head'' instruction that comes before all the real
-instructions and an ``end'' instruction that comes after all real
-instructions. These instructions exist to represent things that
-are conceptually defined or used at the start and end of a basic block.
-The instructions always exist, even if they do not currently do anything.
-
-Like instructions, these blocks are chained together in a reverse
-postorder. This list includes the entry block (which always comes
-first) and the exit block (which always comes last).
-
-@cindex extended basic blocks, RTL SSA
-@findex rtl_ssa::ebb_info
-RTL SSA basic blocks are chained together into ``extended basic blocks''
-(EBBs), represented by an @code{rtl_ssa::ebb_info}. Extended basic
-blocks contain one or more basic blocks. They have the property
-that if a block @var{bby} comes immediately after a block @var{bbx}
-in an EBB, then @var{bby} can only be reached by @var{bbx}; in other words,
-@var{bbx} is the sole predecessor of @var{bby}.
-
-Each extended basic block starts with an artificial ``phi node''
-instruction. This instruction defines all phi nodes for the EBB
-(@pxref{RTL SSA Phi Nodes}). (Individual blocks in an EBB do not
-need phi nodes because their live values can only come from one source.)
-
-The contents of a function are therefore represented using a
-four-level hierarchy:
-
-@itemize @bullet
-@item
-functions (@code{rtl_ssa::function_info}), which contain @dots{}
-
-@item
-extended basic blocks (@code{rtl_ssa::ebb_info}), which contain @dots{}
-
-@item
-basic blocks (@code{rtl_ssa::bb_info}), which contain @dots{}
-
-@item
-instructions (@code{rtl_ssa::insn_info})
-@end itemize
-
-In dumps, a basic block is identified as @code{bb@var{n}}, where @var{n}
-is the index of the associated CFG @code{basic_block} structure.
-An EBB is in turn identified by the index of its first block.
-For example, an EBB that contains @samp{bb10}, @code{bb5}, @code{bb6}
-and @code{bb9} is identified as @var{ebb10}.
-
-@node RTL SSA Resources
-@subsection RTL SSA Resources
-
-The RTL SSA form tracks two types of ``resource'': registers and memory.
-Each hard and pseudo register is a separate resource. Memory is a
-single unified resource, like it is in GIMPLE (@pxref{GIMPLE}).
-
-Each resource has a unique identifier. The unique identifier for a
-register is simply its register number. The unique identifier for
-memory is a special register number called @code{MEM_REGNO}.
-
-Since resource numbers so closely match register numbers, it is sometimes
-convenient to refer to them simply as register numbers, or ``regnos''
-for short. However, the RTL SSA form also provides an abstraction
-of resources in the form of @code{rtl_ssa::resource_info}.
-This is a lightweight class that records both the regno of a resource
-and the @code{machine_mode} that the resource has (@pxref{Machine Modes}).
-It has functions for testing whether a resource is a register or memory.
-In principle it could be extended to other kinds of resource in future.
-
-@node RTL SSA Accesses
-@subsection RTL SSA Register and Memory Accesses
-
-In the RTL SSA form, most reads or writes of a resource are
-represented as a @code{rtl_ssa::access_info}@footnote{The exceptions
-are call clobbers, which are generally represented separately.
-See the comment above @code{rtl_ssa::insn_info} for details.}.
-These @code{rtl_ssa::access_info}s are organized into the following
-class hierarchy:
-
-@findex rtl_ssa::access_info
-@findex rtl_ssa::use_info
-@findex rtl_ssa::def_info
-@findex rtl_ssa::clobber_info
-@findex rtl_ssa::set_info
-@findex rtl_ssa::phi_info
-@smallexample
-rtl_ssa::access_info
- |
- +-- rtl_ssa::use_info
- |
- +-- rtl_ssa::def_info
- |
- +-- rtl_ssa::clobber_info
- |
- +-- rtl_ssa::set_info
- |
- +-- rtl_ssa::phi_info
-@end smallexample
-
-A @code{rtl_ssa::use_info} represents a read or use of a resource and
-a @code{rtl_ssa::def_info} represents a write or definition of a resource.
-As in the main RTL representation, there are two basic types of
-definition: clobbers and sets. The difference is that a clobber
-leaves the register with an unspecified value that cannot be used
-or relied on by later instructions, while a set leaves the register
-with a known value that later instructions could use if they wanted to.
-A @code{rtl_ssa::clobber_info} represents a clobber and
-a @code{rtl_ssa::set_info} represent a set.
-
-Each @code{rtl_ssa::use_info} records which single @code{rtl_ssa::set_info}
-provides the value of the resource; this is null if the resource is
-completely undefined at the point of use. Each @code{rtl_ssa::set_info}
-in turn records all the @code{rtl_ssa::use_info}s that use its value.
-
-If a value of a resource can come from multiple sources,
-a @code{rtl_ssa::phi_info} brings those multiple sources together
-into a single definition (@pxref{RTL SSA Phi Nodes}).
-
-@node RTL SSA Phi Nodes
-@subsection RTL SSA Phi Nodes
-
-@cindex phi nodes, RTL SSA
-@findex rtl_ssa::phi_info
-If a resource is live on entry to an extended basic block and if the
-resource's value can come from multiple sources, the extended basic block
-has a ``phi node'' that collects together these multiple sources.
-The phi node conceptually has one input for each incoming edge of
-the extended basic block, with the input specifying the value of
-the resource on that edge. For example, suppose a function contains
-the following RTL:
-
-@smallexample
-;; Basic block bb3
-@dots{}
-(set (reg:SI R1) (const_int 0)) ;; A
-(set (pc) (label_ref bb5))
-
-;; Basic block bb4
-@dots{}
-(set (reg:SI R1) (const_int 1)) ;; B
-;; Fall through
-
-;; Basic block bb5
-;; preds: bb3, bb4
-;; live in: R1 @dots{}
-(code_label bb5)
-@dots{}
-(set (reg:SI @var{R2})
- (plus:SI (reg:SI R1) @dots{})) ;; C
-@end smallexample
-
-The value of R1 on entry to block 5 can come from either A or B@.
-The extended basic block that contains block 5 would therefore have a
-phi node with two inputs: the first input would have the value of
-R1 defined by A and the second input would have the value of
-R1 defined by B@. This phi node would then provide the value of
-R1 for C (assuming that R1 does not change again between
-the start of block 5 and C).
-
-Since RTL is not a ``native'' SSA representation, these phi nodes
-simply collect together definitions that already exist. Each input
-to a phi node for a resource @var{R} is itself a definition of
-resource @var{R} (or is null if the resource is completely
-undefined for a particular incoming edge). This is in contrast
-to a native SSA representation like GIMPLE, where the phi inputs
-can be arbitrary expressions. As a result, RTL SSA phi nodes
-never involve ``hidden'' moves: all moves are instead explicit.
-
-Phi nodes are represented as a @code{rtl_ssa::phi_node}.
-Each input to a phi node is represented as an @code{rtl_ssa::use_info}.
-
-@node RTL SSA Access Lists
-@subsection RTL SSA Access Lists
-
-All the definitions of a resource are chained together in reverse postorder.
-In general, this list can contain an arbitrary mix of both sets
-(@code{rtl_ssa::set_info}) and clobbers (@code{rtl_ssa::clobber_info}).
-However, it is often useful to skip over all intervening clobbers
-of a resource in order to find the next set. The list is constructed
-in such a way that this can be done in amortized constant time.
-
-All uses (@code{rtl_ssa::use_info}) of a given set are also chained
-together into a list. This list of uses is divided into three parts:
-
-@enumerate
-@item
-uses by ``real'' nondebug instructions (@pxref{real RTL SSA insns})
-
-@item
-uses by real debug instructions
-
-@item
-uses by phi nodes (@pxref{RTL SSA Phi Nodes})
-@end enumerate
-
-The first and second parts individually follow reverse postorder.
-The third part has no particular order.
-
-@cindex degenerate phi node, RTL SSA
-The last use by a real nondebug instruction always comes earlier in
-the reverse postorder than the next definition of the resource (if any).
-This means that the accesses follow a linear sequence of the form:
-
-@itemize @bullet
-@item
-first definition of resource R
-
-@itemize @bullet
-@item
-first use by a real nondebug instruction of the first definition of resource R
-
-@item
-@dots{}
-
-@item
-last use by a real nondebug instruction of the first definition of resource R
-@end itemize
-
-@item
-second definition of resource R
-
-@itemize @bullet
-@item
-first use by a real nondebug instruction of the second definition of resource R
-
-@item
-@dots{}
-
-@item
-last use by a real nondebug instruction of the second definition of resource R
-@end itemize
-
-@item
-@dots{}
-
-@item
-last definition of resource R
-
-@itemize @bullet
-@item
-first use by a real nondebug instruction of the last definition of resource R
-
-@item
-@dots{}
-
-@item
-last use by a real nondebug instruction of the last definition of resource R
-@end itemize
-@end itemize
-
-(Note that clobbers never have uses; only sets do.)
-
-This linear view is easy to achieve when there is only a single definition
-of a resource, which is commonly true for pseudo registers. However,
-things are more complex if code has a structure like the following:
-
-@smallexample
-// ebb2, bb2
-R = @var{va}; // A
-if (@dots{})
- @{
- // ebb2, bb3
- use1 (R); // B
- @dots{}
- R = @var{vc}; // C
- @}
-else
- @{
- // ebb4, bb4
- use2 (R); // D
- @}
-@end smallexample
-
-The list of accesses would begin as follows:
-
-@itemize @bullet
-@item
-definition of R by A
-
-@itemize @bullet
-@item
-use of A's definition of R by B
-@end itemize
-
-@item
-definition of R by C
-@end itemize
-
-The next access to R is in D, but the value of R that D uses comes from
-A rather than C@.
-
-This is resolved by adding a phi node for @code{ebb4}. All inputs to this
-phi node have the same value, which in the example above is A's definition
-of R@. In other circumstances, it would not be necessary to create a phi
-node when all inputs are equal, so these phi nodes are referred to as
-``degenerate'' phi nodes.
-
-The full list of accesses to R is therefore:
-
-@itemize @bullet
-@item
-definition of R by A
-
-@itemize @bullet
-@item
-use of A's definition of R by B
-@end itemize
-
-@item
-definition of R by C
-
-@item
-definition of R by ebb4's phi instruction, with the input coming from A
-
-@itemize @bullet
-@item
-use of the ebb4's R phi definition of R by B
-@end itemize
-@end itemize
-
-Note that A's definition is also used by ebb4's phi node, but this
-use belongs to the third part of the use list described above and
-so does not form part of the linear sequence.
-
-It is possible to ``look through'' any degenerate phi to the ultimate
-definition using the function @code{look_through_degenerate_phi}.
-Note that the input to a degenerate phi is never itself provided
-by a degenerate phi.
-
-At present, the SSA form takes this principle one step further
-and guarantees that, for any given resource @var{res}, one of the
-following is true:
-
-@itemize
-@item
-The resource has a single definition @var{def}, which is not a phi node.
-Excluding uses of undefined registers, all uses of @var{res} by real
-nondebug instructions use the value provided by @var{def}.
-
-@item
-Excluding uses of undefined registers, all uses of @var{res} use
-values provided by definitions that occur earlier in the same
-extended basic block. These definitions might come from phi nodes
-or from real instructions.
-@end itemize
-
-@node Changing RTL Instructions
-@subsection Using the RTL SSA framework to change instructions
-
-@findex rtl_ssa::insn_change
-There are various routines that help to change a single RTL instruction
-or a group of RTL instructions while keeping the RTL SSA form up-to-date.
-This section first describes the process for changing a single instruction,
-then goes on to describe the differences when changing multiple instructions.
-
-@menu
-* Changing One RTL SSA Instruction::
-* Changing Multiple RTL SSA Instructions::
-@end menu
-
-@node Changing One RTL SSA Instruction
-@subsubsection Changing One RTL SSA Instruction
-
-Before making a change, passes should first use a statement like the
-following:
-
-@smallexample
-auto attempt = crtl->ssa->new_change_attempt ();
-@end smallexample
-
-Here, @code{attempt} is an RAII object that should remain in scope
-for the entire change attempt. It automatically frees temporary
-memory related to the changes when it goes out of scope.
-
-Next, the pass should create an @code{rtl_ssa::insn_change} object
-for the instruction that it wants to change. This object specifies
-several things:
-
-@itemize @bullet
-@item
-what the instruction's new list of uses should be (@code{new_uses}).
-By default this is the same as the instruction's current list of uses.
-
-@item
-what the instruction's new list of definitions should be (@code{new_defs}).
-By default this is the same as the instruction's current list of
-definitions.
-
-@item
-where the instruction should be located (@code{move_range}).
-This is a range of instructions after which the instruction could
-be placed, represented as an @code{rtl_ssa::insn_range}.
-By default the instruction must remain at its current position.
-@end itemize
-
-If a pass was attempting to change all these properties of an instruction
-@code{insn}, it might do something like this:
-
-@smallexample
-rtl_ssa::insn_change change (insn);
-change.new_defs = @dots{};
-change.new_uses = @dots{};
-change.move_range = @dots{};
-@end smallexample
-
-This @code{rtl_ssa::insn_change} only describes something that the
-pass @emph{might} do; at this stage, nothing has actually changed.
-
-As noted above, the default @code{move_range} requires the instruction
-to remain where it is. At the other extreme, it is possible to allow
-the instruction to move anywhere within its extended basic block,
-provided that all the new uses and definitions can be performed
-at the new location. The way to do this is:
-
-@smallexample
-change.move_range = insn->ebb ()->insn_range ();
-@end smallexample
-
-In either case, the next step is to make sure that move range is
-consistent with the new uses and definitions. The way to do this is:
-
-@smallexample
-if (!rtl_ssa::restrict_movement (change))
- return false;
-@end smallexample
-
-This function tries to limit @code{move_range} to a range of instructions
-at which @code{new_uses} and @code{new_defs} can be correctly performed.
-It returns true on success or false if no suitable location exists.
-
-The pass should also tentatively change the pattern of the instruction
-to whatever form the pass wants the instruction to have. This should use
-the facilities provided by @file{recog.cc}. For example:
-
-@smallexample
-rtl_insn *rtl = insn->rtl ();
-insn_change_watermark watermark;
-validate_change (rtl, &PATTERN (rtl), new_pat, 1);
-@end smallexample
-
-will tentatively replace @code{insn}'s pattern with @code{new_pat}.
-
-These changes and the construction of the @code{rtl_ssa::insn_change}
-can happen in either order or be interleaved.
-
-After the tentative changes to the instruction are complete,
-the pass should check whether the new pattern matches a target
-instruction or satisfies the requirements of an inline asm:
-
-@smallexample
-if (!rtl_ssa::recog (change))
- return false;
-@end smallexample
-
-This step might change the instruction pattern further in order to
-make it match. It might also add new definitions or restrict the range
-of the move. For example, if the new pattern did not match in its original
-form, but could be made to match by adding a clobber of the flags
-register, @code{rtl_ssa::recog} will check whether the flags register
-is free at an appropriate point. If so, it will add a clobber of the
-flags register to @code{new_defs} and restrict @code{move_range} to
-the locations at which the flags register can be safely clobbered.
-
-Even if the proposed new instruction is valid according to
-@code{rtl_ssa::recog}, the change might not be worthwhile.
-For example, when optimizing for speed, the new instruction might
-turn out to be slower than the original one. When optimizing for
-size, the new instruction might turn out to be bigger than the
-original one.
-
-Passes should check for this case using @code{change_is_worthwhile}.
-For example:
-
-@smallexample
-if (!rtl_ssa::change_is_worthwhile (change))
- return false;
-@end smallexample
-
-If the change passes this test too then the pass can perform the change using:
-
-@smallexample
-confirm_change_group ();
-crtl->ssa->change_insn (change);
-@end smallexample
-
-Putting all this together, the change has the following form:
-
-@smallexample
-auto attempt = crtl->ssa->new_change_attempt ();
-
-rtl_ssa::insn_change change (insn);
-change.new_defs = @dots{};
-change.new_uses = @dots{};
-change.move_range = @dots{};
-
-if (!rtl_ssa::restrict_movement (change))
- return false;
-
-insn_change_watermark watermark;
-// Use validate_change etc. to change INSN's pattern.
-@dots{}
-if (!rtl_ssa::recog (change)
- || !rtl_ssa::change_is_worthwhile (change))
- return false;
-
-confirm_change_group ();
-crtl->ssa->change_insn (change);
-@end smallexample
-
-@node Changing Multiple RTL SSA Instructions
-@subsubsection Changing Multiple RTL SSA Instructions
-
-The process for changing multiple instructions is similar
-to the process for changing single instructions
-(@pxref{Changing One RTL SSA Instruction}). The pass should
-again start the change attempt with:
-
-@smallexample
-auto attempt = crtl->ssa->new_change_attempt ();
-@end smallexample
-
-and keep @code{attempt} in scope for the duration of the change
-attempt. It should then construct an @code{rtl_ssa::insn_change}
-for each change that it wants to make.
-
-After this, it should combine the changes into a sequence of
-@code{rtl_ssa::insn_change} pointers. This sequence must be in
-reverse postorder; the instructions will remain strictly in the
-order that the sequence specifies.
-
-For example, if a pass is changing exactly two instructions,
-it might do:
-
-@smallexample
-rtl_ssa::insn_change *changes[] = @{ &change1, change2 @};
-@end smallexample
-
-where @code{change1}'s instruction must come before @code{change2}'s.
-Alternatively, if the pass is changing a variable number of
-instructions, it might build up the sequence in a
-@code{vec<rtl_ssa::insn_change *>}.
-
-By default, @code{rtl_ssa::restrict_movement} assumes that all
-instructions other than the one passed to it will remain in their
-current positions and will retain their current uses and definitions.
-When changing multiple instructions, it is usually more effective
-to ignore the other instructions that are changing. The sequencing
-described above ensures that the changing instructions remain
-in the correct order with respect to each other.
-The way to do this is:
-
-@smallexample
-if (!rtl_ssa::restrict_movement (change, insn_is_changing (changes)))
- return false;
-@end smallexample
-
-Similarly, when @code{rtl_ssa::restrict_movement} is detecting
-whether a register can be clobbered, it by default assumes that
-all other instructions will remain in their current positions and
-retain their current form. It is again more effective to ignore
-changing instructions (which might, for example, no longer need
-to clobber the flags register). The way to do this is:
-
-@smallexample
-if (!rtl_ssa::recog (change, insn_is_changing (changes)))
- return false;
-@end smallexample
-
-When changing multiple instructions, the important question is usually
-not whether each individual change is worthwhile, but whether the changes
-as a whole are worthwhile. The way to test this is:
-
-@smallexample
-if (!rtl_ssa::changes_are_worthwhile (changes))
- return false;
-@end smallexample
-
-The process for changing single instructions makes sure that one
-@code{rtl_ssa::insn_change} in isolation is valid. But when changing
-multiple instructions, it is also necessary to test whether the
-sequence as a whole is valid. For example, it might be impossible
-to satisfy all of the @code{move_range}s at once.
-
-Therefore, once the pass has a sequence of changes that are
-individually correct, it should use:
-
-@smallexample
-if (!crtl->ssa->verify_insn_changes (changes))
- return false;
-@end smallexample
-
-to check whether the sequence as a whole is valid. If all checks pass,
-the final step is:
-
-@smallexample
-confirm_change_group ();
-crtl->ssa->change_insns (changes);
-@end smallexample
-
-Putting all this together, the process for a two-instruction change is:
-
-@smallexample
-auto attempt = crtl->ssa->new_change_attempt ();
-
-rtl_ssa::insn_change change (insn1);
-change1.new_defs = @dots{};
-change1.new_uses = @dots{};
-change1.move_range = @dots{};
-
-rtl_ssa::insn_change change (insn2);
-change2.new_defs = @dots{};
-change2.new_uses = @dots{};
-change2.move_range = @dots{};
-
-rtl_ssa::insn_change *changes[] = @{ &change1, change2 @};
-
-auto is_changing = insn_is_changing (changes);
-if (!rtl_ssa::restrict_movement (change1, is_changing)
- || !rtl_ssa::restrict_movement (change2, is_changing))
- return false;
-
-insn_change_watermark watermark;
-// Use validate_change etc. to change INSN1's and INSN2's patterns.
-@dots{}
-if (!rtl_ssa::recog (change1, is_changing)
- || !rtl_ssa::recog (change2, is_changing)
- || !rtl_ssa::changes_are_worthwhile (changes)
- || !crtl->ssa->verify_insn_changes (changes))
- return false;
-
-confirm_change_group ();
-crtl->ssa->change_insns (changes);
-@end smallexample
-
-@node Sharing
-@section Structure Sharing Assumptions
-@cindex sharing of RTL components
-@cindex RTL structure sharing assumptions
-
-The compiler assumes that certain kinds of RTL expressions are unique;
-there do not exist two distinct objects representing the same value.
-In other cases, it makes an opposite assumption: that no RTL expression
-object of a certain kind appears in more than one place in the
-containing structure.
-
-These assumptions refer to a single function; except for the RTL
-objects that describe global variables and external functions,
-and a few standard objects such as small integer constants,
-no RTL objects are common to two functions.
-
-@itemize @bullet
-@cindex @code{reg}, RTL sharing
-@item
-Each pseudo-register has only a single @code{reg} object to represent it,
-and therefore only a single machine mode.
-
-@cindex symbolic label
-@cindex @code{symbol_ref}, RTL sharing
-@item
-For any symbolic label, there is only one @code{symbol_ref} object
-referring to it.
-
-@cindex @code{const_int}, RTL sharing
-@item
-All @code{const_int} expressions with equal values are shared.
-
-@cindex @code{const_poly_int}, RTL sharing
-@item
-All @code{const_poly_int} expressions with equal modes and values
-are shared.
-
-@cindex @code{pc}, RTL sharing
-@item
-There is only one @code{pc} expression.
-
-@cindex @code{const_double}, RTL sharing
-@item
-There is only one @code{const_double} expression with value 0 for
-each floating point mode. Likewise for values 1 and 2.
-
-@cindex @code{const_vector}, RTL sharing
-@item
-There is only one @code{const_vector} expression with value 0 for
-each vector mode, be it an integer or a double constant vector.
-
-@cindex @code{label_ref}, RTL sharing
-@cindex @code{scratch}, RTL sharing
-@item
-No @code{label_ref} or @code{scratch} appears in more than one place in
-the RTL structure; in other words, it is safe to do a tree-walk of all
-the insns in the function and assume that each time a @code{label_ref}
-or @code{scratch} is seen it is distinct from all others that are seen.
-
-@cindex @code{mem}, RTL sharing
-@item
-Only one @code{mem} object is normally created for each static
-variable or stack slot, so these objects are frequently shared in all
-the places they appear. However, separate but equal objects for these
-variables are occasionally made.
-
-@cindex @code{asm_operands}, RTL sharing
-@item
-When a single @code{asm} statement has multiple output operands, a
-distinct @code{asm_operands} expression is made for each output operand.
-However, these all share the vector which contains the sequence of input
-operands. This sharing is used later on to test whether two
-@code{asm_operands} expressions come from the same statement, so all
-optimizations must carefully preserve the sharing if they copy the
-vector at all.
-
-@item
-No RTL object appears in more than one place in the RTL structure
-except as described above. Many passes of the compiler rely on this
-by assuming that they can modify RTL objects in place without unwanted
-side-effects on other insns.
-
-@findex unshare_all_rtl
-@item
-During initial RTL generation, shared structure is freely introduced.
-After all the RTL for a function has been generated, all shared
-structure is copied by @code{unshare_all_rtl} in @file{emit-rtl.cc},
-after which the above rules are guaranteed to be followed.
-
-@findex copy_rtx_if_shared
-@item
-During the combiner pass, shared structure within an insn can exist
-temporarily. However, the shared structure is copied before the
-combiner is finished with the insn. This is done by calling
-@code{copy_rtx_if_shared}, which is a subroutine of
-@code{unshare_all_rtl}.
-@end itemize
-
-@node Reading RTL
-@section Reading RTL
-
-To read an RTL object from a file, call @code{read_rtx}. It takes one
-argument, a stdio stream, and returns a single RTL object. This routine
-is defined in @file{read-rtl.cc}. It is not available in the compiler
-itself, only the various programs that generate the compiler back end
-from the machine description.
-
-People frequently have the idea of using RTL stored as text in a file as
-an interface between a language front end and the bulk of GCC@. This
-idea is not feasible.
-
-GCC was designed to use RTL internally only. Correct RTL for a given
-program is very dependent on the particular target machine. And the RTL
-does not contain all the information about the program.
-
-The proper way to interface GCC to a new language front end is with
-the ``tree'' data structure, described in the files @file{tree.h} and
-@file{tree.def}. The documentation for this structure (@pxref{GENERIC})
-is incomplete.
+++ /dev/null
-@c Copyright (C) 1988-2022 Free Software Foundation, Inc.
-@c This is part of the GCC manual.
-@c For copying conditions, see the file gcc.texi.
-
-@node Service
-@chapter How To Get Help with GCC
-
-If you need help installing, using or changing GCC, there are two
-ways to find it:
-
-@itemize @bullet
-@item
-Send a message to a suitable network mailing list. First try
-@email{gcc-help@@gcc.gnu.org} (for help installing or using GCC), and if
-that brings no response, try @email{gcc@@gcc.gnu.org}. For help
-changing GCC, ask @email{gcc@@gcc.gnu.org}. If you think you have found
-a bug in GCC, please report it following the instructions at
-@pxref{Bug Reporting}.
-
-@item
-Look in the service directory for someone who might help you for a fee.
-The service directory is found at
-@uref{https://www.fsf.org/resources/service}.
-@end itemize
-
-For further information, see
-@uref{https://gcc.gnu.org/faq.html#support}.
+++ /dev/null
-@c Copyright (C) 2002-2022 Free Software Foundation, Inc.
-@c This is part of the GCC manual.
-@c For copying conditions, see the file gcc.texi.
-
-@node Source Tree
-@chapter Source Tree Structure and Build System
-
-This chapter describes the structure of the GCC source tree, and how
-GCC is built. The user documentation for building and installing GCC
-is in a separate manual (@uref{https://gcc.gnu.org/install/}), with
-which it is presumed that you are familiar.
-
-@menu
-* Configure Terms:: Configuration terminology and history.
-* Top Level:: The top level source directory.
-* gcc Directory:: The @file{gcc} subdirectory.
-@end menu
-
-@include configterms.texi
-
-@node Top Level
-@section Top Level Source Directory
-
-The top level source directory in a GCC distribution contains several
-files and directories that are shared with other software
-distributions such as that of GNU Binutils. It also contains several
-subdirectories that contain parts of GCC and its runtime libraries:
-
-@table @file
-@item c++tools
-Contains the sources for the g++-mapper-server, a tool used with
-C++ modules.
-
-@item config
-Autoconf macros and Makefile fragments used throughout the tree.
-
-@item contrib
-Contributed scripts that may be found useful in conjunction with GCC@.
-One of these, @file{contrib/texi2pod.pl}, is used to generate man
-pages from Texinfo manuals as part of the GCC build process.
-
-@item fixincludes
-The support for fixing system headers to work with GCC@. See
-@file{fixincludes/README} for more information. The headers fixed by
-this mechanism are installed in @file{@var{libsubdir}/include-fixed}.
-Along with those headers, @file{README-fixinc} is also installed, as
-@file{@var{libsubdir}/include-fixed/README}.
-
-@item gcc
-The main sources of GCC itself (except for runtime libraries),
-including optimizers, support for different target architectures,
-language front ends, and testsuites. @xref{gcc Directory, , The
-@file{gcc} Subdirectory}, for details.
-
-@item gnattools
-Support tools for GNAT.
-
-@item gotools
-Support tools for Go.
-
-@item include
-Headers for the @code{libiberty} library.
-
-@item intl
-GNU @code{libintl}, from GNU @code{gettext}, for systems which do not
-include it in @code{libc}.
-
-@item libada
-The Ada runtime library.
-
-@item libatomic
-The runtime support library for atomic operations (e.g.@: for @code{__sync}
-and @code{__atomic}).
-
-@item libbacktrace
-A library that allows gcc to produce backtraces when it crashes.
-
-@item libcc1
-A library that allows gdb to make use of the compiler.
-
-@item libcody
-A compiler dynamism library to allow communication between compilers and
-build systems, for purposes such as C++ modules.
-
-@item libcpp
-The C preprocessor library.
-
-@item libdecnumber
-The Decimal Float support library.
-
-@item libffi
-The @code{libffi} library, used as part of the Go runtime library.
-
-@item libgcc
-The GCC runtime library.
-
-@item libgfortran
-The Fortran runtime library.
-
-@item libgo
-The Go runtime library. The bulk of this library is mirrored from the
-@uref{https://github.com/@/golang/go, master Go repository}.
-
-@item libgomp
-The GNU Offloading and Multi Processing Runtime Library.
-
-@item libiberty
-The @code{libiberty} library, used for portability and for some
-generally useful data structures and algorithms. @xref{Top, ,
-Introduction, libiberty, @sc{gnu} libiberty}, for more information
-about this library.
-
-@item libitm
-The runtime support library for transactional memory.
-
-@item libobjc
-The Objective-C and Objective-C++ runtime library.
-
-@item libphobos
-The D standard and runtime library. The bulk of this library is mirrored
-from the @uref{https://github.com/@/dlang, master D repositories}.
-
-@item libquadmath
-The runtime support library for quad-precision math operations.
-
-@item libsanitizer
-Libraries for various sanitizers. The bulk of this directory is mirrored
-from the @uref{https://github.com/google/sanitizers, Google sanitizers
-repositories}.
-
-@item libssp
-The Stack protector runtime library.
-
-@item libstdc++-v3
-The C++ runtime library.
-
-@item libvtv
-The vtable verification library.
-
-@item lto-plugin
-Plugin used by the linker if link-time optimizations are enabled.
-
-@item maintainer-scripts
-Scripts used by the @code{gccadmin} account on @code{gcc.gnu.org}.
-
-@item zlib
-The @code{zlib} compression library, used for compressing and
-uncompressing GCC's intermediate language in LTO object files.
-@end table
-
-The build system in the top level directory, including how recursion
-into subdirectories works and how building runtime libraries for
-multilibs is handled, is documented in a separate manual, included
-with GNU Binutils. @xref{Top, , GNU configure and build system,
-configure, The GNU configure and build system}, for details.
-
-@node gcc Directory
-@section The @file{gcc} Subdirectory
-
-The @file{gcc} directory contains many files that are part of the C
-sources of GCC, other files used as part of the configuration and
-build process, and subdirectories including documentation and a
-testsuite. The files that are sources of GCC are documented in a
-separate chapter. @xref{Passes, , Passes and Files of the Compiler}.
-
-@menu
-* Subdirectories:: Subdirectories of @file{gcc}.
-* Configuration:: The configuration process, and the files it uses.
-* Build:: The build system in the @file{gcc} directory.
-* Makefile:: Targets in @file{gcc/Makefile}.
-* Library Files:: Library source files and headers under @file{gcc/}.
-* Headers:: Headers installed by GCC.
-* Documentation:: Building documentation in GCC.
-* Front End:: Anatomy of a language front end.
-* Back End:: Anatomy of a target back end.
-@end menu
-
-@node Subdirectories
-@subsection Subdirectories of @file{gcc}
-
-The @file{gcc} directory contains the following subdirectories:
-
-@table @file
-@item @var{language}
-Subdirectories for various languages. Directories containing a file
-@file{config-lang.in} are language subdirectories. The contents of
-the subdirectories @file{c} (for C), @file{cp} (for C++),
-@file{objc} (for Objective-C), @file{objcp} (for Objective-C++),
-and @file{lto} (for LTO) are documented in this
-manual (@pxref{Passes, , Passes and Files of the Compiler});
-those for other languages are not. @xref{Front End, ,
-Anatomy of a Language Front End}, for details of the files in these
-directories.
-
-@item common
-Source files shared between the compiler drivers (such as
-@command{gcc}) and the compilers proper (such as @file{cc1}). If an
-architecture defines target hooks shared between those places, it also
-has a subdirectory in @file{common/config}. @xref{Target Structure}.
-
-@item config
-Configuration files for supported architectures and operating
-systems. @xref{Back End, , Anatomy of a Target Back End}, for
-details of the files in this directory.
-
-@item doc
-Texinfo documentation for GCC, together with automatically generated
-man pages and support for converting the installation manual to
-HTML@. @xref{Documentation}.
-
-@item ginclude
-System headers installed by GCC, mainly those required by the C
-standard of freestanding implementations. @xref{Headers, , Headers
-Installed by GCC}, for details of when these and other headers are
-installed.
-
-@item po
-Message catalogs with translations of messages produced by GCC into
-various languages, @file{@var{language}.po}. This directory also
-contains @file{gcc.pot}, the template for these message catalogues,
-@file{exgettext}, a wrapper around @command{gettext} to extract the
-messages from the GCC sources and create @file{gcc.pot}, which is run
-by @samp{make gcc.pot}, and @file{EXCLUDES}, a list of files from
-which messages should not be extracted.
-
-@item testsuite
-The GCC testsuites (except for those for runtime libraries).
-@xref{Testsuites}.
-@end table
-
-@node Configuration
-@subsection Configuration in the @file{gcc} Directory
-
-The @file{gcc} directory is configured with an Autoconf-generated
-script @file{configure}. The @file{configure} script is generated
-from @file{configure.ac} and @file{aclocal.m4}. From the files
-@file{configure.ac} and @file{acconfig.h}, Autoheader generates the
-file @file{config.in}. The file @file{cstamp-h.in} is used as a
-timestamp.
-
-@menu
-* Config Fragments:: Scripts used by @file{configure}.
-* System Config:: The @file{config.build}, @file{config.host}, and
- @file{config.gcc} files.
-* Configuration Files:: Files created by running @file{configure}.
-@end menu
-
-@node Config Fragments
-@subsubsection Scripts Used by @file{configure}
-
-@file{configure} uses some other scripts to help in its work:
-
-@itemize @bullet
-@item The standard GNU @file{config.sub} and @file{config.guess}
-files, kept in the top level directory, are used.
-
-@item The file @file{config.gcc} is used to handle configuration
-specific to the particular target machine. The file
-@file{config.build} is used to handle configuration specific to the
-particular build machine. The file @file{config.host} is used to handle
-configuration specific to the particular host machine. (In general,
-these should only be used for features that cannot reasonably be tested in
-Autoconf feature tests.)
-@xref{System Config, , The @file{config.build}; @file{config.host};
-and @file{config.gcc} Files}, for details of the contents of these files.
-
-@item Each language subdirectory has a file
-@file{@var{language}/config-lang.in} that is used for
-front-end-specific configuration. @xref{Front End Config, , The Front
-End @file{config-lang.in} File}, for details of this file.
-
-@item A helper script @file{configure.frag} is used as part of
-creating the output of @file{configure}.
-@end itemize
-
-@node System Config
-@subsubsection The @file{config.build}; @file{config.host}; and @file{config.gcc} Files
-
-The @file{config.build} file contains specific rules for particular systems
-which GCC is built on. This should be used as rarely as possible, as the
-behavior of the build system can always be detected by autoconf.
-
-The @file{config.host} file contains specific rules for particular systems
-which GCC will run on. This is rarely needed.
-
-The @file{config.gcc} file contains specific rules for particular systems
-which GCC will generate code for. This is usually needed.
-
-Each file has a list of the shell variables it sets, with descriptions, at the
-top of the file.
-
-FIXME: document the contents of these files, and what variables should
-be set to control build, host and target configuration.
-
-@include configfiles.texi
-
-@node Build
-@subsection Build System in the @file{gcc} Directory
-
-FIXME: describe the build system, including what is built in what
-stages. Also list the various source files that are used in the build
-process but aren't source files of GCC itself and so aren't documented
-below (@pxref{Passes}).
-
-@include makefile.texi
-
-@node Library Files
-@subsection Library Source Files and Headers under the @file{gcc} Directory
-
-FIXME: list here, with explanation, all the C source files and headers
-under the @file{gcc} directory that aren't built into the GCC
-executable but rather are part of runtime libraries and object files,
-such as @file{crtstuff.c} and @file{unwind-dw2.c}. @xref{Headers, ,
-Headers Installed by GCC}, for more information about the
-@file{ginclude} directory.
-
-@node Headers
-@subsection Headers Installed by GCC
-
-In general, GCC expects the system C library to provide most of the
-headers to be used with it. However, GCC will fix those headers if
-necessary to make them work with GCC, and will install some headers
-required of freestanding implementations. These headers are installed
-in @file{@var{libsubdir}/include}. Headers for non-C runtime
-libraries are also installed by GCC; these are not documented here.
-(FIXME: document them somewhere.)
-
-Several of the headers GCC installs are in the @file{ginclude}
-directory. These headers, @file{iso646.h},
-@file{stdarg.h}, @file{stdbool.h}, and @file{stddef.h},
-are installed in @file{@var{libsubdir}/include},
-unless the target Makefile fragment (@pxref{Target Fragment})
-overrides this by setting @code{USER_H}.
-
-In addition to these headers and those generated by fixing system
-headers to work with GCC, some other headers may also be installed in
-@file{@var{libsubdir}/include}. @file{config.gcc} may set
-@code{extra_headers}; this specifies additional headers under
-@file{config} to be installed on some systems.
-
-GCC installs its own version of @code{<float.h>}, from @file{ginclude/float.h}.
-This is done to cope with command-line options that change the
-representation of floating point numbers.
-
-GCC also installs its own version of @code{<limits.h>}; this is generated
-from @file{glimits.h}, together with @file{limitx.h} and
-@file{limity.h} if the system also has its own version of
-@code{<limits.h>}. (GCC provides its own header because it is
-required of ISO C freestanding implementations, but needs to include
-the system header from its own header as well because other standards
-such as POSIX specify additional values to be defined in
-@code{<limits.h>}.) The system's @code{<limits.h>} header is used via
-@file{@var{libsubdir}/include/syslimits.h}, which is copied from
-@file{gsyslimits.h} if it does not need fixing to work with GCC; if it
-needs fixing, @file{syslimits.h} is the fixed copy.
-
-GCC can also install @code{<tgmath.h>}. It will do this when
-@file{config.gcc} sets @code{use_gcc_tgmath} to @code{yes}.
-
-@node Documentation
-@subsection Building Documentation
-
-The main GCC documentation is in the form of manuals in Texinfo
-format. These are installed in Info format; DVI versions may be
-generated by @samp{make dvi}, PDF versions by @samp{make pdf}, and
-HTML versions by @samp{make html}. In addition, some man pages are
-generated from the Texinfo manuals, there are some other text files
-with miscellaneous documentation, and runtime libraries have their own
-documentation outside the @file{gcc} directory. FIXME: document the
-documentation for runtime libraries somewhere.
-
-@menu
-* Texinfo Manuals:: GCC manuals in Texinfo format.
-* Man Page Generation:: Generating man pages from Texinfo manuals.
-* Miscellaneous Docs:: Miscellaneous text files with documentation.
-@end menu
-
-@node Texinfo Manuals
-@subsubsection Texinfo Manuals
-
-The manuals for GCC as a whole, and the C and C++ front ends, are in
-files @file{doc/*.texi}. Other front ends have their own manuals in
-files @file{@var{language}/*.texi}. Common files
-@file{doc/include/*.texi} are provided which may be included in
-multiple manuals; the following files are in @file{doc/include}:
-
-@table @file
-@item fdl.texi
-The GNU Free Documentation License.
-@item funding.texi
-The section ``Funding Free Software''.
-@item gcc-common.texi
-Common definitions for manuals.
-@item gpl_v3.texi
-The GNU General Public License.
-@item texinfo.tex
-A copy of @file{texinfo.tex} known to work with the GCC manuals.
-@end table
-
-DVI-formatted manuals are generated by @samp{make dvi}, which uses
-@command{texi2dvi} (via the Makefile macro @code{$(TEXI2DVI)}).
-PDF-formatted manuals are generated by @samp{make pdf}, which uses
-@command{texi2pdf} (via the Makefile macro @code{$(TEXI2PDF)}). HTML
-formatted manuals are generated by @samp{make html}. Info
-manuals are generated by @samp{make info} (which is run as part of
-a bootstrap); this generates the manuals in the source directory,
-using @command{makeinfo} via the Makefile macro @code{$(MAKEINFO)},
-and they are included in release distributions.
-
-Manuals are also provided on the GCC web site, in both HTML and
-PostScript forms. This is done via the script
-@file{maintainer-scripts/update_web_docs_git}. Each manual to be
-provided online must be listed in the definition of @code{MANUALS} in
-that file; a file @file{@var{name}.texi} must only appear once in the
-source tree, and the output manual must have the same name as the
-source file. (However, other Texinfo files, included in manuals but
-not themselves the root files of manuals, may have names that appear
-more than once in the source tree.) The manual file
-@file{@var{name}.texi} should only include other files in its own
-directory or in @file{doc/include}. HTML manuals will be generated by
-@samp{makeinfo --html}, PostScript manuals by @command{texi2dvi}
-and @command{dvips}, and PDF manuals by @command{texi2pdf}.
-All Texinfo files that are parts of manuals must
-be version-controlled, even if they are generated files, for the
-generation of online manuals to work.
-
-The installation manual, @file{doc/install.texi}, is also provided on
-the GCC web site. The HTML version is generated by the script
-@file{doc/install.texi2html}.
-
-@node Man Page Generation
-@subsubsection Man Page Generation
-
-Because of user demand, in addition to full Texinfo manuals, man pages
-are provided which contain extracts from those manuals. These man
-pages are generated from the Texinfo manuals using
-@file{contrib/texi2pod.pl} and @command{pod2man}. (The man page for
-@command{g++}, @file{cp/g++.1}, just contains a @samp{.so} reference
-to @file{gcc.1}, but all the other man pages are generated from
-Texinfo manuals.)
-
-Because many systems may not have the necessary tools installed to
-generate the man pages, they are only generated if the
-@file{configure} script detects that recent enough tools are
-installed, and the Makefiles allow generating man pages to fail
-without aborting the build. Man pages are also included in release
-distributions. They are generated in the source directory.
-
-Magic comments in Texinfo files starting @samp{@@c man} control what
-parts of a Texinfo file go into a man page. Only a subset of Texinfo
-is supported by @file{texi2pod.pl}, and it may be necessary to add
-support for more Texinfo features to this script when generating new
-man pages. To improve the man page output, some special Texinfo
-macros are provided in @file{doc/include/gcc-common.texi} which
-@file{texi2pod.pl} understands:
-
-@table @code
-@item @@gcctabopt
-Use in the form @samp{@@table @@gcctabopt} for tables of options,
-where for printed output the effect of @samp{@@code} is better than
-that of @samp{@@option} but for man page output a different effect is
-wanted.
-@item @@gccoptlist
-Use for summary lists of options in manuals.
-@item @@gol
-Use at the end of each line inside @samp{@@gccoptlist}. This is
-necessary to avoid problems with differences in how the
-@samp{@@gccoptlist} macro is handled by different Texinfo formatters.
-@end table
-
-FIXME: describe the @file{texi2pod.pl} input language and magic
-comments in more detail.
-
-@node Miscellaneous Docs
-@subsubsection Miscellaneous Documentation
-
-In addition to the formal documentation that is installed by GCC,
-there are several other text files in the @file{gcc} subdirectory
-with miscellaneous documentation:
-
-@table @file
-@item ABOUT-GCC-NLS
-Notes on GCC's Native Language Support. FIXME: this should be part of
-this manual rather than a separate file.
-@item ABOUT-NLS
-Notes on the Free Translation Project.
-@item COPYING
-@itemx COPYING3
-The GNU General Public License, Versions 2 and 3.
-@item COPYING.LIB
-@itemx COPYING3.LIB
-The GNU Lesser General Public License, Versions 2.1 and 3.
-@item *ChangeLog*
-@itemx */ChangeLog*
-Change log files for various parts of GCC@.
-@item LANGUAGES
-Details of a few changes to the GCC front-end interface. FIXME: the
-information in this file should be part of general documentation of
-the front-end interface in this manual.
-@item ONEWS
-Information about new features in old versions of GCC@. (For recent
-versions, the information is on the GCC web site.)
-@item README.Portability
-Information about portability issues when writing code in GCC@. FIXME:
-why isn't this part of this manual or of the GCC Coding Conventions?
-@end table
-
-FIXME: document such files in subdirectories, at least @file{config},
-@file{c}, @file{cp}, @file{objc}, @file{testsuite}.
-
-@node Front End
-@subsection Anatomy of a Language Front End
-
-A front end for a language in GCC has the following parts:
-
-@itemize @bullet
-@item
-A directory @file{@var{language}} under @file{gcc} containing source
-files for that front end. @xref{Front End Directory, , The Front End
-@file{@var{language}} Directory}, for details.
-@item
-A mention of the language in the list of supported languages in
-@file{gcc/doc/install.texi}.
-@item
-A mention of the name under which the language's runtime library is
-recognized by @option{--enable-shared=@var{package}} in the
-documentation of that option in @file{gcc/doc/install.texi}.
-@item
-A mention of any special prerequisites for building the front end in
-the documentation of prerequisites in @file{gcc/doc/install.texi}.
-@item
-Details of contributors to that front end in
-@file{gcc/doc/contrib.texi}. If the details are in that front end's
-own manual then there should be a link to that manual's list in
-@file{contrib.texi}.
-@item
-Information about support for that language in
-@file{gcc/doc/frontends.texi}.
-@item
-Information about standards for that language, and the front end's
-support for them, in @file{gcc/doc/standards.texi}. This may be a
-link to such information in the front end's own manual.
-@item
-Details of source file suffixes for that language and @option{-x
-@var{lang}} options supported, in @file{gcc/doc/invoke.texi}.
-@item
-Entries in @code{default_compilers} in @file{gcc.cc} for source file
-suffixes for that language.
-@item
-Preferably testsuites, which may be under @file{gcc/testsuite} or
-runtime library directories. FIXME: document somewhere how to write
-testsuite harnesses.
-@item
-Probably a runtime library for the language, outside the @file{gcc}
-directory. FIXME: document this further.
-@item
-Details of the directories of any runtime libraries in
-@file{gcc/doc/sourcebuild.texi}.
-@item
-Check targets in @file{Makefile.def} for the top-level @file{Makefile}
-to check just the compiler or the compiler and runtime library for the
-language.
-@end itemize
-
-If the front end is added to the official GCC source repository, the
-following are also necessary:
-
-@itemize @bullet
-@item
-At least one Bugzilla component for bugs in that front end and runtime
-libraries. This category needs to be added to the Bugzilla database.
-@item
-Normally, one or more maintainers of that front end listed in
-@file{MAINTAINERS}.
-@item
-Mentions on the GCC web site in @file{index.html} and
-@file{frontends.html}, with any relevant links on
-@file{readings.html}. (Front ends that are not an official part of
-GCC may also be listed on @file{frontends.html}, with relevant links.)
-@item
-A news item on @file{index.html}, and possibly an announcement on the
-@email{gcc-announce@@gcc.gnu.org} mailing list.
-@item
-The front end's manuals should be mentioned in
-@file{maintainer-scripts/update_web_docs_git} (@pxref{Texinfo Manuals})
-and the online manuals should be linked to from
-@file{onlinedocs/index.html}.
-@item
-Any old releases or CVS repositories of the front end, before its
-inclusion in GCC, should be made available on the GCC web site at
-@uref{https://gcc.gnu.org/pub/gcc/old-releases/}.
-@item
-The release and snapshot script @file{maintainer-scripts/gcc_release}
-should be updated to generate appropriate tarballs for this front end.
-@item
-If this front end includes its own version files that include the
-current date, @file{maintainer-scripts/update_version} should be
-updated accordingly.
-@end itemize
-
-@menu
-* Front End Directory:: The front end @file{@var{language}} directory.
-* Front End Config:: The front end @file{config-lang.in} file.
-* Front End Makefile:: The front end @file{Make-lang.in} file.
-@end menu
-
-@node Front End Directory
-@subsubsection The Front End @file{@var{language}} Directory
-
-A front end @file{@var{language}} directory contains the source files
-of that front end (but not of any runtime libraries, which should be
-outside the @file{gcc} directory). This includes documentation, and
-possibly some subsidiary programs built alongside the front end.
-Certain files are special and other parts of the compiler depend on
-their names:
-
-@table @file
-@item config-lang.in
-This file is required in all language subdirectories. @xref{Front End
-Config, , The Front End @file{config-lang.in} File}, for details of
-its contents
-@item Make-lang.in
-This file is required in all language subdirectories. @xref{Front End
-Makefile, , The Front End @file{Make-lang.in} File}, for details of its
-contents.
-@item lang.opt
-This file registers the set of switches that the front end accepts on
-the command line, and their @option{--help} text. @xref{Options}.
-@item lang-specs.h
-This file provides entries for @code{default_compilers} in
-@file{gcc.cc} which override the default of giving an error that a
-compiler for that language is not installed.
-@item @var{language}-tree.def
-This file, which need not exist, defines any language-specific tree
-codes.
-@end table
-
-@node Front End Config
-@subsubsection The Front End @file{config-lang.in} File
-
-Each language subdirectory contains a @file{config-lang.in} file.
-This file is a shell script that may define some variables describing
-the language:
-
-@table @code
-@item language
-This definition must be present, and gives the name of the language
-for some purposes such as arguments to @option{--enable-languages}.
-@item lang_requires
-If defined, this variable lists (space-separated) language front ends
-other than C that this front end requires to be enabled (with the
-names given being their @code{language} settings). For example, the
-Obj-C++ front end depends on the C++ and ObjC front ends, so sets
-@samp{lang_requires="objc c++"}.
-@item subdir_requires
-If defined, this variable lists (space-separated) front end directories
-other than C that this front end requires to be present. For example,
-the Objective-C++ front end uses source files from the C++ and
-Objective-C front ends, so sets @samp{subdir_requires="cp objc"}.
-@item target_libs
-If defined, this variable lists (space-separated) targets in the top
-level @file{Makefile} to build the runtime libraries for this
-language, such as @code{target-libobjc}.
-@item lang_dirs
-If defined, this variable lists (space-separated) top level
-directories (parallel to @file{gcc}), apart from the runtime libraries,
-that should not be configured if this front end is not built.
-@item build_by_default
-If defined to @samp{no}, this language front end is not built unless
-enabled in a @option{--enable-languages} argument. Otherwise, front
-ends are built by default, subject to any special logic in
-@file{configure.ac} (as is present to disable the Ada front end if the
-Ada compiler is not already installed).
-@item boot_language
-If defined to @samp{yes}, this front end is built in stage1 of the
-bootstrap. This is only relevant to front ends written in their own
-languages.
-@item compilers
-If defined, a space-separated list of compiler executables that will
-be run by the driver. The names here will each end
-with @samp{\$(exeext)}.
-@item outputs
-If defined, a space-separated list of files that should be generated
-by @file{configure} substituting values in them. This mechanism can
-be used to create a file @file{@var{language}/Makefile} from
-@file{@var{language}/Makefile.in}, but this is deprecated, building
-everything from the single @file{gcc/Makefile} is preferred.
-@item gtfiles
-If defined, a space-separated list of files that should be scanned by
-@file{gengtype.cc} to generate the garbage collection tables and routines for
-this language. This excludes the files that are common to all front
-ends. @xref{Type Information}.
-
-@end table
-
-@node Front End Makefile
-@subsubsection The Front End @file{Make-lang.in} File
-
-Each language subdirectory contains a @file{Make-lang.in} file. It contains
-targets @code{@var{lang}.@var{hook}} (where @code{@var{lang}} is the
-setting of @code{language} in @file{config-lang.in}) for the following
-values of @code{@var{hook}}, and any other Makefile rules required to
-build those targets (which may if necessary use other Makefiles
-specified in @code{outputs} in @file{config-lang.in}, although this is
-deprecated). It also adds any testsuite targets that can use the
-standard rule in @file{gcc/Makefile.in} to the variable
-@code{lang_checks}.
-
-@table @code
-@item all.cross
-@itemx start.encap
-@itemx rest.encap
-FIXME: exactly what goes in each of these targets?
-@item tags
-Build an @command{etags} @file{TAGS} file in the language subdirectory
-in the source tree.
-@item info
-Build info documentation for the front end, in the build directory.
-This target is only called by @samp{make bootstrap} if a suitable
-version of @command{makeinfo} is available, so does not need to check
-for this, and should fail if an error occurs.
-@item dvi
-Build DVI documentation for the front end, in the build directory.
-This should be done using @code{$(TEXI2DVI)}, with appropriate
-@option{-I} arguments pointing to directories of included files.
-@item pdf
-Build PDF documentation for the front end, in the build directory.
-This should be done using @code{$(TEXI2PDF)}, with appropriate
-@option{-I} arguments pointing to directories of included files.
-@item html
-Build HTML documentation for the front end, in the build directory.
-@item man
-Build generated man pages for the front end from Texinfo manuals
-(@pxref{Man Page Generation}), in the build directory. This target
-is only called if the necessary tools are available, but should ignore
-errors so as not to stop the build if errors occur; man pages are
-optional and the tools involved may be installed in a broken way.
-@item install-common
-Install everything that is part of the front end, apart from the
-compiler executables listed in @code{compilers} in
-@file{config-lang.in}.
-@item install-info
-Install info documentation for the front end, if it is present in the
-source directory. This target should have dependencies on info files
-that should be installed.
-@item install-man
-Install man pages for the front end. This target should ignore
-errors.
-@item install-plugin
-Install headers needed for plugins.
-@item srcextra
-Copies its dependencies into the source directory. This generally should
-be used for generated files such as Bison output files which are not
-version-controlled, but should be included in any release tarballs. This
-target will be executed during a bootstrap if
-@samp{--enable-generated-files-in-srcdir} was specified as a
-@file{configure} option.
-@item srcinfo
-@itemx srcman
-Copies its dependencies into the source directory. These targets will be
-executed during a bootstrap if @samp{--enable-generated-files-in-srcdir}
-was specified as a @file{configure} option.
-@item uninstall
-Uninstall files installed by installing the compiler. This is
-currently documented not to be supported, so the hook need not do
-anything.
-@item mostlyclean
-@itemx clean
-@itemx distclean
-@itemx maintainer-clean
-The language parts of the standard GNU
-@samp{*clean} targets. @xref{Standard Targets, , Standard Targets for
-Users, standards, GNU Coding Standards}, for details of the standard
-targets. For GCC, @code{maintainer-clean} should delete
-all generated files in the source directory that are not version-controlled,
-but should not delete anything that is.
-@end table
-
-@file{Make-lang.in} must also define a variable @code{@var{lang}_OBJS}
-to a list of host object files that are used by that language.
-
-@node Back End
-@subsection Anatomy of a Target Back End
-
-A back end for a target architecture in GCC has the following parts:
-
-@itemize @bullet
-@item
-A directory @file{@var{machine}} under @file{gcc/config}, containing a
-machine description @file{@var{machine}.md} file (@pxref{Machine Desc,
-, Machine Descriptions}), header files @file{@var{machine}.h} and
-@file{@var{machine}-protos.h} and a source file @file{@var{machine}.c}
-(@pxref{Target Macros, , Target Description Macros and Functions}),
-possibly a target Makefile fragment @file{t-@var{machine}}
-(@pxref{Target Fragment, , The Target Makefile Fragment}), and maybe
-some other files. The names of these files may be changed from the
-defaults given by explicit specifications in @file{config.gcc}.
-@item
-If necessary, a file @file{@var{machine}-modes.def} in the
-@file{@var{machine}} directory, containing additional machine modes to
-represent condition codes. @xref{Condition Code}, for further details.
-@item
-An optional @file{@var{machine}.opt} file in the @file{@var{machine}}
-directory, containing a list of target-specific options. You can also
-add other option files using the @code{extra_options} variable in
-@file{config.gcc}. @xref{Options}.
-@item
-Entries in @file{config.gcc} (@pxref{System Config, , The
-@file{config.gcc} File}) for the systems with this target
-architecture.
-@item
-Documentation in @file{gcc/doc/invoke.texi} for any command-line
-options supported by this target (@pxref{Run-time Target, , Run-time
-Target Specification}). This means both entries in the summary table
-of options and details of the individual options.
-@item
-Documentation in @file{gcc/doc/extend.texi} for any target-specific
-attributes supported (@pxref{Target Attributes, , Defining
-target-specific uses of @code{__attribute__}}), including where the
-same attribute is already supported on some targets, which are
-enumerated in the manual.
-@item
-Documentation in @file{gcc/doc/extend.texi} for any target-specific
-pragmas supported.
-@item
-Documentation in @file{gcc/doc/extend.texi} of any target-specific
-built-in functions supported.
-@item
-Documentation in @file{gcc/doc/extend.texi} of any target-specific
-format checking styles supported.
-@item
-Documentation in @file{gcc/doc/md.texi} of any target-specific
-constraint letters (@pxref{Machine Constraints, , Constraints for
-Particular Machines}).
-@item
-A note in @file{gcc/doc/contrib.texi} under the person or people who
-contributed the target support.
-@item
-Entries in @file{gcc/doc/install.texi} for all target triplets
-supported with this target architecture, giving details of any special
-notes about installation for this target, or saying that there are no
-special notes if there are none.
-@item
-Possibly other support outside the @file{gcc} directory for runtime
-libraries. FIXME: reference docs for this. The @code{libstdc++} porting
-manual needs to be installed as info for this to work, or to be a
-chapter of this manual.
-@end itemize
-
-The @file{@var{machine}.h} header is included very early in GCC's
-standard sequence of header files, while @file{@var{machine}-protos.h}
-is included late in the sequence. Thus @file{@var{machine}-protos.h}
-can include declarations referencing types that are not defined when
-@file{@var{machine}.h} is included, specifically including those from
-@file{rtl.h} and @file{tree.h}. Since both RTL and tree types may not
-be available in every context where @file{@var{machine}-protos.h} is
-included, in this file you should guard declarations using these types
-inside appropriate @code{#ifdef RTX_CODE} or @code{#ifdef TREE_CODE}
-conditional code segments.
-
-If the backend uses shared data structures that require @code{GTY} markers
-for garbage collection (@pxref{Type Information}), you must declare those
-in @file{@var{machine}.h} rather than @file{@var{machine}-protos.h}.
-Any definitions required for building libgcc must also go in
-@file{@var{machine}.h}.
-
-GCC uses the macro @code{IN_TARGET_CODE} to distinguish between
-machine-specific @file{.c} and @file{.cc} files and
-machine-independent @file{.c} and @file{.cc} files. Machine-specific
-files should use the directive:
-
-@example
-#define IN_TARGET_CODE 1
-@end example
-
-before including @code{config.h}.
-
-If the back end is added to the official GCC source repository, the
-following are also necessary:
-
-@itemize @bullet
-@item
-An entry for the target architecture in @file{readings.html} on the
-GCC web site, with any relevant links.
-@item
-Details of the properties of the back end and target architecture in
-@file{backends.html} on the GCC web site.
-@item
-A news item about the contribution of support for that target
-architecture, in @file{index.html} on the GCC web site.
-@item
-Normally, one or more maintainers of that target listed in
-@file{MAINTAINERS}. Some existing architectures may be unmaintained,
-but it would be unusual to add support for a target that does not have
-a maintainer when support is added.
-@item
-Target triplets covering all @file{config.gcc} stanzas for the target,
-in the list in @file{contrib/config-list.mk}.
-@end itemize
-
-@node Testsuites
-@chapter Testsuites
-
-GCC contains several testsuites to help maintain compiler quality.
-Most of the runtime libraries and language front ends in GCC have
-testsuites. Currently only the C language testsuites are documented
-here; FIXME: document the others.
-
-@menu
-* Test Idioms:: Idioms used in testsuite code.
-* Test Directives:: Directives used within DejaGnu tests.
-* Ada Tests:: The Ada language testsuites.
-* C Tests:: The C language testsuites.
-* LTO Testing:: Support for testing link-time optimizations.
-* gcov Testing:: Support for testing gcov.
-* profopt Testing:: Support for testing profile-directed optimizations.
-* compat Testing:: Support for testing binary compatibility.
-* Torture Tests:: Support for torture testing using multiple options.
-* GIMPLE Tests:: Support for testing GIMPLE passes.
-* RTL Tests:: Support for testing RTL passes.
-@end menu
-
-@node Test Idioms
-@section Idioms Used in Testsuite Code
-
-In general, C testcases have a trailing @file{-@var{n}.c}, starting
-with @file{-1.c}, in case other testcases with similar names are added
-later. If the test is a test of some well-defined feature, it should
-have a name referring to that feature such as
-@file{@var{feature}-1.c}. If it does not test a well-defined feature
-but just happens to exercise a bug somewhere in the compiler, and a
-bug report has been filed for this bug in the GCC bug database,
-@file{pr@var{bug-number}-1.c} is the appropriate form of name.
-Otherwise (for miscellaneous bugs not filed in the GCC bug database),
-and previously more generally, test cases are named after the date on
-which they were added. This allows people to tell at a glance whether
-a test failure is because of a recently found bug that has not yet
-been fixed, or whether it may be a regression, but does not give any
-other information about the bug or where discussion of it may be
-found. Some other language testsuites follow similar conventions.
-
-In the @file{gcc.dg} testsuite, it is often necessary to test that an
-error is indeed a hard error and not just a warning---for example,
-where it is a constraint violation in the C standard, which must
-become an error with @option{-pedantic-errors}. The following idiom,
-where the first line shown is line @var{line} of the file and the line
-that generates the error, is used for this:
-
-@smallexample
-/* @{ dg-bogus "warning" "warning in place of error" @} */
-/* @{ dg-error "@var{regexp}" "@var{message}" @{ target *-*-* @} @var{line} @} */
-@end smallexample
-
-It may be necessary to check that an expression is an integer constant
-expression and has a certain value. To check that @code{@var{E}} has
-value @code{@var{V}}, an idiom similar to the following is used:
-
-@smallexample
-char x[((E) == (V) ? 1 : -1)];
-@end smallexample
-
-In @file{gcc.dg} tests, @code{__typeof__} is sometimes used to make
-assertions about the types of expressions. See, for example,
-@file{gcc.dg/c99-condexpr-1.c}. The more subtle uses depend on the
-exact rules for the types of conditional expressions in the C
-standard; see, for example, @file{gcc.dg/c99-intconst-1.c}.
-
-It is useful to be able to test that optimizations are being made
-properly. This cannot be done in all cases, but it can be done where
-the optimization will lead to code being optimized away (for example,
-where flow analysis or alias analysis should show that certain code
-cannot be called) or to functions not being called because they have
-been expanded as built-in functions. Such tests go in
-@file{gcc.c-torture/execute}. Where code should be optimized away, a
-call to a nonexistent function such as @code{link_failure ()} may be
-inserted; a definition
-
-@smallexample
-#ifndef __OPTIMIZE__
-void
-link_failure (void)
-@{
- abort ();
-@}
-#endif
-@end smallexample
-
-@noindent
-will also be needed so that linking still succeeds when the test is
-run without optimization. When all calls to a built-in function
-should have been optimized and no calls to the non-built-in version of
-the function should remain, that function may be defined as
-@code{static} to call @code{abort ()} (although redeclaring a function
-as static may not work on all targets).
-
-All testcases must be portable. Target-specific testcases must have
-appropriate code to avoid causing failures on unsupported systems;
-unfortunately, the mechanisms for this differ by directory.
-
-FIXME: discuss non-C testsuites here.
-
-@node Test Directives
-@section Directives used within DejaGnu tests
-
-@menu
-* Directives:: Syntax and descriptions of test directives.
-* Selectors:: Selecting targets to which a test applies.
-* Effective-Target Keywords:: Keywords describing target attributes.
-* Add Options:: Features for @code{dg-add-options}
-* Require Support:: Variants of @code{dg-require-@var{support}}
-* Final Actions:: Commands for use in @code{dg-final}
-@end menu
-
-@node Directives
-@subsection Syntax and Descriptions of test directives
-
-Test directives appear within comments in a test source file and begin
-with @code{dg-}. Some of these are defined within DejaGnu and others
-are local to the GCC testsuite.
-
-The order in which test directives appear in a test can be important:
-directives local to GCC sometimes override information used by the
-DejaGnu directives, which know nothing about the GCC directives, so the
-DejaGnu directives must precede GCC directives.
-
-Several test directives include selectors (@pxref{Selectors, , })
-which are usually preceded by the keyword @code{target} or @code{xfail}.
-
-@subsubsection Specify how to build the test
-
-@table @code
-@item @{ dg-do @var{do-what-keyword} [@{ target/xfail @var{selector} @}] @}
-@var{do-what-keyword} specifies how the test is compiled and whether
-it is executed. It is one of:
-
-@table @code
-@item preprocess
-Compile with @option{-E} to run only the preprocessor.
-@item compile
-Compile with @option{-S} to produce an assembly code file.
-@item assemble
-Compile with @option{-c} to produce a relocatable object file.
-@item link
-Compile, assemble, and link to produce an executable file.
-@item run
-Produce and run an executable file, which is expected to return
-an exit code of 0.
-@end table
-
-The default is @code{compile}. That can be overridden for a set of
-tests by redefining @code{dg-do-what-default} within the @code{.exp}
-file for those tests.
-
-If the directive includes the optional @samp{@{ target @var{selector} @}}
-then the test is skipped unless the target system matches the
-@var{selector}.
-
-If @var{do-what-keyword} is @code{run} and the directive includes
-the optional @samp{@{ xfail @var{selector} @}} and the selector is met
-then the test is expected to fail. The @code{xfail} clause is ignored
-for other values of @var{do-what-keyword}; those tests can use
-directive @code{dg-xfail-if}.
-@end table
-
-@subsubsection Specify additional compiler options
-
-@table @code
-@item @{ dg-options @var{options} [@{ target @var{selector} @}] @}
-This DejaGnu directive provides a list of compiler options, to be used
-if the target system matches @var{selector}, that replace the default
-options used for this set of tests.
-
-@item @{ dg-add-options @var{feature} @dots{} @}
-Add any compiler options that are needed to access certain features.
-This directive does nothing on targets that enable the features by
-default, or that don't provide them at all. It must come after
-all @code{dg-options} directives.
-For supported values of @var{feature} see @ref{Add Options, ,}.
-
-@item @{ dg-additional-options @var{options} [@{ target @var{selector} @}] @}
-This directive provides a list of compiler options, to be used
-if the target system matches @var{selector}, that are added to the default
-options used for this set of tests.
-@end table
-
-@subsubsection Modify the test timeout value
-
-The normal timeout limit, in seconds, is found by searching the
-following in order:
-
-@itemize @bullet
-@item the value defined by an earlier @code{dg-timeout} directive in
-the test
-
-@item variable @var{tool_timeout} defined by the set of tests
-
-@item @var{gcc},@var{timeout} set in the target board
-
-@item 300
-@end itemize
-
-@table @code
-@item @{ dg-timeout @var{n} [@{target @var{selector} @}] @}
-Set the time limit for the compilation and for the execution of the test
-to the specified number of seconds.
-
-@item @{ dg-timeout-factor @var{x} [@{ target @var{selector} @}] @}
-Multiply the normal time limit for compilation and execution of the test
-by the specified floating-point factor.
-@end table
-
-@subsubsection Skip a test for some targets
-
-@table @code
-@item @{ dg-skip-if @var{comment} @{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]] @}
-Arguments @var{include-opts} and @var{exclude-opts} are lists in which
-each element is a string of zero or more GCC options.
-Skip the test if all of the following conditions are met:
-@itemize @bullet
-@item the test system is included in @var{selector}
-
-@item for at least one of the option strings in @var{include-opts},
-every option from that string is in the set of options with which
-the test would be compiled; use @samp{"*"} for an @var{include-opts} list
-that matches any options; that is the default if @var{include-opts} is
-not specified
-
-@item for each of the option strings in @var{exclude-opts}, at least one
-option from that string is not in the set of options with which the test
-would be compiled; use @samp{""} for an empty @var{exclude-opts} list;
-that is the default if @var{exclude-opts} is not specified
-@end itemize
-
-For example, to skip a test if option @code{-Os} is present:
-
-@smallexample
-/* @{ dg-skip-if "" @{ *-*-* @} @{ "-Os" @} @{ "" @} @} */
-@end smallexample
-
-To skip a test if both options @code{-O2} and @code{-g} are present:
-
-@smallexample
-/* @{ dg-skip-if "" @{ *-*-* @} @{ "-O2 -g" @} @{ "" @} @} */
-@end smallexample
-
-To skip a test if either @code{-O2} or @code{-O3} is present:
-
-@smallexample
-/* @{ dg-skip-if "" @{ *-*-* @} @{ "-O2" "-O3" @} @{ "" @} @} */
-@end smallexample
-
-To skip a test unless option @code{-Os} is present:
-
-@smallexample
-/* @{ dg-skip-if "" @{ *-*-* @} @{ "*" @} @{ "-Os" @} @} */
-@end smallexample
-
-To skip a test if either @code{-O2} or @code{-O3} is used with @code{-g}
-but not if @code{-fpic} is also present:
-
-@smallexample
-/* @{ dg-skip-if "" @{ *-*-* @} @{ "-O2 -g" "-O3 -g" @} @{ "-fpic" @} @} */
-@end smallexample
-
-@item @{ dg-require-effective-target @var{keyword} [@{ target @var{selector} @}] @}
-Skip the test if the test target, including current multilib flags,
-is not covered by the effective-target keyword.
-If the directive includes the optional @samp{@{ @var{selector} @}}
-then the effective-target test is only performed if the target system
-matches the @var{selector}.
-This directive must appear after any @code{dg-do} directive in the test
-and before any @code{dg-additional-sources} directive.
-@xref{Effective-Target Keywords, , }.
-
-@item @{ dg-require-@var{support} args @}
-Skip the test if the target does not provide the required support.
-These directives must appear after any @code{dg-do} directive in the test
-and before any @code{dg-additional-sources} directive.
-They require at least one argument, which can be an empty string if the
-specific procedure does not examine the argument.
-@xref{Require Support, , }, for a complete list of these directives.
-@end table
-
-@subsubsection Expect a test to fail for some targets
-
-@table @code
-@item @{ dg-xfail-if @var{comment} @{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]] @}
-Expect the test to fail if the conditions (which are the same as for
-@code{dg-skip-if}) are met. This does not affect the execute step.
-
-@item @{ dg-xfail-run-if @var{comment} @{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]] @}
-Expect the execute step of a test to fail if the conditions (which are
-the same as for @code{dg-skip-if}) are met.
-@end table
-
-@subsubsection Expect the compiler to crash
-
-@table @code
-@item @{ dg-ice @var{comment} [@{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]]] @}
-Expect the compiler to crash with an internal compiler error and return
-a nonzero exit status if the conditions (which are the same as for
-@code{dg-skip-if}) are met. Used for tests that test bugs that have not been
-fixed yet.
-@end table
-
-@subsubsection Expect the test executable to fail
-
-@table @code
-@item @{ dg-shouldfail @var{comment} [@{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]]] @}
-Expect the test executable to return a nonzero exit status if the
-conditions (which are the same as for @code{dg-skip-if}) are met.
-@end table
-
-@subsubsection Verify compiler messages
-Where @var{line} is an accepted argument for these commands, a value of @samp{0}
-can be used if there is no line associated with the message.
-
-@table @code
-@item @{ dg-error @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] ]] @}
-This DejaGnu directive appears on a source line that is expected to get
-an error message, or else specifies the source line associated with the
-message. If there is no message for that line or if the text of that
-message is not matched by @var{regexp} then the check fails and
-@var{comment} is included in the @code{FAIL} message. The check does
-not look for the string @samp{error} unless it is part of @var{regexp}.
-
-@item @{ dg-warning @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] ]] @}
-This DejaGnu directive appears on a source line that is expected to get
-a warning message, or else specifies the source line associated with the
-message. If there is no message for that line or if the text of that
-message is not matched by @var{regexp} then the check fails and
-@var{comment} is included in the @code{FAIL} message. The check does
-not look for the string @samp{warning} unless it is part of @var{regexp}.
-
-@item @{ dg-message @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] ]] @}
-The line is expected to get a message other than an error or warning.
-If there is no message for that line or if the text of that message is
-not matched by @var{regexp} then the check fails and @var{comment} is
-included in the @code{FAIL} message.
-
-@item @{ dg-note @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] ]] @}
-The line is expected to get a @samp{note} message.
-If there is no message for that line or if the text of that message is
-not matched by @var{regexp} then the check fails and @var{comment} is
-included in the @code{FAIL} message.
-
-By default, any @emph{excess} @samp{note} messages are pruned, meaning
-their appearance doesn't trigger @emph{excess errors}.
-However, if @samp{dg-note} is used at least once in a testcase,
-they're not pruned and instead must @emph{all} be handled explicitly.
-Thus, if looking for just single instances of messages with
-@samp{note: } prefixes without caring for all of them, use
-@samp{dg-message "note: [@dots{}]"} instead of @samp{dg-note}, or use
-@samp{dg-note} together with @samp{dg-prune-output "note: "}.
-
-@item @{ dg-bogus @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] ]] @}
-This DejaGnu directive appears on a source line that should not get a
-message matching @var{regexp}, or else specifies the source line
-associated with the bogus message. It is usually used with @samp{xfail}
-to indicate that the message is a known problem for a particular set of
-targets.
-
-@item @{ dg-line @var{linenumvar} @}
-This DejaGnu directive sets the variable @var{linenumvar} to the line number of
-the source line. The variable @var{linenumvar} can then be used in subsequent
-@code{dg-error}, @code{dg-warning}, @code{dg-message}, @code{dg-note}
-and @code{dg-bogus}
-directives. For example:
-
-@smallexample
-int a; /* @{ dg-line first_def_a @} */
-float a; /* @{ dg-error "conflicting types of" @} */
-/* @{ dg-message "previous declaration of" "" @{ target *-*-* @} first_def_a @} */
-@end smallexample
-
-@item @{ dg-excess-errors @var{comment} [@{ target/xfail @var{selector} @}] @}
-This DejaGnu directive indicates that the test is expected to fail due
-to compiler messages that are not handled by @samp{dg-error},
-@samp{dg-warning}, @code{dg-message}, @samp{dg-note} or
-@samp{dg-bogus}.
-For this directive @samp{xfail}
-has the same effect as @samp{target}.
-
-@item @{ dg-prune-output @var{regexp} @}
-Prune messages matching @var{regexp} from the test output.
-@end table
-
-@subsubsection Verify output of the test executable
-
-@table @code
-@item @{ dg-output @var{regexp} [@{ target/xfail @var{selector} @}] @}
-This DejaGnu directive compares @var{regexp} to the combined output
-that the test executable writes to @file{stdout} and @file{stderr}.
-@end table
-
-@subsubsection Specify environment variables for a test
-
-@table @code
-@item @{ dg-set-compiler-env-var @var{var_name} "@var{var_value}" @}
-Specify that the environment variable @var{var_name} needs to be set
-to @var{var_value} before invoking the compiler on the test file.
-
-@item @{ dg-set-target-env-var @var{var_name} "@var{var_value}" @}
-Specify that the environment variable @var{var_name} needs to be set
-to @var{var_value} before execution of the program created by the test.
-@end table
-
-@subsubsection Specify additional files for a test
-
-@table @code
-@item @{ dg-additional-files "@var{filelist}" @}
-Specify additional files, other than source files, that must be copied
-to the system where the compiler runs.
-
-@item @{ dg-additional-sources "@var{filelist}" @}
-Specify additional source files to appear in the compile line
-following the main test file.
-@end table
-
-@subsubsection Add checks at the end of a test
-
-@table @code
-@item @{ dg-final @{ @var{local-directive} @} @}
-This DejaGnu directive is placed within a comment anywhere in the
-source file and is processed after the test has been compiled and run.
-Multiple @samp{dg-final} commands are processed in the order in which
-they appear in the source file. @xref{Final Actions, , }, for a list
-of directives that can be used within @code{dg-final}.
-@end table
-
-@node Selectors
-@subsection Selecting targets to which a test applies
-
-Several test directives include @var{selector}s to limit the targets
-for which a test is run or to declare that a test is expected to fail
-on particular targets.
-
-A selector is:
-@itemize @bullet
-@item one or more target triplets, possibly including wildcard characters;
-use @samp{*-*-*} to match any target
-@item a single effective-target keyword (@pxref{Effective-Target Keywords})
-@item a list of compiler options that should be included or excluded
-(as described in more detail below)
-@item a logical expression
-@end itemize
-
-Depending on the context, the selector specifies whether a test is
-skipped and reported as unsupported or is expected to fail. A context
-that allows either @samp{target} or @samp{xfail} also allows
-@samp{@{ target @var{selector1} xfail @var{selector2} @}}
-to skip the test for targets that don't match @var{selector1} and the
-test to fail for targets that match @var{selector2}.
-
-A selector expression appears within curly braces and uses a single
-logical operator: one of @samp{!}, @samp{&&}, or @samp{||}. An
-operand is one of the following:
-
-@itemize @bullet
-@item
-another selector expression, in curly braces
-
-@item
-an effective-target keyword, such as @code{lp64}
-
-@item
-a single target triplet
-
-@item
-a list of target triplets within quotes or curly braces
-
-@item
-one of the following:
-
-@table @samp
-@item @{ any-opts @var{opt1} @dots{} @var{optn} @}
-Each of @var{opt1} to @var{optn} is a space-separated list of option globs.
-The selector expression evaluates to true if, for one of these strings,
-every glob in the string matches an option that was passed to the compiler.
-For example:
-
-@smallexample
-@{ any-opts "-O3 -flto" "-O[2g]" @}
-@end smallexample
-
-is true if any of the following are true:
-
-@itemize @bullet
-@item
-@option{-O2} was passed to the compiler
-
-@item
-@option{-Og} was passed to the compiler
-
-@item
-both @option{-O3} and @option{-flto} were passed to the compiler
-@end itemize
-
-This kind of selector can only be used within @code{dg-final} directives.
-Use @code{dg-skip-if}, @code{dg-xfail-if} or @code{dg-xfail-run-if} to
-skip whole tests based on options, or to mark them as expected to fail
-with certain options.
-
-@item @{ no-opts @var{opt1} @dots{} @var{optn} @}
-As for @code{any-opts} above, each of @var{opt1} to @var{optn} is a
-space-separated list of option globs. The selector expression
-evaluates to true if, for all of these strings, there is at least
-one glob that does not match an option that was passed to the compiler.
-It is shorthand for:
-
-@smallexample
-@{ ! @{ any-opts @var{opt1} @dots{} @var{optn} @} @}
-@end smallexample
-
-For example:
-
-@smallexample
-@{ no-opts "-O3 -flto" "-O[2g]" @}
-@end smallexample
-
-is true if all of the following are true:
-
-@itemize @bullet
-@item
-@option{-O2} was not passed to the compiler
-
-@item
-@option{-Og} was not passed to the compiler
-
-@item
-at least one of @option{-O3} or @option{-flto} was not passed to the compiler
-@end itemize
-
-Like @code{any-opts}, this kind of selector can only be used within
-@code{dg-final} directives.
-
-@end table
-@end itemize
-
-Here are some examples of full target selectors:
-
-@smallexample
-@{ target @{ ! "hppa*-*-* ia64*-*-*" @} @}
-@{ target @{ powerpc*-*-* && lp64 @} @}
-@{ xfail @{ lp64 || vect_no_align @} @}
-@{ xfail @{ aarch64*-*-* && @{ any-opts "-O2" @} @} @}
-@end smallexample
-
-@node Effective-Target Keywords
-@subsection Keywords describing target attributes
-
-Effective-target keywords identify sets of targets that support
-particular functionality. They are used to limit tests to be run only
-for particular targets, or to specify that particular sets of targets
-are expected to fail some tests.
-
-Effective-target keywords are defined in @file{lib/target-supports.exp} in
-the GCC testsuite, with the exception of those that are documented as
-being local to a particular test directory.
-
-The @samp{effective target} takes into account all of the compiler options
-with which the test will be compiled, including the multilib options.
-By convention, keywords ending in @code{_nocache} can also include options
-specified for the particular test in an earlier @code{dg-options} or
-@code{dg-add-options} directive.
-
-@subsubsection Endianness
-
-@table @code
-@item be
-Target uses big-endian memory order for multi-byte and multi-word data.
-
-@item le
-Target uses little-endian memory order for multi-byte and multi-word data.
-@end table
-
-@subsubsection Data type sizes
-
-@table @code
-@item ilp32
-Target has 32-bit @code{int}, @code{long}, and pointers.
-
-@item lp64
-Target has 32-bit @code{int}, 64-bit @code{long} and pointers.
-
-@item llp64
-Target has 32-bit @code{int} and @code{long}, 64-bit @code{long long}
-and pointers.
-
-@item double64
-Target has 64-bit @code{double}.
-
-@item double64plus
-Target has @code{double} that is 64 bits or longer.
-
-@item longdouble128
-Target has 128-bit @code{long double}.
-
-@item int32plus
-Target has @code{int} that is at 32 bits or longer.
-
-@item int16
-Target has @code{int} that is 16 bits or shorter.
-
-@item longlong64
-Target has 64-bit @code{long long}.
-
-@item long_neq_int
-Target has @code{int} and @code{long} with different sizes.
-
-@item short_eq_int
-Target has @code{short} and @code{int} with the same size.
-
-@item ptr_eq_short
-Target has pointers (@code{void *}) and @code{short} with the same size.
-
-@item int_eq_float
-Target has @code{int} and @code{float} with the same size.
-
-@item ptr_eq_long
-Target has pointers (@code{void *}) and @code{long} with the same size.
-
-@item large_double
-Target supports @code{double} that is longer than @code{float}.
-
-@item large_long_double
-Target supports @code{long double} that is longer than @code{double}.
-
-@item ptr32plus
-Target has pointers that are 32 bits or longer.
-
-@item size20plus
-Target has a 20-bit or larger address space, so supports at least
-16-bit array and structure sizes.
-
-@item size24plus
-Target has a 24-bit or larger address space, so supports at least
-20-bit array and structure sizes.
-
-@item size32plus
-Target has a 32-bit or larger address space, so supports at least
-24-bit array and structure sizes.
-
-@item 4byte_wchar_t
-Target has @code{wchar_t} that is at least 4 bytes.
-
-@item float@var{n}
-Target has the @code{_Float@var{n}} type.
-
-@item float@var{n}x
-Target has the @code{_Float@var{n}x} type.
-
-@item float@var{n}_runtime
-Target has the @code{_Float@var{n}} type, including runtime support
-for any options added with @code{dg-add-options}.
-
-@item float@var{n}x_runtime
-Target has the @code{_Float@var{n}x} type, including runtime support
-for any options added with @code{dg-add-options}.
-
-@item floatn_nx_runtime
-Target has runtime support for any options added with
-@code{dg-add-options} for any @code{_Float@var{n}} or
-@code{_Float@var{n}x} type.
-
-@item inf
-Target supports floating point infinite (@code{inf}) for type
-@code{double}.
-
-@item inff
-Target supports floating point infinite (@code{inf}) for type
-@code{float}.
-@end table
-@subsubsection Fortran-specific attributes
-
-@table @code
-@item fortran_integer_16
-Target supports Fortran @code{integer} that is 16 bytes or longer.
-
-@item fortran_real_10
-Target supports Fortran @code{real} that is 10 bytes or longer.
-
-@item fortran_real_16
-Target supports Fortran @code{real} that is 16 bytes or longer.
-
-@item fortran_large_int
-Target supports Fortran @code{integer} kinds larger than @code{integer(8)}.
-
-@item fortran_large_real
-Target supports Fortran @code{real} kinds larger than @code{real(8)}.
-@end table
-
-@subsubsection Vector-specific attributes
-
-@table @code
-@item vect_align_stack_vars
-The target's ABI allows stack variables to be aligned to the preferred
-vector alignment.
-
-@item vect_avg_qi
-Target supports both signed and unsigned averaging operations on vectors
-of bytes.
-
-@item vect_mulhrs_hi
-Target supports both signed and unsigned multiply-high-with-round-and-scale
-operations on vectors of half-words.
-
-@item vect_sdiv_pow2_si
-Target supports signed division by constant power-of-2 operations
-on vectors of 4-byte integers.
-
-@item vect_condition
-Target supports vector conditional operations.
-
-@item vect_cond_mixed
-Target supports vector conditional operations where comparison operands
-have different type from the value operands.
-
-@item vect_double
-Target supports hardware vectors of @code{double}.
-
-@item vect_double_cond_arith
-Target supports conditional addition, subtraction, multiplication,
-division, minimum and maximum on vectors of @code{double}, via the
-@code{cond_} optabs.
-
-@item vect_element_align_preferred
-The target's preferred vector alignment is the same as the element
-alignment.
-
-@item vect_float
-Target supports hardware vectors of @code{float} when
-@option{-funsafe-math-optimizations} is in effect.
-
-@item vect_float_strict
-Target supports hardware vectors of @code{float} when
-@option{-funsafe-math-optimizations} is not in effect.
-This implies @code{vect_float}.
-
-@item vect_int
-Target supports hardware vectors of @code{int}.
-
-@item vect_long
-Target supports hardware vectors of @code{long}.
-
-@item vect_long_long
-Target supports hardware vectors of @code{long long}.
-
-@item vect_check_ptrs
-Target supports the @code{check_raw_ptrs} and @code{check_war_ptrs}
-optabs on vectors.
-
-@item vect_fully_masked
-Target supports fully-masked (also known as fully-predicated) loops,
-so that vector loops can handle partial as well as full vectors.
-
-@item vect_masked_load
-Target supports vector masked loads.
-
-@item vect_masked_store
-Target supports vector masked stores.
-
-@item vect_gather_load_ifn
-Target supports vector gather loads using internal functions
-(rather than via built-in functions or emulation).
-
-@item vect_scatter_store
-Target supports vector scatter stores.
-
-@item vect_aligned_arrays
-Target aligns arrays to vector alignment boundary.
-
-@item vect_hw_misalign
-Target supports a vector misalign access.
-
-@item vect_no_align
-Target does not support a vector alignment mechanism.
-
-@item vect_peeling_profitable
-Target might require to peel loops for alignment purposes.
-
-@item vect_no_int_min_max
-Target does not support a vector min and max instruction on @code{int}.
-
-@item vect_no_int_add
-Target does not support a vector add instruction on @code{int}.
-
-@item vect_no_bitwise
-Target does not support vector bitwise instructions.
-
-@item vect_bool_cmp
-Target supports comparison of @code{bool} vectors for at least one
-vector length.
-
-@item vect_char_add
-Target supports addition of @code{char} vectors for at least one
-vector length.
-
-@item vect_char_mult
-Target supports @code{vector char} multiplication.
-
-@item vect_short_mult
-Target supports @code{vector short} multiplication.
-
-@item vect_int_mult
-Target supports @code{vector int} multiplication.
-
-@item vect_long_mult
-Target supports 64 bit @code{vector long} multiplication.
-
-@item vect_extract_even_odd
-Target supports vector even/odd element extraction.
-
-@item vect_extract_even_odd_wide
-Target supports vector even/odd element extraction of vectors with elements
-@code{SImode} or larger.
-
-@item vect_interleave
-Target supports vector interleaving.
-
-@item vect_strided
-Target supports vector interleaving and extract even/odd.
-
-@item vect_strided_wide
-Target supports vector interleaving and extract even/odd for wide
-element types.
-
-@item vect_perm
-Target supports vector permutation.
-
-@item vect_perm_byte
-Target supports permutation of vectors with 8-bit elements.
-
-@item vect_perm_short
-Target supports permutation of vectors with 16-bit elements.
-
-@item vect_perm3_byte
-Target supports permutation of vectors with 8-bit elements, and for the
-default vector length it is possible to permute:
-@example
-@{ a0, a1, a2, b0, b1, b2, @dots{} @}
-@end example
-to:
-@example
-@{ a0, a0, a0, b0, b0, b0, @dots{} @}
-@{ a1, a1, a1, b1, b1, b1, @dots{} @}
-@{ a2, a2, a2, b2, b2, b2, @dots{} @}
-@end example
-using only two-vector permutes, regardless of how long the sequence is.
-
-@item vect_perm3_int
-Like @code{vect_perm3_byte}, but for 32-bit elements.
-
-@item vect_perm3_short
-Like @code{vect_perm3_byte}, but for 16-bit elements.
-
-@item vect_shift
-Target supports a hardware vector shift operation.
-
-@item vect_unaligned_possible
-Target prefers vectors to have an alignment greater than element
-alignment, but also allows unaligned vector accesses in some
-circumstances.
-
-@item vect_variable_length
-Target has variable-length vectors.
-
-@item vect64
-Target supports vectors of 64 bits.
-
-@item vect32
-Target supports vectors of 32 bits.
-
-@item vect_widen_sum_hi_to_si
-Target supports a vector widening summation of @code{short} operands
-into @code{int} results, or can promote (unpack) from @code{short}
-to @code{int}.
-
-@item vect_widen_sum_qi_to_hi
-Target supports a vector widening summation of @code{char} operands
-into @code{short} results, or can promote (unpack) from @code{char}
-to @code{short}.
-
-@item vect_widen_sum_qi_to_si
-Target supports a vector widening summation of @code{char} operands
-into @code{int} results.
-
-@item vect_widen_mult_qi_to_hi
-Target supports a vector widening multiplication of @code{char} operands
-into @code{short} results, or can promote (unpack) from @code{char} to
-@code{short} and perform non-widening multiplication of @code{short}.
-
-@item vect_widen_mult_hi_to_si
-Target supports a vector widening multiplication of @code{short} operands
-into @code{int} results, or can promote (unpack) from @code{short} to
-@code{int} and perform non-widening multiplication of @code{int}.
-
-@item vect_widen_mult_si_to_di_pattern
-Target supports a vector widening multiplication of @code{int} operands
-into @code{long} results.
-
-@item vect_sdot_qi
-Target supports a vector dot-product of @code{signed char}.
-
-@item vect_udot_qi
-Target supports a vector dot-product of @code{unsigned char}.
-
-@item vect_usdot_qi
-Target supports a vector dot-product where one operand of the multiply is
-@code{signed char} and the other of @code{unsigned char}.
-
-@item vect_sdot_hi
-Target supports a vector dot-product of @code{signed short}.
-
-@item vect_udot_hi
-Target supports a vector dot-product of @code{unsigned short}.
-
-@item vect_pack_trunc
-Target supports a vector demotion (packing) of @code{short} to @code{char}
-and from @code{int} to @code{short} using modulo arithmetic.
-
-@item vect_unpack
-Target supports a vector promotion (unpacking) of @code{char} to @code{short}
-and from @code{char} to @code{int}.
-
-@item vect_intfloat_cvt
-Target supports conversion from @code{signed int} to @code{float}.
-
-@item vect_uintfloat_cvt
-Target supports conversion from @code{unsigned int} to @code{float}.
-
-@item vect_floatint_cvt
-Target supports conversion from @code{float} to @code{signed int}.
-
-@item vect_floatuint_cvt
-Target supports conversion from @code{float} to @code{unsigned int}.
-
-@item vect_intdouble_cvt
-Target supports conversion from @code{signed int} to @code{double}.
-
-@item vect_doubleint_cvt
-Target supports conversion from @code{double} to @code{signed int}.
-
-@item vect_max_reduc
-Target supports max reduction for vectors.
-
-@item vect_sizes_16B_8B
-Target supports 16- and 8-bytes vectors.
-
-@item vect_sizes_32B_16B
-Target supports 32- and 16-bytes vectors.
-
-@item vect_logical_reduc
-Target supports AND, IOR and XOR reduction on vectors.
-
-@item vect_fold_extract_last
-Target supports the @code{fold_extract_last} optab.
-
-@item vect_len_load_store
-Target supports the @code{len_load} and @code{len_store} optabs.
-
-@item vect_partial_vectors_usage_1
-Target supports loop vectorization with partial vectors and
-@code{vect-partial-vector-usage} is set to 1.
-
-@item vect_partial_vectors_usage_2
-Target supports loop vectorization with partial vectors and
-@code{vect-partial-vector-usage} is set to 2.
-
-@item vect_partial_vectors
-Target supports loop vectorization with partial vectors and
-@code{vect-partial-vector-usage} is nonzero.
-
-@item vect_slp_v2qi_store_align
-Target supports vectorization of 2-byte char stores with 2-byte aligned
-address at plain @option{-O2}.
-
-@item vect_slp_v4qi_store_align
-Target supports vectorization of 4-byte char stores with 4-byte aligned
-address at plain @option{-O2}.
-
-@item vect_slp_v4qi_store_unalign
-Target supports vectorization of 4-byte char stores with unaligned address
-at plain @option{-O2}.
-
-@item struct_4char_block_move
-Target supports block move for 8-byte aligned 4-byte size struct initialization.
-
-@item vect_slp_v4qi_store_unalign_1
-Target supports vectorization of 4-byte char stores with unaligned address
-or store them with constant pool at plain @option{-O2}.
-
-@item struct_8char_block_move
-Target supports block move for 8-byte aligned 8-byte size struct initialization.
-
-@item vect_slp_v8qi_store_unalign_1
-Target supports vectorization of 8-byte char stores with unaligned address
-or store them with constant pool at plain @option{-O2}.
-
-@item struct_16char_block_move
-Target supports block move for 8-byte aligned 16-byte size struct
-initialization.
-
-@item vect_slp_v16qi_store_unalign_1
-Target supports vectorization of 16-byte char stores with unaligned address
-or store them with constant pool at plain @option{-O2}.
-
-@item vect_slp_v2hi_store_align
-Target supports vectorization of 4-byte short stores with 4-byte aligned
-addressat plain @option{-O2}.
-
-@item vect_slp_v2hi_store_unalign
-Target supports vectorization of 4-byte short stores with unaligned address
-at plain @option{-O2}.
-
-@item vect_slp_v4hi_store_unalign
-Target supports vectorization of 8-byte short stores with unaligned address
-at plain @option{-O2}.
-
-@item vect_slp_v2si_store_align
-Target supports vectorization of 8-byte int stores with 8-byte aligned address
-at plain @option{-O2}.
-
-@item vect_slp_v4si_store_unalign
-Target supports vectorization of 16-byte int stores with unaligned address
-at plain @option{-O2}.
-@end table
-
-@subsubsection Thread Local Storage attributes
-
-@table @code
-@item tls
-Target supports thread-local storage.
-
-@item tls_native
-Target supports native (rather than emulated) thread-local storage.
-
-@item tls_runtime
-Test system supports executing TLS executables.
-@end table
-
-@subsubsection Decimal floating point attributes
-
-@table @code
-@item dfp
-Targets supports compiling decimal floating point extension to C.
-
-@item dfp_nocache
-Including the options used to compile this particular test, the
-target supports compiling decimal floating point extension to C.
-
-@item dfprt
-Test system can execute decimal floating point tests.
-
-@item dfprt_nocache
-Including the options used to compile this particular test, the
-test system can execute decimal floating point tests.
-
-@item hard_dfp
-Target generates decimal floating point instructions with current options.
-
-@item dfp_bid
-Target uses the BID format for decimal floating point.
-@end table
-
-@subsubsection ARM-specific attributes
-
-@table @code
-@item arm32
-ARM target generates 32-bit code.
-
-@item arm_little_endian
-ARM target that generates little-endian code.
-
-@item arm_eabi
-ARM target adheres to the ABI for the ARM Architecture.
-
-@item arm_fp_ok
-@anchor{arm_fp_ok}
-ARM target defines @code{__ARM_FP} using @code{-mfloat-abi=softfp} or
-equivalent options. Some multilibs may be incompatible with these
-options.
-
-@item arm_fp_dp_ok
-@anchor{arm_fp_dp_ok}
-ARM target defines @code{__ARM_FP} with double-precision support using
-@code{-mfloat-abi=softfp} or equivalent options. Some multilibs may
-be incompatible with these options.
-
-@item arm_hf_eabi
-ARM target adheres to the VFP and Advanced SIMD Register Arguments
-variant of the ABI for the ARM Architecture (as selected with
-@code{-mfloat-abi=hard}).
-
-@item arm_softfloat
-ARM target uses emulated floating point operations.
-
-@item arm_hard_vfp_ok
-ARM target supports @code{-mfpu=vfp -mfloat-abi=hard}.
-Some multilibs may be incompatible with these options.
-
-@item arm_iwmmxt_ok
-ARM target supports @code{-mcpu=iwmmxt}.
-Some multilibs may be incompatible with this option.
-
-@item arm_neon
-ARM target supports generating NEON instructions.
-
-@item arm_tune_string_ops_prefer_neon
-Test CPU tune supports inlining string operations with NEON instructions.
-
-@item arm_neon_hw
-Test system supports executing NEON instructions.
-
-@item arm_neonv2_hw
-Test system supports executing NEON v2 instructions.
-
-@item arm_neon_ok
-@anchor{arm_neon_ok}
-ARM Target supports @code{-mfpu=neon -mfloat-abi=softfp} or compatible
-options. Some multilibs may be incompatible with these options.
-
-@item arm_neon_ok_no_float_abi
-@anchor{arm_neon_ok_no_float_abi}
-ARM Target supports NEON with @code{-mfpu=neon}, but without any
--mfloat-abi= option. Some multilibs may be incompatible with this
-option.
-
-@item arm_neonv2_ok
-@anchor{arm_neonv2_ok}
-ARM Target supports @code{-mfpu=neon-vfpv4 -mfloat-abi=softfp} or compatible
-options. Some multilibs may be incompatible with these options.
-
-@item arm_fp16_ok
-@anchor{arm_fp16_ok}
-Target supports options to generate VFP half-precision floating-point
-instructions. Some multilibs may be incompatible with these
-options. This test is valid for ARM only.
-
-@item arm_fp16_hw
-Target supports executing VFP half-precision floating-point
-instructions. This test is valid for ARM only.
-
-@item arm_neon_fp16_ok
-@anchor{arm_neon_fp16_ok}
-ARM Target supports @code{-mfpu=neon-fp16 -mfloat-abi=softfp} or compatible
-options, including @code{-mfp16-format=ieee} if necessary to obtain the
-@code{__fp16} type. Some multilibs may be incompatible with these options.
-
-@item arm_neon_fp16_hw
-Test system supports executing Neon half-precision float instructions.
-(Implies previous.)
-
-@item arm_fp16_alternative_ok
-ARM target supports the ARM FP16 alternative format. Some multilibs
-may be incompatible with the options needed.
-
-@item arm_fp16_none_ok
-ARM target supports specifying none as the ARM FP16 format.
-
-@item arm_thumb1_ok
-ARM target generates Thumb-1 code for @code{-mthumb}.
-
-@item arm_thumb2_ok
-ARM target generates Thumb-2 code for @code{-mthumb}.
-
-@item arm_nothumb
-ARM target that is not using Thumb.
-
-@item arm_vfp_ok
-ARM target supports @code{-mfpu=vfp -mfloat-abi=softfp}.
-Some multilibs may be incompatible with these options.
-
-@item arm_vfp3_ok
-@anchor{arm_vfp3_ok}
-ARM target supports @code{-mfpu=vfp3 -mfloat-abi=softfp}.
-Some multilibs may be incompatible with these options.
-
-@item arm_arch_v8a_hard_ok
-@anchor{arm_arch_v8a_hard_ok}
-The compiler is targeting @code{arm*-*-*} and can compile and assemble code
-using the options @code{-march=armv8-a -mfpu=neon-fp-armv8 -mfloat-abi=hard}.
-This is not enough to guarantee that linking works.
-
-@item arm_arch_v8a_hard_multilib
-The compiler is targeting @code{arm*-*-*} and can build programs using
-the options @code{-march=armv8-a -mfpu=neon-fp-armv8 -mfloat-abi=hard}.
-The target can also run the resulting binaries.
-
-@item arm_v8_vfp_ok
-ARM target supports @code{-mfpu=fp-armv8 -mfloat-abi=softfp}.
-Some multilibs may be incompatible with these options.
-
-@item arm_v8_neon_ok
-ARM target supports @code{-mfpu=neon-fp-armv8 -mfloat-abi=softfp}.
-Some multilibs may be incompatible with these options.
-
-@item arm_v8_1a_neon_ok
-@anchor{arm_v8_1a_neon_ok}
-ARM target supports options to generate ARMv8.1-A Adv.SIMD instructions.
-Some multilibs may be incompatible with these options.
-
-@item arm_v8_1a_neon_hw
-ARM target supports executing ARMv8.1-A Adv.SIMD instructions. Some
-multilibs may be incompatible with the options needed. Implies
-arm_v8_1a_neon_ok.
-
-@item arm_acq_rel
-ARM target supports acquire-release instructions.
-
-@item arm_v8_2a_fp16_scalar_ok
-@anchor{arm_v8_2a_fp16_scalar_ok}
-ARM target supports options to generate instructions for ARMv8.2-A and
-scalar instructions from the FP16 extension. Some multilibs may be
-incompatible with these options.
-
-@item arm_v8_2a_fp16_scalar_hw
-ARM target supports executing instructions for ARMv8.2-A and scalar
-instructions from the FP16 extension. Some multilibs may be
-incompatible with these options. Implies arm_v8_2a_fp16_neon_ok.
-
-@item arm_v8_2a_fp16_neon_ok
-@anchor{arm_v8_2a_fp16_neon_ok}
-ARM target supports options to generate instructions from ARMv8.2-A with
-the FP16 extension. Some multilibs may be incompatible with these
-options. Implies arm_v8_2a_fp16_scalar_ok.
-
-@item arm_v8_2a_fp16_neon_hw
-ARM target supports executing instructions from ARMv8.2-A with the FP16
-extension. Some multilibs may be incompatible with these options.
-Implies arm_v8_2a_fp16_neon_ok and arm_v8_2a_fp16_scalar_hw.
-
-@item arm_v8_2a_dotprod_neon_ok
-@anchor{arm_v8_2a_dotprod_neon_ok}
-ARM target supports options to generate instructions from ARMv8.2-A with
-the Dot Product extension. Some multilibs may be incompatible with these
-options.
-
-@item arm_v8_2a_dotprod_neon_hw
-ARM target supports executing instructions from ARMv8.2-A with the Dot
-Product extension. Some multilibs may be incompatible with these options.
-Implies arm_v8_2a_dotprod_neon_ok.
-
-@item arm_v8_2a_i8mm_neon_hw
-ARM target supports executing instructions from ARMv8.2-A with the 8-bit
-Matrix Multiply extension. Some multilibs may be incompatible with these
-options. Implies arm_v8_2a_i8mm_ok.
-
-@item arm_fp16fml_neon_ok
-@anchor{arm_fp16fml_neon_ok}
-ARM target supports extensions to generate the @code{VFMAL} and @code{VFMLS}
-half-precision floating-point instructions available from ARMv8.2-A and
-onwards. Some multilibs may be incompatible with these options.
-
-@item arm_v8_2a_bf16_neon_ok
-ARM target supports options to generate instructions from ARMv8.2-A with
-the BFloat16 extension (bf16). Some multilibs may be incompatible with these
-options.
-
-@item arm_v8_2a_i8mm_ok
-ARM target supports options to generate instructions from ARMv8.2-A with
-the 8-Bit Integer Matrix Multiply extension (i8mm). Some multilibs may be
-incompatible with these options.
-
-@item arm_v8_1m_mve_ok
-ARM target supports options to generate instructions from ARMv8.1-M with
-the M-Profile Vector Extension (MVE). Some multilibs may be incompatible
-with these options.
-
-@item arm_v8_1m_mve_fp_ok
-ARM target supports options to generate instructions from ARMv8.1-M with
-the Half-precision floating-point instructions (HP), Floating-point Extension
-(FP) along with M-Profile Vector Extension (MVE). Some multilibs may be
-incompatible with these options.
-
-@item arm_mve_hw
-Test system supports executing MVE instructions.
-
-@item arm_v8m_main_cde
-ARM target supports options to generate instructions from ARMv8-M with
-the Custom Datapath Extension (CDE). Some multilibs may be incompatible
-with these options.
-
-@item arm_v8m_main_cde_fp
-ARM target supports options to generate instructions from ARMv8-M with
-the Custom Datapath Extension (CDE) and floating-point (VFP).
-Some multilibs may be incompatible with these options.
-
-@item arm_v8_1m_main_cde_mve
-ARM target supports options to generate instructions from ARMv8.1-M with
-the Custom Datapath Extension (CDE) and M-Profile Vector Extension (MVE).
-Some multilibs may be incompatible with these options.
-
-@item arm_prefer_ldrd_strd
-ARM target prefers @code{LDRD} and @code{STRD} instructions over
-@code{LDM} and @code{STM} instructions.
-
-@item arm_thumb1_movt_ok
-ARM target generates Thumb-1 code for @code{-mthumb} with @code{MOVW}
-and @code{MOVT} instructions available.
-
-@item arm_thumb1_cbz_ok
-ARM target generates Thumb-1 code for @code{-mthumb} with
-@code{CBZ} and @code{CBNZ} instructions available.
-
-@item arm_divmod_simode
-ARM target for which divmod transform is disabled, if it supports hardware
-div instruction.
-
-@item arm_cmse_ok
-ARM target supports ARMv8-M Security Extensions, enabled by the @code{-mcmse}
-option.
-
-@item arm_cmse_hw
-Test system supports executing CMSE instructions.
-
-@item arm_coproc1_ok
-@anchor{arm_coproc1_ok}
-ARM target supports the following coprocessor instructions: @code{CDP},
-@code{LDC}, @code{STC}, @code{MCR} and @code{MRC}.
-
-@item arm_coproc2_ok
-@anchor{arm_coproc2_ok}
-ARM target supports all the coprocessor instructions also listed as supported
-in @ref{arm_coproc1_ok} in addition to the following: @code{CDP2}, @code{LDC2},
-@code{LDC2l}, @code{STC2}, @code{STC2l}, @code{MCR2} and @code{MRC2}.
-
-@item arm_coproc3_ok
-@anchor{arm_coproc3_ok}
-ARM target supports all the coprocessor instructions also listed as supported
-in @ref{arm_coproc2_ok} in addition the following: @code{MCRR} and @code{MRRC}.
-
-@item arm_coproc4_ok
-ARM target supports all the coprocessor instructions also listed as supported
-in @ref{arm_coproc3_ok} in addition the following: @code{MCRR2} and @code{MRRC2}.
-
-@item arm_simd32_ok
-@anchor{arm_simd32_ok}
-ARM Target supports options suitable for accessing the SIMD32 intrinsics from
-@code{arm_acle.h}.
-Some multilibs may be incompatible with these options.
-
-@item arm_sat_ok
-@anchor{arm_sat_ok}
-ARM Target supports options suitable for accessing the saturation
-intrinsics from @code{arm_acle.h}.
-Some multilibs may be incompatible with these options.
-
-@item arm_dsp_ok
-@anchor{arm_dsp_ok}
-ARM Target supports options suitable for accessing the DSP intrinsics
-from @code{arm_acle.h}.
-Some multilibs may be incompatible with these options.
-
-@item arm_softfp_ok
-@anchor{arm_softfp_ok}
-ARM target supports the @code{-mfloat-abi=softfp} option.
-
-@item arm_hard_ok
-@anchor{arm_hard_ok}
-ARM target supports the @code{-mfloat-abi=hard} option.
-
-@item arm_mve
-@anchor{arm_mve}
-ARM target supports generating MVE instructions.
-
-@item arm_v8_1_lob_ok
-@anchor{arm_v8_1_lob_ok}
-ARM Target supports executing the Armv8.1-M Mainline Low Overhead Loop
-instructions @code{DLS} and @code{LE}.
-Some multilibs may be incompatible with these options.
-
-@item arm_thumb2_no_arm_v8_1_lob
-ARM target where Thumb-2 is used without options but does not support
-executing the Armv8.1-M Mainline Low Overhead Loop instructions
-@code{DLS} and @code{LE}.
-
-@item arm_thumb2_ok_no_arm_v8_1_lob
-ARM target generates Thumb-2 code for @code{-mthumb} but does not
-support executing the Armv8.1-M Mainline Low Overhead Loop
-instructions @code{DLS} and @code{LE}.
-
-@end table
-
-@subsubsection AArch64-specific attributes
-
-@table @code
-@item aarch64_asm_<ext>_ok
-AArch64 assembler supports the architecture extension @code{ext} via the
-@code{.arch_extension} pseudo-op.
-@item aarch64_tiny
-AArch64 target which generates instruction sequences for tiny memory model.
-@item aarch64_small
-AArch64 target which generates instruction sequences for small memory model.
-@item aarch64_large
-AArch64 target which generates instruction sequences for large memory model.
-@item aarch64_little_endian
-AArch64 target which generates instruction sequences for little endian.
-@item aarch64_big_endian
-AArch64 target which generates instruction sequences for big endian.
-@item aarch64_small_fpic
-Binutils installed on test system supports relocation types required by -fpic
-for AArch64 small memory model.
-@item aarch64_sve_hw
-AArch64 target that is able to generate and execute SVE code (regardless of
-whether it does so by default).
-@item aarch64_sve128_hw
-@itemx aarch64_sve256_hw
-@itemx aarch64_sve512_hw
-@itemx aarch64_sve1024_hw
-@itemx aarch64_sve2048_hw
-Like @code{aarch64_sve_hw}, but also test for an exact hardware vector length.
-
-@item aarch64_fjcvtzs_hw
-AArch64 target that is able to generate and execute armv8.3-a FJCVTZS
-instruction.
-@end table
-
-@subsubsection MIPS-specific attributes
-
-@table @code
-@item mips64
-MIPS target supports 64-bit instructions.
-
-@item nomips16
-MIPS target does not produce MIPS16 code.
-
-@item mips16_attribute
-MIPS target can generate MIPS16 code.
-
-@item mips_loongson
-MIPS target is a Loongson-2E or -2F target using an ABI that supports
-the Loongson vector modes.
-
-@item mips_msa
-MIPS target supports @code{-mmsa}, MIPS SIMD Architecture (MSA).
-
-@item mips_newabi_large_long_double
-MIPS target supports @code{long double} larger than @code{double}
-when using the new ABI.
-
-@item mpaired_single
-MIPS target supports @code{-mpaired-single}.
-@end table
-
-@subsubsection MSP430-specific attributes
-
-@table @code
-@item msp430_small
-MSP430 target has the small memory model enabled (@code{-msmall}).
-
-@item msp430_large
-MSP430 target has the large memory model enabled (@code{-mlarge}).
-@end table
-
-@subsubsection PowerPC-specific attributes
-
-@table @code
-
-@item dfp_hw
-PowerPC target supports executing hardware DFP instructions.
-
-@item p8vector_hw
-PowerPC target supports executing VSX instructions (ISA 2.07).
-
-@item powerpc64
-Test system supports executing 64-bit instructions.
-
-@item powerpc_altivec
-PowerPC target supports AltiVec.
-
-@item powerpc_altivec_ok
-PowerPC target supports @code{-maltivec}.
-
-@item powerpc_eabi_ok
-PowerPC target supports @code{-meabi}.
-
-@item powerpc_elfv2
-PowerPC target supports @code{-mabi=elfv2}.
-
-@item powerpc_fprs
-PowerPC target supports floating-point registers.
-
-@item powerpc_hard_double
-PowerPC target supports hardware double-precision floating-point.
-
-@item powerpc_htm_ok
-PowerPC target supports @code{-mhtm}
-
-@item powerpc_p8vector_ok
-PowerPC target supports @code{-mpower8-vector}
-
-@item powerpc_popcntb_ok
-PowerPC target supports the @code{popcntb} instruction, indicating
-that this target supports @code{-mcpu=power5}.
-
-@item powerpc_ppu_ok
-PowerPC target supports @code{-mcpu=cell}.
-
-@item powerpc_spe
-PowerPC target supports PowerPC SPE.
-
-@item powerpc_spe_nocache
-Including the options used to compile this particular test, the
-PowerPC target supports PowerPC SPE.
-
-@item powerpc_spu
-PowerPC target supports PowerPC SPU.
-
-@item powerpc_vsx_ok
-PowerPC target supports @code{-mvsx}.
-
-@item powerpc_405_nocache
-Including the options used to compile this particular test, the
-PowerPC target supports PowerPC 405.
-
-@item ppc_recip_hw
-PowerPC target supports executing reciprocal estimate instructions.
-
-@item vmx_hw
-PowerPC target supports executing AltiVec instructions.
-
-@item vsx_hw
-PowerPC target supports executing VSX instructions (ISA 2.06).
-
-@item has_arch_pwr5
-PowerPC target pre-defines macro _ARCH_PWR5 which means the @code{-mcpu}
-setting is Power5 or later.
-
-@item has_arch_pwr6
-PowerPC target pre-defines macro _ARCH_PWR6 which means the @code{-mcpu}
-setting is Power6 or later.
-
-@item has_arch_pwr7
-PowerPC target pre-defines macro _ARCH_PWR7 which means the @code{-mcpu}
-setting is Power7 or later.
-
-@item has_arch_pwr8
-PowerPC target pre-defines macro _ARCH_PWR8 which means the @code{-mcpu}
-setting is Power8 or later.
-
-@item has_arch_pwr9
-PowerPC target pre-defines macro _ARCH_PWR9 which means the @code{-mcpu}
-setting is Power9 or later.
-@end table
-
-@subsubsection RISC-V specific attributes
-
-@table @code
-
-@item rv32
-Test system has an integer register width of 32 bits.
-
-@item rv64
-Test system has an integer register width of 64 bits.
-
-@end table
-
-@subsubsection Other hardware attributes
-
-@c Please keep this table sorted alphabetically.
-@table @code
-@item autoincdec
-Target supports autoincrement/decrement addressing.
-
-@item avx
-Target supports compiling @code{avx} instructions.
-
-@item avx_runtime
-Target supports the execution of @code{avx} instructions.
-
-@item avx2
-Target supports compiling @code{avx2} instructions.
-
-@item avx2_runtime
-Target supports the execution of @code{avx2} instructions.
-
-@item avxvnni
-Target supports the execution of @code{avxvnni} instructions.
-
-@item avx512f
-Target supports compiling @code{avx512f} instructions.
-
-@item avx512f_runtime
-Target supports the execution of @code{avx512f} instructions.
-
-@item avx512vp2intersect
-Target supports the execution of @code{avx512vp2intersect} instructions.
-
-@item avxifma
-Target supports the execution of @code{avxifma} instructions.
-
-@item avxneconvert
-Target supports the execution of @code{avxneconvert} instructions.
-
-@item avxvnniint8
-Target supports the execution of @code{avxvnniint8} instructions.
-
-@item amx_tile
-Target supports the execution of @code{amx-tile} instructions.
-
-@item amx_int8
-Target supports the execution of @code{amx-int8} instructions.
-
-@item amx_bf16
-Target supports the execution of @code{amx-bf16} instructions.
-
-@item amx_fp16
-Target supports the execution of @code{amx-fp16} instructions.
-
-@item cell_hw
-Test system can execute AltiVec and Cell PPU instructions.
-
-@item cmpccxadd
-Target supports the execution of @code{cmpccxadd} instructions.
-
-@item coldfire_fpu
-Target uses a ColdFire FPU.
-
-@item divmod
-Target supporting hardware divmod insn or divmod libcall.
-
-@item divmod_simode
-Target supporting hardware divmod insn or divmod libcall for SImode.
-
-@item hard_float
-Target supports FPU instructions.
-
-@item non_strict_align
-Target does not require strict alignment.
-
-@item pie_copyreloc
-The x86-64 target linker supports PIE with copy reloc.
-
-@item prefetchi
-Target supports the execution of @code{prefetchi} instructions.
-
-@item raoint
-Target supports the execution of @code{raoint} instructions.
-
-@item rdrand
-Target supports x86 @code{rdrand} instruction.
-
-@item sqrt_insn
-Target has a square root instruction that the compiler can generate.
-
-@item sse
-Target supports compiling @code{sse} instructions.
-
-@item sse_runtime
-Target supports the execution of @code{sse} instructions.
-
-@item sse2
-Target supports compiling @code{sse2} instructions.
-
-@item sse2_runtime
-Target supports the execution of @code{sse2} instructions.
-
-@item sync_char_short
-Target supports atomic operations on @code{char} and @code{short}.
-
-@item sync_int_long
-Target supports atomic operations on @code{int} and @code{long}.
-
-@item ultrasparc_hw
-Test environment appears to run executables on a simulator that
-accepts only @code{EM_SPARC} executables and chokes on @code{EM_SPARC32PLUS}
-or @code{EM_SPARCV9} executables.
-
-@item vect_cmdline_needed
-Target requires a command line argument to enable a SIMD instruction set.
-
-@item xorsign
-Target supports the xorsign optab expansion.
-
-@end table
-
-@subsubsection Environment attributes
-
-@table @code
-@item c
-The language for the compiler under test is C.
-
-@item c++
-The language for the compiler under test is C++.
-
-@item c99_runtime
-Target provides a full C99 runtime.
-
-@item correct_iso_cpp_string_wchar_protos
-Target @code{string.h} and @code{wchar.h} headers provide C++ required
-overloads for @code{strchr} etc. functions.
-
-@item d_runtime
-Target provides the D runtime.
-
-@item d_runtime_has_std_library
-Target provides the D standard library (Phobos).
-
-@item dummy_wcsftime
-Target uses a dummy @code{wcsftime} function that always returns zero.
-
-@item fd_truncate
-Target can truncate a file from a file descriptor, as used by
-@file{libgfortran/io/unix.c:fd_truncate}; i.e.@: @code{ftruncate} or
-@code{chsize}.
-
-@item fenv
-Target provides @file{fenv.h} include file.
-
-@item fenv_exceptions
-Target supports @file{fenv.h} with all the standard IEEE exceptions
-and floating-point exceptions are raised by arithmetic operations.
-
-@item fenv_exceptions_dfp
-Target supports @file{fenv.h} with all the standard IEEE exceptions
-and floating-point exceptions are raised by arithmetic operations for
-decimal floating point.
-
-@item fileio
-Target offers such file I/O library functions as @code{fopen},
-@code{fclose}, @code{tmpnam}, and @code{remove}. This is a link-time
-requirement for the presence of the functions in the library; even if
-they fail at runtime, the requirement is still regarded as satisfied.
-
-@item freestanding
-Target is @samp{freestanding} as defined in section 4 of the C99 standard.
-Effectively, it is a target which supports no extra headers or libraries
-other than what is considered essential.
-
-@item gettimeofday
-Target supports @code{gettimeofday}.
-
-@item init_priority
-Target supports constructors with initialization priority arguments.
-
-@item inttypes_types
-Target has the basic signed and unsigned types in @code{inttypes.h}.
-This is for tests that GCC's notions of these types agree with those
-in the header, as some systems have only @code{inttypes.h}.
-
-@item lax_strtofp
-Target might have errors of a few ULP in string to floating-point
-conversion functions and overflow is not always detected correctly by
-those functions.
-
-@item mempcpy
-Target provides @code{mempcpy} function.
-
-@item mmap
-Target supports @code{mmap}.
-
-@item newlib
-Target supports Newlib.
-
-@item newlib_nano_io
-GCC was configured with @code{--enable-newlib-nano-formatted-io}, which reduces
-the code size of Newlib formatted I/O functions.
-
-@item pow10
-Target provides @code{pow10} function.
-
-@item pthread
-Target can compile using @code{pthread.h} with no errors or warnings.
-
-@item pthread_h
-Target has @code{pthread.h}.
-
-@item run_expensive_tests
-Expensive testcases (usually those that consume excessive amounts of CPU
-time) should be run on this target. This can be enabled by setting the
-@env{GCC_TEST_RUN_EXPENSIVE} environment variable to a non-empty string.
-
-@item simulator
-Test system runs executables on a simulator (i.e.@: slowly) rather than
-hardware (i.e.@: fast).
-
-@item signal
-Target has @code{signal.h}.
-
-@item stabs
-Target supports the stabs debugging format.
-
-@item stdint_types
-Target has the basic signed and unsigned C types in @code{stdint.h}.
-This will be obsolete when GCC ensures a working @code{stdint.h} for
-all targets.
-
-@item stdint_types_mbig_endian
-Target accepts the option @option{-mbig-endian} and @code{stdint.h}
-can be included without error when @option{-mbig-endian} is passed.
-
-@item stpcpy
-Target provides @code{stpcpy} function.
-
-@item sysconf
-Target supports @code{sysconf}.
-
-@item trampolines
-Target supports trampolines.
-
-@item two_plus_gigs
-Target supports linking programs with 2+GiB of data.
-
-@item uclibc
-Target supports uClibc.
-
-@item unwrapped
-Target does not use a status wrapper.
-
-@item vxworks_kernel
-Target is a VxWorks kernel.
-
-@item vxworks_rtp
-Target is a VxWorks RTP.
-
-@item wchar
-Target supports wide characters.
-@end table
-
-@subsubsection Other attributes
-
-@table @code
-@item R_flag_in_section
-Target supports the 'R' flag in .section directive in assembly inputs.
-
-@item automatic_stack_alignment
-Target supports automatic stack alignment.
-
-@item branch_cost
-Target supports @option{-branch-cost=N}.
-
-@item cxa_atexit
-Target uses @code{__cxa_atexit}.
-
-@item default_packed
-@anchor{default_packed}
-Target has packed layout of structure members by default.
-
-@item exceptions
-Target supports exceptions.
-
-@item exceptions_enabled
-Target supports exceptions and they are enabled in the current
-testing configuration.
-
-@item fgraphite
-Target supports Graphite optimizations.
-
-@item fixed_point
-Target supports fixed-point extension to C.
-
-@item fopenacc
-Target supports OpenACC via @option{-fopenacc}.
-
-@item fopenmp
-Target supports OpenMP via @option{-fopenmp}.
-
-@item fpic
-Target supports @option{-fpic} and @option{-fPIC}.
-
-@item freorder
-Target supports @option{-freorder-blocks-and-partition}.
-
-@item fstack_protector
-Target supports @option{-fstack-protector}.
-
-@item gas
-Target uses GNU @command{as}.
-
-@item gc_sections
-Target supports @option{--gc-sections}.
-
-@item gld
-Target uses GNU @command{ld}.
-
-@item keeps_null_pointer_checks
-Target keeps null pointer checks, either due to the use of
-@option{-fno-delete-null-pointer-checks} or hardwired into the target.
-
-@item llvm_binutils
-Target is using an LLVM assembler and/or linker, instead of GNU Binutils.
-
-@item lra
-Target supports local register allocator (LRA).
-
-@item lto
-Compiler has been configured to support link-time optimization (LTO).
-
-@item lto_incremental
-Compiler and linker support link-time optimization relocatable linking
-with @option{-r} and @option{-flto} options.
-
-@item naked_functions
-Target supports the @code{naked} function attribute.
-
-@item named_sections
-Target supports named sections.
-
-@item natural_alignment_32
-Target uses natural alignment (aligned to type size) for types of
-32 bits or less.
-
-@item target_natural_alignment_64
-Target uses natural alignment (aligned to type size) for types of
-64 bits or less.
-
-@item no_alignment_constraints
-Target defines __BIGGEST_ALIGNMENT__=1. Hence target imposes
-no alignment constraints. This is similar, but not necessarily
-the same as @ref{default_packed}. Although @code{BIGGEST_FIELD_ALIGNMENT}
-defaults to @code{BIGGEST_ALIGNMENT} for most targets, it is possible
-for a target to set those two with different values and have different
-alignment constraints for aggregate and non-aggregate types.
-
-@item noinit
-Target supports the @code{noinit} variable attribute.
-
-@item nonpic
-Target does not generate PIC by default.
-
-@item o_flag_in_section
-Target supports the 'o' flag in .section directive in assembly inputs.
-
-@item offload_gcn
-Target has been configured for OpenACC/OpenMP offloading on AMD GCN.
-
-@item persistent
-Target supports the @code{persistent} variable attribute.
-
-@item pie_enabled
-Target generates PIE by default.
-
-@item pcc_bitfield_type_matters
-Target defines @code{PCC_BITFIELD_TYPE_MATTERS}.
-
-@item pe_aligned_commons
-Target supports @option{-mpe-aligned-commons}.
-
-@item pie
-Target supports @option{-pie}, @option{-fpie} and @option{-fPIE}.
-
-@item rdynamic
-Target supports @option{-rdynamic}.
-
-@item scalar_all_fma
-Target supports all four fused multiply-add optabs for both @code{float}
-and @code{double}. These optabs are: @code{fma_optab}, @code{fms_optab},
-@code{fnma_optab} and @code{fnms_optab}.
-
-@item section_anchors
-Target supports section anchors.
-
-@item short_enums
-Target defaults to short enums.
-
-@item stack_size
-@anchor{stack_size_et}
-Target has limited stack size. The stack size limit can be obtained using the
-STACK_SIZE macro defined by @ref{stack_size_ao,,@code{dg-add-options} feature
-@code{stack_size}}.
-
-@item static
-Target supports @option{-static}.
-
-@item static_libgfortran
-Target supports statically linking @samp{libgfortran}.
-
-@item string_merging
-Target supports merging string constants at link time.
-
-@item ucn
-Target supports compiling and assembling UCN.
-
-@item ucn_nocache
-Including the options used to compile this particular test, the
-target supports compiling and assembling UCN.
-
-@item unaligned_stack
-Target does not guarantee that its @code{STACK_BOUNDARY} is greater than
-or equal to the required vector alignment.
-
-@item vector_alignment_reachable
-Vector alignment is reachable for types of 32 bits or less.
-
-@item vector_alignment_reachable_for_64bit
-Vector alignment is reachable for types of 64 bits or less.
-
-@item vma_equals_lma
-Target generates executable with VMA equal to LMA for .data section.
-
-@item wchar_t_char16_t_compatible
-Target supports @code{wchar_t} that is compatible with @code{char16_t}.
-
-@item wchar_t_char32_t_compatible
-Target supports @code{wchar_t} that is compatible with @code{char32_t}.
-
-@item comdat_group
-Target uses comdat groups.
-
-@item indirect_calls
-Target supports indirect calls, i.e. calls where the target is not
-constant.
-
-@item lgccjit
-Target supports -lgccjit, i.e. libgccjit.so can be linked into jit tests.
-
-@item __OPTIMIZE__
-Optimizations are enabled (@code{__OPTIMIZE__}) per the current
-compiler flags.
-@end table
-
-@subsubsection Local to tests in @code{gcc.target/i386}
-
-@table @code
-@item 3dnow
-Target supports compiling @code{3dnow} instructions.
-
-@item aes
-Target supports compiling @code{aes} instructions.
-
-@item fma4
-Target supports compiling @code{fma4} instructions.
-
-@item mfentry
-Target supports the @code{-mfentry} option that alters the
-position of profiling calls such that they precede the prologue.
-
-@item ms_hook_prologue
-Target supports attribute @code{ms_hook_prologue}.
-
-@item pclmul
-Target supports compiling @code{pclmul} instructions.
-
-@item sse3
-Target supports compiling @code{sse3} instructions.
-
-@item sse4
-Target supports compiling @code{sse4} instructions.
-
-@item sse4a
-Target supports compiling @code{sse4a} instructions.
-
-@item ssse3
-Target supports compiling @code{ssse3} instructions.
-
-@item vaes
-Target supports compiling @code{vaes} instructions.
-
-@item vpclmul
-Target supports compiling @code{vpclmul} instructions.
-
-@item xop
-Target supports compiling @code{xop} instructions.
-@end table
-
-@subsubsection Local to tests in @code{gcc.test-framework}
-
-@table @code
-@item no
-Always returns 0.
-
-@item yes
-Always returns 1.
-@end table
-
-@node Add Options
-@subsection Features for @code{dg-add-options}
-
-The supported values of @var{feature} for directive @code{dg-add-options}
-are:
-
-@table @code
-@item arm_fp
-@code{__ARM_FP} definition. Only ARM targets support this feature, and only then
-in certain modes; see the @ref{arm_fp_ok,,arm_fp_ok effective target
-keyword}.
-
-@item arm_fp_dp
-@code{__ARM_FP} definition with double-precision support. Only ARM
-targets support this feature, and only then in certain modes; see the
-@ref{arm_fp_dp_ok,,arm_fp_dp_ok effective target keyword}.
-
-@item arm_neon
-NEON support. Only ARM targets support this feature, and only then
-in certain modes; see the @ref{arm_neon_ok,,arm_neon_ok effective target
-keyword}.
-
-@item arm_fp16
-VFP half-precision floating point support. This does not select the
-FP16 format; for that, use @ref{arm_fp16_ieee,,arm_fp16_ieee} or
-@ref{arm_fp16_alternative,,arm_fp16_alternative} instead. This
-feature is only supported by ARM targets and then only in certain
-modes; see the @ref{arm_fp16_ok,,arm_fp16_ok effective target
-keyword}.
-
-@item arm_fp16_ieee
-@anchor{arm_fp16_ieee}
-ARM IEEE 754-2008 format VFP half-precision floating point support.
-This feature is only supported by ARM targets and then only in certain
-modes; see the @ref{arm_fp16_ok,,arm_fp16_ok effective target
-keyword}.
-
-@item arm_fp16_alternative
-@anchor{arm_fp16_alternative}
-ARM Alternative format VFP half-precision floating point support.
-This feature is only supported by ARM targets and then only in certain
-modes; see the @ref{arm_fp16_ok,,arm_fp16_ok effective target
-keyword}.
-
-@item arm_neon_fp16
-NEON and half-precision floating point support. Only ARM targets
-support this feature, and only then in certain modes; see
-the @ref{arm_neon_fp16_ok,,arm_neon_fp16_ok effective target keyword}.
-
-@item arm_vfp3
-arm vfp3 floating point support; see
-the @ref{arm_vfp3_ok,,arm_vfp3_ok effective target keyword}.
-
-@item arm_arch_v8a_hard
-Add options for ARMv8-A and the hard-float variant of the AAPCS,
-if this is supported by the compiler; see the
-@ref{arm_arch_v8a_hard_ok,,arm_arch_v8a_hard_ok} effective target keyword.
-
-@item arm_v8_1a_neon
-Add options for ARMv8.1-A with Adv.SIMD support, if this is supported
-by the target; see the @ref{arm_v8_1a_neon_ok,,arm_v8_1a_neon_ok}
-effective target keyword.
-
-@item arm_v8_2a_fp16_scalar
-Add options for ARMv8.2-A with scalar FP16 support, if this is
-supported by the target; see the
-@ref{arm_v8_2a_fp16_scalar_ok,,arm_v8_2a_fp16_scalar_ok} effective
-target keyword.
-
-@item arm_v8_2a_fp16_neon
-Add options for ARMv8.2-A with Adv.SIMD FP16 support, if this is
-supported by the target; see the
-@ref{arm_v8_2a_fp16_neon_ok,,arm_v8_2a_fp16_neon_ok} effective target
-keyword.
-
-@item arm_v8_2a_dotprod_neon
-Add options for ARMv8.2-A with Adv.SIMD Dot Product support, if this is
-supported by the target; see the
-@ref{arm_v8_2a_dotprod_neon_ok} effective target keyword.
-
-@item arm_fp16fml_neon
-Add options to enable generation of the @code{VFMAL} and @code{VFMSL}
-instructions, if this is supported by the target; see the
-@ref{arm_fp16fml_neon_ok} effective target keyword.
-
-@item arm_dsp
-Add options for ARM DSP intrinsics support, if this is supported by
-the target; see the @ref{arm_dsp_ok,,arm_dsp_ok effective target
-keyword}.
-
-@item bind_pic_locally
-Add the target-specific flags needed to enable functions to bind
-locally when using pic/PIC passes in the testsuite.
-
-@item float@var{n}
-Add the target-specific flags needed to use the @code{_Float@var{n}} type.
-
-@item float@var{n}x
-Add the target-specific flags needed to use the @code{_Float@var{n}x} type.
-
-@item ieee
-Add the target-specific flags needed to enable full IEEE
-compliance mode.
-
-@item mips16_attribute
-@code{mips16} function attributes.
-Only MIPS targets support this feature, and only then in certain modes.
-
-@item stack_size
-@anchor{stack_size_ao}
-Add the flags needed to define macro STACK_SIZE and set it to the stack size
-limit associated with the @ref{stack_size_et,,@code{stack_size} effective
-target}.
-
-@item sqrt_insn
-Add the target-specific flags needed to enable hardware square root
-instructions, if any.
-
-@item tls
-Add the target-specific flags needed to use thread-local storage.
-@end table
-
-@node Require Support
-@subsection Variants of @code{dg-require-@var{support}}
-
-A few of the @code{dg-require} directives take arguments.
-
-@table @code
-@item dg-require-iconv @var{codeset}
-Skip the test if the target does not support iconv. @var{codeset} is
-the codeset to convert to.
-
-@item dg-require-profiling @var{profopt}
-Skip the test if the target does not support profiling with option
-@var{profopt}.
-
-@item dg-require-stack-check @var{check}
-Skip the test if the target does not support the @code{-fstack-check}
-option. If @var{check} is @code{""}, support for @code{-fstack-check}
-is checked, for @code{-fstack-check=("@var{check}")} otherwise.
-
-@item dg-require-stack-size @var{size}
-Skip the test if the target does not support a stack size of @var{size}.
-
-@item dg-require-visibility @var{vis}
-Skip the test if the target does not support the @code{visibility} attribute.
-If @var{vis} is @code{""}, support for @code{visibility("hidden")} is
-checked, for @code{visibility("@var{vis}")} otherwise.
-@end table
-
-The original @code{dg-require} directives were defined before there
-was support for effective-target keywords. The directives that do not
-take arguments could be replaced with effective-target keywords.
-
-@table @code
-@item dg-require-alias ""
-Skip the test if the target does not support the @samp{alias} attribute.
-
-@item dg-require-ascii-locale ""
-Skip the test if the host does not support an ASCII locale.
-
-@item dg-require-compat-dfp ""
-Skip this test unless both compilers in a @file{compat} testsuite
-support decimal floating point.
-
-@item dg-require-cxa-atexit ""
-Skip the test if the target does not support @code{__cxa_atexit}.
-This is equivalent to @code{dg-require-effective-target cxa_atexit}.
-
-@item dg-require-dll ""
-Skip the test if the target does not support DLL attributes.
-
-@item dg-require-dot ""
-Skip the test if the host does not have @command{dot}.
-
-@item dg-require-fork ""
-Skip the test if the target does not support @code{fork}.
-
-@item dg-require-gc-sections ""
-Skip the test if the target's linker does not support the
-@code{--gc-sections} flags.
-This is equivalent to @code{dg-require-effective-target gc-sections}.
-
-@item dg-require-host-local ""
-Skip the test if the host is remote, rather than the same as the build
-system. Some tests are incompatible with DejaGnu's handling of remote
-hosts, which involves copying the source file to the host and compiling
-it with a relative path and "@code{-o a.out}".
-
-@item dg-require-mkfifo ""
-Skip the test if the target does not support @code{mkfifo}.
-
-@item dg-require-named-sections ""
-Skip the test is the target does not support named sections.
-This is equivalent to @code{dg-require-effective-target named_sections}.
-
-@item dg-require-weak ""
-Skip the test if the target does not support weak symbols.
-
-@item dg-require-weak-override ""
-Skip the test if the target does not support overriding weak symbols.
-@end table
-
-@node Final Actions
-@subsection Commands for use in @code{dg-final}
-
-The GCC testsuite defines the following directives to be used within
-@code{dg-final}.
-
-@subsubsection Scan a particular file
-
-@table @code
-@item scan-file @var{filename} @var{regexp} [@{ target/xfail @var{selector} @}]
-Passes if @var{regexp} matches text in @var{filename}.
-@item scan-file-not @var{filename} @var{regexp} [@{ target/xfail @var{selector} @}]
-Passes if @var{regexp} does not match text in @var{filename}.
-@item scan-module @var{module} @var{regexp} [@{ target/xfail @var{selector} @}]
-Passes if @var{regexp} matches in Fortran module @var{module}.
-@item dg-check-dot @var{filename}
-Passes if @var{filename} is a valid @file{.dot} file (by running
-@code{dot -Tpng} on it, and verifying the exit code is 0).
-@item scan-sarif-file @var{regexp} [@{ target/xfail @var{selector} @}]
-Passes if @var{regexp} matches text in the file generated by
-@option{-fdiagnostics-format=sarif-file}.
-@item scan-sarif-file-not @var{regexp} [@{ target/xfail @var{selector} @}]
-Passes if @var{regexp} does not match text in the file generated by
-@option{-fdiagnostics-format=sarif-file}.
-@end table
-
-@subsubsection Scan the assembly output
-
-@table @code
-@item scan-assembler @var{regex} [@{ target/xfail @var{selector} @}]
-Passes if @var{regex} matches text in the test's assembler output.
-
-@item scan-assembler-not @var{regex} [@{ target/xfail @var{selector} @}]
-Passes if @var{regex} does not match text in the test's assembler output.
-
-@item scan-assembler-times @var{regex} @var{num} [@{ target/xfail @var{selector} @}]
-Passes if @var{regex} is matched exactly @var{num} times in the test's
-assembler output.
-
-@item scan-assembler-dem @var{regex} [@{ target/xfail @var{selector} @}]
-Passes if @var{regex} matches text in the test's demangled assembler output.
-
-@item scan-assembler-dem-not @var{regex} [@{ target/xfail @var{selector} @}]
-Passes if @var{regex} does not match text in the test's demangled assembler
-output.
-
-@item scan-assembler-symbol-section @var{functions} @var{section} [@{ target/xfail @var{selector} @}]
-Passes if @var{functions} are all in @var{section}. The caller needs to
-allow for @code{USER_LABEL_PREFIX} and different section name conventions.
-
-@item scan-symbol-section @var{filename} @var{functions} @var{section} [@{ target/xfail @var{selector} @}]
-Passes if @var{functions} are all in @var{section}in @var{filename}.
-The same caveats as for @code{scan-assembler-symbol-section} apply.
-
-@item scan-hidden @var{symbol} [@{ target/xfail @var{selector} @}]
-Passes if @var{symbol} is defined as a hidden symbol in the test's
-assembly output.
-
-@item scan-not-hidden @var{symbol} [@{ target/xfail @var{selector} @}]
-Passes if @var{symbol} is not defined as a hidden symbol in the test's
-assembly output.
-
-@item check-function-bodies @var{prefix} @var{terminator} [@var{options} [@{ target/xfail @var{selector} @}]]
-Looks through the source file for comments that give the expected assembly
-output for selected functions. Each line of expected output starts with the
-prefix string @var{prefix} and the expected output for a function as a whole
-is followed by a line that starts with the string @var{terminator}.
-Specifying an empty terminator is equivalent to specifying @samp{"*/"}.
-
-@var{options}, if specified, is a list of regular expressions, each of
-which matches a full command-line option. A non-empty list prevents
-the test from running unless all of the given options are present on the
-command line. This can help if a source file is compiled both with
-and without optimization, since it is rarely useful to check the full
-function body for unoptimized code.
-
-The first line of the expected output for a function @var{fn} has the form:
-
-@smallexample
-@var{prefix} @var{fn}: [@{ target/xfail @var{selector} @}]
-@end smallexample
-
-Subsequent lines of the expected output also start with @var{prefix}.
-In both cases, whitespace after @var{prefix} is not significant.
-
-The test discards assembly directives such as @code{.cfi_startproc}
-and local label definitions such as @code{.LFB0} from the compiler's
-assembly output. It then matches the result against the expected
-output for a function as a single regular expression. This means that
-later lines can use backslashes to refer back to @samp{(@dots{})}
-captures on earlier lines. For example:
-
-@smallexample
-/* @{ dg-final @{ check-function-bodies "**" "" "-DCHECK_ASM" @} @} */
-@dots{}
-/*
-** add_w0_s8_m:
-** mov (z[0-9]+\.b), w0
-** add z0\.b, p0/m, z0\.b, \1
-** ret
-*/
-svint8_t add_w0_s8_m (@dots{}) @{ @dots{} @}
-@dots{}
-/*
-** add_b0_s8_m:
-** mov (z[0-9]+\.b), b0
-** add z1\.b, p0/m, z1\.b, \1
-** ret
-*/
-svint8_t add_b0_s8_m (@dots{}) @{ @dots{} @}
-@end smallexample
-
-checks whether the implementations of @code{add_w0_s8_m} and
-@code{add_b0_s8_m} match the regular expressions given. The test only
-runs when @samp{-DCHECK_ASM} is passed on the command line.
-
-It is possible to create non-capturing multi-line regular expression
-groups of the form @samp{(@var{a}|@var{b}|@dots{})} by putting the
-@samp{(}, @samp{|} and @samp{)} on separate lines (each still using
-@var{prefix}). For example:
-
-@smallexample
-/*
-** cmple_f16_tied:
-** (
-** fcmge p0\.h, p0/z, z1\.h, z0\.h
-** |
-** fcmle p0\.h, p0/z, z0\.h, z1\.h
-** )
-** ret
-*/
-svbool_t cmple_f16_tied (@dots{}) @{ @dots{} @}
-@end smallexample
-
-checks whether @code{cmple_f16_tied} is implemented by the
-@code{fcmge} instruction followed by @code{ret} or by the
-@code{fcmle} instruction followed by @code{ret}. The test is
-still a single regular rexpression.
-
-A line containing just:
-
-@smallexample
-@var{prefix} ...
-@end smallexample
-
-stands for zero or more unmatched lines; the whitespace after
-@var{prefix} is again not significant.
-
-@end table
-
-@subsubsection Scan optimization dump files
-
-These commands are available for @var{kind} of @code{tree}, @code{ltrans-tree},
-@code{offload-tree}, @code{rtl}, @code{offload-rtl}, @code{ipa}, and
-@code{wpa-ipa}.
-
-@table @code
-@item scan-@var{kind}-dump @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}]
-Passes if @var{regex} matches text in the dump file with suffix @var{suffix}.
-
-@item scan-@var{kind}-dump-not @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}]
-Passes if @var{regex} does not match text in the dump file with suffix
-@var{suffix}.
-
-@item scan-@var{kind}-dump-times @var{regex} @var{num} @var{suffix} [@{ target/xfail @var{selector} @}]
-Passes if @var{regex} is found exactly @var{num} times in the dump file
-with suffix @var{suffix}.
-
-@item scan-@var{kind}-dump-dem @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}]
-Passes if @var{regex} matches demangled text in the dump file with
-suffix @var{suffix}.
-
-@item scan-@var{kind}-dump-dem-not @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}]
-Passes if @var{regex} does not match demangled text in the dump file with
-suffix @var{suffix}.
-@end table
-
-The @var{suffix} argument which describes the dump file to be scanned
-may contain a glob pattern that must expand to exactly one file
-name. This is useful if, e.g., different pass instances are executed
-depending on torture testing command-line flags, producing dump files
-whose names differ only in their pass instance number suffix. For
-example, to scan instances 1, 2, 3 of a tree pass ``mypass'' for
-occurrences of the string ``code has been optimized'', use:
-@smallexample
-/* @{ dg-options "-fdump-tree-mypass" @} */
-/* @{ dg-final @{ scan-tree-dump "code has been optimized" "mypass\[1-3\]" @} @} */
-@end smallexample
-
-
-@subsubsection Check for output files
-
-@table @code
-@item output-exists [@{ target/xfail @var{selector} @}]
-Passes if compiler output file exists.
-
-@item output-exists-not [@{ target/xfail @var{selector} @}]
-Passes if compiler output file does not exist.
-
-@item scan-symbol @var{regexp} [@{ target/xfail @var{selector} @}]
-Passes if the pattern is present in the final executable.
-
-@item scan-symbol-not @var{regexp} [@{ target/xfail @var{selector} @}]
-Passes if the pattern is absent from the final executable.
-@end table
-
-@subsubsection Checks for @command{gcov} tests
-
-@table @code
-@item run-gcov @var{sourcefile}
-Check line counts in @command{gcov} tests.
-
-@item run-gcov [branches] [calls] @{ @var{opts} @var{sourcefile} @}
-Check branch and/or call counts, in addition to line counts, in
-@command{gcov} tests.
-
-@item run-gcov-pytest @{ @var{sourcefile} @var{pytest_file} @}
-Check output of @command{gcov} intermediate format with a pytest
-script.
-@end table
-
-@subsubsection Clean up generated test files
-
-Usually the test-framework removes files that were generated during
-testing. If a testcase, for example, uses any dumping mechanism to
-inspect a passes dump file, the testsuite recognized the dump option
-passed to the tool and schedules a final cleanup to remove these files.
-
-There are, however, following additional cleanup directives that can be
-used to annotate a testcase "manually".
-@table @code
-@item cleanup-coverage-files
-Removes coverage data files generated for this test.
-
-@item cleanup-modules "@var{list-of-extra-modules}"
-Removes Fortran module files generated for this test, excluding the
-module names listed in keep-modules.
-Cleaning up module files is usually done automatically by the testsuite
-by looking at the source files and removing the modules after the test
-has been executed.
-@smallexample
-module MoD1
-end module MoD1
-module Mod2
-end module Mod2
-module moD3
-end module moD3
-module mod4
-end module mod4
-! @{ dg-final @{ cleanup-modules "mod1 mod2" @} @} ! redundant
-! @{ dg-final @{ keep-modules "mod3 mod4" @} @}
-@end smallexample
-
-@item keep-modules "@var{list-of-modules-not-to-delete}"
-Whitespace separated list of module names that should not be deleted by
-cleanup-modules.
-If the list of modules is empty, all modules defined in this file are kept.
-@smallexample
-module maybe_unneeded
-end module maybe_unneeded
-module keep1
-end module keep1
-module keep2
-end module keep2
-! @{ dg-final @{ keep-modules "keep1 keep2" @} @} ! just keep these two
-! @{ dg-final @{ keep-modules "" @} @} ! keep all
-@end smallexample
-
-@item dg-keep-saved-temps "@var{list-of-suffixes-not-to-delete}"
-Whitespace separated list of suffixes that should not be deleted
-automatically in a testcase that uses @option{-save-temps}.
-@smallexample
-// @{ dg-options "-save-temps -fpch-preprocess -I." @}
-int main() @{ return 0; @}
-// @{ dg-keep-saved-temps ".s" @} ! just keep assembler file
-// @{ dg-keep-saved-temps ".s" ".i" @} ! ... and .i
-// @{ dg-keep-saved-temps ".ii" ".o" @} ! or just .ii and .o
-@end smallexample
-
-@item cleanup-profile-file
-Removes profiling files generated for this test.
-
-@end table
-
-@node Ada Tests
-@section Ada Language Testsuites
-
-The Ada testsuite includes executable tests from the ACATS
-testsuite, publicly available at
-@uref{http://www.ada-auth.org/acats.html}.
-
-These tests are integrated in the GCC testsuite in the
-@file{ada/acats} directory, and
-enabled automatically when running @code{make check}, assuming
-the Ada language has been enabled when configuring GCC@.
-
-You can also run the Ada testsuite independently, using
-@code{make check-ada}, or run a subset of the tests by specifying which
-chapter to run, e.g.:
-
-@smallexample
-$ make check-ada CHAPTERS="c3 c9"
-@end smallexample
-
-The tests are organized by directory, each directory corresponding to
-a chapter of the Ada Reference Manual. So for example, @file{c9} corresponds
-to chapter 9, which deals with tasking features of the language.
-
-The tests are run using two @command{sh} scripts: @file{run_acats} and
-@file{run_all.sh}. To run the tests using a simulator or a cross
-target, see the small
-customization section at the top of @file{run_all.sh}.
-
-These tests are run using the build tree: they can be run without doing
-a @code{make install}.
-
-@node C Tests
-@section C Language Testsuites
-
-GCC contains the following C language testsuites, in the
-@file{gcc/testsuite} directory:
-
-@table @file
-@item gcc.dg
-This contains tests of particular features of the C compiler, using the
-more modern @samp{dg} harness. Correctness tests for various compiler
-features should go here if possible.
-
-Magic comments determine whether the file
-is preprocessed, compiled, linked or run. In these tests, error and warning
-message texts are compared against expected texts or regular expressions
-given in comments. These tests are run with the options @samp{-ansi -pedantic}
-unless other options are given in the test. Except as noted below they
-are not run with multiple optimization options.
-@item gcc.dg/compat
-This subdirectory contains tests for binary compatibility using
-@file{lib/compat.exp}, which in turn uses the language-independent support
-(@pxref{compat Testing, , Support for testing binary compatibility}).
-@item gcc.dg/cpp
-This subdirectory contains tests of the preprocessor.
-@item gcc.dg/debug
-This subdirectory contains tests for debug formats. Tests in this
-subdirectory are run for each debug format that the compiler supports.
-@item gcc.dg/format
-This subdirectory contains tests of the @option{-Wformat} format
-checking. Tests in this directory are run with and without
-@option{-DWIDE}.
-@item gcc.dg/noncompile
-This subdirectory contains tests of code that should not compile and
-does not need any special compilation options. They are run with
-multiple optimization options, since sometimes invalid code crashes
-the compiler with optimization.
-@item gcc.dg/special
-FIXME: describe this.
-
-@item gcc.c-torture
-This contains particular code fragments which have historically broken easily.
-These tests are run with multiple optimization options, so tests for features
-which only break at some optimization levels belong here. This also contains
-tests to check that certain optimizations occur. It might be worthwhile to
-separate the correctness tests cleanly from the code quality tests, but
-it hasn't been done yet.
-
-@item gcc.c-torture/compat
-FIXME: describe this.
-
-This directory should probably not be used for new tests.
-@item gcc.c-torture/compile
-This testsuite contains test cases that should compile, but do not
-need to link or run. These test cases are compiled with several
-different combinations of optimization options. All warnings are
-disabled for these test cases, so this directory is not suitable if
-you wish to test for the presence or absence of compiler warnings.
-While special options can be set, and tests disabled on specific
-platforms, by the use of @file{.x} files, mostly these test cases
-should not contain platform dependencies. FIXME: discuss how defines
-such as @code{STACK_SIZE} are used.
-@item gcc.c-torture/execute
-This testsuite contains test cases that should compile, link and run;
-otherwise the same comments as for @file{gcc.c-torture/compile} apply.
-@item gcc.c-torture/execute/ieee
-This contains tests which are specific to IEEE floating point.
-@item gcc.c-torture/unsorted
-FIXME: describe this.
-
-This directory should probably not be used for new tests.
-@item gcc.misc-tests
-This directory contains C tests that require special handling. Some
-of these tests have individual expect files, and others share
-special-purpose expect files:
-
-@table @file
-@item @code{bprob*.c}
-Test @option{-fbranch-probabilities} using
-@file{gcc.misc-tests/bprob.exp}, which
-in turn uses the generic, language-independent framework
-(@pxref{profopt Testing, , Support for testing profile-directed
-optimizations}).
-
-@item @code{gcov*.c}
-Test @command{gcov} output using @file{gcov.exp}, which in turn uses the
-language-independent support (@pxref{gcov Testing, , Support for testing gcov}).
-
-@item @code{i386-pf-*.c}
-Test i386-specific support for data prefetch using @file{i386-prefetch.exp}.
-@end table
-
-@item gcc.test-framework
-@table @file
-@item @code{dg-*.c}
-Test the testsuite itself using @file{gcc.test-framework/test-framework.exp}.
-@end table
-
-@end table
-
-FIXME: merge in @file{testsuite/README.gcc} and discuss the format of
-test cases and magic comments more.
-
-@node LTO Testing
-@section Support for testing link-time optimizations
-
-Tests for link-time optimizations usually require multiple source files
-that are compiled separately, perhaps with different sets of options.
-There are several special-purpose test directives used for these tests.
-
-@table @code
-@item @{ dg-lto-do @var{do-what-keyword} @}
-@var{do-what-keyword} specifies how the test is compiled and whether
-it is executed. It is one of:
-
-@table @code
-@item assemble
-Compile with @option{-c} to produce a relocatable object file.
-@item link
-Compile, assemble, and link to produce an executable file.
-@item run
-Produce and run an executable file, which is expected to return
-an exit code of 0.
-@end table
-
-The default is @code{assemble}. That can be overridden for a set of
-tests by redefining @code{dg-do-what-default} within the @code{.exp}
-file for those tests.
-
-Unlike @code{dg-do}, @code{dg-lto-do} does not support an optional
-@samp{target} or @samp{xfail} list. Use @code{dg-skip-if},
-@code{dg-xfail-if}, or @code{dg-xfail-run-if}.
-
-@item @{ dg-lto-options @{ @{ @var{options} @} [@{ @var{options} @}] @} [@{ target @var{selector} @}]@}
-This directive provides a list of one or more sets of compiler options
-to override @var{LTO_OPTIONS}. Each test will be compiled and run with
-each of these sets of options.
-
-@item @{ dg-extra-ld-options @var{options} [@{ target @var{selector} @}]@}
-This directive adds @var{options} to the linker options used.
-
-@item @{ dg-suppress-ld-options @var{options} [@{ target @var{selector} @}]@}
-This directive removes @var{options} from the set of linker options used.
-@end table
-
-@node gcov Testing
-@section Support for testing @command{gcov}
-
-Language-independent support for testing @command{gcov}, and for checking
-that branch profiling produces expected values, is provided by the
-expect file @file{lib/gcov.exp}. @command{gcov} tests also rely on procedures
-in @file{lib/gcc-dg.exp} to compile and run the test program. A typical
-@command{gcov} test contains the following DejaGnu commands within comments:
-
-@smallexample
-@{ dg-options "--coverage" @}
-@{ dg-do run @{ target native @} @}
-@{ dg-final @{ run-gcov sourcefile @} @}
-@end smallexample
-
-Checks of @command{gcov} output can include line counts, branch percentages,
-and call return percentages. All of these checks are requested via
-commands that appear in comments in the test's source file.
-Commands to check line counts are processed by default.
-Commands to check branch percentages and call return percentages are
-processed if the @command{run-gcov} command has arguments @code{branches}
-or @code{calls}, respectively. For example, the following specifies
-checking both, as well as passing @option{-b} to @command{gcov}:
-
-@smallexample
-@{ dg-final @{ run-gcov branches calls @{ -b sourcefile @} @} @}
-@end smallexample
-
-A line count command appears within a comment on the source line
-that is expected to get the specified count and has the form
-@code{count(@var{cnt})}. A test should only check line counts for
-lines that will get the same count for any architecture.
-
-Commands to check branch percentages (@code{branch}) and call
-return percentages (@code{returns}) are very similar to each other.
-A beginning command appears on or before the first of a range of
-lines that will report the percentage, and the ending command
-follows that range of lines. The beginning command can include a
-list of percentages, all of which are expected to be found within
-the range. A range is terminated by the next command of the same
-kind. A command @code{branch(end)} or @code{returns(end)} marks
-the end of a range without starting a new one. For example:
-
-@smallexample
-if (i > 10 && j > i && j < 20) /* @r{branch(27 50 75)} */
- /* @r{branch(end)} */
- foo (i, j);
-@end smallexample
-
-For a call return percentage, the value specified is the
-percentage of calls reported to return. For a branch percentage,
-the value is either the expected percentage or 100 minus that
-value, since the direction of a branch can differ depending on the
-target or the optimization level.
-
-Not all branches and calls need to be checked. A test should not
-check for branches that might be optimized away or replaced with
-predicated instructions. Don't check for calls inserted by the
-compiler or ones that might be inlined or optimized away.
-
-A single test can check for combinations of line counts, branch
-percentages, and call return percentages. The command to check a
-line count must appear on the line that will report that count, but
-commands to check branch percentages and call return percentages can
-bracket the lines that report them.
-
-@node profopt Testing
-@section Support for testing profile-directed optimizations
-
-The file @file{profopt.exp} provides language-independent support for
-checking correct execution of a test built with profile-directed
-optimization. This testing requires that a test program be built and
-executed twice. The first time it is compiled to generate profile
-data, and the second time it is compiled to use the data that was
-generated during the first execution. The second execution is to
-verify that the test produces the expected results.
-
-To check that the optimization actually generated better code, a
-test can be built and run a third time with normal optimizations to
-verify that the performance is better with the profile-directed
-optimizations. @file{profopt.exp} has the beginnings of this kind
-of support.
-
-@file{profopt.exp} provides generic support for profile-directed
-optimizations. Each set of tests that uses it provides information
-about a specific optimization:
-
-@table @code
-@item tool
-tool being tested, e.g., @command{gcc}
-
-@item profile_option
-options used to generate profile data
-
-@item feedback_option
-options used to optimize using that profile data
-
-@item prof_ext
-suffix of profile data files
-
-@item PROFOPT_OPTIONS
-list of options with which to run each test, similar to the lists for
-torture tests
-
-@item @{ dg-final-generate @{ @var{local-directive} @} @}
-This directive is similar to @code{dg-final}, but the
-@var{local-directive} is run after the generation of profile data.
-
-@item @{ dg-final-use @{ @var{local-directive} @} @}
-The @var{local-directive} is run after the profile data have been
-used.
-@end table
-
-@node compat Testing
-@section Support for testing binary compatibility
-
-The file @file{compat.exp} provides language-independent support for
-binary compatibility testing. It supports testing interoperability of
-two compilers that follow the same ABI, or of multiple sets of
-compiler options that should not affect binary compatibility. It is
-intended to be used for testsuites that complement ABI testsuites.
-
-A test supported by this framework has three parts, each in a
-separate source file: a main program and two pieces that interact
-with each other to split up the functionality being tested.
-
-@table @file
-@item @var{testname}_main.@var{suffix}
-Contains the main program, which calls a function in file
-@file{@var{testname}_x.@var{suffix}}.
-
-@item @var{testname}_x.@var{suffix}
-Contains at least one call to a function in
-@file{@var{testname}_y.@var{suffix}}.
-
-@item @var{testname}_y.@var{suffix}
-Shares data with, or gets arguments from,
-@file{@var{testname}_x.@var{suffix}}.
-@end table
-
-Within each test, the main program and one functional piece are
-compiled by the GCC under test. The other piece can be compiled by
-an alternate compiler. If no alternate compiler is specified,
-then all three source files are all compiled by the GCC under test.
-You can specify pairs of sets of compiler options. The first element
-of such a pair specifies options used with the GCC under test, and the
-second element of the pair specifies options used with the alternate
-compiler. Each test is compiled with each pair of options.
-
-@file{compat.exp} defines default pairs of compiler options.
-These can be overridden by defining the environment variable
-@env{COMPAT_OPTIONS} as:
-
-@smallexample
-COMPAT_OPTIONS="[list [list @{@var{tst1}@} @{@var{alt1}@}]
- @dots{}[list @{@var{tstn}@} @{@var{altn}@}]]"
-@end smallexample
-
-where @var{tsti} and @var{alti} are lists of options, with @var{tsti}
-used by the compiler under test and @var{alti} used by the alternate
-compiler. For example, with
-@code{[list [list @{-g -O0@} @{-O3@}] [list @{-fpic@} @{-fPIC -O2@}]]},
-the test is first built with @option{-g -O0} by the compiler under
-test and with @option{-O3} by the alternate compiler. The test is
-built a second time using @option{-fpic} by the compiler under test
-and @option{-fPIC -O2} by the alternate compiler.
-
-An alternate compiler is specified by defining an environment
-variable to be the full pathname of an installed compiler; for C
-define @env{ALT_CC_UNDER_TEST}, and for C++ define
-@env{ALT_CXX_UNDER_TEST}. These will be written to the
-@file{site.exp} file used by DejaGnu. The default is to build each
-test with the compiler under test using the first of each pair of
-compiler options from @env{COMPAT_OPTIONS}. When
-@env{ALT_CC_UNDER_TEST} or
-@env{ALT_CXX_UNDER_TEST} is @code{same}, each test is built using
-the compiler under test but with combinations of the options from
-@env{COMPAT_OPTIONS}.
-
-To run only the C++ compatibility suite using the compiler under test
-and another version of GCC using specific compiler options, do the
-following from @file{@var{objdir}/gcc}:
-
-@smallexample
-rm site.exp
-make -k \
- ALT_CXX_UNDER_TEST=$@{alt_prefix@}/bin/g++ \
- COMPAT_OPTIONS="@var{lists as shown above}" \
- check-c++ \
- RUNTESTFLAGS="compat.exp"
-@end smallexample
-
-A test that fails when the source files are compiled with different
-compilers, but passes when the files are compiled with the same
-compiler, demonstrates incompatibility of the generated code or
-runtime support. A test that fails for the alternate compiler but
-passes for the compiler under test probably tests for a bug that was
-fixed in the compiler under test but is present in the alternate
-compiler.
-
-The binary compatibility tests support a small number of test framework
-commands that appear within comments in a test file.
-
-@table @code
-@item dg-require-*
-These commands can be used in @file{@var{testname}_main.@var{suffix}}
-to skip the test if specific support is not available on the target.
-
-@item dg-options
-The specified options are used for compiling this particular source
-file, appended to the options from @env{COMPAT_OPTIONS}. When this
-command appears in @file{@var{testname}_main.@var{suffix}} the options
-are also used to link the test program.
-
-@item dg-xfail-if
-This command can be used in a secondary source file to specify that
-compilation is expected to fail for particular options on particular
-targets.
-@end table
-
-@node Torture Tests
-@section Support for torture testing using multiple options
-
-Throughout the compiler testsuite there are several directories whose
-tests are run multiple times, each with a different set of options.
-These are known as torture tests.
-@file{lib/torture-options.exp} defines procedures to
-set up these lists:
-
-@table @code
-@item torture-init
-Initialize use of torture lists.
-@item set-torture-options
-Set lists of torture options to use for tests with and without loops.
-Optionally combine a set of torture options with a set of other
-options, as is done with Objective-C runtime options.
-@item torture-finish
-Finalize use of torture lists.
-@end table
-
-The @file{.exp} file for a set of tests that use torture options must
-include calls to these three procedures if:
-
-@itemize @bullet
-@item It calls @code{gcc-dg-runtest} and overrides @var{DG_TORTURE_OPTIONS}.
-
-@item It calls @var{$@{tool@}}@code{-torture} or
-@var{$@{tool@}}@code{-torture-execute}, where @var{tool} is @code{c},
-@code{fortran}, or @code{objc}.
-
-@item It calls @code{dg-pch}.
-@end itemize
-
-It is not necessary for a @file{.exp} file that calls @code{gcc-dg-runtest}
-to call the torture procedures if the tests should use the list in
-@var{DG_TORTURE_OPTIONS} defined in @file{gcc-dg.exp}.
-
-Most uses of torture options can override the default lists by defining
-@var{TORTURE_OPTIONS} or add to the default list by defining
-@var{ADDITIONAL_TORTURE_OPTIONS}. Define these in a @file{.dejagnurc}
-file or add them to the @file{site.exp} file; for example
-
-@smallexample
-set ADDITIONAL_TORTURE_OPTIONS [list \
- @{ -O2 -ftree-loop-linear @} \
- @{ -O2 -fpeel-loops @} ]
-@end smallexample
-
-@node GIMPLE Tests
-@section Support for testing GIMPLE passes
-
-As of gcc 7, C functions can be tagged with @code{__GIMPLE} to indicate
-that the function body will be GIMPLE, rather than C. The compiler requires
-the option @option{-fgimple} to enable this functionality. For example:
-
-@smallexample
-/* @{ dg-do compile @} */
-/* @{ dg-options "-O -fgimple" @} */
-
-void __GIMPLE (startwith ("dse2")) foo ()
-@{
- int a;
-
-bb_2:
- if (a > 4)
- goto bb_3;
- else
- goto bb_4;
-
-bb_3:
- a_2 = 10;
- goto bb_5;
-
-bb_4:
- a_3 = 20;
-
-bb_5:
- a_1 = __PHI (bb_3: a_2, bb_4: a_3);
- a_4 = a_1 + 4;
-
- return;
-@}
-@end smallexample
-
-The @code{startwith} argument indicates at which pass to begin.
-
-Use the dump modifier @code{-gimple} (e.g.@: @option{-fdump-tree-all-gimple})
-to make tree dumps more closely follow the format accepted by the GIMPLE
-parser.
-
-Example DejaGnu tests of GIMPLE can be seen in the source tree at
-@file{gcc/testsuite/gcc.dg/gimplefe-*.c}.
-
-The @code{__GIMPLE} parser is integrated with the C tokenizer and
-preprocessor, so it should be possible to use macros to build out
-test coverage.
-
-@node RTL Tests
-@section Support for testing RTL passes
-
-As of gcc 7, C functions can be tagged with @code{__RTL} to indicate that the
-function body will be RTL, rather than C. For example:
-
-@smallexample
-double __RTL (startwith ("ira")) test (struct foo *f, const struct bar *b)
-@{
- (function "test"
- [...snip; various directives go in here...]
- ) ;; function "test"
-@}
-@end smallexample
-
-The @code{startwith} argument indicates at which pass to begin.
-
-The parser expects the RTL body to be in the format emitted by this
-dumping function:
-
-@smallexample
-DEBUG_FUNCTION void
-print_rtx_function (FILE *outfile, function *fn, bool compact);
-@end smallexample
-
-when "compact" is true. So you can capture RTL in the correct format
-from the debugger using:
-
-@smallexample
-(gdb) print_rtx_function (stderr, cfun, true);
-@end smallexample
-
-and copy and paste the output into the body of the C function.
-
-Example DejaGnu tests of RTL can be seen in the source tree under
-@file{gcc/testsuite/gcc.dg/rtl}.
-
-The @code{__RTL} parser is not integrated with the C tokenizer or
-preprocessor, and works simply by reading the relevant lines within
-the braces. In particular, the RTL body must be on separate lines from
-the enclosing braces, and the preprocessor is not usable within it.
+++ /dev/null
-@c Copyright (C) 2000-2022 Free Software Foundation, Inc.
-@c This is part of the GCC manual.
-@c For copying conditions, see the file gcc.texi.
-
-@node Standards
-@chapter Language Standards Supported by GCC
-
-For each language compiled by GCC for which there is a standard, GCC
-attempts to follow one or more versions of that standard, possibly
-with some exceptions, and possibly with some extensions.
-
-@section C Language
-@cindex C standard
-@cindex C standards
-@cindex ANSI C standard
-@cindex ANSI C
-@cindex ANSI C89
-@cindex C89
-@cindex ANSI X3.159-1989
-@cindex X3.159-1989
-@cindex ISO C standard
-@cindex ISO C
-@cindex ISO C90
-@cindex ISO/IEC 9899
-@cindex ISO 9899
-@cindex C90
-@cindex ISO C94
-@cindex C94
-@cindex ISO C95
-@cindex C95
-@cindex ISO C99
-@cindex C99
-@cindex ISO C9X
-@cindex C9X
-@cindex ISO C11
-@cindex C11
-@cindex ISO C1X
-@cindex C1X
-@cindex ISO C17
-@cindex C17
-@cindex ISO C2X
-@cindex C2X
-@cindex Technical Corrigenda
-@cindex TC1
-@cindex Technical Corrigendum 1
-@cindex TC2
-@cindex Technical Corrigendum 2
-@cindex TC3
-@cindex Technical Corrigendum 3
-@cindex AMD1
-@cindex freestanding implementation
-@cindex freestanding environment
-@cindex hosted implementation
-@cindex hosted environment
-@findex __STDC_HOSTED__
-
-@opindex std
-@opindex ansi
-@opindex pedantic
-@opindex pedantic-errors
-The original ANSI C standard (X3.159-1989) was ratified in 1989 and
-published in 1990. This standard was ratified as an ISO standard
-(ISO/IEC 9899:1990) later in 1990. There were no technical
-differences between these publications, although the sections of the
-ANSI standard were renumbered and became clauses in the ISO standard.
-The ANSI
-standard, but not the ISO standard, also came with a Rationale
-document.
-This standard, in both its forms, is commonly known as @dfn{C89}, or
-occasionally as @dfn{C90}, from the dates of ratification.
-To select this standard in GCC, use one of the options
-@option{-ansi}, @option{-std=c90} or @option{-std=iso9899:1990}; to obtain
-all the diagnostics required by the standard, you should also specify
-@option{-pedantic} (or @option{-pedantic-errors} if you want them to be
-errors rather than warnings). @xref{C Dialect Options,,Options
-Controlling C Dialect}.
-
-Errors in the 1990 ISO C standard were corrected in two Technical
-Corrigenda published in 1994 and 1996. GCC does not support the
-uncorrected version.
-
-An amendment to the 1990 standard was published in 1995. This
-amendment added digraphs and @code{__STDC_VERSION__} to the language,
-but otherwise concerned the library. This amendment is commonly known
-as @dfn{AMD1}; the amended standard is sometimes known as @dfn{C94} or
-@dfn{C95}. To select this standard in GCC, use the option
-@option{-std=iso9899:199409} (with, as for other standard versions,
-@option{-pedantic} to receive all required diagnostics).
-
-A new edition of the ISO C standard was published in 1999 as ISO/IEC
-9899:1999, and is commonly known as @dfn{C99}. (While in
-development, drafts of this standard version were referred to as
-@dfn{C9X}.) GCC has substantially
-complete support for this standard version; see
-@uref{https://gcc.gnu.org/c99status.html} for details. To select this
-standard, use @option{-std=c99} or @option{-std=iso9899:1999}.
-
-Errors in the 1999 ISO C standard were corrected in three Technical
-Corrigenda published in 2001, 2004 and 2007. GCC does not support the
-uncorrected version.
-
-A fourth version of the C standard, known as @dfn{C11}, was published
-in 2011 as ISO/IEC 9899:2011. (While in development, drafts of this
-standard version were referred to as @dfn{C1X}.)
-GCC has substantially complete support
-for this standard, enabled with @option{-std=c11} or
-@option{-std=iso9899:2011}. A version with corrections integrated was
-prepared in 2017 and published in 2018 as ISO/IEC 9899:2018; it is
-known as @dfn{C17} and is supported with @option{-std=c17} or
-@option{-std=iso9899:2017}; the corrections are also applied with
-@option{-std=c11}, and the only difference between the options is the
-value of @code{__STDC_VERSION__}.
-
-A further version of the C standard, known as @dfn{C2X}, is under
-development; experimental and incomplete support for this is enabled
-with @option{-std=c2x}.
-
-By default, GCC provides some extensions to the C language that, on
-rare occasions conflict with the C standard. @xref{C
-Extensions,,Extensions to the C Language Family}.
-Some features that are part of the C99 standard
-are accepted as extensions in C90 mode, and some features that are part
-of the C11 standard are accepted as extensions in C90 and C99 modes.
-Use of the
-@option{-std} options listed above disables these extensions where
-they conflict with the C standard version selected. You may also
-select an extended version of the C language explicitly with
-@option{-std=gnu90} (for C90 with GNU extensions), @option{-std=gnu99}
-(for C99 with GNU extensions) or @option{-std=gnu11} (for C11 with GNU
-extensions).
-
-The default, if no C language dialect options are given,
-is @option{-std=gnu17}.
-
-The ISO C standard defines (in clause 4) two classes of conforming
-implementation. A @dfn{conforming hosted implementation} supports the
-whole standard including all the library facilities; a @dfn{conforming
-freestanding implementation} is only required to provide certain
-library facilities: those in @code{<float.h>}, @code{<limits.h>},
-@code{<stdarg.h>}, and @code{<stddef.h>}; since AMD1, also those in
-@code{<iso646.h>}; since C99, also those in @code{<stdbool.h>} and
-@code{<stdint.h>}; and since C11, also those in @code{<stdalign.h>}
-and @code{<stdnoreturn.h>}. In addition, complex types, added in C99, are not
-required for freestanding implementations.
-
-The standard also defines two environments for programs, a
-@dfn{freestanding environment}, required of all implementations and
-which may not have library facilities beyond those required of
-freestanding implementations, where the handling of program startup
-and termination are implementation-defined; and a @dfn{hosted
-environment}, which is not required, in which all the library
-facilities are provided and startup is through a function @code{int
-main (void)} or @code{int main (int, char *[])}. An OS kernel is an example
-of a program running in a freestanding environment;
-a program using the facilities of an
-operating system is an example of a program running in a hosted environment.
-
-@opindex ffreestanding
-GCC aims towards being usable as a conforming freestanding
-implementation, or as the compiler for a conforming hosted
-implementation. By default, it acts as the compiler for a hosted
-implementation, defining @code{__STDC_HOSTED__} as @code{1} and
-presuming that when the names of ISO C functions are used, they have
-the semantics defined in the standard. To make it act as a conforming
-freestanding implementation for a freestanding environment, use the
-option @option{-ffreestanding}; it then defines
-@code{__STDC_HOSTED__} to @code{0} and does not make assumptions about the
-meanings of function names from the standard library, with exceptions
-noted below. To build an OS kernel, you may well still need to make
-your own arrangements for linking and startup.
-@xref{C Dialect Options,,Options Controlling C Dialect}.
-
-GCC does not provide the library facilities required only of hosted
-implementations, nor yet all the facilities required by C99 of
-freestanding implementations on all platforms.
-To use the facilities of a hosted
-environment, you need to find them elsewhere (for example, in the
-GNU C library). @xref{Standard Libraries,,Standard Libraries}.
-
-Most of the compiler support routines used by GCC are present in
-@file{libgcc}, but there are a few exceptions. GCC requires the
-freestanding environment provide @code{memcpy}, @code{memmove},
-@code{memset} and @code{memcmp}.
-Finally, if @code{__builtin_trap} is used, and the target does
-not implement the @code{trap} pattern, then GCC emits a call
-to @code{abort}.
-
-For references to Technical Corrigenda, Rationale documents and
-information concerning the history of C that is available online, see
-@uref{https://gcc.gnu.org/readings.html}
-
-@section C++ Language
-
-GCC supports the original ISO C++ standard published in 1998,
-and the 2011, 2014, 2017 and mostly 2020 revisions.
-
-The original ISO C++ standard was published as the ISO standard (ISO/IEC
-14882:1998) and amended by a Technical Corrigenda published in 2003
-(ISO/IEC 14882:2003). These standards are referred to as C++98 and
-C++03, respectively. GCC implements the majority of C++98 (@code{export}
-is a notable exception) and most of the changes in C++03. To select
-this standard in GCC, use one of the options @option{-ansi},
-@option{-std=c++98}, or @option{-std=c++03}; to obtain all the diagnostics
-required by the standard, you should also specify @option{-pedantic} (or
-@option{-pedantic-errors} if you want them to be errors rather than
-warnings).
-
-A revised ISO C++ standard was published in 2011 as ISO/IEC
-14882:2011, and is referred to as C++11; before its publication it was
-commonly referred to as C++0x. C++11 contains several changes to the
-C++ language, all of which have been implemented in GCC@. For details
-see @uref{https://gcc.gnu.org/projects/@/cxx-status.html#cxx11}.
-To select this standard in GCC, use the option @option{-std=c++11}.
-
-Another revised ISO C++ standard was published in 2014 as ISO/IEC
-14882:2014, and is referred to as C++14; before its publication it was
-sometimes referred to as C++1y. C++14 contains several further
-changes to the C++ language, all of which have been implemented in GCC@.
-For details see @uref{https://gcc.gnu.org/projects/@/cxx-status.html#cxx14}.
-To select this standard in GCC, use the option @option{-std=c++14}.
-
-The C++ language was further revised in 2017 and ISO/IEC 14882:2017 was
-published. This is referred to as C++17, and before publication was
-often referred to as C++1z. GCC supports all the changes in that
-specification. For further details see
-@uref{https://gcc.gnu.org/projects/@/cxx-status.html#cxx17}. Use the option
-@option{-std=c++17} to select this variant of C++.
-
-Another revised ISO C++ standard was published in 2020 as ISO/IEC
-14882:2020, and is referred to as C++20; before its publication it was
-sometimes referred to as C++2a. GCC supports most of the changes in the
-new specification. For further details see
-@uref{https://gcc.gnu.org/projects/@/cxx-status.html#cxx20}.
-To select this standard in GCC, use the option @option{-std=c++20}.
-
-More information about the C++ standards is available on the ISO C++
-committee's web site at @uref{http://www.open-std.org/@/jtc1/@/sc22/@/wg21/}.
-
-To obtain all the diagnostics required by any of the standard versions
-described above you should specify @option{-pedantic}
-or @option{-pedantic-errors}, otherwise GCC will allow some non-ISO C++
-features as extensions. @xref{Warning Options}.
-
-By default, GCC also provides some additional extensions to the C++ language
-that on rare occasions conflict with the C++ standard. @xref{C++
-Dialect Options,Options Controlling C++ Dialect}. Use of the
-@option{-std} options listed above disables these extensions where they
-they conflict with the C++ standard version selected. You may also
-select an extended version of the C++ language explicitly with
-@option{-std=gnu++98} (for C++98 with GNU extensions), or
-@option{-std=gnu++11} (for C++11 with GNU extensions), or
-@option{-std=gnu++14} (for C++14 with GNU extensions), or
-@option{-std=gnu++17} (for C++17 with GNU extensions), or
-@option{-std=gnu++20} (for C++20 with GNU extensions).
-
-The default, if
-no C++ language dialect options are given, is @option{-std=gnu++17}.
-
-@section Objective-C and Objective-C++ Languages
-@cindex Objective-C
-@cindex Objective-C++
-
-GCC supports ``traditional'' Objective-C (also known as ``Objective-C
-1.0'') and contains support for the Objective-C exception and
-synchronization syntax. It has also support for a number of
-``Objective-C 2.0'' language extensions, including properties, fast
-enumeration (only for Objective-C), method attributes and the
-@@optional and @@required keywords in protocols. GCC supports
-Objective-C++ and features available in Objective-C are also available
-in Objective-C++@.
-
-GCC by default uses the GNU Objective-C runtime library, which is part
-of GCC and is not the same as the Apple/NeXT Objective-C runtime
-library used on Apple systems. There are a number of differences
-documented in this manual. The options @option{-fgnu-runtime} and
-@option{-fnext-runtime} allow you to switch between producing output
-that works with the GNU Objective-C runtime library and output that
-works with the Apple/NeXT Objective-C runtime library.
-
-There is no formal written standard for Objective-C or Objective-C++@.
-The authoritative manual on traditional Objective-C (1.0) is
-``Object-Oriented Programming and the Objective-C Language'':
-@uref{http://www.gnustep.org/@/resources/@/documentation/@/ObjectivCBook.pdf}
-is the original NeXTstep document.
-
-The Objective-C exception and synchronization syntax (that is, the
-keywords @code{@@try}, @code{@@throw}, @code{@@catch},
-@code{@@finally} and @code{@@synchronized}) is
-supported by GCC and is enabled with the option
-@option{-fobjc-exceptions}. The syntax is briefly documented in this
-manual and in the Objective-C 2.0 manuals from Apple.
-
-The Objective-C 2.0 language extensions and features are automatically
-enabled; they include properties (via the @code{@@property},
-@code{@@synthesize} and
-@code{@@dynamic keywords}), fast enumeration (not available in
-Objective-C++), attributes for methods (such as @code{deprecated},
-@code{noreturn}, @code{sentinel}, @code{format}),
-the @code{unused} attribute for method arguments, the
-@code{@@package} keyword for instance variables and the @code{@@optional} and
-@code{@@required} keywords in protocols. You can disable all these
-Objective-C 2.0 language extensions with the option
-@option{-fobjc-std=objc1}, which causes the compiler to recognize the
-same Objective-C language syntax recognized by GCC 4.0, and to produce
-an error if one of the new features is used.
-
-GCC has currently no support for non-fragile instance variables.
-
-The authoritative manual on Objective-C 2.0 is available from Apple:
-@itemize
-@item
-@uref{https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/ProgrammingWithObjectiveC/Introduction/Introduction.html}
-@end itemize
-
-For more information concerning the history of Objective-C that is
-available online, see @uref{https://gcc.gnu.org/readings.html}
-
-@section Go Language
-
-As of the GCC 4.7.1 release, GCC supports the Go 1 language standard,
-described at @uref{https://golang.org/doc/go1}.
-
-@section D language
-
-GCC supports the D 2.0 programming language. The D language itself is
-currently defined by its reference implementation and supporting language
-specification, described at @uref{https://dlang.org/spec/spec.html}.
-
-@section References for Other Languages
-
-@xref{Top, GNAT Reference Manual, About This Guide, gnat_rm,
-GNAT Reference Manual}, for information on standard
-conformance and compatibility of the Ada compiler.
-
-@xref{Standards,,Standards, gfortran, The GNU Fortran Compiler}, for details
-of standards supported by GNU Fortran.
+++ /dev/null
-@c Copyright (C) 1988-2022 Free Software Foundation, Inc.
-@c This is part of the GCC manual.
-@c For copying conditions, see the file gcc.texi.
-
-@node Target Macros
-@chapter Target Description Macros and Functions
-@cindex machine description macros
-@cindex target description macros
-@cindex macros, target description
-@cindex @file{tm.h} macros
-
-In addition to the file @file{@var{machine}.md}, a machine description
-includes a C header file conventionally given the name
-@file{@var{machine}.h} and a C source file named @file{@var{machine}.c}.
-The header file defines numerous macros that convey the information
-about the target machine that does not fit into the scheme of the
-@file{.md} file. The file @file{tm.h} should be a link to
-@file{@var{machine}.h}. The header file @file{config.h} includes
-@file{tm.h} and most compiler source files include @file{config.h}. The
-source file defines a variable @code{targetm}, which is a structure
-containing pointers to functions and data relating to the target
-machine. @file{@var{machine}.c} should also contain their definitions,
-if they are not defined elsewhere in GCC, and other functions called
-through the macros defined in the @file{.h} file.
-
-@menu
-* Target Structure:: The @code{targetm} variable.
-* Driver:: Controlling how the driver runs the compilation passes.
-* Run-time Target:: Defining @samp{-m} options like @option{-m68000} and @option{-m68020}.
-* Per-Function Data:: Defining data structures for per-function information.
-* Storage Layout:: Defining sizes and alignments of data.
-* Type Layout:: Defining sizes and properties of basic user data types.
-* Registers:: Naming and describing the hardware registers.
-* Register Classes:: Defining the classes of hardware registers.
-* Stack and Calling:: Defining which way the stack grows and by how much.
-* Varargs:: Defining the varargs macros.
-* Trampolines:: Code set up at run time to enter a nested function.
-* Library Calls:: Controlling how library routines are implicitly called.
-* Addressing Modes:: Defining addressing modes valid for memory operands.
-* Anchored Addresses:: Defining how @option{-fsection-anchors} should work.
-* Condition Code:: Defining how insns update the condition code.
-* Costs:: Defining relative costs of different operations.
-* Scheduling:: Adjusting the behavior of the instruction scheduler.
-* Sections:: Dividing storage into text, data, and other sections.
-* PIC:: Macros for position independent code.
-* Assembler Format:: Defining how to write insns and pseudo-ops to output.
-* Debugging Info:: Defining the format of debugging output.
-* Floating Point:: Handling floating point for cross-compilers.
-* Mode Switching:: Insertion of mode-switching instructions.
-* Target Attributes:: Defining target-specific uses of @code{__attribute__}.
-* Emulated TLS:: Emulated TLS support.
-* MIPS Coprocessors:: MIPS coprocessor support and how to customize it.
-* PCH Target:: Validity checking for precompiled headers.
-* C++ ABI:: Controlling C++ ABI changes.
-* D Language and ABI:: Controlling D ABI changes.
-* Named Address Spaces:: Adding support for named address spaces
-* Misc:: Everything else.
-@end menu
-
-@node Target Structure
-@section The Global @code{targetm} Variable
-@cindex target hooks
-@cindex target functions
-
-@deftypevar {struct gcc_target} targetm
-The target @file{.c} file must define the global @code{targetm} variable
-which contains pointers to functions and data relating to the target
-machine. The variable is declared in @file{target.h};
-@file{target-def.h} defines the macro @code{TARGET_INITIALIZER} which is
-used to initialize the variable, and macros for the default initializers
-for elements of the structure. The @file{.c} file should override those
-macros for which the default definition is inappropriate. For example:
-@smallexample
-#include "target.h"
-#include "target-def.h"
-
-/* @r{Initialize the GCC target structure.} */
-
-#undef TARGET_COMP_TYPE_ATTRIBUTES
-#define TARGET_COMP_TYPE_ATTRIBUTES @var{machine}_comp_type_attributes
-
-struct gcc_target targetm = TARGET_INITIALIZER;
-@end smallexample
-@end deftypevar
-
-Where a macro should be defined in the @file{.c} file in this manner to
-form part of the @code{targetm} structure, it is documented below as a
-``Target Hook'' with a prototype. Many macros will change in future
-from being defined in the @file{.h} file to being part of the
-@code{targetm} structure.
-
-Similarly, there is a @code{targetcm} variable for hooks that are
-specific to front ends for C-family languages, documented as ``C
-Target Hook''. This is declared in @file{c-family/c-target.h}, the
-initializer @code{TARGETCM_INITIALIZER} in
-@file{c-family/c-target-def.h}. If targets initialize @code{targetcm}
-themselves, they should set @code{target_has_targetcm=yes} in
-@file{config.gcc}; otherwise a default definition is used.
-
-Similarly, there is a @code{targetm_common} variable for hooks that
-are shared between the compiler driver and the compilers proper,
-documented as ``Common Target Hook''. This is declared in
-@file{common/common-target.h}, the initializer
-@code{TARGETM_COMMON_INITIALIZER} in
-@file{common/common-target-def.h}. If targets initialize
-@code{targetm_common} themselves, they should set
-@code{target_has_targetm_common=yes} in @file{config.gcc}; otherwise a
-default definition is used.
-
-Similarly, there is a @code{targetdm} variable for hooks that are
-specific to the D language front end, documented as ``D Target Hook''.
-This is declared in @file{d/d-target.h}, the initializer
-@code{TARGETDM_INITIALIZER} in @file{d/d-target-def.h}. If targets
-initialize @code{targetdm} themselves, they should set
-@code{target_has_targetdm=yes} in @file{config.gcc}; otherwise a default
-definition is used.
-
-@node Driver
-@section Controlling the Compilation Driver, @file{gcc}
-@cindex driver
-@cindex controlling the compilation driver
-
-@c prevent bad page break with this line
-You can control the compilation driver.
-
-@defmac DRIVER_SELF_SPECS
-A list of specs for the driver itself. It should be a suitable
-initializer for an array of strings, with no surrounding braces.
-
-The driver applies these specs to its own command line between loading
-default @file{specs} files (but not command-line specified ones) and
-choosing the multilib directory or running any subcommands. It
-applies them in the order given, so each spec can depend on the
-options added by earlier ones. It is also possible to remove options
-using @samp{%<@var{option}} in the usual way.
-
-This macro can be useful when a port has several interdependent target
-options. It provides a way of standardizing the command line so
-that the other specs are easier to write.
-
-Do not define this macro if it does not need to do anything.
-@end defmac
-
-@defmac OPTION_DEFAULT_SPECS
-A list of specs used to support configure-time default options (i.e.@:
-@option{--with} options) in the driver. It should be a suitable initializer
-for an array of structures, each containing two strings, without the
-outermost pair of surrounding braces.
-
-The first item in the pair is the name of the default. This must match
-the code in @file{config.gcc} for the target. The second item is a spec
-to apply if a default with this name was specified. The string
-@samp{%(VALUE)} in the spec will be replaced by the value of the default
-everywhere it occurs.
-
-The driver will apply these specs to its own command line between loading
-default @file{specs} files and processing @code{DRIVER_SELF_SPECS}, using
-the same mechanism as @code{DRIVER_SELF_SPECS}.
-
-Do not define this macro if it does not need to do anything.
-@end defmac
-
-@defmac CPP_SPEC
-A C string constant that tells the GCC driver program options to
-pass to CPP@. It can also specify how to translate options you
-give to GCC into options for GCC to pass to the CPP@.
-
-Do not define this macro if it does not need to do anything.
-@end defmac
-
-@defmac CPLUSPLUS_CPP_SPEC
-This macro is just like @code{CPP_SPEC}, but is used for C++, rather
-than C@. If you do not define this macro, then the value of
-@code{CPP_SPEC} (if any) will be used instead.
-@end defmac
-
-@defmac CC1_SPEC
-A C string constant that tells the GCC driver program options to
-pass to @code{cc1}, @code{cc1plus}, @code{f771}, and the other language
-front ends.
-It can also specify how to translate options you give to GCC into options
-for GCC to pass to front ends.
-
-Do not define this macro if it does not need to do anything.
-@end defmac
-
-@defmac CC1PLUS_SPEC
-A C string constant that tells the GCC driver program options to
-pass to @code{cc1plus}. It can also specify how to translate options you
-give to GCC into options for GCC to pass to the @code{cc1plus}.
-
-Do not define this macro if it does not need to do anything.
-Note that everything defined in CC1_SPEC is already passed to
-@code{cc1plus} so there is no need to duplicate the contents of
-CC1_SPEC in CC1PLUS_SPEC@.
-@end defmac
-
-@defmac ASM_SPEC
-A C string constant that tells the GCC driver program options to
-pass to the assembler. It can also specify how to translate options
-you give to GCC into options for GCC to pass to the assembler.
-See the file @file{sun3.h} for an example of this.
-
-Do not define this macro if it does not need to do anything.
-@end defmac
-
-@defmac ASM_FINAL_SPEC
-A C string constant that tells the GCC driver program how to
-run any programs which cleanup after the normal assembler.
-Normally, this is not needed. See the file @file{mips.h} for
-an example of this.
-
-Do not define this macro if it does not need to do anything.
-@end defmac
-
-@defmac AS_NEEDS_DASH_FOR_PIPED_INPUT
-Define this macro, with no value, if the driver should give the assembler
-an argument consisting of a single dash, @option{-}, to instruct it to
-read from its standard input (which will be a pipe connected to the
-output of the compiler proper). This argument is given after any
-@option{-o} option specifying the name of the output file.
-
-If you do not define this macro, the assembler is assumed to read its
-standard input if given no non-option arguments. If your assembler
-cannot read standard input at all, use a @samp{%@{pipe:%e@}} construct;
-see @file{mips.h} for instance.
-@end defmac
-
-@defmac LINK_SPEC
-A C string constant that tells the GCC driver program options to
-pass to the linker. It can also specify how to translate options you
-give to GCC into options for GCC to pass to the linker.
-
-Do not define this macro if it does not need to do anything.
-@end defmac
-
-@defmac LIB_SPEC
-Another C string constant used much like @code{LINK_SPEC}. The difference
-between the two is that @code{LIB_SPEC} is used at the end of the
-command given to the linker.
-
-If this macro is not defined, a default is provided that
-loads the standard C library from the usual place. See @file{gcc.cc}.
-@end defmac
-
-@defmac LIBGCC_SPEC
-Another C string constant that tells the GCC driver program
-how and when to place a reference to @file{libgcc.a} into the
-linker command line. This constant is placed both before and after
-the value of @code{LIB_SPEC}.
-
-If this macro is not defined, the GCC driver provides a default that
-passes the string @option{-lgcc} to the linker.
-@end defmac
-
-@defmac REAL_LIBGCC_SPEC
-By default, if @code{ENABLE_SHARED_LIBGCC} is defined, the
-@code{LIBGCC_SPEC} is not directly used by the driver program but is
-instead modified to refer to different versions of @file{libgcc.a}
-depending on the values of the command line flags @option{-static},
-@option{-shared}, @option{-static-libgcc}, and @option{-shared-libgcc}. On
-targets where these modifications are inappropriate, define
-@code{REAL_LIBGCC_SPEC} instead. @code{REAL_LIBGCC_SPEC} tells the
-driver how to place a reference to @file{libgcc} on the link command
-line, but, unlike @code{LIBGCC_SPEC}, it is used unmodified.
-@end defmac
-
-@defmac USE_LD_AS_NEEDED
-A macro that controls the modifications to @code{LIBGCC_SPEC}
-mentioned in @code{REAL_LIBGCC_SPEC}. If nonzero, a spec will be
-generated that uses @option{--as-needed} or equivalent options and the
-shared @file{libgcc} in place of the
-static exception handler library, when linking without any of
-@code{-static}, @code{-static-libgcc}, or @code{-shared-libgcc}.
-@end defmac
-
-@defmac LINK_EH_SPEC
-If defined, this C string constant is added to @code{LINK_SPEC}.
-When @code{USE_LD_AS_NEEDED} is zero or undefined, it also affects
-the modifications to @code{LIBGCC_SPEC} mentioned in
-@code{REAL_LIBGCC_SPEC}.
-@end defmac
-
-@defmac STARTFILE_SPEC
-Another C string constant used much like @code{LINK_SPEC}. The
-difference between the two is that @code{STARTFILE_SPEC} is used at
-the very beginning of the command given to the linker.
-
-If this macro is not defined, a default is provided that loads the
-standard C startup file from the usual place. See @file{gcc.cc}.
-@end defmac
-
-@defmac ENDFILE_SPEC
-Another C string constant used much like @code{LINK_SPEC}. The
-difference between the two is that @code{ENDFILE_SPEC} is used at
-the very end of the command given to the linker.
-
-Do not define this macro if it does not need to do anything.
-@end defmac
-
-@defmac THREAD_MODEL_SPEC
-GCC @code{-v} will print the thread model GCC was configured to use.
-However, this doesn't work on platforms that are multilibbed on thread
-models, such as AIX 4.3. On such platforms, define
-@code{THREAD_MODEL_SPEC} such that it evaluates to a string without
-blanks that names one of the recognized thread models. @code{%*}, the
-default value of this macro, will expand to the value of
-@code{thread_file} set in @file{config.gcc}.
-@end defmac
-
-@defmac SYSROOT_SUFFIX_SPEC
-Define this macro to add a suffix to the target sysroot when GCC is
-configured with a sysroot. This will cause GCC to search for usr/lib,
-et al, within sysroot+suffix.
-@end defmac
-
-@defmac SYSROOT_HEADERS_SUFFIX_SPEC
-Define this macro to add a headers_suffix to the target sysroot when
-GCC is configured with a sysroot. This will cause GCC to pass the
-updated sysroot+headers_suffix to CPP, causing it to search for
-usr/include, et al, within sysroot+headers_suffix.
-@end defmac
-
-@defmac EXTRA_SPECS
-Define this macro to provide additional specifications to put in the
-@file{specs} file that can be used in various specifications like
-@code{CC1_SPEC}.
-
-The definition should be an initializer for an array of structures,
-containing a string constant, that defines the specification name, and a
-string constant that provides the specification.
-
-Do not define this macro if it does not need to do anything.
-
-@code{EXTRA_SPECS} is useful when an architecture contains several
-related targets, which have various @code{@dots{}_SPECS} which are similar
-to each other, and the maintainer would like one central place to keep
-these definitions.
-
-For example, the PowerPC System V.4 targets use @code{EXTRA_SPECS} to
-define either @code{_CALL_SYSV} when the System V calling sequence is
-used or @code{_CALL_AIX} when the older AIX-based calling sequence is
-used.
-
-The @file{config/rs6000/rs6000.h} target file defines:
-
-@smallexample
-#define EXTRA_SPECS \
- @{ "cpp_sysv_default", CPP_SYSV_DEFAULT @},
-
-#define CPP_SYS_DEFAULT ""
-@end smallexample
-
-The @file{config/rs6000/sysv.h} target file defines:
-@smallexample
-#undef CPP_SPEC
-#define CPP_SPEC \
-"%@{posix: -D_POSIX_SOURCE @} \
-%@{mcall-sysv: -D_CALL_SYSV @} \
-%@{!mcall-sysv: %(cpp_sysv_default) @} \
-%@{msoft-float: -D_SOFT_FLOAT@} %@{mcpu=403: -D_SOFT_FLOAT@}"
-
-#undef CPP_SYSV_DEFAULT
-#define CPP_SYSV_DEFAULT "-D_CALL_SYSV"
-@end smallexample
-
-while the @file{config/rs6000/eabiaix.h} target file defines
-@code{CPP_SYSV_DEFAULT} as:
-
-@smallexample
-#undef CPP_SYSV_DEFAULT
-#define CPP_SYSV_DEFAULT "-D_CALL_AIX"
-@end smallexample
-@end defmac
-
-@defmac LINK_LIBGCC_SPECIAL_1
-Define this macro if the driver program should find the library
-@file{libgcc.a}. If you do not define this macro, the driver program will pass
-the argument @option{-lgcc} to tell the linker to do the search.
-@end defmac
-
-@defmac LINK_GCC_C_SEQUENCE_SPEC
-The sequence in which libgcc and libc are specified to the linker.
-By default this is @code{%G %L %G}.
-@end defmac
-
-@defmac POST_LINK_SPEC
-Define this macro to add additional steps to be executed after linker.
-The default value of this macro is empty string.
-@end defmac
-
-@defmac LINK_COMMAND_SPEC
-A C string constant giving the complete command line need to execute the
-linker. When you do this, you will need to update your port each time a
-change is made to the link command line within @file{gcc.cc}. Therefore,
-define this macro only if you need to completely redefine the command
-line for invoking the linker and there is no other way to accomplish
-the effect you need. Overriding this macro may be avoidable by overriding
-@code{LINK_GCC_C_SEQUENCE_SPEC} instead.
-@end defmac
-
-@deftypevr {Common Target Hook} bool TARGET_ALWAYS_STRIP_DOTDOT
-True if @file{..} components should always be removed from directory names
-computed relative to GCC's internal directories, false (default) if such
-components should be preserved and directory names containing them passed
-to other tools such as the linker.
-@end deftypevr
-
-@defmac MULTILIB_DEFAULTS
-Define this macro as a C expression for the initializer of an array of
-string to tell the driver program which options are defaults for this
-target and thus do not need to be handled specially when using
-@code{MULTILIB_OPTIONS}.
-
-Do not define this macro if @code{MULTILIB_OPTIONS} is not defined in
-the target makefile fragment or if none of the options listed in
-@code{MULTILIB_OPTIONS} are set by default.
-@xref{Target Fragment}.
-@end defmac
-
-@defmac RELATIVE_PREFIX_NOT_LINKDIR
-Define this macro to tell @command{gcc} that it should only translate
-a @option{-B} prefix into a @option{-L} linker option if the prefix
-indicates an absolute file name.
-@end defmac
-
-@defmac MD_EXEC_PREFIX
-If defined, this macro is an additional prefix to try after
-@code{STANDARD_EXEC_PREFIX}. @code{MD_EXEC_PREFIX} is not searched
-when the compiler is built as a cross
-compiler. If you define @code{MD_EXEC_PREFIX}, then be sure to add it
-to the list of directories used to find the assembler in @file{configure.ac}.
-@end defmac
-
-@defmac STANDARD_STARTFILE_PREFIX
-Define this macro as a C string constant if you wish to override the
-standard choice of @code{libdir} as the default prefix to
-try when searching for startup files such as @file{crt0.o}.
-@code{STANDARD_STARTFILE_PREFIX} is not searched when the compiler
-is built as a cross compiler.
-@end defmac
-
-@defmac STANDARD_STARTFILE_PREFIX_1
-Define this macro as a C string constant if you wish to override the
-standard choice of @code{/lib} as a prefix to try after the default prefix
-when searching for startup files such as @file{crt0.o}.
-@code{STANDARD_STARTFILE_PREFIX_1} is not searched when the compiler
-is built as a cross compiler.
-@end defmac
-
-@defmac STANDARD_STARTFILE_PREFIX_2
-Define this macro as a C string constant if you wish to override the
-standard choice of @code{/lib} as yet another prefix to try after the
-default prefix when searching for startup files such as @file{crt0.o}.
-@code{STANDARD_STARTFILE_PREFIX_2} is not searched when the compiler
-is built as a cross compiler.
-@end defmac
-
-@defmac MD_STARTFILE_PREFIX
-If defined, this macro supplies an additional prefix to try after the
-standard prefixes. @code{MD_EXEC_PREFIX} is not searched when the
-compiler is built as a cross compiler.
-@end defmac
-
-@defmac MD_STARTFILE_PREFIX_1
-If defined, this macro supplies yet another prefix to try after the
-standard prefixes. It is not searched when the compiler is built as a
-cross compiler.
-@end defmac
-
-@defmac INIT_ENVIRONMENT
-Define this macro as a C string constant if you wish to set environment
-variables for programs called by the driver, such as the assembler and
-loader. The driver passes the value of this macro to @code{putenv} to
-initialize the necessary environment variables.
-@end defmac
-
-@defmac LOCAL_INCLUDE_DIR
-Define this macro as a C string constant if you wish to override the
-standard choice of @file{/usr/local/include} as the default prefix to
-try when searching for local header files. @code{LOCAL_INCLUDE_DIR}
-comes before @code{NATIVE_SYSTEM_HEADER_DIR} (set in
-@file{config.gcc}, normally @file{/usr/include}) in the search order.
-
-Cross compilers do not search either @file{/usr/local/include} or its
-replacement.
-@end defmac
-
-@defmac NATIVE_SYSTEM_HEADER_COMPONENT
-The ``component'' corresponding to @code{NATIVE_SYSTEM_HEADER_DIR}.
-See @code{INCLUDE_DEFAULTS}, below, for the description of components.
-If you do not define this macro, no component is used.
-@end defmac
-
-@defmac INCLUDE_DEFAULTS
-Define this macro if you wish to override the entire default search path
-for include files. For a native compiler, the default search path
-usually consists of @code{GCC_INCLUDE_DIR}, @code{LOCAL_INCLUDE_DIR},
-@code{GPLUSPLUS_INCLUDE_DIR}, and
-@code{NATIVE_SYSTEM_HEADER_DIR}. In addition, @code{GPLUSPLUS_INCLUDE_DIR}
-and @code{GCC_INCLUDE_DIR} are defined automatically by @file{Makefile},
-and specify private search areas for GCC@. The directory
-@code{GPLUSPLUS_INCLUDE_DIR} is used only for C++ programs.
-
-The definition should be an initializer for an array of structures.
-Each array element should have four elements: the directory name (a
-string constant), the component name (also a string constant), a flag
-for C++-only directories,
-and a flag showing that the includes in the directory don't need to be
-wrapped in @code{extern @samp{C}} when compiling C++. Mark the end of
-the array with a null element.
-
-The component name denotes what GNU package the include file is part of,
-if any, in all uppercase letters. For example, it might be @samp{GCC}
-or @samp{BINUTILS}. If the package is part of a vendor-supplied
-operating system, code the component name as @samp{0}.
-
-For example, here is the definition used for VAX/VMS:
-
-@smallexample
-#define INCLUDE_DEFAULTS \
-@{ \
- @{ "GNU_GXX_INCLUDE:", "G++", 1, 1@}, \
- @{ "GNU_CC_INCLUDE:", "GCC", 0, 0@}, \
- @{ "SYS$SYSROOT:[SYSLIB.]", 0, 0, 0@}, \
- @{ ".", 0, 0, 0@}, \
- @{ 0, 0, 0, 0@} \
-@}
-@end smallexample
-@end defmac
-
-Here is the order of prefixes tried for exec files:
-
-@enumerate
-@item
-Any prefixes specified by the user with @option{-B}.
-
-@item
-The environment variable @code{GCC_EXEC_PREFIX} or, if @code{GCC_EXEC_PREFIX}
-is not set and the compiler has not been installed in the configure-time
-@var{prefix}, the location in which the compiler has actually been installed.
-
-@item
-The directories specified by the environment variable @code{COMPILER_PATH}.
-
-@item
-The macro @code{STANDARD_EXEC_PREFIX}, if the compiler has been installed
-in the configured-time @var{prefix}.
-
-@item
-The location @file{/usr/libexec/gcc/}, but only if this is a native compiler.
-
-@item
-The location @file{/usr/lib/gcc/}, but only if this is a native compiler.
-
-@item
-The macro @code{MD_EXEC_PREFIX}, if defined, but only if this is a native
-compiler.
-@end enumerate
-
-Here is the order of prefixes tried for startfiles:
-
-@enumerate
-@item
-Any prefixes specified by the user with @option{-B}.
-
-@item
-The environment variable @code{GCC_EXEC_PREFIX} or its automatically determined
-value based on the installed toolchain location.
-
-@item
-The directories specified by the environment variable @code{LIBRARY_PATH}
-(or port-specific name; native only, cross compilers do not use this).
-
-@item
-The macro @code{STANDARD_EXEC_PREFIX}, but only if the toolchain is installed
-in the configured @var{prefix} or this is a native compiler.
-
-@item
-The location @file{/usr/lib/gcc/}, but only if this is a native compiler.
-
-@item
-The macro @code{MD_EXEC_PREFIX}, if defined, but only if this is a native
-compiler.
-
-@item
-The macro @code{MD_STARTFILE_PREFIX}, if defined, but only if this is a
-native compiler, or we have a target system root.
-
-@item
-The macro @code{MD_STARTFILE_PREFIX_1}, if defined, but only if this is a
-native compiler, or we have a target system root.
-
-@item
-The macro @code{STANDARD_STARTFILE_PREFIX}, with any sysroot modifications.
-If this path is relative it will be prefixed by @code{GCC_EXEC_PREFIX} and
-the machine suffix or @code{STANDARD_EXEC_PREFIX} and the machine suffix.
-
-@item
-The macro @code{STANDARD_STARTFILE_PREFIX_1}, but only if this is a native
-compiler, or we have a target system root. The default for this macro is
-@file{/lib/}.
-
-@item
-The macro @code{STANDARD_STARTFILE_PREFIX_2}, but only if this is a native
-compiler, or we have a target system root. The default for this macro is
-@file{/usr/lib/}.
-@end enumerate
-
-@node Run-time Target
-@section Run-time Target Specification
-@cindex run-time target specification
-@cindex predefined macros
-@cindex target specifications
-
-@c prevent bad page break with this line
-Here are run-time target specifications.
-
-@defmac TARGET_CPU_CPP_BUILTINS ()
-This function-like macro expands to a block of code that defines
-built-in preprocessor macros and assertions for the target CPU, using
-the functions @code{builtin_define}, @code{builtin_define_std} and
-@code{builtin_assert}. When the front end
-calls this macro it provides a trailing semicolon, and since it has
-finished command line option processing your code can use those
-results freely.
-
-@code{builtin_assert} takes a string in the form you pass to the
-command-line option @option{-A}, such as @code{cpu=mips}, and creates
-the assertion. @code{builtin_define} takes a string in the form
-accepted by option @option{-D} and unconditionally defines the macro.
-
-@code{builtin_define_std} takes a string representing the name of an
-object-like macro. If it doesn't lie in the user's namespace,
-@code{builtin_define_std} defines it unconditionally. Otherwise, it
-defines a version with two leading underscores, and another version
-with two leading and trailing underscores, and defines the original
-only if an ISO standard was not requested on the command line. For
-example, passing @code{unix} defines @code{__unix}, @code{__unix__}
-and possibly @code{unix}; passing @code{_mips} defines @code{__mips},
-@code{__mips__} and possibly @code{_mips}, and passing @code{_ABI64}
-defines only @code{_ABI64}.
-
-You can also test for the C dialect being compiled. The variable
-@code{c_language} is set to one of @code{clk_c}, @code{clk_cplusplus}
-or @code{clk_objective_c}. Note that if we are preprocessing
-assembler, this variable will be @code{clk_c} but the function-like
-macro @code{preprocessing_asm_p()} will return true, so you might want
-to check for that first. If you need to check for strict ANSI, the
-variable @code{flag_iso} can be used. The function-like macro
-@code{preprocessing_trad_p()} can be used to check for traditional
-preprocessing.
-@end defmac
-
-@defmac TARGET_OS_CPP_BUILTINS ()
-Similarly to @code{TARGET_CPU_CPP_BUILTINS} but this macro is optional
-and is used for the target operating system instead.
-@end defmac
-
-@defmac TARGET_OBJFMT_CPP_BUILTINS ()
-Similarly to @code{TARGET_CPU_CPP_BUILTINS} but this macro is optional
-and is used for the target object format. @file{elfos.h} uses this
-macro to define @code{__ELF__}, so you probably do not need to define
-it yourself.
-@end defmac
-
-@deftypevar {extern int} target_flags
-This variable is declared in @file{options.h}, which is included before
-any target-specific headers.
-@end deftypevar
-
-@deftypevr {Common Target Hook} int TARGET_DEFAULT_TARGET_FLAGS
-This variable specifies the initial value of @code{target_flags}.
-Its default setting is 0.
-@end deftypevr
-
-@cindex optional hardware or system features
-@cindex features, optional, in system conventions
-
-@deftypefn {Common Target Hook} bool TARGET_HANDLE_OPTION (struct gcc_options *@var{opts}, struct gcc_options *@var{opts_set}, const struct cl_decoded_option *@var{decoded}, location_t @var{loc})
-This hook is called whenever the user specifies one of the
-target-specific options described by the @file{.opt} definition files
-(@pxref{Options}). It has the opportunity to do some option-specific
-processing and should return true if the option is valid. The default
-definition does nothing but return true.
-
-@var{decoded} specifies the option and its arguments. @var{opts} and
-@var{opts_set} are the @code{gcc_options} structures to be used for
-storing option state, and @var{loc} is the location at which the
-option was passed (@code{UNKNOWN_LOCATION} except for options passed
-via attributes).
-@end deftypefn
-
-@deftypefn {C Target Hook} bool TARGET_HANDLE_C_OPTION (size_t @var{code}, const char *@var{arg}, int @var{value})
-This target hook is called whenever the user specifies one of the
-target-specific C language family options described by the @file{.opt}
-definition files(@pxref{Options}). It has the opportunity to do some
-option-specific processing and should return true if the option is
-valid. The arguments are like for @code{TARGET_HANDLE_OPTION}. The
-default definition does nothing but return false.
-
-In general, you should use @code{TARGET_HANDLE_OPTION} to handle
-options. However, if processing an option requires routines that are
-only available in the C (and related language) front ends, then you
-should use @code{TARGET_HANDLE_C_OPTION} instead.
-@end deftypefn
-
-@deftypefn {C Target Hook} tree TARGET_OBJC_CONSTRUCT_STRING_OBJECT (tree @var{string})
-Targets may provide a string object type that can be used within
-and between C, C++ and their respective Objective-C dialects.
-A string object might, for example, embed encoding and length information.
-These objects are considered opaque to the compiler and handled as references.
-An ideal implementation makes the composition of the string object
-match that of the Objective-C @code{NSString} (@code{NXString} for GNUStep),
-allowing efficient interworking between C-only and Objective-C code.
-If a target implements string objects then this hook should return a
-reference to such an object constructed from the normal `C' string
-representation provided in @var{string}.
-At present, the hook is used by Objective-C only, to obtain a
- common-format string object when the target provides one.
-@end deftypefn
-
-@deftypefn {C Target Hook} void TARGET_OBJC_DECLARE_UNRESOLVED_CLASS_REFERENCE (const char *@var{classname})
-Declare that Objective C class @var{classname} is referenced
-by the current TU.
-@end deftypefn
-
-@deftypefn {C Target Hook} void TARGET_OBJC_DECLARE_CLASS_DEFINITION (const char *@var{classname})
-Declare that Objective C class @var{classname} is defined
-by the current TU.
-@end deftypefn
-
-@deftypefn {C Target Hook} bool TARGET_STRING_OBJECT_REF_TYPE_P (const_tree @var{stringref})
-If a target implements string objects then this hook should return
-@code{true} if @var{stringref} is a valid reference to such an object.
-@end deftypefn
-
-@deftypefn {C Target Hook} void TARGET_CHECK_STRING_OBJECT_FORMAT_ARG (tree @var{format_arg}, tree @var{args_list})
-If a target implements string objects then this hook should
-provide a facility to check the function arguments in @var{args_list}
-against the format specifiers in @var{format_arg} where the type of
-@var{format_arg} is one recognized as a valid string reference type.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_OVERRIDE_OPTIONS_AFTER_CHANGE (void)
-This target function is similar to the hook @code{TARGET_OPTION_OVERRIDE}
-but is called when the optimize level is changed via an attribute or
-pragma or when it is reset at the end of the code affected by the
-attribute or pragma. It is not called at the beginning of compilation
-when @code{TARGET_OPTION_OVERRIDE} is called so if you want to perform these
-actions then, you should have @code{TARGET_OPTION_OVERRIDE} call
-@code{TARGET_OVERRIDE_OPTIONS_AFTER_CHANGE}.
-@end deftypefn
-
-@defmac C_COMMON_OVERRIDE_OPTIONS
-This is similar to the @code{TARGET_OPTION_OVERRIDE} hook
-but is only used in the C
-language frontends (C, Objective-C, C++, Objective-C++) and so can be
-used to alter option flag variables which only exist in those
-frontends.
-@end defmac
-
-@deftypevr {Common Target Hook} {const struct default_options *} TARGET_OPTION_OPTIMIZATION_TABLE
-Some machines may desire to change what optimizations are performed for
-various optimization levels. This variable, if defined, describes
-options to enable at particular sets of optimization levels. These
-options are processed once
-just after the optimization level is determined and before the remainder
-of the command options have been parsed, so may be overridden by other
-options passed explicitly.
-
-This processing is run once at program startup and when the optimization
-options are changed via @code{#pragma GCC optimize} or by using the
-@code{optimize} attribute.
-@end deftypevr
-
-@deftypefn {Common Target Hook} void TARGET_OPTION_INIT_STRUCT (struct gcc_options *@var{opts})
-Set target-dependent initial values of fields in @var{opts}.
-@end deftypefn
-
-@deftypefn {Common Target Hook} {const char *} TARGET_COMPUTE_MULTILIB (const struct switchstr *@var{switches}, int @var{n_switches}, const char *@var{multilib_dir}, const char *@var{multilib_defaults}, const char *@var{multilib_select}, const char *@var{multilib_matches}, const char *@var{multilib_exclusions}, const char *@var{multilib_reuse})
-Some targets like RISC-V might have complicated multilib reuse rules which
-are hard to implement with the current multilib scheme. This hook allows
-targets to override the result from the built-in multilib mechanism.
-@var{switches} is the raw option list with @var{n_switches} items;
-@var{multilib_dir} is the multi-lib result which is computed by the built-in
-multi-lib mechanism;
-@var{multilib_defaults} is the default options list for multi-lib;
-@var{multilib_select} is the string containing the list of supported
-multi-libs, and the option checking list.
-@var{multilib_matches}, @var{multilib_exclusions}, and @var{multilib_reuse}
-are corresponding to @var{MULTILIB_MATCHES}, @var{MULTILIB_EXCLUSIONS},
-and @var{MULTILIB_REUSE}.
-The default definition does nothing but return @var{multilib_dir} directly.
-@end deftypefn
-
-
-@defmac SWITCHABLE_TARGET
-Some targets need to switch between substantially different subtargets
-during compilation. For example, the MIPS target has one subtarget for
-the traditional MIPS architecture and another for MIPS16. Source code
-can switch between these two subarchitectures using the @code{mips16}
-and @code{nomips16} attributes.
-
-Such subtargets can differ in things like the set of available
-registers, the set of available instructions, the costs of various
-operations, and so on. GCC caches a lot of this type of information
-in global variables, and recomputing them for each subtarget takes a
-significant amount of time. The compiler therefore provides a facility
-for maintaining several versions of the global variables and quickly
-switching between them; see @file{target-globals.h} for details.
-
-Define this macro to 1 if your target needs this facility. The default
-is 0.
-@end defmac
-
-@deftypefn {Target Hook} bool TARGET_FLOAT_EXCEPTIONS_ROUNDING_SUPPORTED_P (void)
-Returns true if the target supports IEEE 754 floating-point exceptions
-and rounding modes, false otherwise. This is intended to relate to the
-@code{float} and @code{double} types, but not necessarily @code{long double}.
-By default, returns true if the @code{adddf3} instruction pattern is
-available and false otherwise, on the assumption that hardware floating
-point supports exceptions and rounding modes but software floating point
-does not.
-@end deftypefn
-
-@node Per-Function Data
-@section Defining data structures for per-function information.
-@cindex per-function data
-@cindex data structures
-
-If the target needs to store information on a per-function basis, GCC
-provides a macro and a couple of variables to allow this. Note, just
-using statics to store the information is a bad idea, since GCC supports
-nested functions, so you can be halfway through encoding one function
-when another one comes along.
-
-GCC defines a data structure called @code{struct function} which
-contains all of the data specific to an individual function. This
-structure contains a field called @code{machine} whose type is
-@code{struct machine_function *}, which can be used by targets to point
-to their own specific data.
-
-If a target needs per-function specific data it should define the type
-@code{struct machine_function} and also the macro @code{INIT_EXPANDERS}.
-This macro should be used to initialize the function pointer
-@code{init_machine_status}. This pointer is explained below.
-
-One typical use of per-function, target specific data is to create an
-RTX to hold the register containing the function's return address. This
-RTX can then be used to implement the @code{__builtin_return_address}
-function, for level 0.
-
-Note---earlier implementations of GCC used a single data area to hold
-all of the per-function information. Thus when processing of a nested
-function began the old per-function data had to be pushed onto a
-stack, and when the processing was finished, it had to be popped off the
-stack. GCC used to provide function pointers called
-@code{save_machine_status} and @code{restore_machine_status} to handle
-the saving and restoring of the target specific information. Since the
-single data area approach is no longer used, these pointers are no
-longer supported.
-
-@defmac INIT_EXPANDERS
-Macro called to initialize any target specific information. This macro
-is called once per function, before generation of any RTL has begun.
-The intention of this macro is to allow the initialization of the
-function pointer @code{init_machine_status}.
-@end defmac
-
-@deftypevar {void (*)(struct function *)} init_machine_status
-If this function pointer is non-@code{NULL} it will be called once per
-function, before function compilation starts, in order to allow the
-target to perform any target specific initialization of the
-@code{struct function} structure. It is intended that this would be
-used to initialize the @code{machine} of that structure.
-
-@code{struct machine_function} structures are expected to be freed by GC@.
-Generally, any memory that they reference must be allocated by using
-GC allocation, including the structure itself.
-@end deftypevar
-
-@node Storage Layout
-@section Storage Layout
-@cindex storage layout
-
-Note that the definitions of the macros in this table which are sizes or
-alignments measured in bits do not need to be constant. They can be C
-expressions that refer to static variables, such as the @code{target_flags}.
-@xref{Run-time Target}.
-
-@defmac BITS_BIG_ENDIAN
-Define this macro to have the value 1 if the most significant bit in a
-byte has the lowest number; otherwise define it to have the value zero.
-This means that bit-field instructions count from the most significant
-bit. If the machine has no bit-field instructions, then this must still
-be defined, but it doesn't matter which value it is defined to. This
-macro need not be a constant.
-
-This macro does not affect the way structure fields are packed into
-bytes or words; that is controlled by @code{BYTES_BIG_ENDIAN}.
-@end defmac
-
-@defmac BYTES_BIG_ENDIAN
-Define this macro to have the value 1 if the most significant byte in a
-word has the lowest number. This macro need not be a constant.
-@end defmac
-
-@defmac WORDS_BIG_ENDIAN
-Define this macro to have the value 1 if, in a multiword object, the
-most significant word has the lowest number. This applies to both
-memory locations and registers; see @code{REG_WORDS_BIG_ENDIAN} if the
-order of words in memory is not the same as the order in registers. This
-macro need not be a constant.
-@end defmac
-
-@defmac REG_WORDS_BIG_ENDIAN
-On some machines, the order of words in a multiword object differs between
-registers in memory. In such a situation, define this macro to describe
-the order of words in a register. The macro @code{WORDS_BIG_ENDIAN} controls
-the order of words in memory.
-@end defmac
-
-@defmac FLOAT_WORDS_BIG_ENDIAN
-Define this macro to have the value 1 if @code{DFmode}, @code{XFmode} or
-@code{TFmode} floating point numbers are stored in memory with the word
-containing the sign bit at the lowest address; otherwise define it to
-have the value 0. This macro need not be a constant.
-
-You need not define this macro if the ordering is the same as for
-multi-word integers.
-@end defmac
-
-@defmac BITS_PER_WORD
-Number of bits in a word. If you do not define this macro, the default
-is @code{BITS_PER_UNIT * UNITS_PER_WORD}.
-@end defmac
-
-@defmac MAX_BITS_PER_WORD
-Maximum number of bits in a word. If this is undefined, the default is
-@code{BITS_PER_WORD}. Otherwise, it is the constant value that is the
-largest value that @code{BITS_PER_WORD} can have at run-time.
-@end defmac
-
-@defmac UNITS_PER_WORD
-Number of storage units in a word; normally the size of a general-purpose
-register, a power of two from 1 or 8.
-@end defmac
-
-@defmac MIN_UNITS_PER_WORD
-Minimum number of units in a word. If this is undefined, the default is
-@code{UNITS_PER_WORD}. Otherwise, it is the constant value that is the
-smallest value that @code{UNITS_PER_WORD} can have at run-time.
-@end defmac
-
-@defmac POINTER_SIZE
-Width of a pointer, in bits. You must specify a value no wider than the
-width of @code{Pmode}. If it is not equal to the width of @code{Pmode},
-you must define @code{POINTERS_EXTEND_UNSIGNED}. If you do not specify
-a value the default is @code{BITS_PER_WORD}.
-@end defmac
-
-@defmac POINTERS_EXTEND_UNSIGNED
-A C expression that determines how pointers should be extended from
-@code{ptr_mode} to either @code{Pmode} or @code{word_mode}. It is
-greater than zero if pointers should be zero-extended, zero if they
-should be sign-extended, and negative if some other sort of conversion
-is needed. In the last case, the extension is done by the target's
-@code{ptr_extend} instruction.
-
-You need not define this macro if the @code{ptr_mode}, @code{Pmode}
-and @code{word_mode} are all the same width.
-@end defmac
-
-@defmac PROMOTE_MODE (@var{m}, @var{unsignedp}, @var{type})
-A macro to update @var{m} and @var{unsignedp} when an object whose type
-is @var{type} and which has the specified mode and signedness is to be
-stored in a register. This macro is only called when @var{type} is a
-scalar type.
-
-On most RISC machines, which only have operations that operate on a full
-register, define this macro to set @var{m} to @code{word_mode} if
-@var{m} is an integer mode narrower than @code{BITS_PER_WORD}. In most
-cases, only integer modes should be widened because wider-precision
-floating-point operations are usually more expensive than their narrower
-counterparts.
-
-For most machines, the macro definition does not change @var{unsignedp}.
-However, some machines, have instructions that preferentially handle
-either signed or unsigned quantities of certain modes. For example, on
-the DEC Alpha, 32-bit loads from memory and 32-bit add instructions
-sign-extend the result to 64 bits. On such machines, set
-@var{unsignedp} according to which kind of extension is more efficient.
-
-Do not define this macro if it would never modify @var{m}.
-@end defmac
-
-@deftypefn {Target Hook} {enum flt_eval_method} TARGET_C_EXCESS_PRECISION (enum excess_precision_type @var{type})
-Return a value, with the same meaning as the C99 macro
-@code{FLT_EVAL_METHOD} that describes which excess precision should be
-applied. @var{type} is either @code{EXCESS_PRECISION_TYPE_IMPLICIT},
-@code{EXCESS_PRECISION_TYPE_FAST},
-@code{EXCESS_PRECISION_TYPE_STANDARD}, or
-@code{EXCESS_PRECISION_TYPE_FLOAT16}. For
-@code{EXCESS_PRECISION_TYPE_IMPLICIT}, the target should return which
-precision and range operations will be implictly evaluated in regardless
-of the excess precision explicitly added. For
-@code{EXCESS_PRECISION_TYPE_STANDARD},
-@code{EXCESS_PRECISION_TYPE_FLOAT16}, and
-@code{EXCESS_PRECISION_TYPE_FAST}, the target should return the
-explicit excess precision that should be added depending on the
-value set for @option{-fexcess-precision=@r{[}standard@r{|}fast@r{|}16@r{]}}.
-Note that unpredictable explicit excess precision does not make sense,
-so a target should never return @code{FLT_EVAL_METHOD_UNPREDICTABLE}
-when @var{type} is @code{EXCESS_PRECISION_TYPE_STANDARD},
-@code{EXCESS_PRECISION_TYPE_FLOAT16} or
-@code{EXCESS_PRECISION_TYPE_FAST}.
-@end deftypefn
-Return a value, with the same meaning as the C99 macro
-@code{FLT_EVAL_METHOD} that describes which excess precision should be
-applied.
-
-@deftypefn {Target Hook} machine_mode TARGET_PROMOTE_FUNCTION_MODE (const_tree @var{type}, machine_mode @var{mode}, int *@var{punsignedp}, const_tree @var{funtype}, int @var{for_return})
-Like @code{PROMOTE_MODE}, but it is applied to outgoing function arguments or
-function return values. The target hook should return the new mode
-and possibly change @code{*@var{punsignedp}} if the promotion should
-change signedness. This function is called only for scalar @emph{or
-pointer} types.
-
-@var{for_return} allows to distinguish the promotion of arguments and
-return values. If it is @code{1}, a return value is being promoted and
-@code{TARGET_FUNCTION_VALUE} must perform the same promotions done here.
-If it is @code{2}, the returned mode should be that of the register in
-which an incoming parameter is copied, or the outgoing result is computed;
-then the hook should return the same mode as @code{promote_mode}, though
-the signedness may be different.
-
-@var{type} can be NULL when promoting function arguments of libcalls.
-
-The default is to not promote arguments and return values. You can
-also define the hook to @code{default_promote_function_mode_always_promote}
-if you would like to apply the same rules given by @code{PROMOTE_MODE}.
-@end deftypefn
-
-@defmac PARM_BOUNDARY
-Normal alignment required for function parameters on the stack, in
-bits. All stack parameters receive at least this much alignment
-regardless of data type. On most machines, this is the same as the
-size of an integer.
-@end defmac
-
-@defmac STACK_BOUNDARY
-Define this macro to the minimum alignment enforced by hardware for the
-stack pointer on this machine. The definition is a C expression for the
-desired alignment (measured in bits). This value is used as a default
-if @code{PREFERRED_STACK_BOUNDARY} is not defined. On most machines,
-this should be the same as @code{PARM_BOUNDARY}.
-@end defmac
-
-@defmac PREFERRED_STACK_BOUNDARY
-Define this macro if you wish to preserve a certain alignment for the
-stack pointer, greater than what the hardware enforces. The definition
-is a C expression for the desired alignment (measured in bits). This
-macro must evaluate to a value equal to or larger than
-@code{STACK_BOUNDARY}.
-@end defmac
-
-@defmac INCOMING_STACK_BOUNDARY
-Define this macro if the incoming stack boundary may be different
-from @code{PREFERRED_STACK_BOUNDARY}. This macro must evaluate
-to a value equal to or larger than @code{STACK_BOUNDARY}.
-@end defmac
-
-@defmac FUNCTION_BOUNDARY
-Alignment required for a function entry point, in bits.
-@end defmac
-
-@defmac BIGGEST_ALIGNMENT
-Biggest alignment that any data type can require on this machine, in
-bits. Note that this is not the biggest alignment that is supported,
-just the biggest alignment that, when violated, may cause a fault.
-@end defmac
-
-@deftypevr {Target Hook} HOST_WIDE_INT TARGET_ABSOLUTE_BIGGEST_ALIGNMENT
-If defined, this target hook specifies the absolute biggest alignment
-that a type or variable can have on this machine, otherwise,
-@code{BIGGEST_ALIGNMENT} is used.
-@end deftypevr
-
-@defmac MALLOC_ABI_ALIGNMENT
-Alignment, in bits, a C conformant malloc implementation has to
-provide. If not defined, the default value is @code{BITS_PER_WORD}.
-@end defmac
-
-@defmac ATTRIBUTE_ALIGNED_VALUE
-Alignment used by the @code{__attribute__ ((aligned))} construct. If
-not defined, the default value is @code{BIGGEST_ALIGNMENT}.
-@end defmac
-
-@defmac MINIMUM_ATOMIC_ALIGNMENT
-If defined, the smallest alignment, in bits, that can be given to an
-object that can be referenced in one operation, without disturbing any
-nearby object. Normally, this is @code{BITS_PER_UNIT}, but may be larger
-on machines that don't have byte or half-word store operations.
-@end defmac
-
-@defmac BIGGEST_FIELD_ALIGNMENT
-Biggest alignment that any structure or union field can require on this
-machine, in bits. If defined, this overrides @code{BIGGEST_ALIGNMENT} for
-structure and union fields only, unless the field alignment has been set
-by the @code{__attribute__ ((aligned (@var{n})))} construct.
-@end defmac
-
-@defmac ADJUST_FIELD_ALIGN (@var{field}, @var{type}, @var{computed})
-An expression for the alignment of a structure field @var{field} of
-type @var{type} if the alignment computed in the usual way (including
-applying of @code{BIGGEST_ALIGNMENT} and @code{BIGGEST_FIELD_ALIGNMENT} to the
-alignment) is @var{computed}. It overrides alignment only if the
-field alignment has not been set by the
-@code{__attribute__ ((aligned (@var{n})))} construct. Note that @var{field}
-may be @code{NULL_TREE} in case we just query for the minimum alignment
-of a field of type @var{type} in structure context.
-@end defmac
-
-@defmac MAX_STACK_ALIGNMENT
-Biggest stack alignment guaranteed by the backend. Use this macro
-to specify the maximum alignment of a variable on stack.
-
-If not defined, the default value is @code{STACK_BOUNDARY}.
-
-@c FIXME: The default should be @code{PREFERRED_STACK_BOUNDARY}.
-@c But the fix for PR 32893 indicates that we can only guarantee
-@c maximum stack alignment on stack up to @code{STACK_BOUNDARY}, not
-@c @code{PREFERRED_STACK_BOUNDARY}, if stack alignment isn't supported.
-@end defmac
-
-@defmac MAX_OFILE_ALIGNMENT
-Biggest alignment supported by the object file format of this machine.
-Use this macro to limit the alignment which can be specified using the
-@code{__attribute__ ((aligned (@var{n})))} construct for functions and
-objects with static storage duration. The alignment of automatic
-objects may exceed the object file format maximum up to the maximum
-supported by GCC. If not defined, the default value is
-@code{BIGGEST_ALIGNMENT}.
-
-On systems that use ELF, the default (in @file{config/elfos.h}) is
-the largest supported 32-bit ELF section alignment representable on
-a 32-bit host e.g.@: @samp{(((uint64_t) 1 << 28) * 8)}.
-On 32-bit ELF the largest supported section alignment in bits is
-@samp{(0x80000000 * 8)}, but this is not representable on 32-bit hosts.
-@end defmac
-
-@deftypefn {Target Hook} void TARGET_LOWER_LOCAL_DECL_ALIGNMENT (tree @var{decl})
-Define this hook to lower alignment of local, parm or result
-decl @samp{(@var{decl})}.
-@end deftypefn
-
-@deftypefn {Target Hook} HOST_WIDE_INT TARGET_STATIC_RTX_ALIGNMENT (machine_mode @var{mode})
-This hook returns the preferred alignment in bits for a
-statically-allocated rtx, such as a constant pool entry. @var{mode}
-is the mode of the rtx. The default implementation returns
-@samp{GET_MODE_ALIGNMENT (@var{mode})}.
-@end deftypefn
-
-@defmac DATA_ALIGNMENT (@var{type}, @var{basic-align})
-If defined, a C expression to compute the alignment for a variable in
-the static store. @var{type} is the data type, and @var{basic-align} is
-the alignment that the object would ordinarily have. The value of this
-macro is used instead of that alignment to align the object.
-
-If this macro is not defined, then @var{basic-align} is used.
-
-@findex strcpy
-One use of this macro is to increase alignment of medium-size data to
-make it all fit in fewer cache lines. Another is to cause character
-arrays to be word-aligned so that @code{strcpy} calls that copy
-constants to character arrays can be done inline.
-@end defmac
-
-@defmac DATA_ABI_ALIGNMENT (@var{type}, @var{basic-align})
-Similar to @code{DATA_ALIGNMENT}, but for the cases where the ABI mandates
-some alignment increase, instead of optimization only purposes. E.g.@
-AMD x86-64 psABI says that variables with array type larger than 15 bytes
-must be aligned to 16 byte boundaries.
-
-If this macro is not defined, then @var{basic-align} is used.
-@end defmac
-
-@deftypefn {Target Hook} HOST_WIDE_INT TARGET_CONSTANT_ALIGNMENT (const_tree @var{constant}, HOST_WIDE_INT @var{basic_align})
-This hook returns the alignment in bits of a constant that is being
-placed in memory. @var{constant} is the constant and @var{basic_align}
-is the alignment that the object would ordinarily have.
-
-The default definition just returns @var{basic_align}.
-
-The typical use of this hook is to increase alignment for string
-constants to be word aligned so that @code{strcpy} calls that copy
-constants can be done inline. The function
-@code{constant_alignment_word_strings} provides such a definition.
-@end deftypefn
-
-@defmac LOCAL_ALIGNMENT (@var{type}, @var{basic-align})
-If defined, a C expression to compute the alignment for a variable in
-the local store. @var{type} is the data type, and @var{basic-align} is
-the alignment that the object would ordinarily have. The value of this
-macro is used instead of that alignment to align the object.
-
-If this macro is not defined, then @var{basic-align} is used.
-
-One use of this macro is to increase alignment of medium-size data to
-make it all fit in fewer cache lines.
-
-If the value of this macro has a type, it should be an unsigned type.
-@end defmac
-
-@deftypefn {Target Hook} HOST_WIDE_INT TARGET_VECTOR_ALIGNMENT (const_tree @var{type})
-This hook can be used to define the alignment for a vector of type
-@var{type}, in order to comply with a platform ABI. The default is to
-require natural alignment for vector types. The alignment returned by
-this hook must be a power-of-two multiple of the default alignment of
-the vector element type.
-@end deftypefn
-
-@defmac STACK_SLOT_ALIGNMENT (@var{type}, @var{mode}, @var{basic-align})
-If defined, a C expression to compute the alignment for stack slot.
-@var{type} is the data type, @var{mode} is the widest mode available,
-and @var{basic-align} is the alignment that the slot would ordinarily
-have. The value of this macro is used instead of that alignment to
-align the slot.
-
-If this macro is not defined, then @var{basic-align} is used when
-@var{type} is @code{NULL}. Otherwise, @code{LOCAL_ALIGNMENT} will
-be used.
-
-This macro is to set alignment of stack slot to the maximum alignment
-of all possible modes which the slot may have.
-
-If the value of this macro has a type, it should be an unsigned type.
-@end defmac
-
-@defmac LOCAL_DECL_ALIGNMENT (@var{decl})
-If defined, a C expression to compute the alignment for a local
-variable @var{decl}.
-
-If this macro is not defined, then
-@code{LOCAL_ALIGNMENT (TREE_TYPE (@var{decl}), DECL_ALIGN (@var{decl}))}
-is used.
-
-One use of this macro is to increase alignment of medium-size data to
-make it all fit in fewer cache lines.
-
-If the value of this macro has a type, it should be an unsigned type.
-@end defmac
-
-@defmac MINIMUM_ALIGNMENT (@var{exp}, @var{mode}, @var{align})
-If defined, a C expression to compute the minimum required alignment
-for dynamic stack realignment purposes for @var{exp} (a type or decl),
-@var{mode}, assuming normal alignment @var{align}.
-
-If this macro is not defined, then @var{align} will be used.
-@end defmac
-
-@defmac EMPTY_FIELD_BOUNDARY
-Alignment in bits to be given to a structure bit-field that follows an
-empty field such as @code{int : 0;}.
-
-If @code{PCC_BITFIELD_TYPE_MATTERS} is true, it overrides this macro.
-@end defmac
-
-@defmac STRUCTURE_SIZE_BOUNDARY
-Number of bits which any structure or union's size must be a multiple of.
-Each structure or union's size is rounded up to a multiple of this.
-
-If you do not define this macro, the default is the same as
-@code{BITS_PER_UNIT}.
-@end defmac
-
-@defmac STRICT_ALIGNMENT
-Define this macro to be the value 1 if instructions will fail to work
-if given data not on the nominal alignment. If instructions will merely
-go slower in that case, define this macro as 0.
-@end defmac
-
-@defmac PCC_BITFIELD_TYPE_MATTERS
-Define this if you wish to imitate the way many other C compilers handle
-alignment of bit-fields and the structures that contain them.
-
-The behavior is that the type written for a named bit-field (@code{int},
-@code{short}, or other integer type) imposes an alignment for the entire
-structure, as if the structure really did contain an ordinary field of
-that type. In addition, the bit-field is placed within the structure so
-that it would fit within such a field, not crossing a boundary for it.
-
-Thus, on most machines, a named bit-field whose type is written as
-@code{int} would not cross a four-byte boundary, and would force
-four-byte alignment for the whole structure. (The alignment used may
-not be four bytes; it is controlled by the other alignment parameters.)
-
-An unnamed bit-field will not affect the alignment of the containing
-structure.
-
-If the macro is defined, its definition should be a C expression;
-a nonzero value for the expression enables this behavior.
-
-Note that if this macro is not defined, or its value is zero, some
-bit-fields may cross more than one alignment boundary. The compiler can
-support such references if there are @samp{insv}, @samp{extv}, and
-@samp{extzv} insns that can directly reference memory.
-
-The other known way of making bit-fields work is to define
-@code{STRUCTURE_SIZE_BOUNDARY} as large as @code{BIGGEST_ALIGNMENT}.
-Then every structure can be accessed with fullwords.
-
-Unless the machine has bit-field instructions or you define
-@code{STRUCTURE_SIZE_BOUNDARY} that way, you must define
-@code{PCC_BITFIELD_TYPE_MATTERS} to have a nonzero value.
-
-If your aim is to make GCC use the same conventions for laying out
-bit-fields as are used by another compiler, here is how to investigate
-what the other compiler does. Compile and run this program:
-
-@smallexample
-struct foo1
-@{
- char x;
- char :0;
- char y;
-@};
-
-struct foo2
-@{
- char x;
- int :0;
- char y;
-@};
-
-main ()
-@{
- printf ("Size of foo1 is %d\n",
- sizeof (struct foo1));
- printf ("Size of foo2 is %d\n",
- sizeof (struct foo2));
- exit (0);
-@}
-@end smallexample
-
-If this prints 2 and 5, then the compiler's behavior is what you would
-get from @code{PCC_BITFIELD_TYPE_MATTERS}.
-@end defmac
-
-@defmac BITFIELD_NBYTES_LIMITED
-Like @code{PCC_BITFIELD_TYPE_MATTERS} except that its effect is limited
-to aligning a bit-field within the structure.
-@end defmac
-
-@deftypefn {Target Hook} bool TARGET_ALIGN_ANON_BITFIELD (void)
-When @code{PCC_BITFIELD_TYPE_MATTERS} is true this hook will determine
-whether unnamed bitfields affect the alignment of the containing
-structure. The hook should return true if the structure should inherit
-the alignment requirements of an unnamed bitfield's type.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_NARROW_VOLATILE_BITFIELD (void)
-This target hook should return @code{true} if accesses to volatile bitfields
-should use the narrowest mode possible. It should return @code{false} if
-these accesses should use the bitfield container type.
-
-The default is @code{false}.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_MEMBER_TYPE_FORCES_BLK (const_tree @var{field}, machine_mode @var{mode})
-Return true if a structure, union or array containing @var{field} should
-be accessed using @code{BLKMODE}.
-
-If @var{field} is the only field in the structure, @var{mode} is its
-mode, otherwise @var{mode} is VOIDmode. @var{mode} is provided in the
-case where structures of one field would require the structure's mode to
-retain the field's mode.
-
-Normally, this is not needed.
-@end deftypefn
-
-@defmac ROUND_TYPE_ALIGN (@var{type}, @var{computed}, @var{specified})
-Define this macro as an expression for the alignment of a type (given
-by @var{type} as a tree node) if the alignment computed in the usual
-way is @var{computed} and the alignment explicitly specified was
-@var{specified}.
-
-The default is to use @var{specified} if it is larger; otherwise, use
-the smaller of @var{computed} and @code{BIGGEST_ALIGNMENT}
-@end defmac
-
-@defmac MAX_FIXED_MODE_SIZE
-An integer expression for the size in bits of the largest integer
-machine mode that should actually be used. All integer machine modes of
-this size or smaller can be used for structures and unions with the
-appropriate sizes. If this macro is undefined, @code{GET_MODE_BITSIZE
-(DImode)} is assumed.
-@end defmac
-
-@defmac STACK_SAVEAREA_MODE (@var{save_level})
-If defined, an expression of type @code{machine_mode} that
-specifies the mode of the save area operand of a
-@code{save_stack_@var{level}} named pattern (@pxref{Standard Names}).
-@var{save_level} is one of @code{SAVE_BLOCK}, @code{SAVE_FUNCTION}, or
-@code{SAVE_NONLOCAL} and selects which of the three named patterns is
-having its mode specified.
-
-You need not define this macro if it always returns @code{Pmode}. You
-would most commonly define this macro if the
-@code{save_stack_@var{level}} patterns need to support both a 32- and a
-64-bit mode.
-@end defmac
-
-@defmac STACK_SIZE_MODE
-If defined, an expression of type @code{machine_mode} that
-specifies the mode of the size increment operand of an
-@code{allocate_stack} named pattern (@pxref{Standard Names}).
-
-You need not define this macro if it always returns @code{word_mode}.
-You would most commonly define this macro if the @code{allocate_stack}
-pattern needs to support both a 32- and a 64-bit mode.
-@end defmac
-
-@deftypefn {Target Hook} scalar_int_mode TARGET_LIBGCC_CMP_RETURN_MODE (void)
-This target hook should return the mode to be used for the return value
-of compare instructions expanded to libgcc calls. If not defined
-@code{word_mode} is returned which is the right choice for a majority of
-targets.
-@end deftypefn
-
-@deftypefn {Target Hook} scalar_int_mode TARGET_LIBGCC_SHIFT_COUNT_MODE (void)
-This target hook should return the mode to be used for the shift count operand
-of shift instructions expanded to libgcc calls. If not defined
-@code{word_mode} is returned which is the right choice for a majority of
-targets.
-@end deftypefn
-
-@deftypefn {Target Hook} scalar_int_mode TARGET_UNWIND_WORD_MODE (void)
-Return machine mode to be used for @code{_Unwind_Word} type.
-The default is to use @code{word_mode}.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_MS_BITFIELD_LAYOUT_P (const_tree @var{record_type})
-This target hook returns @code{true} if bit-fields in the given
-@var{record_type} are to be laid out following the rules of Microsoft
-Visual C/C++, namely: (i) a bit-field won't share the same storage
-unit with the previous bit-field if their underlying types have
-different sizes, and the bit-field will be aligned to the highest
-alignment of the underlying types of itself and of the previous
-bit-field; (ii) a zero-sized bit-field will affect the alignment of
-the whole enclosing structure, even if it is unnamed; except that
-(iii) a zero-sized bit-field will be disregarded unless it follows
-another bit-field of nonzero size. If this hook returns @code{true},
-other macros that control bit-field layout are ignored.
-
-When a bit-field is inserted into a packed record, the whole size
-of the underlying type is used by one or more same-size adjacent
-bit-fields (that is, if its long:3, 32 bits is used in the record,
-and any additional adjacent long bit-fields are packed into the same
-chunk of 32 bits. However, if the size changes, a new field of that
-size is allocated). In an unpacked record, this is the same as using
-alignment, but not equivalent when packing.
-
-If both MS bit-fields and @samp{__attribute__((packed))} are used,
-the latter will take precedence. If @samp{__attribute__((packed))} is
-used on a single field when MS bit-fields are in use, it will take
-precedence for that field, but the alignment of the rest of the structure
-may affect its placement.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_DECIMAL_FLOAT_SUPPORTED_P (void)
-Returns true if the target supports decimal floating point.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_FIXED_POINT_SUPPORTED_P (void)
-Returns true if the target supports fixed-point arithmetic.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_EXPAND_TO_RTL_HOOK (void)
-This hook is called just before expansion into rtl, allowing the target
-to perform additional initializations or analysis before the expansion.
-For example, the rs6000 port uses it to allocate a scratch stack slot
-for use in copying SDmode values between memory and floating point
-registers whenever the function being expanded has any SDmode
-usage.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_INSTANTIATE_DECLS (void)
-This hook allows the backend to perform additional instantiations on rtl
-that are not actually in any insns yet, but will be later.
-@end deftypefn
-
-@deftypefn {Target Hook} {const char *} TARGET_MANGLE_TYPE (const_tree @var{type})
-If your target defines any fundamental types, or any types your target
-uses should be mangled differently from the default, define this hook
-to return the appropriate encoding for these types as part of a C++
-mangled name. The @var{type} argument is the tree structure representing
-the type to be mangled. The hook may be applied to trees which are
-not target-specific fundamental types; it should return @code{NULL}
-for all such types, as well as arguments it does not recognize. If the
-return value is not @code{NULL}, it must point to a statically-allocated
-string constant.
-
-Target-specific fundamental types might be new fundamental types or
-qualified versions of ordinary fundamental types. Encode new
-fundamental types as @samp{@w{u @var{n} @var{name}}}, where @var{name}
-is the name used for the type in source code, and @var{n} is the
-length of @var{name} in decimal. Encode qualified versions of
-ordinary types as @samp{@w{U @var{n} @var{name} @var{code}}}, where
-@var{name} is the name used for the type qualifier in source code,
-@var{n} is the length of @var{name} as above, and @var{code} is the
-code used to represent the unqualified version of this type. (See
-@code{write_builtin_type} in @file{cp/mangle.cc} for the list of
-codes.) In both cases the spaces are for clarity; do not include any
-spaces in your string.
-
-This hook is applied to types prior to typedef resolution. If the mangled
-name for a particular type depends only on that type's main variant, you
-can perform typedef resolution yourself using @code{TYPE_MAIN_VARIANT}
-before mangling.
-
-The default version of this hook always returns @code{NULL}, which is
-appropriate for a target that does not define any new fundamental
-types.
-@end deftypefn
-
-@node Type Layout
-@section Layout of Source Language Data Types
-
-These macros define the sizes and other characteristics of the standard
-basic data types used in programs being compiled. Unlike the macros in
-the previous section, these apply to specific features of C and related
-languages, rather than to fundamental aspects of storage layout.
-
-@defmac INT_TYPE_SIZE
-A C expression for the size in bits of the type @code{int} on the
-target machine. If you don't define this, the default is one word.
-@end defmac
-
-@defmac SHORT_TYPE_SIZE
-A C expression for the size in bits of the type @code{short} on the
-target machine. If you don't define this, the default is half a word.
-(If this would be less than one storage unit, it is rounded up to one
-unit.)
-@end defmac
-
-@defmac LONG_TYPE_SIZE
-A C expression for the size in bits of the type @code{long} on the
-target machine. If you don't define this, the default is one word.
-@end defmac
-
-@defmac ADA_LONG_TYPE_SIZE
-On some machines, the size used for the Ada equivalent of the type
-@code{long} by a native Ada compiler differs from that used by C@. In
-that situation, define this macro to be a C expression to be used for
-the size of that type. If you don't define this, the default is the
-value of @code{LONG_TYPE_SIZE}.
-@end defmac
-
-@defmac LONG_LONG_TYPE_SIZE
-A C expression for the size in bits of the type @code{long long} on the
-target machine. If you don't define this, the default is two
-words. If you want to support GNU Ada on your machine, the value of this
-macro must be at least 64.
-@end defmac
-
-@defmac CHAR_TYPE_SIZE
-A C expression for the size in bits of the type @code{char} on the
-target machine. If you don't define this, the default is
-@code{BITS_PER_UNIT}.
-@end defmac
-
-@defmac BOOL_TYPE_SIZE
-A C expression for the size in bits of the C++ type @code{bool} and
-C99 type @code{_Bool} on the target machine. If you don't define
-this, and you probably shouldn't, the default is @code{CHAR_TYPE_SIZE}.
-@end defmac
-
-@defmac FLOAT_TYPE_SIZE
-A C expression for the size in bits of the type @code{float} on the
-target machine. If you don't define this, the default is one word.
-@end defmac
-
-@defmac DOUBLE_TYPE_SIZE
-A C expression for the size in bits of the type @code{double} on the
-target machine. If you don't define this, the default is two
-words.
-@end defmac
-
-@defmac LONG_DOUBLE_TYPE_SIZE
-A C expression for the size in bits of the type @code{long double} on
-the target machine. If you don't define this, the default is two
-words.
-@end defmac
-
-@defmac SHORT_FRACT_TYPE_SIZE
-A C expression for the size in bits of the type @code{short _Fract} on
-the target machine. If you don't define this, the default is
-@code{BITS_PER_UNIT}.
-@end defmac
-
-@defmac FRACT_TYPE_SIZE
-A C expression for the size in bits of the type @code{_Fract} on
-the target machine. If you don't define this, the default is
-@code{BITS_PER_UNIT * 2}.
-@end defmac
-
-@defmac LONG_FRACT_TYPE_SIZE
-A C expression for the size in bits of the type @code{long _Fract} on
-the target machine. If you don't define this, the default is
-@code{BITS_PER_UNIT * 4}.
-@end defmac
-
-@defmac LONG_LONG_FRACT_TYPE_SIZE
-A C expression for the size in bits of the type @code{long long _Fract} on
-the target machine. If you don't define this, the default is
-@code{BITS_PER_UNIT * 8}.
-@end defmac
-
-@defmac SHORT_ACCUM_TYPE_SIZE
-A C expression for the size in bits of the type @code{short _Accum} on
-the target machine. If you don't define this, the default is
-@code{BITS_PER_UNIT * 2}.
-@end defmac
-
-@defmac ACCUM_TYPE_SIZE
-A C expression for the size in bits of the type @code{_Accum} on
-the target machine. If you don't define this, the default is
-@code{BITS_PER_UNIT * 4}.
-@end defmac
-
-@defmac LONG_ACCUM_TYPE_SIZE
-A C expression for the size in bits of the type @code{long _Accum} on
-the target machine. If you don't define this, the default is
-@code{BITS_PER_UNIT * 8}.
-@end defmac
-
-@defmac LONG_LONG_ACCUM_TYPE_SIZE
-A C expression for the size in bits of the type @code{long long _Accum} on
-the target machine. If you don't define this, the default is
-@code{BITS_PER_UNIT * 16}.
-@end defmac
-
-@defmac LIBGCC2_GNU_PREFIX
-This macro corresponds to the @code{TARGET_LIBFUNC_GNU_PREFIX} target
-hook and should be defined if that hook is overriden to be true. It
-causes function names in libgcc to be changed to use a @code{__gnu_}
-prefix for their name rather than the default @code{__}. A port which
-uses this macro should also arrange to use @file{t-gnu-prefix} in
-the libgcc @file{config.host}.
-@end defmac
-
-@defmac WIDEST_HARDWARE_FP_SIZE
-A C expression for the size in bits of the widest floating-point format
-supported by the hardware. If you define this macro, you must specify a
-value less than or equal to the value of @code{LONG_DOUBLE_TYPE_SIZE}.
-If you do not define this macro, the value of @code{LONG_DOUBLE_TYPE_SIZE}
-is the default.
-@end defmac
-
-@defmac DEFAULT_SIGNED_CHAR
-An expression whose value is 1 or 0, according to whether the type
-@code{char} should be signed or unsigned by default. The user can
-always override this default with the options @option{-fsigned-char}
-and @option{-funsigned-char}.
-@end defmac
-
-@deftypefn {Target Hook} bool TARGET_DEFAULT_SHORT_ENUMS (void)
-This target hook should return true if the compiler should give an
-@code{enum} type only as many bytes as it takes to represent the range
-of possible values of that type. It should return false if all
-@code{enum} types should be allocated like @code{int}.
-
-The default is to return false.
-@end deftypefn
-
-@defmac SIZE_TYPE
-A C expression for a string describing the name of the data type to use
-for size values. The typedef name @code{size_t} is defined using the
-contents of the string.
-
-The string can contain more than one keyword. If so, separate them with
-spaces, and write first any length keyword, then @code{unsigned} if
-appropriate, and finally @code{int}. The string must exactly match one
-of the data type names defined in the function
-@code{c_common_nodes_and_builtins} in the file @file{c-family/c-common.cc}.
-You may not omit @code{int} or change the order---that would cause the
-compiler to crash on startup.
-
-If you don't define this macro, the default is @code{"long unsigned
-int"}.
-@end defmac
-
-@defmac SIZETYPE
-GCC defines internal types (@code{sizetype}, @code{ssizetype},
-@code{bitsizetype} and @code{sbitsizetype}) for expressions
-dealing with size. This macro is a C expression for a string describing
-the name of the data type from which the precision of @code{sizetype}
-is extracted.
-
-The string has the same restrictions as @code{SIZE_TYPE} string.
-
-If you don't define this macro, the default is @code{SIZE_TYPE}.
-@end defmac
-
-@defmac PTRDIFF_TYPE
-A C expression for a string describing the name of the data type to use
-for the result of subtracting two pointers. The typedef name
-@code{ptrdiff_t} is defined using the contents of the string. See
-@code{SIZE_TYPE} above for more information.
-
-If you don't define this macro, the default is @code{"long int"}.
-@end defmac
-
-@defmac WCHAR_TYPE
-A C expression for a string describing the name of the data type to use
-for wide characters. The typedef name @code{wchar_t} is defined using
-the contents of the string. See @code{SIZE_TYPE} above for more
-information.
-
-If you don't define this macro, the default is @code{"int"}.
-@end defmac
-
-@defmac WCHAR_TYPE_SIZE
-A C expression for the size in bits of the data type for wide
-characters. This is used in @code{cpp}, which cannot make use of
-@code{WCHAR_TYPE}.
-@end defmac
-
-@defmac WINT_TYPE
-A C expression for a string describing the name of the data type to
-use for wide characters passed to @code{printf} and returned from
-@code{getwc}. The typedef name @code{wint_t} is defined using the
-contents of the string. See @code{SIZE_TYPE} above for more
-information.
-
-If you don't define this macro, the default is @code{"unsigned int"}.
-@end defmac
-
-@defmac INTMAX_TYPE
-A C expression for a string describing the name of the data type that
-can represent any value of any standard or extended signed integer type.
-The typedef name @code{intmax_t} is defined using the contents of the
-string. See @code{SIZE_TYPE} above for more information.
-
-If you don't define this macro, the default is the first of
-@code{"int"}, @code{"long int"}, or @code{"long long int"} that has as
-much precision as @code{long long int}.
-@end defmac
-
-@defmac UINTMAX_TYPE
-A C expression for a string describing the name of the data type that
-can represent any value of any standard or extended unsigned integer
-type. The typedef name @code{uintmax_t} is defined using the contents
-of the string. See @code{SIZE_TYPE} above for more information.
-
-If you don't define this macro, the default is the first of
-@code{"unsigned int"}, @code{"long unsigned int"}, or @code{"long long
-unsigned int"} that has as much precision as @code{long long unsigned
-int}.
-@end defmac
-
-@defmac SIG_ATOMIC_TYPE
-@defmacx INT8_TYPE
-@defmacx INT16_TYPE
-@defmacx INT32_TYPE
-@defmacx INT64_TYPE
-@defmacx UINT8_TYPE
-@defmacx UINT16_TYPE
-@defmacx UINT32_TYPE
-@defmacx UINT64_TYPE
-@defmacx INT_LEAST8_TYPE
-@defmacx INT_LEAST16_TYPE
-@defmacx INT_LEAST32_TYPE
-@defmacx INT_LEAST64_TYPE
-@defmacx UINT_LEAST8_TYPE
-@defmacx UINT_LEAST16_TYPE
-@defmacx UINT_LEAST32_TYPE
-@defmacx UINT_LEAST64_TYPE
-@defmacx INT_FAST8_TYPE
-@defmacx INT_FAST16_TYPE
-@defmacx INT_FAST32_TYPE
-@defmacx INT_FAST64_TYPE
-@defmacx UINT_FAST8_TYPE
-@defmacx UINT_FAST16_TYPE
-@defmacx UINT_FAST32_TYPE
-@defmacx UINT_FAST64_TYPE
-@defmacx INTPTR_TYPE
-@defmacx UINTPTR_TYPE
-C expressions for the standard types @code{sig_atomic_t},
-@code{int8_t}, @code{int16_t}, @code{int32_t}, @code{int64_t},
-@code{uint8_t}, @code{uint16_t}, @code{uint32_t}, @code{uint64_t},
-@code{int_least8_t}, @code{int_least16_t}, @code{int_least32_t},
-@code{int_least64_t}, @code{uint_least8_t}, @code{uint_least16_t},
-@code{uint_least32_t}, @code{uint_least64_t}, @code{int_fast8_t},
-@code{int_fast16_t}, @code{int_fast32_t}, @code{int_fast64_t},
-@code{uint_fast8_t}, @code{uint_fast16_t}, @code{uint_fast32_t},
-@code{uint_fast64_t}, @code{intptr_t}, and @code{uintptr_t}. See
-@code{SIZE_TYPE} above for more information.
-
-If any of these macros evaluates to a null pointer, the corresponding
-type is not supported; if GCC is configured to provide
-@code{<stdint.h>} in such a case, the header provided may not conform
-to C99, depending on the type in question. The defaults for all of
-these macros are null pointers.
-@end defmac
-
-@defmac TARGET_PTRMEMFUNC_VBIT_LOCATION
-The C++ compiler represents a pointer-to-member-function with a struct
-that looks like:
-
-@smallexample
- struct @{
- union @{
- void (*fn)();
- ptrdiff_t vtable_index;
- @};
- ptrdiff_t delta;
- @};
-@end smallexample
-
-@noindent
-The C++ compiler must use one bit to indicate whether the function that
-will be called through a pointer-to-member-function is virtual.
-Normally, we assume that the low-order bit of a function pointer must
-always be zero. Then, by ensuring that the vtable_index is odd, we can
-distinguish which variant of the union is in use. But, on some
-platforms function pointers can be odd, and so this doesn't work. In
-that case, we use the low-order bit of the @code{delta} field, and shift
-the remainder of the @code{delta} field to the left.
-
-GCC will automatically make the right selection about where to store
-this bit using the @code{FUNCTION_BOUNDARY} setting for your platform.
-However, some platforms such as ARM/Thumb have @code{FUNCTION_BOUNDARY}
-set such that functions always start at even addresses, but the lowest
-bit of pointers to functions indicate whether the function at that
-address is in ARM or Thumb mode. If this is the case of your
-architecture, you should define this macro to
-@code{ptrmemfunc_vbit_in_delta}.
-
-In general, you should not have to define this macro. On architectures
-in which function addresses are always even, according to
-@code{FUNCTION_BOUNDARY}, GCC will automatically define this macro to
-@code{ptrmemfunc_vbit_in_pfn}.
-@end defmac
-
-@defmac TARGET_VTABLE_USES_DESCRIPTORS
-Normally, the C++ compiler uses function pointers in vtables. This
-macro allows the target to change to use ``function descriptors''
-instead. Function descriptors are found on targets for whom a
-function pointer is actually a small data structure. Normally the
-data structure consists of the actual code address plus a data
-pointer to which the function's data is relative.
-
-If vtables are used, the value of this macro should be the number
-of words that the function descriptor occupies.
-@end defmac
-
-@defmac TARGET_VTABLE_ENTRY_ALIGN
-By default, the vtable entries are void pointers, the so the alignment
-is the same as pointer alignment. The value of this macro specifies
-the alignment of the vtable entry in bits. It should be defined only
-when special alignment is necessary. */
-@end defmac
-
-@defmac TARGET_VTABLE_DATA_ENTRY_DISTANCE
-There are a few non-descriptor entries in the vtable at offsets below
-zero. If these entries must be padded (say, to preserve the alignment
-specified by @code{TARGET_VTABLE_ENTRY_ALIGN}), set this to the number
-of words in each data entry.
-@end defmac
-
-@node Registers
-@section Register Usage
-@cindex register usage
-
-This section explains how to describe what registers the target machine
-has, and how (in general) they can be used.
-
-The description of which registers a specific instruction can use is
-done with register classes; see @ref{Register Classes}. For information
-on using registers to access a stack frame, see @ref{Frame Registers}.
-For passing values in registers, see @ref{Register Arguments}.
-For returning values in registers, see @ref{Scalar Return}.
-
-@menu
-* Register Basics:: Number and kinds of registers.
-* Allocation Order:: Order in which registers are allocated.
-* Values in Registers:: What kinds of values each reg can hold.
-* Leaf Functions:: Renumbering registers for leaf functions.
-* Stack Registers:: Handling a register stack such as 80387.
-@end menu
-
-@node Register Basics
-@subsection Basic Characteristics of Registers
-
-@c prevent bad page break with this line
-Registers have various characteristics.
-
-@defmac FIRST_PSEUDO_REGISTER
-Number of hardware registers known to the compiler. They receive
-numbers 0 through @code{FIRST_PSEUDO_REGISTER-1}; thus, the first
-pseudo register's number really is assigned the number
-@code{FIRST_PSEUDO_REGISTER}.
-@end defmac
-
-@defmac FIXED_REGISTERS
-@cindex fixed register
-An initializer that says which registers are used for fixed purposes
-all throughout the compiled code and are therefore not available for
-general allocation. These would include the stack pointer, the frame
-pointer (except on machines where that can be used as a general
-register when no frame pointer is needed), the program counter on
-machines where that is considered one of the addressable registers,
-and any other numbered register with a standard use.
-
-This information is expressed as a sequence of numbers, separated by
-commas and surrounded by braces. The @var{n}th number is 1 if
-register @var{n} is fixed, 0 otherwise.
-
-The table initialized from this macro, and the table initialized by
-the following one, may be overridden at run time either automatically,
-by the actions of the macro @code{CONDITIONAL_REGISTER_USAGE}, or by
-the user with the command options @option{-ffixed-@var{reg}},
-@option{-fcall-used-@var{reg}} and @option{-fcall-saved-@var{reg}}.
-@end defmac
-
-@defmac CALL_USED_REGISTERS
-@cindex call-used register
-@cindex call-clobbered register
-@cindex call-saved register
-Like @code{FIXED_REGISTERS} but has 1 for each register that is
-clobbered (in general) by function calls as well as for fixed
-registers. This macro therefore identifies the registers that are not
-available for general allocation of values that must live across
-function calls.
-
-If a register has 0 in @code{CALL_USED_REGISTERS}, the compiler
-automatically saves it on function entry and restores it on function
-exit, if the register is used within the function.
-
-Exactly one of @code{CALL_USED_REGISTERS} and @code{CALL_REALLY_USED_REGISTERS}
-must be defined. Modern ports should define @code{CALL_REALLY_USED_REGISTERS}.
-@end defmac
-
-@defmac CALL_REALLY_USED_REGISTERS
-@cindex call-used register
-@cindex call-clobbered register
-@cindex call-saved register
-Like @code{CALL_USED_REGISTERS} except this macro doesn't require
-that the entire set of @code{FIXED_REGISTERS} be included.
-(@code{CALL_USED_REGISTERS} must be a superset of @code{FIXED_REGISTERS}).
-
-Exactly one of @code{CALL_USED_REGISTERS} and @code{CALL_REALLY_USED_REGISTERS}
-must be defined. Modern ports should define @code{CALL_REALLY_USED_REGISTERS}.
-@end defmac
-
-@cindex call-used register
-@cindex call-clobbered register
-@cindex call-saved register
-@deftypefn {Target Hook} {const predefined_function_abi &} TARGET_FNTYPE_ABI (const_tree @var{type})
-Return the ABI used by a function with type @var{type}; see the
-definition of @code{predefined_function_abi} for details of the ABI
-descriptor. Targets only need to define this hook if they support
-interoperability between several ABIs in the same translation unit.
-@end deftypefn
-
-@deftypefn {Target Hook} {const predefined_function_abi &} TARGET_INSN_CALLEE_ABI (const rtx_insn *@var{insn})
-This hook returns a description of the ABI used by the target of
-call instruction @var{insn}; see the definition of
-@code{predefined_function_abi} for details of the ABI descriptor.
-Only the global function @code{insn_callee_abi} should call this hook
-directly.
-
-Targets only need to define this hook if they support
-interoperability between several ABIs in the same translation unit.
-@end deftypefn
-
-@cindex call-used register
-@cindex call-clobbered register
-@cindex call-saved register
-@deftypefn {Target Hook} bool TARGET_HARD_REGNO_CALL_PART_CLOBBERED (unsigned int @var{abi_id}, unsigned int @var{regno}, machine_mode @var{mode})
-ABIs usually specify that calls must preserve the full contents
-of a particular register, or that calls can alter any part of a
-particular register. This information is captured by the target macro
-@code{CALL_REALLY_USED_REGISTERS}. However, some ABIs specify that calls
-must preserve certain bits of a particular register but can alter others.
-This hook should return true if this applies to at least one of the
-registers in @samp{(reg:@var{mode} @var{regno})}, and if as a result the
-call would alter part of the @var{mode} value. For example, if a call
-preserves the low 32 bits of a 64-bit hard register @var{regno} but can
-clobber the upper 32 bits, this hook should return true for a 64-bit mode
-but false for a 32-bit mode.
-
-The value of @var{abi_id} comes from the @code{predefined_function_abi}
-structure that describes the ABI of the call; see the definition of the
-structure for more details. If (as is usual) the target uses the same ABI
-for all functions in a translation unit, @var{abi_id} is always 0.
-
-The default implementation returns false, which is correct
-for targets that don't have partly call-clobbered registers.
-@end deftypefn
-
-@deftypefn {Target Hook} {const char *} TARGET_GET_MULTILIB_ABI_NAME (void)
-This hook returns name of multilib ABI name.
-@end deftypefn
-
-@findex fixed_regs
-@findex call_used_regs
-@findex global_regs
-@findex reg_names
-@findex reg_class_contents
-@deftypefn {Target Hook} void TARGET_CONDITIONAL_REGISTER_USAGE (void)
-This hook may conditionally modify five variables
-@code{fixed_regs}, @code{call_used_regs}, @code{global_regs},
-@code{reg_names}, and @code{reg_class_contents}, to take into account
-any dependence of these register sets on target flags. The first three
-of these are of type @code{char []} (interpreted as boolean vectors).
-@code{global_regs} is a @code{const char *[]}, and
-@code{reg_class_contents} is a @code{HARD_REG_SET}. Before the macro is
-called, @code{fixed_regs}, @code{call_used_regs},
-@code{reg_class_contents}, and @code{reg_names} have been initialized
-from @code{FIXED_REGISTERS}, @code{CALL_USED_REGISTERS},
-@code{REG_CLASS_CONTENTS}, and @code{REGISTER_NAMES}, respectively.
-@code{global_regs} has been cleared, and any @option{-ffixed-@var{reg}},
-@option{-fcall-used-@var{reg}} and @option{-fcall-saved-@var{reg}}
-command options have been applied.
-
-@cindex disabling certain registers
-@cindex controlling register usage
-If the usage of an entire class of registers depends on the target
-flags, you may indicate this to GCC by using this macro to modify
-@code{fixed_regs} and @code{call_used_regs} to 1 for each of the
-registers in the classes which should not be used by GCC@. Also make
-@code{define_register_constraint}s return @code{NO_REGS} for constraints
-that shouldn't be used.
-
-(However, if this class is not included in @code{GENERAL_REGS} and all
-of the insn patterns whose constraints permit this class are
-controlled by target switches, then GCC will automatically avoid using
-these registers when the target switches are opposed to them.)
-@end deftypefn
-
-@defmac INCOMING_REGNO (@var{out})
-Define this macro if the target machine has register windows. This C
-expression returns the register number as seen by the called function
-corresponding to the register number @var{out} as seen by the calling
-function. Return @var{out} if register number @var{out} is not an
-outbound register.
-@end defmac
-
-@defmac OUTGOING_REGNO (@var{in})
-Define this macro if the target machine has register windows. This C
-expression returns the register number as seen by the calling function
-corresponding to the register number @var{in} as seen by the called
-function. Return @var{in} if register number @var{in} is not an inbound
-register.
-@end defmac
-
-@defmac LOCAL_REGNO (@var{regno})
-Define this macro if the target machine has register windows. This C
-expression returns true if the register is call-saved but is in the
-register window. Unlike most call-saved registers, such registers
-need not be explicitly restored on function exit or during non-local
-gotos.
-@end defmac
-
-@defmac PC_REGNUM
-If the program counter has a register number, define this as that
-register number. Otherwise, do not define it.
-@end defmac
-
-@node Allocation Order
-@subsection Order of Allocation of Registers
-@cindex order of register allocation
-@cindex register allocation order
-
-@c prevent bad page break with this line
-Registers are allocated in order.
-
-@defmac REG_ALLOC_ORDER
-If defined, an initializer for a vector of integers, containing the
-numbers of hard registers in the order in which GCC should prefer
-to use them (from most preferred to least).
-
-If this macro is not defined, registers are used lowest numbered first
-(all else being equal).
-
-One use of this macro is on machines where the highest numbered
-registers must always be saved and the save-multiple-registers
-instruction supports only sequences of consecutive registers. On such
-machines, define @code{REG_ALLOC_ORDER} to be an initializer that lists
-the highest numbered allocable register first.
-@end defmac
-
-@defmac ADJUST_REG_ALLOC_ORDER
-A C statement (sans semicolon) to choose the order in which to allocate
-hard registers for pseudo-registers local to a basic block.
-
-Store the desired register order in the array @code{reg_alloc_order}.
-Element 0 should be the register to allocate first; element 1, the next
-register; and so on.
-
-The macro body should not assume anything about the contents of
-@code{reg_alloc_order} before execution of the macro.
-
-On most machines, it is not necessary to define this macro.
-@end defmac
-
-@defmac HONOR_REG_ALLOC_ORDER
-Normally, IRA tries to estimate the costs for saving a register in the
-prologue and restoring it in the epilogue. This discourages it from
-using call-saved registers. If a machine wants to ensure that IRA
-allocates registers in the order given by REG_ALLOC_ORDER even if some
-call-saved registers appear earlier than call-used ones, then define this
-macro as a C expression to nonzero. Default is 0.
-@end defmac
-
-@defmac IRA_HARD_REGNO_ADD_COST_MULTIPLIER (@var{regno})
-In some case register allocation order is not enough for the
-Integrated Register Allocator (@acronym{IRA}) to generate a good code.
-If this macro is defined, it should return a floating point value
-based on @var{regno}. The cost of using @var{regno} for a pseudo will
-be increased by approximately the pseudo's usage frequency times the
-value returned by this macro. Not defining this macro is equivalent
-to having it always return @code{0.0}.
-
-On most machines, it is not necessary to define this macro.
-@end defmac
-
-@node Values in Registers
-@subsection How Values Fit in Registers
-
-This section discusses the macros that describe which kinds of values
-(specifically, which machine modes) each register can hold, and how many
-consecutive registers are needed for a given mode.
-
-@deftypefn {Target Hook} {unsigned int} TARGET_HARD_REGNO_NREGS (unsigned int @var{regno}, machine_mode @var{mode})
-This hook returns the number of consecutive hard registers, starting
-at register number @var{regno}, required to hold a value of mode
-@var{mode}. This hook must never return zero, even if a register
-cannot hold the requested mode - indicate that with
-@code{TARGET_HARD_REGNO_MODE_OK} and/or
-@code{TARGET_CAN_CHANGE_MODE_CLASS} instead.
-
-The default definition returns the number of words in @var{mode}.
-@end deftypefn
-
-@defmac HARD_REGNO_NREGS_HAS_PADDING (@var{regno}, @var{mode})
-A C expression that is nonzero if a value of mode @var{mode}, stored
-in memory, ends with padding that causes it to take up more space than
-in registers starting at register number @var{regno} (as determined by
-multiplying GCC's notion of the size of the register when containing
-this mode by the number of registers returned by
-@code{TARGET_HARD_REGNO_NREGS}). By default this is zero.
-
-For example, if a floating-point value is stored in three 32-bit
-registers but takes up 128 bits in memory, then this would be
-nonzero.
-
-This macros only needs to be defined if there are cases where
-@code{subreg_get_info}
-would otherwise wrongly determine that a @code{subreg} can be
-represented by an offset to the register number, when in fact such a
-@code{subreg} would contain some of the padding not stored in
-registers and so not be representable.
-@end defmac
-
-@defmac HARD_REGNO_NREGS_WITH_PADDING (@var{regno}, @var{mode})
-For values of @var{regno} and @var{mode} for which
-@code{HARD_REGNO_NREGS_HAS_PADDING} returns nonzero, a C expression
-returning the greater number of registers required to hold the value
-including any padding. In the example above, the value would be four.
-@end defmac
-
-@defmac REGMODE_NATURAL_SIZE (@var{mode})
-Define this macro if the natural size of registers that hold values
-of mode @var{mode} is not the word size. It is a C expression that
-should give the natural size in bytes for the specified mode. It is
-used by the register allocator to try to optimize its results. This
-happens for example on SPARC 64-bit where the natural size of
-floating-point registers is still 32-bit.
-@end defmac
-
-@deftypefn {Target Hook} bool TARGET_HARD_REGNO_MODE_OK (unsigned int @var{regno}, machine_mode @var{mode})
-This hook returns true if it is permissible to store a value
-of mode @var{mode} in hard register number @var{regno} (or in several
-registers starting with that one). The default definition returns true
-unconditionally.
-
-You need not include code to check for the numbers of fixed registers,
-because the allocation mechanism considers them to be always occupied.
-
-@cindex register pairs
-On some machines, double-precision values must be kept in even/odd
-register pairs. You can implement that by defining this hook to reject
-odd register numbers for such modes.
-
-The minimum requirement for a mode to be OK in a register is that the
-@samp{mov@var{mode}} instruction pattern support moves between the
-register and other hard register in the same class and that moving a
-value into the register and back out not alter it.
-
-Since the same instruction used to move @code{word_mode} will work for
-all narrower integer modes, it is not necessary on any machine for
-this hook to distinguish between these modes, provided you define
-patterns @samp{movhi}, etc., to take advantage of this. This is
-useful because of the interaction between @code{TARGET_HARD_REGNO_MODE_OK}
-and @code{TARGET_MODES_TIEABLE_P}; it is very desirable for all integer
-modes to be tieable.
-
-Many machines have special registers for floating point arithmetic.
-Often people assume that floating point machine modes are allowed only
-in floating point registers. This is not true. Any registers that
-can hold integers can safely @emph{hold} a floating point machine
-mode, whether or not floating arithmetic can be done on it in those
-registers. Integer move instructions can be used to move the values.
-
-On some machines, though, the converse is true: fixed-point machine
-modes may not go in floating registers. This is true if the floating
-registers normalize any value stored in them, because storing a
-non-floating value there would garble it. In this case,
-@code{TARGET_HARD_REGNO_MODE_OK} should reject fixed-point machine modes in
-floating registers. But if the floating registers do not automatically
-normalize, if you can store any bit pattern in one and retrieve it
-unchanged without a trap, then any machine mode may go in a floating
-register, so you can define this hook to say so.
-
-The primary significance of special floating registers is rather that
-they are the registers acceptable in floating point arithmetic
-instructions. However, this is of no concern to
-@code{TARGET_HARD_REGNO_MODE_OK}. You handle it by writing the proper
-constraints for those instructions.
-
-On some machines, the floating registers are especially slow to access,
-so that it is better to store a value in a stack frame than in such a
-register if floating point arithmetic is not being done. As long as the
-floating registers are not in class @code{GENERAL_REGS}, they will not
-be used unless some pattern's constraint asks for one.
-@end deftypefn
-
-@defmac HARD_REGNO_RENAME_OK (@var{from}, @var{to})
-A C expression that is nonzero if it is OK to rename a hard register
-@var{from} to another hard register @var{to}.
-
-One common use of this macro is to prevent renaming of a register to
-another register that is not saved by a prologue in an interrupt
-handler.
-
-The default is always nonzero.
-@end defmac
-
-@deftypefn {Target Hook} bool TARGET_MODES_TIEABLE_P (machine_mode @var{mode1}, machine_mode @var{mode2})
-This hook returns true if a value of mode @var{mode1} is accessible
-in mode @var{mode2} without copying.
-
-If @code{TARGET_HARD_REGNO_MODE_OK (@var{r}, @var{mode1})} and
-@code{TARGET_HARD_REGNO_MODE_OK (@var{r}, @var{mode2})} are always
-the same for any @var{r}, then
-@code{TARGET_MODES_TIEABLE_P (@var{mode1}, @var{mode2})}
-should be true. If they differ for any @var{r}, you should define
-this hook to return false unless some other mechanism ensures the
-accessibility of the value in a narrower mode.
-
-You should define this hook to return true in as many cases as
-possible since doing so will allow GCC to perform better register
-allocation. The default definition returns true unconditionally.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_HARD_REGNO_SCRATCH_OK (unsigned int @var{regno})
-This target hook should return @code{true} if it is OK to use a hard register
-@var{regno} as scratch reg in peephole2.
-
-One common use of this macro is to prevent using of a register that
-is not saved by a prologue in an interrupt handler.
-
-The default version of this hook always returns @code{true}.
-@end deftypefn
-
-@defmac AVOID_CCMODE_COPIES
-Define this macro if the compiler should avoid copies to/from @code{CCmode}
-registers. You should only define this macro if support for copying to/from
-@code{CCmode} is incomplete.
-@end defmac
-
-@node Leaf Functions
-@subsection Handling Leaf Functions
-
-@cindex leaf functions
-@cindex functions, leaf
-On some machines, a leaf function (i.e., one which makes no calls) can run
-more efficiently if it does not make its own register window. Often this
-means it is required to receive its arguments in the registers where they
-are passed by the caller, instead of the registers where they would
-normally arrive.
-
-The special treatment for leaf functions generally applies only when
-other conditions are met; for example, often they may use only those
-registers for its own variables and temporaries. We use the term ``leaf
-function'' to mean a function that is suitable for this special
-handling, so that functions with no calls are not necessarily ``leaf
-functions''.
-
-GCC assigns register numbers before it knows whether the function is
-suitable for leaf function treatment. So it needs to renumber the
-registers in order to output a leaf function. The following macros
-accomplish this.
-
-@defmac LEAF_REGISTERS
-Name of a char vector, indexed by hard register number, which
-contains 1 for a register that is allowable in a candidate for leaf
-function treatment.
-
-If leaf function treatment involves renumbering the registers, then the
-registers marked here should be the ones before renumbering---those that
-GCC would ordinarily allocate. The registers which will actually be
-used in the assembler code, after renumbering, should not be marked with 1
-in this vector.
-
-Define this macro only if the target machine offers a way to optimize
-the treatment of leaf functions.
-@end defmac
-
-@defmac LEAF_REG_REMAP (@var{regno})
-A C expression whose value is the register number to which @var{regno}
-should be renumbered, when a function is treated as a leaf function.
-
-If @var{regno} is a register number which should not appear in a leaf
-function before renumbering, then the expression should yield @minus{}1, which
-will cause the compiler to abort.
-
-Define this macro only if the target machine offers a way to optimize the
-treatment of leaf functions, and registers need to be renumbered to do
-this.
-@end defmac
-
-@findex current_function_is_leaf
-@findex current_function_uses_only_leaf_regs
-@code{TARGET_ASM_FUNCTION_PROLOGUE} and
-@code{TARGET_ASM_FUNCTION_EPILOGUE} must usually treat leaf functions
-specially. They can test the C variable @code{current_function_is_leaf}
-which is nonzero for leaf functions. @code{current_function_is_leaf} is
-set prior to local register allocation and is valid for the remaining
-compiler passes. They can also test the C variable
-@code{current_function_uses_only_leaf_regs} which is nonzero for leaf
-functions which only use leaf registers.
-@code{current_function_uses_only_leaf_regs} is valid after all passes
-that modify the instructions have been run and is only useful if
-@code{LEAF_REGISTERS} is defined.
-@c changed this to fix overfull. ALSO: why the "it" at the beginning
-@c of the next paragraph?! --mew 2feb93
-
-@node Stack Registers
-@subsection Registers That Form a Stack
-
-There are special features to handle computers where some of the
-``registers'' form a stack. Stack registers are normally written by
-pushing onto the stack, and are numbered relative to the top of the
-stack.
-
-Currently, GCC can only handle one group of stack-like registers, and
-they must be consecutively numbered. Furthermore, the existing
-support for stack-like registers is specific to the 80387 floating
-point coprocessor. If you have a new architecture that uses
-stack-like registers, you will need to do substantial work on
-@file{reg-stack.cc} and write your machine description to cooperate
-with it, as well as defining these macros.
-
-@defmac STACK_REGS
-Define this if the machine has any stack-like registers.
-@end defmac
-
-@defmac STACK_REG_COVER_CLASS
-This is a cover class containing the stack registers. Define this if
-the machine has any stack-like registers.
-@end defmac
-
-@defmac FIRST_STACK_REG
-The number of the first stack-like register. This one is the top
-of the stack.
-@end defmac
-
-@defmac LAST_STACK_REG
-The number of the last stack-like register. This one is the bottom of
-the stack.
-@end defmac
-
-@node Register Classes
-@section Register Classes
-@cindex register class definitions
-@cindex class definitions, register
-
-On many machines, the numbered registers are not all equivalent.
-For example, certain registers may not be allowed for indexed addressing;
-certain registers may not be allowed in some instructions. These machine
-restrictions are described to the compiler using @dfn{register classes}.
-
-You define a number of register classes, giving each one a name and saying
-which of the registers belong to it. Then you can specify register classes
-that are allowed as operands to particular instruction patterns.
-
-@findex ALL_REGS
-@findex NO_REGS
-In general, each register will belong to several classes. In fact, one
-class must be named @code{ALL_REGS} and contain all the registers. Another
-class must be named @code{NO_REGS} and contain no registers. Often the
-union of two classes will be another class; however, this is not required.
-
-@findex GENERAL_REGS
-One of the classes must be named @code{GENERAL_REGS}. There is nothing
-terribly special about the name, but the operand constraint letters
-@samp{r} and @samp{g} specify this class. If @code{GENERAL_REGS} is
-the same as @code{ALL_REGS}, just define it as a macro which expands
-to @code{ALL_REGS}.
-
-Order the classes so that if class @var{x} is contained in class @var{y}
-then @var{x} has a lower class number than @var{y}.
-
-The way classes other than @code{GENERAL_REGS} are specified in operand
-constraints is through machine-dependent operand constraint letters.
-You can define such letters to correspond to various classes, then use
-them in operand constraints.
-
-You must define the narrowest register classes for allocatable
-registers, so that each class either has no subclasses, or that for
-some mode, the move cost between registers within the class is
-cheaper than moving a register in the class to or from memory
-(@pxref{Costs}).
-
-You should define a class for the union of two classes whenever some
-instruction allows both classes. For example, if an instruction allows
-either a floating point (coprocessor) register or a general register for a
-certain operand, you should define a class @code{FLOAT_OR_GENERAL_REGS}
-which includes both of them. Otherwise you will get suboptimal code,
-or even internal compiler errors when reload cannot find a register in the
-class computed via @code{reg_class_subunion}.
-
-You must also specify certain redundant information about the register
-classes: for each class, which classes contain it and which ones are
-contained in it; for each pair of classes, the largest class contained
-in their union.
-
-When a value occupying several consecutive registers is expected in a
-certain class, all the registers used must belong to that class.
-Therefore, register classes cannot be used to enforce a requirement for
-a register pair to start with an even-numbered register. The way to
-specify this requirement is with @code{TARGET_HARD_REGNO_MODE_OK}.
-
-Register classes used for input-operands of bitwise-and or shift
-instructions have a special requirement: each such class must have, for
-each fixed-point machine mode, a subclass whose registers can transfer that
-mode to or from memory. For example, on some machines, the operations for
-single-byte values (@code{QImode}) are limited to certain registers. When
-this is so, each register class that is used in a bitwise-and or shift
-instruction must have a subclass consisting of registers from which
-single-byte values can be loaded or stored. This is so that
-@code{PREFERRED_RELOAD_CLASS} can always have a possible value to return.
-
-@deftp {Data type} {enum reg_class}
-An enumerated type that must be defined with all the register class names
-as enumerated values. @code{NO_REGS} must be first. @code{ALL_REGS}
-must be the last register class, followed by one more enumerated value,
-@code{LIM_REG_CLASSES}, which is not a register class but rather
-tells how many classes there are.
-
-Each register class has a number, which is the value of casting
-the class name to type @code{int}. The number serves as an index
-in many of the tables described below.
-@end deftp
-
-@defmac N_REG_CLASSES
-The number of distinct register classes, defined as follows:
-
-@smallexample
-#define N_REG_CLASSES (int) LIM_REG_CLASSES
-@end smallexample
-@end defmac
-
-@defmac REG_CLASS_NAMES
-An initializer containing the names of the register classes as C string
-constants. These names are used in writing some of the debugging dumps.
-@end defmac
-
-@defmac REG_CLASS_CONTENTS
-An initializer containing the contents of the register classes, as integers
-which are bit masks. The @var{n}th integer specifies the contents of class
-@var{n}. The way the integer @var{mask} is interpreted is that
-register @var{r} is in the class if @code{@var{mask} & (1 << @var{r})} is 1.
-
-When the machine has more than 32 registers, an integer does not suffice.
-Then the integers are replaced by sub-initializers, braced groupings containing
-several integers. Each sub-initializer must be suitable as an initializer
-for the type @code{HARD_REG_SET} which is defined in @file{hard-reg-set.h}.
-In this situation, the first integer in each sub-initializer corresponds to
-registers 0 through 31, the second integer to registers 32 through 63, and
-so on.
-@end defmac
-
-@defmac REGNO_REG_CLASS (@var{regno})
-A C expression whose value is a register class containing hard register
-@var{regno}. In general there is more than one such class; choose a class
-which is @dfn{minimal}, meaning that no smaller class also contains the
-register.
-@end defmac
-
-@defmac BASE_REG_CLASS
-A macro whose definition is the name of the class to which a valid
-base register must belong. A base register is one used in an address
-which is the register value plus a displacement.
-@end defmac
-
-@defmac MODE_BASE_REG_CLASS (@var{mode})
-This is a variation of the @code{BASE_REG_CLASS} macro which allows
-the selection of a base register in a mode dependent manner. If
-@var{mode} is VOIDmode then it should return the same value as
-@code{BASE_REG_CLASS}.
-@end defmac
-
-@defmac MODE_BASE_REG_REG_CLASS (@var{mode})
-A C expression whose value is the register class to which a valid
-base register must belong in order to be used in a base plus index
-register address. You should define this macro if base plus index
-addresses have different requirements than other base register uses.
-@end defmac
-
-@defmac MODE_CODE_BASE_REG_CLASS (@var{mode}, @var{address_space}, @var{outer_code}, @var{index_code})
-A C expression whose value is the register class to which a valid
-base register for a memory reference in mode @var{mode} to address
-space @var{address_space} must belong. @var{outer_code} and @var{index_code}
-define the context in which the base register occurs. @var{outer_code} is
-the code of the immediately enclosing expression (@code{MEM} for the top level
-of an address, @code{ADDRESS} for something that occurs in an
-@code{address_operand}). @var{index_code} is the code of the corresponding
-index expression if @var{outer_code} is @code{PLUS}; @code{SCRATCH} otherwise.
-@end defmac
-
-@defmac INDEX_REG_CLASS
-A macro whose definition is the name of the class to which a valid
-index register must belong. An index register is one used in an
-address where its value is either multiplied by a scale factor or
-added to another register (as well as added to a displacement).
-@end defmac
-
-@defmac REGNO_OK_FOR_BASE_P (@var{num})
-A C expression which is nonzero if register number @var{num} is
-suitable for use as a base register in operand addresses.
-@end defmac
-
-@defmac REGNO_MODE_OK_FOR_BASE_P (@var{num}, @var{mode})
-A C expression that is just like @code{REGNO_OK_FOR_BASE_P}, except that
-that expression may examine the mode of the memory reference in
-@var{mode}. You should define this macro if the mode of the memory
-reference affects whether a register may be used as a base register. If
-you define this macro, the compiler will use it instead of
-@code{REGNO_OK_FOR_BASE_P}. The mode may be @code{VOIDmode} for
-addresses that appear outside a @code{MEM}, i.e., as an
-@code{address_operand}.
-@end defmac
-
-@defmac REGNO_MODE_OK_FOR_REG_BASE_P (@var{num}, @var{mode})
-A C expression which is nonzero if register number @var{num} is suitable for
-use as a base register in base plus index operand addresses, accessing
-memory in mode @var{mode}. It may be either a suitable hard register or a
-pseudo register that has been allocated such a hard register. You should
-define this macro if base plus index addresses have different requirements
-than other base register uses.
-
-Use of this macro is deprecated; please use the more general
-@code{REGNO_MODE_CODE_OK_FOR_BASE_P}.
-@end defmac
-
-@defmac REGNO_MODE_CODE_OK_FOR_BASE_P (@var{num}, @var{mode}, @var{address_space}, @var{outer_code}, @var{index_code})
-A C expression which is nonzero if register number @var{num} is
-suitable for use as a base register in operand addresses, accessing
-memory in mode @var{mode} in address space @var{address_space}.
-This is similar to @code{REGNO_MODE_OK_FOR_BASE_P}, except
-that that expression may examine the context in which the register
-appears in the memory reference. @var{outer_code} is the code of the
-immediately enclosing expression (@code{MEM} if at the top level of the
-address, @code{ADDRESS} for something that occurs in an
-@code{address_operand}). @var{index_code} is the code of the
-corresponding index expression if @var{outer_code} is @code{PLUS};
-@code{SCRATCH} otherwise. The mode may be @code{VOIDmode} for addresses
-that appear outside a @code{MEM}, i.e., as an @code{address_operand}.
-@end defmac
-
-@defmac REGNO_OK_FOR_INDEX_P (@var{num})
-A C expression which is nonzero if register number @var{num} is
-suitable for use as an index register in operand addresses. It may be
-either a suitable hard register or a pseudo register that has been
-allocated such a hard register.
-
-The difference between an index register and a base register is that
-the index register may be scaled. If an address involves the sum of
-two registers, neither one of them scaled, then either one may be
-labeled the ``base'' and the other the ``index''; but whichever
-labeling is used must fit the machine's constraints of which registers
-may serve in each capacity. The compiler will try both labelings,
-looking for one that is valid, and will reload one or both registers
-only if neither labeling works.
-@end defmac
-
-@deftypefn {Target Hook} reg_class_t TARGET_PREFERRED_RENAME_CLASS (reg_class_t @var{rclass})
-A target hook that places additional preference on the register
-class to use when it is necessary to rename a register in class
-@var{rclass} to another class, or perhaps @var{NO_REGS}, if no
-preferred register class is found or hook @code{preferred_rename_class}
-is not implemented.
-Sometimes returning a more restrictive class makes better code. For
-example, on ARM, thumb-2 instructions using @code{LO_REGS} may be
-smaller than instructions using @code{GENERIC_REGS}. By returning
-@code{LO_REGS} from @code{preferred_rename_class}, code size can
-be reduced.
-@end deftypefn
-
-@deftypefn {Target Hook} reg_class_t TARGET_PREFERRED_RELOAD_CLASS (rtx @var{x}, reg_class_t @var{rclass})
-A target hook that places additional restrictions on the register class
-to use when it is necessary to copy value @var{x} into a register in class
-@var{rclass}. The value is a register class; perhaps @var{rclass}, or perhaps
-another, smaller class.
-
-The default version of this hook always returns value of @code{rclass} argument.
-
-Sometimes returning a more restrictive class makes better code. For
-example, on the 68000, when @var{x} is an integer constant that is in range
-for a @samp{moveq} instruction, the value of this macro is always
-@code{DATA_REGS} as long as @var{rclass} includes the data registers.
-Requiring a data register guarantees that a @samp{moveq} will be used.
-
-One case where @code{TARGET_PREFERRED_RELOAD_CLASS} must not return
-@var{rclass} is if @var{x} is a legitimate constant which cannot be
-loaded into some register class. By returning @code{NO_REGS} you can
-force @var{x} into a memory location. For example, rs6000 can load
-immediate values into general-purpose registers, but does not have an
-instruction for loading an immediate value into a floating-point
-register, so @code{TARGET_PREFERRED_RELOAD_CLASS} returns @code{NO_REGS} when
-@var{x} is a floating-point constant. If the constant can't be loaded
-into any kind of register, code generation will be better if
-@code{TARGET_LEGITIMATE_CONSTANT_P} makes the constant illegitimate instead
-of using @code{TARGET_PREFERRED_RELOAD_CLASS}.
-
-If an insn has pseudos in it after register allocation, reload will go
-through the alternatives and call repeatedly @code{TARGET_PREFERRED_RELOAD_CLASS}
-to find the best one. Returning @code{NO_REGS}, in this case, makes
-reload add a @code{!} in front of the constraint: the x86 back-end uses
-this feature to discourage usage of 387 registers when math is done in
-the SSE registers (and vice versa).
-@end deftypefn
-
-@defmac PREFERRED_RELOAD_CLASS (@var{x}, @var{class})
-A C expression that places additional restrictions on the register class
-to use when it is necessary to copy value @var{x} into a register in class
-@var{class}. The value is a register class; perhaps @var{class}, or perhaps
-another, smaller class. On many machines, the following definition is
-safe:
-
-@smallexample
-#define PREFERRED_RELOAD_CLASS(X,CLASS) CLASS
-@end smallexample
-
-Sometimes returning a more restrictive class makes better code. For
-example, on the 68000, when @var{x} is an integer constant that is in range
-for a @samp{moveq} instruction, the value of this macro is always
-@code{DATA_REGS} as long as @var{class} includes the data registers.
-Requiring a data register guarantees that a @samp{moveq} will be used.
-
-One case where @code{PREFERRED_RELOAD_CLASS} must not return
-@var{class} is if @var{x} is a legitimate constant which cannot be
-loaded into some register class. By returning @code{NO_REGS} you can
-force @var{x} into a memory location. For example, rs6000 can load
-immediate values into general-purpose registers, but does not have an
-instruction for loading an immediate value into a floating-point
-register, so @code{PREFERRED_RELOAD_CLASS} returns @code{NO_REGS} when
-@var{x} is a floating-point constant. If the constant cannot be loaded
-into any kind of register, code generation will be better if
-@code{TARGET_LEGITIMATE_CONSTANT_P} makes the constant illegitimate instead
-of using @code{TARGET_PREFERRED_RELOAD_CLASS}.
-
-If an insn has pseudos in it after register allocation, reload will go
-through the alternatives and call repeatedly @code{PREFERRED_RELOAD_CLASS}
-to find the best one. Returning @code{NO_REGS}, in this case, makes
-reload add a @code{!} in front of the constraint: the x86 back-end uses
-this feature to discourage usage of 387 registers when math is done in
-the SSE registers (and vice versa).
-@end defmac
-
-@deftypefn {Target Hook} reg_class_t TARGET_PREFERRED_OUTPUT_RELOAD_CLASS (rtx @var{x}, reg_class_t @var{rclass})
-Like @code{TARGET_PREFERRED_RELOAD_CLASS}, but for output reloads instead of
-input reloads.
-
-The default version of this hook always returns value of @code{rclass}
-argument.
-
-You can also use @code{TARGET_PREFERRED_OUTPUT_RELOAD_CLASS} to discourage
-reload from using some alternatives, like @code{TARGET_PREFERRED_RELOAD_CLASS}.
-@end deftypefn
-
-@defmac LIMIT_RELOAD_CLASS (@var{mode}, @var{class})
-A C expression that places additional restrictions on the register class
-to use when it is necessary to be able to hold a value of mode
-@var{mode} in a reload register for which class @var{class} would
-ordinarily be used.
-
-Unlike @code{PREFERRED_RELOAD_CLASS}, this macro should be used when
-there are certain modes that simply cannot go in certain reload classes.
-
-The value is a register class; perhaps @var{class}, or perhaps another,
-smaller class.
-
-Don't define this macro unless the target machine has limitations which
-require the macro to do something nontrivial.
-@end defmac
-
-@deftypefn {Target Hook} reg_class_t TARGET_SECONDARY_RELOAD (bool @var{in_p}, rtx @var{x}, reg_class_t @var{reload_class}, machine_mode @var{reload_mode}, secondary_reload_info *@var{sri})
-Many machines have some registers that cannot be copied directly to or
-from memory or even from other types of registers. An example is the
-@samp{MQ} register, which on most machines, can only be copied to or
-from general registers, but not memory. Below, we shall be using the
-term 'intermediate register' when a move operation cannot be performed
-directly, but has to be done by copying the source into the intermediate
-register first, and then copying the intermediate register to the
-destination. An intermediate register always has the same mode as
-source and destination. Since it holds the actual value being copied,
-reload might apply optimizations to re-use an intermediate register
-and eliding the copy from the source when it can determine that the
-intermediate register still holds the required value.
-
-Another kind of secondary reload is required on some machines which
-allow copying all registers to and from memory, but require a scratch
-register for stores to some memory locations (e.g., those with symbolic
-address on the RT, and those with certain symbolic address on the SPARC
-when compiling PIC)@. Scratch registers need not have the same mode
-as the value being copied, and usually hold a different value than
-that being copied. Special patterns in the md file are needed to
-describe how the copy is performed with the help of the scratch register;
-these patterns also describe the number, register class(es) and mode(s)
-of the scratch register(s).
-
-In some cases, both an intermediate and a scratch register are required.
-
-For input reloads, this target hook is called with nonzero @var{in_p},
-and @var{x} is an rtx that needs to be copied to a register of class
-@var{reload_class} in @var{reload_mode}. For output reloads, this target
-hook is called with zero @var{in_p}, and a register of class @var{reload_class}
-needs to be copied to rtx @var{x} in @var{reload_mode}.
-
-If copying a register of @var{reload_class} from/to @var{x} requires
-an intermediate register, the hook @code{secondary_reload} should
-return the register class required for this intermediate register.
-If no intermediate register is required, it should return NO_REGS.
-If more than one intermediate register is required, describe the one
-that is closest in the copy chain to the reload register.
-
-If scratch registers are needed, you also have to describe how to
-perform the copy from/to the reload register to/from this
-closest intermediate register. Or if no intermediate register is
-required, but still a scratch register is needed, describe the
-copy from/to the reload register to/from the reload operand @var{x}.
-
-You do this by setting @code{sri->icode} to the instruction code of a pattern
-in the md file which performs the move. Operands 0 and 1 are the output
-and input of this copy, respectively. Operands from operand 2 onward are
-for scratch operands. These scratch operands must have a mode, and a
-single-register-class
-@c [later: or memory]
-output constraint.
-
-When an intermediate register is used, the @code{secondary_reload}
-hook will be called again to determine how to copy the intermediate
-register to/from the reload operand @var{x}, so your hook must also
-have code to handle the register class of the intermediate operand.
-
-@c [For later: maybe we'll allow multi-alternative reload patterns -
-@c the port maintainer could name a mov<mode> pattern that has clobbers -
-@c and match the constraints of input and output to determine the required
-@c alternative. A restriction would be that constraints used to match
-@c against reloads registers would have to be written as register class
-@c constraints, or we need a new target macro / hook that tells us if an
-@c arbitrary constraint can match an unknown register of a given class.
-@c Such a macro / hook would also be useful in other places.]
-
-
-@var{x} might be a pseudo-register or a @code{subreg} of a
-pseudo-register, which could either be in a hard register or in memory.
-Use @code{true_regnum} to find out; it will return @minus{}1 if the pseudo is
-in memory and the hard register number if it is in a register.
-
-Scratch operands in memory (constraint @code{"=m"} / @code{"=&m"}) are
-currently not supported. For the time being, you will have to continue
-to use @code{TARGET_SECONDARY_MEMORY_NEEDED} for that purpose.
-
-@code{copy_cost} also uses this target hook to find out how values are
-copied. If you want it to include some extra cost for the need to allocate
-(a) scratch register(s), set @code{sri->extra_cost} to the additional cost.
-Or if two dependent moves are supposed to have a lower cost than the sum
-of the individual moves due to expected fortuitous scheduling and/or special
-forwarding logic, you can set @code{sri->extra_cost} to a negative amount.
-@end deftypefn
-
-@defmac SECONDARY_RELOAD_CLASS (@var{class}, @var{mode}, @var{x})
-@defmacx SECONDARY_INPUT_RELOAD_CLASS (@var{class}, @var{mode}, @var{x})
-@defmacx SECONDARY_OUTPUT_RELOAD_CLASS (@var{class}, @var{mode}, @var{x})
-These macros are obsolete, new ports should use the target hook
-@code{TARGET_SECONDARY_RELOAD} instead.
-
-These are obsolete macros, replaced by the @code{TARGET_SECONDARY_RELOAD}
-target hook. Older ports still define these macros to indicate to the
-reload phase that it may
-need to allocate at least one register for a reload in addition to the
-register to contain the data. Specifically, if copying @var{x} to a
-register @var{class} in @var{mode} requires an intermediate register,
-you were supposed to define @code{SECONDARY_INPUT_RELOAD_CLASS} to return the
-largest register class all of whose registers can be used as
-intermediate registers or scratch registers.
-
-If copying a register @var{class} in @var{mode} to @var{x} requires an
-intermediate or scratch register, @code{SECONDARY_OUTPUT_RELOAD_CLASS}
-was supposed to be defined to return the largest register
-class required. If the
-requirements for input and output reloads were the same, the macro
-@code{SECONDARY_RELOAD_CLASS} should have been used instead of defining both
-macros identically.
-
-The values returned by these macros are often @code{GENERAL_REGS}.
-Return @code{NO_REGS} if no spare register is needed; i.e., if @var{x}
-can be directly copied to or from a register of @var{class} in
-@var{mode} without requiring a scratch register. Do not define this
-macro if it would always return @code{NO_REGS}.
-
-If a scratch register is required (either with or without an
-intermediate register), you were supposed to define patterns for
-@samp{reload_in@var{m}} or @samp{reload_out@var{m}}, as required
-(@pxref{Standard Names}. These patterns, which were normally
-implemented with a @code{define_expand}, should be similar to the
-@samp{mov@var{m}} patterns, except that operand 2 is the scratch
-register.
-
-These patterns need constraints for the reload register and scratch
-register that
-contain a single register class. If the original reload register (whose
-class is @var{class}) can meet the constraint given in the pattern, the
-value returned by these macros is used for the class of the scratch
-register. Otherwise, two additional reload registers are required.
-Their classes are obtained from the constraints in the insn pattern.
-
-@var{x} might be a pseudo-register or a @code{subreg} of a
-pseudo-register, which could either be in a hard register or in memory.
-Use @code{true_regnum} to find out; it will return @minus{}1 if the pseudo is
-in memory and the hard register number if it is in a register.
-
-These macros should not be used in the case where a particular class of
-registers can only be copied to memory and not to another class of
-registers. In that case, secondary reload registers are not needed and
-would not be helpful. Instead, a stack location must be used to perform
-the copy and the @code{mov@var{m}} pattern should use memory as an
-intermediate storage. This case often occurs between floating-point and
-general registers.
-@end defmac
-
-@deftypefn {Target Hook} bool TARGET_SECONDARY_MEMORY_NEEDED (machine_mode @var{mode}, reg_class_t @var{class1}, reg_class_t @var{class2})
-Certain machines have the property that some registers cannot be copied
-to some other registers without using memory. Define this hook on
-those machines to return true if objects of mode @var{m} in registers
-of @var{class1} can only be copied to registers of class @var{class2} by
- storing a register of @var{class1} into memory and loading that memory
-location into a register of @var{class2}. The default definition returns
-false for all inputs.
-@end deftypefn
-
-@defmac SECONDARY_MEMORY_NEEDED_RTX (@var{mode})
-Normally when @code{TARGET_SECONDARY_MEMORY_NEEDED} is defined, the compiler
-allocates a stack slot for a memory location needed for register copies.
-If this macro is defined, the compiler instead uses the memory location
-defined by this macro.
-
-Do not define this macro if you do not define
-@code{TARGET_SECONDARY_MEMORY_NEEDED}.
-@end defmac
-
-@deftypefn {Target Hook} machine_mode TARGET_SECONDARY_MEMORY_NEEDED_MODE (machine_mode @var{mode})
-If @code{TARGET_SECONDARY_MEMORY_NEEDED} tells the compiler to use memory
-when moving between two particular registers of mode @var{mode},
-this hook specifies the mode that the memory should have.
-
-The default depends on @code{TARGET_LRA_P}. Without LRA, the default
-is to use a word-sized mode for integral modes that are smaller than a
-a word. This is right thing to do on most machines because it ensures
-that all bits of the register are copied and prevents accesses to the
-registers in a narrower mode, which some machines prohibit for
-floating-point registers.
-
-However, this default behavior is not correct on some machines, such as
-the DEC Alpha, that store short integers in floating-point registers
-differently than in integer registers. On those machines, the default
-widening will not work correctly and you must define this hook to
-suppress that widening in some cases. See the file @file{alpha.cc} for
-details.
-
-With LRA, the default is to use @var{mode} unmodified.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_SELECT_EARLY_REMAT_MODES (sbitmap @var{modes})
-On some targets, certain modes cannot be held in registers around a
-standard ABI call and are relatively expensive to spill to the stack.
-The early rematerialization pass can help in such cases by aggressively
-recomputing values after calls, so that they don't need to be spilled.
-
-This hook returns the set of such modes by setting the associated bits
-in @var{modes}. The default implementation selects no modes, which has
-the effect of disabling the early rematerialization pass.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_CLASS_LIKELY_SPILLED_P (reg_class_t @var{rclass})
-A target hook which returns @code{true} if pseudos that have been assigned
-to registers of class @var{rclass} would likely be spilled because
-registers of @var{rclass} are needed for spill registers.
-
-The default version of this target hook returns @code{true} if @var{rclass}
-has exactly one register and @code{false} otherwise. On most machines, this
-default should be used. For generally register-starved machines, such as
-i386, or machines with right register constraints, such as SH, this hook
-can be used to avoid excessive spilling.
-
-This hook is also used by some of the global intra-procedural code
-transformations to throtle code motion, to avoid increasing register
-pressure.
-@end deftypefn
-
-@deftypefn {Target Hook} {unsigned char} TARGET_CLASS_MAX_NREGS (reg_class_t @var{rclass}, machine_mode @var{mode})
-A target hook returns the maximum number of consecutive registers
-of class @var{rclass} needed to hold a value of mode @var{mode}.
-
-This is closely related to the macro @code{TARGET_HARD_REGNO_NREGS}.
-In fact, the value returned by @code{TARGET_CLASS_MAX_NREGS (@var{rclass},
-@var{mode})} target hook should be the maximum value of
-@code{TARGET_HARD_REGNO_NREGS (@var{regno}, @var{mode})} for all @var{regno}
-values in the class @var{rclass}.
-
-This target hook helps control the handling of multiple-word values
-in the reload pass.
-
-The default version of this target hook returns the size of @var{mode}
-in words.
-@end deftypefn
-
-@defmac CLASS_MAX_NREGS (@var{class}, @var{mode})
-A C expression for the maximum number of consecutive registers
-of class @var{class} needed to hold a value of mode @var{mode}.
-
-This is closely related to the macro @code{TARGET_HARD_REGNO_NREGS}. In fact,
-the value of the macro @code{CLASS_MAX_NREGS (@var{class}, @var{mode})}
-should be the maximum value of @code{TARGET_HARD_REGNO_NREGS (@var{regno},
-@var{mode})} for all @var{regno} values in the class @var{class}.
-
-This macro helps control the handling of multiple-word values
-in the reload pass.
-@end defmac
-
-@deftypefn {Target Hook} bool TARGET_CAN_CHANGE_MODE_CLASS (machine_mode @var{from}, machine_mode @var{to}, reg_class_t @var{rclass})
-This hook returns true if it is possible to bitcast values held in
-registers of class @var{rclass} from mode @var{from} to mode @var{to}
-and if doing so preserves the low-order bits that are common to both modes.
-The result is only meaningful if @var{rclass} has registers that can hold
-both @code{from} and @code{to}. The default implementation returns true.
-
-As an example of when such bitcasting is invalid, loading 32-bit integer or
-floating-point objects into floating-point registers on Alpha extends them
-to 64 bits. Therefore loading a 64-bit object and then storing it as a
-32-bit object does not store the low-order 32 bits, as would be the case
-for a normal register. Therefore, @file{alpha.h} defines
-@code{TARGET_CAN_CHANGE_MODE_CLASS} to return:
-
-@smallexample
-(GET_MODE_SIZE (from) == GET_MODE_SIZE (to)
- || !reg_classes_intersect_p (FLOAT_REGS, rclass))
-@end smallexample
-
-Even if storing from a register in mode @var{to} would be valid,
-if both @var{from} and @code{raw_reg_mode} for @var{rclass} are wider
-than @code{word_mode}, then we must prevent @var{to} narrowing the
-mode. This happens when the middle-end assumes that it can load
-or store pieces of an @var{N}-word pseudo, and that the pseudo will
-eventually be allocated to @var{N} @code{word_mode} hard registers.
-Failure to prevent this kind of mode change will result in the
-entire @code{raw_reg_mode} being modified instead of the partial
-value that the middle-end intended.
-@end deftypefn
-
-@deftypefn {Target Hook} reg_class_t TARGET_IRA_CHANGE_PSEUDO_ALLOCNO_CLASS (int, @var{reg_class_t}, @var{reg_class_t})
-A target hook which can change allocno class for given pseudo from
- allocno and best class calculated by IRA.
-
- The default version of this target hook always returns given class.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_LRA_P (void)
-A target hook which returns true if we use LRA instead of reload pass.
-
-The default version of this target hook returns true. New ports
-should use LRA, and existing ports are encouraged to convert.
-@end deftypefn
-
-@deftypefn {Target Hook} int TARGET_REGISTER_PRIORITY (int)
-A target hook which returns the register priority number to which the
-register @var{hard_regno} belongs to. The bigger the number, the
-more preferable the hard register usage (when all other conditions are
-the same). This hook can be used to prefer some hard register over
-others in LRA. For example, some x86-64 register usage needs
-additional prefix which makes instructions longer. The hook can
-return lower priority number for such registers make them less favorable
-and as result making the generated code smaller.
-
-The default version of this target hook returns always zero.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_REGISTER_USAGE_LEVELING_P (void)
-A target hook which returns true if we need register usage leveling.
-That means if a few hard registers are equally good for the
-assignment, we choose the least used hard register. The register
-usage leveling may be profitable for some targets. Don't use the
-usage leveling for targets with conditional execution or targets
-with big register files as it hurts if-conversion and cross-jumping
-optimizations.
-
-The default version of this target hook returns always false.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_DIFFERENT_ADDR_DISPLACEMENT_P (void)
-A target hook which returns true if an address with the same structure
-can have different maximal legitimate displacement. For example, the
-displacement can depend on memory mode or on operand combinations in
-the insn.
-
-The default version of this target hook returns always false.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_CANNOT_SUBSTITUTE_MEM_EQUIV_P (rtx @var{subst})
-A target hook which returns @code{true} if @var{subst} can't
-substitute safely pseudos with equivalent memory values during
-register allocation.
-The default version of this target hook returns @code{false}.
-On most machines, this default should be used. For generally
-machines with non orthogonal register usage for addressing, such
-as SH, this hook can be used to avoid excessive spilling.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_LEGITIMIZE_ADDRESS_DISPLACEMENT (rtx *@var{offset1}, rtx *@var{offset2}, poly_int64 @var{orig_offset}, machine_mode @var{mode})
-This hook tries to split address offset @var{orig_offset} into
-two parts: one that should be added to the base address to create
-a local anchor point, and an additional offset that can be applied
-to the anchor to address a value of mode @var{mode}. The idea is that
-the local anchor could be shared by other accesses to nearby locations.
-
-The hook returns true if it succeeds, storing the offset of the
-anchor from the base in @var{offset1} and the offset of the final address
-from the anchor in @var{offset2}. The default implementation returns false.
-@end deftypefn
-
-@deftypefn {Target Hook} reg_class_t TARGET_SPILL_CLASS (reg_class_t, @var{machine_mode})
-This hook defines a class of registers which could be used for spilling
-pseudos of the given mode and class, or @code{NO_REGS} if only memory
-should be used. Not defining this hook is equivalent to returning
-@code{NO_REGS} for all inputs.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_ADDITIONAL_ALLOCNO_CLASS_P (reg_class_t)
-This hook should return @code{true} if given class of registers should
-be an allocno class in any way. Usually RA uses only one register
-class from all classes containing the same register set. In some
-complicated cases, you need to have two or more such classes as
-allocno ones for RA correct work. Not defining this hook is
-equivalent to returning @code{false} for all inputs.
-@end deftypefn
-
-@deftypefn {Target Hook} scalar_int_mode TARGET_CSTORE_MODE (enum insn_code @var{icode})
-This hook defines the machine mode to use for the boolean result of
-conditional store patterns. The ICODE argument is the instruction code
-for the cstore being performed. Not definiting this hook is the same
-as accepting the mode encoded into operand 0 of the cstore expander
-patterns.
-@end deftypefn
-
-@deftypefn {Target Hook} int TARGET_COMPUTE_PRESSURE_CLASSES (enum reg_class *@var{pressure_classes})
-A target hook which lets a backend compute the set of pressure classes to
-be used by those optimization passes which take register pressure into
-account, as opposed to letting IRA compute them. It returns the number of
-register classes stored in the array @var{pressure_classes}.
-@end deftypefn
-
-@node Stack and Calling
-@section Stack Layout and Calling Conventions
-@cindex calling conventions
-
-@c prevent bad page break with this line
-This describes the stack layout and calling conventions.
-
-@menu
-* Frame Layout::
-* Exception Handling::
-* Stack Checking::
-* Frame Registers::
-* Elimination::
-* Stack Arguments::
-* Register Arguments::
-* Scalar Return::
-* Aggregate Return::
-* Caller Saves::
-* Function Entry::
-* Profiling::
-* Tail Calls::
-* Shrink-wrapping separate components::
-* Stack Smashing Protection::
-* Miscellaneous Register Hooks::
-@end menu
-
-@node Frame Layout
-@subsection Basic Stack Layout
-@cindex stack frame layout
-@cindex frame layout
-
-@c prevent bad page break with this line
-Here is the basic stack layout.
-
-@defmac STACK_GROWS_DOWNWARD
-Define this macro to be true if pushing a word onto the stack moves the stack
-pointer to a smaller address, and false otherwise.
-@end defmac
-
-@defmac STACK_PUSH_CODE
-This macro defines the operation used when something is pushed
-on the stack. In RTL, a push operation will be
-@code{(set (mem (STACK_PUSH_CODE (reg sp))) @dots{})}
-
-The choices are @code{PRE_DEC}, @code{POST_DEC}, @code{PRE_INC},
-and @code{POST_INC}. Which of these is correct depends on
-the stack direction and on whether the stack pointer points
-to the last item on the stack or whether it points to the
-space for the next item on the stack.
-
-The default is @code{PRE_DEC} when @code{STACK_GROWS_DOWNWARD} is
-true, which is almost always right, and @code{PRE_INC} otherwise,
-which is often wrong.
-@end defmac
-
-@defmac FRAME_GROWS_DOWNWARD
-Define this macro to nonzero value if the addresses of local variable slots
-are at negative offsets from the frame pointer.
-@end defmac
-
-@defmac ARGS_GROW_DOWNWARD
-Define this macro if successive arguments to a function occupy decreasing
-addresses on the stack.
-@end defmac
-
-@deftypefn {Target Hook} HOST_WIDE_INT TARGET_STARTING_FRAME_OFFSET (void)
-This hook returns the offset from the frame pointer to the first local
-variable slot to be allocated. If @code{FRAME_GROWS_DOWNWARD}, it is the
-offset to @emph{end} of the first slot allocated, otherwise it is the
-offset to @emph{beginning} of the first slot allocated. The default
-implementation returns 0.
-@end deftypefn
-
-@defmac STACK_ALIGNMENT_NEEDED
-Define to zero to disable final alignment of the stack during reload.
-The nonzero default for this macro is suitable for most ports.
-
-On ports where @code{TARGET_STARTING_FRAME_OFFSET} is nonzero or where there
-is a register save block following the local block that doesn't require
-alignment to @code{STACK_BOUNDARY}, it may be beneficial to disable
-stack alignment and do it in the backend.
-@end defmac
-
-@defmac STACK_POINTER_OFFSET
-Offset from the stack pointer register to the first location at which
-outgoing arguments are placed. If not specified, the default value of
-zero is used. This is the proper value for most machines.
-
-If @code{ARGS_GROW_DOWNWARD}, this is the offset to the location above
-the first location at which outgoing arguments are placed.
-@end defmac
-
-@defmac FIRST_PARM_OFFSET (@var{fundecl})
-Offset from the argument pointer register to the first argument's
-address. On some machines it may depend on the data type of the
-function.
-
-If @code{ARGS_GROW_DOWNWARD}, this is the offset to the location above
-the first argument's address.
-@end defmac
-
-@defmac STACK_DYNAMIC_OFFSET (@var{fundecl})
-Offset from the stack pointer register to an item dynamically allocated
-on the stack, e.g., by @code{alloca}.
-
-The default value for this macro is @code{STACK_POINTER_OFFSET} plus the
-length of the outgoing arguments. The default is correct for most
-machines. See @file{function.cc} for details.
-@end defmac
-
-@defmac INITIAL_FRAME_ADDRESS_RTX
-A C expression whose value is RTL representing the address of the initial
-stack frame. This address is passed to @code{RETURN_ADDR_RTX} and
-@code{DYNAMIC_CHAIN_ADDRESS}. If you don't define this macro, a reasonable
-default value will be used. Define this macro in order to make frame pointer
-elimination work in the presence of @code{__builtin_frame_address (count)} and
-@code{__builtin_return_address (count)} for @code{count} not equal to zero.
-@end defmac
-
-@defmac DYNAMIC_CHAIN_ADDRESS (@var{frameaddr})
-A C expression whose value is RTL representing the address in a stack
-frame where the pointer to the caller's frame is stored. Assume that
-@var{frameaddr} is an RTL expression for the address of the stack frame
-itself.
-
-If you don't define this macro, the default is to return the value
-of @var{frameaddr}---that is, the stack frame address is also the
-address of the stack word that points to the previous frame.
-@end defmac
-
-@defmac SETUP_FRAME_ADDRESSES
-A C expression that produces the machine-specific code to
-setup the stack so that arbitrary frames can be accessed. For example,
-on the SPARC, we must flush all of the register windows to the stack
-before we can access arbitrary stack frames. You will seldom need to
-define this macro. The default is to do nothing.
-@end defmac
-
-@deftypefn {Target Hook} rtx TARGET_BUILTIN_SETJMP_FRAME_VALUE (void)
-This target hook should return an rtx that is used to store
-the address of the current frame into the built in @code{setjmp} buffer.
-The default value, @code{virtual_stack_vars_rtx}, is correct for most
-machines. One reason you may need to define this target hook is if
-@code{hard_frame_pointer_rtx} is the appropriate value on your machine.
-@end deftypefn
-
-@defmac FRAME_ADDR_RTX (@var{frameaddr})
-A C expression whose value is RTL representing the value of the frame
-address for the current frame. @var{frameaddr} is the frame pointer
-of the current frame. This is used for __builtin_frame_address.
-You need only define this macro if the frame address is not the same
-as the frame pointer. Most machines do not need to define it.
-@end defmac
-
-@defmac RETURN_ADDR_RTX (@var{count}, @var{frameaddr})
-A C expression whose value is RTL representing the value of the return
-address for the frame @var{count} steps up from the current frame, after
-the prologue. @var{frameaddr} is the frame pointer of the @var{count}
-frame, or the frame pointer of the @var{count} @minus{} 1 frame if
-@code{RETURN_ADDR_IN_PREVIOUS_FRAME} is nonzero.
-
-The value of the expression must always be the correct address when
-@var{count} is zero, but may be @code{NULL_RTX} if there is no way to
-determine the return address of other frames.
-@end defmac
-
-@defmac RETURN_ADDR_IN_PREVIOUS_FRAME
-Define this macro to nonzero value if the return address of a particular
-stack frame is accessed from the frame pointer of the previous stack
-frame. The zero default for this macro is suitable for most ports.
-@end defmac
-
-@defmac INCOMING_RETURN_ADDR_RTX
-A C expression whose value is RTL representing the location of the
-incoming return address at the beginning of any function, before the
-prologue. This RTL is either a @code{REG}, indicating that the return
-value is saved in @samp{REG}, or a @code{MEM} representing a location in
-the stack.
-
-You only need to define this macro if you want to support call frame
-debugging information like that provided by DWARF 2.
-
-If this RTL is a @code{REG}, you should also define
-@code{DWARF_FRAME_RETURN_COLUMN} to @code{DWARF_FRAME_REGNUM (REGNO)}.
-@end defmac
-
-@defmac DWARF_ALT_FRAME_RETURN_COLUMN
-A C expression whose value is an integer giving a DWARF 2 column
-number that may be used as an alternative return column. The column
-must not correspond to any gcc hard register (that is, it must not
-be in the range of @code{DWARF_FRAME_REGNUM}).
-
-This macro can be useful if @code{DWARF_FRAME_RETURN_COLUMN} is set to a
-general register, but an alternative column needs to be used for signal
-frames. Some targets have also used different frame return columns
-over time.
-@end defmac
-
-@defmac DWARF_ZERO_REG
-A C expression whose value is an integer giving a DWARF 2 register
-number that is considered to always have the value zero. This should
-only be defined if the target has an architected zero register, and
-someone decided it was a good idea to use that register number to
-terminate the stack backtrace. New ports should avoid this.
-@end defmac
-
-@defmac DWARF_VERSION_DEFAULT
-A C expression whose value is the default dwarf standard version we'll honor
-and advertise when generating dwarf debug information, in absence of
-an explicit @option{-gdwarf-@var{version}} option on the command line.
-@end defmac
-
-@deftypefn {Target Hook} void TARGET_DWARF_HANDLE_FRAME_UNSPEC (const char *@var{label}, rtx @var{pattern}, int @var{index})
-This target hook allows the backend to emit frame-related insns that
-contain UNSPECs or UNSPEC_VOLATILEs. The DWARF 2 call frame debugging
-info engine will invoke it on insns of the form
-@smallexample
-(set (reg) (unspec [@dots{}] UNSPEC_INDEX))
-@end smallexample
-and
-@smallexample
-(set (reg) (unspec_volatile [@dots{}] UNSPECV_INDEX)).
-@end smallexample
-to let the backend emit the call frame instructions. @var{label} is
-the CFI label attached to the insn, @var{pattern} is the pattern of
-the insn and @var{index} is @code{UNSPEC_INDEX} or @code{UNSPECV_INDEX}.
-@end deftypefn
-
-@deftypefn {Target Hook} {unsigned int} TARGET_DWARF_POLY_INDETERMINATE_VALUE (unsigned int @var{i}, unsigned int *@var{factor}, int *@var{offset})
-Express the value of @code{poly_int} indeterminate @var{i} as a DWARF
-expression, with @var{i} counting from 1. Return the number of a DWARF
-register @var{R} and set @samp{*@var{factor}} and @samp{*@var{offset}} such
-that the value of the indeterminate is:
-@smallexample
-value_of(@var{R}) / @var{factor} - @var{offset}
-@end smallexample
-
-A target only needs to define this hook if it sets
-@samp{NUM_POLY_INT_COEFFS} to a value greater than 1.
-@end deftypefn
-
-@defmac INCOMING_FRAME_SP_OFFSET
-A C expression whose value is an integer giving the offset, in bytes,
-from the value of the stack pointer register to the top of the stack
-frame at the beginning of any function, before the prologue. The top of
-the frame is defined to be the value of the stack pointer in the
-previous frame, just before the call instruction.
-
-You only need to define this macro if you want to support call frame
-debugging information like that provided by DWARF 2.
-@end defmac
-
-@defmac DEFAULT_INCOMING_FRAME_SP_OFFSET
-Like @code{INCOMING_FRAME_SP_OFFSET}, but must be the same for all
-functions of the same ABI, and when using GAS @code{.cfi_*} directives
-must also agree with the default CFI GAS emits. Define this macro
-only if @code{INCOMING_FRAME_SP_OFFSET} can have different values
-between different functions of the same ABI or when
-@code{INCOMING_FRAME_SP_OFFSET} does not agree with GAS default CFI.
-@end defmac
-
-@defmac ARG_POINTER_CFA_OFFSET (@var{fundecl})
-A C expression whose value is an integer giving the offset, in bytes,
-from the argument pointer to the canonical frame address (cfa). The
-final value should coincide with that calculated by
-@code{INCOMING_FRAME_SP_OFFSET}. Which is unfortunately not usable
-during virtual register instantiation.
-
-The default value for this macro is
-@code{FIRST_PARM_OFFSET (fundecl) + crtl->args.pretend_args_size},
-which is correct for most machines; in general, the arguments are found
-immediately before the stack frame. Note that this is not the case on
-some targets that save registers into the caller's frame, such as SPARC
-and rs6000, and so such targets need to define this macro.
-
-You only need to define this macro if the default is incorrect, and you
-want to support call frame debugging information like that provided by
-DWARF 2.
-@end defmac
-
-@defmac FRAME_POINTER_CFA_OFFSET (@var{fundecl})
-If defined, a C expression whose value is an integer giving the offset
-in bytes from the frame pointer to the canonical frame address (cfa).
-The final value should coincide with that calculated by
-@code{INCOMING_FRAME_SP_OFFSET}.
-
-Normally the CFA is calculated as an offset from the argument pointer,
-via @code{ARG_POINTER_CFA_OFFSET}, but if the argument pointer is
-variable due to the ABI, this may not be possible. If this macro is
-defined, it implies that the virtual register instantiation should be
-based on the frame pointer instead of the argument pointer. Only one
-of @code{FRAME_POINTER_CFA_OFFSET} and @code{ARG_POINTER_CFA_OFFSET}
-should be defined.
-@end defmac
-
-@defmac CFA_FRAME_BASE_OFFSET (@var{fundecl})
-If defined, a C expression whose value is an integer giving the offset
-in bytes from the canonical frame address (cfa) to the frame base used
-in DWARF 2 debug information. The default is zero. A different value
-may reduce the size of debug information on some ports.
-@end defmac
-
-@node Exception Handling
-@subsection Exception Handling Support
-@cindex exception handling
-
-@defmac EH_RETURN_DATA_REGNO (@var{N})
-A C expression whose value is the @var{N}th register number used for
-data by exception handlers, or @code{INVALID_REGNUM} if fewer than
-@var{N} registers are usable.
-
-The exception handling library routines communicate with the exception
-handlers via a set of agreed upon registers. Ideally these registers
-should be call-clobbered; it is possible to use call-saved registers,
-but may negatively impact code size. The target must support at least
-2 data registers, but should define 4 if there are enough free registers.
-
-You must define this macro if you want to support call frame exception
-handling like that provided by DWARF 2.
-@end defmac
-
-@defmac EH_RETURN_STACKADJ_RTX
-A C expression whose value is RTL representing a location in which
-to store a stack adjustment to be applied before function return.
-This is used to unwind the stack to an exception handler's call frame.
-It will be assigned zero on code paths that return normally.
-
-Typically this is a call-clobbered hard register that is otherwise
-untouched by the epilogue, but could also be a stack slot.
-
-Do not define this macro if the stack pointer is saved and restored
-by the regular prolog and epilog code in the call frame itself; in
-this case, the exception handling library routines will update the
-stack location to be restored in place. Otherwise, you must define
-this macro if you want to support call frame exception handling like
-that provided by DWARF 2.
-@end defmac
-
-@defmac EH_RETURN_HANDLER_RTX
-A C expression whose value is RTL representing a location in which
-to store the address of an exception handler to which we should
-return. It will not be assigned on code paths that return normally.
-
-Typically this is the location in the call frame at which the normal
-return address is stored. For targets that return by popping an
-address off the stack, this might be a memory address just below
-the @emph{target} call frame rather than inside the current call
-frame. If defined, @code{EH_RETURN_STACKADJ_RTX} will have already
-been assigned, so it may be used to calculate the location of the
-target call frame.
-
-Some targets have more complex requirements than storing to an
-address calculable during initial code generation. In that case
-the @code{eh_return} instruction pattern should be used instead.
-
-If you want to support call frame exception handling, you must
-define either this macro or the @code{eh_return} instruction pattern.
-@end defmac
-
-@defmac RETURN_ADDR_OFFSET
-If defined, an integer-valued C expression for which rtl will be generated
-to add it to the exception handler address before it is searched in the
-exception handling tables, and to subtract it again from the address before
-using it to return to the exception handler.
-@end defmac
-
-@defmac ASM_PREFERRED_EH_DATA_FORMAT (@var{code}, @var{global})
-This macro chooses the encoding of pointers embedded in the exception
-handling sections. If at all possible, this should be defined such
-that the exception handling section will not require dynamic relocations,
-and so may be read-only.
-
-@var{code} is 0 for data, 1 for code labels, 2 for function pointers.
-@var{global} is true if the symbol may be affected by dynamic relocations.
-The macro should return a combination of the @code{DW_EH_PE_*} defines
-as found in @file{dwarf2.h}.
-
-If this macro is not defined, pointers will not be encoded but
-represented directly.
-@end defmac
-
-@defmac ASM_MAYBE_OUTPUT_ENCODED_ADDR_RTX (@var{file}, @var{encoding}, @var{size}, @var{addr}, @var{done})
-This macro allows the target to emit whatever special magic is required
-to represent the encoding chosen by @code{ASM_PREFERRED_EH_DATA_FORMAT}.
-Generic code takes care of pc-relative and indirect encodings; this must
-be defined if the target uses text-relative or data-relative encodings.
-
-This is a C statement that branches to @var{done} if the format was
-handled. @var{encoding} is the format chosen, @var{size} is the number
-of bytes that the format occupies, @var{addr} is the @code{SYMBOL_REF}
-to be emitted.
-@end defmac
-
-@defmac MD_FALLBACK_FRAME_STATE_FOR (@var{context}, @var{fs})
-This macro allows the target to add CPU and operating system specific
-code to the call-frame unwinder for use when there is no unwind data
-available. The most common reason to implement this macro is to unwind
-through signal frames.
-
-This macro is called from @code{uw_frame_state_for} in
-@file{unwind-dw2.c}, @file{unwind-dw2-xtensa.c} and
-@file{unwind-ia64.c}. @var{context} is an @code{_Unwind_Context};
-@var{fs} is an @code{_Unwind_FrameState}. Examine @code{context->ra}
-for the address of the code being executed and @code{context->cfa} for
-the stack pointer value. If the frame can be decoded, the register
-save addresses should be updated in @var{fs} and the macro should
-evaluate to @code{_URC_NO_REASON}. If the frame cannot be decoded,
-the macro should evaluate to @code{_URC_END_OF_STACK}.
-
-For proper signal handling in Java this macro is accompanied by
-@code{MAKE_THROW_FRAME}, defined in @file{libjava/include/*-signal.h} headers.
-@end defmac
-
-@defmac MD_HANDLE_UNWABI (@var{context}, @var{fs})
-This macro allows the target to add operating system specific code to the
-call-frame unwinder to handle the IA-64 @code{.unwabi} unwinding directive,
-usually used for signal or interrupt frames.
-
-This macro is called from @code{uw_update_context} in libgcc's
-@file{unwind-ia64.c}. @var{context} is an @code{_Unwind_Context};
-@var{fs} is an @code{_Unwind_FrameState}. Examine @code{fs->unwabi}
-for the abi and context in the @code{.unwabi} directive. If the
-@code{.unwabi} directive can be handled, the register save addresses should
-be updated in @var{fs}.
-@end defmac
-
-@defmac TARGET_USES_WEAK_UNWIND_INFO
-A C expression that evaluates to true if the target requires unwind
-info to be given comdat linkage. Define it to be @code{1} if comdat
-linkage is necessary. The default is @code{0}.
-@end defmac
-
-@node Stack Checking
-@subsection Specifying How Stack Checking is Done
-
-GCC will check that stack references are within the boundaries of the
-stack, if the option @option{-fstack-check} is specified, in one of
-three ways:
-
-@enumerate
-@item
-If the value of the @code{STACK_CHECK_BUILTIN} macro is nonzero, GCC
-will assume that you have arranged for full stack checking to be done
-at appropriate places in the configuration files. GCC will not do
-other special processing.
-
-@item
-If @code{STACK_CHECK_BUILTIN} is zero and the value of the
-@code{STACK_CHECK_STATIC_BUILTIN} macro is nonzero, GCC will assume
-that you have arranged for static stack checking (checking of the
-static stack frame of functions) to be done at appropriate places
-in the configuration files. GCC will only emit code to do dynamic
-stack checking (checking on dynamic stack allocations) using the third
-approach below.
-
-@item
-If neither of the above are true, GCC will generate code to periodically
-``probe'' the stack pointer using the values of the macros defined below.
-@end enumerate
-
-If neither STACK_CHECK_BUILTIN nor STACK_CHECK_STATIC_BUILTIN is defined,
-GCC will change its allocation strategy for large objects if the option
-@option{-fstack-check} is specified: they will always be allocated
-dynamically if their size exceeds @code{STACK_CHECK_MAX_VAR_SIZE} bytes.
-
-@defmac STACK_CHECK_BUILTIN
-A nonzero value if stack checking is done by the configuration files in a
-machine-dependent manner. You should define this macro if stack checking
-is required by the ABI of your machine or if you would like to do stack
-checking in some more efficient way than the generic approach. The default
-value of this macro is zero.
-@end defmac
-
-@defmac STACK_CHECK_STATIC_BUILTIN
-A nonzero value if static stack checking is done by the configuration files
-in a machine-dependent manner. You should define this macro if you would
-like to do static stack checking in some more efficient way than the generic
-approach. The default value of this macro is zero.
-@end defmac
-
-@defmac STACK_CHECK_PROBE_INTERVAL_EXP
-An integer specifying the interval at which GCC must generate stack probe
-instructions, defined as 2 raised to this integer. You will normally
-define this macro so that the interval be no larger than the size of
-the ``guard pages'' at the end of a stack area. The default value
-of 12 (4096-byte interval) is suitable for most systems.
-@end defmac
-
-@defmac STACK_CHECK_MOVING_SP
-An integer which is nonzero if GCC should move the stack pointer page by page
-when doing probes. This can be necessary on systems where the stack pointer
-contains the bottom address of the memory area accessible to the executing
-thread at any point in time. In this situation an alternate signal stack
-is required in order to be able to recover from a stack overflow. The
-default value of this macro is zero.
-@end defmac
-
-@defmac STACK_CHECK_PROTECT
-The number of bytes of stack needed to recover from a stack overflow, for
-languages where such a recovery is supported. The default value of 4KB/8KB
-with the @code{setjmp}/@code{longjmp}-based exception handling mechanism and
-8KB/12KB with other exception handling mechanisms should be adequate for most
-architectures and operating systems.
-@end defmac
-
-The following macros are relevant only if neither STACK_CHECK_BUILTIN
-nor STACK_CHECK_STATIC_BUILTIN is defined; you can omit them altogether
-in the opposite case.
-
-@defmac STACK_CHECK_MAX_FRAME_SIZE
-The maximum size of a stack frame, in bytes. GCC will generate probe
-instructions in non-leaf functions to ensure at least this many bytes of
-stack are available. If a stack frame is larger than this size, stack
-checking will not be reliable and GCC will issue a warning. The
-default is chosen so that GCC only generates one instruction on most
-systems. You should normally not change the default value of this macro.
-@end defmac
-
-@defmac STACK_CHECK_FIXED_FRAME_SIZE
-GCC uses this value to generate the above warning message. It
-represents the amount of fixed frame used by a function, not including
-space for any callee-saved registers, temporaries and user variables.
-You need only specify an upper bound for this amount and will normally
-use the default of four words.
-@end defmac
-
-@defmac STACK_CHECK_MAX_VAR_SIZE
-The maximum size, in bytes, of an object that GCC will place in the
-fixed area of the stack frame when the user specifies
-@option{-fstack-check}.
-GCC computed the default from the values of the above macros and you will
-normally not need to override that default.
-@end defmac
-
-@deftypefn {Target Hook} HOST_WIDE_INT TARGET_STACK_CLASH_PROTECTION_ALLOCA_PROBE_RANGE (void)
-Some targets have an ABI defined interval for which no probing needs to be done.
-When a probe does need to be done this same interval is used as the probe distance
-up when doing stack clash protection for alloca.
-On such targets this value can be set to override the default probing up interval.
-Define this variable to return nonzero if such a probe range is required or zero otherwise.
-Defining this hook also requires your functions which make use of alloca to have at least 8 byes
-of outgoing arguments. If this is not the case the stack will be corrupted.
-You need not define this macro if it would always have the value zero.
-@end deftypefn
-
-@need 2000
-@node Frame Registers
-@subsection Registers That Address the Stack Frame
-
-@c prevent bad page break with this line
-This discusses registers that address the stack frame.
-
-@defmac STACK_POINTER_REGNUM
-The register number of the stack pointer register, which must also be a
-fixed register according to @code{FIXED_REGISTERS}. On most machines,
-the hardware determines which register this is.
-@end defmac
-
-@defmac FRAME_POINTER_REGNUM
-The register number of the frame pointer register, which is used to
-access automatic variables in the stack frame. On some machines, the
-hardware determines which register this is. On other machines, you can
-choose any register you wish for this purpose.
-@end defmac
-
-@defmac HARD_FRAME_POINTER_REGNUM
-On some machines the offset between the frame pointer and starting
-offset of the automatic variables is not known until after register
-allocation has been done (for example, because the saved registers are
-between these two locations). On those machines, define
-@code{FRAME_POINTER_REGNUM} the number of a special, fixed register to
-be used internally until the offset is known, and define
-@code{HARD_FRAME_POINTER_REGNUM} to be the actual hard register number
-used for the frame pointer.
-
-You should define this macro only in the very rare circumstances when it
-is not possible to calculate the offset between the frame pointer and
-the automatic variables until after register allocation has been
-completed. When this macro is defined, you must also indicate in your
-definition of @code{ELIMINABLE_REGS} how to eliminate
-@code{FRAME_POINTER_REGNUM} into either @code{HARD_FRAME_POINTER_REGNUM}
-or @code{STACK_POINTER_REGNUM}.
-
-Do not define this macro if it would be the same as
-@code{FRAME_POINTER_REGNUM}.
-@end defmac
-
-@defmac ARG_POINTER_REGNUM
-The register number of the arg pointer register, which is used to access
-the function's argument list. On some machines, this is the same as the
-frame pointer register. On some machines, the hardware determines which
-register this is. On other machines, you can choose any register you
-wish for this purpose. If this is not the same register as the frame
-pointer register, then you must mark it as a fixed register according to
-@code{FIXED_REGISTERS}, or arrange to be able to eliminate it
-(@pxref{Elimination}).
-@end defmac
-
-@defmac HARD_FRAME_POINTER_IS_FRAME_POINTER
-Define this to a preprocessor constant that is nonzero if
-@code{hard_frame_pointer_rtx} and @code{frame_pointer_rtx} should be
-the same. The default definition is @samp{(HARD_FRAME_POINTER_REGNUM
-== FRAME_POINTER_REGNUM)}; you only need to define this macro if that
-definition is not suitable for use in preprocessor conditionals.
-@end defmac
-
-@defmac HARD_FRAME_POINTER_IS_ARG_POINTER
-Define this to a preprocessor constant that is nonzero if
-@code{hard_frame_pointer_rtx} and @code{arg_pointer_rtx} should be the
-same. The default definition is @samp{(HARD_FRAME_POINTER_REGNUM ==
-ARG_POINTER_REGNUM)}; you only need to define this macro if that
-definition is not suitable for use in preprocessor conditionals.
-@end defmac
-
-@defmac RETURN_ADDRESS_POINTER_REGNUM
-The register number of the return address pointer register, which is used to
-access the current function's return address from the stack. On some
-machines, the return address is not at a fixed offset from the frame
-pointer or stack pointer or argument pointer. This register can be defined
-to point to the return address on the stack, and then be converted by
-@code{ELIMINABLE_REGS} into either the frame pointer or stack pointer.
-
-Do not define this macro unless there is no other way to get the return
-address from the stack.
-@end defmac
-
-@defmac STATIC_CHAIN_REGNUM
-@defmacx STATIC_CHAIN_INCOMING_REGNUM
-Register numbers used for passing a function's static chain pointer. If
-register windows are used, the register number as seen by the called
-function is @code{STATIC_CHAIN_INCOMING_REGNUM}, while the register
-number as seen by the calling function is @code{STATIC_CHAIN_REGNUM}. If
-these registers are the same, @code{STATIC_CHAIN_INCOMING_REGNUM} need
-not be defined.
-
-The static chain register need not be a fixed register.
-
-If the static chain is passed in memory, these macros should not be
-defined; instead, the @code{TARGET_STATIC_CHAIN} hook should be used.
-@end defmac
-
-@deftypefn {Target Hook} rtx TARGET_STATIC_CHAIN (const_tree @var{fndecl_or_type}, bool @var{incoming_p})
-This hook replaces the use of @code{STATIC_CHAIN_REGNUM} et al for
-targets that may use different static chain locations for different
-nested functions. This may be required if the target has function
-attributes that affect the calling conventions of the function and
-those calling conventions use different static chain locations.
-
-The default version of this hook uses @code{STATIC_CHAIN_REGNUM} et al.
-
-If the static chain is passed in memory, this hook should be used to
-provide rtx giving @code{mem} expressions that denote where they are stored.
-Often the @code{mem} expression as seen by the caller will be at an offset
-from the stack pointer and the @code{mem} expression as seen by the callee
-will be at an offset from the frame pointer.
-@findex stack_pointer_rtx
-@findex frame_pointer_rtx
-@findex arg_pointer_rtx
-The variables @code{stack_pointer_rtx}, @code{frame_pointer_rtx}, and
-@code{arg_pointer_rtx} will have been initialized and should be used
-to refer to those items.
-@end deftypefn
-
-@defmac DWARF_FRAME_REGISTERS
-This macro specifies the maximum number of hard registers that can be
-saved in a call frame. This is used to size data structures used in
-DWARF2 exception handling.
-
-Prior to GCC 3.0, this macro was needed in order to establish a stable
-exception handling ABI in the face of adding new hard registers for ISA
-extensions. In GCC 3.0 and later, the EH ABI is insulated from changes
-in the number of hard registers. Nevertheless, this macro can still be
-used to reduce the runtime memory requirements of the exception handling
-routines, which can be substantial if the ISA contains a lot of
-registers that are not call-saved.
-
-If this macro is not defined, it defaults to
-@code{FIRST_PSEUDO_REGISTER}.
-@end defmac
-
-@defmac PRE_GCC3_DWARF_FRAME_REGISTERS
-
-This macro is similar to @code{DWARF_FRAME_REGISTERS}, but is provided
-for backward compatibility in pre GCC 3.0 compiled code.
-
-If this macro is not defined, it defaults to
-@code{DWARF_FRAME_REGISTERS}.
-@end defmac
-
-@defmac DWARF_REG_TO_UNWIND_COLUMN (@var{regno})
-
-Define this macro if the target's representation for dwarf registers
-is different than the internal representation for unwind column.
-Given a dwarf register, this macro should return the internal unwind
-column number to use instead.
-@end defmac
-
-@defmac DWARF_FRAME_REGNUM (@var{regno})
-
-Define this macro if the target's representation for dwarf registers
-used in .eh_frame or .debug_frame is different from that used in other
-debug info sections. Given a GCC hard register number, this macro
-should return the .eh_frame register number. The default is
-@code{DEBUGGER_REGNO (@var{regno})}.
-
-@end defmac
-
-@defmac DWARF2_FRAME_REG_OUT (@var{regno}, @var{for_eh})
-
-Define this macro to map register numbers held in the call frame info
-that GCC has collected using @code{DWARF_FRAME_REGNUM} to those that
-should be output in .debug_frame (@code{@var{for_eh}} is zero) and
-.eh_frame (@code{@var{for_eh}} is nonzero). The default is to
-return @code{@var{regno}}.
-
-@end defmac
-
-@defmac REG_VALUE_IN_UNWIND_CONTEXT
-
-Define this macro if the target stores register values as
-@code{_Unwind_Word} type in unwind context. It should be defined if
-target register size is larger than the size of @code{void *}. The
-default is to store register values as @code{void *} type.
-
-@end defmac
-
-@defmac ASSUME_EXTENDED_UNWIND_CONTEXT
-
-Define this macro to be 1 if the target always uses extended unwind
-context with version, args_size and by_value fields. If it is undefined,
-it will be defined to 1 when @code{REG_VALUE_IN_UNWIND_CONTEXT} is
-defined and 0 otherwise.
-
-@end defmac
-
-@defmac DWARF_LAZY_REGISTER_VALUE (@var{regno}, @var{value})
-Define this macro if the target has pseudo DWARF registers whose
-values need to be computed lazily on demand by the unwinder (such as when
-referenced in a CFA expression). The macro returns true if @var{regno}
-is such a register and stores its value in @samp{*@var{value}} if so.
-@end defmac
-
-@node Elimination
-@subsection Eliminating Frame Pointer and Arg Pointer
-
-@c prevent bad page break with this line
-This is about eliminating the frame pointer and arg pointer.
-
-@deftypefn {Target Hook} bool TARGET_FRAME_POINTER_REQUIRED (void)
-This target hook should return @code{true} if a function must have and use
-a frame pointer. This target hook is called in the reload pass. If its return
-value is @code{true} the function will have a frame pointer.
-
-This target hook can in principle examine the current function and decide
-according to the facts, but on most machines the constant @code{false} or the
-constant @code{true} suffices. Use @code{false} when the machine allows code
-to be generated with no frame pointer, and doing so saves some time or space.
-Use @code{true} when there is no possible advantage to avoiding a frame
-pointer.
-
-In certain cases, the compiler does not know how to produce valid code
-without a frame pointer. The compiler recognizes those cases and
-automatically gives the function a frame pointer regardless of what
-@code{targetm.frame_pointer_required} returns. You don't need to worry about
-them.
-
-In a function that does not require a frame pointer, the frame pointer
-register can be allocated for ordinary usage, unless you mark it as a
-fixed register. See @code{FIXED_REGISTERS} for more information.
-
-Default return value is @code{false}.
-@end deftypefn
-
-@defmac ELIMINABLE_REGS
-This macro specifies a table of register pairs used to eliminate
-unneeded registers that point into the stack frame.
-
-The definition of this macro is a list of structure initializations, each
-of which specifies an original and replacement register.
-
-On some machines, the position of the argument pointer is not known until
-the compilation is completed. In such a case, a separate hard register
-must be used for the argument pointer. This register can be eliminated by
-replacing it with either the frame pointer or the argument pointer,
-depending on whether or not the frame pointer has been eliminated.
-
-In this case, you might specify:
-@smallexample
-#define ELIMINABLE_REGS \
-@{@{ARG_POINTER_REGNUM, STACK_POINTER_REGNUM@}, \
- @{ARG_POINTER_REGNUM, FRAME_POINTER_REGNUM@}, \
- @{FRAME_POINTER_REGNUM, STACK_POINTER_REGNUM@}@}
-@end smallexample
-
-Note that the elimination of the argument pointer with the stack pointer is
-specified first since that is the preferred elimination.
-@end defmac
-
-@deftypefn {Target Hook} bool TARGET_CAN_ELIMINATE (const int @var{from_reg}, const int @var{to_reg})
-This target hook should return @code{true} if the compiler is allowed to
-try to replace register number @var{from_reg} with register number
-@var{to_reg}. This target hook will usually be @code{true}, since most of the
-cases preventing register elimination are things that the compiler already
-knows about.
-
-Default return value is @code{true}.
-@end deftypefn
-
-@defmac INITIAL_ELIMINATION_OFFSET (@var{from-reg}, @var{to-reg}, @var{offset-var})
-This macro returns the initial difference between the specified pair
-of registers. The value would be computed from information
-such as the result of @code{get_frame_size ()} and the tables of
-registers @code{df_regs_ever_live_p} and @code{call_used_regs}.
-@end defmac
-
-@deftypefn {Target Hook} void TARGET_COMPUTE_FRAME_LAYOUT (void)
-This target hook is called once each time the frame layout needs to be
-recalculated. The calculations can be cached by the target and can then
-be used by @code{INITIAL_ELIMINATION_OFFSET} instead of re-computing the
-layout on every invocation of that hook. This is particularly useful
-for targets that have an expensive frame layout function. Implementing
-this callback is optional.
-@end deftypefn
-
-@node Stack Arguments
-@subsection Passing Function Arguments on the Stack
-@cindex arguments on stack
-@cindex stack arguments
-
-The macros in this section control how arguments are passed
-on the stack. See the following section for other macros that
-control passing certain arguments in registers.
-
-@deftypefn {Target Hook} bool TARGET_PROMOTE_PROTOTYPES (const_tree @var{fntype})
-This target hook returns @code{true} if an argument declared in a
-prototype as an integral type smaller than @code{int} should actually be
-passed as an @code{int}. In addition to avoiding errors in certain
-cases of mismatch, it also makes for better code on certain machines.
-The default is to not promote prototypes.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_PUSH_ARGUMENT (unsigned int @var{npush})
-This target hook returns @code{true} if push instructions will be
-used to pass outgoing arguments. When the push instruction usage is
-optional, @var{npush} is nonzero to indicate the number of bytes to
-push. Otherwise, @var{npush} is zero. If the target machine does not
-have a push instruction or push instruction should be avoided,
-@code{false} should be returned. That directs GCC to use an alternate
-strategy: to allocate the entire argument block and then store the
-arguments into it. If this target hook may return @code{true},
-@code{PUSH_ROUNDING} must be defined.
-@end deftypefn
-
-@defmac PUSH_ARGS_REVERSED
-A C expression. If nonzero, function arguments will be evaluated from
-last to first, rather than from first to last. If this macro is not
-defined, it defaults to @code{PUSH_ARGS} on targets where the stack
-and args grow in opposite directions, and 0 otherwise.
-@end defmac
-
-@defmac PUSH_ROUNDING (@var{npushed})
-A C expression that is the number of bytes actually pushed onto the
-stack when an instruction attempts to push @var{npushed} bytes.
-
-On some machines, the definition
-
-@smallexample
-#define PUSH_ROUNDING(BYTES) (BYTES)
-@end smallexample
-
-@noindent
-will suffice. But on other machines, instructions that appear
-to push one byte actually push two bytes in an attempt to maintain
-alignment. Then the definition should be
-
-@smallexample
-#define PUSH_ROUNDING(BYTES) (((BYTES) + 1) & ~1)
-@end smallexample
-
-If the value of this macro has a type, it should be an unsigned type.
-@end defmac
-
-@findex outgoing_args_size
-@findex crtl->outgoing_args_size
-@defmac ACCUMULATE_OUTGOING_ARGS
-A C expression. If nonzero, the maximum amount of space required for outgoing arguments
-will be computed and placed into
-@code{crtl->outgoing_args_size}. No space will be pushed
-onto the stack for each call; instead, the function prologue should
-increase the stack frame size by this amount.
-
-Setting both @code{PUSH_ARGS} and @code{ACCUMULATE_OUTGOING_ARGS}
-is not proper.
-@end defmac
-
-@defmac REG_PARM_STACK_SPACE (@var{fndecl})
-Define this macro if functions should assume that stack space has been
-allocated for arguments even when their values are passed in
-registers.
-
-The value of this macro is the size, in bytes, of the area reserved for
-arguments passed in registers for the function represented by @var{fndecl},
-which can be zero if GCC is calling a library function.
-The argument @var{fndecl} can be the FUNCTION_DECL, or the type itself
-of the function.
-
-This space can be allocated by the caller, or be a part of the
-machine-dependent stack frame: @code{OUTGOING_REG_PARM_STACK_SPACE} says
-which.
-@end defmac
-@c above is overfull. not sure what to do. --mew 5feb93 did
-@c something, not sure if it looks good. --mew 10feb93
-
-@defmac INCOMING_REG_PARM_STACK_SPACE (@var{fndecl})
-Like @code{REG_PARM_STACK_SPACE}, but for incoming register arguments.
-Define this macro if space guaranteed when compiling a function body
-is different to space required when making a call, a situation that
-can arise with K&R style function definitions.
-@end defmac
-
-@defmac OUTGOING_REG_PARM_STACK_SPACE (@var{fntype})
-Define this to a nonzero value if it is the responsibility of the
-caller to allocate the area reserved for arguments passed in registers
-when calling a function of @var{fntype}. @var{fntype} may be NULL
-if the function called is a library function.
-
-If @code{ACCUMULATE_OUTGOING_ARGS} is defined, this macro controls
-whether the space for these arguments counts in the value of
-@code{crtl->outgoing_args_size}.
-@end defmac
-
-@defmac STACK_PARMS_IN_REG_PARM_AREA
-Define this macro if @code{REG_PARM_STACK_SPACE} is defined, but the
-stack parameters don't skip the area specified by it.
-@c i changed this, makes more sens and it should have taken care of the
-@c overfull.. not as specific, tho. --mew 5feb93
-
-Normally, when a parameter is not passed in registers, it is placed on the
-stack beyond the @code{REG_PARM_STACK_SPACE} area. Defining this macro
-suppresses this behavior and causes the parameter to be passed on the
-stack in its natural location.
-@end defmac
-
-@deftypefn {Target Hook} poly_int64 TARGET_RETURN_POPS_ARGS (tree @var{fundecl}, tree @var{funtype}, poly_int64 @var{size})
-This target hook returns the number of bytes of its own arguments that
-a function pops on returning, or 0 if the function pops no arguments
-and the caller must therefore pop them all after the function returns.
-
-@var{fundecl} is a C variable whose value is a tree node that describes
-the function in question. Normally it is a node of type
-@code{FUNCTION_DECL} that describes the declaration of the function.
-From this you can obtain the @code{DECL_ATTRIBUTES} of the function.
-
-@var{funtype} is a C variable whose value is a tree node that
-describes the function in question. Normally it is a node of type
-@code{FUNCTION_TYPE} that describes the data type of the function.
-From this it is possible to obtain the data types of the value and
-arguments (if known).
-
-When a call to a library function is being considered, @var{fundecl}
-will contain an identifier node for the library function. Thus, if
-you need to distinguish among various library functions, you can do so
-by their names. Note that ``library function'' in this context means
-a function used to perform arithmetic, whose name is known specially
-in the compiler and was not mentioned in the C code being compiled.
-
-@var{size} is the number of bytes of arguments passed on the
-stack. If a variable number of bytes is passed, it is zero, and
-argument popping will always be the responsibility of the calling function.
-
-On the VAX, all functions always pop their arguments, so the definition
-of this macro is @var{size}. On the 68000, using the standard
-calling convention, no functions pop their arguments, so the value of
-the macro is always 0 in this case. But an alternative calling
-convention is available in which functions that take a fixed number of
-arguments pop them but other functions (such as @code{printf}) pop
-nothing (the caller pops all). When this convention is in use,
-@var{funtype} is examined to determine whether a function takes a fixed
-number of arguments.
-@end deftypefn
-
-@defmac CALL_POPS_ARGS (@var{cum})
-A C expression that should indicate the number of bytes a call sequence
-pops off the stack. It is added to the value of @code{RETURN_POPS_ARGS}
-when compiling a function call.
-
-@var{cum} is the variable in which all arguments to the called function
-have been accumulated.
-
-On certain architectures, such as the SH5, a call trampoline is used
-that pops certain registers off the stack, depending on the arguments
-that have been passed to the function. Since this is a property of the
-call site, not of the called function, @code{RETURN_POPS_ARGS} is not
-appropriate.
-@end defmac
-
-@node Register Arguments
-@subsection Passing Arguments in Registers
-@cindex arguments in registers
-@cindex registers arguments
-
-This section describes the macros which let you control how various
-types of arguments are passed in registers or how they are arranged in
-the stack.
-
-@deftypefn {Target Hook} rtx TARGET_FUNCTION_ARG (cumulative_args_t @var{ca}, const function_arg_info @var{&arg})
-Return an RTX indicating whether function argument @var{arg} is passed
-in a register and if so, which register. Argument @var{ca} summarizes all
-the previous arguments.
-
-The return value is usually either a @code{reg} RTX for the hard
-register in which to pass the argument, or zero to pass the argument
-on the stack.
-
-The value of the expression can also be a @code{parallel} RTX@. This is
-used when an argument is passed in multiple locations. The mode of the
-@code{parallel} should be the mode of the entire argument. The
-@code{parallel} holds any number of @code{expr_list} pairs; each one
-describes where part of the argument is passed. In each
-@code{expr_list} the first operand must be a @code{reg} RTX for the hard
-register in which to pass this part of the argument, and the mode of the
-register RTX indicates how large this part of the argument is. The
-second operand of the @code{expr_list} is a @code{const_int} which gives
-the offset in bytes into the entire argument of where this part starts.
-As a special exception the first @code{expr_list} in the @code{parallel}
-RTX may have a first operand of zero. This indicates that the entire
-argument is also stored on the stack.
-
-The last time this hook is called, it is called with @code{MODE ==
-VOIDmode}, and its result is passed to the @code{call} or @code{call_value}
-pattern as operands 2 and 3 respectively.
-
-@cindex @file{stdarg.h} and register arguments
-The usual way to make the ISO library @file{stdarg.h} work on a
-machine where some arguments are usually passed in registers, is to
-cause nameless arguments to be passed on the stack instead. This is
-done by making @code{TARGET_FUNCTION_ARG} return 0 whenever
-@var{named} is @code{false}.
-
-@cindex @code{TARGET_MUST_PASS_IN_STACK}, and @code{TARGET_FUNCTION_ARG}
-@cindex @code{REG_PARM_STACK_SPACE}, and @code{TARGET_FUNCTION_ARG}
-You may use the hook @code{targetm.calls.must_pass_in_stack}
-in the definition of this macro to determine if this argument is of a
-type that must be passed in the stack. If @code{REG_PARM_STACK_SPACE}
-is not defined and @code{TARGET_FUNCTION_ARG} returns nonzero for such an
-argument, the compiler will abort. If @code{REG_PARM_STACK_SPACE} is
-defined, the argument will be computed in the stack and then loaded into
-a register.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_MUST_PASS_IN_STACK (const function_arg_info @var{&arg})
-This target hook should return @code{true} if we should not pass @var{arg}
-solely in registers. The file @file{expr.h} defines a
-definition that is usually appropriate, refer to @file{expr.h} for additional
-documentation.
-@end deftypefn
-
-@deftypefn {Target Hook} rtx TARGET_FUNCTION_INCOMING_ARG (cumulative_args_t @var{ca}, const function_arg_info @var{&arg})
-Define this hook if the caller and callee on the target have different
-views of where arguments are passed. Also define this hook if there are
-functions that are never directly called, but are invoked by the hardware
-and which have nonstandard calling conventions.
-
-In this case @code{TARGET_FUNCTION_ARG} computes the register in
-which the caller passes the value, and
-@code{TARGET_FUNCTION_INCOMING_ARG} should be defined in a similar
-fashion to tell the function being called where the arguments will
-arrive.
-
-@code{TARGET_FUNCTION_INCOMING_ARG} can also return arbitrary address
-computation using hard register, which can be forced into a register,
-so that it can be used to pass special arguments.
-
-If @code{TARGET_FUNCTION_INCOMING_ARG} is not defined,
-@code{TARGET_FUNCTION_ARG} serves both purposes.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_USE_PSEUDO_PIC_REG (void)
-This hook should return 1 in case pseudo register should be created
-for pic_offset_table_rtx during function expand.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_INIT_PIC_REG (void)
-Perform a target dependent initialization of pic_offset_table_rtx.
-This hook is called at the start of register allocation.
-@end deftypefn
-
-@deftypefn {Target Hook} int TARGET_ARG_PARTIAL_BYTES (cumulative_args_t @var{cum}, const function_arg_info @var{&arg})
-This target hook returns the number of bytes at the beginning of an
-argument that must be put in registers. The value must be zero for
-arguments that are passed entirely in registers or that are entirely
-pushed on the stack.
-
-On some machines, certain arguments must be passed partially in
-registers and partially in memory. On these machines, typically the
-first few words of arguments are passed in registers, and the rest
-on the stack. If a multi-word argument (a @code{double} or a
-structure) crosses that boundary, its first few words must be passed
-in registers and the rest must be pushed. This macro tells the
-compiler when this occurs, and how many bytes should go in registers.
-
-@code{TARGET_FUNCTION_ARG} for these arguments should return the first
-register to be used by the caller for this argument; likewise
-@code{TARGET_FUNCTION_INCOMING_ARG}, for the called function.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_PASS_BY_REFERENCE (cumulative_args_t @var{cum}, const function_arg_info @var{&arg})
-This target hook should return @code{true} if argument @var{arg} at the
-position indicated by @var{cum} should be passed by reference. This
-predicate is queried after target independent reasons for being
-passed by reference, such as @code{TREE_ADDRESSABLE (@var{arg}.type)}.
-
-If the hook returns true, a copy of that argument is made in memory and a
-pointer to the argument is passed instead of the argument itself.
-The pointer is passed in whatever way is appropriate for passing a pointer
-to that type.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_CALLEE_COPIES (cumulative_args_t @var{cum}, const function_arg_info @var{&arg})
-The function argument described by the parameters to this hook is
-known to be passed by reference. The hook should return true if the
-function argument should be copied by the callee instead of copied
-by the caller.
-
-For any argument for which the hook returns true, if it can be
-determined that the argument is not modified, then a copy need
-not be generated.
-
-The default version of this hook always returns false.
-@end deftypefn
-
-@defmac CUMULATIVE_ARGS
-A C type for declaring a variable that is used as the first argument
-of @code{TARGET_FUNCTION_ARG} and other related values. For some
-target machines, the type @code{int} suffices and can hold the number
-of bytes of argument so far.
-
-There is no need to record in @code{CUMULATIVE_ARGS} anything about the
-arguments that have been passed on the stack. The compiler has other
-variables to keep track of that. For target machines on which all
-arguments are passed on the stack, there is no need to store anything in
-@code{CUMULATIVE_ARGS}; however, the data structure must exist and
-should not be empty, so use @code{int}.
-@end defmac
-
-@defmac OVERRIDE_ABI_FORMAT (@var{fndecl})
-If defined, this macro is called before generating any code for a
-function, but after the @var{cfun} descriptor for the function has been
-created. The back end may use this macro to update @var{cfun} to
-reflect an ABI other than that which would normally be used by default.
-If the compiler is generating code for a compiler-generated function,
-@var{fndecl} may be @code{NULL}.
-@end defmac
-
-@defmac INIT_CUMULATIVE_ARGS (@var{cum}, @var{fntype}, @var{libname}, @var{fndecl}, @var{n_named_args})
-A C statement (sans semicolon) for initializing the variable
-@var{cum} for the state at the beginning of the argument list. The
-variable has type @code{CUMULATIVE_ARGS}. The value of @var{fntype}
-is the tree node for the data type of the function which will receive
-the args, or 0 if the args are to a compiler support library function.
-For direct calls that are not libcalls, @var{fndecl} contain the
-declaration node of the function. @var{fndecl} is also set when
-@code{INIT_CUMULATIVE_ARGS} is used to find arguments for the function
-being compiled. @var{n_named_args} is set to the number of named
-arguments, including a structure return address if it is passed as a
-parameter, when making a call. When processing incoming arguments,
-@var{n_named_args} is set to @minus{}1.
-
-When processing a call to a compiler support library function,
-@var{libname} identifies which one. It is a @code{symbol_ref} rtx which
-contains the name of the function, as a string. @var{libname} is 0 when
-an ordinary C function call is being processed. Thus, each time this
-macro is called, either @var{libname} or @var{fntype} is nonzero, but
-never both of them at once.
-@end defmac
-
-@defmac INIT_CUMULATIVE_LIBCALL_ARGS (@var{cum}, @var{mode}, @var{libname})
-Like @code{INIT_CUMULATIVE_ARGS} but only used for outgoing libcalls,
-it gets a @code{MODE} argument instead of @var{fntype}, that would be
-@code{NULL}. @var{indirect} would always be zero, too. If this macro
-is not defined, @code{INIT_CUMULATIVE_ARGS (cum, NULL_RTX, libname,
-0)} is used instead.
-@end defmac
-
-@defmac INIT_CUMULATIVE_INCOMING_ARGS (@var{cum}, @var{fntype}, @var{libname})
-Like @code{INIT_CUMULATIVE_ARGS} but overrides it for the purposes of
-finding the arguments for the function being compiled. If this macro is
-undefined, @code{INIT_CUMULATIVE_ARGS} is used instead.
-
-The value passed for @var{libname} is always 0, since library routines
-with special calling conventions are never compiled with GCC@. The
-argument @var{libname} exists for symmetry with
-@code{INIT_CUMULATIVE_ARGS}.
-@c could use "this macro" in place of @code{INIT_CUMULATIVE_ARGS}, maybe.
-@c --mew 5feb93 i switched the order of the sentences. --mew 10feb93
-@end defmac
-
-@deftypefn {Target Hook} void TARGET_FUNCTION_ARG_ADVANCE (cumulative_args_t @var{ca}, const function_arg_info @var{&arg})
-This hook updates the summarizer variable pointed to by @var{ca} to
-advance past argument @var{arg} in the argument list. Once this is done,
-the variable @var{cum} is suitable for analyzing the @emph{following}
-argument with @code{TARGET_FUNCTION_ARG}, etc.
-
-This hook need not do anything if the argument in question was passed
-on the stack. The compiler knows how to track the amount of stack space
-used for arguments without any special help.
-@end deftypefn
-
-@deftypefn {Target Hook} HOST_WIDE_INT TARGET_FUNCTION_ARG_OFFSET (machine_mode @var{mode}, const_tree @var{type})
-This hook returns the number of bytes to add to the offset of an
-argument of type @var{type} and mode @var{mode} when passed in memory.
-This is needed for the SPU, which passes @code{char} and @code{short}
-arguments in the preferred slot that is in the middle of the quad word
-instead of starting at the top. The default implementation returns 0.
-@end deftypefn
-
-@deftypefn {Target Hook} pad_direction TARGET_FUNCTION_ARG_PADDING (machine_mode @var{mode}, const_tree @var{type})
-This hook determines whether, and in which direction, to pad out
-an argument of mode @var{mode} and type @var{type}. It returns
-@code{PAD_UPWARD} to insert padding above the argument, @code{PAD_DOWNWARD}
-to insert padding below the argument, or @code{PAD_NONE} to inhibit padding.
-
-The @emph{amount} of padding is not controlled by this hook, but by
-@code{TARGET_FUNCTION_ARG_ROUND_BOUNDARY}. It is always just enough
-to reach the next multiple of that boundary.
-
-This hook has a default definition that is right for most systems.
-For little-endian machines, the default is to pad upward. For
-big-endian machines, the default is to pad downward for an argument of
-constant size shorter than an @code{int}, and upward otherwise.
-@end deftypefn
-
-@defmac PAD_VARARGS_DOWN
-If defined, a C expression which determines whether the default
-implementation of va_arg will attempt to pad down before reading the
-next argument, if that argument is smaller than its aligned space as
-controlled by @code{PARM_BOUNDARY}. If this macro is not defined, all such
-arguments are padded down if @code{BYTES_BIG_ENDIAN} is true.
-@end defmac
-
-@defmac BLOCK_REG_PADDING (@var{mode}, @var{type}, @var{first})
-Specify padding for the last element of a block move between registers and
-memory. @var{first} is nonzero if this is the only element. Defining this
-macro allows better control of register function parameters on big-endian
-machines, without using @code{PARALLEL} rtl. In particular,
-@code{MUST_PASS_IN_STACK} need not test padding and mode of types in
-registers, as there is no longer a "wrong" part of a register; For example,
-a three byte aggregate may be passed in the high part of a register if so
-required.
-@end defmac
-
-@deftypefn {Target Hook} {unsigned int} TARGET_FUNCTION_ARG_BOUNDARY (machine_mode @var{mode}, const_tree @var{type})
-This hook returns the alignment boundary, in bits, of an argument
-with the specified mode and type. The default hook returns
-@code{PARM_BOUNDARY} for all arguments.
-@end deftypefn
-
-@deftypefn {Target Hook} {unsigned int} TARGET_FUNCTION_ARG_ROUND_BOUNDARY (machine_mode @var{mode}, const_tree @var{type})
-Normally, the size of an argument is rounded up to @code{PARM_BOUNDARY},
-which is the default value for this hook. You can define this hook to
-return a different value if an argument size must be rounded to a larger
-value.
-@end deftypefn
-
-@defmac FUNCTION_ARG_REGNO_P (@var{regno})
-A C expression that is nonzero if @var{regno} is the number of a hard
-register in which function arguments are sometimes passed. This does
-@emph{not} include implicit arguments such as the static chain and
-the structure-value address. On many machines, no registers can be
-used for this purpose since all function arguments are pushed on the
-stack.
-@end defmac
-
-@deftypefn {Target Hook} bool TARGET_SPLIT_COMPLEX_ARG (const_tree @var{type})
-This hook should return true if parameter of type @var{type} are passed
-as two scalar parameters. By default, GCC will attempt to pack complex
-arguments into the target's word size. Some ABIs require complex arguments
-to be split and treated as their individual components. For example, on
-AIX64, complex floats should be passed in a pair of floating point
-registers, even though a complex float would fit in one 64-bit floating
-point register.
-
-The default value of this hook is @code{NULL}, which is treated as always
-false.
-@end deftypefn
-
-@deftypefn {Target Hook} tree TARGET_BUILD_BUILTIN_VA_LIST (void)
-This hook returns a type node for @code{va_list} for the target.
-The default version of the hook returns @code{void*}.
-@end deftypefn
-
-@deftypefn {Target Hook} int TARGET_ENUM_VA_LIST_P (int @var{idx}, const char **@var{pname}, tree *@var{ptree})
-This target hook is used in function @code{c_common_nodes_and_builtins}
-to iterate through the target specific builtin types for va_list. The
-variable @var{idx} is used as iterator. @var{pname} has to be a pointer
-to a @code{const char *} and @var{ptree} a pointer to a @code{tree} typed
-variable.
-The arguments @var{pname} and @var{ptree} are used to store the result of
-this macro and are set to the name of the va_list builtin type and its
-internal type.
-If the return value of this macro is zero, then there is no more element.
-Otherwise the @var{IDX} should be increased for the next call of this
-macro to iterate through all types.
-@end deftypefn
-
-@deftypefn {Target Hook} tree TARGET_FN_ABI_VA_LIST (tree @var{fndecl})
-This hook returns the va_list type of the calling convention specified by
-@var{fndecl}.
-The default version of this hook returns @code{va_list_type_node}.
-@end deftypefn
-
-@deftypefn {Target Hook} tree TARGET_CANONICAL_VA_LIST_TYPE (tree @var{type})
-This hook returns the va_list type of the calling convention specified by the
-type of @var{type}. If @var{type} is not a valid va_list type, it returns
-@code{NULL_TREE}.
-@end deftypefn
-
-@deftypefn {Target Hook} tree TARGET_GIMPLIFY_VA_ARG_EXPR (tree @var{valist}, tree @var{type}, gimple_seq *@var{pre_p}, gimple_seq *@var{post_p})
-This hook performs target-specific gimplification of
-@code{VA_ARG_EXPR}. The first two parameters correspond to the
-arguments to @code{va_arg}; the latter two are as in
-@code{gimplify.cc:gimplify_expr}.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_VALID_POINTER_MODE (scalar_int_mode @var{mode})
-Define this to return nonzero if the port can handle pointers
-with machine mode @var{mode}. The default version of this
-hook returns true for both @code{ptr_mode} and @code{Pmode}.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_REF_MAY_ALIAS_ERRNO (ao_ref *@var{ref})
-Define this to return nonzero if the memory reference @var{ref}
-may alias with the system C library errno location. The default
-version of this hook assumes the system C library errno location
-is either a declaration of type int or accessed by dereferencing
-a pointer to int.
-@end deftypefn
-
-@deftypefn {Target Hook} machine_mode TARGET_TRANSLATE_MODE_ATTRIBUTE (machine_mode @var{mode})
-Define this hook if during mode attribute processing, the port should
-translate machine_mode @var{mode} to another mode. For example, rs6000's
-@code{KFmode}, when it is the same as @code{TFmode}.
-
-The default version of the hook returns that mode that was passed in.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_SCALAR_MODE_SUPPORTED_P (scalar_mode @var{mode})
-Define this to return nonzero if the port is prepared to handle
-insns involving scalar mode @var{mode}. For a scalar mode to be
-considered supported, all the basic arithmetic and comparisons
-must work.
-
-The default version of this hook returns true for any mode
-required to handle the basic C types (as defined by the port).
-Included here are the double-word arithmetic supported by the
-code in @file{optabs.cc}.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_VECTOR_MODE_SUPPORTED_P (machine_mode @var{mode})
-Define this to return nonzero if the port is prepared to handle
-insns involving vector mode @var{mode}. At the very least, it
-must have move patterns for this mode.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_COMPATIBLE_VECTOR_TYPES_P (const_tree @var{type1}, const_tree @var{type2})
-Return true if there is no target-specific reason for treating
-vector types @var{type1} and @var{type2} as distinct types. The caller
-has already checked for target-independent reasons, meaning that the
-types are known to have the same mode, to have the same number of elements,
-and to have what the caller considers to be compatible element types.
-
-The main reason for defining this hook is to reject pairs of types
-that are handled differently by the target's calling convention.
-For example, when a new @var{N}-bit vector architecture is added
-to a target, the target may want to handle normal @var{N}-bit
-@code{VECTOR_TYPE} arguments and return values in the same way as
-before, to maintain backwards compatibility. However, it may also
-provide new, architecture-specific @code{VECTOR_TYPE}s that are passed
-and returned in a more efficient way. It is then important to maintain
-a distinction between the ``normal'' @code{VECTOR_TYPE}s and the new
-architecture-specific ones.
-
-The default implementation returns true, which is correct for most targets.
-@end deftypefn
-
-@deftypefn {Target Hook} opt_machine_mode TARGET_ARRAY_MODE (machine_mode @var{mode}, unsigned HOST_WIDE_INT @var{nelems})
-Return the mode that GCC should use for an array that has
-@var{nelems} elements, with each element having mode @var{mode}.
-Return no mode if the target has no special requirements. In the
-latter case, GCC looks for an integer mode of the appropriate size
-if available and uses BLKmode otherwise. Usually the search for the
-integer mode is limited to @code{MAX_FIXED_MODE_SIZE}, but the
-@code{TARGET_ARRAY_MODE_SUPPORTED_P} hook allows a larger mode to be
-used in specific cases.
-
-The main use of this hook is to specify that an array of vectors should
-also have a vector mode. The default implementation returns no mode.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_ARRAY_MODE_SUPPORTED_P (machine_mode @var{mode}, unsigned HOST_WIDE_INT @var{nelems})
-Return true if GCC should try to use a scalar mode to store an array
-of @var{nelems} elements, given that each element has mode @var{mode}.
-Returning true here overrides the usual @code{MAX_FIXED_MODE} limit
-and allows GCC to use any defined integer mode.
-
-One use of this hook is to support vector load and store operations
-that operate on several homogeneous vectors. For example, ARM NEON
-has operations like:
-
-@smallexample
-int8x8x3_t vld3_s8 (const int8_t *)
-@end smallexample
-
-where the return type is defined as:
-
-@smallexample
-typedef struct int8x8x3_t
-@{
- int8x8_t val[3];
-@} int8x8x3_t;
-@end smallexample
-
-If this hook allows @code{val} to have a scalar mode, then
-@code{int8x8x3_t} can have the same mode. GCC can then store
-@code{int8x8x3_t}s in registers rather than forcing them onto the stack.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_LIBGCC_FLOATING_MODE_SUPPORTED_P (scalar_float_mode @var{mode})
-Define this to return nonzero if libgcc provides support for the
-floating-point mode @var{mode}, which is known to pass
-@code{TARGET_SCALAR_MODE_SUPPORTED_P}. The default version of this
-hook returns true for all of @code{SFmode}, @code{DFmode},
-@code{XFmode} and @code{TFmode}, if such modes exist.
-@end deftypefn
-
-@deftypefn {Target Hook} opt_scalar_float_mode TARGET_FLOATN_MODE (int @var{n}, bool @var{extended})
-Define this to return the machine mode to use for the type
-@code{_Float@var{n}}, if @var{extended} is false, or the type
-@code{_Float@var{n}x}, if @var{extended} is true. If such a type is not
-supported, return @code{opt_scalar_float_mode ()}. The default version of
-this hook returns @code{SFmode} for @code{_Float32}, @code{DFmode} for
-@code{_Float64} and @code{_Float32x} and @code{TFmode} for
-@code{_Float128}, if those modes exist and satisfy the requirements for
-those types and pass @code{TARGET_SCALAR_MODE_SUPPORTED_P} and
-@code{TARGET_LIBGCC_FLOATING_MODE_SUPPORTED_P}; for @code{_Float64x}, it
-returns the first of @code{XFmode} and @code{TFmode} that exists and
-satisfies the same requirements; for other types, it returns
-@code{opt_scalar_float_mode ()}. The hook is only called for values
-of @var{n} and @var{extended} that are valid according to
-ISO/IEC TS 18661-3:2015; that is, @var{n} is one of 32, 64, 128, or,
-if @var{extended} is false, 16 or greater than 128 and a multiple of 32.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_FLOATN_BUILTIN_P (int @var{func})
-Define this to return true if the @code{_Float@var{n}} and
-@code{_Float@var{n}x} built-in functions should implicitly enable the
-built-in function without the @code{__builtin_} prefix in addition to the
-normal built-in function with the @code{__builtin_} prefix. The default is
-to only enable built-in functions without the @code{__builtin_} prefix for
-the GNU C langauge. In strict ANSI/ISO mode, the built-in function without
-the @code{__builtin_} prefix is not enabled. The argument @code{FUNC} is the
-@code{enum built_in_function} id of the function to be enabled.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_SMALL_REGISTER_CLASSES_FOR_MODE_P (machine_mode @var{mode})
-Define this to return nonzero for machine modes for which the port has
-small register classes. If this target hook returns nonzero for a given
-@var{mode}, the compiler will try to minimize the lifetime of registers
-in @var{mode}. The hook may be called with @code{VOIDmode} as argument.
-In this case, the hook is expected to return nonzero if it returns nonzero
-for any mode.
-
-On some machines, it is risky to let hard registers live across arbitrary
-insns. Typically, these machines have instructions that require values
-to be in specific registers (like an accumulator), and reload will fail
-if the required hard register is used for another purpose across such an
-insn.
-
-Passes before reload do not know which hard registers will be used
-in an instruction, but the machine modes of the registers set or used in
-the instruction are already known. And for some machines, register
-classes are small for, say, integer registers but not for floating point
-registers. For example, the AMD x86-64 architecture requires specific
-registers for the legacy x86 integer instructions, but there are many
-SSE registers for floating point operations. On such targets, a good
-strategy may be to return nonzero from this hook for @code{INTEGRAL_MODE_P}
-machine modes but zero for the SSE register classes.
-
-The default version of this hook returns false for any mode. It is always
-safe to redefine this hook to return with a nonzero value. But if you
-unnecessarily define it, you will reduce the amount of optimizations
-that can be performed in some cases. If you do not define this hook
-to return a nonzero value when it is required, the compiler will run out
-of spill registers and print a fatal error message.
-@end deftypefn
-
-@node Scalar Return
-@subsection How Scalar Function Values Are Returned
-@cindex return values in registers
-@cindex values, returned by functions
-@cindex scalars, returned as values
-
-This section discusses the macros that control returning scalars as
-values---values that can fit in registers.
-
-@deftypefn {Target Hook} rtx TARGET_FUNCTION_VALUE (const_tree @var{ret_type}, const_tree @var{fn_decl_or_type}, bool @var{outgoing})
-
-Define this to return an RTX representing the place where a function
-returns or receives a value of data type @var{ret_type}, a tree node
-representing a data type. @var{fn_decl_or_type} is a tree node
-representing @code{FUNCTION_DECL} or @code{FUNCTION_TYPE} of a
-function being called. If @var{outgoing} is false, the hook should
-compute the register in which the caller will see the return value.
-Otherwise, the hook should return an RTX representing the place where
-a function returns a value.
-
-On many machines, only @code{TYPE_MODE (@var{ret_type})} is relevant.
-(Actually, on most machines, scalar values are returned in the same
-place regardless of mode.) The value of the expression is usually a
-@code{reg} RTX for the hard register where the return value is stored.
-The value can also be a @code{parallel} RTX, if the return value is in
-multiple places. See @code{TARGET_FUNCTION_ARG} for an explanation of the
-@code{parallel} form. Note that the callee will populate every
-location specified in the @code{parallel}, but if the first element of
-the @code{parallel} contains the whole return value, callers will use
-that element as the canonical location and ignore the others. The m68k
-port uses this type of @code{parallel} to return pointers in both
-@samp{%a0} (the canonical location) and @samp{%d0}.
-
-If @code{TARGET_PROMOTE_FUNCTION_RETURN} returns true, you must apply
-the same promotion rules specified in @code{PROMOTE_MODE} if
-@var{valtype} is a scalar type.
-
-If the precise function being called is known, @var{func} is a tree
-node (@code{FUNCTION_DECL}) for it; otherwise, @var{func} is a null
-pointer. This makes it possible to use a different value-returning
-convention for specific functions when all their calls are
-known.
-
-Some target machines have ``register windows'' so that the register in
-which a function returns its value is not the same as the one in which
-the caller sees the value. For such machines, you should return
-different RTX depending on @var{outgoing}.
-
-@code{TARGET_FUNCTION_VALUE} is not used for return values with
-aggregate data types, because these are returned in another way. See
-@code{TARGET_STRUCT_VALUE_RTX} and related macros, below.
-@end deftypefn
-
-@defmac FUNCTION_VALUE (@var{valtype}, @var{func})
-This macro has been deprecated. Use @code{TARGET_FUNCTION_VALUE} for
-a new target instead.
-@end defmac
-
-@defmac LIBCALL_VALUE (@var{mode})
-A C expression to create an RTX representing the place where a library
-function returns a value of mode @var{mode}.
-
-Note that ``library function'' in this context means a compiler
-support routine, used to perform arithmetic, whose name is known
-specially by the compiler and was not mentioned in the C code being
-compiled.
-@end defmac
-
-@deftypefn {Target Hook} rtx TARGET_LIBCALL_VALUE (machine_mode @var{mode}, const_rtx @var{fun})
-Define this hook if the back-end needs to know the name of the libcall
-function in order to determine where the result should be returned.
-
-The mode of the result is given by @var{mode} and the name of the called
-library function is given by @var{fun}. The hook should return an RTX
-representing the place where the library function result will be returned.
-
-If this hook is not defined, then LIBCALL_VALUE will be used.
-@end deftypefn
-
-@defmac FUNCTION_VALUE_REGNO_P (@var{regno})
-A C expression that is nonzero if @var{regno} is the number of a hard
-register in which the values of called function may come back.
-
-A register whose use for returning values is limited to serving as the
-second of a pair (for a value of type @code{double}, say) need not be
-recognized by this macro. So for most machines, this definition
-suffices:
-
-@smallexample
-#define FUNCTION_VALUE_REGNO_P(N) ((N) == 0)
-@end smallexample
-
-If the machine has register windows, so that the caller and the called
-function use different registers for the return value, this macro
-should recognize only the caller's register numbers.
-
-This macro has been deprecated. Use @code{TARGET_FUNCTION_VALUE_REGNO_P}
-for a new target instead.
-@end defmac
-
-@deftypefn {Target Hook} bool TARGET_FUNCTION_VALUE_REGNO_P (const unsigned int @var{regno})
-A target hook that return @code{true} if @var{regno} is the number of a hard
-register in which the values of called function may come back.
-
-A register whose use for returning values is limited to serving as the
-second of a pair (for a value of type @code{double}, say) need not be
-recognized by this target hook.
-
-If the machine has register windows, so that the caller and the called
-function use different registers for the return value, this target hook
-should recognize only the caller's register numbers.
-
-If this hook is not defined, then FUNCTION_VALUE_REGNO_P will be used.
-@end deftypefn
-
-@defmac APPLY_RESULT_SIZE
-Define this macro if @samp{untyped_call} and @samp{untyped_return}
-need more space than is implied by @code{FUNCTION_VALUE_REGNO_P} for
-saving and restoring an arbitrary return value.
-@end defmac
-
-@deftypevr {Target Hook} bool TARGET_OMIT_STRUCT_RETURN_REG
-Normally, when a function returns a structure by memory, the address
-is passed as an invisible pointer argument, but the compiler also
-arranges to return the address from the function like it would a normal
-pointer return value. Define this to true if that behavior is
-undesirable on your target.
-@end deftypevr
-
-@deftypefn {Target Hook} bool TARGET_RETURN_IN_MSB (const_tree @var{type})
-This hook should return true if values of type @var{type} are returned
-at the most significant end of a register (in other words, if they are
-padded at the least significant end). You can assume that @var{type}
-is returned in a register; the caller is required to check this.
-
-Note that the register provided by @code{TARGET_FUNCTION_VALUE} must
-be able to hold the complete return value. For example, if a 1-, 2-
-or 3-byte structure is returned at the most significant end of a
-4-byte register, @code{TARGET_FUNCTION_VALUE} should provide an
-@code{SImode} rtx.
-@end deftypefn
-
-@node Aggregate Return
-@subsection How Large Values Are Returned
-@cindex aggregates as return values
-@cindex large return values
-@cindex returning aggregate values
-@cindex structure value address
-
-When a function value's mode is @code{BLKmode} (and in some other
-cases), the value is not returned according to
-@code{TARGET_FUNCTION_VALUE} (@pxref{Scalar Return}). Instead, the
-caller passes the address of a block of memory in which the value
-should be stored. This address is called the @dfn{structure value
-address}.
-
-This section describes how to control returning structure values in
-memory.
-
-@deftypefn {Target Hook} bool TARGET_RETURN_IN_MEMORY (const_tree @var{type}, const_tree @var{fntype})
-This target hook should return a nonzero value to say to return the
-function value in memory, just as large structures are always returned.
-Here @var{type} will be the data type of the value, and @var{fntype}
-will be the type of the function doing the returning, or @code{NULL} for
-libcalls.
-
-Note that values of mode @code{BLKmode} must be explicitly handled
-by this function. Also, the option @option{-fpcc-struct-return}
-takes effect regardless of this macro. On most systems, it is
-possible to leave the hook undefined; this causes a default
-definition to be used, whose value is the constant 1 for @code{BLKmode}
-values, and 0 otherwise.
-
-Do not use this hook to indicate that structures and unions should always
-be returned in memory. You should instead use @code{DEFAULT_PCC_STRUCT_RETURN}
-to indicate this.
-@end deftypefn
-
-@defmac DEFAULT_PCC_STRUCT_RETURN
-Define this macro to be 1 if all structure and union return values must be
-in memory. Since this results in slower code, this should be defined
-only if needed for compatibility with other compilers or with an ABI@.
-If you define this macro to be 0, then the conventions used for structure
-and union return values are decided by the @code{TARGET_RETURN_IN_MEMORY}
-target hook.
-
-If not defined, this defaults to the value 1.
-@end defmac
-
-@deftypefn {Target Hook} rtx TARGET_STRUCT_VALUE_RTX (tree @var{fndecl}, int @var{incoming})
-This target hook should return the location of the structure value
-address (normally a @code{mem} or @code{reg}), or 0 if the address is
-passed as an ``invisible'' first argument. Note that @var{fndecl} may
-be @code{NULL}, for libcalls. You do not need to define this target
-hook if the address is always passed as an ``invisible'' first
-argument.
-
-On some architectures the place where the structure value address
-is found by the called function is not the same place that the
-caller put it. This can be due to register windows, or it could
-be because the function prologue moves it to a different place.
-@var{incoming} is @code{1} or @code{2} when the location is needed in
-the context of the called function, and @code{0} in the context of
-the caller.
-
-If @var{incoming} is nonzero and the address is to be found on the
-stack, return a @code{mem} which refers to the frame pointer. If
-@var{incoming} is @code{2}, the result is being used to fetch the
-structure value address at the beginning of a function. If you need
-to emit adjusting code, you should do it at this point.
-@end deftypefn
-
-@defmac PCC_STATIC_STRUCT_RETURN
-Define this macro if the usual system convention on the target machine
-for returning structures and unions is for the called function to return
-the address of a static variable containing the value.
-
-Do not define this if the usual system convention is for the caller to
-pass an address to the subroutine.
-
-This macro has effect in @option{-fpcc-struct-return} mode, but it does
-nothing when you use @option{-freg-struct-return} mode.
-@end defmac
-
-@deftypefn {Target Hook} fixed_size_mode TARGET_GET_RAW_RESULT_MODE (int @var{regno})
-This target hook returns the mode to be used when accessing raw return
-registers in @code{__builtin_return}. Define this macro if the value
-in @var{reg_raw_mode} is not correct.
-@end deftypefn
-
-@deftypefn {Target Hook} fixed_size_mode TARGET_GET_RAW_ARG_MODE (int @var{regno})
-This target hook returns the mode to be used when accessing raw argument
-registers in @code{__builtin_apply_args}. Define this macro if the value
-in @var{reg_raw_mode} is not correct.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_EMPTY_RECORD_P (const_tree @var{type})
-This target hook returns true if the type is an empty record. The default
-is to return @code{false}.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_WARN_PARAMETER_PASSING_ABI (cumulative_args_t @var{ca}, tree @var{type})
-This target hook warns about the change in empty class parameter passing
-ABI.
-@end deftypefn
-
-@node Caller Saves
-@subsection Caller-Saves Register Allocation
-
-If you enable it, GCC can save registers around function calls. This
-makes it possible to use call-clobbered registers to hold variables that
-must live across calls.
-
-@defmac HARD_REGNO_CALLER_SAVE_MODE (@var{regno}, @var{nregs})
-A C expression specifying which mode is required for saving @var{nregs}
-of a pseudo-register in call-clobbered hard register @var{regno}. If
-@var{regno} is unsuitable for caller save, @code{VOIDmode} should be
-returned. For most machines this macro need not be defined since GCC
-will select the smallest suitable mode.
-@end defmac
-
-@node Function Entry
-@subsection Function Entry and Exit
-@cindex function entry and exit
-@cindex prologue
-@cindex epilogue
-
-This section describes the macros that output function entry
-(@dfn{prologue}) and exit (@dfn{epilogue}) code.
-
-@deftypefn {Target Hook} void TARGET_ASM_PRINT_PATCHABLE_FUNCTION_ENTRY (FILE *@var{file}, unsigned HOST_WIDE_INT @var{patch_area_size}, bool @var{record_p})
-Generate a patchable area at the function start, consisting of
-@var{patch_area_size} NOP instructions. If the target supports named
-sections and if @var{record_p} is true, insert a pointer to the current
-location in the table of patchable functions. The default implementation
-of the hook places the table of pointers in the special section named
-@code{__patchable_function_entries}.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_ASM_FUNCTION_PROLOGUE (FILE *@var{file})
-If defined, a function that outputs the assembler code for entry to a
-function. The prologue is responsible for setting up the stack frame,
-initializing the frame pointer register, saving registers that must be
-saved, and allocating @var{size} additional bytes of storage for the
-local variables. @var{file} is a stdio stream to which the assembler
-code should be output.
-
-The label for the beginning of the function need not be output by this
-macro. That has already been done when the macro is run.
-
-@findex regs_ever_live
-To determine which registers to save, the macro can refer to the array
-@code{regs_ever_live}: element @var{r} is nonzero if hard register
-@var{r} is used anywhere within the function. This implies the function
-prologue should save register @var{r}, provided it is not one of the
-call-used registers. (@code{TARGET_ASM_FUNCTION_EPILOGUE} must likewise use
-@code{regs_ever_live}.)
-
-On machines that have ``register windows'', the function entry code does
-not save on the stack the registers that are in the windows, even if
-they are supposed to be preserved by function calls; instead it takes
-appropriate steps to ``push'' the register stack, if any non-call-used
-registers are used in the function.
-
-@findex frame_pointer_needed
-On machines where functions may or may not have frame-pointers, the
-function entry code must vary accordingly; it must set up the frame
-pointer if one is wanted, and not otherwise. To determine whether a
-frame pointer is in wanted, the macro can refer to the variable
-@code{frame_pointer_needed}. The variable's value will be 1 at run
-time in a function that needs a frame pointer. @xref{Elimination}.
-
-The function entry code is responsible for allocating any stack space
-required for the function. This stack space consists of the regions
-listed below. In most cases, these regions are allocated in the
-order listed, with the last listed region closest to the top of the
-stack (the lowest address if @code{STACK_GROWS_DOWNWARD} is defined, and
-the highest address if it is not defined). You can use a different order
-for a machine if doing so is more convenient or required for
-compatibility reasons. Except in cases where required by standard
-or by a debugger, there is no reason why the stack layout used by GCC
-need agree with that used by other compilers for a machine.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_ASM_FUNCTION_END_PROLOGUE (FILE *@var{file})
-If defined, a function that outputs assembler code at the end of a
-prologue. This should be used when the function prologue is being
-emitted as RTL, and you have some extra assembler that needs to be
-emitted. @xref{prologue instruction pattern}.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_ASM_FUNCTION_BEGIN_EPILOGUE (FILE *@var{file})
-If defined, a function that outputs assembler code at the start of an
-epilogue. This should be used when the function epilogue is being
-emitted as RTL, and you have some extra assembler that needs to be
-emitted. @xref{epilogue instruction pattern}.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_ASM_FUNCTION_EPILOGUE (FILE *@var{file})
-If defined, a function that outputs the assembler code for exit from a
-function. The epilogue is responsible for restoring the saved
-registers and stack pointer to their values when the function was
-called, and returning control to the caller. This macro takes the
-same argument as the macro @code{TARGET_ASM_FUNCTION_PROLOGUE}, and the
-registers to restore are determined from @code{regs_ever_live} and
-@code{CALL_USED_REGISTERS} in the same way.
-
-On some machines, there is a single instruction that does all the work
-of returning from the function. On these machines, give that
-instruction the name @samp{return} and do not define the macro
-@code{TARGET_ASM_FUNCTION_EPILOGUE} at all.
-
-Do not define a pattern named @samp{return} if you want the
-@code{TARGET_ASM_FUNCTION_EPILOGUE} to be used. If you want the target
-switches to control whether return instructions or epilogues are used,
-define a @samp{return} pattern with a validity condition that tests the
-target switches appropriately. If the @samp{return} pattern's validity
-condition is false, epilogues will be used.
-
-On machines where functions may or may not have frame-pointers, the
-function exit code must vary accordingly. Sometimes the code for these
-two cases is completely different. To determine whether a frame pointer
-is wanted, the macro can refer to the variable
-@code{frame_pointer_needed}. The variable's value will be 1 when compiling
-a function that needs a frame pointer.
-
-Normally, @code{TARGET_ASM_FUNCTION_PROLOGUE} and
-@code{TARGET_ASM_FUNCTION_EPILOGUE} must treat leaf functions specially.
-The C variable @code{current_function_is_leaf} is nonzero for such a
-function. @xref{Leaf Functions}.
-
-On some machines, some functions pop their arguments on exit while
-others leave that for the caller to do. For example, the 68020 when
-given @option{-mrtd} pops arguments in functions that take a fixed
-number of arguments.
-
-@findex pops_args
-@findex crtl->args.pops_args
-Your definition of the macro @code{RETURN_POPS_ARGS} decides which
-functions pop their own arguments. @code{TARGET_ASM_FUNCTION_EPILOGUE}
-needs to know what was decided. The number of bytes of the current
-function's arguments that this function should pop is available in
-@code{crtl->args.pops_args}. @xref{Scalar Return}.
-@end deftypefn
-
-@itemize @bullet
-@item
-@findex pretend_args_size
-@findex crtl->args.pretend_args_size
-A region of @code{crtl->args.pretend_args_size} bytes of
-uninitialized space just underneath the first argument arriving on the
-stack. (This may not be at the very start of the allocated stack region
-if the calling sequence has pushed anything else since pushing the stack
-arguments. But usually, on such machines, nothing else has been pushed
-yet, because the function prologue itself does all the pushing.) This
-region is used on machines where an argument may be passed partly in
-registers and partly in memory, and, in some cases to support the
-features in @code{<stdarg.h>}.
-
-@item
-An area of memory used to save certain registers used by the function.
-The size of this area, which may also include space for such things as
-the return address and pointers to previous stack frames, is
-machine-specific and usually depends on which registers have been used
-in the function. Machines with register windows often do not require
-a save area.
-
-@item
-A region of at least @var{size} bytes, possibly rounded up to an allocation
-boundary, to contain the local variables of the function. On some machines,
-this region and the save area may occur in the opposite order, with the
-save area closer to the top of the stack.
-
-@item
-@cindex @code{ACCUMULATE_OUTGOING_ARGS} and stack frames
-Optionally, when @code{ACCUMULATE_OUTGOING_ARGS} is defined, a region of
-@code{crtl->outgoing_args_size} bytes to be used for outgoing
-argument lists of the function. @xref{Stack Arguments}.
-@end itemize
-
-@defmac EXIT_IGNORE_STACK
-Define this macro as a C expression that is nonzero if the return
-instruction or the function epilogue ignores the value of the stack
-pointer; in other words, if it is safe to delete an instruction to
-adjust the stack pointer before a return from the function. The
-default is 0.
-
-Note that this macro's value is relevant only for functions for which
-frame pointers are maintained. It is never safe to delete a final
-stack adjustment in a function that has no frame pointer, and the
-compiler knows this regardless of @code{EXIT_IGNORE_STACK}.
-@end defmac
-
-@defmac EPILOGUE_USES (@var{regno})
-Define this macro as a C expression that is nonzero for registers that are
-used by the epilogue or the @samp{return} pattern. The stack and frame
-pointer registers are already assumed to be used as needed.
-@end defmac
-
-@defmac EH_USES (@var{regno})
-Define this macro as a C expression that is nonzero for registers that are
-used by the exception handling mechanism, and so should be considered live
-on entry to an exception edge.
-@end defmac
-
-@deftypefn {Target Hook} void TARGET_ASM_OUTPUT_MI_THUNK (FILE *@var{file}, tree @var{thunk_fndecl}, HOST_WIDE_INT @var{delta}, HOST_WIDE_INT @var{vcall_offset}, tree @var{function})
-A function that outputs the assembler code for a thunk
-function, used to implement C++ virtual function calls with multiple
-inheritance. The thunk acts as a wrapper around a virtual function,
-adjusting the implicit object parameter before handing control off to
-the real function.
-
-First, emit code to add the integer @var{delta} to the location that
-contains the incoming first argument. Assume that this argument
-contains a pointer, and is the one used to pass the @code{this} pointer
-in C++. This is the incoming argument @emph{before} the function prologue,
-e.g.@: @samp{%o0} on a sparc. The addition must preserve the values of
-all other incoming arguments.
-
-Then, if @var{vcall_offset} is nonzero, an additional adjustment should be
-made after adding @code{delta}. In particular, if @var{p} is the
-adjusted pointer, the following adjustment should be made:
-
-@smallexample
-p += (*((ptrdiff_t **)p))[vcall_offset/sizeof(ptrdiff_t)]
-@end smallexample
-
-After the additions, emit code to jump to @var{function}, which is a
-@code{FUNCTION_DECL}. This is a direct pure jump, not a call, and does
-not touch the return address. Hence returning from @var{FUNCTION} will
-return to whoever called the current @samp{thunk}.
-
-The effect must be as if @var{function} had been called directly with
-the adjusted first argument. This macro is responsible for emitting all
-of the code for a thunk function; @code{TARGET_ASM_FUNCTION_PROLOGUE}
-and @code{TARGET_ASM_FUNCTION_EPILOGUE} are not invoked.
-
-The @var{thunk_fndecl} is redundant. (@var{delta} and @var{function}
-have already been extracted from it.) It might possibly be useful on
-some targets, but probably not.
-
-If you do not define this macro, the target-independent code in the C++
-front end will generate a less efficient heavyweight thunk that calls
-@var{function} instead of jumping to it. The generic approach does
-not support varargs.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_ASM_CAN_OUTPUT_MI_THUNK (const_tree @var{thunk_fndecl}, HOST_WIDE_INT @var{delta}, HOST_WIDE_INT @var{vcall_offset}, const_tree @var{function})
-A function that returns true if TARGET_ASM_OUTPUT_MI_THUNK would be able
-to output the assembler code for the thunk function specified by the
-arguments it is passed, and false otherwise. In the latter case, the
-generic approach will be used by the C++ front end, with the limitations
-previously exposed.
-@end deftypefn
-
-@node Profiling
-@subsection Generating Code for Profiling
-@cindex profiling, code generation
-
-These macros will help you generate code for profiling.
-
-@defmac FUNCTION_PROFILER (@var{file}, @var{labelno})
-A C statement or compound statement to output to @var{file} some
-assembler code to call the profiling subroutine @code{mcount}.
-
-@findex mcount
-The details of how @code{mcount} expects to be called are determined by
-your operating system environment, not by GCC@. To figure them out,
-compile a small program for profiling using the system's installed C
-compiler and look at the assembler code that results.
-
-Older implementations of @code{mcount} expect the address of a counter
-variable to be loaded into some register. The name of this variable is
-@samp{LP} followed by the number @var{labelno}, so you would generate
-the name using @samp{LP%d} in a @code{fprintf}.
-@end defmac
-
-@defmac PROFILE_HOOK
-A C statement or compound statement to output to @var{file} some assembly
-code to call the profiling subroutine @code{mcount} even the target does
-not support profiling.
-@end defmac
-
-@defmac NO_PROFILE_COUNTERS
-Define this macro to be an expression with a nonzero value if the
-@code{mcount} subroutine on your system does not need a counter variable
-allocated for each function. This is true for almost all modern
-implementations. If you define this macro, you must not use the
-@var{labelno} argument to @code{FUNCTION_PROFILER}.
-@end defmac
-
-@defmac PROFILE_BEFORE_PROLOGUE
-Define this macro if the code for function profiling should come before
-the function prologue. Normally, the profiling code comes after.
-@end defmac
-
-@deftypefn {Target Hook} bool TARGET_KEEP_LEAF_WHEN_PROFILED (void)
-This target hook returns true if the target wants the leaf flag for
-the current function to stay true even if it calls mcount. This might
-make sense for targets using the leaf flag only to determine whether a
-stack frame needs to be generated or not and for which the call to
-mcount is generated before the function prologue.
-@end deftypefn
-
-@node Tail Calls
-@subsection Permitting tail calls
-@cindex tail calls
-
-@deftypefn {Target Hook} bool TARGET_FUNCTION_OK_FOR_SIBCALL (tree @var{decl}, tree @var{exp})
-True if it is OK to do sibling call optimization for the specified
-call expression @var{exp}. @var{decl} will be the called function,
-or @code{NULL} if this is an indirect call.
-
-It is not uncommon for limitations of calling conventions to prevent
-tail calls to functions outside the current unit of translation, or
-during PIC compilation. The hook is used to enforce these restrictions,
-as the @code{sibcall} md pattern cannot fail, or fall over to a
-``normal'' call. The criteria for successful sibling call optimization
-may vary greatly between different architectures.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_EXTRA_LIVE_ON_ENTRY (bitmap @var{regs})
-Add any hard registers to @var{regs} that are live on entry to the
-function. This hook only needs to be defined to provide registers that
-cannot be found by examination of FUNCTION_ARG_REGNO_P, the callee saved
-registers, STATIC_CHAIN_INCOMING_REGNUM, STATIC_CHAIN_REGNUM,
-TARGET_STRUCT_VALUE_RTX, FRAME_POINTER_REGNUM, EH_USES,
-FRAME_POINTER_REGNUM, ARG_POINTER_REGNUM, and the PIC_OFFSET_TABLE_REGNUM.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_SET_UP_BY_PROLOGUE (struct hard_reg_set_container *@var{})
-This hook should add additional registers that are computed by the prologue
-to the hard regset for shrink-wrapping optimization purposes.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_WARN_FUNC_RETURN (tree)
-True if a function's return statements should be checked for matching
-the function's return type. This includes checking for falling off the end
-of a non-void function. Return false if no such check should be made.
-@end deftypefn
-
-@node Shrink-wrapping separate components
-@subsection Shrink-wrapping separate components
-@cindex shrink-wrapping separate components
-
-The prologue may perform a variety of target dependent tasks such as
-saving callee-saved registers, saving the return address, aligning the
-stack, creating a stack frame, initializing the PIC register, setting
-up the static chain, etc.
-
-On some targets some of these tasks may be independent of others and
-thus may be shrink-wrapped separately. These independent tasks are
-referred to as components and are handled generically by the target
-independent parts of GCC.
-
-Using the following hooks those prologue or epilogue components can be
-shrink-wrapped separately, so that the initialization (and possibly
-teardown) those components do is not done as frequently on execution
-paths where this would unnecessary.
-
-What exactly those components are is up to the target code; the generic
-code treats them abstractly, as a bit in an @code{sbitmap}. These
-@code{sbitmap}s are allocated by the @code{shrink_wrap.get_separate_components}
-and @code{shrink_wrap.components_for_bb} hooks, and deallocated by the
-generic code.
-
-@deftypefn {Target Hook} sbitmap TARGET_SHRINK_WRAP_GET_SEPARATE_COMPONENTS (void)
-This hook should return an @code{sbitmap} with the bits set for those
-components that can be separately shrink-wrapped in the current function.
-Return @code{NULL} if the current function should not get any separate
-shrink-wrapping.
-Don't define this hook if it would always return @code{NULL}.
-If it is defined, the other hooks in this group have to be defined as well.
-@end deftypefn
-
-@deftypefn {Target Hook} sbitmap TARGET_SHRINK_WRAP_COMPONENTS_FOR_BB (basic_block)
-This hook should return an @code{sbitmap} with the bits set for those
-components where either the prologue component has to be executed before
-the @code{basic_block}, or the epilogue component after it, or both.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_SHRINK_WRAP_DISQUALIFY_COMPONENTS (sbitmap @var{components}, edge @var{e}, sbitmap @var{edge_components}, bool @var{is_prologue})
-This hook should clear the bits in the @var{components} bitmap for those
-components in @var{edge_components} that the target cannot handle on edge
-@var{e}, where @var{is_prologue} says if this is for a prologue or an
-epilogue instead.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_SHRINK_WRAP_EMIT_PROLOGUE_COMPONENTS (sbitmap)
-Emit prologue insns for the components indicated by the parameter.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_SHRINK_WRAP_EMIT_EPILOGUE_COMPONENTS (sbitmap)
-Emit epilogue insns for the components indicated by the parameter.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_SHRINK_WRAP_SET_HANDLED_COMPONENTS (sbitmap)
-Mark the components in the parameter as handled, so that the
-@code{prologue} and @code{epilogue} named patterns know to ignore those
-components. The target code should not hang on to the @code{sbitmap}, it
-will be deleted after this call.
-@end deftypefn
-
-@node Stack Smashing Protection
-@subsection Stack smashing protection
-@cindex stack smashing protection
-
-@deftypefn {Target Hook} tree TARGET_STACK_PROTECT_GUARD (void)
-This hook returns a @code{DECL} node for the external variable to use
-for the stack protection guard. This variable is initialized by the
-runtime to some random value and is used to initialize the guard value
-that is placed at the top of the local stack frame. The type of this
-variable must be @code{ptr_type_node}.
-
-The default version of this hook creates a variable called
-@samp{__stack_chk_guard}, which is normally defined in @file{libgcc2.c}.
-@end deftypefn
-
-@deftypefn {Target Hook} tree TARGET_STACK_PROTECT_FAIL (void)
-This hook returns a @code{CALL_EXPR} that alerts the runtime that the
-stack protect guard variable has been modified. This expression should
-involve a call to a @code{noreturn} function.
-
-The default version of this hook invokes a function called
-@samp{__stack_chk_fail}, taking no arguments. This function is
-normally defined in @file{libgcc2.c}.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_STACK_PROTECT_RUNTIME_ENABLED_P (void)
-Returns true if the target wants GCC's default stack protect runtime support,
-otherwise return false. The default implementation always returns true.
-@end deftypefn
-
-@deftypefn {Common Target Hook} bool TARGET_SUPPORTS_SPLIT_STACK (bool @var{report}, struct gcc_options *@var{opts})
-Whether this target supports splitting the stack when the options
-described in @var{opts} have been passed. This is called
-after options have been parsed, so the target may reject splitting
-the stack in some configurations. The default version of this hook
-returns false. If @var{report} is true, this function may issue a warning
-or error; if @var{report} is false, it must simply return a value
-@end deftypefn
-
-@deftypefn {Common Target Hook} {vec<const char *>} TARGET_GET_VALID_OPTION_VALUES (int @var{option_code}, const char *@var{prefix})
-The hook is used for options that have a non-trivial list of
-possible option values. OPTION_CODE is option code of opt_code
-enum type. PREFIX is used for bash completion and allows an implementation
-to return more specific completion based on the prefix. All string values
-should be allocated from heap memory and consumers should release them.
-The result will be pruned to cases with PREFIX if not NULL.
-@end deftypefn
-
-@node Miscellaneous Register Hooks
-@subsection Miscellaneous register hooks
-@cindex miscellaneous register hooks
-
-@deftypevr {Target Hook} bool TARGET_CALL_FUSAGE_CONTAINS_NON_CALLEE_CLOBBERS
-Set to true if each call that binds to a local definition explicitly
-clobbers or sets all non-fixed registers modified by performing the call.
-That is, by the call pattern itself, or by code that might be inserted by the
-linker (e.g.@: stubs, veneers, branch islands), but not including those
-modifiable by the callee. The affected registers may be mentioned explicitly
-in the call pattern, or included as clobbers in CALL_INSN_FUNCTION_USAGE.
-The default version of this hook is set to false. The purpose of this hook
-is to enable the fipa-ra optimization.
-@end deftypevr
-
-@node Varargs
-@section Implementing the Varargs Macros
-@cindex varargs implementation
-
-GCC comes with an implementation of @code{<varargs.h>} and
-@code{<stdarg.h>} that work without change on machines that pass arguments
-on the stack. Other machines require their own implementations of
-varargs, and the two machine independent header files must have
-conditionals to include it.
-
-ISO @code{<stdarg.h>} differs from traditional @code{<varargs.h>} mainly in
-the calling convention for @code{va_start}. The traditional
-implementation takes just one argument, which is the variable in which
-to store the argument pointer. The ISO implementation of
-@code{va_start} takes an additional second argument. The user is
-supposed to write the last named argument of the function here.
-
-However, @code{va_start} should not use this argument. The way to find
-the end of the named arguments is with the built-in functions described
-below.
-
-@defmac __builtin_saveregs ()
-Use this built-in function to save the argument registers in memory so
-that the varargs mechanism can access them. Both ISO and traditional
-versions of @code{va_start} must use @code{__builtin_saveregs}, unless
-you use @code{TARGET_SETUP_INCOMING_VARARGS} (see below) instead.
-
-On some machines, @code{__builtin_saveregs} is open-coded under the
-control of the target hook @code{TARGET_EXPAND_BUILTIN_SAVEREGS}. On
-other machines, it calls a routine written in assembler language,
-found in @file{libgcc2.c}.
-
-Code generated for the call to @code{__builtin_saveregs} appears at the
-beginning of the function, as opposed to where the call to
-@code{__builtin_saveregs} is written, regardless of what the code is.
-This is because the registers must be saved before the function starts
-to use them for its own purposes.
-@c i rewrote the first sentence above to fix an overfull hbox. --mew
-@c 10feb93
-@end defmac
-
-@defmac __builtin_next_arg (@var{lastarg})
-This builtin returns the address of the first anonymous stack
-argument, as type @code{void *}. If @code{ARGS_GROW_DOWNWARD}, it
-returns the address of the location above the first anonymous stack
-argument. Use it in @code{va_start} to initialize the pointer for
-fetching arguments from the stack. Also use it in @code{va_start} to
-verify that the second parameter @var{lastarg} is the last named argument
-of the current function.
-@end defmac
-
-@defmac __builtin_classify_type (@var{object})
-Since each machine has its own conventions for which data types are
-passed in which kind of register, your implementation of @code{va_arg}
-has to embody these conventions. The easiest way to categorize the
-specified data type is to use @code{__builtin_classify_type} together
-with @code{sizeof} and @code{__alignof__}.
-
-@code{__builtin_classify_type} ignores the value of @var{object},
-considering only its data type. It returns an integer describing what
-kind of type that is---integer, floating, pointer, structure, and so on.
-
-The file @file{typeclass.h} defines an enumeration that you can use to
-interpret the values of @code{__builtin_classify_type}.
-@end defmac
-
-These machine description macros help implement varargs:
-
-@deftypefn {Target Hook} rtx TARGET_EXPAND_BUILTIN_SAVEREGS (void)
-If defined, this hook produces the machine-specific code for a call to
-@code{__builtin_saveregs}. This code will be moved to the very
-beginning of the function, before any parameter access are made. The
-return value of this function should be an RTX that contains the value
-to use as the return of @code{__builtin_saveregs}.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_SETUP_INCOMING_VARARGS (cumulative_args_t @var{args_so_far}, const function_arg_info @var{&arg}, int *@var{pretend_args_size}, int @var{second_time})
-This target hook offers an alternative to using
-@code{__builtin_saveregs} and defining the hook
-@code{TARGET_EXPAND_BUILTIN_SAVEREGS}. Use it to store the anonymous
-register arguments into the stack so that all the arguments appear to
-have been passed consecutively on the stack. Once this is done, you can
-use the standard implementation of varargs that works for machines that
-pass all their arguments on the stack.
-
-The argument @var{args_so_far} points to the @code{CUMULATIVE_ARGS} data
-structure, containing the values that are obtained after processing the
-named arguments. The argument @var{arg} describes the last of these named
-arguments. The argument @var{arg} should not be used if the function type
-satisfies @code{TYPE_NO_NAMED_ARGS_STDARG_P}, since in that case there are
-no named arguments and all arguments are accessed with @code{va_arg}.
-
-The target hook should do two things: first, push onto the stack all the
-argument registers @emph{not} used for the named arguments, and second,
-store the size of the data thus pushed into the @code{int}-valued
-variable pointed to by @var{pretend_args_size}. The value that you
-store here will serve as additional offset for setting up the stack
-frame.
-
-Because you must generate code to push the anonymous arguments at
-compile time without knowing their data types,
-@code{TARGET_SETUP_INCOMING_VARARGS} is only useful on machines that
-have just a single category of argument register and use it uniformly
-for all data types.
-
-If the argument @var{second_time} is nonzero, it means that the
-arguments of the function are being analyzed for the second time. This
-happens for an inline function, which is not actually compiled until the
-end of the source file. The hook @code{TARGET_SETUP_INCOMING_VARARGS} should
-not generate any instructions in this case.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_STRICT_ARGUMENT_NAMING (cumulative_args_t @var{ca})
-Define this hook to return @code{true} if the location where a function
-argument is passed depends on whether or not it is a named argument.
-
-This hook controls how the @var{named} argument to @code{TARGET_FUNCTION_ARG}
-is set for varargs and stdarg functions. If this hook returns
-@code{true}, the @var{named} argument is always true for named
-arguments, and false for unnamed arguments. If it returns @code{false},
-but @code{TARGET_PRETEND_OUTGOING_VARARGS_NAMED} returns @code{true},
-then all arguments are treated as named. Otherwise, all named arguments
-except the last are treated as named.
-
-You need not define this hook if it always returns @code{false}.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_CALL_ARGS (rtx, @var{tree})
-While generating RTL for a function call, this target hook is invoked once
-for each argument passed to the function, either a register returned by
-@code{TARGET_FUNCTION_ARG} or a memory location. It is called just
-before the point where argument registers are stored. The type of the
-function to be called is also passed as the second argument; it is
-@code{NULL_TREE} for libcalls. The @code{TARGET_END_CALL_ARGS} hook is
-invoked just after the code to copy the return reg has been emitted.
-This functionality can be used to perform special setup of call argument
-registers if a target needs it.
-For functions without arguments, the hook is called once with @code{pc_rtx}
-passed instead of an argument register.
-Most ports do not need to implement anything for this hook.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_END_CALL_ARGS (void)
-This target hook is invoked while generating RTL for a function call,
-just after the point where the return reg is copied into a pseudo. It
-signals that all the call argument and return registers for the just
-emitted call are now no longer in use.
-Most ports do not need to implement anything for this hook.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_PRETEND_OUTGOING_VARARGS_NAMED (cumulative_args_t @var{ca})
-If you need to conditionally change ABIs so that one works with
-@code{TARGET_SETUP_INCOMING_VARARGS}, but the other works like neither
-@code{TARGET_SETUP_INCOMING_VARARGS} nor @code{TARGET_STRICT_ARGUMENT_NAMING} was
-defined, then define this hook to return @code{true} if
-@code{TARGET_SETUP_INCOMING_VARARGS} is used, @code{false} otherwise.
-Otherwise, you should not define this hook.
-@end deftypefn
-
-@node Trampolines
-@section Support for Nested Functions
-@cindex support for nested functions
-@cindex trampolines for nested functions
-@cindex descriptors for nested functions
-@cindex nested functions, support for
-
-Taking the address of a nested function requires special compiler
-handling to ensure that the static chain register is loaded when
-the function is invoked via an indirect call.
-
-GCC has traditionally supported nested functions by creating an
-executable @dfn{trampoline} at run time when the address of a nested
-function is taken. This is a small piece of code which normally
-resides on the stack, in the stack frame of the containing function.
-The trampoline loads the static chain register and then jumps to the
-real address of the nested function.
-
-The use of trampolines requires an executable stack, which is a
-security risk. To avoid this problem, GCC also supports another
-strategy: using descriptors for nested functions. Under this model,
-taking the address of a nested function results in a pointer to a
-non-executable function descriptor object. Initializing the static chain
-from the descriptor is handled at indirect call sites.
-
-On some targets, including HPPA and IA-64, function descriptors may be
-mandated by the ABI or be otherwise handled in a target-specific way
-by the back end in its code generation strategy for indirect calls.
-GCC also provides its own generic descriptor implementation to support the
-@option{-fno-trampolines} option. In this case runtime detection of
-function descriptors at indirect call sites relies on descriptor
-pointers being tagged with a bit that is never set in bare function
-addresses. Since GCC's generic function descriptors are
-not ABI-compliant, this option is typically used only on a
-per-language basis (notably by Ada) or when it can otherwise be
-applied to the whole program.
-
-For languages other than Ada, the @code{-ftrampolines} and
-@code{-fno-trampolines} options currently have no effect, and
-trampolines are always generated on platforms that need them
-for nested functions.
-
-Define the following hook if your backend either implements ABI-specified
-descriptor support, or can use GCC's generic descriptor implementation
-for nested functions.
-
-@deftypevr {Target Hook} int TARGET_CUSTOM_FUNCTION_DESCRIPTORS
-If the target can use GCC's generic descriptor mechanism for nested
-functions, define this hook to a power of 2 representing an unused bit
-in function pointers which can be used to differentiate descriptors at
-run time. This value gives the number of bytes by which descriptor
-pointers are misaligned compared to function pointers. For example, on
-targets that require functions to be aligned to a 4-byte boundary, a
-value of either 1 or 2 is appropriate unless the architecture already
-reserves the bit for another purpose, such as on ARM.
-
-Define this hook to 0 if the target implements ABI support for
-function descriptors in its standard calling sequence, like for example
-HPPA or IA-64.
-
-Using descriptors for nested functions
-eliminates the need for trampolines that reside on the stack and require
-it to be made executable.
-@end deftypevr
-
-The following macros tell GCC how to generate code to allocate and
-initialize an executable trampoline. You can also use this interface
-if your back end needs to create ABI-specified non-executable descriptors; in
-this case the "trampoline" created is the descriptor containing data only.
-
-The instructions in an executable trampoline must do two things: load
-a constant address into the static chain register, and jump to the real
-address of the nested function. On CISC machines such as the m68k,
-this requires two instructions, a move immediate and a jump. Then the
-two addresses exist in the trampoline as word-long immediate operands.
-On RISC machines, it is often necessary to load each address into a
-register in two parts. Then pieces of each address form separate
-immediate operands.
-
-The code generated to initialize the trampoline must store the variable
-parts---the static chain value and the function address---into the
-immediate operands of the instructions. On a CISC machine, this is
-simply a matter of copying each address to a memory reference at the
-proper offset from the start of the trampoline. On a RISC machine, it
-may be necessary to take out pieces of the address and store them
-separately.
-
-@deftypefn {Target Hook} void TARGET_ASM_TRAMPOLINE_TEMPLATE (FILE *@var{f})
-This hook is called by @code{assemble_trampoline_template} to output,
-on the stream @var{f}, assembler code for a block of data that contains
-the constant parts of a trampoline. This code should not include a
-label---the label is taken care of automatically.
-
-If you do not define this hook, it means no template is needed
-for the target. Do not define this hook on systems where the block move
-code to copy the trampoline into place would be larger than the code
-to generate it on the spot.
-@end deftypefn
-
-@defmac TRAMPOLINE_SECTION
-Return the section into which the trampoline template is to be placed
-(@pxref{Sections}). The default value is @code{readonly_data_section}.
-@end defmac
-
-@defmac TRAMPOLINE_SIZE
-A C expression for the size in bytes of the trampoline, as an integer.
-@end defmac
-
-@defmac TRAMPOLINE_ALIGNMENT
-Alignment required for trampolines, in bits.
-
-If you don't define this macro, the value of @code{FUNCTION_ALIGNMENT}
-is used for aligning trampolines.
-@end defmac
-
-@deftypefn {Target Hook} void TARGET_TRAMPOLINE_INIT (rtx @var{m_tramp}, tree @var{fndecl}, rtx @var{static_chain})
-This hook is called to initialize a trampoline.
-@var{m_tramp} is an RTX for the memory block for the trampoline; @var{fndecl}
-is the @code{FUNCTION_DECL} for the nested function; @var{static_chain} is an
-RTX for the static chain value that should be passed to the function
-when it is called.
-
-If the target defines @code{TARGET_ASM_TRAMPOLINE_TEMPLATE}, then the
-first thing this hook should do is emit a block move into @var{m_tramp}
-from the memory block returned by @code{assemble_trampoline_template}.
-Note that the block move need only cover the constant parts of the
-trampoline. If the target isolates the variable parts of the trampoline
-to the end, not all @code{TRAMPOLINE_SIZE} bytes need be copied.
-
-If the target requires any other actions, such as flushing caches
-(possibly calling function maybe_emit_call_builtin___clear_cache) or
-enabling stack execution, these actions should be performed after
-initializing the trampoline proper.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_EMIT_CALL_BUILTIN___CLEAR_CACHE (rtx @var{begin}, rtx @var{end})
-On targets that do not define a @code{clear_cache} insn expander,
-but that define the @code{CLEAR_CACHE_INSN} macro,
-maybe_emit_call_builtin___clear_cache relies on this target hook
-to clear an address range in the instruction cache.
-
-The default implementation calls the @code{__clear_cache} builtin,
-taking the assembler name from the builtin declaration. Overriding
-definitions may call alternate functions, with alternate calling
-conventions, or emit alternate RTX to perform the job.
-@end deftypefn
-
-@deftypefn {Target Hook} rtx TARGET_TRAMPOLINE_ADJUST_ADDRESS (rtx @var{addr})
-This hook should perform any machine-specific adjustment in
-the address of the trampoline. Its argument contains the address of the
-memory block that was passed to @code{TARGET_TRAMPOLINE_INIT}. In case
-the address to be used for a function call should be different from the
-address at which the template was stored, the different address should
-be returned; otherwise @var{addr} should be returned unchanged.
-If this hook is not defined, @var{addr} will be used for function calls.
-@end deftypefn
-
-Implementing trampolines is difficult on many machines because they have
-separate instruction and data caches. Writing into a stack location
-fails to clear the memory in the instruction cache, so when the program
-jumps to that location, it executes the old contents.
-
-Here are two possible solutions. One is to clear the relevant parts of
-the instruction cache whenever a trampoline is set up. The other is to
-make all trampolines identical, by having them jump to a standard
-subroutine. The former technique makes trampoline execution faster; the
-latter makes initialization faster.
-
-To clear the instruction cache when a trampoline is initialized, define
-the following macro.
-
-@defmac CLEAR_INSN_CACHE (@var{beg}, @var{end})
-If defined, expands to a C expression clearing the @emph{instruction
-cache} in the specified interval. The definition of this macro would
-typically be a series of @code{asm} statements. Both @var{beg} and
-@var{end} are pointer expressions.
-@end defmac
-
-To use a standard subroutine, define the following macro. In addition,
-you must make sure that the instructions in a trampoline fill an entire
-cache line with identical instructions, or else ensure that the
-beginning of the trampoline code is always aligned at the same point in
-its cache line. Look in @file{m68k.h} as a guide.
-
-@defmac TRANSFER_FROM_TRAMPOLINE
-Define this macro if trampolines need a special subroutine to do their
-work. The macro should expand to a series of @code{asm} statements
-which will be compiled with GCC@. They go in a library function named
-@code{__transfer_from_trampoline}.
-
-If you need to avoid executing the ordinary prologue code of a compiled
-C function when you jump to the subroutine, you can do so by placing a
-special label of your own in the assembler code. Use one @code{asm}
-statement to generate an assembler label, and another to make the label
-global. Then trampolines can use that label to jump directly to your
-special assembler code.
-@end defmac
-
-@node Library Calls
-@section Implicit Calls to Library Routines
-@cindex library subroutine names
-@cindex @file{libgcc.a}
-
-@c prevent bad page break with this line
-Here is an explanation of implicit calls to library routines.
-
-@defmac DECLARE_LIBRARY_RENAMES
-This macro, if defined, should expand to a piece of C code that will get
-expanded when compiling functions for libgcc.a. It can be used to
-provide alternate names for GCC's internal library functions if there
-are ABI-mandated names that the compiler should provide.
-@end defmac
-
-@findex set_optab_libfunc
-@findex init_one_libfunc
-@deftypefn {Target Hook} void TARGET_INIT_LIBFUNCS (void)
-This hook should declare additional library routines or rename
-existing ones, using the functions @code{set_optab_libfunc} and
-@code{init_one_libfunc} defined in @file{optabs.cc}.
-@code{init_optabs} calls this macro after initializing all the normal
-library routines.
-
-The default is to do nothing. Most ports don't need to define this hook.
-@end deftypefn
-
-@deftypevr {Target Hook} bool TARGET_LIBFUNC_GNU_PREFIX
-If false (the default), internal library routines start with two
-underscores. If set to true, these routines start with @code{__gnu_}
-instead. E.g., @code{__muldi3} changes to @code{__gnu_muldi3}. This
-currently only affects functions defined in @file{libgcc2.c}. If this
-is set to true, the @file{tm.h} file must also
-@code{#define LIBGCC2_GNU_PREFIX}.
-@end deftypevr
-
-@defmac FLOAT_LIB_COMPARE_RETURNS_BOOL (@var{mode}, @var{comparison})
-This macro should return @code{true} if the library routine that
-implements the floating point comparison operator @var{comparison} in
-mode @var{mode} will return a boolean, and @var{false} if it will
-return a tristate.
-
-GCC's own floating point libraries return tristates from the
-comparison operators, so the default returns false always. Most ports
-don't need to define this macro.
-@end defmac
-
-@defmac TARGET_LIB_INT_CMP_BIASED
-This macro should evaluate to @code{true} if the integer comparison
-functions (like @code{__cmpdi2}) return 0 to indicate that the first
-operand is smaller than the second, 1 to indicate that they are equal,
-and 2 to indicate that the first operand is greater than the second.
-If this macro evaluates to @code{false} the comparison functions return
-@minus{}1, 0, and 1 instead of 0, 1, and 2. If the target uses the routines
-in @file{libgcc.a}, you do not need to define this macro.
-@end defmac
-
-@defmac TARGET_HAS_NO_HW_DIVIDE
-This macro should be defined if the target has no hardware divide
-instructions. If this macro is defined, GCC will use an algorithm which
-make use of simple logical and arithmetic operations for 64-bit
-division. If the macro is not defined, GCC will use an algorithm which
-make use of a 64-bit by 32-bit divide primitive.
-@end defmac
-
-@cindex @code{EDOM}, implicit usage
-@findex matherr
-@defmac TARGET_EDOM
-The value of @code{EDOM} on the target machine, as a C integer constant
-expression. If you don't define this macro, GCC does not attempt to
-deposit the value of @code{EDOM} into @code{errno} directly. Look in
-@file{/usr/include/errno.h} to find the value of @code{EDOM} on your
-system.
-
-If you do not define @code{TARGET_EDOM}, then compiled code reports
-domain errors by calling the library function and letting it report the
-error. If mathematical functions on your system use @code{matherr} when
-there is an error, then you should leave @code{TARGET_EDOM} undefined so
-that @code{matherr} is used normally.
-@end defmac
-
-@cindex @code{errno}, implicit usage
-@defmac GEN_ERRNO_RTX
-Define this macro as a C expression to create an rtl expression that
-refers to the global ``variable'' @code{errno}. (On certain systems,
-@code{errno} may not actually be a variable.) If you don't define this
-macro, a reasonable default is used.
-@end defmac
-
-@deftypefn {Target Hook} bool TARGET_LIBC_HAS_FUNCTION (enum function_class @var{fn_class}, tree @var{type})
-This hook determines whether a function from a class of functions
-@var{fn_class} is present in the target C library. If @var{type} is NULL,
-the caller asks for support for all standard (float, double, long double)
-types. If @var{type} is non-NULL, the caller asks for support for a
-specific type.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_LIBC_HAS_FAST_FUNCTION (int @var{fcode})
-This hook determines whether a function from a class of functions
-@code{(enum function_class)}@var{fcode} has a fast implementation.
-@end deftypefn
-
-@defmac NEXT_OBJC_RUNTIME
-Set this macro to 1 to use the "NeXT" Objective-C message sending conventions
-by default. This calling convention involves passing the object, the selector
-and the method arguments all at once to the method-lookup library function.
-This is the usual setting when targeting Darwin/Mac OS X systems, which have
-the NeXT runtime installed.
-
-If the macro is set to 0, the "GNU" Objective-C message sending convention
-will be used by default. This convention passes just the object and the
-selector to the method-lookup function, which returns a pointer to the method.
-
-In either case, it remains possible to select code-generation for the alternate
-scheme, by means of compiler command line switches.
-@end defmac
-
-@node Addressing Modes
-@section Addressing Modes
-@cindex addressing modes
-
-@c prevent bad page break with this line
-This is about addressing modes.
-
-@defmac HAVE_PRE_INCREMENT
-@defmacx HAVE_PRE_DECREMENT
-@defmacx HAVE_POST_INCREMENT
-@defmacx HAVE_POST_DECREMENT
-A C expression that is nonzero if the machine supports pre-increment,
-pre-decrement, post-increment, or post-decrement addressing respectively.
-@end defmac
-
-@defmac HAVE_PRE_MODIFY_DISP
-@defmacx HAVE_POST_MODIFY_DISP
-A C expression that is nonzero if the machine supports pre- or
-post-address side-effect generation involving constants other than
-the size of the memory operand.
-@end defmac
-
-@defmac HAVE_PRE_MODIFY_REG
-@defmacx HAVE_POST_MODIFY_REG
-A C expression that is nonzero if the machine supports pre- or
-post-address side-effect generation involving a register displacement.
-@end defmac
-
-@defmac CONSTANT_ADDRESS_P (@var{x})
-A C expression that is 1 if the RTX @var{x} is a constant which
-is a valid address. On most machines the default definition of
-@code{(CONSTANT_P (@var{x}) && GET_CODE (@var{x}) != CONST_DOUBLE)}
-is acceptable, but a few machines are more restrictive as to which
-constant addresses are supported.
-@end defmac
-
-@defmac CONSTANT_P (@var{x})
-@code{CONSTANT_P}, which is defined by target-independent code,
-accepts integer-values expressions whose values are not explicitly
-known, such as @code{symbol_ref}, @code{label_ref}, and @code{high}
-expressions and @code{const} arithmetic expressions, in addition to
-@code{const_int} and @code{const_double} expressions.
-@end defmac
-
-@defmac MAX_REGS_PER_ADDRESS
-A number, the maximum number of registers that can appear in a valid
-memory address. Note that it is up to you to specify a value equal to
-the maximum number that @code{TARGET_LEGITIMATE_ADDRESS_P} would ever
-accept.
-@end defmac
-
-@deftypefn {Target Hook} bool TARGET_LEGITIMATE_ADDRESS_P (machine_mode @var{mode}, rtx @var{x}, bool @var{strict})
-A function that returns whether @var{x} (an RTX) is a legitimate memory
-address on the target machine for a memory operand of mode @var{mode}.
-
-Legitimate addresses are defined in two variants: a strict variant and a
-non-strict one. The @var{strict} parameter chooses which variant is
-desired by the caller.
-
-The strict variant is used in the reload pass. It must be defined so
-that any pseudo-register that has not been allocated a hard register is
-considered a memory reference. This is because in contexts where some
-kind of register is required, a pseudo-register with no hard register
-must be rejected. For non-hard registers, the strict variant should look
-up the @code{reg_renumber} array; it should then proceed using the hard
-register number in the array, or treat the pseudo as a memory reference
-if the array holds @code{-1}.
-
-The non-strict variant is used in other passes. It must be defined to
-accept all pseudo-registers in every context where some kind of
-register is required.
-
-Normally, constant addresses which are the sum of a @code{symbol_ref}
-and an integer are stored inside a @code{const} RTX to mark them as
-constant. Therefore, there is no need to recognize such sums
-specifically as legitimate addresses. Normally you would simply
-recognize any @code{const} as legitimate.
-
-Usually @code{PRINT_OPERAND_ADDRESS} is not prepared to handle constant
-sums that are not marked with @code{const}. It assumes that a naked
-@code{plus} indicates indexing. If so, then you @emph{must} reject such
-naked constant sums as illegitimate addresses, so that none of them will
-be given to @code{PRINT_OPERAND_ADDRESS}.
-
-@cindex @code{TARGET_ENCODE_SECTION_INFO} and address validation
-On some machines, whether a symbolic address is legitimate depends on
-the section that the address refers to. On these machines, define the
-target hook @code{TARGET_ENCODE_SECTION_INFO} to store the information
-into the @code{symbol_ref}, and then check for it here. When you see a
-@code{const}, you will have to look inside it to find the
-@code{symbol_ref} in order to determine the section. @xref{Assembler
-Format}.
-
-@cindex @code{GO_IF_LEGITIMATE_ADDRESS}
-Some ports are still using a deprecated legacy substitute for
-this hook, the @code{GO_IF_LEGITIMATE_ADDRESS} macro. This macro
-has this syntax:
-
-@example
-#define GO_IF_LEGITIMATE_ADDRESS (@var{mode}, @var{x}, @var{label})
-@end example
-
-@noindent
-and should @code{goto @var{label}} if the address @var{x} is a valid
-address on the target machine for a memory operand of mode @var{mode}.
-
-@findex REG_OK_STRICT
-Compiler source files that want to use the strict variant of this
-macro define the macro @code{REG_OK_STRICT}. You should use an
-@code{#ifdef REG_OK_STRICT} conditional to define the strict variant in
-that case and the non-strict variant otherwise.
-
-Using the hook is usually simpler because it limits the number of
-files that are recompiled when changes are made.
-@end deftypefn
-
-@defmac TARGET_MEM_CONSTRAINT
-A single character to be used instead of the default @code{'m'}
-character for general memory addresses. This defines the constraint
-letter which matches the memory addresses accepted by
-@code{TARGET_LEGITIMATE_ADDRESS_P}. Define this macro if you want to
-support new address formats in your back end without changing the
-semantics of the @code{'m'} constraint. This is necessary in order to
-preserve functionality of inline assembly constructs using the
-@code{'m'} constraint.
-@end defmac
-
-@defmac FIND_BASE_TERM (@var{x})
-A C expression to determine the base term of address @var{x},
-or to provide a simplified version of @var{x} from which @file{alias.cc}
-can easily find the base term. This macro is used in only two places:
-@code{find_base_value} and @code{find_base_term} in @file{alias.cc}.
-
-It is always safe for this macro to not be defined. It exists so
-that alias analysis can understand machine-dependent addresses.
-
-The typical use of this macro is to handle addresses containing
-a label_ref or symbol_ref within an UNSPEC@.
-@end defmac
-
-@deftypefn {Target Hook} rtx TARGET_LEGITIMIZE_ADDRESS (rtx @var{x}, rtx @var{oldx}, machine_mode @var{mode})
-This hook is given an invalid memory address @var{x} for an
-operand of mode @var{mode} and should try to return a valid memory
-address.
-
-@findex break_out_memory_refs
-@var{x} will always be the result of a call to @code{break_out_memory_refs},
-and @var{oldx} will be the operand that was given to that function to produce
-@var{x}.
-
-The code of the hook should not alter the substructure of
-@var{x}. If it transforms @var{x} into a more legitimate form, it
-should return the new @var{x}.
-
-It is not necessary for this hook to come up with a legitimate address,
-with the exception of native TLS addresses (@pxref{Emulated TLS}).
-The compiler has standard ways of doing so in all cases. In fact, if
-the target supports only emulated TLS, it
-is safe to omit this hook or make it return @var{x} if it cannot find
-a valid way to legitimize the address. But often a machine-dependent
-strategy can generate better code.
-@end deftypefn
-
-@defmac LEGITIMIZE_RELOAD_ADDRESS (@var{x}, @var{mode}, @var{opnum}, @var{type}, @var{ind_levels}, @var{win})
-A C compound statement that attempts to replace @var{x}, which is an address
-that needs reloading, with a valid memory address for an operand of mode
-@var{mode}. @var{win} will be a C statement label elsewhere in the code.
-It is not necessary to define this macro, but it might be useful for
-performance reasons.
-
-For example, on the i386, it is sometimes possible to use a single
-reload register instead of two by reloading a sum of two pseudo
-registers into a register. On the other hand, for number of RISC
-processors offsets are limited so that often an intermediate address
-needs to be generated in order to address a stack slot. By defining
-@code{LEGITIMIZE_RELOAD_ADDRESS} appropriately, the intermediate addresses
-generated for adjacent some stack slots can be made identical, and thus
-be shared.
-
-@emph{Note}: This macro should be used with caution. It is necessary
-to know something of how reload works in order to effectively use this,
-and it is quite easy to produce macros that build in too much knowledge
-of reload internals.
-
-@emph{Note}: This macro must be able to reload an address created by a
-previous invocation of this macro. If it fails to handle such addresses
-then the compiler may generate incorrect code or abort.
-
-@findex push_reload
-The macro definition should use @code{push_reload} to indicate parts that
-need reloading; @var{opnum}, @var{type} and @var{ind_levels} are usually
-suitable to be passed unaltered to @code{push_reload}.
-
-The code generated by this macro must not alter the substructure of
-@var{x}. If it transforms @var{x} into a more legitimate form, it
-should assign @var{x} (which will always be a C variable) a new value.
-This also applies to parts that you change indirectly by calling
-@code{push_reload}.
-
-@findex strict_memory_address_p
-The macro definition may use @code{strict_memory_address_p} to test if
-the address has become legitimate.
-
-@findex copy_rtx
-If you want to change only a part of @var{x}, one standard way of doing
-this is to use @code{copy_rtx}. Note, however, that it unshares only a
-single level of rtl. Thus, if the part to be changed is not at the
-top level, you'll need to replace first the top level.
-It is not necessary for this macro to come up with a legitimate
-address; but often a machine-dependent strategy can generate better code.
-@end defmac
-
-@deftypefn {Target Hook} bool TARGET_MODE_DEPENDENT_ADDRESS_P (const_rtx @var{addr}, addr_space_t @var{addrspace})
-This hook returns @code{true} if memory address @var{addr} in address
-space @var{addrspace} can have
-different meanings depending on the machine mode of the memory
-reference it is used for or if the address is valid for some modes
-but not others.
-
-Autoincrement and autodecrement addresses typically have mode-dependent
-effects because the amount of the increment or decrement is the size
-of the operand being addressed. Some machines have other mode-dependent
-addresses. Many RISC machines have no mode-dependent addresses.
-
-You may assume that @var{addr} is a valid address for the machine.
-
-The default version of this hook returns @code{false}.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_LEGITIMATE_CONSTANT_P (machine_mode @var{mode}, rtx @var{x})
-This hook returns true if @var{x} is a legitimate constant for a
-@var{mode}-mode immediate operand on the target machine. You can assume that
-@var{x} satisfies @code{CONSTANT_P}, so you need not check this.
-
-The default definition returns true.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_PRECOMPUTE_TLS_P (machine_mode @var{mode}, rtx @var{x})
-This hook returns true if @var{x} is a TLS operand on the target
-machine that should be pre-computed when used as the argument in a call.
-You can assume that @var{x} satisfies @code{CONSTANT_P}, so you need not
-check this.
-
-The default definition returns false.
-@end deftypefn
-
-@deftypefn {Target Hook} rtx TARGET_DELEGITIMIZE_ADDRESS (rtx @var{x})
-This hook is used to undo the possibly obfuscating effects of the
-@code{LEGITIMIZE_ADDRESS} and @code{LEGITIMIZE_RELOAD_ADDRESS} target
-macros. Some backend implementations of these macros wrap symbol
-references inside an @code{UNSPEC} rtx to represent PIC or similar
-addressing modes. This target hook allows GCC's optimizers to understand
-the semantics of these opaque @code{UNSPEC}s by converting them back
-into their original form.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_CONST_NOT_OK_FOR_DEBUG_P (rtx @var{x})
-This hook should return true if @var{x} should not be emitted into
-debug sections.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_CANNOT_FORCE_CONST_MEM (machine_mode @var{mode}, rtx @var{x})
-This hook should return true if @var{x} is of a form that cannot (or
-should not) be spilled to the constant pool. @var{mode} is the mode
-of @var{x}.
-
-The default version of this hook returns false.
-
-The primary reason to define this hook is to prevent reload from
-deciding that a non-legitimate constant would be better reloaded
-from the constant pool instead of spilling and reloading a register
-holding the constant. This restriction is often true of addresses
-of TLS symbols for various targets.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_USE_BLOCKS_FOR_CONSTANT_P (machine_mode @var{mode}, const_rtx @var{x})
-This hook should return true if pool entries for constant @var{x} can
-be placed in an @code{object_block} structure. @var{mode} is the mode
-of @var{x}.
-
-The default version returns false for all constants.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_USE_BLOCKS_FOR_DECL_P (const_tree @var{decl})
-This hook should return true if pool entries for @var{decl} should
-be placed in an @code{object_block} structure.
-
-The default version returns true for all decls.
-@end deftypefn
-
-@deftypefn {Target Hook} tree TARGET_BUILTIN_RECIPROCAL (tree @var{fndecl})
-This hook should return the DECL of a function that implements the
-reciprocal of the machine-specific builtin function @var{fndecl}, or
-@code{NULL_TREE} if such a function is not available.
-@end deftypefn
-
-@deftypefn {Target Hook} tree TARGET_VECTORIZE_BUILTIN_MASK_FOR_LOAD (void)
-This hook should return the DECL of a function @var{f} that given an
-address @var{addr} as an argument returns a mask @var{m} that can be
-used to extract from two vectors the relevant data that resides in
-@var{addr} in case @var{addr} is not properly aligned.
-
-The autovectorizer, when vectorizing a load operation from an address
-@var{addr} that may be unaligned, will generate two vector loads from
-the two aligned addresses around @var{addr}. It then generates a
-@code{REALIGN_LOAD} operation to extract the relevant data from the
-two loaded vectors. The first two arguments to @code{REALIGN_LOAD},
-@var{v1} and @var{v2}, are the two vectors, each of size @var{VS}, and
-the third argument, @var{OFF}, defines how the data will be extracted
-from these two vectors: if @var{OFF} is 0, then the returned vector is
-@var{v2}; otherwise, the returned vector is composed from the last
-@var{VS}-@var{OFF} elements of @var{v1} concatenated to the first
-@var{OFF} elements of @var{v2}.
-
-If this hook is defined, the autovectorizer will generate a call
-to @var{f} (using the DECL tree that this hook returns) and will
-use the return value of @var{f} as the argument @var{OFF} to
-@code{REALIGN_LOAD}. Therefore, the mask @var{m} returned by @var{f}
-should comply with the semantics expected by @code{REALIGN_LOAD}
-described above.
-If this hook is not defined, then @var{addr} will be used as
-the argument @var{OFF} to @code{REALIGN_LOAD}, in which case the low
-log2(@var{VS}) @minus{} 1 bits of @var{addr} will be considered.
-@end deftypefn
-
-@deftypefn {Target Hook} int TARGET_VECTORIZE_BUILTIN_VECTORIZATION_COST (enum vect_cost_for_stmt @var{type_of_cost}, tree @var{vectype}, int @var{misalign})
-Returns cost of different scalar or vector statements for vectorization cost model.
-For vector memory operations the cost may depend on type (@var{vectype}) and
-misalignment value (@var{misalign}).
-@end deftypefn
-
-@deftypefn {Target Hook} poly_uint64 TARGET_VECTORIZE_PREFERRED_VECTOR_ALIGNMENT (const_tree @var{type})
-This hook returns the preferred alignment in bits for accesses to
-vectors of type @var{type} in vectorized code. This might be less than
-or greater than the ABI-defined value returned by
-@code{TARGET_VECTOR_ALIGNMENT}. It can be equal to the alignment of
-a single element, in which case the vectorizer will not try to optimize
-for alignment.
-
-The default hook returns @code{TYPE_ALIGN (@var{type})}, which is
-correct for most targets.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_VECTORIZE_VECTOR_ALIGNMENT_REACHABLE (const_tree @var{type}, bool @var{is_packed})
-Return true if vector alignment is reachable (by peeling N iterations)
-for the given scalar type @var{type}. @var{is_packed} is false if the scalar
-access using @var{type} is known to be naturally aligned.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_VECTORIZE_VEC_PERM_CONST (machine_mode @var{mode}, machine_mode @var{op_mode}, rtx @var{output}, rtx @var{in0}, rtx @var{in1}, const vec_perm_indices @var{&sel})
-This hook is used to test whether the target can permute up to two
-vectors of mode @var{op_mode} using the permutation vector @code{sel},
-producing a vector of mode @var{mode}. The hook is also used to emit such
-a permutation.
-
-When the hook is being used to test whether the target supports a permutation,
-@var{in0}, @var{in1}, and @var{out} are all null. When the hook is being used
-to emit a permutation, @var{in0} and @var{in1} are the source vectors of mode
-@var{op_mode} and @var{out} is the destination vector of mode @var{mode}.
-@var{in1} is the same as @var{in0} if @var{sel} describes a permutation on one
-vector instead of two.
-
-Return true if the operation is possible, emitting instructions for it
-if rtxes are provided.
-
-@cindex @code{vec_perm@var{m}} instruction pattern
-If the hook returns false for a mode with multibyte elements, GCC will
-try the equivalent byte operation. If that also fails, it will try forcing
-the selector into a register and using the @var{vec_perm@var{mode}}
-instruction pattern. There is no need for the hook to handle these two
-implementation approaches itself.
-@end deftypefn
-
-@deftypefn {Target Hook} tree TARGET_VECTORIZE_BUILTIN_VECTORIZED_FUNCTION (unsigned @var{code}, tree @var{vec_type_out}, tree @var{vec_type_in})
-This hook should return the decl of a function that implements the
-vectorized variant of the function with the @code{combined_fn} code
-@var{code} or @code{NULL_TREE} if such a function is not available.
-The return type of the vectorized function shall be of vector type
-@var{vec_type_out} and the argument types should be @var{vec_type_in}.
-@end deftypefn
-
-@deftypefn {Target Hook} tree TARGET_VECTORIZE_BUILTIN_MD_VECTORIZED_FUNCTION (tree @var{fndecl}, tree @var{vec_type_out}, tree @var{vec_type_in})
-This hook should return the decl of a function that implements the
-vectorized variant of target built-in function @code{fndecl}. The
-return type of the vectorized function shall be of vector type
-@var{vec_type_out} and the argument types should be @var{vec_type_in}.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_VECTORIZE_SUPPORT_VECTOR_MISALIGNMENT (machine_mode @var{mode}, const_tree @var{type}, int @var{misalignment}, bool @var{is_packed})
-This hook should return true if the target supports misaligned vector
-store/load of a specific factor denoted in the @var{misalignment}
-parameter. The vector store/load should be of machine mode @var{mode} and
-the elements in the vectors should be of type @var{type}. @var{is_packed}
-parameter is true if the memory access is defined in a packed struct.
-@end deftypefn
-
-@deftypefn {Target Hook} machine_mode TARGET_VECTORIZE_PREFERRED_SIMD_MODE (scalar_mode @var{mode})
-This hook should return the preferred mode for vectorizing scalar
-mode @var{mode}. The default is
-equal to @code{word_mode}, because the vectorizer can do some
-transformations even in absence of specialized @acronym{SIMD} hardware.
-@end deftypefn
-
-@deftypefn {Target Hook} machine_mode TARGET_VECTORIZE_SPLIT_REDUCTION (machine_mode)
-This hook should return the preferred mode to split the final reduction
-step on @var{mode} to. The reduction is then carried out reducing upper
-against lower halves of vectors recursively until the specified mode is
-reached. The default is @var{mode} which means no splitting.
-@end deftypefn
-
-@deftypefn {Target Hook} {unsigned int} TARGET_VECTORIZE_AUTOVECTORIZE_VECTOR_MODES (vector_modes *@var{modes}, bool @var{all})
-If using the mode returned by @code{TARGET_VECTORIZE_PREFERRED_SIMD_MODE}
-is not the only approach worth considering, this hook should add one mode to
-@var{modes} for each useful alternative approach. These modes are then
-passed to @code{TARGET_VECTORIZE_RELATED_MODE} to obtain the vector mode
-for a given element mode.
-
-The modes returned in @var{modes} should use the smallest element mode
-possible for the vectorization approach that they represent, preferring
-integer modes over floating-poing modes in the event of a tie. The first
-mode should be the @code{TARGET_VECTORIZE_PREFERRED_SIMD_MODE} for its
-element mode.
-
-If @var{all} is true, add suitable vector modes even when they are generally
-not expected to be worthwhile.
-
-The hook returns a bitmask of flags that control how the modes in
-@var{modes} are used. The flags are:
-@table @code
-@item VECT_COMPARE_COSTS
-Tells the loop vectorizer to try all the provided modes and pick the one
-with the lowest cost. By default the vectorizer will choose the first
-mode that works.
-@end table
-
-The hook does not need to do anything if the vector returned by
-@code{TARGET_VECTORIZE_PREFERRED_SIMD_MODE} is the only one relevant
-for autovectorization. The default implementation adds no modes and
-returns 0.
-@end deftypefn
-
-@deftypefn {Target Hook} opt_machine_mode TARGET_VECTORIZE_RELATED_MODE (machine_mode @var{vector_mode}, scalar_mode @var{element_mode}, poly_uint64 @var{nunits})
-If a piece of code is using vector mode @var{vector_mode} and also wants
-to operate on elements of mode @var{element_mode}, return the vector mode
-it should use for those elements. If @var{nunits} is nonzero, ensure that
-the mode has exactly @var{nunits} elements, otherwise pick whichever vector
-size pairs the most naturally with @var{vector_mode}. Return an empty
-@code{opt_machine_mode} if there is no supported vector mode with the
-required properties.
-
-There is no prescribed way of handling the case in which @var{nunits}
-is zero. One common choice is to pick a vector mode with the same size
-as @var{vector_mode}; this is the natural choice if the target has a
-fixed vector size. Another option is to choose a vector mode with the
-same number of elements as @var{vector_mode}; this is the natural choice
-if the target has a fixed number of elements. Alternatively, the hook
-might choose a middle ground, such as trying to keep the number of
-elements as similar as possible while applying maximum and minimum
-vector sizes.
-
-The default implementation uses @code{mode_for_vector} to find the
-requested mode, returning a mode with the same size as @var{vector_mode}
-when @var{nunits} is zero. This is the correct behavior for most targets.
-@end deftypefn
-
-@deftypefn {Target Hook} opt_machine_mode TARGET_VECTORIZE_GET_MASK_MODE (machine_mode @var{mode})
-Return the mode to use for a vector mask that holds one boolean
-result for each element of vector mode @var{mode}. The returned mask mode
-can be a vector of integers (class @code{MODE_VECTOR_INT}), a vector of
-booleans (class @code{MODE_VECTOR_BOOL}) or a scalar integer (class
-@code{MODE_INT}). Return an empty @code{opt_machine_mode} if no such
-mask mode exists.
-
-The default implementation returns a @code{MODE_VECTOR_INT} with the
-same size and number of elements as @var{mode}, if such a mode exists.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_VECTORIZE_EMPTY_MASK_IS_EXPENSIVE (unsigned @var{ifn})
-This hook returns true if masked internal function @var{ifn} (really of
-type @code{internal_fn}) should be considered expensive when the mask is
-all zeros. GCC can then try to branch around the instruction instead.
-@end deftypefn
-
-@deftypefn {Target Hook} {class vector_costs *} TARGET_VECTORIZE_CREATE_COSTS (vec_info *@var{vinfo}, bool @var{costing_for_scalar})
-This hook should initialize target-specific data structures in preparation
-for modeling the costs of vectorizing a loop or basic block. The default
-allocates three unsigned integers for accumulating costs for the prologue,
-body, and epilogue of the loop or basic block. If @var{loop_info} is
-non-NULL, it identifies the loop being vectorized; otherwise a single block
-is being vectorized. If @var{costing_for_scalar} is true, it indicates the
-current cost model is for the scalar version of a loop or block; otherwise
-it is for the vector version.
-@end deftypefn
-
-@deftypefn {Target Hook} tree TARGET_VECTORIZE_BUILTIN_GATHER (const_tree @var{mem_vectype}, const_tree @var{index_type}, int @var{scale})
-Target builtin that implements vector gather operation. @var{mem_vectype}
-is the vector type of the load and @var{index_type} is scalar type of
-the index, scaled by @var{scale}.
-The default is @code{NULL_TREE} which means to not vectorize gather
-loads.
-@end deftypefn
-
-@deftypefn {Target Hook} tree TARGET_VECTORIZE_BUILTIN_SCATTER (const_tree @var{vectype}, const_tree @var{index_type}, int @var{scale})
-Target builtin that implements vector scatter operation. @var{vectype}
-is the vector type of the store and @var{index_type} is scalar type of
-the index, scaled by @var{scale}.
-The default is @code{NULL_TREE} which means to not vectorize scatter
-stores.
-@end deftypefn
-
-@deftypefn {Target Hook} int TARGET_SIMD_CLONE_COMPUTE_VECSIZE_AND_SIMDLEN (struct cgraph_node *@var{}, struct cgraph_simd_clone *@var{}, @var{tree}, @var{int})
-This hook should set @var{vecsize_mangle}, @var{vecsize_int}, @var{vecsize_float}
-fields in @var{simd_clone} structure pointed by @var{clone_info} argument and also
-@var{simdlen} field if it was previously 0.
-@var{vecsize_mangle} is a marker for the backend only. @var{vecsize_int} and
-@var{vecsize_float} should be left zero on targets where the number of lanes is
-not determined by the bitsize (in which case @var{simdlen} is always used).
-The hook should return 0 if SIMD clones shouldn't be emitted,
-or number of @var{vecsize_mangle} variants that should be emitted.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_SIMD_CLONE_ADJUST (struct cgraph_node *@var{})
-This hook should add implicit @code{attribute(target("..."))} attribute
-to SIMD clone @var{node} if needed.
-@end deftypefn
-
-@deftypefn {Target Hook} int TARGET_SIMD_CLONE_USABLE (struct cgraph_node *@var{})
-This hook should return -1 if SIMD clone @var{node} shouldn't be used
-in vectorized loops in current function, or non-negative number if it is
-usable. In that case, the smaller the number is, the more desirable it is
-to use it.
-@end deftypefn
-
-@deftypefn {Target Hook} int TARGET_SIMT_VF (void)
-Return number of threads in SIMT thread group on the target.
-@end deftypefn
-
-@deftypefn {Target Hook} int TARGET_OMP_DEVICE_KIND_ARCH_ISA (enum omp_device_kind_arch_isa @var{trait}, const char *@var{name})
-Return 1 if @var{trait} @var{name} is present in the OpenMP context's
-device trait set, return 0 if not present in any OpenMP context in the
-whole translation unit, or -1 if not present in the current OpenMP context
-but might be present in another OpenMP context in the same TU.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_GOACC_VALIDATE_DIMS (tree @var{decl}, int *@var{dims}, int @var{fn_level}, unsigned @var{used})
-This hook should check the launch dimensions provided for an OpenACC
-compute region, or routine. Defaulted values are represented as -1
-and non-constant values as 0. The @var{fn_level} is negative for the
-function corresponding to the compute region. For a routine it is the
-outermost level at which partitioned execution may be spawned. The hook
-should verify non-default values. If DECL is NULL, global defaults
-are being validated and unspecified defaults should be filled in.
-Diagnostics should be issued as appropriate. Return
-true, if changes have been made. You must override this hook to
-provide dimensions larger than 1.
-@end deftypefn
-
-@deftypefn {Target Hook} int TARGET_GOACC_DIM_LIMIT (int @var{axis})
-This hook should return the maximum size of a particular dimension,
-or zero if unbounded.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_GOACC_FORK_JOIN (gcall *@var{call}, const int *@var{dims}, bool @var{is_fork})
-This hook can be used to convert IFN_GOACC_FORK and IFN_GOACC_JOIN
-function calls to target-specific gimple, or indicate whether they
-should be retained. It is executed during the oacc_device_lower pass.
-It should return true, if the call should be retained. It should
-return false, if it is to be deleted (either because target-specific
-gimple has been inserted before it, or there is no need for it).
-The default hook returns false, if there are no RTL expanders for them.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_GOACC_REDUCTION (gcall *@var{call})
-This hook is used by the oacc_transform pass to expand calls to the
-@var{GOACC_REDUCTION} internal function, into a sequence of gimple
-instructions. @var{call} is gimple statement containing the call to
-the function. This hook removes statement @var{call} after the
-expanded sequence has been inserted. This hook is also responsible
-for allocating any storage for reductions when necessary.
-@end deftypefn
-
-@deftypefn {Target Hook} tree TARGET_PREFERRED_ELSE_VALUE (unsigned @var{ifn}, tree @var{type}, unsigned @var{nops}, tree *@var{ops})
-This hook returns the target's preferred final argument for a call
-to conditional internal function @var{ifn} (really of type
-@code{internal_fn}). @var{type} specifies the return type of the
-function and @var{ops} are the operands to the conditional operation,
-of which there are @var{nops}.
-
-For example, if @var{ifn} is @code{IFN_COND_ADD}, the hook returns
-a value of type @var{type} that should be used when @samp{@var{ops}[0]}
-and @samp{@var{ops}[1]} are conditionally added together.
-
-This hook is only relevant if the target supports conditional patterns
-like @code{cond_add@var{m}}. The default implementation returns a zero
-constant of type @var{type}.
-@end deftypefn
-
-@deftypefn {Target Hook} tree TARGET_GOACC_ADJUST_PRIVATE_DECL (location_t @var{loc}, tree @var{var}, int @var{level})
-This hook, if defined, is used by accelerator target back-ends to adjust
-OpenACC variable declarations that should be made private to the given
-parallelism level (i.e. @code{GOMP_DIM_GANG}, @code{GOMP_DIM_WORKER} or
-@code{GOMP_DIM_VECTOR}). A typical use for this hook is to force variable
-declarations at the @code{gang} level to reside in GPU shared memory.
-@var{loc} may be used for diagnostic purposes.
-
-You may also use the @code{TARGET_GOACC_EXPAND_VAR_DECL} hook if the
-adjusted variable declaration needs to be expanded to RTL in a non-standard
-way.
-@end deftypefn
-
-@deftypefn {Target Hook} rtx TARGET_GOACC_EXPAND_VAR_DECL (tree @var{var})
-This hook, if defined, is used by accelerator target back-ends to expand
-specially handled kinds of @code{VAR_DECL} expressions. A particular use is
-to place variables with specific attributes inside special accelarator
-memories. A return value of @code{NULL} indicates that the target does not
-handle this @code{VAR_DECL}, and normal RTL expanding is resumed.
-
-Only define this hook if your accelerator target needs to expand certain
-@code{VAR_DECL} nodes in a way that differs from the default. You can also adjust
-private variables at OpenACC device-lowering time using the
-@code{TARGET_GOACC_ADJUST_PRIVATE_DECL} target hook.
-@end deftypefn
-
-@deftypefn {Target Hook} tree TARGET_GOACC_CREATE_WORKER_BROADCAST_RECORD (tree @var{rec}, bool @var{sender}, const char *@var{name}, unsigned HOST_WIDE_INT @var{offset})
-Create a record used to propagate local-variable state from an active
-worker to other workers. A possible implementation might adjust the type
-of REC to place the new variable in shared GPU memory.
-
-Presence of this target hook indicates that middle end neutering/broadcasting
-be used.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_GOACC_SHARED_MEM_LAYOUT (unsigned HOST_WIDE_INT *@var{}, unsigned HOST_WIDE_INT *@var{}, @var{int[]}, unsigned @var{HOST_WIDE_INT[]}, unsigned @var{HOST_WIDE_INT[]})
-Lay out a fixed shared-memory region on the target. The LO and HI
-arguments should be set to a range of addresses that can be used for worker
-broadcasting. The dimensions, reduction size and gang-private size
-arguments are for the current offload region.
-@end deftypefn
-
-@node Anchored Addresses
-@section Anchored Addresses
-@cindex anchored addresses
-@cindex @option{-fsection-anchors}
-
-GCC usually addresses every static object as a separate entity.
-For example, if we have:
-
-@smallexample
-static int a, b, c;
-int foo (void) @{ return a + b + c; @}
-@end smallexample
-
-the code for @code{foo} will usually calculate three separate symbolic
-addresses: those of @code{a}, @code{b} and @code{c}. On some targets,
-it would be better to calculate just one symbolic address and access
-the three variables relative to it. The equivalent pseudocode would
-be something like:
-
-@smallexample
-int foo (void)
-@{
- register int *xr = &x;
- return xr[&a - &x] + xr[&b - &x] + xr[&c - &x];
-@}
-@end smallexample
-
-(which isn't valid C). We refer to shared addresses like @code{x} as
-``section anchors''. Their use is controlled by @option{-fsection-anchors}.
-
-The hooks below describe the target properties that GCC needs to know
-in order to make effective use of section anchors. It won't use
-section anchors at all unless either @code{TARGET_MIN_ANCHOR_OFFSET}
-or @code{TARGET_MAX_ANCHOR_OFFSET} is set to a nonzero value.
-
-@deftypevr {Target Hook} HOST_WIDE_INT TARGET_MIN_ANCHOR_OFFSET
-The minimum offset that should be applied to a section anchor.
-On most targets, it should be the smallest offset that can be
-applied to a base register while still giving a legitimate address
-for every mode. The default value is 0.
-@end deftypevr
-
-@deftypevr {Target Hook} HOST_WIDE_INT TARGET_MAX_ANCHOR_OFFSET
-Like @code{TARGET_MIN_ANCHOR_OFFSET}, but the maximum (inclusive)
-offset that should be applied to section anchors. The default
-value is 0.
-@end deftypevr
-
-@deftypefn {Target Hook} void TARGET_ASM_OUTPUT_ANCHOR (rtx @var{x})
-Write the assembly code to define section anchor @var{x}, which is a
-@code{SYMBOL_REF} for which @samp{SYMBOL_REF_ANCHOR_P (@var{x})} is true.
-The hook is called with the assembly output position set to the beginning
-of @code{SYMBOL_REF_BLOCK (@var{x})}.
-
-If @code{ASM_OUTPUT_DEF} is available, the hook's default definition uses
-it to define the symbol as @samp{. + SYMBOL_REF_BLOCK_OFFSET (@var{x})}.
-If @code{ASM_OUTPUT_DEF} is not available, the hook's default definition
-is @code{NULL}, which disables the use of section anchors altogether.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_USE_ANCHORS_FOR_SYMBOL_P (const_rtx @var{x})
-Return true if GCC should attempt to use anchors to access @code{SYMBOL_REF}
-@var{x}. You can assume @samp{SYMBOL_REF_HAS_BLOCK_INFO_P (@var{x})} and
-@samp{!SYMBOL_REF_ANCHOR_P (@var{x})}.
-
-The default version is correct for most targets, but you might need to
-intercept this hook to handle things like target-specific attributes
-or target-specific sections.
-@end deftypefn
-
-@node Condition Code
-@section Condition Code Status
-@cindex condition code status
-
-Condition codes in GCC are represented as registers,
-which provides better schedulability for
-architectures that do have a condition code register, but on which
-most instructions do not affect it. The latter category includes
-most RISC machines.
-
-Implicit clobbering would pose a strong restriction on the placement of
-the definition and use of the condition code. In the past the definition
-and use were always adjacent. However, recent changes to support trapping
-arithmetic may result in the definition and user being in different blocks.
-Thus, there may be a @code{NOTE_INSN_BASIC_BLOCK} between them. Additionally,
-the definition may be the source of exception handling edges.
-
-These restrictions can prevent important
-optimizations on some machines. For example, on the IBM RS/6000, there
-is a delay for taken branches unless the condition code register is set
-three instructions earlier than the conditional branch. The instruction
-scheduler cannot perform this optimization if it is not permitted to
-separate the definition and use of the condition code register.
-
-If there is a specific
-condition code register in the machine, use a hard register. If the
-condition code or comparison result can be placed in any general register,
-or if there are multiple condition registers, use a pseudo register.
-Registers used to store the condition code value will usually have a mode
-that is in class @code{MODE_CC}.
-
-Alternatively, you can use @code{BImode} if the comparison operator is
-specified already in the compare instruction. In this case, you are not
-interested in most macros in this section.
-
-@menu
-* MODE_CC Condition Codes:: Modern representation of condition codes.
-@end menu
-
-@node MODE_CC Condition Codes
-@subsection Representation of condition codes using registers
-@findex CCmode
-@findex MODE_CC
-
-@defmac SELECT_CC_MODE (@var{op}, @var{x}, @var{y})
-On many machines, the condition code may be produced by other instructions
-than compares, for example the branch can use directly the condition
-code set by a subtract instruction. However, on some machines
-when the condition code is set this way some bits (such as the overflow
-bit) are not set in the same way as a test instruction, so that a different
-branch instruction must be used for some conditional branches. When
-this happens, use the machine mode of the condition code register to
-record different formats of the condition code register. Modes can
-also be used to record which compare instruction (e.g.@: a signed or an
-unsigned comparison) produced the condition codes.
-
-If other modes than @code{CCmode} are required, add them to
-@file{@var{machine}-modes.def} and define @code{SELECT_CC_MODE} to choose
-a mode given an operand of a compare. This is needed because the modes
-have to be chosen not only during RTL generation but also, for example,
-by instruction combination. The result of @code{SELECT_CC_MODE} should
-be consistent with the mode used in the patterns; for example to support
-the case of the add on the SPARC discussed above, we have the pattern
-
-@smallexample
-(define_insn ""
- [(set (reg:CCNZ 0)
- (compare:CCNZ
- (plus:SI (match_operand:SI 0 "register_operand" "%r")
- (match_operand:SI 1 "arith_operand" "rI"))
- (const_int 0)))]
- ""
- "@dots{}")
-@end smallexample
-
-@noindent
-together with a @code{SELECT_CC_MODE} that returns @code{CCNZmode}
-for comparisons whose argument is a @code{plus}:
-
-@smallexample
-#define SELECT_CC_MODE(OP,X,Y) \
- (GET_MODE_CLASS (GET_MODE (X)) == MODE_FLOAT \
- ? ((OP == LT || OP == LE || OP == GT || OP == GE) \
- ? CCFPEmode : CCFPmode) \
- : ((GET_CODE (X) == PLUS || GET_CODE (X) == MINUS \
- || GET_CODE (X) == NEG || GET_CODE (x) == ASHIFT) \
- ? CCNZmode : CCmode))
-@end smallexample
-
-Another reason to use modes is to retain information on which operands
-were used by the comparison; see @code{REVERSIBLE_CC_MODE} later in
-this section.
-
-You should define this macro if and only if you define extra CC modes
-in @file{@var{machine}-modes.def}.
-@end defmac
-
-@deftypefn {Target Hook} void TARGET_CANONICALIZE_COMPARISON (int *@var{code}, rtx *@var{op0}, rtx *@var{op1}, bool @var{op0_preserve_value})
-On some machines not all possible comparisons are defined, but you can
-convert an invalid comparison into a valid one. For example, the Alpha
-does not have a @code{GT} comparison, but you can use an @code{LT}
-comparison instead and swap the order of the operands.
-
-On such machines, implement this hook to do any required conversions.
-@var{code} is the initial comparison code and @var{op0} and @var{op1}
-are the left and right operands of the comparison, respectively. If
-@var{op0_preserve_value} is @code{true} the implementation is not
-allowed to change the value of @var{op0} since the value might be used
-in RTXs which aren't comparisons. E.g. the implementation is not
-allowed to swap operands in that case.
-
-GCC will not assume that the comparison resulting from this macro is
-valid but will see if the resulting insn matches a pattern in the
-@file{md} file.
-
-You need not to implement this hook if it would never change the
-comparison code or operands.
-@end deftypefn
-
-@defmac REVERSIBLE_CC_MODE (@var{mode})
-A C expression whose value is one if it is always safe to reverse a
-comparison whose mode is @var{mode}. If @code{SELECT_CC_MODE}
-can ever return @var{mode} for a floating-point inequality comparison,
-then @code{REVERSIBLE_CC_MODE (@var{mode})} must be zero.
-
-You need not define this macro if it would always returns zero or if the
-floating-point format is anything other than @code{IEEE_FLOAT_FORMAT}.
-For example, here is the definition used on the SPARC, where floating-point
-inequality comparisons are given either @code{CCFPEmode} or @code{CCFPmode}:
-
-@smallexample
-#define REVERSIBLE_CC_MODE(MODE) \
- ((MODE) != CCFPEmode && (MODE) != CCFPmode)
-@end smallexample
-@end defmac
-
-@defmac REVERSE_CONDITION (@var{code}, @var{mode})
-A C expression whose value is reversed condition code of the @var{code} for
-comparison done in CC_MODE @var{mode}. The macro is used only in case
-@code{REVERSIBLE_CC_MODE (@var{mode})} is nonzero. Define this macro in case
-machine has some non-standard way how to reverse certain conditionals. For
-instance in case all floating point conditions are non-trapping, compiler may
-freely convert unordered compares to ordered ones. Then definition may look
-like:
-
-@smallexample
-#define REVERSE_CONDITION(CODE, MODE) \
- ((MODE) != CCFPmode ? reverse_condition (CODE) \
- : reverse_condition_maybe_unordered (CODE))
-@end smallexample
-@end defmac
-
-@deftypefn {Target Hook} bool TARGET_FIXED_CONDITION_CODE_REGS (unsigned int *@var{p1}, unsigned int *@var{p2})
-On targets which use a hard
-register rather than a pseudo-register to hold condition codes, the
-regular CSE passes are often not able to identify cases in which the
-hard register is set to a common value. Use this hook to enable a
-small pass which optimizes such cases. This hook should return true
-to enable this pass, and it should set the integers to which its
-arguments point to the hard register numbers used for condition codes.
-When there is only one such register, as is true on most systems, the
-integer pointed to by @var{p2} should be set to
-@code{INVALID_REGNUM}.
-
-The default version of this hook returns false.
-@end deftypefn
-
-@deftypefn {Target Hook} machine_mode TARGET_CC_MODES_COMPATIBLE (machine_mode @var{m1}, machine_mode @var{m2})
-On targets which use multiple condition code modes in class
-@code{MODE_CC}, it is sometimes the case that a comparison can be
-validly done in more than one mode. On such a system, define this
-target hook to take two mode arguments and to return a mode in which
-both comparisons may be validly done. If there is no such mode,
-return @code{VOIDmode}.
-
-The default version of this hook checks whether the modes are the
-same. If they are, it returns that mode. If they are different, it
-returns @code{VOIDmode}.
-@end deftypefn
-
-@deftypevr {Target Hook} {unsigned int} TARGET_FLAGS_REGNUM
-If the target has a dedicated flags register, and it needs to use the
-post-reload comparison elimination pass, or the delay slot filler pass,
-then this value should be set appropriately.
-@end deftypevr
-
-@node Costs
-@section Describing Relative Costs of Operations
-@cindex costs of instructions
-@cindex relative costs
-@cindex speed of instructions
-
-These macros let you describe the relative speed of various operations
-on the target machine.
-
-@defmac REGISTER_MOVE_COST (@var{mode}, @var{from}, @var{to})
-A C expression for the cost of moving data of mode @var{mode} from a
-register in class @var{from} to one in class @var{to}. The classes are
-expressed using the enumeration values such as @code{GENERAL_REGS}. A
-value of 2 is the default; other values are interpreted relative to
-that.
-
-It is not required that the cost always equal 2 when @var{from} is the
-same as @var{to}; on some machines it is expensive to move between
-registers if they are not general registers.
-
-If reload sees an insn consisting of a single @code{set} between two
-hard registers, and if @code{REGISTER_MOVE_COST} applied to their
-classes returns a value of 2, reload does not check to ensure that the
-constraints of the insn are met. Setting a cost of other than 2 will
-allow reload to verify that the constraints are met. You should do this
-if the @samp{mov@var{m}} pattern's constraints do not allow such copying.
-
-These macros are obsolete, new ports should use the target hook
-@code{TARGET_REGISTER_MOVE_COST} instead.
-@end defmac
-
-@deftypefn {Target Hook} int TARGET_REGISTER_MOVE_COST (machine_mode @var{mode}, reg_class_t @var{from}, reg_class_t @var{to})
-This target hook should return the cost of moving data of mode @var{mode}
-from a register in class @var{from} to one in class @var{to}. The classes
-are expressed using the enumeration values such as @code{GENERAL_REGS}.
-A value of 2 is the default; other values are interpreted relative to
-that.
-
-It is not required that the cost always equal 2 when @var{from} is the
-same as @var{to}; on some machines it is expensive to move between
-registers if they are not general registers.
-
-If reload sees an insn consisting of a single @code{set} between two
-hard registers, and if @code{TARGET_REGISTER_MOVE_COST} applied to their
-classes returns a value of 2, reload does not check to ensure that the
-constraints of the insn are met. Setting a cost of other than 2 will
-allow reload to verify that the constraints are met. You should do this
-if the @samp{mov@var{m}} pattern's constraints do not allow such copying.
-
-The default version of this function returns 2.
-@end deftypefn
-
-@defmac MEMORY_MOVE_COST (@var{mode}, @var{class}, @var{in})
-A C expression for the cost of moving data of mode @var{mode} between a
-register of class @var{class} and memory; @var{in} is zero if the value
-is to be written to memory, nonzero if it is to be read in. This cost
-is relative to those in @code{REGISTER_MOVE_COST}. If moving between
-registers and memory is more expensive than between two registers, you
-should define this macro to express the relative cost.
-
-If you do not define this macro, GCC uses a default cost of 4 plus
-the cost of copying via a secondary reload register, if one is
-needed. If your machine requires a secondary reload register to copy
-between memory and a register of @var{class} but the reload mechanism is
-more complex than copying via an intermediate, define this macro to
-reflect the actual cost of the move.
-
-GCC defines the function @code{memory_move_secondary_cost} if
-secondary reloads are needed. It computes the costs due to copying via
-a secondary register. If your machine copies from memory using a
-secondary register in the conventional way but the default base value of
-4 is not correct for your machine, define this macro to add some other
-value to the result of that function. The arguments to that function
-are the same as to this macro.
-
-These macros are obsolete, new ports should use the target hook
-@code{TARGET_MEMORY_MOVE_COST} instead.
-@end defmac
-
-@deftypefn {Target Hook} int TARGET_MEMORY_MOVE_COST (machine_mode @var{mode}, reg_class_t @var{rclass}, bool @var{in})
-This target hook should return the cost of moving data of mode @var{mode}
-between a register of class @var{rclass} and memory; @var{in} is @code{false}
-if the value is to be written to memory, @code{true} if it is to be read in.
-This cost is relative to those in @code{TARGET_REGISTER_MOVE_COST}.
-If moving between registers and memory is more expensive than between two
-registers, you should add this target hook to express the relative cost.
-
-If you do not add this target hook, GCC uses a default cost of 4 plus
-the cost of copying via a secondary reload register, if one is
-needed. If your machine requires a secondary reload register to copy
-between memory and a register of @var{rclass} but the reload mechanism is
-more complex than copying via an intermediate, use this target hook to
-reflect the actual cost of the move.
-
-GCC defines the function @code{memory_move_secondary_cost} if
-secondary reloads are needed. It computes the costs due to copying via
-a secondary register. If your machine copies from memory using a
-secondary register in the conventional way but the default base value of
-4 is not correct for your machine, use this target hook to add some other
-value to the result of that function. The arguments to that function
-are the same as to this target hook.
-@end deftypefn
-
-@defmac BRANCH_COST (@var{speed_p}, @var{predictable_p})
-A C expression for the cost of a branch instruction. A value of 1 is
-the default; other values are interpreted relative to that. Parameter
-@var{speed_p} is true when the branch in question should be optimized
-for speed. When it is false, @code{BRANCH_COST} should return a value
-optimal for code size rather than performance. @var{predictable_p} is
-true for well-predicted branches. On many architectures the
-@code{BRANCH_COST} can be reduced then.
-@end defmac
-
-Here are additional macros which do not specify precise relative costs,
-but only that certain actions are more expensive than GCC would
-ordinarily expect.
-
-@defmac SLOW_BYTE_ACCESS
-Define this macro as a C expression which is nonzero if accessing less
-than a word of memory (i.e.@: a @code{char} or a @code{short}) is no
-faster than accessing a word of memory, i.e., if such access
-require more than one instruction or if there is no difference in cost
-between byte and (aligned) word loads.
-
-When this macro is not defined, the compiler will access a field by
-finding the smallest containing object; when it is defined, a fullword
-load will be used if alignment permits. Unless bytes accesses are
-faster than word accesses, using word accesses is preferable since it
-may eliminate subsequent memory access if subsequent accesses occur to
-other fields in the same word of the structure, but to different bytes.
-@end defmac
-
-@deftypefn {Target Hook} bool TARGET_SLOW_UNALIGNED_ACCESS (machine_mode @var{mode}, unsigned int @var{align})
-This hook returns true if memory accesses described by the
-@var{mode} and @var{alignment} parameters have a cost many times greater
-than aligned accesses, for example if they are emulated in a trap handler.
-This hook is invoked only for unaligned accesses, i.e.@: when
-@code{@var{alignment} < GET_MODE_ALIGNMENT (@var{mode})}.
-
-When this hook returns true, the compiler will act as if
-@code{STRICT_ALIGNMENT} were true when generating code for block
-moves. This can cause significantly more instructions to be produced.
-Therefore, do not make this hook return true if unaligned accesses only
-add a cycle or two to the time for a memory access.
-
-The hook must return true whenever @code{STRICT_ALIGNMENT} is true.
-The default implementation returns @code{STRICT_ALIGNMENT}.
-@end deftypefn
-
-@defmac MOVE_RATIO (@var{speed})
-The threshold of number of scalar memory-to-memory move insns, @emph{below}
-which a sequence of insns should be generated instead of a
-string move insn or a library call. Increasing the value will always
-make code faster, but eventually incurs high cost in increased code size.
-
-Note that on machines where the corresponding move insn is a
-@code{define_expand} that emits a sequence of insns, this macro counts
-the number of such sequences.
-
-The parameter @var{speed} is true if the code is currently being
-optimized for speed rather than size.
-
-If you don't define this, a reasonable default is used.
-@end defmac
-
-@deftypefn {Target Hook} bool TARGET_USE_BY_PIECES_INFRASTRUCTURE_P (unsigned HOST_WIDE_INT @var{size}, unsigned int @var{alignment}, enum by_pieces_operation @var{op}, bool @var{speed_p})
-GCC will attempt several strategies when asked to copy between
-two areas of memory, or to set, clear or store to memory, for example
-when copying a @code{struct}. The @code{by_pieces} infrastructure
-implements such memory operations as a sequence of load, store or move
-insns. Alternate strategies are to expand the
-@code{cpymem} or @code{setmem} optabs, to emit a library call, or to emit
-unit-by-unit, loop-based operations.
-
-This target hook should return true if, for a memory operation with a
-given @var{size} and @var{alignment}, using the @code{by_pieces}
-infrastructure is expected to result in better code generation.
-Both @var{size} and @var{alignment} are measured in terms of storage
-units.
-
-The parameter @var{op} is one of: @code{CLEAR_BY_PIECES},
-@code{MOVE_BY_PIECES}, @code{SET_BY_PIECES}, @code{STORE_BY_PIECES} or
-@code{COMPARE_BY_PIECES}. These describe the type of memory operation
-under consideration.
-
-The parameter @var{speed_p} is true if the code is currently being
-optimized for speed rather than size.
-
-Returning true for higher values of @var{size} can improve code generation
-for speed if the target does not provide an implementation of the
-@code{cpymem} or @code{setmem} standard names, if the @code{cpymem} or
-@code{setmem} implementation would be more expensive than a sequence of
-insns, or if the overhead of a library call would dominate that of
-the body of the memory operation.
-
-Returning true for higher values of @code{size} may also cause an increase
-in code size, for example where the number of insns emitted to perform a
-move would be greater than that of a library call.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_OVERLAP_OP_BY_PIECES_P (void)
-This target hook should return true if when the @code{by_pieces}
-infrastructure is used, an offset adjusted unaligned memory operation
-in the smallest integer mode for the last piece operation of a memory
-region can be generated to avoid doing more than one smaller operations.
-@end deftypefn
-
-@deftypefn {Target Hook} int TARGET_COMPARE_BY_PIECES_BRANCH_RATIO (machine_mode @var{mode})
-When expanding a block comparison in MODE, gcc can try to reduce the
-number of branches at the expense of more memory operations. This hook
-allows the target to override the default choice. It should return the
-factor by which branches should be reduced over the plain expansion with
-one comparison per @var{mode}-sized piece. A port can also prevent a
-particular mode from being used for block comparisons by returning a
-negative number from this hook.
-@end deftypefn
-
-@defmac MOVE_MAX_PIECES
-A C expression used by @code{move_by_pieces} to determine the largest unit
-a load or store used to copy memory is. Defaults to @code{MOVE_MAX}.
-@end defmac
-
-@defmac STORE_MAX_PIECES
-A C expression used by @code{store_by_pieces} to determine the largest unit
-a store used to memory is. Defaults to @code{MOVE_MAX_PIECES}, or two times
-the size of @code{HOST_WIDE_INT}, whichever is smaller.
-@end defmac
-
-@defmac COMPARE_MAX_PIECES
-A C expression used by @code{compare_by_pieces} to determine the largest unit
-a load or store used to compare memory is. Defaults to
-@code{MOVE_MAX_PIECES}.
-@end defmac
-
-@defmac CLEAR_RATIO (@var{speed})
-The threshold of number of scalar move insns, @emph{below} which a sequence
-of insns should be generated to clear memory instead of a string clear insn
-or a library call. Increasing the value will always make code faster, but
-eventually incurs high cost in increased code size.
-
-The parameter @var{speed} is true if the code is currently being
-optimized for speed rather than size.
-
-If you don't define this, a reasonable default is used.
-@end defmac
-
-@defmac SET_RATIO (@var{speed})
-The threshold of number of scalar move insns, @emph{below} which a sequence
-of insns should be generated to set memory to a constant value, instead of
-a block set insn or a library call.
-Increasing the value will always make code faster, but
-eventually incurs high cost in increased code size.
-
-The parameter @var{speed} is true if the code is currently being
-optimized for speed rather than size.
-
-If you don't define this, it defaults to the value of @code{MOVE_RATIO}.
-@end defmac
-
-@defmac USE_LOAD_POST_INCREMENT (@var{mode})
-A C expression used to determine whether a load postincrement is a good
-thing to use for a given mode. Defaults to the value of
-@code{HAVE_POST_INCREMENT}.
-@end defmac
-
-@defmac USE_LOAD_POST_DECREMENT (@var{mode})
-A C expression used to determine whether a load postdecrement is a good
-thing to use for a given mode. Defaults to the value of
-@code{HAVE_POST_DECREMENT}.
-@end defmac
-
-@defmac USE_LOAD_PRE_INCREMENT (@var{mode})
-A C expression used to determine whether a load preincrement is a good
-thing to use for a given mode. Defaults to the value of
-@code{HAVE_PRE_INCREMENT}.
-@end defmac
-
-@defmac USE_LOAD_PRE_DECREMENT (@var{mode})
-A C expression used to determine whether a load predecrement is a good
-thing to use for a given mode. Defaults to the value of
-@code{HAVE_PRE_DECREMENT}.
-@end defmac
-
-@defmac USE_STORE_POST_INCREMENT (@var{mode})
-A C expression used to determine whether a store postincrement is a good
-thing to use for a given mode. Defaults to the value of
-@code{HAVE_POST_INCREMENT}.
-@end defmac
-
-@defmac USE_STORE_POST_DECREMENT (@var{mode})
-A C expression used to determine whether a store postdecrement is a good
-thing to use for a given mode. Defaults to the value of
-@code{HAVE_POST_DECREMENT}.
-@end defmac
-
-@defmac USE_STORE_PRE_INCREMENT (@var{mode})
-This macro is used to determine whether a store preincrement is a good
-thing to use for a given mode. Defaults to the value of
-@code{HAVE_PRE_INCREMENT}.
-@end defmac
-
-@defmac USE_STORE_PRE_DECREMENT (@var{mode})
-This macro is used to determine whether a store predecrement is a good
-thing to use for a given mode. Defaults to the value of
-@code{HAVE_PRE_DECREMENT}.
-@end defmac
-
-@defmac NO_FUNCTION_CSE
-Define this macro to be true if it is as good or better to call a constant
-function address than to call an address kept in a register.
-@end defmac
-
-@defmac LOGICAL_OP_NON_SHORT_CIRCUIT
-Define this macro if a non-short-circuit operation produced by
-@samp{fold_range_test ()} is optimal. This macro defaults to true if
-@code{BRANCH_COST} is greater than or equal to the value 2.
-@end defmac
-
-@deftypefn {Target Hook} bool TARGET_OPTAB_SUPPORTED_P (int @var{op}, machine_mode @var{mode1}, machine_mode @var{mode2}, optimization_type @var{opt_type})
-Return true if the optimizers should use optab @var{op} with
-modes @var{mode1} and @var{mode2} for optimization type @var{opt_type}.
-The optab is known to have an associated @file{.md} instruction
-whose C condition is true. @var{mode2} is only meaningful for conversion
-optabs; for direct optabs it is a copy of @var{mode1}.
-
-For example, when called with @var{op} equal to @code{rint_optab} and
-@var{mode1} equal to @code{DFmode}, the hook should say whether the
-optimizers should use optab @code{rintdf2}.
-
-The default hook returns true for all inputs.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_RTX_COSTS (rtx @var{x}, machine_mode @var{mode}, int @var{outer_code}, int @var{opno}, int *@var{total}, bool @var{speed})
-This target hook describes the relative costs of RTL expressions.
-
-The cost may depend on the precise form of the expression, which is
-available for examination in @var{x}, and the fact that @var{x} appears
-as operand @var{opno} of an expression with rtx code @var{outer_code}.
-That is, the hook can assume that there is some rtx @var{y} such
-that @samp{GET_CODE (@var{y}) == @var{outer_code}} and such that
-either (a) @samp{XEXP (@var{y}, @var{opno}) == @var{x}} or
-(b) @samp{XVEC (@var{y}, @var{opno})} contains @var{x}.
-
-@var{mode} is @var{x}'s machine mode, or for cases like @code{const_int} that
-do not have a mode, the mode in which @var{x} is used.
-
-In implementing this hook, you can use the construct
-@code{COSTS_N_INSNS (@var{n})} to specify a cost equal to @var{n} fast
-instructions.
-
-On entry to the hook, @code{*@var{total}} contains a default estimate
-for the cost of the expression. The hook should modify this value as
-necessary. Traditionally, the default costs are @code{COSTS_N_INSNS (5)}
-for multiplications, @code{COSTS_N_INSNS (7)} for division and modulus
-operations, and @code{COSTS_N_INSNS (1)} for all other operations.
-
-When optimizing for code size, i.e.@: when @code{speed} is
-false, this target hook should be used to estimate the relative
-size cost of an expression, again relative to @code{COSTS_N_INSNS}.
-
-The hook returns true when all subexpressions of @var{x} have been
-processed, and false when @code{rtx_cost} should recurse.
-@end deftypefn
-
-@deftypefn {Target Hook} int TARGET_ADDRESS_COST (rtx @var{address}, machine_mode @var{mode}, addr_space_t @var{as}, bool @var{speed})
-This hook computes the cost of an addressing mode that contains
-@var{address}. If not defined, the cost is computed from
-the @var{address} expression and the @code{TARGET_RTX_COST} hook.
-
-For most CISC machines, the default cost is a good approximation of the
-true cost of the addressing mode. However, on RISC machines, all
-instructions normally have the same length and execution time. Hence
-all addresses will have equal costs.
-
-In cases where more than one form of an address is known, the form with
-the lowest cost will be used. If multiple forms have the same, lowest,
-cost, the one that is the most complex will be used.
-
-For example, suppose an address that is equal to the sum of a register
-and a constant is used twice in the same basic block. When this macro
-is not defined, the address will be computed in a register and memory
-references will be indirect through that register. On machines where
-the cost of the addressing mode containing the sum is no higher than
-that of a simple indirect reference, this will produce an additional
-instruction and possibly require an additional register. Proper
-specification of this macro eliminates this overhead for such machines.
-
-This hook is never called with an invalid address.
-
-On machines where an address involving more than one register is as
-cheap as an address computation involving only one register, defining
-@code{TARGET_ADDRESS_COST} to reflect this can cause two registers to
-be live over a region of code where only one would have been if
-@code{TARGET_ADDRESS_COST} were not defined in that manner. This effect
-should be considered in the definition of this macro. Equivalent costs
-should probably only be given to addresses with different numbers of
-registers on machines with lots of registers.
-@end deftypefn
-
-@deftypefn {Target Hook} int TARGET_INSN_COST (rtx_insn *@var{insn}, bool @var{speed})
-This target hook describes the relative costs of RTL instructions.
-
-In implementing this hook, you can use the construct
-@code{COSTS_N_INSNS (@var{n})} to specify a cost equal to @var{n} fast
-instructions.
-
-When optimizing for code size, i.e.@: when @code{speed} is
-false, this target hook should be used to estimate the relative
-size cost of an expression, again relative to @code{COSTS_N_INSNS}.
-@end deftypefn
-
-@deftypefn {Target Hook} {unsigned int} TARGET_MAX_NOCE_IFCVT_SEQ_COST (edge @var{e})
-This hook returns a value in the same units as @code{TARGET_RTX_COSTS},
-giving the maximum acceptable cost for a sequence generated by the RTL
-if-conversion pass when conditional execution is not available.
-The RTL if-conversion pass attempts to convert conditional operations
-that would require a branch to a series of unconditional operations and
-@code{mov@var{mode}cc} insns. This hook returns the maximum cost of the
-unconditional instructions and the @code{mov@var{mode}cc} insns.
-RTL if-conversion is cancelled if the cost of the converted sequence
-is greater than the value returned by this hook.
-
-@code{e} is the edge between the basic block containing the conditional
-branch to the basic block which would be executed if the condition
-were true.
-
-The default implementation of this hook uses the
-@code{max-rtl-if-conversion-[un]predictable} parameters if they are set,
-and uses a multiple of @code{BRANCH_COST} otherwise.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_NOCE_CONVERSION_PROFITABLE_P (rtx_insn *@var{seq}, struct noce_if_info *@var{if_info})
-This hook returns true if the instruction sequence @code{seq} is a good
-candidate as a replacement for the if-convertible sequence described in
-@code{if_info}.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_NEW_ADDRESS_PROFITABLE_P (rtx @var{memref}, rtx_insn * @var{insn}, rtx @var{new_addr})
-Return @code{true} if it is profitable to replace the address in
-@var{memref} with @var{new_addr}. This allows targets to prevent the
-scheduler from undoing address optimizations. The instruction containing the
-memref is @var{insn}. The default implementation returns @code{true}.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_NO_SPECULATION_IN_DELAY_SLOTS_P (void)
-This predicate controls the use of the eager delay slot filler to disallow
-speculatively executed instructions being placed in delay slots. Targets
-such as certain MIPS architectures possess both branches with and without
-delay slots. As the eager delay slot filler can decrease performance,
-disabling it is beneficial when ordinary branches are available. Use of
-delay slot branches filled using the basic filler is often still desirable
-as the delay slot can hide a pipeline bubble.
-@end deftypefn
-
-@deftypefn {Target Hook} HOST_WIDE_INT TARGET_ESTIMATED_POLY_VALUE (poly_int64 @var{val}, poly_value_estimate_kind @var{kind})
-Return an estimate of the runtime value of @var{val}, for use in
-things like cost calculations or profiling frequencies. @var{kind} is used
-to ask for the minimum, maximum, and likely estimates of the value through
-the @code{POLY_VALUE_MIN}, @code{POLY_VALUE_MAX} and
-@code{POLY_VALUE_LIKELY} values. The default
-implementation returns the lowest possible value of @var{val}.
-@end deftypefn
-
-@node Scheduling
-@section Adjusting the Instruction Scheduler
-
-The instruction scheduler may need a fair amount of machine-specific
-adjustment in order to produce good code. GCC provides several target
-hooks for this purpose. It is usually enough to define just a few of
-them: try the first ones in this list first.
-
-@deftypefn {Target Hook} int TARGET_SCHED_ISSUE_RATE (void)
-This hook returns the maximum number of instructions that can ever
-issue at the same time on the target machine. The default is one.
-Although the insn scheduler can define itself the possibility of issue
-an insn on the same cycle, the value can serve as an additional
-constraint to issue insns on the same simulated processor cycle (see
-hooks @samp{TARGET_SCHED_REORDER} and @samp{TARGET_SCHED_REORDER2}).
-This value must be constant over the entire compilation. If you need
-it to vary depending on what the instructions are, you must use
-@samp{TARGET_SCHED_VARIABLE_ISSUE}.
-@end deftypefn
-
-@deftypefn {Target Hook} int TARGET_SCHED_VARIABLE_ISSUE (FILE *@var{file}, int @var{verbose}, rtx_insn *@var{insn}, int @var{more})
-This hook is executed by the scheduler after it has scheduled an insn
-from the ready list. It should return the number of insns which can
-still be issued in the current cycle. The default is
-@samp{@w{@var{more} - 1}} for insns other than @code{CLOBBER} and
-@code{USE}, which normally are not counted against the issue rate.
-You should define this hook if some insns take more machine resources
-than others, so that fewer insns can follow them in the same cycle.
-@var{file} is either a null pointer, or a stdio stream to write any
-debug output to. @var{verbose} is the verbose level provided by
-@option{-fsched-verbose-@var{n}}. @var{insn} is the instruction that
-was scheduled.
-@end deftypefn
-
-@deftypefn {Target Hook} int TARGET_SCHED_ADJUST_COST (rtx_insn *@var{insn}, int @var{dep_type1}, rtx_insn *@var{dep_insn}, int @var{cost}, unsigned int @var{dw})
-This function corrects the value of @var{cost} based on the
-relationship between @var{insn} and @var{dep_insn} through a
-dependence of type dep_type, and strength @var{dw}. It should return the new
-value. The default is to make no adjustment to @var{cost}. This can be
-used for example to specify to the scheduler using the traditional pipeline
-description that an output- or anti-dependence does not incur the same cost
-as a data-dependence. If the scheduler using the automaton based pipeline
-description, the cost of anti-dependence is zero and the cost of
-output-dependence is maximum of one and the difference of latency
-times of the first and the second insns. If these values are not
-acceptable, you could use the hook to modify them too. See also
-@pxref{Processor pipeline description}.
-@end deftypefn
-
-@deftypefn {Target Hook} int TARGET_SCHED_ADJUST_PRIORITY (rtx_insn *@var{insn}, int @var{priority})
-This hook adjusts the integer scheduling priority @var{priority} of
-@var{insn}. It should return the new priority. Increase the priority to
-execute @var{insn} earlier, reduce the priority to execute @var{insn}
-later. Do not define this hook if you do not need to adjust the
-scheduling priorities of insns.
-@end deftypefn
-
-@deftypefn {Target Hook} int TARGET_SCHED_REORDER (FILE *@var{file}, int @var{verbose}, rtx_insn **@var{ready}, int *@var{n_readyp}, int @var{clock})
-This hook is executed by the scheduler after it has scheduled the ready
-list, to allow the machine description to reorder it (for example to
-combine two small instructions together on @samp{VLIW} machines).
-@var{file} is either a null pointer, or a stdio stream to write any
-debug output to. @var{verbose} is the verbose level provided by
-@option{-fsched-verbose-@var{n}}. @var{ready} is a pointer to the ready
-list of instructions that are ready to be scheduled. @var{n_readyp} is
-a pointer to the number of elements in the ready list. The scheduler
-reads the ready list in reverse order, starting with
-@var{ready}[@var{*n_readyp} @minus{} 1] and going to @var{ready}[0]. @var{clock}
-is the timer tick of the scheduler. You may modify the ready list and
-the number of ready insns. The return value is the number of insns that
-can issue this cycle; normally this is just @code{issue_rate}. See also
-@samp{TARGET_SCHED_REORDER2}.
-@end deftypefn
-
-@deftypefn {Target Hook} int TARGET_SCHED_REORDER2 (FILE *@var{file}, int @var{verbose}, rtx_insn **@var{ready}, int *@var{n_readyp}, int @var{clock})
-Like @samp{TARGET_SCHED_REORDER}, but called at a different time. That
-function is called whenever the scheduler starts a new cycle. This one
-is called once per iteration over a cycle, immediately after
-@samp{TARGET_SCHED_VARIABLE_ISSUE}; it can reorder the ready list and
-return the number of insns to be scheduled in the same cycle. Defining
-this hook can be useful if there are frequent situations where
-scheduling one insn causes other insns to become ready in the same
-cycle. These other insns can then be taken into account properly.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_SCHED_MACRO_FUSION_P (void)
-This hook is used to check whether target platform supports macro fusion.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_SCHED_MACRO_FUSION_PAIR_P (rtx_insn *@var{prev}, rtx_insn *@var{curr})
-This hook is used to check whether two insns should be macro fused for
-a target microarchitecture. If this hook returns true for the given insn pair
-(@var{prev} and @var{curr}), the scheduler will put them into a sched
-group, and they will not be scheduled apart. The two insns will be either
-two SET insns or a compare and a conditional jump and this hook should
-validate any dependencies needed to fuse the two insns together.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_SCHED_DEPENDENCIES_EVALUATION_HOOK (rtx_insn *@var{head}, rtx_insn *@var{tail})
-This hook is called after evaluation forward dependencies of insns in
-chain given by two parameter values (@var{head} and @var{tail}
-correspondingly) but before insns scheduling of the insn chain. For
-example, it can be used for better insn classification if it requires
-analysis of dependencies. This hook can use backward and forward
-dependencies of the insn scheduler because they are already
-calculated.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_SCHED_INIT (FILE *@var{file}, int @var{verbose}, int @var{max_ready})
-This hook is executed by the scheduler at the beginning of each block of
-instructions that are to be scheduled. @var{file} is either a null
-pointer, or a stdio stream to write any debug output to. @var{verbose}
-is the verbose level provided by @option{-fsched-verbose-@var{n}}.
-@var{max_ready} is the maximum number of insns in the current scheduling
-region that can be live at the same time. This can be used to allocate
-scratch space if it is needed, e.g.@: by @samp{TARGET_SCHED_REORDER}.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_SCHED_FINISH (FILE *@var{file}, int @var{verbose})
-This hook is executed by the scheduler at the end of each block of
-instructions that are to be scheduled. It can be used to perform
-cleanup of any actions done by the other scheduling hooks. @var{file}
-is either a null pointer, or a stdio stream to write any debug output
-to. @var{verbose} is the verbose level provided by
-@option{-fsched-verbose-@var{n}}.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_SCHED_INIT_GLOBAL (FILE *@var{file}, int @var{verbose}, int @var{old_max_uid})
-This hook is executed by the scheduler after function level initializations.
-@var{file} is either a null pointer, or a stdio stream to write any debug output to.
-@var{verbose} is the verbose level provided by @option{-fsched-verbose-@var{n}}.
-@var{old_max_uid} is the maximum insn uid when scheduling begins.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_SCHED_FINISH_GLOBAL (FILE *@var{file}, int @var{verbose})
-This is the cleanup hook corresponding to @code{TARGET_SCHED_INIT_GLOBAL}.
-@var{file} is either a null pointer, or a stdio stream to write any debug output to.
-@var{verbose} is the verbose level provided by @option{-fsched-verbose-@var{n}}.
-@end deftypefn
-
-@deftypefn {Target Hook} rtx TARGET_SCHED_DFA_PRE_CYCLE_INSN (void)
-The hook returns an RTL insn. The automaton state used in the
-pipeline hazard recognizer is changed as if the insn were scheduled
-when the new simulated processor cycle starts. Usage of the hook may
-simplify the automaton pipeline description for some @acronym{VLIW}
-processors. If the hook is defined, it is used only for the automaton
-based pipeline description. The default is not to change the state
-when the new simulated processor cycle starts.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_SCHED_INIT_DFA_PRE_CYCLE_INSN (void)
-The hook can be used to initialize data used by the previous hook.
-@end deftypefn
-
-@deftypefn {Target Hook} {rtx_insn *} TARGET_SCHED_DFA_POST_CYCLE_INSN (void)
-The hook is analogous to @samp{TARGET_SCHED_DFA_PRE_CYCLE_INSN} but used
-to changed the state as if the insn were scheduled when the new
-simulated processor cycle finishes.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_SCHED_INIT_DFA_POST_CYCLE_INSN (void)
-The hook is analogous to @samp{TARGET_SCHED_INIT_DFA_PRE_CYCLE_INSN} but
-used to initialize data used by the previous hook.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_SCHED_DFA_PRE_ADVANCE_CYCLE (void)
-The hook to notify target that the current simulated cycle is about to finish.
-The hook is analogous to @samp{TARGET_SCHED_DFA_PRE_CYCLE_INSN} but used
-to change the state in more complicated situations - e.g., when advancing
-state on a single insn is not enough.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_SCHED_DFA_POST_ADVANCE_CYCLE (void)
-The hook to notify target that new simulated cycle has just started.
-The hook is analogous to @samp{TARGET_SCHED_DFA_POST_CYCLE_INSN} but used
-to change the state in more complicated situations - e.g., when advancing
-state on a single insn is not enough.
-@end deftypefn
-
-@deftypefn {Target Hook} int TARGET_SCHED_FIRST_CYCLE_MULTIPASS_DFA_LOOKAHEAD (void)
-This hook controls better choosing an insn from the ready insn queue
-for the @acronym{DFA}-based insn scheduler. Usually the scheduler
-chooses the first insn from the queue. If the hook returns a positive
-value, an additional scheduler code tries all permutations of
-@samp{TARGET_SCHED_FIRST_CYCLE_MULTIPASS_DFA_LOOKAHEAD ()}
-subsequent ready insns to choose an insn whose issue will result in
-maximal number of issued insns on the same cycle. For the
-@acronym{VLIW} processor, the code could actually solve the problem of
-packing simple insns into the @acronym{VLIW} insn. Of course, if the
-rules of @acronym{VLIW} packing are described in the automaton.
-
-This code also could be used for superscalar @acronym{RISC}
-processors. Let us consider a superscalar @acronym{RISC} processor
-with 3 pipelines. Some insns can be executed in pipelines @var{A} or
-@var{B}, some insns can be executed only in pipelines @var{B} or
-@var{C}, and one insn can be executed in pipeline @var{B}. The
-processor may issue the 1st insn into @var{A} and the 2nd one into
-@var{B}. In this case, the 3rd insn will wait for freeing @var{B}
-until the next cycle. If the scheduler issues the 3rd insn the first,
-the processor could issue all 3 insns per cycle.
-
-Actually this code demonstrates advantages of the automaton based
-pipeline hazard recognizer. We try quickly and easy many insn
-schedules to choose the best one.
-
-The default is no multipass scheduling.
-@end deftypefn
-
-@deftypefn {Target Hook} int TARGET_SCHED_FIRST_CYCLE_MULTIPASS_DFA_LOOKAHEAD_GUARD (rtx_insn *@var{insn}, int @var{ready_index})
-
-This hook controls what insns from the ready insn queue will be
-considered for the multipass insn scheduling. If the hook returns
-zero for @var{insn}, the insn will be considered in multipass scheduling.
-Positive return values will remove @var{insn} from consideration on
-the current round of multipass scheduling.
-Negative return values will remove @var{insn} from consideration for given
-number of cycles.
-Backends should be careful about returning non-zero for highest priority
-instruction at position 0 in the ready list. @var{ready_index} is passed
-to allow backends make correct judgements.
-
-The default is that any ready insns can be chosen to be issued.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_SCHED_FIRST_CYCLE_MULTIPASS_BEGIN (void *@var{data}, signed char *@var{ready_try}, int @var{n_ready}, bool @var{first_cycle_insn_p})
-This hook prepares the target backend for a new round of multipass
-scheduling.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_SCHED_FIRST_CYCLE_MULTIPASS_ISSUE (void *@var{data}, signed char *@var{ready_try}, int @var{n_ready}, rtx_insn *@var{insn}, const void *@var{prev_data})
-This hook is called when multipass scheduling evaluates instruction INSN.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_SCHED_FIRST_CYCLE_MULTIPASS_BACKTRACK (const void *@var{data}, signed char *@var{ready_try}, int @var{n_ready})
-This is called when multipass scheduling backtracks from evaluation of
-an instruction.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_SCHED_FIRST_CYCLE_MULTIPASS_END (const void *@var{data})
-This hook notifies the target about the result of the concluded current
-round of multipass scheduling.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_SCHED_FIRST_CYCLE_MULTIPASS_INIT (void *@var{data})
-This hook initializes target-specific data used in multipass scheduling.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_SCHED_FIRST_CYCLE_MULTIPASS_FINI (void *@var{data})
-This hook finalizes target-specific data used in multipass scheduling.
-@end deftypefn
-
-@deftypefn {Target Hook} int TARGET_SCHED_DFA_NEW_CYCLE (FILE *@var{dump}, int @var{verbose}, rtx_insn *@var{insn}, int @var{last_clock}, int @var{clock}, int *@var{sort_p})
-This hook is called by the insn scheduler before issuing @var{insn}
-on cycle @var{clock}. If the hook returns nonzero,
-@var{insn} is not issued on this processor cycle. Instead,
-the processor cycle is advanced. If *@var{sort_p}
-is zero, the insn ready queue is not sorted on the new cycle
-start as usually. @var{dump} and @var{verbose} specify the file and
-verbosity level to use for debugging output.
-@var{last_clock} and @var{clock} are, respectively, the
-processor cycle on which the previous insn has been issued,
-and the current processor cycle.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_SCHED_IS_COSTLY_DEPENDENCE (struct _dep *@var{_dep}, int @var{cost}, int @var{distance})
-This hook is used to define which dependences are considered costly by
-the target, so costly that it is not advisable to schedule the insns that
-are involved in the dependence too close to one another. The parameters
-to this hook are as follows: The first parameter @var{_dep} is the dependence
-being evaluated. The second parameter @var{cost} is the cost of the
-dependence as estimated by the scheduler, and the third
-parameter @var{distance} is the distance in cycles between the two insns.
-The hook returns @code{true} if considering the distance between the two
-insns the dependence between them is considered costly by the target,
-and @code{false} otherwise.
-
-Defining this hook can be useful in multiple-issue out-of-order machines,
-where (a) it's practically hopeless to predict the actual data/resource
-delays, however: (b) there's a better chance to predict the actual grouping
-that will be formed, and (c) correctly emulating the grouping can be very
-important. In such targets one may want to allow issuing dependent insns
-closer to one another---i.e., closer than the dependence distance; however,
-not in cases of ``costly dependences'', which this hooks allows to define.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_SCHED_H_I_D_EXTENDED (void)
-This hook is called by the insn scheduler after emitting a new instruction to
-the instruction stream. The hook notifies a target backend to extend its
-per instruction data structures.
-@end deftypefn
-
-@deftypefn {Target Hook} {void *} TARGET_SCHED_ALLOC_SCHED_CONTEXT (void)
-Return a pointer to a store large enough to hold target scheduling context.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_SCHED_INIT_SCHED_CONTEXT (void *@var{tc}, bool @var{clean_p})
-Initialize store pointed to by @var{tc} to hold target scheduling context.
-It @var{clean_p} is true then initialize @var{tc} as if scheduler is at the
-beginning of the block. Otherwise, copy the current context into @var{tc}.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_SCHED_SET_SCHED_CONTEXT (void *@var{tc})
-Copy target scheduling context pointed to by @var{tc} to the current context.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_SCHED_CLEAR_SCHED_CONTEXT (void *@var{tc})
-Deallocate internal data in target scheduling context pointed to by @var{tc}.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_SCHED_FREE_SCHED_CONTEXT (void *@var{tc})
-Deallocate a store for target scheduling context pointed to by @var{tc}.
-@end deftypefn
-
-@deftypefn {Target Hook} int TARGET_SCHED_SPECULATE_INSN (rtx_insn *@var{insn}, unsigned int @var{dep_status}, rtx *@var{new_pat})
-This hook is called by the insn scheduler when @var{insn} has only
-speculative dependencies and therefore can be scheduled speculatively.
-The hook is used to check if the pattern of @var{insn} has a speculative
-version and, in case of successful check, to generate that speculative
-pattern. The hook should return 1, if the instruction has a speculative form,
-or @minus{}1, if it doesn't. @var{request} describes the type of requested
-speculation. If the return value equals 1 then @var{new_pat} is assigned
-the generated speculative pattern.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_SCHED_NEEDS_BLOCK_P (unsigned int @var{dep_status})
-This hook is called by the insn scheduler during generation of recovery code
-for @var{insn}. It should return @code{true}, if the corresponding check
-instruction should branch to recovery code, or @code{false} otherwise.
-@end deftypefn
-
-@deftypefn {Target Hook} rtx TARGET_SCHED_GEN_SPEC_CHECK (rtx_insn *@var{insn}, rtx_insn *@var{label}, unsigned int @var{ds})
-This hook is called by the insn scheduler to generate a pattern for recovery
-check instruction. If @var{mutate_p} is zero, then @var{insn} is a
-speculative instruction for which the check should be generated.
-@var{label} is either a label of a basic block, where recovery code should
-be emitted, or a null pointer, when requested check doesn't branch to
-recovery code (a simple check). If @var{mutate_p} is nonzero, then
-a pattern for a branchy check corresponding to a simple check denoted by
-@var{insn} should be generated. In this case @var{label} can't be null.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_SCHED_SET_SCHED_FLAGS (struct spec_info_def *@var{spec_info})
-This hook is used by the insn scheduler to find out what features should be
-enabled/used.
-The structure *@var{spec_info} should be filled in by the target.
-The structure describes speculation types that can be used in the scheduler.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_SCHED_CAN_SPECULATE_INSN (rtx_insn *@var{insn})
-Some instructions should never be speculated by the schedulers, usually
- because the instruction is too expensive to get this wrong. Often such
- instructions have long latency, and often they are not fully modeled in the
- pipeline descriptions. This hook should return @code{false} if @var{insn}
- should not be speculated.
-@end deftypefn
-
-@deftypefn {Target Hook} int TARGET_SCHED_SMS_RES_MII (struct ddg *@var{g})
-This hook is called by the swing modulo scheduler to calculate a
-resource-based lower bound which is based on the resources available in
-the machine and the resources required by each instruction. The target
-backend can use @var{g} to calculate such bound. A very simple lower
-bound will be used in case this hook is not implemented: the total number
-of instructions divided by the issue rate.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_SCHED_DISPATCH (rtx_insn *@var{insn}, int @var{x})
-This hook is called by Haifa Scheduler. It returns true if dispatch scheduling
-is supported in hardware and the condition specified in the parameter is true.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_SCHED_DISPATCH_DO (rtx_insn *@var{insn}, int @var{x})
-This hook is called by Haifa Scheduler. It performs the operation specified
-in its second parameter.
-@end deftypefn
-
-@deftypevr {Target Hook} bool TARGET_SCHED_EXPOSED_PIPELINE
-True if the processor has an exposed pipeline, which means that not just
-the order of instructions is important for correctness when scheduling, but
-also the latencies of operations.
-@end deftypevr
-
-@deftypefn {Target Hook} int TARGET_SCHED_REASSOCIATION_WIDTH (unsigned int @var{opc}, machine_mode @var{mode})
-This hook is called by tree reassociator to determine a level of
-parallelism required in output calculations chain.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_SCHED_FUSION_PRIORITY (rtx_insn *@var{insn}, int @var{max_pri}, int *@var{fusion_pri}, int *@var{pri})
-This hook is called by scheduling fusion pass. It calculates fusion
-priorities for each instruction passed in by parameter. The priorities
-are returned via pointer parameters.
-
-@var{insn} is the instruction whose priorities need to be calculated.
-@var{max_pri} is the maximum priority can be returned in any cases.
-@var{fusion_pri} is the pointer parameter through which @var{insn}'s
-fusion priority should be calculated and returned.
-@var{pri} is the pointer parameter through which @var{insn}'s priority
-should be calculated and returned.
-
-Same @var{fusion_pri} should be returned for instructions which should
-be scheduled together. Different @var{pri} should be returned for
-instructions with same @var{fusion_pri}. @var{fusion_pri} is the major
-sort key, @var{pri} is the minor sort key. All instructions will be
-scheduled according to the two priorities. All priorities calculated
-should be between 0 (exclusive) and @var{max_pri} (inclusive). To avoid
-false dependencies, @var{fusion_pri} of instructions which need to be
-scheduled together should be smaller than @var{fusion_pri} of irrelevant
-instructions.
-
-Given below example:
-
-@smallexample
- ldr r10, [r1, 4]
- add r4, r4, r10
- ldr r15, [r2, 8]
- sub r5, r5, r15
- ldr r11, [r1, 0]
- add r4, r4, r11
- ldr r16, [r2, 12]
- sub r5, r5, r16
-@end smallexample
-
-On targets like ARM/AArch64, the two pairs of consecutive loads should be
-merged. Since peephole2 pass can't help in this case unless consecutive
-loads are actually next to each other in instruction flow. That's where
-this scheduling fusion pass works. This hook calculates priority for each
-instruction based on its fustion type, like:
-
-@smallexample
- ldr r10, [r1, 4] ; fusion_pri=99, pri=96
- add r4, r4, r10 ; fusion_pri=100, pri=100
- ldr r15, [r2, 8] ; fusion_pri=98, pri=92
- sub r5, r5, r15 ; fusion_pri=100, pri=100
- ldr r11, [r1, 0] ; fusion_pri=99, pri=100
- add r4, r4, r11 ; fusion_pri=100, pri=100
- ldr r16, [r2, 12] ; fusion_pri=98, pri=88
- sub r5, r5, r16 ; fusion_pri=100, pri=100
-@end smallexample
-
-Scheduling fusion pass then sorts all ready to issue instructions according
-to the priorities. As a result, instructions of same fusion type will be
-pushed together in instruction flow, like:
-
-@smallexample
- ldr r11, [r1, 0]
- ldr r10, [r1, 4]
- ldr r15, [r2, 8]
- ldr r16, [r2, 12]
- add r4, r4, r10
- sub r5, r5, r15
- add r4, r4, r11
- sub r5, r5, r16
-@end smallexample
-
-Now peephole2 pass can simply merge the two pairs of loads.
-
-Since scheduling fusion pass relies on peephole2 to do real fusion
-work, it is only enabled by default when peephole2 is in effect.
-
-This is firstly introduced on ARM/AArch64 targets, please refer to
-the hook implementation for how different fusion types are supported.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_EXPAND_DIVMOD_LIBFUNC (rtx @var{libfunc}, machine_mode @var{mode}, rtx @var{op0}, rtx @var{op1}, rtx *@var{quot}, rtx *@var{rem})
-Define this hook for enabling divmod transform if the port does not have
-hardware divmod insn but defines target-specific divmod libfuncs.
-@end deftypefn
-
-@node Sections
-@section Dividing the Output into Sections (Texts, Data, @dots{})
-@c the above section title is WAY too long. maybe cut the part between
-@c the (...)? --mew 10feb93
-
-An object file is divided into sections containing different types of
-data. In the most common case, there are three sections: the @dfn{text
-section}, which holds instructions and read-only data; the @dfn{data
-section}, which holds initialized writable data; and the @dfn{bss
-section}, which holds uninitialized data. Some systems have other kinds
-of sections.
-
-@file{varasm.cc} provides several well-known sections, such as
-@code{text_section}, @code{data_section} and @code{bss_section}.
-The normal way of controlling a @code{@var{foo}_section} variable
-is to define the associated @code{@var{FOO}_SECTION_ASM_OP} macro,
-as described below. The macros are only read once, when @file{varasm.cc}
-initializes itself, so their values must be run-time constants.
-They may however depend on command-line flags.
-
-@emph{Note:} Some run-time files, such @file{crtstuff.c}, also make
-use of the @code{@var{FOO}_SECTION_ASM_OP} macros, and expect them
-to be string literals.
-
-Some assemblers require a different string to be written every time a
-section is selected. If your assembler falls into this category, you
-should define the @code{TARGET_ASM_INIT_SECTIONS} hook and use
-@code{get_unnamed_section} to set up the sections.
-
-You must always create a @code{text_section}, either by defining
-@code{TEXT_SECTION_ASM_OP} or by initializing @code{text_section}
-in @code{TARGET_ASM_INIT_SECTIONS}. The same is true of
-@code{data_section} and @code{DATA_SECTION_ASM_OP}. If you do not
-create a distinct @code{readonly_data_section}, the default is to
-reuse @code{text_section}.
-
-All the other @file{varasm.cc} sections are optional, and are null
-if the target does not provide them.
-
-@defmac TEXT_SECTION_ASM_OP
-A C expression whose value is a string, including spacing, containing the
-assembler operation that should precede instructions and read-only data.
-Normally @code{"\t.text"} is right.
-@end defmac
-
-@defmac HOT_TEXT_SECTION_NAME
-If defined, a C string constant for the name of the section containing most
-frequently executed functions of the program. If not defined, GCC will provide
-a default definition if the target supports named sections.
-@end defmac
-
-@defmac UNLIKELY_EXECUTED_TEXT_SECTION_NAME
-If defined, a C string constant for the name of the section containing unlikely
-executed functions in the program.
-@end defmac
-
-@defmac DATA_SECTION_ASM_OP
-A C expression whose value is a string, including spacing, containing the
-assembler operation to identify the following data as writable initialized
-data. Normally @code{"\t.data"} is right.
-@end defmac
-
-@defmac SDATA_SECTION_ASM_OP
-If defined, a C expression whose value is a string, including spacing,
-containing the assembler operation to identify the following data as
-initialized, writable small data.
-@end defmac
-
-@defmac READONLY_DATA_SECTION_ASM_OP
-A C expression whose value is a string, including spacing, containing the
-assembler operation to identify the following data as read-only initialized
-data.
-@end defmac
-
-@defmac BSS_SECTION_ASM_OP
-If defined, a C expression whose value is a string, including spacing,
-containing the assembler operation to identify the following data as
-uninitialized global data. If not defined, and
-@code{ASM_OUTPUT_ALIGNED_BSS} not defined,
-uninitialized global data will be output in the data section if
-@option{-fno-common} is passed, otherwise @code{ASM_OUTPUT_COMMON} will be
-used.
-@end defmac
-
-@defmac SBSS_SECTION_ASM_OP
-If defined, a C expression whose value is a string, including spacing,
-containing the assembler operation to identify the following data as
-uninitialized, writable small data.
-@end defmac
-
-@defmac TLS_COMMON_ASM_OP
-If defined, a C expression whose value is a string containing the
-assembler operation to identify the following data as thread-local
-common data. The default is @code{".tls_common"}.
-@end defmac
-
-@defmac TLS_SECTION_ASM_FLAG
-If defined, a C expression whose value is a character constant
-containing the flag used to mark a section as a TLS section. The
-default is @code{'T'}.
-@end defmac
-
-@defmac INIT_SECTION_ASM_OP
-If defined, a C expression whose value is a string, including spacing,
-containing the assembler operation to identify the following data as
-initialization code. If not defined, GCC will assume such a section does
-not exist. This section has no corresponding @code{init_section}
-variable; it is used entirely in runtime code.
-@end defmac
-
-@defmac FINI_SECTION_ASM_OP
-If defined, a C expression whose value is a string, including spacing,
-containing the assembler operation to identify the following data as
-finalization code. If not defined, GCC will assume such a section does
-not exist. This section has no corresponding @code{fini_section}
-variable; it is used entirely in runtime code.
-@end defmac
-
-@defmac INIT_ARRAY_SECTION_ASM_OP
-If defined, a C expression whose value is a string, including spacing,
-containing the assembler operation to identify the following data as
-part of the @code{.init_array} (or equivalent) section. If not
-defined, GCC will assume such a section does not exist. Do not define
-both this macro and @code{INIT_SECTION_ASM_OP}.
-@end defmac
-
-@defmac FINI_ARRAY_SECTION_ASM_OP
-If defined, a C expression whose value is a string, including spacing,
-containing the assembler operation to identify the following data as
-part of the @code{.fini_array} (or equivalent) section. If not
-defined, GCC will assume such a section does not exist. Do not define
-both this macro and @code{FINI_SECTION_ASM_OP}.
-@end defmac
-
-@defmac MACH_DEP_SECTION_ASM_FLAG
-If defined, a C expression whose value is a character constant
-containing the flag used to mark a machine-dependent section. This
-corresponds to the @code{SECTION_MACH_DEP} section flag.
-@end defmac
-
-@defmac CRT_CALL_STATIC_FUNCTION (@var{section_op}, @var{function})
-If defined, an ASM statement that switches to a different section
-via @var{section_op}, calls @var{function}, and switches back to
-the text section. This is used in @file{crtstuff.c} if
-@code{INIT_SECTION_ASM_OP} or @code{FINI_SECTION_ASM_OP} to calls
-to initialization and finalization functions from the init and fini
-sections. By default, this macro uses a simple function call. Some
-ports need hand-crafted assembly code to avoid dependencies on
-registers initialized in the function prologue or to ensure that
-constant pools don't end up too far way in the text section.
-@end defmac
-
-@defmac TARGET_LIBGCC_SDATA_SECTION
-If defined, a string which names the section into which small
-variables defined in crtstuff and libgcc should go. This is useful
-when the target has options for optimizing access to small data, and
-you want the crtstuff and libgcc routines to be conservative in what
-they expect of your application yet liberal in what your application
-expects. For example, for targets with a @code{.sdata} section (like
-MIPS), you could compile crtstuff with @code{-G 0} so that it doesn't
-require small data support from your application, but use this macro
-to put small data into @code{.sdata} so that your application can
-access these variables whether it uses small data or not.
-@end defmac
-
-@defmac FORCE_CODE_SECTION_ALIGN
-If defined, an ASM statement that aligns a code section to some
-arbitrary boundary. This is used to force all fragments of the
-@code{.init} and @code{.fini} sections to have to same alignment
-and thus prevent the linker from having to add any padding.
-@end defmac
-
-@defmac JUMP_TABLES_IN_TEXT_SECTION
-Define this macro to be an expression with a nonzero value if jump
-tables (for @code{tablejump} insns) should be output in the text
-section, along with the assembler instructions. Otherwise, the
-readonly data section is used.
-
-This macro is irrelevant if there is no separate readonly data section.
-@end defmac
-
-@deftypefn {Target Hook} void TARGET_ASM_INIT_SECTIONS (void)
-Define this hook if you need to do something special to set up the
-@file{varasm.cc} sections, or if your target has some special sections
-of its own that you need to create.
-
-GCC calls this hook after processing the command line, but before writing
-any assembly code, and before calling any of the section-returning hooks
-described below.
-@end deftypefn
-
-@deftypefn {Target Hook} int TARGET_ASM_RELOC_RW_MASK (void)
-Return a mask describing how relocations should be treated when
-selecting sections. Bit 1 should be set if global relocations
-should be placed in a read-write section; bit 0 should be set if
-local relocations should be placed in a read-write section.
-
-The default version of this function returns 3 when @option{-fpic}
-is in effect, and 0 otherwise. The hook is typically redefined
-when the target cannot support (some kinds of) dynamic relocations
-in read-only sections even in executables.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_ASM_GENERATE_PIC_ADDR_DIFF_VEC (void)
-Return true to generate ADDR_DIF_VEC table
-or false to generate ADDR_VEC table for jumps in case of -fPIC.
-
-The default version of this function returns true if flag_pic
-equals true and false otherwise
-@end deftypefn
-
-@deftypefn {Target Hook} {section *} TARGET_ASM_SELECT_SECTION (tree @var{exp}, int @var{reloc}, unsigned HOST_WIDE_INT @var{align})
-Return the section into which @var{exp} should be placed. You can
-assume that @var{exp} is either a @code{VAR_DECL} node or a constant of
-some sort. @var{reloc} indicates whether the initial value of @var{exp}
-requires link-time relocations. Bit 0 is set when variable contains
-local relocations only, while bit 1 is set for global relocations.
-@var{align} is the constant alignment in bits.
-
-The default version of this function takes care of putting read-only
-variables in @code{readonly_data_section}.
-
-See also @var{USE_SELECT_SECTION_FOR_FUNCTIONS}.
-@end deftypefn
-
-@defmac USE_SELECT_SECTION_FOR_FUNCTIONS
-Define this macro if you wish TARGET_ASM_SELECT_SECTION to be called
-for @code{FUNCTION_DECL}s as well as for variables and constants.
-
-In the case of a @code{FUNCTION_DECL}, @var{reloc} will be zero if the
-function has been determined to be likely to be called, and nonzero if
-it is unlikely to be called.
-@end defmac
-
-@deftypefn {Target Hook} void TARGET_ASM_UNIQUE_SECTION (tree @var{decl}, int @var{reloc})
-Build up a unique section name, expressed as a @code{STRING_CST} node,
-and assign it to @samp{DECL_SECTION_NAME (@var{decl})}.
-As with @code{TARGET_ASM_SELECT_SECTION}, @var{reloc} indicates whether
-the initial value of @var{exp} requires link-time relocations.
-
-The default version of this function appends the symbol name to the
-ELF section name that would normally be used for the symbol. For
-example, the function @code{foo} would be placed in @code{.text.foo}.
-Whatever the actual target object format, this is often good enough.
-@end deftypefn
-
-@deftypefn {Target Hook} {section *} TARGET_ASM_FUNCTION_RODATA_SECTION (tree @var{decl}, bool @var{relocatable})
-Return the readonly data or reloc readonly data section associated with
-@samp{DECL_SECTION_NAME (@var{decl})}. @var{relocatable} selects the latter
-over the former.
-The default version of this function selects @code{.gnu.linkonce.r.name} if
-the function's section is @code{.gnu.linkonce.t.name}, @code{.rodata.name}
-or @code{.data.rel.ro.name} if function is in @code{.text.name}, and
-the normal readonly-data or reloc readonly data section otherwise.
-@end deftypefn
-
-@deftypevr {Target Hook} {const char *} TARGET_ASM_MERGEABLE_RODATA_PREFIX
-Usually, the compiler uses the prefix @code{".rodata"} to construct
-section names for mergeable constant data. Define this macro to override
-the string if a different section name should be used.
-@end deftypevr
-
-@deftypefn {Target Hook} {section *} TARGET_ASM_TM_CLONE_TABLE_SECTION (void)
-Return the section that should be used for transactional memory clone
-tables.
-@end deftypefn
-
-@deftypefn {Target Hook} {section *} TARGET_ASM_SELECT_RTX_SECTION (machine_mode @var{mode}, rtx @var{x}, unsigned HOST_WIDE_INT @var{align})
-Return the section into which a constant @var{x}, of mode @var{mode},
-should be placed. You can assume that @var{x} is some kind of
-constant in RTL@. The argument @var{mode} is redundant except in the
-case of a @code{const_int} rtx. @var{align} is the constant alignment
-in bits.
-
-The default version of this function takes care of putting symbolic
-constants in @code{flag_pic} mode in @code{data_section} and everything
-else in @code{readonly_data_section}.
-@end deftypefn
-
-@deftypefn {Target Hook} tree TARGET_MANGLE_DECL_ASSEMBLER_NAME (tree @var{decl}, tree @var{id})
-Define this hook if you need to postprocess the assembler name generated
-by target-independent code. The @var{id} provided to this hook will be
-the computed name (e.g., the macro @code{DECL_NAME} of the @var{decl} in C,
-or the mangled name of the @var{decl} in C++). The return value of the
-hook is an @code{IDENTIFIER_NODE} for the appropriate mangled name on
-your target system. The default implementation of this hook just
-returns the @var{id} provided.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_ENCODE_SECTION_INFO (tree @var{decl}, rtx @var{rtl}, int @var{new_decl_p})
-Define this hook if references to a symbol or a constant must be
-treated differently depending on something about the variable or
-function named by the symbol (such as what section it is in).
-
-The hook is executed immediately after rtl has been created for
-@var{decl}, which may be a variable or function declaration or
-an entry in the constant pool. In either case, @var{rtl} is the
-rtl in question. Do @emph{not} use @code{DECL_RTL (@var{decl})}
-in this hook; that field may not have been initialized yet.
-
-In the case of a constant, it is safe to assume that the rtl is
-a @code{mem} whose address is a @code{symbol_ref}. Most decls
-will also have this form, but that is not guaranteed. Global
-register variables, for instance, will have a @code{reg} for their
-rtl. (Normally the right thing to do with such unusual rtl is
-leave it alone.)
-
-The @var{new_decl_p} argument will be true if this is the first time
-that @code{TARGET_ENCODE_SECTION_INFO} has been invoked on this decl. It will
-be false for subsequent invocations, which will happen for duplicate
-declarations. Whether or not anything must be done for the duplicate
-declaration depends on whether the hook examines @code{DECL_ATTRIBUTES}.
-@var{new_decl_p} is always true when the hook is called for a constant.
-
-@cindex @code{SYMBOL_REF_FLAG}, in @code{TARGET_ENCODE_SECTION_INFO}
-The usual thing for this hook to do is to record flags in the
-@code{symbol_ref}, using @code{SYMBOL_REF_FLAG} or @code{SYMBOL_REF_FLAGS}.
-Historically, the name string was modified if it was necessary to
-encode more than one bit of information, but this practice is now
-discouraged; use @code{SYMBOL_REF_FLAGS}.
-
-The default definition of this hook, @code{default_encode_section_info}
-in @file{varasm.cc}, sets a number of commonly-useful bits in
-@code{SYMBOL_REF_FLAGS}. Check whether the default does what you need
-before overriding it.
-@end deftypefn
-
-@deftypefn {Target Hook} {const char *} TARGET_STRIP_NAME_ENCODING (const char *@var{name})
-Decode @var{name} and return the real name part, sans
-the characters that @code{TARGET_ENCODE_SECTION_INFO}
-may have added.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_IN_SMALL_DATA_P (const_tree @var{exp})
-Returns true if @var{exp} should be placed into a ``small data'' section.
-The default version of this hook always returns false.
-@end deftypefn
-
-@deftypevr {Target Hook} bool TARGET_HAVE_SRODATA_SECTION
-Contains the value true if the target places read-only
-``small data'' into a separate section. The default value is false.
-@end deftypevr
-
-@deftypefn {Target Hook} bool TARGET_PROFILE_BEFORE_PROLOGUE (void)
-It returns true if target wants profile code emitted before prologue.
-
-The default version of this hook use the target macro
-@code{PROFILE_BEFORE_PROLOGUE}.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_BINDS_LOCAL_P (const_tree @var{exp})
-Returns true if @var{exp} names an object for which name resolution
-rules must resolve to the current ``module'' (dynamic shared library
-or executable image).
-
-The default version of this hook implements the name resolution rules
-for ELF, which has a looser model of global name binding than other
-currently supported object file formats.
-@end deftypefn
-
-@deftypevr {Target Hook} bool TARGET_HAVE_TLS
-Contains the value true if the target supports thread-local storage.
-The default value is false.
-@end deftypevr
-
-
-@node PIC
-@section Position Independent Code
-@cindex position independent code
-@cindex PIC
-
-This section describes macros that help implement generation of position
-independent code. Simply defining these macros is not enough to
-generate valid PIC; you must also add support to the hook
-@code{TARGET_LEGITIMATE_ADDRESS_P} and to the macro
-@code{PRINT_OPERAND_ADDRESS}, as well as @code{LEGITIMIZE_ADDRESS}. You
-must modify the definition of @samp{movsi} to do something appropriate
-when the source operand contains a symbolic address. You may also
-need to alter the handling of switch statements so that they use
-relative addresses.
-@c i rearranged the order of the macros above to try to force one of
-@c them to the next line, to eliminate an overfull hbox. --mew 10feb93
-
-@defmac PIC_OFFSET_TABLE_REGNUM
-The register number of the register used to address a table of static
-data addresses in memory. In some cases this register is defined by a
-processor's ``application binary interface'' (ABI)@. When this macro
-is defined, RTL is generated for this register once, as with the stack
-pointer and frame pointer registers. If this macro is not defined, it
-is up to the machine-dependent files to allocate such a register (if
-necessary). Note that this register must be fixed when in use (e.g.@:
-when @code{flag_pic} is true).
-@end defmac
-
-@defmac PIC_OFFSET_TABLE_REG_CALL_CLOBBERED
-A C expression that is nonzero if the register defined by
-@code{PIC_OFFSET_TABLE_REGNUM} is clobbered by calls. If not defined,
-the default is zero. Do not define
-this macro if @code{PIC_OFFSET_TABLE_REGNUM} is not defined.
-@end defmac
-
-@defmac LEGITIMATE_PIC_OPERAND_P (@var{x})
-A C expression that is nonzero if @var{x} is a legitimate immediate
-operand on the target machine when generating position independent code.
-You can assume that @var{x} satisfies @code{CONSTANT_P}, so you need not
-check this. You can also assume @var{flag_pic} is true, so you need not
-check it either. You need not define this macro if all constants
-(including @code{SYMBOL_REF}) can be immediate operands when generating
-position independent code.
-@end defmac
-
-@node Assembler Format
-@section Defining the Output Assembler Language
-
-This section describes macros whose principal purpose is to describe how
-to write instructions in assembler language---rather than what the
-instructions do.
-
-@menu
-* File Framework:: Structural information for the assembler file.
-* Data Output:: Output of constants (numbers, strings, addresses).
-* Uninitialized Data:: Output of uninitialized variables.
-* Label Output:: Output and generation of labels.
-* Initialization:: General principles of initialization
- and termination routines.
-* Macros for Initialization::
- Specific macros that control the handling of
- initialization and termination routines.
-* Instruction Output:: Output of actual instructions.
-* Dispatch Tables:: Output of jump tables.
-* Exception Region Output:: Output of exception region code.
-* Alignment Output:: Pseudo ops for alignment and skipping data.
-@end menu
-
-@node File Framework
-@subsection The Overall Framework of an Assembler File
-@cindex assembler format
-@cindex output of assembler code
-
-@c prevent bad page break with this line
-This describes the overall framework of an assembly file.
-
-@findex default_file_start
-@deftypefn {Target Hook} void TARGET_ASM_FILE_START (void)
-Output to @code{asm_out_file} any text which the assembler expects to
-find at the beginning of a file. The default behavior is controlled
-by two flags, documented below. Unless your target's assembler is
-quite unusual, if you override the default, you should call
-@code{default_file_start} at some point in your target hook. This
-lets other target files rely on these variables.
-@end deftypefn
-
-@deftypevr {Target Hook} bool TARGET_ASM_FILE_START_APP_OFF
-If this flag is true, the text of the macro @code{ASM_APP_OFF} will be
-printed as the very first line in the assembly file, unless
-@option{-fverbose-asm} is in effect. (If that macro has been defined
-to the empty string, this variable has no effect.) With the normal
-definition of @code{ASM_APP_OFF}, the effect is to notify the GNU
-assembler that it need not bother stripping comments or extra
-whitespace from its input. This allows it to work a bit faster.
-
-The default is false. You should not set it to true unless you have
-verified that your port does not generate any extra whitespace or
-comments that will cause GAS to issue errors in NO_APP mode.
-@end deftypevr
-
-@deftypevr {Target Hook} bool TARGET_ASM_FILE_START_FILE_DIRECTIVE
-If this flag is true, @code{output_file_directive} will be called
-for the primary source file, immediately after printing
-@code{ASM_APP_OFF} (if that is enabled). Most ELF assemblers expect
-this to be done. The default is false.
-@end deftypevr
-
-@deftypefn {Target Hook} void TARGET_ASM_FILE_END (void)
-Output to @code{asm_out_file} any text which the assembler expects
-to find at the end of a file. The default is to output nothing.
-@end deftypefn
-
-@deftypefun void file_end_indicate_exec_stack ()
-Some systems use a common convention, the @samp{.note.GNU-stack}
-special section, to indicate whether or not an object file relies on
-the stack being executable. If your system uses this convention, you
-should define @code{TARGET_ASM_FILE_END} to this function. If you
-need to do other things in that hook, have your hook function call
-this function.
-@end deftypefun
-
-@deftypefn {Target Hook} void TARGET_ASM_LTO_START (void)
-Output to @code{asm_out_file} any text which the assembler expects
-to find at the start of an LTO section. The default is to output
-nothing.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_ASM_LTO_END (void)
-Output to @code{asm_out_file} any text which the assembler expects
-to find at the end of an LTO section. The default is to output
-nothing.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_ASM_CODE_END (void)
-Output to @code{asm_out_file} any text which is needed before emitting
-unwind info and debug info at the end of a file. Some targets emit
-here PIC setup thunks that cannot be emitted at the end of file,
-because they couldn't have unwind info then. The default is to output
-nothing.
-@end deftypefn
-
-@defmac ASM_COMMENT_START
-A C string constant describing how to begin a comment in the target
-assembler language. The compiler assumes that the comment will end at
-the end of the line.
-@end defmac
-
-@defmac ASM_APP_ON
-A C string constant for text to be output before each @code{asm}
-statement or group of consecutive ones. Normally this is
-@code{"#APP"}, which is a comment that has no effect on most
-assemblers but tells the GNU assembler that it must check the lines
-that follow for all valid assembler constructs.
-@end defmac
-
-@defmac ASM_APP_OFF
-A C string constant for text to be output after each @code{asm}
-statement or group of consecutive ones. Normally this is
-@code{"#NO_APP"}, which tells the GNU assembler to resume making the
-time-saving assumptions that are valid for ordinary compiler output.
-@end defmac
-
-@defmac ASM_OUTPUT_SOURCE_FILENAME (@var{stream}, @var{name})
-A C statement to output COFF information or DWARF debugging information
-which indicates that filename @var{name} is the current source file to
-the stdio stream @var{stream}.
-
-This macro need not be defined if the standard form of output
-for the file format in use is appropriate.
-@end defmac
-
-@deftypefn {Target Hook} void TARGET_ASM_OUTPUT_SOURCE_FILENAME (FILE *@var{file}, const char *@var{name})
-Output DWARF debugging information which indicates that filename
-@var{name} is the current source file to the stdio stream @var{file}.
-
-This target hook need not be defined if the standard form of output
-for the file format in use is appropriate.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_ASM_OUTPUT_IDENT (const char *@var{name})
-Output a string based on @var{name}, suitable for the @samp{#ident}
-directive, or the equivalent directive or pragma in non-C-family languages.
-If this hook is not defined, nothing is output for the @samp{#ident}
-directive.
-@end deftypefn
-
-@defmac OUTPUT_QUOTED_STRING (@var{stream}, @var{string})
-A C statement to output the string @var{string} to the stdio stream
-@var{stream}. If you do not call the function @code{output_quoted_string}
-in your config files, GCC will only call it to output filenames to
-the assembler source. So you can use it to canonicalize the format
-of the filename using this macro.
-@end defmac
-
-@deftypefn {Target Hook} void TARGET_ASM_NAMED_SECTION (const char *@var{name}, unsigned int @var{flags}, tree @var{decl})
-Output assembly directives to switch to section @var{name}. The section
-should have attributes as specified by @var{flags}, which is a bit mask
-of the @code{SECTION_*} flags defined in @file{output.h}. If @var{decl}
-is non-NULL, it is the @code{VAR_DECL} or @code{FUNCTION_DECL} with which
-this section is associated.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_ASM_ELF_FLAGS_NUMERIC (unsigned int @var{flags}, unsigned int *@var{num})
-This hook can be used to encode ELF section flags for which no letter
-code has been defined in the assembler. It is called by
-@code{default_asm_named_section} whenever the section flags need to be
-emitted in the assembler output. If the hook returns true, then the
-numerical value for ELF section flags should be calculated from
-@var{flags} and saved in @var{*num}; the value is printed out instead of the
-normal sequence of letter codes. If the hook is not defined, or if it
-returns false, then @var{num} is ignored and the traditional letter sequence
-is emitted.
-@end deftypefn
-
-@deftypefn {Target Hook} {section *} TARGET_ASM_FUNCTION_SECTION (tree @var{decl}, enum node_frequency @var{freq}, bool @var{startup}, bool @var{exit})
-Return preferred text (sub)section for function @var{decl}.
-Main purpose of this function is to separate cold, normal and hot
-functions. @var{startup} is true when function is known to be used only
-at startup (from static constructors or it is @code{main()}).
-@var{exit} is true when function is known to be used only at exit
-(from static destructors).
-Return NULL if function should go to default text section.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_ASM_FUNCTION_SWITCHED_TEXT_SECTIONS (FILE *@var{file}, tree @var{decl}, bool @var{new_is_cold})
-Used by the target to emit any assembler directives or additional
-labels needed when a function is partitioned between different
-sections. Output should be written to @var{file}. The function
-decl is available as @var{decl} and the new section is `cold' if
-@var{new_is_cold} is @code{true}.
-@end deftypefn
-
-@deftypevr {Common Target Hook} bool TARGET_HAVE_NAMED_SECTIONS
-This flag is true if the target supports @code{TARGET_ASM_NAMED_SECTION}.
-It must not be modified by command-line option processing.
-@end deftypevr
-
-@anchor{TARGET_HAVE_SWITCHABLE_BSS_SECTIONS}
-@deftypevr {Target Hook} bool TARGET_HAVE_SWITCHABLE_BSS_SECTIONS
-This flag is true if we can create zeroed data by switching to a BSS
-section and then using @code{ASM_OUTPUT_SKIP} to allocate the space.
-This is true on most ELF targets.
-@end deftypevr
-
-@deftypefn {Target Hook} {unsigned int} TARGET_SECTION_TYPE_FLAGS (tree @var{decl}, const char *@var{name}, int @var{reloc})
-Choose a set of section attributes for use by @code{TARGET_ASM_NAMED_SECTION}
-based on a variable or function decl, a section name, and whether or not the
-declaration's initializer may contain runtime relocations. @var{decl} may be
-null, in which case read-write data should be assumed.
-
-The default version of this function handles choosing code vs data,
-read-only vs read-write data, and @code{flag_pic}. You should only
-need to override this if your target has special flags that might be
-set via @code{__attribute__}.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_ASM_RECORD_GCC_SWITCHES (const char *@var{})
-Provides the target with the ability to record the gcc command line
-switches provided as argument.
-
-By default this hook is set to NULL, but an example implementation is
-provided for ELF based targets. Called @var{elf_record_gcc_switches},
-it records the switches as ASCII text inside a new, string mergeable
-section in the assembler output file. The name of the new section is
-provided by the @code{TARGET_ASM_RECORD_GCC_SWITCHES_SECTION} target
-hook.
-@end deftypefn
-
-@deftypevr {Target Hook} {const char *} TARGET_ASM_RECORD_GCC_SWITCHES_SECTION
-This is the name of the section that will be created by the example
-ELF implementation of the @code{TARGET_ASM_RECORD_GCC_SWITCHES} target
-hook.
-@end deftypevr
-
-@need 2000
-@node Data Output
-@subsection Output of Data
-
-
-@deftypevr {Target Hook} {const char *} TARGET_ASM_BYTE_OP
-@deftypevrx {Target Hook} {const char *} TARGET_ASM_ALIGNED_HI_OP
-@deftypevrx {Target Hook} {const char *} TARGET_ASM_ALIGNED_PSI_OP
-@deftypevrx {Target Hook} {const char *} TARGET_ASM_ALIGNED_SI_OP
-@deftypevrx {Target Hook} {const char *} TARGET_ASM_ALIGNED_PDI_OP
-@deftypevrx {Target Hook} {const char *} TARGET_ASM_ALIGNED_DI_OP
-@deftypevrx {Target Hook} {const char *} TARGET_ASM_ALIGNED_PTI_OP
-@deftypevrx {Target Hook} {const char *} TARGET_ASM_ALIGNED_TI_OP
-@deftypevrx {Target Hook} {const char *} TARGET_ASM_UNALIGNED_HI_OP
-@deftypevrx {Target Hook} {const char *} TARGET_ASM_UNALIGNED_PSI_OP
-@deftypevrx {Target Hook} {const char *} TARGET_ASM_UNALIGNED_SI_OP
-@deftypevrx {Target Hook} {const char *} TARGET_ASM_UNALIGNED_PDI_OP
-@deftypevrx {Target Hook} {const char *} TARGET_ASM_UNALIGNED_DI_OP
-@deftypevrx {Target Hook} {const char *} TARGET_ASM_UNALIGNED_PTI_OP
-@deftypevrx {Target Hook} {const char *} TARGET_ASM_UNALIGNED_TI_OP
-These hooks specify assembly directives for creating certain kinds
-of integer object. The @code{TARGET_ASM_BYTE_OP} directive creates a
-byte-sized object, the @code{TARGET_ASM_ALIGNED_HI_OP} one creates an
-aligned two-byte object, and so on. Any of the hooks may be
-@code{NULL}, indicating that no suitable directive is available.
-
-The compiler will print these strings at the start of a new line,
-followed immediately by the object's initial value. In most cases,
-the string should contain a tab, a pseudo-op, and then another tab.
-@end deftypevr
-
-@deftypefn {Target Hook} bool TARGET_ASM_INTEGER (rtx @var{x}, unsigned int @var{size}, int @var{aligned_p})
-The @code{assemble_integer} function uses this hook to output an
-integer object. @var{x} is the object's value, @var{size} is its size
-in bytes and @var{aligned_p} indicates whether it is aligned. The
-function should return @code{true} if it was able to output the
-object. If it returns false, @code{assemble_integer} will try to
-split the object into smaller parts.
-
-The default implementation of this hook will use the
-@code{TARGET_ASM_BYTE_OP} family of strings, returning @code{false}
-when the relevant string is @code{NULL}.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_ASM_DECL_END (void)
-Define this hook if the target assembler requires a special marker to
-terminate an initialized variable declaration.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_ASM_OUTPUT_ADDR_CONST_EXTRA (FILE *@var{file}, rtx @var{x})
-A target hook to recognize @var{rtx} patterns that @code{output_addr_const}
-can't deal with, and output assembly code to @var{file} corresponding to
-the pattern @var{x}. This may be used to allow machine-dependent
-@code{UNSPEC}s to appear within constants.
-
-If target hook fails to recognize a pattern, it must return @code{false},
-so that a standard error message is printed. If it prints an error message
-itself, by calling, for example, @code{output_operand_lossage}, it may just
-return @code{true}.
-@end deftypefn
-
-@defmac ASM_OUTPUT_ASCII (@var{stream}, @var{ptr}, @var{len})
-A C statement to output to the stdio stream @var{stream} an assembler
-instruction to assemble a string constant containing the @var{len}
-bytes at @var{ptr}. @var{ptr} will be a C expression of type
-@code{char *} and @var{len} a C expression of type @code{int}.
-
-If the assembler has a @code{.ascii} pseudo-op as found in the
-Berkeley Unix assembler, do not define the macro
-@code{ASM_OUTPUT_ASCII}.
-@end defmac
-
-@defmac ASM_OUTPUT_FDESC (@var{stream}, @var{decl}, @var{n})
-A C statement to output word @var{n} of a function descriptor for
-@var{decl}. This must be defined if @code{TARGET_VTABLE_USES_DESCRIPTORS}
-is defined, and is otherwise unused.
-@end defmac
-
-@defmac CONSTANT_POOL_BEFORE_FUNCTION
-You may define this macro as a C expression. You should define the
-expression to have a nonzero value if GCC should output the constant
-pool for a function before the code for the function, or a zero value if
-GCC should output the constant pool after the function. If you do
-not define this macro, the usual case, GCC will output the constant
-pool before the function.
-@end defmac
-
-@defmac ASM_OUTPUT_POOL_PROLOGUE (@var{file}, @var{funname}, @var{fundecl}, @var{size})
-A C statement to output assembler commands to define the start of the
-constant pool for a function. @var{funname} is a string giving
-the name of the function. Should the return type of the function
-be required, it can be obtained via @var{fundecl}. @var{size}
-is the size, in bytes, of the constant pool that will be written
-immediately after this call.
-
-If no constant-pool prefix is required, the usual case, this macro need
-not be defined.
-@end defmac
-
-@defmac ASM_OUTPUT_SPECIAL_POOL_ENTRY (@var{file}, @var{x}, @var{mode}, @var{align}, @var{labelno}, @var{jumpto})
-A C statement (with or without semicolon) to output a constant in the
-constant pool, if it needs special treatment. (This macro need not do
-anything for RTL expressions that can be output normally.)
-
-The argument @var{file} is the standard I/O stream to output the
-assembler code on. @var{x} is the RTL expression for the constant to
-output, and @var{mode} is the machine mode (in case @var{x} is a
-@samp{const_int}). @var{align} is the required alignment for the value
-@var{x}; you should output an assembler directive to force this much
-alignment.
-
-The argument @var{labelno} is a number to use in an internal label for
-the address of this pool entry. The definition of this macro is
-responsible for outputting the label definition at the proper place.
-Here is how to do this:
-
-@smallexample
-@code{(*targetm.asm_out.internal_label)} (@var{file}, "LC", @var{labelno});
-@end smallexample
-
-When you output a pool entry specially, you should end with a
-@code{goto} to the label @var{jumpto}. This will prevent the same pool
-entry from being output a second time in the usual manner.
-
-You need not define this macro if it would do nothing.
-@end defmac
-
-@defmac ASM_OUTPUT_POOL_EPILOGUE (@var{file} @var{funname} @var{fundecl} @var{size})
-A C statement to output assembler commands to at the end of the constant
-pool for a function. @var{funname} is a string giving the name of the
-function. Should the return type of the function be required, you can
-obtain it via @var{fundecl}. @var{size} is the size, in bytes, of the
-constant pool that GCC wrote immediately before this call.
-
-If no constant-pool epilogue is required, the usual case, you need not
-define this macro.
-@end defmac
-
-@defmac IS_ASM_LOGICAL_LINE_SEPARATOR (@var{C}, @var{STR})
-Define this macro as a C expression which is nonzero if @var{C} is
-used as a logical line separator by the assembler. @var{STR} points
-to the position in the string where @var{C} was found; this can be used if
-a line separator uses multiple characters.
-
-If you do not define this macro, the default is that only
-the character @samp{;} is treated as a logical line separator.
-@end defmac
-
-@deftypevr {Target Hook} {const char *} TARGET_ASM_OPEN_PAREN
-@deftypevrx {Target Hook} {const char *} TARGET_ASM_CLOSE_PAREN
-These target hooks are C string constants, describing the syntax in the
-assembler for grouping arithmetic expressions. If not overridden, they
-default to normal parentheses, which is correct for most assemblers.
-@end deftypevr
-
-These macros are provided by @file{real.h} for writing the definitions
-of @code{ASM_OUTPUT_DOUBLE} and the like:
-
-@defmac REAL_VALUE_TO_TARGET_SINGLE (@var{x}, @var{l})
-@defmacx REAL_VALUE_TO_TARGET_DOUBLE (@var{x}, @var{l})
-@defmacx REAL_VALUE_TO_TARGET_LONG_DOUBLE (@var{x}, @var{l})
-@defmacx REAL_VALUE_TO_TARGET_DECIMAL32 (@var{x}, @var{l})
-@defmacx REAL_VALUE_TO_TARGET_DECIMAL64 (@var{x}, @var{l})
-@defmacx REAL_VALUE_TO_TARGET_DECIMAL128 (@var{x}, @var{l})
-These translate @var{x}, of type @code{REAL_VALUE_TYPE}, to the
-target's floating point representation, and store its bit pattern in
-the variable @var{l}. For @code{REAL_VALUE_TO_TARGET_SINGLE} and
-@code{REAL_VALUE_TO_TARGET_DECIMAL32}, this variable should be a
-simple @code{long int}. For the others, it should be an array of
-@code{long int}. The number of elements in this array is determined
-by the size of the desired target floating point data type: 32 bits of
-it go in each @code{long int} array element. Each array element holds
-32 bits of the result, even if @code{long int} is wider than 32 bits
-on the host machine.
-
-The array element values are designed so that you can print them out
-using @code{fprintf} in the order they should appear in the target
-machine's memory.
-@end defmac
-
-@node Uninitialized Data
-@subsection Output of Uninitialized Variables
-
-Each of the macros in this section is used to do the whole job of
-outputting a single uninitialized variable.
-
-@defmac ASM_OUTPUT_COMMON (@var{stream}, @var{name}, @var{size}, @var{rounded})
-A C statement (sans semicolon) to output to the stdio stream
-@var{stream} the assembler definition of a common-label named
-@var{name} whose size is @var{size} bytes. The variable @var{rounded}
-is the size rounded up to whatever alignment the caller wants. It is
-possible that @var{size} may be zero, for instance if a struct with no
-other member than a zero-length array is defined. In this case, the
-backend must output a symbol definition that allocates at least one
-byte, both so that the address of the resulting object does not compare
-equal to any other, and because some object formats cannot even express
-the concept of a zero-sized common symbol, as that is how they represent
-an ordinary undefined external.
-
-Use the expression @code{assemble_name (@var{stream}, @var{name})} to
-output the name itself; before and after that, output the additional
-assembler syntax for defining the name, and a newline.
-
-This macro controls how the assembler definitions of uninitialized
-common global variables are output.
-@end defmac
-
-@defmac ASM_OUTPUT_ALIGNED_COMMON (@var{stream}, @var{name}, @var{size}, @var{alignment})
-Like @code{ASM_OUTPUT_COMMON} except takes the required alignment as a
-separate, explicit argument. If you define this macro, it is used in
-place of @code{ASM_OUTPUT_COMMON}, and gives you more flexibility in
-handling the required alignment of the variable. The alignment is specified
-as the number of bits.
-@end defmac
-
-@defmac ASM_OUTPUT_ALIGNED_DECL_COMMON (@var{stream}, @var{decl}, @var{name}, @var{size}, @var{alignment})
-Like @code{ASM_OUTPUT_ALIGNED_COMMON} except that @var{decl} of the
-variable to be output, if there is one, or @code{NULL_TREE} if there
-is no corresponding variable. If you define this macro, GCC will use it
-in place of both @code{ASM_OUTPUT_COMMON} and
-@code{ASM_OUTPUT_ALIGNED_COMMON}. Define this macro when you need to see
-the variable's decl in order to chose what to output.
-@end defmac
-
-@defmac ASM_OUTPUT_ALIGNED_BSS (@var{stream}, @var{decl}, @var{name}, @var{size}, @var{alignment})
-A C statement (sans semicolon) to output to the stdio stream
-@var{stream} the assembler definition of uninitialized global @var{decl} named
-@var{name} whose size is @var{size} bytes. The variable @var{alignment}
-is the alignment specified as the number of bits.
-
-Try to use function @code{asm_output_aligned_bss} defined in file
-@file{varasm.cc} when defining this macro. If unable, use the expression
-@code{assemble_name (@var{stream}, @var{name})} to output the name itself;
-before and after that, output the additional assembler syntax for defining
-the name, and a newline.
-
-There are two ways of handling global BSS@. One is to define this macro.
-The other is to have @code{TARGET_ASM_SELECT_SECTION} return a
-switchable BSS section (@pxref{TARGET_HAVE_SWITCHABLE_BSS_SECTIONS}).
-You do not need to do both.
-
-Some languages do not have @code{common} data, and require a
-non-common form of global BSS in order to handle uninitialized globals
-efficiently. C++ is one example of this. However, if the target does
-not support global BSS, the front end may choose to make globals
-common in order to save space in the object file.
-@end defmac
-
-@defmac ASM_OUTPUT_LOCAL (@var{stream}, @var{name}, @var{size}, @var{rounded})
-A C statement (sans semicolon) to output to the stdio stream
-@var{stream} the assembler definition of a local-common-label named
-@var{name} whose size is @var{size} bytes. The variable @var{rounded}
-is the size rounded up to whatever alignment the caller wants.
-
-Use the expression @code{assemble_name (@var{stream}, @var{name})} to
-output the name itself; before and after that, output the additional
-assembler syntax for defining the name, and a newline.
-
-This macro controls how the assembler definitions of uninitialized
-static variables are output.
-@end defmac
-
-@defmac ASM_OUTPUT_ALIGNED_LOCAL (@var{stream}, @var{name}, @var{size}, @var{alignment})
-Like @code{ASM_OUTPUT_LOCAL} except takes the required alignment as a
-separate, explicit argument. If you define this macro, it is used in
-place of @code{ASM_OUTPUT_LOCAL}, and gives you more flexibility in
-handling the required alignment of the variable. The alignment is specified
-as the number of bits.
-@end defmac
-
-@defmac ASM_OUTPUT_ALIGNED_DECL_LOCAL (@var{stream}, @var{decl}, @var{name}, @var{size}, @var{alignment})
-Like @code{ASM_OUTPUT_ALIGNED_LOCAL} except that @var{decl} of the
-variable to be output, if there is one, or @code{NULL_TREE} if there
-is no corresponding variable. If you define this macro, GCC will use it
-in place of both @code{ASM_OUTPUT_LOCAL} and
-@code{ASM_OUTPUT_ALIGNED_LOCAL}. Define this macro when you need to see
-the variable's decl in order to chose what to output.
-@end defmac
-
-@node Label Output
-@subsection Output and Generation of Labels
-
-@c prevent bad page break with this line
-This is about outputting labels.
-
-@findex assemble_name
-@defmac ASM_OUTPUT_LABEL (@var{stream}, @var{name})
-A C statement (sans semicolon) to output to the stdio stream
-@var{stream} the assembler definition of a label named @var{name}.
-Use the expression @code{assemble_name (@var{stream}, @var{name})} to
-output the name itself; before and after that, output the additional
-assembler syntax for defining the name, and a newline. A default
-definition of this macro is provided which is correct for most systems.
-@end defmac
-
-@defmac ASM_OUTPUT_FUNCTION_LABEL (@var{stream}, @var{name}, @var{decl})
-A C statement (sans semicolon) to output to the stdio stream
-@var{stream} the assembler definition of a label named @var{name} of
-a function.
-Use the expression @code{assemble_name (@var{stream}, @var{name})} to
-output the name itself; before and after that, output the additional
-assembler syntax for defining the name, and a newline. A default
-definition of this macro is provided which is correct for most systems.
-
-If this macro is not defined, then the function name is defined in the
-usual manner as a label (by means of @code{ASM_OUTPUT_LABEL}).
-@end defmac
-
-@findex assemble_name_raw
-@defmac ASM_OUTPUT_INTERNAL_LABEL (@var{stream}, @var{name})
-Identical to @code{ASM_OUTPUT_LABEL}, except that @var{name} is known
-to refer to a compiler-generated label. The default definition uses
-@code{assemble_name_raw}, which is like @code{assemble_name} except
-that it is more efficient.
-@end defmac
-
-@defmac SIZE_ASM_OP
-A C string containing the appropriate assembler directive to specify the
-size of a symbol, without any arguments. On systems that use ELF, the
-default (in @file{config/elfos.h}) is @samp{"\t.size\t"}; on other
-systems, the default is not to define this macro.
-
-Define this macro only if it is correct to use the default definitions
-of @code{ASM_OUTPUT_SIZE_DIRECTIVE} and @code{ASM_OUTPUT_MEASURED_SIZE}
-for your system. If you need your own custom definitions of those
-macros, or if you do not need explicit symbol sizes at all, do not
-define this macro.
-@end defmac
-
-@defmac ASM_OUTPUT_SIZE_DIRECTIVE (@var{stream}, @var{name}, @var{size})
-A C statement (sans semicolon) to output to the stdio stream
-@var{stream} a directive telling the assembler that the size of the
-symbol @var{name} is @var{size}. @var{size} is a @code{HOST_WIDE_INT}.
-If you define @code{SIZE_ASM_OP}, a default definition of this macro is
-provided.
-@end defmac
-
-@defmac ASM_OUTPUT_MEASURED_SIZE (@var{stream}, @var{name})
-A C statement (sans semicolon) to output to the stdio stream
-@var{stream} a directive telling the assembler to calculate the size of
-the symbol @var{name} by subtracting its address from the current
-address.
-
-If you define @code{SIZE_ASM_OP}, a default definition of this macro is
-provided. The default assumes that the assembler recognizes a special
-@samp{.} symbol as referring to the current address, and can calculate
-the difference between this and another symbol. If your assembler does
-not recognize @samp{.} or cannot do calculations with it, you will need
-to redefine @code{ASM_OUTPUT_MEASURED_SIZE} to use some other technique.
-@end defmac
-
-@defmac NO_DOLLAR_IN_LABEL
-Define this macro if the assembler does not accept the character
-@samp{$} in label names. By default constructors and destructors in
-G++ have @samp{$} in the identifiers. If this macro is defined,
-@samp{.} is used instead.
-@end defmac
-
-@defmac NO_DOT_IN_LABEL
-Define this macro if the assembler does not accept the character
-@samp{.} in label names. By default constructors and destructors in G++
-have names that use @samp{.}. If this macro is defined, these names
-are rewritten to avoid @samp{.}.
-@end defmac
-
-@defmac TYPE_ASM_OP
-A C string containing the appropriate assembler directive to specify the
-type of a symbol, without any arguments. On systems that use ELF, the
-default (in @file{config/elfos.h}) is @samp{"\t.type\t"}; on other
-systems, the default is not to define this macro.
-
-Define this macro only if it is correct to use the default definition of
-@code{ASM_OUTPUT_TYPE_DIRECTIVE} for your system. If you need your own
-custom definition of this macro, or if you do not need explicit symbol
-types at all, do not define this macro.
-@end defmac
-
-@defmac TYPE_OPERAND_FMT
-A C string which specifies (using @code{printf} syntax) the format of
-the second operand to @code{TYPE_ASM_OP}. On systems that use ELF, the
-default (in @file{config/elfos.h}) is @samp{"@@%s"}; on other systems,
-the default is not to define this macro.
-
-Define this macro only if it is correct to use the default definition of
-@code{ASM_OUTPUT_TYPE_DIRECTIVE} for your system. If you need your own
-custom definition of this macro, or if you do not need explicit symbol
-types at all, do not define this macro.
-@end defmac
-
-@defmac ASM_OUTPUT_TYPE_DIRECTIVE (@var{stream}, @var{type})
-A C statement (sans semicolon) to output to the stdio stream
-@var{stream} a directive telling the assembler that the type of the
-symbol @var{name} is @var{type}. @var{type} is a C string; currently,
-that string is always either @samp{"function"} or @samp{"object"}, but
-you should not count on this.
-
-If you define @code{TYPE_ASM_OP} and @code{TYPE_OPERAND_FMT}, a default
-definition of this macro is provided.
-@end defmac
-
-@defmac ASM_DECLARE_FUNCTION_NAME (@var{stream}, @var{name}, @var{decl})
-A C statement (sans semicolon) to output to the stdio stream
-@var{stream} any text necessary for declaring the name @var{name} of a
-function which is being defined. This macro is responsible for
-outputting the label definition (perhaps using
-@code{ASM_OUTPUT_FUNCTION_LABEL}). The argument @var{decl} is the
-@code{FUNCTION_DECL} tree node representing the function.
-
-If this macro is not defined, then the function name is defined in the
-usual manner as a label (by means of @code{ASM_OUTPUT_FUNCTION_LABEL}).
-
-You may wish to use @code{ASM_OUTPUT_TYPE_DIRECTIVE} in the definition
-of this macro.
-@end defmac
-
-@defmac ASM_DECLARE_FUNCTION_SIZE (@var{stream}, @var{name}, @var{decl})
-A C statement (sans semicolon) to output to the stdio stream
-@var{stream} any text necessary for declaring the size of a function
-which is being defined. The argument @var{name} is the name of the
-function. The argument @var{decl} is the @code{FUNCTION_DECL} tree node
-representing the function.
-
-If this macro is not defined, then the function size is not defined.
-
-You may wish to use @code{ASM_OUTPUT_MEASURED_SIZE} in the definition
-of this macro.
-@end defmac
-
-@defmac ASM_DECLARE_COLD_FUNCTION_NAME (@var{stream}, @var{name}, @var{decl})
-A C statement (sans semicolon) to output to the stdio stream
-@var{stream} any text necessary for declaring the name @var{name} of a
-cold function partition which is being defined. This macro is responsible
-for outputting the label definition (perhaps using
-@code{ASM_OUTPUT_FUNCTION_LABEL}). The argument @var{decl} is the
-@code{FUNCTION_DECL} tree node representing the function.
-
-If this macro is not defined, then the cold partition name is defined in the
-usual manner as a label (by means of @code{ASM_OUTPUT_LABEL}).
-
-You may wish to use @code{ASM_OUTPUT_TYPE_DIRECTIVE} in the definition
-of this macro.
-@end defmac
-
-@defmac ASM_DECLARE_COLD_FUNCTION_SIZE (@var{stream}, @var{name}, @var{decl})
-A C statement (sans semicolon) to output to the stdio stream
-@var{stream} any text necessary for declaring the size of a cold function
-partition which is being defined. The argument @var{name} is the name of the
-cold partition of the function. The argument @var{decl} is the
-@code{FUNCTION_DECL} tree node representing the function.
-
-If this macro is not defined, then the partition size is not defined.
-
-You may wish to use @code{ASM_OUTPUT_MEASURED_SIZE} in the definition
-of this macro.
-@end defmac
-
-@defmac ASM_DECLARE_OBJECT_NAME (@var{stream}, @var{name}, @var{decl})
-A C statement (sans semicolon) to output to the stdio stream
-@var{stream} any text necessary for declaring the name @var{name} of an
-initialized variable which is being defined. This macro must output the
-label definition (perhaps using @code{ASM_OUTPUT_LABEL}). The argument
-@var{decl} is the @code{VAR_DECL} tree node representing the variable.
-
-If this macro is not defined, then the variable name is defined in the
-usual manner as a label (by means of @code{ASM_OUTPUT_LABEL}).
-
-You may wish to use @code{ASM_OUTPUT_TYPE_DIRECTIVE} and/or
-@code{ASM_OUTPUT_SIZE_DIRECTIVE} in the definition of this macro.
-@end defmac
-
-@deftypefn {Target Hook} void TARGET_ASM_DECLARE_CONSTANT_NAME (FILE *@var{file}, const char *@var{name}, const_tree @var{expr}, HOST_WIDE_INT @var{size})
-A target hook to output to the stdio stream @var{file} any text necessary
-for declaring the name @var{name} of a constant which is being defined. This
-target hook is responsible for outputting the label definition (perhaps using
-@code{assemble_label}). The argument @var{exp} is the value of the constant,
-and @var{size} is the size of the constant in bytes. The @var{name}
-will be an internal label.
-
-The default version of this target hook, define the @var{name} in the
-usual manner as a label (by means of @code{assemble_label}).
-
-You may wish to use @code{ASM_OUTPUT_TYPE_DIRECTIVE} in this target hook.
-@end deftypefn
-
-@defmac ASM_DECLARE_REGISTER_GLOBAL (@var{stream}, @var{decl}, @var{regno}, @var{name})
-A C statement (sans semicolon) to output to the stdio stream
-@var{stream} any text necessary for claiming a register @var{regno}
-for a global variable @var{decl} with name @var{name}.
-
-If you don't define this macro, that is equivalent to defining it to do
-nothing.
-@end defmac
-
-@defmac ASM_FINISH_DECLARE_OBJECT (@var{stream}, @var{decl}, @var{toplevel}, @var{atend})
-A C statement (sans semicolon) to finish up declaring a variable name
-once the compiler has processed its initializer fully and thus has had a
-chance to determine the size of an array when controlled by an
-initializer. This is used on systems where it's necessary to declare
-something about the size of the object.
-
-If you don't define this macro, that is equivalent to defining it to do
-nothing.
-
-You may wish to use @code{ASM_OUTPUT_SIZE_DIRECTIVE} and/or
-@code{ASM_OUTPUT_MEASURED_SIZE} in the definition of this macro.
-@end defmac
-
-@deftypefn {Target Hook} void TARGET_ASM_GLOBALIZE_LABEL (FILE *@var{stream}, const char *@var{name})
-This target hook is a function to output to the stdio stream
-@var{stream} some commands that will make the label @var{name} global;
-that is, available for reference from other files.
-
-The default implementation relies on a proper definition of
-@code{GLOBAL_ASM_OP}.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_ASM_GLOBALIZE_DECL_NAME (FILE *@var{stream}, tree @var{decl})
-This target hook is a function to output to the stdio stream
-@var{stream} some commands that will make the name associated with @var{decl}
-global; that is, available for reference from other files.
-
-The default implementation uses the TARGET_ASM_GLOBALIZE_LABEL target hook.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_ASM_ASSEMBLE_UNDEFINED_DECL (FILE *@var{stream}, const char *@var{name}, const_tree @var{decl})
-This target hook is a function to output to the stdio stream
-@var{stream} some commands that will declare the name associated with
-@var{decl} which is not defined in the current translation unit. Most
-assemblers do not require anything to be output in this case.
-@end deftypefn
-
-@defmac ASM_WEAKEN_LABEL (@var{stream}, @var{name})
-A C statement (sans semicolon) to output to the stdio stream
-@var{stream} some commands that will make the label @var{name} weak;
-that is, available for reference from other files but only used if
-no other definition is available. Use the expression
-@code{assemble_name (@var{stream}, @var{name})} to output the name
-itself; before and after that, output the additional assembler syntax
-for making that name weak, and a newline.
-
-If you don't define this macro or @code{ASM_WEAKEN_DECL}, GCC will not
-support weak symbols and you should not define the @code{SUPPORTS_WEAK}
-macro.
-@end defmac
-
-@defmac ASM_WEAKEN_DECL (@var{stream}, @var{decl}, @var{name}, @var{value})
-Combines (and replaces) the function of @code{ASM_WEAKEN_LABEL} and
-@code{ASM_OUTPUT_WEAK_ALIAS}, allowing access to the associated function
-or variable decl. If @var{value} is not @code{NULL}, this C statement
-should output to the stdio stream @var{stream} assembler code which
-defines (equates) the weak symbol @var{name} to have the value
-@var{value}. If @var{value} is @code{NULL}, it should output commands
-to make @var{name} weak.
-@end defmac
-
-@defmac ASM_OUTPUT_WEAKREF (@var{stream}, @var{decl}, @var{name}, @var{value})
-Outputs a directive that enables @var{name} to be used to refer to
-symbol @var{value} with weak-symbol semantics. @code{decl} is the
-declaration of @code{name}.
-@end defmac
-
-@defmac SUPPORTS_WEAK
-A preprocessor constant expression which evaluates to true if the target
-supports weak symbols.
-
-If you don't define this macro, @file{defaults.h} provides a default
-definition. If either @code{ASM_WEAKEN_LABEL} or @code{ASM_WEAKEN_DECL}
-is defined, the default definition is @samp{1}; otherwise, it is @samp{0}.
-@end defmac
-
-@defmac TARGET_SUPPORTS_WEAK
-A C expression which evaluates to true if the target supports weak symbols.
-
-If you don't define this macro, @file{defaults.h} provides a default
-definition. The default definition is @samp{(SUPPORTS_WEAK)}. Define
-this macro if you want to control weak symbol support with a compiler
-flag such as @option{-melf}.
-@end defmac
-
-@defmac MAKE_DECL_ONE_ONLY (@var{decl})
-A C statement (sans semicolon) to mark @var{decl} to be emitted as a
-public symbol such that extra copies in multiple translation units will
-be discarded by the linker. Define this macro if your object file
-format provides support for this concept, such as the @samp{COMDAT}
-section flags in the Microsoft Windows PE/COFF format, and this support
-requires changes to @var{decl}, such as putting it in a separate section.
-@end defmac
-
-@defmac SUPPORTS_ONE_ONLY
-A C expression which evaluates to true if the target supports one-only
-semantics.
-
-If you don't define this macro, @file{varasm.cc} provides a default
-definition. If @code{MAKE_DECL_ONE_ONLY} is defined, the default
-definition is @samp{1}; otherwise, it is @samp{0}. Define this macro if
-you want to control one-only symbol support with a compiler flag, or if
-setting the @code{DECL_ONE_ONLY} flag is enough to mark a declaration to
-be emitted as one-only.
-@end defmac
-
-@deftypefn {Target Hook} void TARGET_ASM_ASSEMBLE_VISIBILITY (tree @var{decl}, int @var{visibility})
-This target hook is a function to output to @var{asm_out_file} some
-commands that will make the symbol(s) associated with @var{decl} have
-hidden, protected or internal visibility as specified by @var{visibility}.
-@end deftypefn
-
-@defmac TARGET_WEAK_NOT_IN_ARCHIVE_TOC
-A C expression that evaluates to true if the target's linker expects
-that weak symbols do not appear in a static archive's table of contents.
-The default is @code{0}.
-
-Leaving weak symbols out of an archive's table of contents means that,
-if a symbol will only have a definition in one translation unit and
-will have undefined references from other translation units, that
-symbol should not be weak. Defining this macro to be nonzero will
-thus have the effect that certain symbols that would normally be weak
-(explicit template instantiations, and vtables for polymorphic classes
-with noninline key methods) will instead be nonweak.
-
-The C++ ABI requires this macro to be zero. Define this macro for
-targets where full C++ ABI compliance is impossible and where linker
-restrictions require weak symbols to be left out of a static archive's
-table of contents.
-@end defmac
-
-@defmac ASM_OUTPUT_EXTERNAL (@var{stream}, @var{decl}, @var{name})
-A C statement (sans semicolon) to output to the stdio stream
-@var{stream} any text necessary for declaring the name of an external
-symbol named @var{name} which is referenced in this compilation but
-not defined. The value of @var{decl} is the tree node for the
-declaration.
-
-This macro need not be defined if it does not need to output anything.
-The GNU assembler and most Unix assemblers don't require anything.
-@end defmac
-
-@deftypefn {Target Hook} void TARGET_ASM_EXTERNAL_LIBCALL (rtx @var{symref})
-This target hook is a function to output to @var{asm_out_file} an assembler
-pseudo-op to declare a library function name external. The name of the
-library function is given by @var{symref}, which is a @code{symbol_ref}.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_ASM_MARK_DECL_PRESERVED (const char *@var{symbol})
-This target hook is a function to output to @var{asm_out_file} an assembler
-directive to annotate @var{symbol} as used. The Darwin target uses the
-.no_dead_code_strip directive.
-@end deftypefn
-
-@defmac ASM_OUTPUT_LABELREF (@var{stream}, @var{name})
-A C statement (sans semicolon) to output to the stdio stream
-@var{stream} a reference in assembler syntax to a label named
-@var{name}. This should add @samp{_} to the front of the name, if that
-is customary on your operating system, as it is in most Berkeley Unix
-systems. This macro is used in @code{assemble_name}.
-@end defmac
-
-@deftypefn {Target Hook} tree TARGET_MANGLE_ASSEMBLER_NAME (const char *@var{name})
-Given a symbol @var{name}, perform same mangling as @code{varasm.cc}'s
-@code{assemble_name}, but in memory rather than to a file stream, returning
-result as an @code{IDENTIFIER_NODE}. Required for correct LTO symtabs. The
-default implementation calls the @code{TARGET_STRIP_NAME_ENCODING} hook and
-then prepends the @code{USER_LABEL_PREFIX}, if any.
-@end deftypefn
-
-@defmac ASM_OUTPUT_SYMBOL_REF (@var{stream}, @var{sym})
-A C statement (sans semicolon) to output a reference to
-@code{SYMBOL_REF} @var{sym}. If not defined, @code{assemble_name}
-will be used to output the name of the symbol. This macro may be used
-to modify the way a symbol is referenced depending on information
-encoded by @code{TARGET_ENCODE_SECTION_INFO}.
-@end defmac
-
-@defmac ASM_OUTPUT_LABEL_REF (@var{stream}, @var{buf})
-A C statement (sans semicolon) to output a reference to @var{buf}, the
-result of @code{ASM_GENERATE_INTERNAL_LABEL}. If not defined,
-@code{assemble_name} will be used to output the name of the symbol.
-This macro is not used by @code{output_asm_label}, or the @code{%l}
-specifier that calls it; the intention is that this macro should be set
-when it is necessary to output a label differently when its address is
-being taken.
-@end defmac
-
-@deftypefn {Target Hook} void TARGET_ASM_INTERNAL_LABEL (FILE *@var{stream}, const char *@var{prefix}, unsigned long @var{labelno})
-A function to output to the stdio stream @var{stream} a label whose
-name is made from the string @var{prefix} and the number @var{labelno}.
-
-It is absolutely essential that these labels be distinct from the labels
-used for user-level functions and variables. Otherwise, certain programs
-will have name conflicts with internal labels.
-
-It is desirable to exclude internal labels from the symbol table of the
-object file. Most assemblers have a naming convention for labels that
-should be excluded; on many systems, the letter @samp{L} at the
-beginning of a label has this effect. You should find out what
-convention your system uses, and follow it.
-
-The default version of this function utilizes @code{ASM_GENERATE_INTERNAL_LABEL}.
-@end deftypefn
-
-@defmac ASM_OUTPUT_DEBUG_LABEL (@var{stream}, @var{prefix}, @var{num})
-A C statement to output to the stdio stream @var{stream} a debug info
-label whose name is made from the string @var{prefix} and the number
-@var{num}. This is useful for VLIW targets, where debug info labels
-may need to be treated differently than branch target labels. On some
-systems, branch target labels must be at the beginning of instruction
-bundles, but debug info labels can occur in the middle of instruction
-bundles.
-
-If this macro is not defined, then @code{(*targetm.asm_out.internal_label)} will be
-used.
-@end defmac
-
-@defmac ASM_GENERATE_INTERNAL_LABEL (@var{string}, @var{prefix}, @var{num})
-A C statement to store into the string @var{string} a label whose name
-is made from the string @var{prefix} and the number @var{num}.
-
-This string, when output subsequently by @code{assemble_name}, should
-produce the output that @code{(*targetm.asm_out.internal_label)} would produce
-with the same @var{prefix} and @var{num}.
-
-If the string begins with @samp{*}, then @code{assemble_name} will
-output the rest of the string unchanged. It is often convenient for
-@code{ASM_GENERATE_INTERNAL_LABEL} to use @samp{*} in this way. If the
-string doesn't start with @samp{*}, then @code{ASM_OUTPUT_LABELREF} gets
-to output the string, and may change it. (Of course,
-@code{ASM_OUTPUT_LABELREF} is also part of your machine description, so
-you should know what it does on your machine.)
-@end defmac
-
-@defmac ASM_FORMAT_PRIVATE_NAME (@var{outvar}, @var{name}, @var{number})
-A C expression to assign to @var{outvar} (which is a variable of type
-@code{char *}) a newly allocated string made from the string
-@var{name} and the number @var{number}, with some suitable punctuation
-added. Use @code{alloca} to get space for the string.
-
-The string will be used as an argument to @code{ASM_OUTPUT_LABELREF} to
-produce an assembler label for an internal static variable whose name is
-@var{name}. Therefore, the string must be such as to result in valid
-assembler code. The argument @var{number} is different each time this
-macro is executed; it prevents conflicts between similarly-named
-internal static variables in different scopes.
-
-Ideally this string should not be a valid C identifier, to prevent any
-conflict with the user's own symbols. Most assemblers allow periods
-or percent signs in assembler symbols; putting at least one of these
-between the name and the number will suffice.
-
-If this macro is not defined, a default definition will be provided
-which is correct for most systems.
-@end defmac
-
-@defmac ASM_OUTPUT_DEF (@var{stream}, @var{name}, @var{value})
-A C statement to output to the stdio stream @var{stream} assembler code
-which defines (equates) the symbol @var{name} to have the value @var{value}.
-
-@findex SET_ASM_OP
-If @code{SET_ASM_OP} is defined, a default definition is provided which is
-correct for most systems.
-@end defmac
-
-@defmac ASM_OUTPUT_DEF_FROM_DECLS (@var{stream}, @var{decl_of_name}, @var{decl_of_value})
-A C statement to output to the stdio stream @var{stream} assembler code
-which defines (equates) the symbol whose tree node is @var{decl_of_name}
-to have the value of the tree node @var{decl_of_value}. This macro will
-be used in preference to @samp{ASM_OUTPUT_DEF} if it is defined and if
-the tree nodes are available.
-
-@findex SET_ASM_OP
-If @code{SET_ASM_OP} is defined, a default definition is provided which is
-correct for most systems.
-@end defmac
-
-@defmac TARGET_DEFERRED_OUTPUT_DEFS (@var{decl_of_name}, @var{decl_of_value})
-A C statement that evaluates to true if the assembler code which defines
-(equates) the symbol whose tree node is @var{decl_of_name} to have the value
-of the tree node @var{decl_of_value} should be emitted near the end of the
-current compilation unit. The default is to not defer output of defines.
-This macro affects defines output by @samp{ASM_OUTPUT_DEF} and
-@samp{ASM_OUTPUT_DEF_FROM_DECLS}.
-@end defmac
-
-@defmac ASM_OUTPUT_WEAK_ALIAS (@var{stream}, @var{name}, @var{value})
-A C statement to output to the stdio stream @var{stream} assembler code
-which defines (equates) the weak symbol @var{name} to have the value
-@var{value}. If @var{value} is @code{NULL}, it defines @var{name} as
-an undefined weak symbol.
-
-Define this macro if the target only supports weak aliases; define
-@code{ASM_OUTPUT_DEF} instead if possible.
-@end defmac
-
-@defmac OBJC_GEN_METHOD_LABEL (@var{buf}, @var{is_inst}, @var{class_name}, @var{cat_name}, @var{sel_name})
-Define this macro to override the default assembler names used for
-Objective-C methods.
-
-The default name is a unique method number followed by the name of the
-class (e.g.@: @samp{_1_Foo}). For methods in categories, the name of
-the category is also included in the assembler name (e.g.@:
-@samp{_1_Foo_Bar}).
-
-These names are safe on most systems, but make debugging difficult since
-the method's selector is not present in the name. Therefore, particular
-systems define other ways of computing names.
-
-@var{buf} is an expression of type @code{char *} which gives you a
-buffer in which to store the name; its length is as long as
-@var{class_name}, @var{cat_name} and @var{sel_name} put together, plus
-50 characters extra.
-
-The argument @var{is_inst} specifies whether the method is an instance
-method or a class method; @var{class_name} is the name of the class;
-@var{cat_name} is the name of the category (or @code{NULL} if the method is not
-in a category); and @var{sel_name} is the name of the selector.
-
-On systems where the assembler can handle quoted names, you can use this
-macro to provide more human-readable names.
-@end defmac
-
-@node Initialization
-@subsection How Initialization Functions Are Handled
-@cindex initialization routines
-@cindex termination routines
-@cindex constructors, output of
-@cindex destructors, output of
-
-The compiled code for certain languages includes @dfn{constructors}
-(also called @dfn{initialization routines})---functions to initialize
-data in the program when the program is started. These functions need
-to be called before the program is ``started''---that is to say, before
-@code{main} is called.
-
-Compiling some languages generates @dfn{destructors} (also called
-@dfn{termination routines}) that should be called when the program
-terminates.
-
-To make the initialization and termination functions work, the compiler
-must output something in the assembler code to cause those functions to
-be called at the appropriate time. When you port the compiler to a new
-system, you need to specify how to do this.
-
-There are two major ways that GCC currently supports the execution of
-initialization and termination functions. Each way has two variants.
-Much of the structure is common to all four variations.
-
-@findex __CTOR_LIST__
-@findex __DTOR_LIST__
-The linker must build two lists of these functions---a list of
-initialization functions, called @code{__CTOR_LIST__}, and a list of
-termination functions, called @code{__DTOR_LIST__}.
-
-Each list always begins with an ignored function pointer (which may hold
-0, @minus{}1, or a count of the function pointers after it, depending on
-the environment). This is followed by a series of zero or more function
-pointers to constructors (or destructors), followed by a function
-pointer containing zero.
-
-Depending on the operating system and its executable file format, either
-@file{crtstuff.c} or @file{libgcc2.c} traverses these lists at startup
-time and exit time. Constructors are called in reverse order of the
-list; destructors in forward order.
-
-The best way to handle static constructors works only for object file
-formats which provide arbitrarily-named sections. A section is set
-aside for a list of constructors, and another for a list of destructors.
-Traditionally these are called @samp{.ctors} and @samp{.dtors}. Each
-object file that defines an initialization function also puts a word in
-the constructor section to point to that function. The linker
-accumulates all these words into one contiguous @samp{.ctors} section.
-Termination functions are handled similarly.
-
-This method will be chosen as the default by @file{target-def.h} if
-@code{TARGET_ASM_NAMED_SECTION} is defined. A target that does not
-support arbitrary sections, but does support special designated
-constructor and destructor sections may define @code{CTORS_SECTION_ASM_OP}
-and @code{DTORS_SECTION_ASM_OP} to achieve the same effect.
-
-When arbitrary sections are available, there are two variants, depending
-upon how the code in @file{crtstuff.c} is called. On systems that
-support a @dfn{.init} section which is executed at program startup,
-parts of @file{crtstuff.c} are compiled into that section. The
-program is linked by the @command{gcc} driver like this:
-
-@smallexample
-ld -o @var{output_file} crti.o crtbegin.o @dots{} -lgcc crtend.o crtn.o
-@end smallexample
-
-The prologue of a function (@code{__init}) appears in the @code{.init}
-section of @file{crti.o}; the epilogue appears in @file{crtn.o}. Likewise
-for the function @code{__fini} in the @dfn{.fini} section. Normally these
-files are provided by the operating system or by the GNU C library, but
-are provided by GCC for a few targets.
-
-The objects @file{crtbegin.o} and @file{crtend.o} are (for most targets)
-compiled from @file{crtstuff.c}. They contain, among other things, code
-fragments within the @code{.init} and @code{.fini} sections that branch
-to routines in the @code{.text} section. The linker will pull all parts
-of a section together, which results in a complete @code{__init} function
-that invokes the routines we need at startup.
-
-To use this variant, you must define the @code{INIT_SECTION_ASM_OP}
-macro properly.
-
-If no init section is available, when GCC compiles any function called
-@code{main} (or more accurately, any function designated as a program
-entry point by the language front end calling @code{expand_main_function}),
-it inserts a procedure call to @code{__main} as the first executable code
-after the function prologue. The @code{__main} function is defined
-in @file{libgcc2.c} and runs the global constructors.
-
-In file formats that don't support arbitrary sections, there are again
-two variants. In the simplest variant, the GNU linker (GNU @code{ld})
-and an `a.out' format must be used. In this case,
-@code{TARGET_ASM_CONSTRUCTOR} is defined to produce a @code{.stabs}
-entry of type @samp{N_SETT}, referencing the name @code{__CTOR_LIST__},
-and with the address of the void function containing the initialization
-code as its value. The GNU linker recognizes this as a request to add
-the value to a @dfn{set}; the values are accumulated, and are eventually
-placed in the executable as a vector in the format described above, with
-a leading (ignored) count and a trailing zero element.
-@code{TARGET_ASM_DESTRUCTOR} is handled similarly. Since no init
-section is available, the absence of @code{INIT_SECTION_ASM_OP} causes
-the compilation of @code{main} to call @code{__main} as above, starting
-the initialization process.
-
-The last variant uses neither arbitrary sections nor the GNU linker.
-This is preferable when you want to do dynamic linking and when using
-file formats which the GNU linker does not support, such as `ECOFF'@. In
-this case, @code{TARGET_HAVE_CTORS_DTORS} is false, initialization and
-termination functions are recognized simply by their names. This requires
-an extra program in the linkage step, called @command{collect2}. This program
-pretends to be the linker, for use with GCC; it does its job by running
-the ordinary linker, but also arranges to include the vectors of
-initialization and termination functions. These functions are called
-via @code{__main} as described above. In order to use this method,
-@code{use_collect2} must be defined in the target in @file{config.gcc}.
-
-@ifinfo
-The following section describes the specific macros that control and
-customize the handling of initialization and termination functions.
-@end ifinfo
-
-@node Macros for Initialization
-@subsection Macros Controlling Initialization Routines
-
-Here are the macros that control how the compiler handles initialization
-and termination functions:
-
-@defmac INIT_SECTION_ASM_OP
-If defined, a C string constant, including spacing, for the assembler
-operation to identify the following data as initialization code. If not
-defined, GCC will assume such a section does not exist. When you are
-using special sections for initialization and termination functions, this
-macro also controls how @file{crtstuff.c} and @file{libgcc2.c} arrange to
-run the initialization functions.
-@end defmac
-
-@defmac HAS_INIT_SECTION
-If defined, @code{main} will not call @code{__main} as described above.
-This macro should be defined for systems that control start-up code
-on a symbol-by-symbol basis, such as OSF/1, and should not
-be defined explicitly for systems that support @code{INIT_SECTION_ASM_OP}.
-@end defmac
-
-@defmac LD_INIT_SWITCH
-If defined, a C string constant for a switch that tells the linker that
-the following symbol is an initialization routine.
-@end defmac
-
-@defmac LD_FINI_SWITCH
-If defined, a C string constant for a switch that tells the linker that
-the following symbol is a finalization routine.
-@end defmac
-
-@defmac COLLECT_SHARED_INIT_FUNC (@var{stream}, @var{func})
-If defined, a C statement that will write a function that can be
-automatically called when a shared library is loaded. The function
-should call @var{func}, which takes no arguments. If not defined, and
-the object format requires an explicit initialization function, then a
-function called @code{_GLOBAL__DI} will be generated.
-
-This function and the following one are used by collect2 when linking a
-shared library that needs constructors or destructors, or has DWARF2
-exception tables embedded in the code.
-@end defmac
-
-@defmac COLLECT_SHARED_FINI_FUNC (@var{stream}, @var{func})
-If defined, a C statement that will write a function that can be
-automatically called when a shared library is unloaded. The function
-should call @var{func}, which takes no arguments. If not defined, and
-the object format requires an explicit finalization function, then a
-function called @code{_GLOBAL__DD} will be generated.
-@end defmac
-
-@defmac INVOKE__main
-If defined, @code{main} will call @code{__main} despite the presence of
-@code{INIT_SECTION_ASM_OP}. This macro should be defined for systems
-where the init section is not actually run automatically, but is still
-useful for collecting the lists of constructors and destructors.
-@end defmac
-
-@defmac SUPPORTS_INIT_PRIORITY
-If nonzero, the C++ @code{init_priority} attribute is supported and the
-compiler should emit instructions to control the order of initialization
-of objects. If zero, the compiler will issue an error message upon
-encountering an @code{init_priority} attribute.
-@end defmac
-
-@deftypevr {Target Hook} bool TARGET_HAVE_CTORS_DTORS
-This value is true if the target supports some ``native'' method of
-collecting constructors and destructors to be run at startup and exit.
-It is false if we must use @command{collect2}.
-@end deftypevr
-
-@deftypevr {Target Hook} bool TARGET_DTORS_FROM_CXA_ATEXIT
-This value is true if the target wants destructors to be queued to be
-run from __cxa_atexit. If this is the case then, for each priority level,
-a new constructor will be entered that registers the destructors for that
-level with __cxa_atexit (and there will be no destructors emitted).
-It is false the method implied by @code{have_ctors_dtors} is used.
-@end deftypevr
-
-@deftypefn {Target Hook} void TARGET_ASM_CONSTRUCTOR (rtx @var{symbol}, int @var{priority})
-If defined, a function that outputs assembler code to arrange to call
-the function referenced by @var{symbol} at initialization time.
-
-Assume that @var{symbol} is a @code{SYMBOL_REF} for a function taking
-no arguments and with no return value. If the target supports initialization
-priorities, @var{priority} is a value between 0 and @code{MAX_INIT_PRIORITY};
-otherwise it must be @code{DEFAULT_INIT_PRIORITY}.
-
-If this macro is not defined by the target, a suitable default will
-be chosen if (1) the target supports arbitrary section names, (2) the
-target defines @code{CTORS_SECTION_ASM_OP}, or (3) @code{USE_COLLECT2}
-is not defined.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_ASM_DESTRUCTOR (rtx @var{symbol}, int @var{priority})
-This is like @code{TARGET_ASM_CONSTRUCTOR} but used for termination
-functions rather than initialization functions.
-@end deftypefn
-
-If @code{TARGET_HAVE_CTORS_DTORS} is true, the initialization routine
-generated for the generated object file will have static linkage.
-
-If your system uses @command{collect2} as the means of processing
-constructors, then that program normally uses @command{nm} to scan
-an object file for constructor functions to be called.
-
-On certain kinds of systems, you can define this macro to make
-@command{collect2} work faster (and, in some cases, make it work at all):
-
-@defmac OBJECT_FORMAT_COFF
-Define this macro if the system uses COFF (Common Object File Format)
-object files, so that @command{collect2} can assume this format and scan
-object files directly for dynamic constructor/destructor functions.
-
-This macro is effective only in a native compiler; @command{collect2} as
-part of a cross compiler always uses @command{nm} for the target machine.
-@end defmac
-
-@defmac REAL_NM_FILE_NAME
-Define this macro as a C string constant containing the file name to use
-to execute @command{nm}. The default is to search the path normally for
-@command{nm}.
-@end defmac
-
-@defmac NM_FLAGS
-@command{collect2} calls @command{nm} to scan object files for static
-constructors and destructors and LTO info. By default, @option{-n} is
-passed. Define @code{NM_FLAGS} to a C string constant if other options
-are needed to get the same output format as GNU @command{nm -n}
-produces.
-@end defmac
-
-If your system supports shared libraries and has a program to list the
-dynamic dependencies of a given library or executable, you can define
-these macros to enable support for running initialization and
-termination functions in shared libraries:
-
-@defmac LDD_SUFFIX
-Define this macro to a C string constant containing the name of the program
-which lists dynamic dependencies, like @command{ldd} under SunOS 4.
-@end defmac
-
-@defmac PARSE_LDD_OUTPUT (@var{ptr})
-Define this macro to be C code that extracts filenames from the output
-of the program denoted by @code{LDD_SUFFIX}. @var{ptr} is a variable
-of type @code{char *} that points to the beginning of a line of output
-from @code{LDD_SUFFIX}. If the line lists a dynamic dependency, the
-code must advance @var{ptr} to the beginning of the filename on that
-line. Otherwise, it must set @var{ptr} to @code{NULL}.
-@end defmac
-
-@defmac SHLIB_SUFFIX
-Define this macro to a C string constant containing the default shared
-library extension of the target (e.g., @samp{".so"}). @command{collect2}
-strips version information after this suffix when generating global
-constructor and destructor names. This define is only needed on targets
-that use @command{collect2} to process constructors and destructors.
-@end defmac
-
-@node Instruction Output
-@subsection Output of Assembler Instructions
-
-@c prevent bad page break with this line
-This describes assembler instruction output.
-
-@defmac REGISTER_NAMES
-A C initializer containing the assembler's names for the machine
-registers, each one as a C string constant. This is what translates
-register numbers in the compiler into assembler language.
-@end defmac
-
-@defmac ADDITIONAL_REGISTER_NAMES
-If defined, a C initializer for an array of structures containing a name
-and a register number. This macro defines additional names for hard
-registers, thus allowing the @code{asm} option in declarations to refer
-to registers using alternate names.
-@end defmac
-
-@defmac OVERLAPPING_REGISTER_NAMES
-If defined, a C initializer for an array of structures containing a
-name, a register number and a count of the number of consecutive
-machine registers the name overlaps. This macro defines additional
-names for hard registers, thus allowing the @code{asm} option in
-declarations to refer to registers using alternate names. Unlike
-@code{ADDITIONAL_REGISTER_NAMES}, this macro should be used when the
-register name implies multiple underlying registers.
-
-This macro should be used when it is important that a clobber in an
-@code{asm} statement clobbers all the underlying values implied by the
-register name. For example, on ARM, clobbering the double-precision
-VFP register ``d0'' implies clobbering both single-precision registers
-``s0'' and ``s1''.
-@end defmac
-
-@defmac ASM_OUTPUT_OPCODE (@var{stream}, @var{ptr})
-Define this macro if you are using an unusual assembler that
-requires different names for the machine instructions.
-
-The definition is a C statement or statements which output an
-assembler instruction opcode to the stdio stream @var{stream}. The
-macro-operand @var{ptr} is a variable of type @code{char *} which
-points to the opcode name in its ``internal'' form---the form that is
-written in the machine description. The definition should output the
-opcode name to @var{stream}, performing any translation you desire, and
-increment the variable @var{ptr} to point at the end of the opcode
-so that it will not be output twice.
-
-In fact, your macro definition may process less than the entire opcode
-name, or more than the opcode name; but if you want to process text
-that includes @samp{%}-sequences to substitute operands, you must take
-care of the substitution yourself. Just be sure to increment
-@var{ptr} over whatever text should not be output normally.
-
-@findex recog_data.operand
-If you need to look at the operand values, they can be found as the
-elements of @code{recog_data.operand}.
-
-If the macro definition does nothing, the instruction is output
-in the usual way.
-@end defmac
-
-@defmac FINAL_PRESCAN_INSN (@var{insn}, @var{opvec}, @var{noperands})
-If defined, a C statement to be executed just prior to the output of
-assembler code for @var{insn}, to modify the extracted operands so
-they will be output differently.
-
-Here the argument @var{opvec} is the vector containing the operands
-extracted from @var{insn}, and @var{noperands} is the number of
-elements of the vector which contain meaningful data for this insn.
-The contents of this vector are what will be used to convert the insn
-template into assembler code, so you can change the assembler output
-by changing the contents of the vector.
-
-This macro is useful when various assembler syntaxes share a single
-file of instruction patterns; by defining this macro differently, you
-can cause a large class of instructions to be output differently (such
-as with rearranged operands). Naturally, variations in assembler
-syntax affecting individual insn patterns ought to be handled by
-writing conditional output routines in those patterns.
-
-If this macro is not defined, it is equivalent to a null statement.
-@end defmac
-
-@deftypefn {Target Hook} void TARGET_ASM_FINAL_POSTSCAN_INSN (FILE *@var{file}, rtx_insn *@var{insn}, rtx *@var{opvec}, int @var{noperands})
-If defined, this target hook is a function which is executed just after the
-output of assembler code for @var{insn}, to change the mode of the assembler
-if necessary.
-
-Here the argument @var{opvec} is the vector containing the operands
-extracted from @var{insn}, and @var{noperands} is the number of
-elements of the vector which contain meaningful data for this insn.
-The contents of this vector are what was used to convert the insn
-template into assembler code, so you can change the assembler mode
-by checking the contents of the vector.
-@end deftypefn
-
-@defmac PRINT_OPERAND (@var{stream}, @var{x}, @var{code})
-A C compound statement to output to stdio stream @var{stream} the
-assembler syntax for an instruction operand @var{x}. @var{x} is an
-RTL expression.
-
-@var{code} is a value that can be used to specify one of several ways
-of printing the operand. It is used when identical operands must be
-printed differently depending on the context. @var{code} comes from
-the @samp{%} specification that was used to request printing of the
-operand. If the specification was just @samp{%@var{digit}} then
-@var{code} is 0; if the specification was @samp{%@var{ltr}
-@var{digit}} then @var{code} is the ASCII code for @var{ltr}.
-
-@findex reg_names
-If @var{x} is a register, this macro should print the register's name.
-The names can be found in an array @code{reg_names} whose type is
-@code{char *[]}. @code{reg_names} is initialized from
-@code{REGISTER_NAMES}.
-
-When the machine description has a specification @samp{%@var{punct}}
-(a @samp{%} followed by a punctuation character), this macro is called
-with a null pointer for @var{x} and the punctuation character for
-@var{code}.
-@end defmac
-
-@defmac PRINT_OPERAND_PUNCT_VALID_P (@var{code})
-A C expression which evaluates to true if @var{code} is a valid
-punctuation character for use in the @code{PRINT_OPERAND} macro. If
-@code{PRINT_OPERAND_PUNCT_VALID_P} is not defined, it means that no
-punctuation characters (except for the standard one, @samp{%}) are used
-in this way.
-@end defmac
-
-@defmac PRINT_OPERAND_ADDRESS (@var{stream}, @var{x})
-A C compound statement to output to stdio stream @var{stream} the
-assembler syntax for an instruction operand that is a memory reference
-whose address is @var{x}. @var{x} is an RTL expression.
-
-@cindex @code{TARGET_ENCODE_SECTION_INFO} usage
-On some machines, the syntax for a symbolic address depends on the
-section that the address refers to. On these machines, define the hook
-@code{TARGET_ENCODE_SECTION_INFO} to store the information into the
-@code{symbol_ref}, and then check for it here. @xref{Assembler
-Format}.
-@end defmac
-
-@findex dbr_sequence_length
-@defmac DBR_OUTPUT_SEQEND (@var{file})
-A C statement, to be executed after all slot-filler instructions have
-been output. If necessary, call @code{dbr_sequence_length} to
-determine the number of slots filled in a sequence (zero if not
-currently outputting a sequence), to decide how many no-ops to output,
-or whatever.
-
-Don't define this macro if it has nothing to do, but it is helpful in
-reading assembly output if the extent of the delay sequence is made
-explicit (e.g.@: with white space).
-@end defmac
-
-@findex final_sequence
-Note that output routines for instructions with delay slots must be
-prepared to deal with not being output as part of a sequence
-(i.e.@: when the scheduling pass is not run, or when no slot fillers could be
-found.) The variable @code{final_sequence} is null when not
-processing a sequence, otherwise it contains the @code{sequence} rtx
-being output.
-
-@findex asm_fprintf
-@defmac REGISTER_PREFIX
-@defmacx LOCAL_LABEL_PREFIX
-@defmacx USER_LABEL_PREFIX
-@defmacx IMMEDIATE_PREFIX
-If defined, C string expressions to be used for the @samp{%R}, @samp{%L},
-@samp{%U}, and @samp{%I} options of @code{asm_fprintf} (see
-@file{final.cc}). These are useful when a single @file{md} file must
-support multiple assembler formats. In that case, the various @file{tm.h}
-files can define these macros differently.
-@end defmac
-
-@defmac ASM_FPRINTF_EXTENSIONS (@var{file}, @var{argptr}, @var{format})
-If defined this macro should expand to a series of @code{case}
-statements which will be parsed inside the @code{switch} statement of
-the @code{asm_fprintf} function. This allows targets to define extra
-printf formats which may useful when generating their assembler
-statements. Note that uppercase letters are reserved for future
-generic extensions to asm_fprintf, and so are not available to target
-specific code. The output file is given by the parameter @var{file}.
-The varargs input pointer is @var{argptr} and the rest of the format
-string, starting the character after the one that is being switched
-upon, is pointed to by @var{format}.
-@end defmac
-
-@defmac ASSEMBLER_DIALECT
-If your target supports multiple dialects of assembler language (such as
-different opcodes), define this macro as a C expression that gives the
-numeric index of the assembler language dialect to use, with zero as the
-first variant.
-
-If this macro is defined, you may use constructs of the form
-@smallexample
-@samp{@{option0|option1|option2@dots{}@}}
-@end smallexample
-@noindent
-in the output templates of patterns (@pxref{Output Template}) or in the
-first argument of @code{asm_fprintf}. This construct outputs
-@samp{option0}, @samp{option1}, @samp{option2}, etc., if the value of
-@code{ASSEMBLER_DIALECT} is zero, one, two, etc. Any special characters
-within these strings retain their usual meaning. If there are fewer
-alternatives within the braces than the value of
-@code{ASSEMBLER_DIALECT}, the construct outputs nothing. If it's needed
-to print curly braces or @samp{|} character in assembler output directly,
-@samp{%@{}, @samp{%@}} and @samp{%|} can be used.
-
-If you do not define this macro, the characters @samp{@{}, @samp{|} and
-@samp{@}} do not have any special meaning when used in templates or
-operands to @code{asm_fprintf}.
-
-Define the macros @code{REGISTER_PREFIX}, @code{LOCAL_LABEL_PREFIX},
-@code{USER_LABEL_PREFIX} and @code{IMMEDIATE_PREFIX} if you can express
-the variations in assembler language syntax with that mechanism. Define
-@code{ASSEMBLER_DIALECT} and use the @samp{@{option0|option1@}} syntax
-if the syntax variant are larger and involve such things as different
-opcodes or operand order.
-@end defmac
-
-@defmac ASM_OUTPUT_REG_PUSH (@var{stream}, @var{regno})
-A C expression to output to @var{stream} some assembler code
-which will push hard register number @var{regno} onto the stack.
-The code need not be optimal, since this macro is used only when
-profiling.
-@end defmac
-
-@defmac ASM_OUTPUT_REG_POP (@var{stream}, @var{regno})
-A C expression to output to @var{stream} some assembler code
-which will pop hard register number @var{regno} off of the stack.
-The code need not be optimal, since this macro is used only when
-profiling.
-@end defmac
-
-@node Dispatch Tables
-@subsection Output of Dispatch Tables
-
-@c prevent bad page break with this line
-This concerns dispatch tables.
-
-@cindex dispatch table
-@defmac ASM_OUTPUT_ADDR_DIFF_ELT (@var{stream}, @var{body}, @var{value}, @var{rel})
-A C statement to output to the stdio stream @var{stream} an assembler
-pseudo-instruction to generate a difference between two labels.
-@var{value} and @var{rel} are the numbers of two internal labels. The
-definitions of these labels are output using
-@code{(*targetm.asm_out.internal_label)}, and they must be printed in the same
-way here. For example,
-
-@smallexample
-fprintf (@var{stream}, "\t.word L%d-L%d\n",
- @var{value}, @var{rel})
-@end smallexample
-
-You must provide this macro on machines where the addresses in a
-dispatch table are relative to the table's own address. If defined, GCC
-will also use this macro on all machines when producing PIC@.
-@var{body} is the body of the @code{ADDR_DIFF_VEC}; it is provided so that the
-mode and flags can be read.
-@end defmac
-
-@defmac ASM_OUTPUT_ADDR_VEC_ELT (@var{stream}, @var{value})
-This macro should be provided on machines where the addresses
-in a dispatch table are absolute.
-
-The definition should be a C statement to output to the stdio stream
-@var{stream} an assembler pseudo-instruction to generate a reference to
-a label. @var{value} is the number of an internal label whose
-definition is output using @code{(*targetm.asm_out.internal_label)}.
-For example,
-
-@smallexample
-fprintf (@var{stream}, "\t.word L%d\n", @var{value})
-@end smallexample
-@end defmac
-
-@defmac ASM_OUTPUT_CASE_LABEL (@var{stream}, @var{prefix}, @var{num}, @var{table})
-Define this if the label before a jump-table needs to be output
-specially. The first three arguments are the same as for
-@code{(*targetm.asm_out.internal_label)}; the fourth argument is the
-jump-table which follows (a @code{jump_table_data} containing an
-@code{addr_vec} or @code{addr_diff_vec}).
-
-This feature is used on system V to output a @code{swbeg} statement
-for the table.
-
-If this macro is not defined, these labels are output with
-@code{(*targetm.asm_out.internal_label)}.
-@end defmac
-
-@defmac ASM_OUTPUT_CASE_END (@var{stream}, @var{num}, @var{table})
-Define this if something special must be output at the end of a
-jump-table. The definition should be a C statement to be executed
-after the assembler code for the table is written. It should write
-the appropriate code to stdio stream @var{stream}. The argument
-@var{table} is the jump-table insn, and @var{num} is the label-number
-of the preceding label.
-
-If this macro is not defined, nothing special is output at the end of
-the jump-table.
-@end defmac
-
-@deftypefn {Target Hook} void TARGET_ASM_POST_CFI_STARTPROC (FILE *@var{}, @var{tree})
-This target hook is used to emit assembly strings required by the target
-after the .cfi_startproc directive. The first argument is the file stream to
-write the strings to and the second argument is the function's declaration. The
-expected use is to add more .cfi_* directives.
-
-The default is to not output any assembly strings.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_ASM_EMIT_UNWIND_LABEL (FILE *@var{stream}, tree @var{decl}, int @var{for_eh}, int @var{empty})
-This target hook emits a label at the beginning of each FDE@. It
-should be defined on targets where FDEs need special labels, and it
-should write the appropriate label, for the FDE associated with the
-function declaration @var{decl}, to the stdio stream @var{stream}.
-The third argument, @var{for_eh}, is a boolean: true if this is for an
-exception table. The fourth argument, @var{empty}, is a boolean:
-true if this is a placeholder label for an omitted FDE@.
-
-The default is that FDEs are not given nonlocal labels.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_ASM_EMIT_EXCEPT_TABLE_LABEL (FILE *@var{stream})
-This target hook emits a label at the beginning of the exception table.
-It should be defined on targets where it is desirable for the table
-to be broken up according to function.
-
-The default is that no label is emitted.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_ASM_EMIT_EXCEPT_PERSONALITY (rtx @var{personality})
-If the target implements @code{TARGET_ASM_UNWIND_EMIT}, this hook may be
-used to emit a directive to install a personality hook into the unwind
-info. This hook should not be used if dwarf2 unwind info is used.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_ASM_UNWIND_EMIT (FILE *@var{stream}, rtx_insn *@var{insn})
-This target hook emits assembly directives required to unwind the
-given instruction. This is only used when @code{TARGET_EXCEPT_UNWIND_INFO}
-returns @code{UI_TARGET}.
-@end deftypefn
-
-@deftypefn {Target Hook} rtx TARGET_ASM_MAKE_EH_SYMBOL_INDIRECT (rtx @var{origsymbol}, bool @var{pubvis})
-If necessary, modify personality and LSDA references to handle indirection.
-The original symbol is in @code{origsymbol} and if @code{pubvis} is true
-the symbol is visible outside the TU.
-@end deftypefn
-
-@deftypevr {Target Hook} bool TARGET_ASM_UNWIND_EMIT_BEFORE_INSN
-True if the @code{TARGET_ASM_UNWIND_EMIT} hook should be called before
-the assembly for @var{insn} has been emitted, false if the hook should
-be called afterward.
-@end deftypevr
-
-@deftypefn {Target Hook} bool TARGET_ASM_SHOULD_RESTORE_CFA_STATE (void)
-For DWARF-based unwind frames, two CFI instructions provide for save and
-restore of register state. GCC maintains the current frame address (CFA)
-separately from the register bank but the unwinder in libgcc preserves this
-state along with the registers (and this is expected by the code that writes
-the unwind frames). This hook allows the target to specify that the CFA data
-is not saved/restored along with the registers by the target unwinder so that
-suitable additional instructions should be emitted to restore it.
-@end deftypefn
-
-@node Exception Region Output
-@subsection Assembler Commands for Exception Regions
-
-@c prevent bad page break with this line
-
-This describes commands marking the start and the end of an exception
-region.
-
-@defmac EH_FRAME_SECTION_NAME
-If defined, a C string constant for the name of the section containing
-exception handling frame unwind information. If not defined, GCC will
-provide a default definition if the target supports named sections.
-@file{crtstuff.c} uses this macro to switch to the appropriate section.
-
-You should define this symbol if your target supports DWARF 2 frame
-unwind information and the default definition does not work.
-@end defmac
-
-@defmac EH_FRAME_THROUGH_COLLECT2
-If defined, DWARF 2 frame unwind information will identified by
-specially named labels. The collect2 process will locate these
-labels and generate code to register the frames.
-
-This might be necessary, for instance, if the system linker will not
-place the eh_frames in-between the sentinals from @file{crtstuff.c},
-or if the system linker does garbage collection and sections cannot
-be marked as not to be collected.
-@end defmac
-
-@defmac EH_TABLES_CAN_BE_READ_ONLY
-Define this macro to 1 if your target is such that no frame unwind
-information encoding used with non-PIC code will ever require a
-runtime relocation, but the linker may not support merging read-only
-and read-write sections into a single read-write section.
-@end defmac
-
-@defmac MASK_RETURN_ADDR
-An rtx used to mask the return address found via @code{RETURN_ADDR_RTX}, so
-that it does not contain any extraneous set bits in it.
-@end defmac
-
-@defmac DWARF2_UNWIND_INFO
-Define this macro to 0 if your target supports DWARF 2 frame unwind
-information, but it does not yet work with exception handling.
-Otherwise, if your target supports this information (if it defines
-@code{INCOMING_RETURN_ADDR_RTX} and @code{OBJECT_FORMAT_ELF}),
-GCC will provide a default definition of 1.
-@end defmac
-
-@deftypefn {Common Target Hook} {enum unwind_info_type} TARGET_EXCEPT_UNWIND_INFO (struct gcc_options *@var{opts})
-This hook defines the mechanism that will be used for exception handling
-by the target. If the target has ABI specified unwind tables, the hook
-should return @code{UI_TARGET}. If the target is to use the
-@code{setjmp}/@code{longjmp}-based exception handling scheme, the hook
-should return @code{UI_SJLJ}. If the target supports DWARF 2 frame unwind
-information, the hook should return @code{UI_DWARF2}.
-
-A target may, if exceptions are disabled, choose to return @code{UI_NONE}.
-This may end up simplifying other parts of target-specific code. The
-default implementation of this hook never returns @code{UI_NONE}.
-
-Note that the value returned by this hook should be constant. It should
-not depend on anything except the command-line switches described by
-@var{opts}. In particular, the
-setting @code{UI_SJLJ} must be fixed at compiler start-up as C pre-processor
-macros and builtin functions related to exception handling are set up
-depending on this setting.
-
-The default implementation of the hook first honors the
-@option{--enable-sjlj-exceptions} configure option, then
-@code{DWARF2_UNWIND_INFO}, and finally defaults to @code{UI_SJLJ}. If
-@code{DWARF2_UNWIND_INFO} depends on command-line options, the target
-must define this hook so that @var{opts} is used correctly.
-@end deftypefn
-
-@deftypevr {Common Target Hook} bool TARGET_UNWIND_TABLES_DEFAULT
-This variable should be set to @code{true} if the target ABI requires unwinding
-tables even when exceptions are not used. It must not be modified by
-command-line option processing.
-@end deftypevr
-
-@defmac DONT_USE_BUILTIN_SETJMP
-Define this macro to 1 if the @code{setjmp}/@code{longjmp}-based scheme
-should use the @code{setjmp}/@code{longjmp} functions from the C library
-instead of the @code{__builtin_setjmp}/@code{__builtin_longjmp} machinery.
-@end defmac
-
-@defmac JMP_BUF_SIZE
-This macro has no effect unless @code{DONT_USE_BUILTIN_SETJMP} is also
-defined. Define this macro if the default size of @code{jmp_buf} buffer
-for the @code{setjmp}/@code{longjmp}-based exception handling mechanism
-is not large enough, or if it is much too large.
-The default size is @code{FIRST_PSEUDO_REGISTER * sizeof(void *)}.
-@end defmac
-
-@defmac DWARF_CIE_DATA_ALIGNMENT
-This macro need only be defined if the target might save registers in the
-function prologue at an offset to the stack pointer that is not aligned to
-@code{UNITS_PER_WORD}. The definition should be the negative minimum
-alignment if @code{STACK_GROWS_DOWNWARD} is true, and the positive
-minimum alignment otherwise. @xref{DWARF}. Only applicable if
-the target supports DWARF 2 frame unwind information.
-@end defmac
-
-@deftypevr {Target Hook} bool TARGET_TERMINATE_DW2_EH_FRAME_INFO
-Contains the value true if the target should add a zero word onto the
-end of a Dwarf-2 frame info section when used for exception handling.
-Default value is false if @code{EH_FRAME_SECTION_NAME} is defined, and
-true otherwise.
-@end deftypevr
-
-@deftypefn {Target Hook} rtx TARGET_DWARF_REGISTER_SPAN (rtx @var{reg})
-Given a register, this hook should return a parallel of registers to
-represent where to find the register pieces. Define this hook if the
-register and its mode are represented in Dwarf in non-contiguous
-locations, or if the register should be represented in more than one
-register in Dwarf. Otherwise, this hook should return @code{NULL_RTX}.
-If not defined, the default is to return @code{NULL_RTX}.
-@end deftypefn
-
-@deftypefn {Target Hook} machine_mode TARGET_DWARF_FRAME_REG_MODE (int @var{regno})
-Given a register, this hook should return the mode which the
-corresponding Dwarf frame register should have. This is normally
-used to return a smaller mode than the raw mode to prevent call
-clobbered parts of a register altering the frame register size
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_INIT_DWARF_REG_SIZES_EXTRA (tree @var{address})
-If some registers are represented in Dwarf-2 unwind information in
-multiple pieces, define this hook to fill in information about the
-sizes of those pieces in the table used by the unwinder at runtime.
-It will be called by @code{expand_builtin_init_dwarf_reg_sizes} after
-filling in a single size corresponding to each hard register;
-@var{address} is the address of the table.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_ASM_TTYPE (rtx @var{sym})
-This hook is used to output a reference from a frame unwinding table to
-the type_info object identified by @var{sym}. It should return @code{true}
-if the reference was output. Returning @code{false} will cause the
-reference to be output using the normal Dwarf2 routines.
-@end deftypefn
-
-@deftypevr {Target Hook} bool TARGET_ARM_EABI_UNWINDER
-This flag should be set to @code{true} on targets that use an ARM EABI
-based unwinding library, and @code{false} on other targets. This effects
-the format of unwinding tables, and how the unwinder in entered after
-running a cleanup. The default is @code{false}.
-@end deftypevr
-
-@node Alignment Output
-@subsection Assembler Commands for Alignment
-
-@c prevent bad page break with this line
-This describes commands for alignment.
-
-@defmac JUMP_ALIGN (@var{label})
-The alignment (log base 2) to put in front of @var{label}, which is
-a common destination of jumps and has no fallthru incoming edge.
-
-This macro need not be defined if you don't want any special alignment
-to be done at such a time. Most machine descriptions do not currently
-define the macro.
-
-Unless it's necessary to inspect the @var{label} parameter, it is better
-to set the variable @var{align_jumps} in the target's
-@code{TARGET_OPTION_OVERRIDE}. Otherwise, you should try to honor the user's
-selection in @var{align_jumps} in a @code{JUMP_ALIGN} implementation.
-@end defmac
-
-@defmac LABEL_ALIGN_AFTER_BARRIER (@var{label})
-The alignment (log base 2) to put in front of @var{label}, which follows
-a @code{BARRIER}.
-
-This macro need not be defined if you don't want any special alignment
-to be done at such a time. Most machine descriptions do not currently
-define the macro.
-@end defmac
-
-@defmac LOOP_ALIGN (@var{label})
-The alignment (log base 2) to put in front of @var{label} that heads
-a frequently executed basic block (usually the header of a loop).
-
-This macro need not be defined if you don't want any special alignment
-to be done at such a time. Most machine descriptions do not currently
-define the macro.
-
-Unless it's necessary to inspect the @var{label} parameter, it is better
-to set the variable @code{align_loops} in the target's
-@code{TARGET_OPTION_OVERRIDE}. Otherwise, you should try to honor the user's
-selection in @code{align_loops} in a @code{LOOP_ALIGN} implementation.
-@end defmac
-
-@defmac LABEL_ALIGN (@var{label})
-The alignment (log base 2) to put in front of @var{label}.
-If @code{LABEL_ALIGN_AFTER_BARRIER} / @code{LOOP_ALIGN} specify a different alignment,
-the maximum of the specified values is used.
-
-Unless it's necessary to inspect the @var{label} parameter, it is better
-to set the variable @code{align_labels} in the target's
-@code{TARGET_OPTION_OVERRIDE}. Otherwise, you should try to honor the user's
-selection in @code{align_labels} in a @code{LABEL_ALIGN} implementation.
-@end defmac
-
-@defmac ASM_OUTPUT_SKIP (@var{stream}, @var{nbytes})
-A C statement to output to the stdio stream @var{stream} an assembler
-instruction to advance the location counter by @var{nbytes} bytes.
-Those bytes should be zero when loaded. @var{nbytes} will be a C
-expression of type @code{unsigned HOST_WIDE_INT}.
-@end defmac
-
-@defmac ASM_NO_SKIP_IN_TEXT
-Define this macro if @code{ASM_OUTPUT_SKIP} should not be used in the
-text section because it fails to put zeros in the bytes that are skipped.
-This is true on many Unix systems, where the pseudo--op to skip bytes
-produces no-op instructions rather than zeros when used in the text
-section.
-@end defmac
-
-@defmac ASM_OUTPUT_ALIGN (@var{stream}, @var{power})
-A C statement to output to the stdio stream @var{stream} an assembler
-command to advance the location counter to a multiple of 2 to the
-@var{power} bytes. @var{power} will be a C expression of type @code{int}.
-@end defmac
-
-@defmac ASM_OUTPUT_ALIGN_WITH_NOP (@var{stream}, @var{power})
-Like @code{ASM_OUTPUT_ALIGN}, except that the ``nop'' instruction is used
-for padding, if necessary.
-@end defmac
-
-@defmac ASM_OUTPUT_MAX_SKIP_ALIGN (@var{stream}, @var{power}, @var{max_skip})
-A C statement to output to the stdio stream @var{stream} an assembler
-command to advance the location counter to a multiple of 2 to the
-@var{power} bytes, but only if @var{max_skip} or fewer bytes are needed to
-satisfy the alignment request. @var{power} and @var{max_skip} will be
-a C expression of type @code{int}.
-@end defmac
-
-@need 3000
-@node Debugging Info
-@section Controlling Debugging Information Format
-
-@c prevent bad page break with this line
-This describes how to specify debugging information.
-
-@menu
-* All Debuggers:: Macros that affect all debugging formats uniformly.
-* DWARF:: Macros for DWARF format.
-* VMS Debug:: Macros for VMS debug format.
-* CTF Debug:: Macros for CTF debug format.
-* BTF Debug:: Macros for BTF debug format.
-@end menu
-
-@node All Debuggers
-@subsection Macros Affecting All Debugging Formats
-
-@c prevent bad page break with this line
-These macros affect all debugging formats.
-
-@defmac DEBUGGER_REGNO (@var{regno})
-A C expression that returns the debugger register number for the compiler
-register number @var{regno}. In the default macro provided, the value
-of this expression will be @var{regno} itself. But sometimes there are
-some registers that the compiler knows about and debugger does not, or vice
-versa. In such cases, some register may need to have one number in the
-compiler and another for debugger@.
-
-If two registers have consecutive numbers inside GCC, and they can be
-used as a pair to hold a multiword value, then they @emph{must} have
-consecutive numbers after renumbering with @code{DEBUGGER_REGNO}.
-Otherwise, debuggers will be unable to access such a pair, because they
-expect register pairs to be consecutive in their own numbering scheme.
-
-If you find yourself defining @code{DEBUGGER_REGNO} in way that
-does not preserve register pairs, then what you must do instead is
-redefine the actual register numbering scheme.
-@end defmac
-
-@defmac DEBUGGER_AUTO_OFFSET (@var{x})
-A C expression that returns the integer offset value for an automatic
-variable having address @var{x} (an RTL expression). The default
-computation assumes that @var{x} is based on the frame-pointer and
-gives the offset from the frame-pointer. This is required for targets
-that produce debugging output for debugger and allow the frame-pointer to be
-eliminated when the @option{-g} option is used.
-@end defmac
-
-@defmac DEBUGGER_ARG_OFFSET (@var{offset}, @var{x})
-A C expression that returns the integer offset value for an argument
-having address @var{x} (an RTL expression). The nominal offset is
-@var{offset}.
-@end defmac
-
-@defmac PREFERRED_DEBUGGING_TYPE
-A C expression that returns the type of debugging output GCC should
-produce when the user specifies just @option{-g}. Define
-this if you have arranged for GCC to support more than one format of
-debugging output. Currently, the allowable values are
-@code{DWARF2_DEBUG}, @code{VMS_DEBUG},
-and @code{VMS_AND_DWARF2_DEBUG}.
-
-When the user specifies @option{-ggdb}, GCC normally also uses the
-value of this macro to select the debugging output format, but with two
-exceptions. If @code{DWARF2_DEBUGGING_INFO} is defined, GCC uses the
-value @code{DWARF2_DEBUG}.
-
-The value of this macro only affects the default debugging output; the
-user can always get a specific type of output by using @option{-gdwarf-2},
-or @option{-gvms}.
-@end defmac
-
-@defmac DEFAULT_GDB_EXTENSIONS
-Define this macro to control whether GCC should by default generate
-GDB's extended version of debugging information. If you don't define the
-macro, the default is 1: always generate the extended information
-if there is any occasion to.
-@end defmac
-
-@need 2000
-@node DWARF
-@subsection Macros for DWARF Output
-
-@c prevent bad page break with this line
-Here are macros for DWARF output.
-
-@defmac DWARF2_DEBUGGING_INFO
-Define this macro if GCC should produce dwarf version 2 format
-debugging output in response to the @option{-g} option.
-
-To support optional call frame debugging information, you must also
-define @code{INCOMING_RETURN_ADDR_RTX} and either set
-@code{RTX_FRAME_RELATED_P} on the prologue insns if you use RTL for the
-prologue, or call @code{dwarf2out_def_cfa} and @code{dwarf2out_reg_save}
-as appropriate from @code{TARGET_ASM_FUNCTION_PROLOGUE} if you don't.
-@end defmac
-
-@deftypefn {Target Hook} int TARGET_DWARF_CALLING_CONVENTION (const_tree @var{function})
-Define this to enable the dwarf attribute @code{DW_AT_calling_convention} to
-be emitted for each function. Instead of an integer return the enum
-value for the @code{DW_CC_} tag.
-@end deftypefn
-
-@defmac DWARF2_FRAME_INFO
-Define this macro to a nonzero value if GCC should always output
-Dwarf 2 frame information. If @code{TARGET_EXCEPT_UNWIND_INFO}
-(@pxref{Exception Region Output}) returns @code{UI_DWARF2}, and
-exceptions are enabled, GCC will output this information not matter
-how you define @code{DWARF2_FRAME_INFO}.
-@end defmac
-
-@deftypefn {Target Hook} {enum unwind_info_type} TARGET_DEBUG_UNWIND_INFO (void)
-This hook defines the mechanism that will be used for describing frame
-unwind information to the debugger. Normally the hook will return
-@code{UI_DWARF2} if DWARF 2 debug information is enabled, and
-return @code{UI_NONE} otherwise.
-
-A target may return @code{UI_DWARF2} even when DWARF 2 debug information
-is disabled in order to always output DWARF 2 frame information.
-
-A target may return @code{UI_TARGET} if it has ABI specified unwind tables.
-This will suppress generation of the normal debug frame unwind information.
-@end deftypefn
-
-@defmac DWARF2_ASM_LINE_DEBUG_INFO
-Define this macro to be a nonzero value if the assembler can generate Dwarf 2
-line debug info sections. This will result in much more compact line number
-tables, and hence is desirable if it works.
-@end defmac
-
-@defmac DWARF2_ASM_VIEW_DEBUG_INFO
-Define this macro to be a nonzero value if the assembler supports view
-assignment and verification in @code{.loc}. If it does not, but the
-user enables location views, the compiler may have to fallback to
-internal line number tables.
-@end defmac
-
-@deftypefn {Target Hook} int TARGET_RESET_LOCATION_VIEW (rtx_insn *@var{})
-This hook, if defined, enables -ginternal-reset-location-views, and
-uses its result to override cases in which the estimated min insn
-length might be nonzero even when a PC advance (i.e., a view reset)
-cannot be taken for granted.
-
-If the hook is defined, it must return a positive value to indicate
-the insn definitely advances the PC, and so the view number can be
-safely assumed to be reset; a negative value to mean the insn
-definitely does not advance the PC, and os the view number must not
-be reset; or zero to decide based on the estimated insn length.
-
-If insn length is to be regarded as reliable, set the hook to
-@code{hook_int_rtx_insn_0}.
-@end deftypefn
-
-@deftypevr {Target Hook} bool TARGET_WANT_DEBUG_PUB_SECTIONS
-True if the @code{.debug_pubtypes} and @code{.debug_pubnames} sections
-should be emitted. These sections are not used on most platforms, and
-in particular GDB does not use them.
-@end deftypevr
-
-@deftypevr {Target Hook} bool TARGET_DELAY_SCHED2
-True if sched2 is not to be run at its normal place.
-This usually means it will be run as part of machine-specific reorg.
-@end deftypevr
-
-@deftypevr {Target Hook} bool TARGET_DELAY_VARTRACK
-True if vartrack is not to be run at its normal place.
-This usually means it will be run as part of machine-specific reorg.
-@end deftypevr
-
-@deftypevr {Target Hook} bool TARGET_NO_REGISTER_ALLOCATION
-True if register allocation and the passes
-following it should not be run. Usually true only for virtual assembler
-targets.
-@end deftypevr
-
-@defmac ASM_OUTPUT_DWARF_DELTA (@var{stream}, @var{size}, @var{label1}, @var{label2})
-A C statement to issue assembly directives that create a difference
-@var{lab1} minus @var{lab2}, using an integer of the given @var{size}.
-@end defmac
-
-@defmac ASM_OUTPUT_DWARF_VMS_DELTA (@var{stream}, @var{size}, @var{label1}, @var{label2})
-A C statement to issue assembly directives that create a difference
-between the two given labels in system defined units, e.g.@: instruction
-slots on IA64 VMS, using an integer of the given size.
-@end defmac
-
-@defmac ASM_OUTPUT_DWARF_OFFSET (@var{stream}, @var{size}, @var{label}, @var{offset}, @var{section})
-A C statement to issue assembly directives that create a
-section-relative reference to the given @var{label} plus @var{offset}, using
-an integer of the given @var{size}. The label is known to be defined in the
-given @var{section}.
-@end defmac
-
-@defmac ASM_OUTPUT_DWARF_PCREL (@var{stream}, @var{size}, @var{label})
-A C statement to issue assembly directives that create a self-relative
-reference to the given @var{label}, using an integer of the given @var{size}.
-@end defmac
-
-@defmac ASM_OUTPUT_DWARF_DATAREL (@var{stream}, @var{size}, @var{label})
-A C statement to issue assembly directives that create a reference to the
-given @var{label} relative to the dbase, using an integer of the given @var{size}.
-@end defmac
-
-@defmac ASM_OUTPUT_DWARF_TABLE_REF (@var{label})
-A C statement to issue assembly directives that create a reference to
-the DWARF table identifier @var{label} from the current section. This
-is used on some systems to avoid garbage collecting a DWARF table which
-is referenced by a function.
-@end defmac
-
-@deftypefn {Target Hook} void TARGET_ASM_OUTPUT_DWARF_DTPREL (FILE *@var{file}, int @var{size}, rtx @var{x})
-If defined, this target hook is a function which outputs a DTP-relative
-reference to the given TLS symbol of the specified size.
-@end deftypefn
-
-@need 2000
-@node VMS Debug
-@subsection Macros for VMS Debug Format
-
-@c prevent bad page break with this line
-Here are macros for VMS debug format.
-
-@defmac VMS_DEBUGGING_INFO
-Define this macro if GCC should produce debugging output for VMS
-in response to the @option{-g} option. The default behavior for VMS
-is to generate minimal debug info for a traceback in the absence of
-@option{-g} unless explicitly overridden with @option{-g0}. This
-behavior is controlled by @code{TARGET_OPTION_OPTIMIZATION} and
-@code{TARGET_OPTION_OVERRIDE}.
-@end defmac
-
-@need 2000
-@node CTF Debug
-@subsection Macros for CTF Debug Format
-
-@c prevent bad page break with this line
-Here are macros for CTF debug format.
-
-@defmac CTF_DEBUGGING_INFO
-Define this macro if GCC should produce debugging output in CTF debug
-format in response to the @option{-gctf} option.
-@end defmac
-
-@need 2000
-@node BTF Debug
-@subsection Macros for BTF Debug Format
-
-@c prevent bad page break with this line
-Here are macros for BTF debug format.
-
-@defmac BTF_DEBUGGING_INFO
-Define this macro if GCC should produce debugging output in BTF debug
-format in response to the @option{-gbtf} option.
-@end defmac
-
-@node Floating Point
-@section Cross Compilation and Floating Point
-@cindex cross compilation and floating point
-@cindex floating point and cross compilation
-
-While all modern machines use twos-complement representation for integers,
-there are a variety of representations for floating point numbers. This
-means that in a cross-compiler the representation of floating point numbers
-in the compiled program may be different from that used in the machine
-doing the compilation.
-
-Because different representation systems may offer different amounts of
-range and precision, all floating point constants must be represented in
-the target machine's format. Therefore, the cross compiler cannot
-safely use the host machine's floating point arithmetic; it must emulate
-the target's arithmetic. To ensure consistency, GCC always uses
-emulation to work with floating point values, even when the host and
-target floating point formats are identical.
-
-The following macros are provided by @file{real.h} for the compiler to
-use. All parts of the compiler which generate or optimize
-floating-point calculations must use these macros. They may evaluate
-their operands more than once, so operands must not have side effects.
-
-@defmac REAL_VALUE_TYPE
-The C data type to be used to hold a floating point value in the target
-machine's format. Typically this is a @code{struct} containing an
-array of @code{HOST_WIDE_INT}, but all code should treat it as an opaque
-quantity.
-@end defmac
-
-@deftypefn Macro HOST_WIDE_INT REAL_VALUE_FIX (REAL_VALUE_TYPE @var{x})
-Truncates @var{x} to a signed integer, rounding toward zero.
-@end deftypefn
-
-@deftypefn Macro {unsigned HOST_WIDE_INT} REAL_VALUE_UNSIGNED_FIX (REAL_VALUE_TYPE @var{x})
-Truncates @var{x} to an unsigned integer, rounding toward zero. If
-@var{x} is negative, returns zero.
-@end deftypefn
-
-@deftypefn Macro REAL_VALUE_TYPE REAL_VALUE_ATOF (const char *@var{string}, machine_mode @var{mode})
-Converts @var{string} into a floating point number in the target machine's
-representation for mode @var{mode}. This routine can handle both
-decimal and hexadecimal floating point constants, using the syntax
-defined by the C language for both.
-@end deftypefn
-
-@deftypefn Macro int REAL_VALUE_NEGATIVE (REAL_VALUE_TYPE @var{x})
-Returns 1 if @var{x} is negative (including negative zero), 0 otherwise.
-@end deftypefn
-
-@deftypefn Macro int REAL_VALUE_ISINF (REAL_VALUE_TYPE @var{x})
-Determines whether @var{x} represents infinity (positive or negative).
-@end deftypefn
-
-@deftypefn Macro int REAL_VALUE_ISNAN (REAL_VALUE_TYPE @var{x})
-Determines whether @var{x} represents a ``NaN'' (not-a-number).
-@end deftypefn
-
-@deftypefn Macro REAL_VALUE_TYPE REAL_VALUE_NEGATE (REAL_VALUE_TYPE @var{x})
-Returns the negative of the floating point value @var{x}.
-@end deftypefn
-
-@deftypefn Macro REAL_VALUE_TYPE REAL_VALUE_ABS (REAL_VALUE_TYPE @var{x})
-Returns the absolute value of @var{x}.
-@end deftypefn
-
-@node Mode Switching
-@section Mode Switching Instructions
-@cindex mode switching
-The following macros control mode switching optimizations:
-
-@defmac OPTIMIZE_MODE_SWITCHING (@var{entity})
-Define this macro if the port needs extra instructions inserted for mode
-switching in an optimizing compilation.
-
-For an example, the SH4 can perform both single and double precision
-floating point operations, but to perform a single precision operation,
-the FPSCR PR bit has to be cleared, while for a double precision
-operation, this bit has to be set. Changing the PR bit requires a general
-purpose register as a scratch register, hence these FPSCR sets have to
-be inserted before reload, i.e.@: you cannot put this into instruction emitting
-or @code{TARGET_MACHINE_DEPENDENT_REORG}.
-
-You can have multiple entities that are mode-switched, and select at run time
-which entities actually need it. @code{OPTIMIZE_MODE_SWITCHING} should
-return nonzero for any @var{entity} that needs mode-switching.
-If you define this macro, you also have to define
-@code{NUM_MODES_FOR_MODE_SWITCHING}, @code{TARGET_MODE_NEEDED},
-@code{TARGET_MODE_PRIORITY} and @code{TARGET_MODE_EMIT}.
-@code{TARGET_MODE_AFTER}, @code{TARGET_MODE_ENTRY}, and @code{TARGET_MODE_EXIT}
-are optional.
-@end defmac
-
-@defmac NUM_MODES_FOR_MODE_SWITCHING
-If you define @code{OPTIMIZE_MODE_SWITCHING}, you have to define this as
-initializer for an array of integers. Each initializer element
-N refers to an entity that needs mode switching, and specifies the number
-of different modes that might need to be set for this entity.
-The position of the initializer in the initializer---starting counting at
-zero---determines the integer that is used to refer to the mode-switched
-entity in question.
-In macros that take mode arguments / yield a mode result, modes are
-represented as numbers 0 @dots{} N @minus{} 1. N is used to specify that no mode
-switch is needed / supplied.
-@end defmac
-
-@deftypefn {Target Hook} void TARGET_MODE_EMIT (int @var{entity}, int @var{mode}, int @var{prev_mode}, HARD_REG_SET @var{regs_live})
-Generate one or more insns to set @var{entity} to @var{mode}.
-@var{hard_reg_live} is the set of hard registers live at the point where
-the insn(s) are to be inserted. @var{prev_moxde} indicates the mode
-to switch from. Sets of a lower numbered entity will be emitted before
-sets of a higher numbered entity to a mode of the same or lower priority.
-@end deftypefn
-
-@deftypefn {Target Hook} int TARGET_MODE_NEEDED (int @var{entity}, rtx_insn *@var{insn})
-@var{entity} is an integer specifying a mode-switched entity.
-If @code{OPTIMIZE_MODE_SWITCHING} is defined, you must define this macro
-to return an integer value not larger than the corresponding element
-in @code{NUM_MODES_FOR_MODE_SWITCHING}, to denote the mode that @var{entity}
-must be switched into prior to the execution of @var{insn}.
-@end deftypefn
-
-@deftypefn {Target Hook} int TARGET_MODE_AFTER (int @var{entity}, int @var{mode}, rtx_insn *@var{insn})
-@var{entity} is an integer specifying a mode-switched entity.
-If this macro is defined, it is evaluated for every @var{insn} during mode
-switching. It determines the mode that an insn results
-in (if different from the incoming mode).
-@end deftypefn
-
-@deftypefn {Target Hook} int TARGET_MODE_ENTRY (int @var{entity})
-If this macro is defined, it is evaluated for every @var{entity} that
-needs mode switching. It should evaluate to an integer, which is a mode
-that @var{entity} is assumed to be switched to at function entry.
-If @code{TARGET_MODE_ENTRY} is defined then @code{TARGET_MODE_EXIT}
-must be defined.
-@end deftypefn
-
-@deftypefn {Target Hook} int TARGET_MODE_EXIT (int @var{entity})
-If this macro is defined, it is evaluated for every @var{entity} that
-needs mode switching. It should evaluate to an integer, which is a mode
-that @var{entity} is assumed to be switched to at function exit.
-If @code{TARGET_MODE_EXIT} is defined then @code{TARGET_MODE_ENTRY}
-must be defined.
-@end deftypefn
-
-@deftypefn {Target Hook} int TARGET_MODE_PRIORITY (int @var{entity}, int @var{n})
-This macro specifies the order in which modes for @var{entity}
-are processed. 0 is the highest priority,
-@code{NUM_MODES_FOR_MODE_SWITCHING[@var{entity}] - 1} the lowest.
-The value of the macro should be an integer designating a mode
-for @var{entity}. For any fixed @var{entity}, @code{mode_priority}
-(@var{entity}, @var{n}) shall be a bijection in 0 @dots{}
-@code{num_modes_for_mode_switching[@var{entity}] - 1}.
-@end deftypefn
-
-@node Target Attributes
-@section Defining target-specific uses of @code{__attribute__}
-@cindex target attributes
-@cindex machine attributes
-@cindex attributes, target-specific
-
-Target-specific attributes may be defined for functions, data and types.
-These are described using the following target hooks; they also need to
-be documented in @file{extend.texi}.
-
-@deftypevr {Target Hook} {const struct attribute_spec *} TARGET_ATTRIBUTE_TABLE
-If defined, this target hook points to an array of @samp{struct
-attribute_spec} (defined in @file{tree-core.h}) specifying the machine
-specific attributes for this target and some of the restrictions on the
-entities to which these attributes are applied and the arguments they
-take.
-@end deftypevr
-
-@deftypefn {Target Hook} bool TARGET_ATTRIBUTE_TAKES_IDENTIFIER_P (const_tree @var{name})
-If defined, this target hook is a function which returns true if the
-machine-specific attribute named @var{name} expects an identifier
-given as its first argument to be passed on as a plain identifier, not
-subjected to name lookup. If this is not defined, the default is
-false for all machine-specific attributes.
-@end deftypefn
-
-@deftypefn {Target Hook} int TARGET_COMP_TYPE_ATTRIBUTES (const_tree @var{type1}, const_tree @var{type2})
-If defined, this target hook is a function which returns zero if the attributes on
-@var{type1} and @var{type2} are incompatible, one if they are compatible,
-and two if they are nearly compatible (which causes a warning to be
-generated). If this is not defined, machine-specific attributes are
-supposed always to be compatible.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_SET_DEFAULT_TYPE_ATTRIBUTES (tree @var{type})
-If defined, this target hook is a function which assigns default attributes to
-the newly defined @var{type}.
-@end deftypefn
-
-@deftypefn {Target Hook} tree TARGET_MERGE_TYPE_ATTRIBUTES (tree @var{type1}, tree @var{type2})
-Define this target hook if the merging of type attributes needs special
-handling. If defined, the result is a list of the combined
-@code{TYPE_ATTRIBUTES} of @var{type1} and @var{type2}. It is assumed
-that @code{comptypes} has already been called and returned 1. This
-function may call @code{merge_attributes} to handle machine-independent
-merging.
-@end deftypefn
-
-@deftypefn {Target Hook} tree TARGET_MERGE_DECL_ATTRIBUTES (tree @var{olddecl}, tree @var{newdecl})
-Define this target hook if the merging of decl attributes needs special
-handling. If defined, the result is a list of the combined
-@code{DECL_ATTRIBUTES} of @var{olddecl} and @var{newdecl}.
-@var{newdecl} is a duplicate declaration of @var{olddecl}. Examples of
-when this is needed are when one attribute overrides another, or when an
-attribute is nullified by a subsequent definition. This function may
-call @code{merge_attributes} to handle machine-independent merging.
-
-@findex TARGET_DLLIMPORT_DECL_ATTRIBUTES
-If the only target-specific handling you require is @samp{dllimport}
-for Microsoft Windows targets, you should define the macro
-@code{TARGET_DLLIMPORT_DECL_ATTRIBUTES} to @code{1}. The compiler
-will then define a function called
-@code{merge_dllimport_decl_attributes} which can then be defined as
-the expansion of @code{TARGET_MERGE_DECL_ATTRIBUTES}. You can also
-add @code{handle_dll_attribute} in the attribute table for your port
-to perform initial processing of the @samp{dllimport} and
-@samp{dllexport} attributes. This is done in @file{i386/cygwin.h} and
-@file{i386/i386.cc}, for example.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_VALID_DLLIMPORT_ATTRIBUTE_P (const_tree @var{decl})
-@var{decl} is a variable or function with @code{__attribute__((dllimport))}
-specified. Use this hook if the target needs to add extra validation
-checks to @code{handle_dll_attribute}.
-@end deftypefn
-
-@defmac TARGET_DECLSPEC
-Define this macro to a nonzero value if you want to treat
-@code{__declspec(X)} as equivalent to @code{__attribute((X))}. By
-default, this behavior is enabled only for targets that define
-@code{TARGET_DLLIMPORT_DECL_ATTRIBUTES}. The current implementation
-of @code{__declspec} is via a built-in macro, but you should not rely
-on this implementation detail.
-@end defmac
-
-@deftypefn {Target Hook} void TARGET_INSERT_ATTRIBUTES (tree @var{node}, tree *@var{attr_ptr})
-Define this target hook if you want to be able to add attributes to a decl
-when it is being created. This is normally useful for back ends which
-wish to implement a pragma by using the attributes which correspond to
-the pragma's effect. The @var{node} argument is the decl which is being
-created. The @var{attr_ptr} argument is a pointer to the attribute list
-for this decl. The list itself should not be modified, since it may be
-shared with other decls, but attributes may be chained on the head of
-the list and @code{*@var{attr_ptr}} modified to point to the new
-attributes, or a copy of the list may be made if further changes are
-needed.
-@end deftypefn
-
-@deftypefn {Target Hook} tree TARGET_HANDLE_GENERIC_ATTRIBUTE (tree *@var{node}, tree @var{name}, tree @var{args}, int @var{flags}, bool *@var{no_add_attrs})
-Define this target hook if you want to be able to perform additional
-target-specific processing of an attribute which is handled generically
-by a front end. The arguments are the same as those which are passed to
-attribute handlers. So far this only affects the @var{noinit} and
-@var{section} attribute.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_FUNCTION_ATTRIBUTE_INLINABLE_P (const_tree @var{fndecl})
-@cindex inlining
-This target hook returns @code{true} if it is OK to inline @var{fndecl}
-into the current function, despite its having target-specific
-attributes, @code{false} otherwise. By default, if a function has a
-target specific attribute attached to it, it will not be inlined.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_OPTION_VALID_ATTRIBUTE_P (tree @var{fndecl}, tree @var{name}, tree @var{args}, int @var{flags})
-This hook is called to parse @code{attribute(target("..."))}, which
-allows setting target-specific options on individual functions.
-These function-specific options may differ
-from the options specified on the command line. The hook should return
-@code{true} if the options are valid.
-
-The hook should set the @code{DECL_FUNCTION_SPECIFIC_TARGET} field in
-the function declaration to hold a pointer to a target-specific
-@code{struct cl_target_option} structure.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_OPTION_SAVE (struct cl_target_option *@var{ptr}, struct gcc_options *@var{opts}, struct gcc_options *@var{opts_set})
-This hook is called to save any additional target-specific information
-in the @code{struct cl_target_option} structure for function-specific
-options from the @code{struct gcc_options} structure.
-@xref{Option file format}.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_OPTION_RESTORE (struct gcc_options *@var{opts}, struct gcc_options *@var{opts_set}, struct cl_target_option *@var{ptr})
-This hook is called to restore any additional target-specific
-information in the @code{struct cl_target_option} structure for
-function-specific options to the @code{struct gcc_options} structure.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_OPTION_POST_STREAM_IN (struct cl_target_option *@var{ptr})
-This hook is called to update target-specific information in the
-@code{struct cl_target_option} structure after it is streamed in from
-LTO bytecode.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_OPTION_PRINT (FILE *@var{file}, int @var{indent}, struct cl_target_option *@var{ptr})
-This hook is called to print any additional target-specific
-information in the @code{struct cl_target_option} structure for
-function-specific options.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_OPTION_PRAGMA_PARSE (tree @var{args}, tree @var{pop_target})
-This target hook parses the options for @code{#pragma GCC target}, which
-sets the target-specific options for functions that occur later in the
-input stream. The options accepted should be the same as those handled by the
-@code{TARGET_OPTION_VALID_ATTRIBUTE_P} hook.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_OPTION_OVERRIDE (void)
-Sometimes certain combinations of command options do not make sense on
-a particular target machine. You can override the hook
-@code{TARGET_OPTION_OVERRIDE} to take account of this. This hooks is called
-once just after all the command options have been parsed.
-
-Don't use this hook to turn on various extra optimizations for
-@option{-O}. That is what @code{TARGET_OPTION_OPTIMIZATION} is for.
-
-If you need to do something whenever the optimization level is
-changed via the optimize attribute or pragma, see
-@code{TARGET_OVERRIDE_OPTIONS_AFTER_CHANGE}
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_OPTION_FUNCTION_VERSIONS (tree @var{decl1}, tree @var{decl2})
-This target hook returns @code{true} if @var{DECL1} and @var{DECL2} are
-versions of the same function. @var{DECL1} and @var{DECL2} are function
-versions if and only if they have the same function signature and
-different target specific attributes, that is, they are compiled for
-different target machines.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_CAN_INLINE_P (tree @var{caller}, tree @var{callee})
-This target hook returns @code{false} if the @var{caller} function
-cannot inline @var{callee}, based on target specific information. By
-default, inlining is not allowed if the callee function has function
-specific target options and the caller does not use the same options.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_UPDATE_IPA_FN_TARGET_INFO (unsigned int& @var{info}, const gimple* @var{stmt})
-Allow target to analyze all gimple statements for the given function to
-record and update some target specific information for inlining. A typical
-example is that a caller with one isa feature disabled is normally not
-allowed to inline a callee with that same isa feature enabled even which is
-attributed by always_inline, but with the conservative analysis on all
-statements of the callee if we are able to guarantee the callee does not
-exploit any instructions from the mismatch isa feature, it would be safe to
-allow the caller to inline the callee.
-@var{info} is one @code{unsigned int} value to record information in which
-one set bit indicates one corresponding feature is detected in the analysis,
-@var{stmt} is the statement being analyzed. Return true if target still
-need to analyze the subsequent statements, otherwise return false to stop
-subsequent analysis.
-The default version of this hook returns false.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_NEED_IPA_FN_TARGET_INFO (const_tree @var{decl}, unsigned int& @var{info})
-Allow target to check early whether it is necessary to analyze all gimple
-statements in the given function to update target specific information for
-inlining. See hook @code{update_ipa_fn_target_info} for usage example of
-target specific information. This hook is expected to be invoked ahead of
-the iterating with hook @code{update_ipa_fn_target_info}.
-@var{decl} is the function being analyzed, @var{info} is the same as what
-in hook @code{update_ipa_fn_target_info}, target can do one time update
-into @var{info} without iterating for some case. Return true if target
-decides to analyze all gimple statements to collect information, otherwise
-return false.
-The default version of this hook returns false.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_RELAYOUT_FUNCTION (tree @var{fndecl})
-This target hook fixes function @var{fndecl} after attributes are processed.
-Default does nothing. On ARM, the default function's alignment is updated
-with the attribute target.
-@end deftypefn
-
-@node Emulated TLS
-@section Emulating TLS
-@cindex Emulated TLS
-
-For targets whose psABI does not provide Thread Local Storage via
-specific relocations and instruction sequences, an emulation layer is
-used. A set of target hooks allows this emulation layer to be
-configured for the requirements of a particular target. For instance
-the psABI may in fact specify TLS support in terms of an emulation
-layer.
-
-The emulation layer works by creating a control object for every TLS
-object. To access the TLS object, a lookup function is provided
-which, when given the address of the control object, will return the
-address of the current thread's instance of the TLS object.
-
-@deftypevr {Target Hook} {const char *} TARGET_EMUTLS_GET_ADDRESS
-Contains the name of the helper function that uses a TLS control
-object to locate a TLS instance. The default causes libgcc's
-emulated TLS helper function to be used.
-@end deftypevr
-
-@deftypevr {Target Hook} {const char *} TARGET_EMUTLS_REGISTER_COMMON
-Contains the name of the helper function that should be used at
-program startup to register TLS objects that are implicitly
-initialized to zero. If this is @code{NULL}, all TLS objects will
-have explicit initializers. The default causes libgcc's emulated TLS
-registration function to be used.
-@end deftypevr
-
-@deftypevr {Target Hook} {const char *} TARGET_EMUTLS_VAR_SECTION
-Contains the name of the section in which TLS control variables should
-be placed. The default of @code{NULL} allows these to be placed in
-any section.
-@end deftypevr
-
-@deftypevr {Target Hook} {const char *} TARGET_EMUTLS_TMPL_SECTION
-Contains the name of the section in which TLS initializers should be
-placed. The default of @code{NULL} allows these to be placed in any
-section.
-@end deftypevr
-
-@deftypevr {Target Hook} {const char *} TARGET_EMUTLS_VAR_PREFIX
-Contains the prefix to be prepended to TLS control variable names.
-The default of @code{NULL} uses a target-specific prefix.
-@end deftypevr
-
-@deftypevr {Target Hook} {const char *} TARGET_EMUTLS_TMPL_PREFIX
-Contains the prefix to be prepended to TLS initializer objects. The
-default of @code{NULL} uses a target-specific prefix.
-@end deftypevr
-
-@deftypefn {Target Hook} tree TARGET_EMUTLS_VAR_FIELDS (tree @var{type}, tree *@var{name})
-Specifies a function that generates the FIELD_DECLs for a TLS control
-object type. @var{type} is the RECORD_TYPE the fields are for and
-@var{name} should be filled with the structure tag, if the default of
-@code{__emutls_object} is unsuitable. The default creates a type suitable
-for libgcc's emulated TLS function.
-@end deftypefn
-
-@deftypefn {Target Hook} tree TARGET_EMUTLS_VAR_INIT (tree @var{var}, tree @var{decl}, tree @var{tmpl_addr})
-Specifies a function that generates the CONSTRUCTOR to initialize a
-TLS control object. @var{var} is the TLS control object, @var{decl}
-is the TLS object and @var{tmpl_addr} is the address of the
-initializer. The default initializes libgcc's emulated TLS control object.
-@end deftypefn
-
-@deftypevr {Target Hook} bool TARGET_EMUTLS_VAR_ALIGN_FIXED
-Specifies whether the alignment of TLS control variable objects is
-fixed and should not be increased as some backends may do to optimize
-single objects. The default is false.
-@end deftypevr
-
-@deftypevr {Target Hook} bool TARGET_EMUTLS_DEBUG_FORM_TLS_ADDRESS
-Specifies whether a DWARF @code{DW_OP_form_tls_address} location descriptor
-may be used to describe emulated TLS control objects.
-@end deftypevr
-
-@node MIPS Coprocessors
-@section Defining coprocessor specifics for MIPS targets.
-@cindex MIPS coprocessor-definition macros
-
-The MIPS specification allows MIPS implementations to have as many as 4
-coprocessors, each with as many as 32 private registers. GCC supports
-accessing these registers and transferring values between the registers
-and memory using asm-ized variables. For example:
-
-@smallexample
- register unsigned int cp0count asm ("c0r1");
- unsigned int d;
-
- d = cp0count + 3;
-@end smallexample
-
-(``c0r1'' is the default name of register 1 in coprocessor 0; alternate
-names may be added as described below, or the default names may be
-overridden entirely in @code{SUBTARGET_CONDITIONAL_REGISTER_USAGE}.)
-
-Coprocessor registers are assumed to be epilogue-used; sets to them will
-be preserved even if it does not appear that the register is used again
-later in the function.
-
-Another note: according to the MIPS spec, coprocessor 1 (if present) is
-the FPU@. One accesses COP1 registers through standard mips
-floating-point support; they are not included in this mechanism.
-
-@node PCH Target
-@section Parameters for Precompiled Header Validity Checking
-@cindex parameters, precompiled headers
-
-@deftypefn {Target Hook} {void *} TARGET_GET_PCH_VALIDITY (size_t *@var{sz})
-This hook returns a pointer to the data needed by
-@code{TARGET_PCH_VALID_P} and sets
-@samp{*@var{sz}} to the size of the data in bytes.
-@end deftypefn
-
-@deftypefn {Target Hook} {const char *} TARGET_PCH_VALID_P (const void *@var{data}, size_t @var{sz})
-This hook checks whether the options used to create a PCH file are
-compatible with the current settings. It returns @code{NULL}
-if so and a suitable error message if not. Error messages will
-be presented to the user and must be localized using @samp{_(@var{msg})}.
-
-@var{data} is the data that was returned by @code{TARGET_GET_PCH_VALIDITY}
-when the PCH file was created and @var{sz} is the size of that data in bytes.
-It's safe to assume that the data was created by the same version of the
-compiler, so no format checking is needed.
-
-The default definition of @code{default_pch_valid_p} should be
-suitable for most targets.
-@end deftypefn
-
-@deftypefn {Target Hook} {const char *} TARGET_CHECK_PCH_TARGET_FLAGS (int @var{pch_flags})
-If this hook is nonnull, the default implementation of
-@code{TARGET_PCH_VALID_P} will use it to check for compatible values
-of @code{target_flags}. @var{pch_flags} specifies the value that
-@code{target_flags} had when the PCH file was created. The return
-value is the same as for @code{TARGET_PCH_VALID_P}.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_PREPARE_PCH_SAVE (void)
-Called before writing out a PCH file. If the target has some
-garbage-collected data that needs to be in a particular state on PCH loads,
-it can use this hook to enforce that state. Very few targets need
-to do anything here.
-@end deftypefn
-
-@node C++ ABI
-@section C++ ABI parameters
-@cindex parameters, c++ abi
-
-@deftypefn {Target Hook} tree TARGET_CXX_GUARD_TYPE (void)
-Define this hook to override the integer type used for guard variables.
-These are used to implement one-time construction of static objects. The
-default is long_long_integer_type_node.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_CXX_GUARD_MASK_BIT (void)
-This hook determines how guard variables are used. It should return
-@code{false} (the default) if the first byte should be used. A return value of
-@code{true} indicates that only the least significant bit should be used.
-@end deftypefn
-
-@deftypefn {Target Hook} tree TARGET_CXX_GET_COOKIE_SIZE (tree @var{type})
-This hook returns the size of the cookie to use when allocating an array
-whose elements have the indicated @var{type}. Assumes that it is already
-known that a cookie is needed. The default is
-@code{max(sizeof (size_t), alignof(type))}, as defined in section 2.7 of the
-IA64/Generic C++ ABI@.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_CXX_COOKIE_HAS_SIZE (void)
-This hook should return @code{true} if the element size should be stored in
-array cookies. The default is to return @code{false}.
-@end deftypefn
-
-@deftypefn {Target Hook} int TARGET_CXX_IMPORT_EXPORT_CLASS (tree @var{type}, int @var{import_export})
-If defined by a backend this hook allows the decision made to export
-class @var{type} to be overruled. Upon entry @var{import_export}
-will contain 1 if the class is going to be exported, @minus{}1 if it is going
-to be imported and 0 otherwise. This function should return the
-modified value and perform any other actions necessary to support the
-backend's targeted operating system.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_CXX_CDTOR_RETURNS_THIS (void)
-This hook should return @code{true} if constructors and destructors return
-the address of the object created/destroyed. The default is to return
-@code{false}.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_CXX_KEY_METHOD_MAY_BE_INLINE (void)
-This hook returns true if the key method for a class (i.e., the method
-which, if defined in the current translation unit, causes the virtual
-table to be emitted) may be an inline function. Under the standard
-Itanium C++ ABI the key method may be an inline function so long as
-the function is not declared inline in the class definition. Under
-some variants of the ABI, an inline function can never be the key
-method. The default is to return @code{true}.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_CXX_DETERMINE_CLASS_DATA_VISIBILITY (tree @var{decl})
-@var{decl} is a virtual table, virtual table table, typeinfo object,
-or other similar implicit class data object that will be emitted with
-external linkage in this translation unit. No ELF visibility has been
-explicitly specified. If the target needs to specify a visibility
-other than that of the containing class, use this hook to set
-@code{DECL_VISIBILITY} and @code{DECL_VISIBILITY_SPECIFIED}.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_CXX_CLASS_DATA_ALWAYS_COMDAT (void)
-This hook returns true (the default) if virtual tables and other
-similar implicit class data objects are always COMDAT if they have
-external linkage. If this hook returns false, then class data for
-classes whose virtual table will be emitted in only one translation
-unit will not be COMDAT.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_CXX_LIBRARY_RTTI_COMDAT (void)
-This hook returns true (the default) if the RTTI information for
-the basic types which is defined in the C++ runtime should always
-be COMDAT, false if it should not be COMDAT.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_CXX_USE_AEABI_ATEXIT (void)
-This hook returns true if @code{__aeabi_atexit} (as defined by the ARM EABI)
-should be used to register static destructors when @option{-fuse-cxa-atexit}
-is in effect. The default is to return false to use @code{__cxa_atexit}.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_CXX_USE_ATEXIT_FOR_CXA_ATEXIT (void)
-This hook returns true if the target @code{atexit} function can be used
-in the same manner as @code{__cxa_atexit} to register C++ static
-destructors. This requires that @code{atexit}-registered functions in
-shared libraries are run in the correct order when the libraries are
-unloaded. The default is to return false.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_CXX_ADJUST_CLASS_AT_DEFINITION (tree @var{type})
-@var{type} is a C++ class (i.e., RECORD_TYPE or UNION_TYPE) that has just
-been defined. Use this hook to make adjustments to the class (eg, tweak
-visibility or perform any other required target modifications).
-@end deftypefn
-
-@deftypefn {Target Hook} tree TARGET_CXX_DECL_MANGLING_CONTEXT (const_tree @var{decl})
-Return target-specific mangling context of @var{decl} or @code{NULL_TREE}.
-@end deftypefn
-
-@node D Language and ABI
-@section D ABI parameters
-@cindex parameters, d abi
-
-@deftypefn {D Target Hook} void TARGET_D_CPU_VERSIONS (void)
-Declare all environmental version identifiers relating to the target CPU
-using the function @code{builtin_version}, which takes a string representing
-the name of the version. Version identifiers predefined by this hook apply
-to all modules that are being compiled and imported.
-@end deftypefn
-
-@deftypefn {D Target Hook} void TARGET_D_OS_VERSIONS (void)
-Similarly to @code{TARGET_D_CPU_VERSIONS}, but is used for versions
-relating to the target operating system.
-@end deftypefn
-
-@deftypefn {D Target Hook} void TARGET_D_REGISTER_CPU_TARGET_INFO (void)
-Register all target information keys relating to the target CPU using the
-function @code{d_add_target_info_handlers}, which takes a
-@samp{struct d_target_info_spec} (defined in @file{d/d-target.h}). The keys
-added by this hook are made available at compile time by the
-@code{__traits(getTargetInfo)} extension, the result is an expression
-describing the requested target information.
-@end deftypefn
-
-@deftypefn {D Target Hook} void TARGET_D_REGISTER_OS_TARGET_INFO (void)
-Same as @code{TARGET_D_CPU_TARGET_INFO}, but is used for keys relating to
-the target operating system.
-@end deftypefn
-
-@deftypevr {D Target Hook} {const char *} TARGET_D_MINFO_SECTION
-Contains the name of the section in which module info references should be
-placed. By default, the compiler puts all module info symbols in the
-@code{"minfo"} section. Define this macro to override the string if a
-different section name should be used. This section is expected to be
-bracketed by two symbols @code{TARGET_D_MINFO_SECTION_START} and
-@code{TARGET_D_MINFO_SECTION_END} to indicate the start and end address of
-the section, so that the runtime library can collect all modules for each
-loaded shared library and executable. Setting the value to @code{NULL}
-disables the use of sections for storing module info altogether.
-@end deftypevr
-
-@deftypevr {D Target Hook} {const char *} TARGET_D_MINFO_SECTION_START
-If @code{TARGET_D_MINFO_SECTION} is defined, then this must also be defined
-as the name of the symbol indicating the start address of the module info
-section
-@end deftypevr
-
-@deftypevr {D Target Hook} {const char *} TARGET_D_MINFO_SECTION_END
-If @code{TARGET_D_MINFO_SECTION} is defined, then this must also be defined
-as the name of the symbol indicating the end address of the module info
-section
-@end deftypevr
-
-@deftypefn {D Target Hook} bool TARGET_D_HAS_STDCALL_CONVENTION (unsigned int *@var{link_system}, unsigned int *@var{link_windows})
-Returns @code{true} if the target supports the stdcall calling convention.
-The hook should also set @var{link_system} to @code{1} if the @code{stdcall}
-attribute should be applied to functions with @code{extern(System)} linkage,
-and @var{link_windows} to @code{1} to apply @code{stdcall} to functions with
-@code{extern(Windows)} linkage.
-@end deftypefn
-
-@deftypevr {D Target Hook} bool TARGET_D_TEMPLATES_ALWAYS_COMDAT
-This flag is true if instantiated functions and variables are always COMDAT
-if they have external linkage. If this flag is false, then instantiated
-decls will be emitted as weak symbols. The default is @code{false}.
-@end deftypevr
-
-@node Named Address Spaces
-@section Adding support for named address spaces
-@cindex named address spaces
-
-The draft technical report of the ISO/IEC JTC1 S22 WG14 N1275
-standards committee, @cite{Programming Languages - C - Extensions to
-support embedded processors}, specifies a syntax for embedded
-processors to specify alternate address spaces. You can configure a
-GCC port to support section 5.1 of the draft report to add support for
-address spaces other than the default address space. These address
-spaces are new keywords that are similar to the @code{volatile} and
-@code{const} type attributes.
-
-Pointers to named address spaces can have a different size than
-pointers to the generic address space.
-
-For example, the SPU port uses the @code{__ea} address space to refer
-to memory in the host processor, rather than memory local to the SPU
-processor. Access to memory in the @code{__ea} address space involves
-issuing DMA operations to move data between the host processor and the
-local processor memory address space. Pointers in the @code{__ea}
-address space are either 32 bits or 64 bits based on the
-@option{-mea32} or @option{-mea64} switches (native SPU pointers are
-always 32 bits).
-
-Internally, address spaces are represented as a small integer in the
-range 0 to 15 with address space 0 being reserved for the generic
-address space.
-
-To register a named address space qualifier keyword with the C front end,
-the target may call the @code{c_register_addr_space} routine. For example,
-the SPU port uses the following to declare @code{__ea} as the keyword for
-named address space #1:
-@smallexample
-#define ADDR_SPACE_EA 1
-c_register_addr_space ("__ea", ADDR_SPACE_EA);
-@end smallexample
-
-@deftypefn {Target Hook} scalar_int_mode TARGET_ADDR_SPACE_POINTER_MODE (addr_space_t @var{address_space})
-Define this to return the machine mode to use for pointers to
-@var{address_space} if the target supports named address spaces.
-The default version of this hook returns @code{ptr_mode}.
-@end deftypefn
-
-@deftypefn {Target Hook} scalar_int_mode TARGET_ADDR_SPACE_ADDRESS_MODE (addr_space_t @var{address_space})
-Define this to return the machine mode to use for addresses in
-@var{address_space} if the target supports named address spaces.
-The default version of this hook returns @code{Pmode}.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_ADDR_SPACE_VALID_POINTER_MODE (scalar_int_mode @var{mode}, addr_space_t @var{as})
-Define this to return nonzero if the port can handle pointers
-with machine mode @var{mode} to address space @var{as}. This target
-hook is the same as the @code{TARGET_VALID_POINTER_MODE} target hook,
-except that it includes explicit named address space support. The default
-version of this hook returns true for the modes returned by either the
-@code{TARGET_ADDR_SPACE_POINTER_MODE} or @code{TARGET_ADDR_SPACE_ADDRESS_MODE}
-target hooks for the given address space.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_ADDR_SPACE_LEGITIMATE_ADDRESS_P (machine_mode @var{mode}, rtx @var{exp}, bool @var{strict}, addr_space_t @var{as})
-Define this to return true if @var{exp} is a valid address for mode
-@var{mode} in the named address space @var{as}. The @var{strict}
-parameter says whether strict addressing is in effect after reload has
-finished. This target hook is the same as the
-@code{TARGET_LEGITIMATE_ADDRESS_P} target hook, except that it includes
-explicit named address space support.
-@end deftypefn
-
-@deftypefn {Target Hook} rtx TARGET_ADDR_SPACE_LEGITIMIZE_ADDRESS (rtx @var{x}, rtx @var{oldx}, machine_mode @var{mode}, addr_space_t @var{as})
-Define this to modify an invalid address @var{x} to be a valid address
-with mode @var{mode} in the named address space @var{as}. This target
-hook is the same as the @code{TARGET_LEGITIMIZE_ADDRESS} target hook,
-except that it includes explicit named address space support.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_ADDR_SPACE_SUBSET_P (addr_space_t @var{subset}, addr_space_t @var{superset})
-Define this to return whether the @var{subset} named address space is
-contained within the @var{superset} named address space. Pointers to
-a named address space that is a subset of another named address space
-will be converted automatically without a cast if used together in
-arithmetic operations. Pointers to a superset address space can be
-converted to pointers to a subset address space via explicit casts.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_ADDR_SPACE_ZERO_ADDRESS_VALID (addr_space_t @var{as})
-Define this to modify the default handling of address 0 for the
-address space. Return true if 0 should be considered a valid address.
-@end deftypefn
-
-@deftypefn {Target Hook} rtx TARGET_ADDR_SPACE_CONVERT (rtx @var{op}, tree @var{from_type}, tree @var{to_type})
-Define this to convert the pointer expression represented by the RTL
-@var{op} with type @var{from_type} that points to a named address
-space to a new pointer expression with type @var{to_type} that points
-to a different named address space. When this hook it called, it is
-guaranteed that one of the two address spaces is a subset of the other,
-as determined by the @code{TARGET_ADDR_SPACE_SUBSET_P} target hook.
-@end deftypefn
-
-@deftypefn {Target Hook} int TARGET_ADDR_SPACE_DEBUG (addr_space_t @var{as})
-Define this to define how the address space is encoded in dwarf.
-The result is the value to be used with @code{DW_AT_address_class}.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_ADDR_SPACE_DIAGNOSE_USAGE (addr_space_t @var{as}, location_t @var{loc})
-Define this hook if the availability of an address space depends on
-command line options and some diagnostics should be printed when the
-address space is used. This hook is called during parsing and allows
-to emit a better diagnostic compared to the case where the address space
-was not registered with @code{c_register_addr_space}. @var{as} is
-the address space as registered with @code{c_register_addr_space}.
-@var{loc} is the location of the address space qualifier token.
-The default implementation does nothing.
-@end deftypefn
-
-@node Misc
-@section Miscellaneous Parameters
-@cindex parameters, miscellaneous
-
-@c prevent bad page break with this line
-Here are several miscellaneous parameters.
-
-@defmac HAS_LONG_COND_BRANCH
-Define this boolean macro to indicate whether or not your architecture
-has conditional branches that can span all of memory. It is used in
-conjunction with an optimization that partitions hot and cold basic
-blocks into separate sections of the executable. If this macro is
-set to false, gcc will convert any conditional branches that attempt
-to cross between sections into unconditional branches or indirect jumps.
-@end defmac
-
-@defmac HAS_LONG_UNCOND_BRANCH
-Define this boolean macro to indicate whether or not your architecture
-has unconditional branches that can span all of memory. It is used in
-conjunction with an optimization that partitions hot and cold basic
-blocks into separate sections of the executable. If this macro is
-set to false, gcc will convert any unconditional branches that attempt
-to cross between sections into indirect jumps.
-@end defmac
-
-@defmac CASE_VECTOR_MODE
-An alias for a machine mode name. This is the machine mode that
-elements of a jump-table should have.
-@end defmac
-
-@defmac CASE_VECTOR_SHORTEN_MODE (@var{min_offset}, @var{max_offset}, @var{body})
-Optional: return the preferred mode for an @code{addr_diff_vec}
-when the minimum and maximum offset are known. If you define this,
-it enables extra code in branch shortening to deal with @code{addr_diff_vec}.
-To make this work, you also have to define @code{INSN_ALIGN} and
-make the alignment for @code{addr_diff_vec} explicit.
-The @var{body} argument is provided so that the offset_unsigned and scale
-flags can be updated.
-@end defmac
-
-@defmac CASE_VECTOR_PC_RELATIVE
-Define this macro to be a C expression to indicate when jump-tables
-should contain relative addresses. You need not define this macro if
-jump-tables never contain relative addresses, or jump-tables should
-contain relative addresses only when @option{-fPIC} or @option{-fPIC}
-is in effect.
-@end defmac
-
-@deftypefn {Target Hook} {unsigned int} TARGET_CASE_VALUES_THRESHOLD (void)
-This function return the smallest number of different values for which it
-is best to use a jump-table instead of a tree of conditional branches.
-The default is four for machines with a @code{casesi} instruction and
-five otherwise. This is best for most machines.
-@end deftypefn
-
-@defmac WORD_REGISTER_OPERATIONS
-Define this macro to 1 if operations between registers with integral mode
-smaller than a word are always performed on the entire register. To be
-more explicit, if you start with a pair of @code{word_mode} registers with
-known values and you do a subword, for example @code{QImode}, addition on
-the low part of the registers, then the compiler may consider that the
-result has a known value in @code{word_mode} too if the macro is defined
-to 1. Most RISC machines have this property and most CISC machines do not.
-@end defmac
-
-@deftypefn {Target Hook} {unsigned int} TARGET_MIN_ARITHMETIC_PRECISION (void)
-On some RISC architectures with 64-bit registers, the processor also
-maintains 32-bit condition codes that make it possible to do real 32-bit
-arithmetic, although the operations are performed on the full registers.
-
-On such architectures, defining this hook to 32 tells the compiler to try
-using 32-bit arithmetical operations setting the condition codes instead
-of doing full 64-bit arithmetic.
-
-More generally, define this hook on RISC architectures if you want the
-compiler to try using arithmetical operations setting the condition codes
-with a precision lower than the word precision.
-
-You need not define this hook if @code{WORD_REGISTER_OPERATIONS} is not
-defined to 1.
-@end deftypefn
-
-@defmac LOAD_EXTEND_OP (@var{mem_mode})
-Define this macro to be a C expression indicating when insns that read
-memory in @var{mem_mode}, an integral mode narrower than a word, set the
-bits outside of @var{mem_mode} to be either the sign-extension or the
-zero-extension of the data read. Return @code{SIGN_EXTEND} for values
-of @var{mem_mode} for which the
-insn sign-extends, @code{ZERO_EXTEND} for which it zero-extends, and
-@code{UNKNOWN} for other modes.
-
-This macro is not called with @var{mem_mode} non-integral or with a width
-greater than or equal to @code{BITS_PER_WORD}, so you may return any
-value in this case. Do not define this macro if it would always return
-@code{UNKNOWN}. On machines where this macro is defined, you will normally
-define it as the constant @code{SIGN_EXTEND} or @code{ZERO_EXTEND}.
-
-You may return a non-@code{UNKNOWN} value even if for some hard registers
-the sign extension is not performed, if for the @code{REGNO_REG_CLASS}
-of these hard registers @code{TARGET_CAN_CHANGE_MODE_CLASS} returns false
-when the @var{from} mode is @var{mem_mode} and the @var{to} mode is any
-integral mode larger than this but not larger than @code{word_mode}.
-
-You must return @code{UNKNOWN} if for some hard registers that allow this
-mode, @code{TARGET_CAN_CHANGE_MODE_CLASS} says that they cannot change to
-@code{word_mode}, but that they can change to another integral mode that
-is larger then @var{mem_mode} but still smaller than @code{word_mode}.
-@end defmac
-
-@defmac SHORT_IMMEDIATES_SIGN_EXTEND
-Define this macro to 1 if loading short immediate values into registers sign
-extends.
-@end defmac
-
-@deftypefn {Target Hook} {unsigned int} TARGET_MIN_DIVISIONS_FOR_RECIP_MUL (machine_mode @var{mode})
-When @option{-ffast-math} is in effect, GCC tries to optimize
-divisions by the same divisor, by turning them into multiplications by
-the reciprocal. This target hook specifies the minimum number of divisions
-that should be there for GCC to perform the optimization for a variable
-of mode @var{mode}. The default implementation returns 3 if the machine
-has an instruction for the division, and 2 if it does not.
-@end deftypefn
-
-@defmac MOVE_MAX
-The maximum number of bytes that a single instruction can move quickly
-between memory and registers or between two memory locations.
-@end defmac
-
-@defmac MAX_MOVE_MAX
-The maximum number of bytes that a single instruction can move quickly
-between memory and registers or between two memory locations. If this
-is undefined, the default is @code{MOVE_MAX}. Otherwise, it is the
-constant value that is the largest value that @code{MOVE_MAX} can have
-at run-time.
-@end defmac
-
-@defmac SHIFT_COUNT_TRUNCATED
-A C expression that is nonzero if on this machine the number of bits
-actually used for the count of a shift operation is equal to the number
-of bits needed to represent the size of the object being shifted. When
-this macro is nonzero, the compiler will assume that it is safe to omit
-a sign-extend, zero-extend, and certain bitwise `and' instructions that
-truncates the count of a shift operation. On machines that have
-instructions that act on bit-fields at variable positions, which may
-include `bit test' instructions, a nonzero @code{SHIFT_COUNT_TRUNCATED}
-also enables deletion of truncations of the values that serve as
-arguments to bit-field instructions.
-
-If both types of instructions truncate the count (for shifts) and
-position (for bit-field operations), or if no variable-position bit-field
-instructions exist, you should define this macro.
-
-However, on some machines, such as the 80386 and the 680x0, truncation
-only applies to shift operations and not the (real or pretended)
-bit-field operations. Define @code{SHIFT_COUNT_TRUNCATED} to be zero on
-such machines. Instead, add patterns to the @file{md} file that include
-the implied truncation of the shift instructions.
-
-You need not define this macro if it would always have the value of zero.
-@end defmac
-
-@anchor{TARGET_SHIFT_TRUNCATION_MASK}
-@deftypefn {Target Hook} {unsigned HOST_WIDE_INT} TARGET_SHIFT_TRUNCATION_MASK (machine_mode @var{mode})
-This function describes how the standard shift patterns for @var{mode}
-deal with shifts by negative amounts or by more than the width of the mode.
-@xref{shift patterns}.
-
-On many machines, the shift patterns will apply a mask @var{m} to the
-shift count, meaning that a fixed-width shift of @var{x} by @var{y} is
-equivalent to an arbitrary-width shift of @var{x} by @var{y & m}. If
-this is true for mode @var{mode}, the function should return @var{m},
-otherwise it should return 0. A return value of 0 indicates that no
-particular behavior is guaranteed.
-
-Note that, unlike @code{SHIFT_COUNT_TRUNCATED}, this function does
-@emph{not} apply to general shift rtxes; it applies only to instructions
-that are generated by the named shift patterns.
-
-The default implementation of this function returns
-@code{GET_MODE_BITSIZE (@var{mode}) - 1} if @code{SHIFT_COUNT_TRUNCATED}
-and 0 otherwise. This definition is always safe, but if
-@code{SHIFT_COUNT_TRUNCATED} is false, and some shift patterns
-nevertheless truncate the shift count, you may get better code
-by overriding it.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_TRULY_NOOP_TRUNCATION (poly_uint64 @var{outprec}, poly_uint64 @var{inprec})
-This hook returns true if it is safe to ``convert'' a value of
-@var{inprec} bits to one of @var{outprec} bits (where @var{outprec} is
-smaller than @var{inprec}) by merely operating on it as if it had only
-@var{outprec} bits. The default returns true unconditionally, which
-is correct for most machines. When @code{TARGET_TRULY_NOOP_TRUNCATION}
-returns false, the machine description should provide a @code{trunc}
-optab to specify the RTL that performs the required truncation.
-
-If @code{TARGET_MODES_TIEABLE_P} returns false for a pair of modes,
-suboptimal code can result if this hook returns true for the corresponding
-mode sizes. Making this hook return false in such cases may improve things.
-@end deftypefn
-
-@deftypefn {Target Hook} int TARGET_MODE_REP_EXTENDED (scalar_int_mode @var{mode}, scalar_int_mode @var{rep_mode})
-The representation of an integral mode can be such that the values
-are always extended to a wider integral mode. Return
-@code{SIGN_EXTEND} if values of @var{mode} are represented in
-sign-extended form to @var{rep_mode}. Return @code{UNKNOWN}
-otherwise. (Currently, none of the targets use zero-extended
-representation this way so unlike @code{LOAD_EXTEND_OP},
-@code{TARGET_MODE_REP_EXTENDED} is expected to return either
-@code{SIGN_EXTEND} or @code{UNKNOWN}. Also no target extends
-@var{mode} to @var{rep_mode} so that @var{rep_mode} is not the next
-widest integral mode and currently we take advantage of this fact.)
-
-Similarly to @code{LOAD_EXTEND_OP} you may return a non-@code{UNKNOWN}
-value even if the extension is not performed on certain hard registers
-as long as for the @code{REGNO_REG_CLASS} of these hard registers
-@code{TARGET_CAN_CHANGE_MODE_CLASS} returns false.
-
-Note that @code{TARGET_MODE_REP_EXTENDED} and @code{LOAD_EXTEND_OP}
-describe two related properties. If you define
-@code{TARGET_MODE_REP_EXTENDED (mode, word_mode)} you probably also want
-to define @code{LOAD_EXTEND_OP (mode)} to return the same type of
-extension.
-
-In order to enforce the representation of @code{mode},
-@code{TARGET_TRULY_NOOP_TRUNCATION} should return false when truncating to
-@code{mode}.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_SETJMP_PRESERVES_NONVOLATILE_REGS_P (void)
-On some targets, it is assumed that the compiler will spill all pseudos
- that are live across a call to @code{setjmp}, while other targets treat
- @code{setjmp} calls as normal function calls.
-
- This hook returns false if @code{setjmp} calls do not preserve all
- non-volatile registers so that gcc that must spill all pseudos that are
- live across @code{setjmp} calls. Define this to return true if the
- target does not need to spill all pseudos live across @code{setjmp} calls.
- The default implementation conservatively assumes all pseudos must be
- spilled across @code{setjmp} calls.
-@end deftypefn
-
-@defmac STORE_FLAG_VALUE
-A C expression describing the value returned by a comparison operator
-with an integral mode and stored by a store-flag instruction
-(@samp{cstore@var{mode}4}) when the condition is true. This description must
-apply to @emph{all} the @samp{cstore@var{mode}4} patterns and all the
-comparison operators whose results have a @code{MODE_INT} mode.
-
-A value of 1 or @minus{}1 means that the instruction implementing the
-comparison operator returns exactly 1 or @minus{}1 when the comparison is true
-and 0 when the comparison is false. Otherwise, the value indicates
-which bits of the result are guaranteed to be 1 when the comparison is
-true. This value is interpreted in the mode of the comparison
-operation, which is given by the mode of the first operand in the
-@samp{cstore@var{mode}4} pattern. Either the low bit or the sign bit of
-@code{STORE_FLAG_VALUE} be on. Presently, only those bits are used by
-the compiler.
-
-If @code{STORE_FLAG_VALUE} is neither 1 or @minus{}1, the compiler will
-generate code that depends only on the specified bits. It can also
-replace comparison operators with equivalent operations if they cause
-the required bits to be set, even if the remaining bits are undefined.
-For example, on a machine whose comparison operators return an
-@code{SImode} value and where @code{STORE_FLAG_VALUE} is defined as
-@samp{0x80000000}, saying that just the sign bit is relevant, the
-expression
-
-@smallexample
-(ne:SI (and:SI @var{x} (const_int @var{power-of-2})) (const_int 0))
-@end smallexample
-
-@noindent
-can be converted to
-
-@smallexample
-(ashift:SI @var{x} (const_int @var{n}))
-@end smallexample
-
-@noindent
-where @var{n} is the appropriate shift count to move the bit being
-tested into the sign bit.
-
-There is no way to describe a machine that always sets the low-order bit
-for a true value, but does not guarantee the value of any other bits,
-but we do not know of any machine that has such an instruction. If you
-are trying to port GCC to such a machine, include an instruction to
-perform a logical-and of the result with 1 in the pattern for the
-comparison operators and let us know at @email{gcc@@gcc.gnu.org}.
-
-Often, a machine will have multiple instructions that obtain a value
-from a comparison (or the condition codes). Here are rules to guide the
-choice of value for @code{STORE_FLAG_VALUE}, and hence the instructions
-to be used:
-
-@itemize @bullet
-@item
-Use the shortest sequence that yields a valid definition for
-@code{STORE_FLAG_VALUE}. It is more efficient for the compiler to
-``normalize'' the value (convert it to, e.g., 1 or 0) than for the
-comparison operators to do so because there may be opportunities to
-combine the normalization with other operations.
-
-@item
-For equal-length sequences, use a value of 1 or @minus{}1, with @minus{}1 being
-slightly preferred on machines with expensive jumps and 1 preferred on
-other machines.
-
-@item
-As a second choice, choose a value of @samp{0x80000001} if instructions
-exist that set both the sign and low-order bits but do not define the
-others.
-
-@item
-Otherwise, use a value of @samp{0x80000000}.
-@end itemize
-
-Many machines can produce both the value chosen for
-@code{STORE_FLAG_VALUE} and its negation in the same number of
-instructions. On those machines, you should also define a pattern for
-those cases, e.g., one matching
-
-@smallexample
-(set @var{A} (neg:@var{m} (ne:@var{m} @var{B} @var{C})))
-@end smallexample
-
-Some machines can also perform @code{and} or @code{plus} operations on
-condition code values with less instructions than the corresponding
-@samp{cstore@var{mode}4} insn followed by @code{and} or @code{plus}. On those
-machines, define the appropriate patterns. Use the names @code{incscc}
-and @code{decscc}, respectively, for the patterns which perform
-@code{plus} or @code{minus} operations on condition code values. See
-@file{rs6000.md} for some examples. The GNU Superoptimizer can be used to
-find such instruction sequences on other machines.
-
-If this macro is not defined, the default value, 1, is used. You need
-not define @code{STORE_FLAG_VALUE} if the machine has no store-flag
-instructions, or if the value generated by these instructions is 1.
-@end defmac
-
-@defmac FLOAT_STORE_FLAG_VALUE (@var{mode})
-A C expression that gives a nonzero @code{REAL_VALUE_TYPE} value that is
-returned when comparison operators with floating-point results are true.
-Define this macro on machines that have comparison operations that return
-floating-point values. If there are no such operations, do not define
-this macro.
-@end defmac
-
-@defmac VECTOR_STORE_FLAG_VALUE (@var{mode})
-A C expression that gives an rtx representing the nonzero true element
-for vector comparisons. The returned rtx should be valid for the inner
-mode of @var{mode} which is guaranteed to be a vector mode. Define
-this macro on machines that have vector comparison operations that
-return a vector result. If there are no such operations, do not define
-this macro. Typically, this macro is defined as @code{const1_rtx} or
-@code{constm1_rtx}. This macro may return @code{NULL_RTX} to prevent
-the compiler optimizing such vector comparison operations for the
-given mode.
-@end defmac
-
-@defmac CLZ_DEFINED_VALUE_AT_ZERO (@var{mode}, @var{value})
-@defmacx CTZ_DEFINED_VALUE_AT_ZERO (@var{mode}, @var{value})
-A C expression that indicates whether the architecture defines a value
-for @code{clz} or @code{ctz} with a zero operand.
-A result of @code{0} indicates the value is undefined.
-If the value is defined for only the RTL expression, the macro should
-evaluate to @code{1}; if the value applies also to the corresponding optab
-entry (which is normally the case if it expands directly into
-the corresponding RTL), then the macro should evaluate to @code{2}.
-In the cases where the value is defined, @var{value} should be set to
-this value.
-
-If this macro is not defined, the value of @code{clz} or
-@code{ctz} at zero is assumed to be undefined.
-
-This macro must be defined if the target's expansion for @code{ffs}
-relies on a particular value to get correct results. Otherwise it
-is not necessary, though it may be used to optimize some corner cases, and
-to provide a default expansion for the @code{ffs} optab.
-
-Note that regardless of this macro the ``definedness'' of @code{clz}
-and @code{ctz} at zero do @emph{not} extend to the builtin functions
-visible to the user. Thus one may be free to adjust the value at will
-to match the target expansion of these operations without fear of
-breaking the API@.
-@end defmac
-
-@defmac Pmode
-An alias for the machine mode for pointers. On most machines, define
-this to be the integer mode corresponding to the width of a hardware
-pointer; @code{SImode} on 32-bit machine or @code{DImode} on 64-bit machines.
-On some machines you must define this to be one of the partial integer
-modes, such as @code{PSImode}.
-
-The width of @code{Pmode} must be at least as large as the value of
-@code{POINTER_SIZE}. If it is not equal, you must define the macro
-@code{POINTERS_EXTEND_UNSIGNED} to specify how pointers are extended
-to @code{Pmode}.
-@end defmac
-
-@defmac FUNCTION_MODE
-An alias for the machine mode used for memory references to functions
-being called, in @code{call} RTL expressions. On most CISC machines,
-where an instruction can begin at any byte address, this should be
-@code{QImode}. On most RISC machines, where all instructions have fixed
-size and alignment, this should be a mode with the same size and alignment
-as the machine instruction words - typically @code{SImode} or @code{HImode}.
-@end defmac
-
-@defmac STDC_0_IN_SYSTEM_HEADERS
-In normal operation, the preprocessor expands @code{__STDC__} to the
-constant 1, to signify that GCC conforms to ISO Standard C@. On some
-hosts, like Solaris, the system compiler uses a different convention,
-where @code{__STDC__} is normally 0, but is 1 if the user specifies
-strict conformance to the C Standard.
-
-Defining @code{STDC_0_IN_SYSTEM_HEADERS} makes GNU CPP follows the host
-convention when processing system header files, but when processing user
-files @code{__STDC__} will always expand to 1.
-@end defmac
-
-@deftypefn {C Target Hook} {const char *} TARGET_C_PREINCLUDE (void)
-Define this hook to return the name of a header file to be included at
-the start of all compilations, as if it had been included with
-@code{#include <@var{file}>}. If this hook returns @code{NULL}, or is
-not defined, or the header is not found, or if the user specifies
-@option{-ffreestanding} or @option{-nostdinc}, no header is included.
-
-This hook can be used together with a header provided by the system C
-library to implement ISO C requirements for certain macros to be
-predefined that describe properties of the whole implementation rather
-than just the compiler.
-@end deftypefn
-
-@deftypefn {C Target Hook} bool TARGET_CXX_IMPLICIT_EXTERN_C (const char*@var{})
-Define this hook to add target-specific C++ implicit extern C functions.
-If this function returns true for the name of a file-scope function, that
-function implicitly gets extern "C" linkage rather than whatever language
-linkage the declaration would normally have. An example of such function
-is WinMain on Win32 targets.
-@end deftypefn
-
-@defmac SYSTEM_IMPLICIT_EXTERN_C
-Define this macro if the system header files do not support C++@.
-This macro handles system header files by pretending that system
-header files are enclosed in @samp{extern "C" @{@dots{}@}}.
-@end defmac
-
-@findex #pragma
-@findex pragma
-@defmac REGISTER_TARGET_PRAGMAS ()
-Define this macro if you want to implement any target-specific pragmas.
-If defined, it is a C expression which makes a series of calls to
-@code{c_register_pragma} or @code{c_register_pragma_with_expansion}
-for each pragma. The macro may also do any
-setup required for the pragmas.
-
-The primary reason to define this macro is to provide compatibility with
-other compilers for the same target. In general, we discourage
-definition of target-specific pragmas for GCC@.
-
-If the pragma can be implemented by attributes then you should consider
-defining the target hook @samp{TARGET_INSERT_ATTRIBUTES} as well.
-
-Preprocessor macros that appear on pragma lines are not expanded. All
-@samp{#pragma} directives that do not match any registered pragma are
-silently ignored, unless the user specifies @option{-Wunknown-pragmas}.
-@end defmac
-
-@deftypefun void c_register_pragma (const char *@var{space}, const char *@var{name}, void (*@var{callback}) (struct cpp_reader *))
-@deftypefunx void c_register_pragma_with_expansion (const char *@var{space}, const char *@var{name}, void (*@var{callback}) (struct cpp_reader *))
-
-Each call to @code{c_register_pragma} or
-@code{c_register_pragma_with_expansion} establishes one pragma. The
-@var{callback} routine will be called when the preprocessor encounters a
-pragma of the form
-
-@smallexample
-#pragma [@var{space}] @var{name} @dots{}
-@end smallexample
-
-@var{space} is the case-sensitive namespace of the pragma, or
-@code{NULL} to put the pragma in the global namespace. The callback
-routine receives @var{pfile} as its first argument, which can be passed
-on to cpplib's functions if necessary. You can lex tokens after the
-@var{name} by calling @code{pragma_lex}. Tokens that are not read by the
-callback will be silently ignored. The end of the line is indicated by
-a token of type @code{CPP_EOF}. Macro expansion occurs on the
-arguments of pragmas registered with
-@code{c_register_pragma_with_expansion} but not on the arguments of
-pragmas registered with @code{c_register_pragma}.
-
-Note that the use of @code{pragma_lex} is specific to the C and C++
-compilers. It will not work in the Java or Fortran compilers, or any
-other language compilers for that matter. Thus if @code{pragma_lex} is going
-to be called from target-specific code, it must only be done so when
-building the C and C++ compilers. This can be done by defining the
-variables @code{c_target_objs} and @code{cxx_target_objs} in the
-target entry in the @file{config.gcc} file. These variables should name
-the target-specific, language-specific object file which contains the
-code that uses @code{pragma_lex}. Note it will also be necessary to add a
-rule to the makefile fragment pointed to by @code{tmake_file} that shows
-how to build this object file.
-@end deftypefun
-
-@defmac HANDLE_PRAGMA_PACK_WITH_EXPANSION
-Define this macro if macros should be expanded in the
-arguments of @samp{#pragma pack}.
-@end defmac
-
-@defmac TARGET_DEFAULT_PACK_STRUCT
-If your target requires a structure packing default other than 0 (meaning
-the machine default), define this macro to the necessary value (in bytes).
-This must be a value that would also be valid to use with
-@samp{#pragma pack()} (that is, a small power of two).
-@end defmac
-
-@defmac DOLLARS_IN_IDENTIFIERS
-Define this macro to control use of the character @samp{$} in
-identifier names for the C family of languages. 0 means @samp{$} is
-not allowed by default; 1 means it is allowed. 1 is the default;
-there is no need to define this macro in that case.
-@end defmac
-
-@defmac INSN_SETS_ARE_DELAYED (@var{insn})
-Define this macro as a C expression that is nonzero if it is safe for the
-delay slot scheduler to place instructions in the delay slot of @var{insn},
-even if they appear to use a resource set or clobbered in @var{insn}.
-@var{insn} is always a @code{jump_insn} or an @code{insn}; GCC knows that
-every @code{call_insn} has this behavior. On machines where some @code{insn}
-or @code{jump_insn} is really a function call and hence has this behavior,
-you should define this macro.
-
-You need not define this macro if it would always return zero.
-@end defmac
-
-@defmac INSN_REFERENCES_ARE_DELAYED (@var{insn})
-Define this macro as a C expression that is nonzero if it is safe for the
-delay slot scheduler to place instructions in the delay slot of @var{insn},
-even if they appear to set or clobber a resource referenced in @var{insn}.
-@var{insn} is always a @code{jump_insn} or an @code{insn}. On machines where
-some @code{insn} or @code{jump_insn} is really a function call and its operands
-are registers whose use is actually in the subroutine it calls, you should
-define this macro. Doing so allows the delay slot scheduler to move
-instructions which copy arguments into the argument registers into the delay
-slot of @var{insn}.
-
-You need not define this macro if it would always return zero.
-@end defmac
-
-@defmac MULTIPLE_SYMBOL_SPACES
-Define this macro as a C expression that is nonzero if, in some cases,
-global symbols from one translation unit may not be bound to undefined
-symbols in another translation unit without user intervention. For
-instance, under Microsoft Windows symbols must be explicitly imported
-from shared libraries (DLLs).
-
-You need not define this macro if it would always evaluate to zero.
-@end defmac
-
-@deftypefn {Target Hook} {rtx_insn *} TARGET_MD_ASM_ADJUST (vec<rtx>& @var{outputs}, vec<rtx>& @var{inputs}, vec<machine_mode>& @var{input_modes}, vec<const char *>& @var{constraints}, vec<rtx>& @var{clobbers}, HARD_REG_SET& @var{clobbered_regs}, location_t @var{loc})
-This target hook may add @dfn{clobbers} to @var{clobbers} and
-@var{clobbered_regs} for any hard regs the port wishes to automatically
-clobber for an asm. The @var{outputs} and @var{inputs} may be inspected
-to avoid clobbering a register that is already used by the asm. @var{loc}
-is the source location of the asm.
-
-It may modify the @var{outputs}, @var{inputs}, @var{input_modes}, and
-@var{constraints} as necessary for other pre-processing. In this case the
-return value is a sequence of insns to emit after the asm. Note that
-changes to @var{inputs} must be accompanied by the corresponding changes
-to @var{input_modes}.
-@end deftypefn
-
-@defmac MATH_LIBRARY
-Define this macro as a C string constant for the linker argument to link
-in the system math library, minus the initial @samp{"-l"}, or
-@samp{""} if the target does not have a
-separate math library.
-
-You need only define this macro if the default of @samp{"m"} is wrong.
-@end defmac
-
-@defmac LIBRARY_PATH_ENV
-Define this macro as a C string constant for the environment variable that
-specifies where the linker should look for libraries.
-
-You need only define this macro if the default of @samp{"LIBRARY_PATH"}
-is wrong.
-@end defmac
-
-@defmac TARGET_POSIX_IO
-Define this macro if the target supports the following POSIX@ file
-functions, access, mkdir and file locking with fcntl / F_SETLKW@.
-Defining @code{TARGET_POSIX_IO} will enable the test coverage code
-to use file locking when exiting a program, which avoids race conditions
-if the program has forked. It will also create directories at run-time
-for cross-profiling.
-@end defmac
-
-@defmac MAX_CONDITIONAL_EXECUTE
-
-A C expression for the maximum number of instructions to execute via
-conditional execution instructions instead of a branch. A value of
-@code{BRANCH_COST}+1 is the default.
-@end defmac
-
-@defmac IFCVT_MODIFY_TESTS (@var{ce_info}, @var{true_expr}, @var{false_expr})
-Used if the target needs to perform machine-dependent modifications on the
-conditionals used for turning basic blocks into conditionally executed code.
-@var{ce_info} points to a data structure, @code{struct ce_if_block}, which
-contains information about the currently processed blocks. @var{true_expr}
-and @var{false_expr} are the tests that are used for converting the
-then-block and the else-block, respectively. Set either @var{true_expr} or
-@var{false_expr} to a null pointer if the tests cannot be converted.
-@end defmac
-
-@defmac IFCVT_MODIFY_MULTIPLE_TESTS (@var{ce_info}, @var{bb}, @var{true_expr}, @var{false_expr})
-Like @code{IFCVT_MODIFY_TESTS}, but used when converting more complicated
-if-statements into conditions combined by @code{and} and @code{or} operations.
-@var{bb} contains the basic block that contains the test that is currently
-being processed and about to be turned into a condition.
-@end defmac
-
-@defmac IFCVT_MODIFY_INSN (@var{ce_info}, @var{pattern}, @var{insn})
-A C expression to modify the @var{PATTERN} of an @var{INSN} that is to
-be converted to conditional execution format. @var{ce_info} points to
-a data structure, @code{struct ce_if_block}, which contains information
-about the currently processed blocks.
-@end defmac
-
-@defmac IFCVT_MODIFY_FINAL (@var{ce_info})
-A C expression to perform any final machine dependent modifications in
-converting code to conditional execution. The involved basic blocks
-can be found in the @code{struct ce_if_block} structure that is pointed
-to by @var{ce_info}.
-@end defmac
-
-@defmac IFCVT_MODIFY_CANCEL (@var{ce_info})
-A C expression to cancel any machine dependent modifications in
-converting code to conditional execution. The involved basic blocks
-can be found in the @code{struct ce_if_block} structure that is pointed
-to by @var{ce_info}.
-@end defmac
-
-@defmac IFCVT_MACHDEP_INIT (@var{ce_info})
-A C expression to initialize any machine specific data for if-conversion
-of the if-block in the @code{struct ce_if_block} structure that is pointed
-to by @var{ce_info}.
-@end defmac
-
-@deftypefn {Target Hook} void TARGET_MACHINE_DEPENDENT_REORG (void)
-If non-null, this hook performs a target-specific pass over the
-instruction stream. The compiler will run it at all optimization levels,
-just before the point at which it normally does delayed-branch scheduling.
-
-The exact purpose of the hook varies from target to target. Some use
-it to do transformations that are necessary for correctness, such as
-laying out in-function constant pools or avoiding hardware hazards.
-Others use it as an opportunity to do some machine-dependent optimizations.
-
-You need not implement the hook if it has nothing to do. The default
-definition is null.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_INIT_BUILTINS (void)
-Define this hook if you have any machine-specific built-in functions
-that need to be defined. It should be a function that performs the
-necessary setup.
-
-Machine specific built-in functions can be useful to expand special machine
-instructions that would otherwise not normally be generated because
-they have no equivalent in the source language (for example, SIMD vector
-instructions or prefetch instructions).
-
-To create a built-in function, call the function
-@code{lang_hooks.builtin_function}
-which is defined by the language front end. You can use any type nodes set
-up by @code{build_common_tree_nodes};
-only language front ends that use those two functions will call
-@samp{TARGET_INIT_BUILTINS}.
-@end deftypefn
-
-@deftypefn {Target Hook} tree TARGET_BUILTIN_DECL (unsigned @var{code}, bool @var{initialize_p})
-Define this hook if you have any machine-specific built-in functions
-that need to be defined. It should be a function that returns the
-builtin function declaration for the builtin function code @var{code}.
-If there is no such builtin and it cannot be initialized at this time
-if @var{initialize_p} is true the function should return @code{NULL_TREE}.
-If @var{code} is out of range the function should return
-@code{error_mark_node}.
-@end deftypefn
-
-@deftypefn {Target Hook} rtx TARGET_EXPAND_BUILTIN (tree @var{exp}, rtx @var{target}, rtx @var{subtarget}, machine_mode @var{mode}, int @var{ignore})
-
-Expand a call to a machine specific built-in function that was set up by
-@samp{TARGET_INIT_BUILTINS}. @var{exp} is the expression for the
-function call; the result should go to @var{target} if that is
-convenient, and have mode @var{mode} if that is convenient.
-@var{subtarget} may be used as the target for computing one of
-@var{exp}'s operands. @var{ignore} is nonzero if the value is to be
-ignored. This function should return the result of the call to the
-built-in function.
-@end deftypefn
-
-@deftypefn {Target Hook} tree TARGET_RESOLVE_OVERLOADED_BUILTIN (unsigned int @var{loc}, tree @var{fndecl}, void *@var{arglist})
-Select a replacement for a machine specific built-in function that
-was set up by @samp{TARGET_INIT_BUILTINS}. This is done
-@emph{before} regular type checking, and so allows the target to
-implement a crude form of function overloading. @var{fndecl} is the
-declaration of the built-in function. @var{arglist} is the list of
-arguments passed to the built-in function. The result is a
-complete expression that implements the operation, usually
-another @code{CALL_EXPR}.
-@var{arglist} really has type @samp{VEC(tree,gc)*}
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_CHECK_BUILTIN_CALL (location_t @var{loc}, vec<location_t> @var{arg_loc}, tree @var{fndecl}, tree @var{orig_fndecl}, unsigned int @var{nargs}, tree *@var{args})
-Perform semantic checking on a call to a machine-specific built-in
-function after its arguments have been constrained to the function
-signature. Return true if the call is valid, otherwise report an error
-and return false.
-
-This hook is called after @code{TARGET_RESOLVE_OVERLOADED_BUILTIN}.
-The call was originally to built-in function @var{orig_fndecl},
-but after the optional @code{TARGET_RESOLVE_OVERLOADED_BUILTIN}
-step is now to built-in function @var{fndecl}. @var{loc} is the
-location of the call and @var{args} is an array of function arguments,
-of which there are @var{nargs}. @var{arg_loc} specifies the location
-of each argument.
-@end deftypefn
-
-@deftypefn {Target Hook} tree TARGET_FOLD_BUILTIN (tree @var{fndecl}, int @var{n_args}, tree *@var{argp}, bool @var{ignore})
-Fold a call to a machine specific built-in function that was set up by
-@samp{TARGET_INIT_BUILTINS}. @var{fndecl} is the declaration of the
-built-in function. @var{n_args} is the number of arguments passed to
-the function; the arguments themselves are pointed to by @var{argp}.
-The result is another tree, valid for both GIMPLE and GENERIC,
-containing a simplified expression for the call's result. If
-@var{ignore} is true the value will be ignored.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_GIMPLE_FOLD_BUILTIN (gimple_stmt_iterator *@var{gsi})
-Fold a call to a machine specific built-in function that was set up
-by @samp{TARGET_INIT_BUILTINS}. @var{gsi} points to the gimple
-statement holding the function call. Returns true if any change
-was made to the GIMPLE stream.
-@end deftypefn
-
-@deftypefn {Target Hook} int TARGET_COMPARE_VERSION_PRIORITY (tree @var{decl1}, tree @var{decl2})
-This hook is used to compare the target attributes in two functions to
-determine which function's features get higher priority. This is used
-during function multi-versioning to figure out the order in which two
-versions must be dispatched. A function version with a higher priority
-is checked for dispatching earlier. @var{decl1} and @var{decl2} are
- the two function decls that will be compared.
-@end deftypefn
-
-@deftypefn {Target Hook} tree TARGET_GET_FUNCTION_VERSIONS_DISPATCHER (void *@var{decl})
-This hook is used to get the dispatcher function for a set of function
-versions. The dispatcher function is called to invoke the right function
-version at run-time. @var{decl} is one version from a set of semantically
-identical versions.
-@end deftypefn
-
-@deftypefn {Target Hook} tree TARGET_GENERATE_VERSION_DISPATCHER_BODY (void *@var{arg})
-This hook is used to generate the dispatcher logic to invoke the right
-function version at run-time for a given set of function versions.
-@var{arg} points to the callgraph node of the dispatcher function whose
-body must be generated.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_PREDICT_DOLOOP_P (class loop *@var{loop})
-Return true if we can predict it is possible to use a low-overhead loop
-for a particular loop. The parameter @var{loop} is a pointer to the loop.
-This target hook is required only when the target supports low-overhead
-loops, and will help ivopts to make some decisions.
-The default version of this hook returns false.
-@end deftypefn
-
-@deftypevr {Target Hook} bool TARGET_HAVE_COUNT_REG_DECR_P
-Return true if the target supports hardware count register for decrement
-and branch.
-The default value is false.
-@end deftypevr
-
-@deftypevr {Target Hook} int64_t TARGET_DOLOOP_COST_FOR_GENERIC
-One IV candidate dedicated for doloop is introduced in IVOPTs, we can
-calculate the computation cost of adopting it to any generic IV use by
-function get_computation_cost as before. But for targets which have
-hardware count register support for decrement and branch, it may have to
-move IV value from hardware count register to general purpose register
-while doloop IV candidate is used for generic IV uses. It probably takes
-expensive penalty. This hook allows target owners to define the cost for
-this especially for generic IV uses.
-The default value is zero.
-@end deftypevr
-
-@deftypevr {Target Hook} int64_t TARGET_DOLOOP_COST_FOR_ADDRESS
-One IV candidate dedicated for doloop is introduced in IVOPTs, we can
-calculate the computation cost of adopting it to any address IV use by
-function get_computation_cost as before. But for targets which have
-hardware count register support for decrement and branch, it may have to
-move IV value from hardware count register to general purpose register
-while doloop IV candidate is used for address IV uses. It probably takes
-expensive penalty. This hook allows target owners to define the cost for
-this escpecially for address IV uses.
-The default value is zero.
-@end deftypevr
-
-@deftypefn {Target Hook} bool TARGET_CAN_USE_DOLOOP_P (const widest_int @var{&iterations}, const widest_int @var{&iterations_max}, unsigned int @var{loop_depth}, bool @var{entered_at_top})
-Return true if it is possible to use low-overhead loops (@code{doloop_end}
-and @code{doloop_begin}) for a particular loop. @var{iterations} gives the
-exact number of iterations, or 0 if not known. @var{iterations_max} gives
-the maximum number of iterations, or 0 if not known. @var{loop_depth} is
-the nesting depth of the loop, with 1 for innermost loops, 2 for loops that
-contain innermost loops, and so on. @var{entered_at_top} is true if the
-loop is only entered from the top.
-
-This hook is only used if @code{doloop_end} is available. The default
-implementation returns true. You can use @code{can_use_doloop_if_innermost}
-if the loop must be the innermost, and if there are no other restrictions.
-@end deftypefn
-
-@deftypefn {Target Hook} {const char *} TARGET_INVALID_WITHIN_DOLOOP (const rtx_insn *@var{insn})
-
-Take an instruction in @var{insn} and return NULL if it is valid within a
-low-overhead loop, otherwise return a string explaining why doloop
-could not be applied.
-
-Many targets use special registers for low-overhead looping. For any
-instruction that clobbers these this function should return a string indicating
-the reason why the doloop could not be applied.
-By default, the RTL loop optimizer does not use a present doloop pattern for
-loops containing function calls or branch on table instructions.
-@end deftypefn
-
-@deftypefn {Target Hook} machine_mode TARGET_PREFERRED_DOLOOP_MODE (machine_mode @var{mode})
-This hook takes a @var{mode} for a doloop IV, where @code{mode} is the
-original mode for the operation. If the target prefers an alternate
-@code{mode} for the operation, then this hook should return that mode;
-otherwise the original @code{mode} should be returned. For example, on a
-64-bit target, @code{DImode} might be preferred over @code{SImode}. Both the
-original and the returned modes should be @code{MODE_INT}.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_LEGITIMATE_COMBINED_INSN (rtx_insn *@var{insn})
-Take an instruction in @var{insn} and return @code{false} if the instruction
-is not appropriate as a combination of two or more instructions. The
-default is to accept all instructions.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_CAN_FOLLOW_JUMP (const rtx_insn *@var{follower}, const rtx_insn *@var{followee})
-FOLLOWER and FOLLOWEE are JUMP_INSN instructions;
-return true if FOLLOWER may be modified to follow FOLLOWEE;
-false, if it can't.
-For example, on some targets, certain kinds of branches can't be made to
-follow through a hot/cold partitioning.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_COMMUTATIVE_P (const_rtx @var{x}, int @var{outer_code})
-This target hook returns @code{true} if @var{x} is considered to be commutative.
-Usually, this is just COMMUTATIVE_P (@var{x}), but the HP PA doesn't consider
-PLUS to be commutative inside a MEM@. @var{outer_code} is the rtx code
-of the enclosing rtl, if known, otherwise it is UNKNOWN.
-@end deftypefn
-
-@deftypefn {Target Hook} rtx TARGET_ALLOCATE_INITIAL_VALUE (rtx @var{hard_reg})
-
-When the initial value of a hard register has been copied in a pseudo
-register, it is often not necessary to actually allocate another register
-to this pseudo register, because the original hard register or a stack slot
-it has been saved into can be used. @code{TARGET_ALLOCATE_INITIAL_VALUE}
-is called at the start of register allocation once for each hard register
-that had its initial value copied by using
-@code{get_func_hard_reg_initial_val} or @code{get_hard_reg_initial_val}.
-Possible values are @code{NULL_RTX}, if you don't want
-to do any special allocation, a @code{REG} rtx---that would typically be
-the hard register itself, if it is known not to be clobbered---or a
-@code{MEM}.
-If you are returning a @code{MEM}, this is only a hint for the allocator;
-it might decide to use another register anyways.
-You may use @code{current_function_is_leaf} or
-@code{REG_N_SETS} in the hook to determine if the hard
-register in question will not be clobbered.
-The default value of this hook is @code{NULL}, which disables any special
-allocation.
-@end deftypefn
-
-@deftypefn {Target Hook} int TARGET_UNSPEC_MAY_TRAP_P (const_rtx @var{x}, unsigned @var{flags})
-This target hook returns nonzero if @var{x}, an @code{unspec} or
-@code{unspec_volatile} operation, might cause a trap. Targets can use
-this hook to enhance precision of analysis for @code{unspec} and
-@code{unspec_volatile} operations. You may call @code{may_trap_p_1}
-to analyze inner elements of @var{x} in which case @var{flags} should be
-passed along.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_SET_CURRENT_FUNCTION (tree @var{decl})
-The compiler invokes this hook whenever it changes its current function
-context (@code{cfun}). You can define this function if
-the back end needs to perform any initialization or reset actions on a
-per-function basis. For example, it may be used to implement function
-attributes that affect register usage or code generation patterns.
-The argument @var{decl} is the declaration for the new function context,
-and may be null to indicate that the compiler has left a function context
-and is returning to processing at the top level.
-The default hook function does nothing.
-
-GCC sets @code{cfun} to a dummy function context during initialization of
-some parts of the back end. The hook function is not invoked in this
-situation; you need not worry about the hook being invoked recursively,
-or when the back end is in a partially-initialized state.
-@code{cfun} might be @code{NULL} to indicate processing at top level,
-outside of any function scope.
-@end deftypefn
-
-@defmac TARGET_OBJECT_SUFFIX
-Define this macro to be a C string representing the suffix for object
-files on your target machine. If you do not define this macro, GCC will
-use @samp{.o} as the suffix for object files.
-@end defmac
-
-@defmac TARGET_EXECUTABLE_SUFFIX
-Define this macro to be a C string representing the suffix to be
-automatically added to executable files on your target machine. If you
-do not define this macro, GCC will use the null string as the suffix for
-executable files.
-@end defmac
-
-@defmac COLLECT_EXPORT_LIST
-If defined, @code{collect2} will scan the individual object files
-specified on its command line and create an export list for the linker.
-Define this macro for systems like AIX, where the linker discards
-object files that are not referenced from @code{main} and uses export
-lists.
-@end defmac
-
-@deftypefn {Target Hook} bool TARGET_CANNOT_MODIFY_JUMPS_P (void)
-This target hook returns @code{true} past the point in which new jump
-instructions could be created. On machines that require a register for
-every jump such as the SHmedia ISA of SH5, this point would typically be
-reload, so this target hook should be defined to a function such as:
-
-@smallexample
-static bool
-cannot_modify_jumps_past_reload_p ()
-@{
- return (reload_completed || reload_in_progress);
-@}
-@end smallexample
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_HAVE_CONDITIONAL_EXECUTION (void)
-This target hook returns true if the target supports conditional execution.
-This target hook is required only when the target has several different
-modes and they have different conditional execution capability, such as ARM.
-@end deftypefn
-
-@deftypefn {Target Hook} rtx TARGET_GEN_CCMP_FIRST (rtx_insn **@var{prep_seq}, rtx_insn **@var{gen_seq}, int @var{code}, tree @var{op0}, tree @var{op1})
-This function prepares to emit a comparison insn for the first compare in a
- sequence of conditional comparisions. It returns an appropriate comparison
- with @code{CC} for passing to @code{gen_ccmp_next} or @code{cbranch_optab}.
- The insns to prepare the compare are saved in @var{prep_seq} and the compare
- insns are saved in @var{gen_seq}. They will be emitted when all the
- compares in the conditional comparision are generated without error.
- @var{code} is the @code{rtx_code} of the compare for @var{op0} and @var{op1}.
-@end deftypefn
-
-@deftypefn {Target Hook} rtx TARGET_GEN_CCMP_NEXT (rtx_insn **@var{prep_seq}, rtx_insn **@var{gen_seq}, rtx @var{prev}, int @var{cmp_code}, tree @var{op0}, tree @var{op1}, int @var{bit_code})
-This function prepares to emit a conditional comparison within a sequence
- of conditional comparisons. It returns an appropriate comparison with
- @code{CC} for passing to @code{gen_ccmp_next} or @code{cbranch_optab}.
- The insns to prepare the compare are saved in @var{prep_seq} and the compare
- insns are saved in @var{gen_seq}. They will be emitted when all the
- compares in the conditional comparision are generated without error. The
- @var{prev} expression is the result of a prior call to @code{gen_ccmp_first}
- or @code{gen_ccmp_next}. It may return @code{NULL} if the combination of
- @var{prev} and this comparison is not supported, otherwise the result must
- be appropriate for passing to @code{gen_ccmp_next} or @code{cbranch_optab}.
- @var{code} is the @code{rtx_code} of the compare for @var{op0} and @var{op1}.
- @var{bit_code} is @code{AND} or @code{IOR}, which is the op on the compares.
-@end deftypefn
-
-@deftypefn {Target Hook} rtx TARGET_GEN_MEMSET_SCRATCH_RTX (machine_mode @var{mode})
-This hook should return an rtx for a scratch register in @var{mode} to
-be used when expanding memset calls. The backend can use a hard scratch
-register to avoid stack realignment when expanding memset. The default
-is @code{gen_reg_rtx}.
-@end deftypefn
-
-@deftypefn {Target Hook} unsigned TARGET_LOOP_UNROLL_ADJUST (unsigned @var{nunroll}, class loop *@var{loop})
-This target hook returns a new value for the number of times @var{loop}
-should be unrolled. The parameter @var{nunroll} is the number of times
-the loop is to be unrolled. The parameter @var{loop} is a pointer to
-the loop, which is going to be checked for unrolling. This target hook
-is required only when the target has special constraints like maximum
-number of memory accesses.
-@end deftypefn
-
-@defmac POWI_MAX_MULTS
-If defined, this macro is interpreted as a signed integer C expression
-that specifies the maximum number of floating point multiplications
-that should be emitted when expanding exponentiation by an integer
-constant inline. When this value is defined, exponentiation requiring
-more than this number of multiplications is implemented by calling the
-system library's @code{pow}, @code{powf} or @code{powl} routines.
-The default value places no upper bound on the multiplication count.
-@end defmac
-
-@deftypefn Macro void TARGET_EXTRA_INCLUDES (const char *@var{sysroot}, const char *@var{iprefix}, int @var{stdinc})
-This target hook should register any extra include files for the
-target. The parameter @var{stdinc} indicates if normal include files
-are present. The parameter @var{sysroot} is the system root directory.
-The parameter @var{iprefix} is the prefix for the gcc directory.
-@end deftypefn
-
-@deftypefn Macro void TARGET_EXTRA_PRE_INCLUDES (const char *@var{sysroot}, const char *@var{iprefix}, int @var{stdinc})
-This target hook should register any extra include files for the
-target before any standard headers. The parameter @var{stdinc}
-indicates if normal include files are present. The parameter
-@var{sysroot} is the system root directory. The parameter
-@var{iprefix} is the prefix for the gcc directory.
-@end deftypefn
-
-@deftypefn Macro void TARGET_OPTF (char *@var{path})
-This target hook should register special include paths for the target.
-The parameter @var{path} is the include to register. On Darwin
-systems, this is used for Framework includes, which have semantics
-that are different from @option{-I}.
-@end deftypefn
-
-@defmac bool TARGET_USE_LOCAL_THUNK_ALIAS_P (tree @var{fndecl})
-This target macro returns @code{true} if it is safe to use a local alias
-for a virtual function @var{fndecl} when constructing thunks,
-@code{false} otherwise. By default, the macro returns @code{true} for all
-functions, if a target supports aliases (i.e.@: defines
-@code{ASM_OUTPUT_DEF}), @code{false} otherwise,
-@end defmac
-
-@defmac TARGET_FORMAT_TYPES
-If defined, this macro is the name of a global variable containing
-target-specific format checking information for the @option{-Wformat}
-option. The default is to have no target-specific format checks.
-@end defmac
-
-@defmac TARGET_N_FORMAT_TYPES
-If defined, this macro is the number of entries in
-@code{TARGET_FORMAT_TYPES}.
-@end defmac
-
-@defmac TARGET_OVERRIDES_FORMAT_ATTRIBUTES
-If defined, this macro is the name of a global variable containing
-target-specific format overrides for the @option{-Wformat} option. The
-default is to have no target-specific format overrides. If defined,
-@code{TARGET_FORMAT_TYPES} and @code{TARGET_OVERRIDES_FORMAT_ATTRIBUTES_COUNT}
-must be defined, too.
-@end defmac
-
-@defmac TARGET_OVERRIDES_FORMAT_ATTRIBUTES_COUNT
-If defined, this macro specifies the number of entries in
-@code{TARGET_OVERRIDES_FORMAT_ATTRIBUTES}.
-@end defmac
-
-@defmac TARGET_OVERRIDES_FORMAT_INIT
-If defined, this macro specifies the optional initialization
-routine for target specific customizations of the system printf
-and scanf formatter settings.
-@end defmac
-
-@deftypefn {Target Hook} {const char *} TARGET_INVALID_ARG_FOR_UNPROTOTYPED_FN (const_tree @var{typelist}, const_tree @var{funcdecl}, const_tree @var{val})
-If defined, this macro returns the diagnostic message when it is
-illegal to pass argument @var{val} to function @var{funcdecl}
-with prototype @var{typelist}.
-@end deftypefn
-
-@deftypefn {Target Hook} {const char *} TARGET_INVALID_CONVERSION (const_tree @var{fromtype}, const_tree @var{totype})
-If defined, this macro returns the diagnostic message when it is
-invalid to convert from @var{fromtype} to @var{totype}, or @code{NULL}
-if validity should be determined by the front end.
-@end deftypefn
-
-@deftypefn {Target Hook} {const char *} TARGET_INVALID_UNARY_OP (int @var{op}, const_tree @var{type})
-If defined, this macro returns the diagnostic message when it is
-invalid to apply operation @var{op} (where unary plus is denoted by
-@code{CONVERT_EXPR}) to an operand of type @var{type}, or @code{NULL}
-if validity should be determined by the front end.
-@end deftypefn
-
-@deftypefn {Target Hook} {const char *} TARGET_INVALID_BINARY_OP (int @var{op}, const_tree @var{type1}, const_tree @var{type2})
-If defined, this macro returns the diagnostic message when it is
-invalid to apply operation @var{op} to operands of types @var{type1}
-and @var{type2}, or @code{NULL} if validity should be determined by
-the front end.
-@end deftypefn
-
-@deftypefn {Target Hook} tree TARGET_PROMOTED_TYPE (const_tree @var{type})
-If defined, this target hook returns the type to which values of
-@var{type} should be promoted when they appear in expressions,
-analogous to the integer promotions, or @code{NULL_TREE} to use the
-front end's normal promotion rules. This hook is useful when there are
-target-specific types with special promotion rules.
-This is currently used only by the C and C++ front ends.
-@end deftypefn
-
-@deftypefn {Target Hook} tree TARGET_CONVERT_TO_TYPE (tree @var{type}, tree @var{expr})
-If defined, this hook returns the result of converting @var{expr} to
-@var{type}. It should return the converted expression,
-or @code{NULL_TREE} to apply the front end's normal conversion rules.
-This hook is useful when there are target-specific types with special
-conversion rules.
-This is currently used only by the C and C++ front ends.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_VERIFY_TYPE_CONTEXT (location_t @var{loc}, type_context_kind @var{context}, const_tree @var{type}, bool @var{silent_p})
-If defined, this hook returns false if there is a target-specific reason
-why type @var{type} cannot be used in the source language context described
-by @var{context}. When @var{silent_p} is false, the hook also reports an
-error against @var{loc} for invalid uses of @var{type}.
-
-Calls to this hook should be made through the global function
-@code{verify_type_context}, which makes the @var{silent_p} parameter
-default to false and also handles @code{error_mark_node}.
-
-The default implementation always returns true.
-@end deftypefn
-
-@defmac OBJC_JBLEN
-This macro determines the size of the objective C jump buffer for the
-NeXT runtime. By default, OBJC_JBLEN is defined to an innocuous value.
-@end defmac
-
-@defmac LIBGCC2_UNWIND_ATTRIBUTE
-Define this macro if any target-specific attributes need to be attached
-to the functions in @file{libgcc} that provide low-level support for
-call stack unwinding. It is used in declarations in @file{unwind-generic.h}
-and the associated definitions of those functions.
-@end defmac
-
-@deftypefn {Target Hook} void TARGET_UPDATE_STACK_BOUNDARY (void)
-Define this macro to update the current function stack boundary if
-necessary.
-@end deftypefn
-
-@deftypefn {Target Hook} rtx TARGET_GET_DRAP_RTX (void)
-This hook should return an rtx for Dynamic Realign Argument Pointer (DRAP) if a
-different argument pointer register is needed to access the function's
-argument list due to stack realignment. Return @code{NULL} if no DRAP
-is needed.
-@end deftypefn
-
-@deftypefn {Target Hook} HARD_REG_SET TARGET_ZERO_CALL_USED_REGS (HARD_REG_SET @var{selected_regs})
-This target hook emits instructions to zero the subset of @var{selected_regs}
-that could conceivably contain values that are useful to an attacker.
-Return the set of registers that were actually cleared.
-
-For most targets, the returned set of registers is a subset of
-@var{selected_regs}, however, for some of the targets (for example MIPS),
-clearing some registers that are in the @var{selected_regs} requires
-clearing other call used registers that are not in the @var{selected_regs},
-under such situation, the returned set of registers must be a subset of all
-call used registers.
-
-The default implementation uses normal move instructions to zero
-all the registers in @var{selected_regs}. Define this hook if the
-target has more efficient ways of zeroing certain registers,
-or if you believe that certain registers would never contain
-values that are useful to an attacker.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_ALLOCATE_STACK_SLOTS_FOR_ARGS (void)
-When optimization is disabled, this hook indicates whether or not
-arguments should be allocated to stack slots. Normally, GCC allocates
-stacks slots for arguments when not optimizing in order to make
-debugging easier. However, when a function is declared with
-@code{__attribute__((naked))}, there is no stack frame, and the compiler
-cannot safely move arguments from the registers in which they are passed
-to the stack. Therefore, this hook should return true in general, but
-false for naked functions. The default implementation always returns true.
-@end deftypefn
-
-@deftypevr {Target Hook} {unsigned HOST_WIDE_INT} TARGET_CONST_ANCHOR
-On some architectures it can take multiple instructions to synthesize
-a constant. If there is another constant already in a register that
-is close enough in value then it is preferable that the new constant
-is computed from this register using immediate addition or
-subtraction. We accomplish this through CSE. Besides the value of
-the constant we also add a lower and an upper constant anchor to the
-available expressions. These are then queried when encountering new
-constants. The anchors are computed by rounding the constant up and
-down to a multiple of the value of @code{TARGET_CONST_ANCHOR}.
-@code{TARGET_CONST_ANCHOR} should be the maximum positive value
-accepted by immediate-add plus one. We currently assume that the
-value of @code{TARGET_CONST_ANCHOR} is a power of 2. For example, on
-MIPS, where add-immediate takes a 16-bit signed value,
-@code{TARGET_CONST_ANCHOR} is set to @samp{0x8000}. The default value
-is zero, which disables this optimization.
-@end deftypevr
-
-@deftypefn {Target Hook} {unsigned HOST_WIDE_INT} TARGET_ASAN_SHADOW_OFFSET (void)
-Return the offset bitwise ored into shifted address to get corresponding
-Address Sanitizer shadow memory address. NULL if Address Sanitizer is not
-supported by the target. May return 0 if Address Sanitizer is not supported
-by a subtarget.
-@end deftypefn
-
-@deftypefn {Target Hook} {unsigned HOST_WIDE_INT} TARGET_MEMMODEL_CHECK (unsigned HOST_WIDE_INT @var{val})
-Validate target specific memory model mask bits. When NULL no target specific
-memory model bits are allowed.
-@end deftypefn
-
-@deftypevr {Target Hook} {unsigned char} TARGET_ATOMIC_TEST_AND_SET_TRUEVAL
-This value should be set if the result written by
-@code{atomic_test_and_set} is not exactly 1, i.e.@: the
-@code{bool} @code{true}.
-@end deftypevr
-
-@deftypefn {Target Hook} bool TARGET_HAS_IFUNC_P (void)
-It returns true if the target supports GNU indirect functions.
-The support includes the assembler, linker and dynamic linker.
-The default value of this hook is based on target's libc.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_IFUNC_REF_LOCAL_OK (void)
-Return true if it is OK to reference indirect function resolvers
-locally. The default is to return false.
-@end deftypefn
-
-@deftypefn {Target Hook} {unsigned int} TARGET_ATOMIC_ALIGN_FOR_MODE (machine_mode @var{mode})
-If defined, this function returns an appropriate alignment in bits for an
-atomic object of machine_mode @var{mode}. If 0 is returned then the
-default alignment for the specified mode is used.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_ATOMIC_ASSIGN_EXPAND_FENV (tree *@var{hold}, tree *@var{clear}, tree *@var{update})
-ISO C11 requires atomic compound assignments that may raise floating-point
-exceptions to raise exceptions corresponding to the arithmetic operation
-whose result was successfully stored in a compare-and-exchange sequence.
-This requires code equivalent to calls to @code{feholdexcept},
-@code{feclearexcept} and @code{feupdateenv} to be generated at
-appropriate points in the compare-and-exchange sequence. This hook should
-set @code{*@var{hold}} to an expression equivalent to the call to
-@code{feholdexcept}, @code{*@var{clear}} to an expression equivalent to
-the call to @code{feclearexcept} and @code{*@var{update}} to an expression
-equivalent to the call to @code{feupdateenv}. The three expressions are
-@code{NULL_TREE} on entry to the hook and may be left as @code{NULL_TREE}
-if no code is required in a particular place. The default implementation
-leaves all three expressions as @code{NULL_TREE}. The
-@code{__atomic_feraiseexcept} function from @code{libatomic} may be of use
-as part of the code generated in @code{*@var{update}}.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_RECORD_OFFLOAD_SYMBOL (tree)
-Used when offloaded functions are seen in the compilation unit and no named
-sections are available. It is called once for each symbol that must be
-recorded in the offload function and variable table.
-@end deftypefn
-
-@deftypefn {Target Hook} {char *} TARGET_OFFLOAD_OPTIONS (void)
-Used when writing out the list of options into an LTO file. It should
-translate any relevant target-specific options (such as the ABI in use)
-into one of the @option{-foffload} options that exist as a common interface
-to express such options. It should return a string containing these options,
-separated by spaces, which the caller will free.
-
-@end deftypefn
-
-@defmac TARGET_SUPPORTS_WIDE_INT
-
-On older ports, large integers are stored in @code{CONST_DOUBLE} rtl
-objects. Newer ports define @code{TARGET_SUPPORTS_WIDE_INT} to be nonzero
-to indicate that large integers are stored in
-@code{CONST_WIDE_INT} rtl objects. The @code{CONST_WIDE_INT} allows
-very large integer constants to be represented. @code{CONST_DOUBLE}
-is limited to twice the size of the host's @code{HOST_WIDE_INT}
-representation.
-
-Converting a port mostly requires looking for the places where
-@code{CONST_DOUBLE}s are used with @code{VOIDmode} and replacing that
-code with code that accesses @code{CONST_WIDE_INT}s. @samp{"grep -i
-const_double"} at the port level gets you to 95% of the changes that
-need to be made. There are a few places that require a deeper look.
-
-@itemize @bullet
-@item
-There is no equivalent to @code{hval} and @code{lval} for
-@code{CONST_WIDE_INT}s. This would be difficult to express in the md
-language since there are a variable number of elements.
-
-Most ports only check that @code{hval} is either 0 or -1 to see if the
-value is small. As mentioned above, this will no longer be necessary
-since small constants are always @code{CONST_INT}. Of course there
-are still a few exceptions, the alpha's constraint used by the zap
-instruction certainly requires careful examination by C code.
-However, all the current code does is pass the hval and lval to C
-code, so evolving the c code to look at the @code{CONST_WIDE_INT} is
-not really a large change.
-
-@item
-Because there is no standard template that ports use to materialize
-constants, there is likely to be some futzing that is unique to each
-port in this code.
-
-@item
-The rtx costs may have to be adjusted to properly account for larger
-constants that are represented as @code{CONST_WIDE_INT}.
-@end itemize
-
-All and all it does not take long to convert ports that the
-maintainer is familiar with.
-
-@end defmac
-
-@deftypefn {Target Hook} bool TARGET_HAVE_SPECULATION_SAFE_VALUE (bool @var{active})
-This hook is used to determine the level of target support for
- @code{__builtin_speculation_safe_value}. If called with an argument
- of false, it returns true if the target has been modified to support
- this builtin. If called with an argument of true, it returns true
- if the target requires active mitigation execution might be speculative.
-
- The default implementation returns false if the target does not define
- a pattern named @code{speculation_barrier}. Else it returns true
- for the first case and whether the pattern is enabled for the current
- compilation for the second case.
-
- For targets that have no processors that can execute instructions
- speculatively an alternative implemenation of this hook is available:
- simply redefine this hook to @code{speculation_safe_value_not_needed}
- along with your other target hooks.
-@end deftypefn
-
-@deftypefn {Target Hook} rtx TARGET_SPECULATION_SAFE_VALUE (machine_mode @var{mode}, rtx @var{result}, rtx @var{val}, rtx @var{failval})
-This target hook can be used to generate a target-specific code
- sequence that implements the @code{__builtin_speculation_safe_value}
- built-in function. The function must always return @var{val} in
- @var{result} in mode @var{mode} when the cpu is not executing
- speculatively, but must never return that when speculating until it
- is known that the speculation will not be unwound. The hook supports
- two primary mechanisms for implementing the requirements. The first
- is to emit a speculation barrier which forces the processor to wait
- until all prior speculative operations have been resolved; the second
- is to use a target-specific mechanism that can track the speculation
- state and to return @var{failval} if it can determine that
- speculation must be unwound at a later time.
-
- The default implementation simply copies @var{val} to @var{result} and
- emits a @code{speculation_barrier} instruction if that is defined.
-@end deftypefn
-
-@deftypefn {Target Hook} void TARGET_RUN_TARGET_SELFTESTS (void)
-If selftests are enabled, run any selftests for this target.
-@end deftypefn
-
-@deftypefn {Target Hook} bool TARGET_MEMTAG_CAN_TAG_ADDRESSES ()
-True if the backend architecture naturally supports ignoring some region
-of pointers. This feature means that @option{-fsanitize=hwaddress} can
-work.
-
-At preset, this feature does not support address spaces. It also requires
-@code{Pmode} to be the same as @code{ptr_mode}.
-@end deftypefn
-
-@deftypefn {Target Hook} uint8_t TARGET_MEMTAG_TAG_SIZE ()
-Return the size of a tag (in bits) for this platform.
-
-The default returns 8.
-@end deftypefn
-
-@deftypefn {Target Hook} uint8_t TARGET_MEMTAG_GRANULE_SIZE ()
-Return the size in real memory that each byte in shadow memory refers to.
-I.e. if a variable is @var{X} bytes long in memory, then this hook should
-return the value @var{Y} such that the tag in shadow memory spans
-@var{X}/@var{Y} bytes.
-
-Most variables will need to be aligned to this amount since two variables
-that are neighbors in memory and share a tag granule would need to share
-the same tag.
-
-The default returns 16.
-@end deftypefn
-
-@deftypefn {Target Hook} rtx TARGET_MEMTAG_INSERT_RANDOM_TAG (rtx @var{untagged}, rtx @var{target})
-Return an RTX representing the value of @var{untagged} but with a
-(possibly) random tag in it.
-Put that value into @var{target} if it is convenient to do so.
-This function is used to generate a tagged base for the current stack frame.
-@end deftypefn
-
-@deftypefn {Target Hook} rtx TARGET_MEMTAG_ADD_TAG (rtx @var{base}, poly_int64 @var{addr_offset}, uint8_t @var{tag_offset})
-Return an RTX that represents the result of adding @var{addr_offset} to
-the address in pointer @var{base} and @var{tag_offset} to the tag in pointer
-@var{base}.
-The resulting RTX must either be a valid memory address or be able to get
-put into an operand with @code{force_operand}.
-
-Unlike other memtag hooks, this must return an expression and not emit any
-RTL.
-@end deftypefn
-
-@deftypefn {Target Hook} rtx TARGET_MEMTAG_SET_TAG (rtx @var{untagged_base}, rtx @var{tag}, rtx @var{target})
-Return an RTX representing @var{untagged_base} but with the tag @var{tag}.
-Try and store this in @var{target} if convenient.
-@var{untagged_base} is required to have a zero tag when this hook is called.
-The default of this hook is to set the top byte of @var{untagged_base} to
-@var{tag}.
-@end deftypefn
-
-@deftypefn {Target Hook} rtx TARGET_MEMTAG_EXTRACT_TAG (rtx @var{tagged_pointer}, rtx @var{target})
-Return an RTX representing the tag stored in @var{tagged_pointer}.
-Store the result in @var{target} if it is convenient.
-The default represents the top byte of the original pointer.
-@end deftypefn
-
-@deftypefn {Target Hook} rtx TARGET_MEMTAG_UNTAGGED_POINTER (rtx @var{tagged_pointer}, rtx @var{target})
-Return an RTX representing @var{tagged_pointer} with its tag set to zero.
-Store the result in @var{target} if convenient.
-The default clears the top byte of the original pointer.
-@end deftypefn
-
-@deftypefn {Target Hook} HOST_WIDE_INT TARGET_GCOV_TYPE_SIZE (void)
-Returns the gcov type size in bits. This type is used for example for
-counters incremented by profiling and code-coverage events. The default
-value is 64, if the type size of long long is greater than 32, otherwise the
-default value is 32. A 64-bit type is recommended to avoid overflows of the
-counters. If the @option{-fprofile-update=atomic} is used, then the
-counters are incremented using atomic operations. Targets not supporting
-64-bit atomic operations may override the default value and request a 32-bit
-type.
-@end deftypefn
-
-@deftypevr {Target Hook} bool TARGET_HAVE_SHADOW_CALL_STACK
-This value is true if the target platform supports
-@option{-fsanitize=shadow-call-stack}. The default value is false.
-@end deftypevr
+++ /dev/null
-@c Copyright (C) 1988-2022 Free Software Foundation, Inc.
-@c This is part of the GCC manual.
-@c For copying conditions, see the file gcc.texi.
-
-@node Target Macros
-@chapter Target Description Macros and Functions
-@cindex machine description macros
-@cindex target description macros
-@cindex macros, target description
-@cindex @file{tm.h} macros
-
-In addition to the file @file{@var{machine}.md}, a machine description
-includes a C header file conventionally given the name
-@file{@var{machine}.h} and a C source file named @file{@var{machine}.c}.
-The header file defines numerous macros that convey the information
-about the target machine that does not fit into the scheme of the
-@file{.md} file. The file @file{tm.h} should be a link to
-@file{@var{machine}.h}. The header file @file{config.h} includes
-@file{tm.h} and most compiler source files include @file{config.h}. The
-source file defines a variable @code{targetm}, which is a structure
-containing pointers to functions and data relating to the target
-machine. @file{@var{machine}.c} should also contain their definitions,
-if they are not defined elsewhere in GCC, and other functions called
-through the macros defined in the @file{.h} file.
-
-@menu
-* Target Structure:: The @code{targetm} variable.
-* Driver:: Controlling how the driver runs the compilation passes.
-* Run-time Target:: Defining @samp{-m} options like @option{-m68000} and @option{-m68020}.
-* Per-Function Data:: Defining data structures for per-function information.
-* Storage Layout:: Defining sizes and alignments of data.
-* Type Layout:: Defining sizes and properties of basic user data types.
-* Registers:: Naming and describing the hardware registers.
-* Register Classes:: Defining the classes of hardware registers.
-* Stack and Calling:: Defining which way the stack grows and by how much.
-* Varargs:: Defining the varargs macros.
-* Trampolines:: Code set up at run time to enter a nested function.
-* Library Calls:: Controlling how library routines are implicitly called.
-* Addressing Modes:: Defining addressing modes valid for memory operands.
-* Anchored Addresses:: Defining how @option{-fsection-anchors} should work.
-* Condition Code:: Defining how insns update the condition code.
-* Costs:: Defining relative costs of different operations.
-* Scheduling:: Adjusting the behavior of the instruction scheduler.
-* Sections:: Dividing storage into text, data, and other sections.
-* PIC:: Macros for position independent code.
-* Assembler Format:: Defining how to write insns and pseudo-ops to output.
-* Debugging Info:: Defining the format of debugging output.
-* Floating Point:: Handling floating point for cross-compilers.
-* Mode Switching:: Insertion of mode-switching instructions.
-* Target Attributes:: Defining target-specific uses of @code{__attribute__}.
-* Emulated TLS:: Emulated TLS support.
-* MIPS Coprocessors:: MIPS coprocessor support and how to customize it.
-* PCH Target:: Validity checking for precompiled headers.
-* C++ ABI:: Controlling C++ ABI changes.
-* D Language and ABI:: Controlling D ABI changes.
-* Named Address Spaces:: Adding support for named address spaces
-* Misc:: Everything else.
-@end menu
-
-@node Target Structure
-@section The Global @code{targetm} Variable
-@cindex target hooks
-@cindex target functions
-
-@deftypevar {struct gcc_target} targetm
-The target @file{.c} file must define the global @code{targetm} variable
-which contains pointers to functions and data relating to the target
-machine. The variable is declared in @file{target.h};
-@file{target-def.h} defines the macro @code{TARGET_INITIALIZER} which is
-used to initialize the variable, and macros for the default initializers
-for elements of the structure. The @file{.c} file should override those
-macros for which the default definition is inappropriate. For example:
-@smallexample
-#include "target.h"
-#include "target-def.h"
-
-/* @r{Initialize the GCC target structure.} */
-
-#undef TARGET_COMP_TYPE_ATTRIBUTES
-#define TARGET_COMP_TYPE_ATTRIBUTES @var{machine}_comp_type_attributes
-
-struct gcc_target targetm = TARGET_INITIALIZER;
-@end smallexample
-@end deftypevar
-
-Where a macro should be defined in the @file{.c} file in this manner to
-form part of the @code{targetm} structure, it is documented below as a
-``Target Hook'' with a prototype. Many macros will change in future
-from being defined in the @file{.h} file to being part of the
-@code{targetm} structure.
-
-Similarly, there is a @code{targetcm} variable for hooks that are
-specific to front ends for C-family languages, documented as ``C
-Target Hook''. This is declared in @file{c-family/c-target.h}, the
-initializer @code{TARGETCM_INITIALIZER} in
-@file{c-family/c-target-def.h}. If targets initialize @code{targetcm}
-themselves, they should set @code{target_has_targetcm=yes} in
-@file{config.gcc}; otherwise a default definition is used.
-
-Similarly, there is a @code{targetm_common} variable for hooks that
-are shared between the compiler driver and the compilers proper,
-documented as ``Common Target Hook''. This is declared in
-@file{common/common-target.h}, the initializer
-@code{TARGETM_COMMON_INITIALIZER} in
-@file{common/common-target-def.h}. If targets initialize
-@code{targetm_common} themselves, they should set
-@code{target_has_targetm_common=yes} in @file{config.gcc}; otherwise a
-default definition is used.
-
-Similarly, there is a @code{targetdm} variable for hooks that are
-specific to the D language front end, documented as ``D Target Hook''.
-This is declared in @file{d/d-target.h}, the initializer
-@code{TARGETDM_INITIALIZER} in @file{d/d-target-def.h}. If targets
-initialize @code{targetdm} themselves, they should set
-@code{target_has_targetdm=yes} in @file{config.gcc}; otherwise a default
-definition is used.
-
-@node Driver
-@section Controlling the Compilation Driver, @file{gcc}
-@cindex driver
-@cindex controlling the compilation driver
-
-@c prevent bad page break with this line
-You can control the compilation driver.
-
-@defmac DRIVER_SELF_SPECS
-A list of specs for the driver itself. It should be a suitable
-initializer for an array of strings, with no surrounding braces.
-
-The driver applies these specs to its own command line between loading
-default @file{specs} files (but not command-line specified ones) and
-choosing the multilib directory or running any subcommands. It
-applies them in the order given, so each spec can depend on the
-options added by earlier ones. It is also possible to remove options
-using @samp{%<@var{option}} in the usual way.
-
-This macro can be useful when a port has several interdependent target
-options. It provides a way of standardizing the command line so
-that the other specs are easier to write.
-
-Do not define this macro if it does not need to do anything.
-@end defmac
-
-@defmac OPTION_DEFAULT_SPECS
-A list of specs used to support configure-time default options (i.e.@:
-@option{--with} options) in the driver. It should be a suitable initializer
-for an array of structures, each containing two strings, without the
-outermost pair of surrounding braces.
-
-The first item in the pair is the name of the default. This must match
-the code in @file{config.gcc} for the target. The second item is a spec
-to apply if a default with this name was specified. The string
-@samp{%(VALUE)} in the spec will be replaced by the value of the default
-everywhere it occurs.
-
-The driver will apply these specs to its own command line between loading
-default @file{specs} files and processing @code{DRIVER_SELF_SPECS}, using
-the same mechanism as @code{DRIVER_SELF_SPECS}.
-
-Do not define this macro if it does not need to do anything.
-@end defmac
-
-@defmac CPP_SPEC
-A C string constant that tells the GCC driver program options to
-pass to CPP@. It can also specify how to translate options you
-give to GCC into options for GCC to pass to the CPP@.
-
-Do not define this macro if it does not need to do anything.
-@end defmac
-
-@defmac CPLUSPLUS_CPP_SPEC
-This macro is just like @code{CPP_SPEC}, but is used for C++, rather
-than C@. If you do not define this macro, then the value of
-@code{CPP_SPEC} (if any) will be used instead.
-@end defmac
-
-@defmac CC1_SPEC
-A C string constant that tells the GCC driver program options to
-pass to @code{cc1}, @code{cc1plus}, @code{f771}, and the other language
-front ends.
-It can also specify how to translate options you give to GCC into options
-for GCC to pass to front ends.
-
-Do not define this macro if it does not need to do anything.
-@end defmac
-
-@defmac CC1PLUS_SPEC
-A C string constant that tells the GCC driver program options to
-pass to @code{cc1plus}. It can also specify how to translate options you
-give to GCC into options for GCC to pass to the @code{cc1plus}.
-
-Do not define this macro if it does not need to do anything.
-Note that everything defined in CC1_SPEC is already passed to
-@code{cc1plus} so there is no need to duplicate the contents of
-CC1_SPEC in CC1PLUS_SPEC@.
-@end defmac
-
-@defmac ASM_SPEC
-A C string constant that tells the GCC driver program options to
-pass to the assembler. It can also specify how to translate options
-you give to GCC into options for GCC to pass to the assembler.
-See the file @file{sun3.h} for an example of this.
-
-Do not define this macro if it does not need to do anything.
-@end defmac
-
-@defmac ASM_FINAL_SPEC
-A C string constant that tells the GCC driver program how to
-run any programs which cleanup after the normal assembler.
-Normally, this is not needed. See the file @file{mips.h} for
-an example of this.
-
-Do not define this macro if it does not need to do anything.
-@end defmac
-
-@defmac AS_NEEDS_DASH_FOR_PIPED_INPUT
-Define this macro, with no value, if the driver should give the assembler
-an argument consisting of a single dash, @option{-}, to instruct it to
-read from its standard input (which will be a pipe connected to the
-output of the compiler proper). This argument is given after any
-@option{-o} option specifying the name of the output file.
-
-If you do not define this macro, the assembler is assumed to read its
-standard input if given no non-option arguments. If your assembler
-cannot read standard input at all, use a @samp{%@{pipe:%e@}} construct;
-see @file{mips.h} for instance.
-@end defmac
-
-@defmac LINK_SPEC
-A C string constant that tells the GCC driver program options to
-pass to the linker. It can also specify how to translate options you
-give to GCC into options for GCC to pass to the linker.
-
-Do not define this macro if it does not need to do anything.
-@end defmac
-
-@defmac LIB_SPEC
-Another C string constant used much like @code{LINK_SPEC}. The difference
-between the two is that @code{LIB_SPEC} is used at the end of the
-command given to the linker.
-
-If this macro is not defined, a default is provided that
-loads the standard C library from the usual place. See @file{gcc.cc}.
-@end defmac
-
-@defmac LIBGCC_SPEC
-Another C string constant that tells the GCC driver program
-how and when to place a reference to @file{libgcc.a} into the
-linker command line. This constant is placed both before and after
-the value of @code{LIB_SPEC}.
-
-If this macro is not defined, the GCC driver provides a default that
-passes the string @option{-lgcc} to the linker.
-@end defmac
-
-@defmac REAL_LIBGCC_SPEC
-By default, if @code{ENABLE_SHARED_LIBGCC} is defined, the
-@code{LIBGCC_SPEC} is not directly used by the driver program but is
-instead modified to refer to different versions of @file{libgcc.a}
-depending on the values of the command line flags @option{-static},
-@option{-shared}, @option{-static-libgcc}, and @option{-shared-libgcc}. On
-targets where these modifications are inappropriate, define
-@code{REAL_LIBGCC_SPEC} instead. @code{REAL_LIBGCC_SPEC} tells the
-driver how to place a reference to @file{libgcc} on the link command
-line, but, unlike @code{LIBGCC_SPEC}, it is used unmodified.
-@end defmac
-
-@defmac USE_LD_AS_NEEDED
-A macro that controls the modifications to @code{LIBGCC_SPEC}
-mentioned in @code{REAL_LIBGCC_SPEC}. If nonzero, a spec will be
-generated that uses @option{--as-needed} or equivalent options and the
-shared @file{libgcc} in place of the
-static exception handler library, when linking without any of
-@code{-static}, @code{-static-libgcc}, or @code{-shared-libgcc}.
-@end defmac
-
-@defmac LINK_EH_SPEC
-If defined, this C string constant is added to @code{LINK_SPEC}.
-When @code{USE_LD_AS_NEEDED} is zero or undefined, it also affects
-the modifications to @code{LIBGCC_SPEC} mentioned in
-@code{REAL_LIBGCC_SPEC}.
-@end defmac
-
-@defmac STARTFILE_SPEC
-Another C string constant used much like @code{LINK_SPEC}. The
-difference between the two is that @code{STARTFILE_SPEC} is used at
-the very beginning of the command given to the linker.
-
-If this macro is not defined, a default is provided that loads the
-standard C startup file from the usual place. See @file{gcc.cc}.
-@end defmac
-
-@defmac ENDFILE_SPEC
-Another C string constant used much like @code{LINK_SPEC}. The
-difference between the two is that @code{ENDFILE_SPEC} is used at
-the very end of the command given to the linker.
-
-Do not define this macro if it does not need to do anything.
-@end defmac
-
-@defmac THREAD_MODEL_SPEC
-GCC @code{-v} will print the thread model GCC was configured to use.
-However, this doesn't work on platforms that are multilibbed on thread
-models, such as AIX 4.3. On such platforms, define
-@code{THREAD_MODEL_SPEC} such that it evaluates to a string without
-blanks that names one of the recognized thread models. @code{%*}, the
-default value of this macro, will expand to the value of
-@code{thread_file} set in @file{config.gcc}.
-@end defmac
-
-@defmac SYSROOT_SUFFIX_SPEC
-Define this macro to add a suffix to the target sysroot when GCC is
-configured with a sysroot. This will cause GCC to search for usr/lib,
-et al, within sysroot+suffix.
-@end defmac
-
-@defmac SYSROOT_HEADERS_SUFFIX_SPEC
-Define this macro to add a headers_suffix to the target sysroot when
-GCC is configured with a sysroot. This will cause GCC to pass the
-updated sysroot+headers_suffix to CPP, causing it to search for
-usr/include, et al, within sysroot+headers_suffix.
-@end defmac
-
-@defmac EXTRA_SPECS
-Define this macro to provide additional specifications to put in the
-@file{specs} file that can be used in various specifications like
-@code{CC1_SPEC}.
-
-The definition should be an initializer for an array of structures,
-containing a string constant, that defines the specification name, and a
-string constant that provides the specification.
-
-Do not define this macro if it does not need to do anything.
-
-@code{EXTRA_SPECS} is useful when an architecture contains several
-related targets, which have various @code{@dots{}_SPECS} which are similar
-to each other, and the maintainer would like one central place to keep
-these definitions.
-
-For example, the PowerPC System V.4 targets use @code{EXTRA_SPECS} to
-define either @code{_CALL_SYSV} when the System V calling sequence is
-used or @code{_CALL_AIX} when the older AIX-based calling sequence is
-used.
-
-The @file{config/rs6000/rs6000.h} target file defines:
-
-@smallexample
-#define EXTRA_SPECS \
- @{ "cpp_sysv_default", CPP_SYSV_DEFAULT @},
-
-#define CPP_SYS_DEFAULT ""
-@end smallexample
-
-The @file{config/rs6000/sysv.h} target file defines:
-@smallexample
-#undef CPP_SPEC
-#define CPP_SPEC \
-"%@{posix: -D_POSIX_SOURCE @} \
-%@{mcall-sysv: -D_CALL_SYSV @} \
-%@{!mcall-sysv: %(cpp_sysv_default) @} \
-%@{msoft-float: -D_SOFT_FLOAT@} %@{mcpu=403: -D_SOFT_FLOAT@}"
-
-#undef CPP_SYSV_DEFAULT
-#define CPP_SYSV_DEFAULT "-D_CALL_SYSV"
-@end smallexample
-
-while the @file{config/rs6000/eabiaix.h} target file defines
-@code{CPP_SYSV_DEFAULT} as:
-
-@smallexample
-#undef CPP_SYSV_DEFAULT
-#define CPP_SYSV_DEFAULT "-D_CALL_AIX"
-@end smallexample
-@end defmac
-
-@defmac LINK_LIBGCC_SPECIAL_1
-Define this macro if the driver program should find the library
-@file{libgcc.a}. If you do not define this macro, the driver program will pass
-the argument @option{-lgcc} to tell the linker to do the search.
-@end defmac
-
-@defmac LINK_GCC_C_SEQUENCE_SPEC
-The sequence in which libgcc and libc are specified to the linker.
-By default this is @code{%G %L %G}.
-@end defmac
-
-@defmac POST_LINK_SPEC
-Define this macro to add additional steps to be executed after linker.
-The default value of this macro is empty string.
-@end defmac
-
-@defmac LINK_COMMAND_SPEC
-A C string constant giving the complete command line need to execute the
-linker. When you do this, you will need to update your port each time a
-change is made to the link command line within @file{gcc.cc}. Therefore,
-define this macro only if you need to completely redefine the command
-line for invoking the linker and there is no other way to accomplish
-the effect you need. Overriding this macro may be avoidable by overriding
-@code{LINK_GCC_C_SEQUENCE_SPEC} instead.
-@end defmac
-
-@hook TARGET_ALWAYS_STRIP_DOTDOT
-
-@defmac MULTILIB_DEFAULTS
-Define this macro as a C expression for the initializer of an array of
-string to tell the driver program which options are defaults for this
-target and thus do not need to be handled specially when using
-@code{MULTILIB_OPTIONS}.
-
-Do not define this macro if @code{MULTILIB_OPTIONS} is not defined in
-the target makefile fragment or if none of the options listed in
-@code{MULTILIB_OPTIONS} are set by default.
-@xref{Target Fragment}.
-@end defmac
-
-@defmac RELATIVE_PREFIX_NOT_LINKDIR
-Define this macro to tell @command{gcc} that it should only translate
-a @option{-B} prefix into a @option{-L} linker option if the prefix
-indicates an absolute file name.
-@end defmac
-
-@defmac MD_EXEC_PREFIX
-If defined, this macro is an additional prefix to try after
-@code{STANDARD_EXEC_PREFIX}. @code{MD_EXEC_PREFIX} is not searched
-when the compiler is built as a cross
-compiler. If you define @code{MD_EXEC_PREFIX}, then be sure to add it
-to the list of directories used to find the assembler in @file{configure.ac}.
-@end defmac
-
-@defmac STANDARD_STARTFILE_PREFIX
-Define this macro as a C string constant if you wish to override the
-standard choice of @code{libdir} as the default prefix to
-try when searching for startup files such as @file{crt0.o}.
-@code{STANDARD_STARTFILE_PREFIX} is not searched when the compiler
-is built as a cross compiler.
-@end defmac
-
-@defmac STANDARD_STARTFILE_PREFIX_1
-Define this macro as a C string constant if you wish to override the
-standard choice of @code{/lib} as a prefix to try after the default prefix
-when searching for startup files such as @file{crt0.o}.
-@code{STANDARD_STARTFILE_PREFIX_1} is not searched when the compiler
-is built as a cross compiler.
-@end defmac
-
-@defmac STANDARD_STARTFILE_PREFIX_2
-Define this macro as a C string constant if you wish to override the
-standard choice of @code{/lib} as yet another prefix to try after the
-default prefix when searching for startup files such as @file{crt0.o}.
-@code{STANDARD_STARTFILE_PREFIX_2} is not searched when the compiler
-is built as a cross compiler.
-@end defmac
-
-@defmac MD_STARTFILE_PREFIX
-If defined, this macro supplies an additional prefix to try after the
-standard prefixes. @code{MD_EXEC_PREFIX} is not searched when the
-compiler is built as a cross compiler.
-@end defmac
-
-@defmac MD_STARTFILE_PREFIX_1
-If defined, this macro supplies yet another prefix to try after the
-standard prefixes. It is not searched when the compiler is built as a
-cross compiler.
-@end defmac
-
-@defmac INIT_ENVIRONMENT
-Define this macro as a C string constant if you wish to set environment
-variables for programs called by the driver, such as the assembler and
-loader. The driver passes the value of this macro to @code{putenv} to
-initialize the necessary environment variables.
-@end defmac
-
-@defmac LOCAL_INCLUDE_DIR
-Define this macro as a C string constant if you wish to override the
-standard choice of @file{/usr/local/include} as the default prefix to
-try when searching for local header files. @code{LOCAL_INCLUDE_DIR}
-comes before @code{NATIVE_SYSTEM_HEADER_DIR} (set in
-@file{config.gcc}, normally @file{/usr/include}) in the search order.
-
-Cross compilers do not search either @file{/usr/local/include} or its
-replacement.
-@end defmac
-
-@defmac NATIVE_SYSTEM_HEADER_COMPONENT
-The ``component'' corresponding to @code{NATIVE_SYSTEM_HEADER_DIR}.
-See @code{INCLUDE_DEFAULTS}, below, for the description of components.
-If you do not define this macro, no component is used.
-@end defmac
-
-@defmac INCLUDE_DEFAULTS
-Define this macro if you wish to override the entire default search path
-for include files. For a native compiler, the default search path
-usually consists of @code{GCC_INCLUDE_DIR}, @code{LOCAL_INCLUDE_DIR},
-@code{GPLUSPLUS_INCLUDE_DIR}, and
-@code{NATIVE_SYSTEM_HEADER_DIR}. In addition, @code{GPLUSPLUS_INCLUDE_DIR}
-and @code{GCC_INCLUDE_DIR} are defined automatically by @file{Makefile},
-and specify private search areas for GCC@. The directory
-@code{GPLUSPLUS_INCLUDE_DIR} is used only for C++ programs.
-
-The definition should be an initializer for an array of structures.
-Each array element should have four elements: the directory name (a
-string constant), the component name (also a string constant), a flag
-for C++-only directories,
-and a flag showing that the includes in the directory don't need to be
-wrapped in @code{extern @samp{C}} when compiling C++. Mark the end of
-the array with a null element.
-
-The component name denotes what GNU package the include file is part of,
-if any, in all uppercase letters. For example, it might be @samp{GCC}
-or @samp{BINUTILS}. If the package is part of a vendor-supplied
-operating system, code the component name as @samp{0}.
-
-For example, here is the definition used for VAX/VMS:
-
-@smallexample
-#define INCLUDE_DEFAULTS \
-@{ \
- @{ "GNU_GXX_INCLUDE:", "G++", 1, 1@}, \
- @{ "GNU_CC_INCLUDE:", "GCC", 0, 0@}, \
- @{ "SYS$SYSROOT:[SYSLIB.]", 0, 0, 0@}, \
- @{ ".", 0, 0, 0@}, \
- @{ 0, 0, 0, 0@} \
-@}
-@end smallexample
-@end defmac
-
-Here is the order of prefixes tried for exec files:
-
-@enumerate
-@item
-Any prefixes specified by the user with @option{-B}.
-
-@item
-The environment variable @code{GCC_EXEC_PREFIX} or, if @code{GCC_EXEC_PREFIX}
-is not set and the compiler has not been installed in the configure-time
-@var{prefix}, the location in which the compiler has actually been installed.
-
-@item
-The directories specified by the environment variable @code{COMPILER_PATH}.
-
-@item
-The macro @code{STANDARD_EXEC_PREFIX}, if the compiler has been installed
-in the configured-time @var{prefix}.
-
-@item
-The location @file{/usr/libexec/gcc/}, but only if this is a native compiler.
-
-@item
-The location @file{/usr/lib/gcc/}, but only if this is a native compiler.
-
-@item
-The macro @code{MD_EXEC_PREFIX}, if defined, but only if this is a native
-compiler.
-@end enumerate
-
-Here is the order of prefixes tried for startfiles:
-
-@enumerate
-@item
-Any prefixes specified by the user with @option{-B}.
-
-@item
-The environment variable @code{GCC_EXEC_PREFIX} or its automatically determined
-value based on the installed toolchain location.
-
-@item
-The directories specified by the environment variable @code{LIBRARY_PATH}
-(or port-specific name; native only, cross compilers do not use this).
-
-@item
-The macro @code{STANDARD_EXEC_PREFIX}, but only if the toolchain is installed
-in the configured @var{prefix} or this is a native compiler.
-
-@item
-The location @file{/usr/lib/gcc/}, but only if this is a native compiler.
-
-@item
-The macro @code{MD_EXEC_PREFIX}, if defined, but only if this is a native
-compiler.
-
-@item
-The macro @code{MD_STARTFILE_PREFIX}, if defined, but only if this is a
-native compiler, or we have a target system root.
-
-@item
-The macro @code{MD_STARTFILE_PREFIX_1}, if defined, but only if this is a
-native compiler, or we have a target system root.
-
-@item
-The macro @code{STANDARD_STARTFILE_PREFIX}, with any sysroot modifications.
-If this path is relative it will be prefixed by @code{GCC_EXEC_PREFIX} and
-the machine suffix or @code{STANDARD_EXEC_PREFIX} and the machine suffix.
-
-@item
-The macro @code{STANDARD_STARTFILE_PREFIX_1}, but only if this is a native
-compiler, or we have a target system root. The default for this macro is
-@file{/lib/}.
-
-@item
-The macro @code{STANDARD_STARTFILE_PREFIX_2}, but only if this is a native
-compiler, or we have a target system root. The default for this macro is
-@file{/usr/lib/}.
-@end enumerate
-
-@node Run-time Target
-@section Run-time Target Specification
-@cindex run-time target specification
-@cindex predefined macros
-@cindex target specifications
-
-@c prevent bad page break with this line
-Here are run-time target specifications.
-
-@defmac TARGET_CPU_CPP_BUILTINS ()
-This function-like macro expands to a block of code that defines
-built-in preprocessor macros and assertions for the target CPU, using
-the functions @code{builtin_define}, @code{builtin_define_std} and
-@code{builtin_assert}. When the front end
-calls this macro it provides a trailing semicolon, and since it has
-finished command line option processing your code can use those
-results freely.
-
-@code{builtin_assert} takes a string in the form you pass to the
-command-line option @option{-A}, such as @code{cpu=mips}, and creates
-the assertion. @code{builtin_define} takes a string in the form
-accepted by option @option{-D} and unconditionally defines the macro.
-
-@code{builtin_define_std} takes a string representing the name of an
-object-like macro. If it doesn't lie in the user's namespace,
-@code{builtin_define_std} defines it unconditionally. Otherwise, it
-defines a version with two leading underscores, and another version
-with two leading and trailing underscores, and defines the original
-only if an ISO standard was not requested on the command line. For
-example, passing @code{unix} defines @code{__unix}, @code{__unix__}
-and possibly @code{unix}; passing @code{_mips} defines @code{__mips},
-@code{__mips__} and possibly @code{_mips}, and passing @code{_ABI64}
-defines only @code{_ABI64}.
-
-You can also test for the C dialect being compiled. The variable
-@code{c_language} is set to one of @code{clk_c}, @code{clk_cplusplus}
-or @code{clk_objective_c}. Note that if we are preprocessing
-assembler, this variable will be @code{clk_c} but the function-like
-macro @code{preprocessing_asm_p()} will return true, so you might want
-to check for that first. If you need to check for strict ANSI, the
-variable @code{flag_iso} can be used. The function-like macro
-@code{preprocessing_trad_p()} can be used to check for traditional
-preprocessing.
-@end defmac
-
-@defmac TARGET_OS_CPP_BUILTINS ()
-Similarly to @code{TARGET_CPU_CPP_BUILTINS} but this macro is optional
-and is used for the target operating system instead.
-@end defmac
-
-@defmac TARGET_OBJFMT_CPP_BUILTINS ()
-Similarly to @code{TARGET_CPU_CPP_BUILTINS} but this macro is optional
-and is used for the target object format. @file{elfos.h} uses this
-macro to define @code{__ELF__}, so you probably do not need to define
-it yourself.
-@end defmac
-
-@deftypevar {extern int} target_flags
-This variable is declared in @file{options.h}, which is included before
-any target-specific headers.
-@end deftypevar
-
-@hook TARGET_DEFAULT_TARGET_FLAGS
-This variable specifies the initial value of @code{target_flags}.
-Its default setting is 0.
-@end deftypevr
-
-@cindex optional hardware or system features
-@cindex features, optional, in system conventions
-
-@hook TARGET_HANDLE_OPTION
-This hook is called whenever the user specifies one of the
-target-specific options described by the @file{.opt} definition files
-(@pxref{Options}). It has the opportunity to do some option-specific
-processing and should return true if the option is valid. The default
-definition does nothing but return true.
-
-@var{decoded} specifies the option and its arguments. @var{opts} and
-@var{opts_set} are the @code{gcc_options} structures to be used for
-storing option state, and @var{loc} is the location at which the
-option was passed (@code{UNKNOWN_LOCATION} except for options passed
-via attributes).
-@end deftypefn
-
-@hook TARGET_HANDLE_C_OPTION
-This target hook is called whenever the user specifies one of the
-target-specific C language family options described by the @file{.opt}
-definition files(@pxref{Options}). It has the opportunity to do some
-option-specific processing and should return true if the option is
-valid. The arguments are like for @code{TARGET_HANDLE_OPTION}. The
-default definition does nothing but return false.
-
-In general, you should use @code{TARGET_HANDLE_OPTION} to handle
-options. However, if processing an option requires routines that are
-only available in the C (and related language) front ends, then you
-should use @code{TARGET_HANDLE_C_OPTION} instead.
-@end deftypefn
-
-@hook TARGET_OBJC_CONSTRUCT_STRING_OBJECT
-
-@hook TARGET_OBJC_DECLARE_UNRESOLVED_CLASS_REFERENCE
-
-@hook TARGET_OBJC_DECLARE_CLASS_DEFINITION
-
-@hook TARGET_STRING_OBJECT_REF_TYPE_P
-
-@hook TARGET_CHECK_STRING_OBJECT_FORMAT_ARG
-
-@hook TARGET_OVERRIDE_OPTIONS_AFTER_CHANGE
-
-@defmac C_COMMON_OVERRIDE_OPTIONS
-This is similar to the @code{TARGET_OPTION_OVERRIDE} hook
-but is only used in the C
-language frontends (C, Objective-C, C++, Objective-C++) and so can be
-used to alter option flag variables which only exist in those
-frontends.
-@end defmac
-
-@hook TARGET_OPTION_OPTIMIZATION_TABLE
-Some machines may desire to change what optimizations are performed for
-various optimization levels. This variable, if defined, describes
-options to enable at particular sets of optimization levels. These
-options are processed once
-just after the optimization level is determined and before the remainder
-of the command options have been parsed, so may be overridden by other
-options passed explicitly.
-
-This processing is run once at program startup and when the optimization
-options are changed via @code{#pragma GCC optimize} or by using the
-@code{optimize} attribute.
-@end deftypevr
-
-@hook TARGET_OPTION_INIT_STRUCT
-
-@hook TARGET_COMPUTE_MULTILIB
-
-
-@defmac SWITCHABLE_TARGET
-Some targets need to switch between substantially different subtargets
-during compilation. For example, the MIPS target has one subtarget for
-the traditional MIPS architecture and another for MIPS16. Source code
-can switch between these two subarchitectures using the @code{mips16}
-and @code{nomips16} attributes.
-
-Such subtargets can differ in things like the set of available
-registers, the set of available instructions, the costs of various
-operations, and so on. GCC caches a lot of this type of information
-in global variables, and recomputing them for each subtarget takes a
-significant amount of time. The compiler therefore provides a facility
-for maintaining several versions of the global variables and quickly
-switching between them; see @file{target-globals.h} for details.
-
-Define this macro to 1 if your target needs this facility. The default
-is 0.
-@end defmac
-
-@hook TARGET_FLOAT_EXCEPTIONS_ROUNDING_SUPPORTED_P
-
-@node Per-Function Data
-@section Defining data structures for per-function information.
-@cindex per-function data
-@cindex data structures
-
-If the target needs to store information on a per-function basis, GCC
-provides a macro and a couple of variables to allow this. Note, just
-using statics to store the information is a bad idea, since GCC supports
-nested functions, so you can be halfway through encoding one function
-when another one comes along.
-
-GCC defines a data structure called @code{struct function} which
-contains all of the data specific to an individual function. This
-structure contains a field called @code{machine} whose type is
-@code{struct machine_function *}, which can be used by targets to point
-to their own specific data.
-
-If a target needs per-function specific data it should define the type
-@code{struct machine_function} and also the macro @code{INIT_EXPANDERS}.
-This macro should be used to initialize the function pointer
-@code{init_machine_status}. This pointer is explained below.
-
-One typical use of per-function, target specific data is to create an
-RTX to hold the register containing the function's return address. This
-RTX can then be used to implement the @code{__builtin_return_address}
-function, for level 0.
-
-Note---earlier implementations of GCC used a single data area to hold
-all of the per-function information. Thus when processing of a nested
-function began the old per-function data had to be pushed onto a
-stack, and when the processing was finished, it had to be popped off the
-stack. GCC used to provide function pointers called
-@code{save_machine_status} and @code{restore_machine_status} to handle
-the saving and restoring of the target specific information. Since the
-single data area approach is no longer used, these pointers are no
-longer supported.
-
-@defmac INIT_EXPANDERS
-Macro called to initialize any target specific information. This macro
-is called once per function, before generation of any RTL has begun.
-The intention of this macro is to allow the initialization of the
-function pointer @code{init_machine_status}.
-@end defmac
-
-@deftypevar {void (*)(struct function *)} init_machine_status
-If this function pointer is non-@code{NULL} it will be called once per
-function, before function compilation starts, in order to allow the
-target to perform any target specific initialization of the
-@code{struct function} structure. It is intended that this would be
-used to initialize the @code{machine} of that structure.
-
-@code{struct machine_function} structures are expected to be freed by GC@.
-Generally, any memory that they reference must be allocated by using
-GC allocation, including the structure itself.
-@end deftypevar
-
-@node Storage Layout
-@section Storage Layout
-@cindex storage layout
-
-Note that the definitions of the macros in this table which are sizes or
-alignments measured in bits do not need to be constant. They can be C
-expressions that refer to static variables, such as the @code{target_flags}.
-@xref{Run-time Target}.
-
-@defmac BITS_BIG_ENDIAN
-Define this macro to have the value 1 if the most significant bit in a
-byte has the lowest number; otherwise define it to have the value zero.
-This means that bit-field instructions count from the most significant
-bit. If the machine has no bit-field instructions, then this must still
-be defined, but it doesn't matter which value it is defined to. This
-macro need not be a constant.
-
-This macro does not affect the way structure fields are packed into
-bytes or words; that is controlled by @code{BYTES_BIG_ENDIAN}.
-@end defmac
-
-@defmac BYTES_BIG_ENDIAN
-Define this macro to have the value 1 if the most significant byte in a
-word has the lowest number. This macro need not be a constant.
-@end defmac
-
-@defmac WORDS_BIG_ENDIAN
-Define this macro to have the value 1 if, in a multiword object, the
-most significant word has the lowest number. This applies to both
-memory locations and registers; see @code{REG_WORDS_BIG_ENDIAN} if the
-order of words in memory is not the same as the order in registers. This
-macro need not be a constant.
-@end defmac
-
-@defmac REG_WORDS_BIG_ENDIAN
-On some machines, the order of words in a multiword object differs between
-registers in memory. In such a situation, define this macro to describe
-the order of words in a register. The macro @code{WORDS_BIG_ENDIAN} controls
-the order of words in memory.
-@end defmac
-
-@defmac FLOAT_WORDS_BIG_ENDIAN
-Define this macro to have the value 1 if @code{DFmode}, @code{XFmode} or
-@code{TFmode} floating point numbers are stored in memory with the word
-containing the sign bit at the lowest address; otherwise define it to
-have the value 0. This macro need not be a constant.
-
-You need not define this macro if the ordering is the same as for
-multi-word integers.
-@end defmac
-
-@defmac BITS_PER_WORD
-Number of bits in a word. If you do not define this macro, the default
-is @code{BITS_PER_UNIT * UNITS_PER_WORD}.
-@end defmac
-
-@defmac MAX_BITS_PER_WORD
-Maximum number of bits in a word. If this is undefined, the default is
-@code{BITS_PER_WORD}. Otherwise, it is the constant value that is the
-largest value that @code{BITS_PER_WORD} can have at run-time.
-@end defmac
-
-@defmac UNITS_PER_WORD
-Number of storage units in a word; normally the size of a general-purpose
-register, a power of two from 1 or 8.
-@end defmac
-
-@defmac MIN_UNITS_PER_WORD
-Minimum number of units in a word. If this is undefined, the default is
-@code{UNITS_PER_WORD}. Otherwise, it is the constant value that is the
-smallest value that @code{UNITS_PER_WORD} can have at run-time.
-@end defmac
-
-@defmac POINTER_SIZE
-Width of a pointer, in bits. You must specify a value no wider than the
-width of @code{Pmode}. If it is not equal to the width of @code{Pmode},
-you must define @code{POINTERS_EXTEND_UNSIGNED}. If you do not specify
-a value the default is @code{BITS_PER_WORD}.
-@end defmac
-
-@defmac POINTERS_EXTEND_UNSIGNED
-A C expression that determines how pointers should be extended from
-@code{ptr_mode} to either @code{Pmode} or @code{word_mode}. It is
-greater than zero if pointers should be zero-extended, zero if they
-should be sign-extended, and negative if some other sort of conversion
-is needed. In the last case, the extension is done by the target's
-@code{ptr_extend} instruction.
-
-You need not define this macro if the @code{ptr_mode}, @code{Pmode}
-and @code{word_mode} are all the same width.
-@end defmac
-
-@defmac PROMOTE_MODE (@var{m}, @var{unsignedp}, @var{type})
-A macro to update @var{m} and @var{unsignedp} when an object whose type
-is @var{type} and which has the specified mode and signedness is to be
-stored in a register. This macro is only called when @var{type} is a
-scalar type.
-
-On most RISC machines, which only have operations that operate on a full
-register, define this macro to set @var{m} to @code{word_mode} if
-@var{m} is an integer mode narrower than @code{BITS_PER_WORD}. In most
-cases, only integer modes should be widened because wider-precision
-floating-point operations are usually more expensive than their narrower
-counterparts.
-
-For most machines, the macro definition does not change @var{unsignedp}.
-However, some machines, have instructions that preferentially handle
-either signed or unsigned quantities of certain modes. For example, on
-the DEC Alpha, 32-bit loads from memory and 32-bit add instructions
-sign-extend the result to 64 bits. On such machines, set
-@var{unsignedp} according to which kind of extension is more efficient.
-
-Do not define this macro if it would never modify @var{m}.
-@end defmac
-
-@hook TARGET_C_EXCESS_PRECISION
-Return a value, with the same meaning as the C99 macro
-@code{FLT_EVAL_METHOD} that describes which excess precision should be
-applied.
-
-@hook TARGET_PROMOTE_FUNCTION_MODE
-
-@defmac PARM_BOUNDARY
-Normal alignment required for function parameters on the stack, in
-bits. All stack parameters receive at least this much alignment
-regardless of data type. On most machines, this is the same as the
-size of an integer.
-@end defmac
-
-@defmac STACK_BOUNDARY
-Define this macro to the minimum alignment enforced by hardware for the
-stack pointer on this machine. The definition is a C expression for the
-desired alignment (measured in bits). This value is used as a default
-if @code{PREFERRED_STACK_BOUNDARY} is not defined. On most machines,
-this should be the same as @code{PARM_BOUNDARY}.
-@end defmac
-
-@defmac PREFERRED_STACK_BOUNDARY
-Define this macro if you wish to preserve a certain alignment for the
-stack pointer, greater than what the hardware enforces. The definition
-is a C expression for the desired alignment (measured in bits). This
-macro must evaluate to a value equal to or larger than
-@code{STACK_BOUNDARY}.
-@end defmac
-
-@defmac INCOMING_STACK_BOUNDARY
-Define this macro if the incoming stack boundary may be different
-from @code{PREFERRED_STACK_BOUNDARY}. This macro must evaluate
-to a value equal to or larger than @code{STACK_BOUNDARY}.
-@end defmac
-
-@defmac FUNCTION_BOUNDARY
-Alignment required for a function entry point, in bits.
-@end defmac
-
-@defmac BIGGEST_ALIGNMENT
-Biggest alignment that any data type can require on this machine, in
-bits. Note that this is not the biggest alignment that is supported,
-just the biggest alignment that, when violated, may cause a fault.
-@end defmac
-
-@hook TARGET_ABSOLUTE_BIGGEST_ALIGNMENT
-
-@defmac MALLOC_ABI_ALIGNMENT
-Alignment, in bits, a C conformant malloc implementation has to
-provide. If not defined, the default value is @code{BITS_PER_WORD}.
-@end defmac
-
-@defmac ATTRIBUTE_ALIGNED_VALUE
-Alignment used by the @code{__attribute__ ((aligned))} construct. If
-not defined, the default value is @code{BIGGEST_ALIGNMENT}.
-@end defmac
-
-@defmac MINIMUM_ATOMIC_ALIGNMENT
-If defined, the smallest alignment, in bits, that can be given to an
-object that can be referenced in one operation, without disturbing any
-nearby object. Normally, this is @code{BITS_PER_UNIT}, but may be larger
-on machines that don't have byte or half-word store operations.
-@end defmac
-
-@defmac BIGGEST_FIELD_ALIGNMENT
-Biggest alignment that any structure or union field can require on this
-machine, in bits. If defined, this overrides @code{BIGGEST_ALIGNMENT} for
-structure and union fields only, unless the field alignment has been set
-by the @code{__attribute__ ((aligned (@var{n})))} construct.
-@end defmac
-
-@defmac ADJUST_FIELD_ALIGN (@var{field}, @var{type}, @var{computed})
-An expression for the alignment of a structure field @var{field} of
-type @var{type} if the alignment computed in the usual way (including
-applying of @code{BIGGEST_ALIGNMENT} and @code{BIGGEST_FIELD_ALIGNMENT} to the
-alignment) is @var{computed}. It overrides alignment only if the
-field alignment has not been set by the
-@code{__attribute__ ((aligned (@var{n})))} construct. Note that @var{field}
-may be @code{NULL_TREE} in case we just query for the minimum alignment
-of a field of type @var{type} in structure context.
-@end defmac
-
-@defmac MAX_STACK_ALIGNMENT
-Biggest stack alignment guaranteed by the backend. Use this macro
-to specify the maximum alignment of a variable on stack.
-
-If not defined, the default value is @code{STACK_BOUNDARY}.
-
-@c FIXME: The default should be @code{PREFERRED_STACK_BOUNDARY}.
-@c But the fix for PR 32893 indicates that we can only guarantee
-@c maximum stack alignment on stack up to @code{STACK_BOUNDARY}, not
-@c @code{PREFERRED_STACK_BOUNDARY}, if stack alignment isn't supported.
-@end defmac
-
-@defmac MAX_OFILE_ALIGNMENT
-Biggest alignment supported by the object file format of this machine.
-Use this macro to limit the alignment which can be specified using the
-@code{__attribute__ ((aligned (@var{n})))} construct for functions and
-objects with static storage duration. The alignment of automatic
-objects may exceed the object file format maximum up to the maximum
-supported by GCC. If not defined, the default value is
-@code{BIGGEST_ALIGNMENT}.
-
-On systems that use ELF, the default (in @file{config/elfos.h}) is
-the largest supported 32-bit ELF section alignment representable on
-a 32-bit host e.g.@: @samp{(((uint64_t) 1 << 28) * 8)}.
-On 32-bit ELF the largest supported section alignment in bits is
-@samp{(0x80000000 * 8)}, but this is not representable on 32-bit hosts.
-@end defmac
-
-@hook TARGET_LOWER_LOCAL_DECL_ALIGNMENT
-
-@hook TARGET_STATIC_RTX_ALIGNMENT
-
-@defmac DATA_ALIGNMENT (@var{type}, @var{basic-align})
-If defined, a C expression to compute the alignment for a variable in
-the static store. @var{type} is the data type, and @var{basic-align} is
-the alignment that the object would ordinarily have. The value of this
-macro is used instead of that alignment to align the object.
-
-If this macro is not defined, then @var{basic-align} is used.
-
-@findex strcpy
-One use of this macro is to increase alignment of medium-size data to
-make it all fit in fewer cache lines. Another is to cause character
-arrays to be word-aligned so that @code{strcpy} calls that copy
-constants to character arrays can be done inline.
-@end defmac
-
-@defmac DATA_ABI_ALIGNMENT (@var{type}, @var{basic-align})
-Similar to @code{DATA_ALIGNMENT}, but for the cases where the ABI mandates
-some alignment increase, instead of optimization only purposes. E.g.@
-AMD x86-64 psABI says that variables with array type larger than 15 bytes
-must be aligned to 16 byte boundaries.
-
-If this macro is not defined, then @var{basic-align} is used.
-@end defmac
-
-@hook TARGET_CONSTANT_ALIGNMENT
-
-@defmac LOCAL_ALIGNMENT (@var{type}, @var{basic-align})
-If defined, a C expression to compute the alignment for a variable in
-the local store. @var{type} is the data type, and @var{basic-align} is
-the alignment that the object would ordinarily have. The value of this
-macro is used instead of that alignment to align the object.
-
-If this macro is not defined, then @var{basic-align} is used.
-
-One use of this macro is to increase alignment of medium-size data to
-make it all fit in fewer cache lines.
-
-If the value of this macro has a type, it should be an unsigned type.
-@end defmac
-
-@hook TARGET_VECTOR_ALIGNMENT
-
-@defmac STACK_SLOT_ALIGNMENT (@var{type}, @var{mode}, @var{basic-align})
-If defined, a C expression to compute the alignment for stack slot.
-@var{type} is the data type, @var{mode} is the widest mode available,
-and @var{basic-align} is the alignment that the slot would ordinarily
-have. The value of this macro is used instead of that alignment to
-align the slot.
-
-If this macro is not defined, then @var{basic-align} is used when
-@var{type} is @code{NULL}. Otherwise, @code{LOCAL_ALIGNMENT} will
-be used.
-
-This macro is to set alignment of stack slot to the maximum alignment
-of all possible modes which the slot may have.
-
-If the value of this macro has a type, it should be an unsigned type.
-@end defmac
-
-@defmac LOCAL_DECL_ALIGNMENT (@var{decl})
-If defined, a C expression to compute the alignment for a local
-variable @var{decl}.
-
-If this macro is not defined, then
-@code{LOCAL_ALIGNMENT (TREE_TYPE (@var{decl}), DECL_ALIGN (@var{decl}))}
-is used.
-
-One use of this macro is to increase alignment of medium-size data to
-make it all fit in fewer cache lines.
-
-If the value of this macro has a type, it should be an unsigned type.
-@end defmac
-
-@defmac MINIMUM_ALIGNMENT (@var{exp}, @var{mode}, @var{align})
-If defined, a C expression to compute the minimum required alignment
-for dynamic stack realignment purposes for @var{exp} (a type or decl),
-@var{mode}, assuming normal alignment @var{align}.
-
-If this macro is not defined, then @var{align} will be used.
-@end defmac
-
-@defmac EMPTY_FIELD_BOUNDARY
-Alignment in bits to be given to a structure bit-field that follows an
-empty field such as @code{int : 0;}.
-
-If @code{PCC_BITFIELD_TYPE_MATTERS} is true, it overrides this macro.
-@end defmac
-
-@defmac STRUCTURE_SIZE_BOUNDARY
-Number of bits which any structure or union's size must be a multiple of.
-Each structure or union's size is rounded up to a multiple of this.
-
-If you do not define this macro, the default is the same as
-@code{BITS_PER_UNIT}.
-@end defmac
-
-@defmac STRICT_ALIGNMENT
-Define this macro to be the value 1 if instructions will fail to work
-if given data not on the nominal alignment. If instructions will merely
-go slower in that case, define this macro as 0.
-@end defmac
-
-@defmac PCC_BITFIELD_TYPE_MATTERS
-Define this if you wish to imitate the way many other C compilers handle
-alignment of bit-fields and the structures that contain them.
-
-The behavior is that the type written for a named bit-field (@code{int},
-@code{short}, or other integer type) imposes an alignment for the entire
-structure, as if the structure really did contain an ordinary field of
-that type. In addition, the bit-field is placed within the structure so
-that it would fit within such a field, not crossing a boundary for it.
-
-Thus, on most machines, a named bit-field whose type is written as
-@code{int} would not cross a four-byte boundary, and would force
-four-byte alignment for the whole structure. (The alignment used may
-not be four bytes; it is controlled by the other alignment parameters.)
-
-An unnamed bit-field will not affect the alignment of the containing
-structure.
-
-If the macro is defined, its definition should be a C expression;
-a nonzero value for the expression enables this behavior.
-
-Note that if this macro is not defined, or its value is zero, some
-bit-fields may cross more than one alignment boundary. The compiler can
-support such references if there are @samp{insv}, @samp{extv}, and
-@samp{extzv} insns that can directly reference memory.
-
-The other known way of making bit-fields work is to define
-@code{STRUCTURE_SIZE_BOUNDARY} as large as @code{BIGGEST_ALIGNMENT}.
-Then every structure can be accessed with fullwords.
-
-Unless the machine has bit-field instructions or you define
-@code{STRUCTURE_SIZE_BOUNDARY} that way, you must define
-@code{PCC_BITFIELD_TYPE_MATTERS} to have a nonzero value.
-
-If your aim is to make GCC use the same conventions for laying out
-bit-fields as are used by another compiler, here is how to investigate
-what the other compiler does. Compile and run this program:
-
-@smallexample
-struct foo1
-@{
- char x;
- char :0;
- char y;
-@};
-
-struct foo2
-@{
- char x;
- int :0;
- char y;
-@};
-
-main ()
-@{
- printf ("Size of foo1 is %d\n",
- sizeof (struct foo1));
- printf ("Size of foo2 is %d\n",
- sizeof (struct foo2));
- exit (0);
-@}
-@end smallexample
-
-If this prints 2 and 5, then the compiler's behavior is what you would
-get from @code{PCC_BITFIELD_TYPE_MATTERS}.
-@end defmac
-
-@defmac BITFIELD_NBYTES_LIMITED
-Like @code{PCC_BITFIELD_TYPE_MATTERS} except that its effect is limited
-to aligning a bit-field within the structure.
-@end defmac
-
-@hook TARGET_ALIGN_ANON_BITFIELD
-
-@hook TARGET_NARROW_VOLATILE_BITFIELD
-
-@hook TARGET_MEMBER_TYPE_FORCES_BLK
-
-@defmac ROUND_TYPE_ALIGN (@var{type}, @var{computed}, @var{specified})
-Define this macro as an expression for the alignment of a type (given
-by @var{type} as a tree node) if the alignment computed in the usual
-way is @var{computed} and the alignment explicitly specified was
-@var{specified}.
-
-The default is to use @var{specified} if it is larger; otherwise, use
-the smaller of @var{computed} and @code{BIGGEST_ALIGNMENT}
-@end defmac
-
-@defmac MAX_FIXED_MODE_SIZE
-An integer expression for the size in bits of the largest integer
-machine mode that should actually be used. All integer machine modes of
-this size or smaller can be used for structures and unions with the
-appropriate sizes. If this macro is undefined, @code{GET_MODE_BITSIZE
-(DImode)} is assumed.
-@end defmac
-
-@defmac STACK_SAVEAREA_MODE (@var{save_level})
-If defined, an expression of type @code{machine_mode} that
-specifies the mode of the save area operand of a
-@code{save_stack_@var{level}} named pattern (@pxref{Standard Names}).
-@var{save_level} is one of @code{SAVE_BLOCK}, @code{SAVE_FUNCTION}, or
-@code{SAVE_NONLOCAL} and selects which of the three named patterns is
-having its mode specified.
-
-You need not define this macro if it always returns @code{Pmode}. You
-would most commonly define this macro if the
-@code{save_stack_@var{level}} patterns need to support both a 32- and a
-64-bit mode.
-@end defmac
-
-@defmac STACK_SIZE_MODE
-If defined, an expression of type @code{machine_mode} that
-specifies the mode of the size increment operand of an
-@code{allocate_stack} named pattern (@pxref{Standard Names}).
-
-You need not define this macro if it always returns @code{word_mode}.
-You would most commonly define this macro if the @code{allocate_stack}
-pattern needs to support both a 32- and a 64-bit mode.
-@end defmac
-
-@hook TARGET_LIBGCC_CMP_RETURN_MODE
-
-@hook TARGET_LIBGCC_SHIFT_COUNT_MODE
-
-@hook TARGET_UNWIND_WORD_MODE
-
-@hook TARGET_MS_BITFIELD_LAYOUT_P
-
-@hook TARGET_DECIMAL_FLOAT_SUPPORTED_P
-
-@hook TARGET_FIXED_POINT_SUPPORTED_P
-
-@hook TARGET_EXPAND_TO_RTL_HOOK
-
-@hook TARGET_INSTANTIATE_DECLS
-
-@hook TARGET_MANGLE_TYPE
-
-@node Type Layout
-@section Layout of Source Language Data Types
-
-These macros define the sizes and other characteristics of the standard
-basic data types used in programs being compiled. Unlike the macros in
-the previous section, these apply to specific features of C and related
-languages, rather than to fundamental aspects of storage layout.
-
-@defmac INT_TYPE_SIZE
-A C expression for the size in bits of the type @code{int} on the
-target machine. If you don't define this, the default is one word.
-@end defmac
-
-@defmac SHORT_TYPE_SIZE
-A C expression for the size in bits of the type @code{short} on the
-target machine. If you don't define this, the default is half a word.
-(If this would be less than one storage unit, it is rounded up to one
-unit.)
-@end defmac
-
-@defmac LONG_TYPE_SIZE
-A C expression for the size in bits of the type @code{long} on the
-target machine. If you don't define this, the default is one word.
-@end defmac
-
-@defmac ADA_LONG_TYPE_SIZE
-On some machines, the size used for the Ada equivalent of the type
-@code{long} by a native Ada compiler differs from that used by C@. In
-that situation, define this macro to be a C expression to be used for
-the size of that type. If you don't define this, the default is the
-value of @code{LONG_TYPE_SIZE}.
-@end defmac
-
-@defmac LONG_LONG_TYPE_SIZE
-A C expression for the size in bits of the type @code{long long} on the
-target machine. If you don't define this, the default is two
-words. If you want to support GNU Ada on your machine, the value of this
-macro must be at least 64.
-@end defmac
-
-@defmac CHAR_TYPE_SIZE
-A C expression for the size in bits of the type @code{char} on the
-target machine. If you don't define this, the default is
-@code{BITS_PER_UNIT}.
-@end defmac
-
-@defmac BOOL_TYPE_SIZE
-A C expression for the size in bits of the C++ type @code{bool} and
-C99 type @code{_Bool} on the target machine. If you don't define
-this, and you probably shouldn't, the default is @code{CHAR_TYPE_SIZE}.
-@end defmac
-
-@defmac FLOAT_TYPE_SIZE
-A C expression for the size in bits of the type @code{float} on the
-target machine. If you don't define this, the default is one word.
-@end defmac
-
-@defmac DOUBLE_TYPE_SIZE
-A C expression for the size in bits of the type @code{double} on the
-target machine. If you don't define this, the default is two
-words.
-@end defmac
-
-@defmac LONG_DOUBLE_TYPE_SIZE
-A C expression for the size in bits of the type @code{long double} on
-the target machine. If you don't define this, the default is two
-words.
-@end defmac
-
-@defmac SHORT_FRACT_TYPE_SIZE
-A C expression for the size in bits of the type @code{short _Fract} on
-the target machine. If you don't define this, the default is
-@code{BITS_PER_UNIT}.
-@end defmac
-
-@defmac FRACT_TYPE_SIZE
-A C expression for the size in bits of the type @code{_Fract} on
-the target machine. If you don't define this, the default is
-@code{BITS_PER_UNIT * 2}.
-@end defmac
-
-@defmac LONG_FRACT_TYPE_SIZE
-A C expression for the size in bits of the type @code{long _Fract} on
-the target machine. If you don't define this, the default is
-@code{BITS_PER_UNIT * 4}.
-@end defmac
-
-@defmac LONG_LONG_FRACT_TYPE_SIZE
-A C expression for the size in bits of the type @code{long long _Fract} on
-the target machine. If you don't define this, the default is
-@code{BITS_PER_UNIT * 8}.
-@end defmac
-
-@defmac SHORT_ACCUM_TYPE_SIZE
-A C expression for the size in bits of the type @code{short _Accum} on
-the target machine. If you don't define this, the default is
-@code{BITS_PER_UNIT * 2}.
-@end defmac
-
-@defmac ACCUM_TYPE_SIZE
-A C expression for the size in bits of the type @code{_Accum} on
-the target machine. If you don't define this, the default is
-@code{BITS_PER_UNIT * 4}.
-@end defmac
-
-@defmac LONG_ACCUM_TYPE_SIZE
-A C expression for the size in bits of the type @code{long _Accum} on
-the target machine. If you don't define this, the default is
-@code{BITS_PER_UNIT * 8}.
-@end defmac
-
-@defmac LONG_LONG_ACCUM_TYPE_SIZE
-A C expression for the size in bits of the type @code{long long _Accum} on
-the target machine. If you don't define this, the default is
-@code{BITS_PER_UNIT * 16}.
-@end defmac
-
-@defmac LIBGCC2_GNU_PREFIX
-This macro corresponds to the @code{TARGET_LIBFUNC_GNU_PREFIX} target
-hook and should be defined if that hook is overriden to be true. It
-causes function names in libgcc to be changed to use a @code{__gnu_}
-prefix for their name rather than the default @code{__}. A port which
-uses this macro should also arrange to use @file{t-gnu-prefix} in
-the libgcc @file{config.host}.
-@end defmac
-
-@defmac WIDEST_HARDWARE_FP_SIZE
-A C expression for the size in bits of the widest floating-point format
-supported by the hardware. If you define this macro, you must specify a
-value less than or equal to the value of @code{LONG_DOUBLE_TYPE_SIZE}.
-If you do not define this macro, the value of @code{LONG_DOUBLE_TYPE_SIZE}
-is the default.
-@end defmac
-
-@defmac DEFAULT_SIGNED_CHAR
-An expression whose value is 1 or 0, according to whether the type
-@code{char} should be signed or unsigned by default. The user can
-always override this default with the options @option{-fsigned-char}
-and @option{-funsigned-char}.
-@end defmac
-
-@hook TARGET_DEFAULT_SHORT_ENUMS
-
-@defmac SIZE_TYPE
-A C expression for a string describing the name of the data type to use
-for size values. The typedef name @code{size_t} is defined using the
-contents of the string.
-
-The string can contain more than one keyword. If so, separate them with
-spaces, and write first any length keyword, then @code{unsigned} if
-appropriate, and finally @code{int}. The string must exactly match one
-of the data type names defined in the function
-@code{c_common_nodes_and_builtins} in the file @file{c-family/c-common.cc}.
-You may not omit @code{int} or change the order---that would cause the
-compiler to crash on startup.
-
-If you don't define this macro, the default is @code{"long unsigned
-int"}.
-@end defmac
-
-@defmac SIZETYPE
-GCC defines internal types (@code{sizetype}, @code{ssizetype},
-@code{bitsizetype} and @code{sbitsizetype}) for expressions
-dealing with size. This macro is a C expression for a string describing
-the name of the data type from which the precision of @code{sizetype}
-is extracted.
-
-The string has the same restrictions as @code{SIZE_TYPE} string.
-
-If you don't define this macro, the default is @code{SIZE_TYPE}.
-@end defmac
-
-@defmac PTRDIFF_TYPE
-A C expression for a string describing the name of the data type to use
-for the result of subtracting two pointers. The typedef name
-@code{ptrdiff_t} is defined using the contents of the string. See
-@code{SIZE_TYPE} above for more information.
-
-If you don't define this macro, the default is @code{"long int"}.
-@end defmac
-
-@defmac WCHAR_TYPE
-A C expression for a string describing the name of the data type to use
-for wide characters. The typedef name @code{wchar_t} is defined using
-the contents of the string. See @code{SIZE_TYPE} above for more
-information.
-
-If you don't define this macro, the default is @code{"int"}.
-@end defmac
-
-@defmac WCHAR_TYPE_SIZE
-A C expression for the size in bits of the data type for wide
-characters. This is used in @code{cpp}, which cannot make use of
-@code{WCHAR_TYPE}.
-@end defmac
-
-@defmac WINT_TYPE
-A C expression for a string describing the name of the data type to
-use for wide characters passed to @code{printf} and returned from
-@code{getwc}. The typedef name @code{wint_t} is defined using the
-contents of the string. See @code{SIZE_TYPE} above for more
-information.
-
-If you don't define this macro, the default is @code{"unsigned int"}.
-@end defmac
-
-@defmac INTMAX_TYPE
-A C expression for a string describing the name of the data type that
-can represent any value of any standard or extended signed integer type.
-The typedef name @code{intmax_t} is defined using the contents of the
-string. See @code{SIZE_TYPE} above for more information.
-
-If you don't define this macro, the default is the first of
-@code{"int"}, @code{"long int"}, or @code{"long long int"} that has as
-much precision as @code{long long int}.
-@end defmac
-
-@defmac UINTMAX_TYPE
-A C expression for a string describing the name of the data type that
-can represent any value of any standard or extended unsigned integer
-type. The typedef name @code{uintmax_t} is defined using the contents
-of the string. See @code{SIZE_TYPE} above for more information.
-
-If you don't define this macro, the default is the first of
-@code{"unsigned int"}, @code{"long unsigned int"}, or @code{"long long
-unsigned int"} that has as much precision as @code{long long unsigned
-int}.
-@end defmac
-
-@defmac SIG_ATOMIC_TYPE
-@defmacx INT8_TYPE
-@defmacx INT16_TYPE
-@defmacx INT32_TYPE
-@defmacx INT64_TYPE
-@defmacx UINT8_TYPE
-@defmacx UINT16_TYPE
-@defmacx UINT32_TYPE
-@defmacx UINT64_TYPE
-@defmacx INT_LEAST8_TYPE
-@defmacx INT_LEAST16_TYPE
-@defmacx INT_LEAST32_TYPE
-@defmacx INT_LEAST64_TYPE
-@defmacx UINT_LEAST8_TYPE
-@defmacx UINT_LEAST16_TYPE
-@defmacx UINT_LEAST32_TYPE
-@defmacx UINT_LEAST64_TYPE
-@defmacx INT_FAST8_TYPE
-@defmacx INT_FAST16_TYPE
-@defmacx INT_FAST32_TYPE
-@defmacx INT_FAST64_TYPE
-@defmacx UINT_FAST8_TYPE
-@defmacx UINT_FAST16_TYPE
-@defmacx UINT_FAST32_TYPE
-@defmacx UINT_FAST64_TYPE
-@defmacx INTPTR_TYPE
-@defmacx UINTPTR_TYPE
-C expressions for the standard types @code{sig_atomic_t},
-@code{int8_t}, @code{int16_t}, @code{int32_t}, @code{int64_t},
-@code{uint8_t}, @code{uint16_t}, @code{uint32_t}, @code{uint64_t},
-@code{int_least8_t}, @code{int_least16_t}, @code{int_least32_t},
-@code{int_least64_t}, @code{uint_least8_t}, @code{uint_least16_t},
-@code{uint_least32_t}, @code{uint_least64_t}, @code{int_fast8_t},
-@code{int_fast16_t}, @code{int_fast32_t}, @code{int_fast64_t},
-@code{uint_fast8_t}, @code{uint_fast16_t}, @code{uint_fast32_t},
-@code{uint_fast64_t}, @code{intptr_t}, and @code{uintptr_t}. See
-@code{SIZE_TYPE} above for more information.
-
-If any of these macros evaluates to a null pointer, the corresponding
-type is not supported; if GCC is configured to provide
-@code{<stdint.h>} in such a case, the header provided may not conform
-to C99, depending on the type in question. The defaults for all of
-these macros are null pointers.
-@end defmac
-
-@defmac TARGET_PTRMEMFUNC_VBIT_LOCATION
-The C++ compiler represents a pointer-to-member-function with a struct
-that looks like:
-
-@smallexample
- struct @{
- union @{
- void (*fn)();
- ptrdiff_t vtable_index;
- @};
- ptrdiff_t delta;
- @};
-@end smallexample
-
-@noindent
-The C++ compiler must use one bit to indicate whether the function that
-will be called through a pointer-to-member-function is virtual.
-Normally, we assume that the low-order bit of a function pointer must
-always be zero. Then, by ensuring that the vtable_index is odd, we can
-distinguish which variant of the union is in use. But, on some
-platforms function pointers can be odd, and so this doesn't work. In
-that case, we use the low-order bit of the @code{delta} field, and shift
-the remainder of the @code{delta} field to the left.
-
-GCC will automatically make the right selection about where to store
-this bit using the @code{FUNCTION_BOUNDARY} setting for your platform.
-However, some platforms such as ARM/Thumb have @code{FUNCTION_BOUNDARY}
-set such that functions always start at even addresses, but the lowest
-bit of pointers to functions indicate whether the function at that
-address is in ARM or Thumb mode. If this is the case of your
-architecture, you should define this macro to
-@code{ptrmemfunc_vbit_in_delta}.
-
-In general, you should not have to define this macro. On architectures
-in which function addresses are always even, according to
-@code{FUNCTION_BOUNDARY}, GCC will automatically define this macro to
-@code{ptrmemfunc_vbit_in_pfn}.
-@end defmac
-
-@defmac TARGET_VTABLE_USES_DESCRIPTORS
-Normally, the C++ compiler uses function pointers in vtables. This
-macro allows the target to change to use ``function descriptors''
-instead. Function descriptors are found on targets for whom a
-function pointer is actually a small data structure. Normally the
-data structure consists of the actual code address plus a data
-pointer to which the function's data is relative.
-
-If vtables are used, the value of this macro should be the number
-of words that the function descriptor occupies.
-@end defmac
-
-@defmac TARGET_VTABLE_ENTRY_ALIGN
-By default, the vtable entries are void pointers, the so the alignment
-is the same as pointer alignment. The value of this macro specifies
-the alignment of the vtable entry in bits. It should be defined only
-when special alignment is necessary. */
-@end defmac
-
-@defmac TARGET_VTABLE_DATA_ENTRY_DISTANCE
-There are a few non-descriptor entries in the vtable at offsets below
-zero. If these entries must be padded (say, to preserve the alignment
-specified by @code{TARGET_VTABLE_ENTRY_ALIGN}), set this to the number
-of words in each data entry.
-@end defmac
-
-@node Registers
-@section Register Usage
-@cindex register usage
-
-This section explains how to describe what registers the target machine
-has, and how (in general) they can be used.
-
-The description of which registers a specific instruction can use is
-done with register classes; see @ref{Register Classes}. For information
-on using registers to access a stack frame, see @ref{Frame Registers}.
-For passing values in registers, see @ref{Register Arguments}.
-For returning values in registers, see @ref{Scalar Return}.
-
-@menu
-* Register Basics:: Number and kinds of registers.
-* Allocation Order:: Order in which registers are allocated.
-* Values in Registers:: What kinds of values each reg can hold.
-* Leaf Functions:: Renumbering registers for leaf functions.
-* Stack Registers:: Handling a register stack such as 80387.
-@end menu
-
-@node Register Basics
-@subsection Basic Characteristics of Registers
-
-@c prevent bad page break with this line
-Registers have various characteristics.
-
-@defmac FIRST_PSEUDO_REGISTER
-Number of hardware registers known to the compiler. They receive
-numbers 0 through @code{FIRST_PSEUDO_REGISTER-1}; thus, the first
-pseudo register's number really is assigned the number
-@code{FIRST_PSEUDO_REGISTER}.
-@end defmac
-
-@defmac FIXED_REGISTERS
-@cindex fixed register
-An initializer that says which registers are used for fixed purposes
-all throughout the compiled code and are therefore not available for
-general allocation. These would include the stack pointer, the frame
-pointer (except on machines where that can be used as a general
-register when no frame pointer is needed), the program counter on
-machines where that is considered one of the addressable registers,
-and any other numbered register with a standard use.
-
-This information is expressed as a sequence of numbers, separated by
-commas and surrounded by braces. The @var{n}th number is 1 if
-register @var{n} is fixed, 0 otherwise.
-
-The table initialized from this macro, and the table initialized by
-the following one, may be overridden at run time either automatically,
-by the actions of the macro @code{CONDITIONAL_REGISTER_USAGE}, or by
-the user with the command options @option{-ffixed-@var{reg}},
-@option{-fcall-used-@var{reg}} and @option{-fcall-saved-@var{reg}}.
-@end defmac
-
-@defmac CALL_USED_REGISTERS
-@cindex call-used register
-@cindex call-clobbered register
-@cindex call-saved register
-Like @code{FIXED_REGISTERS} but has 1 for each register that is
-clobbered (in general) by function calls as well as for fixed
-registers. This macro therefore identifies the registers that are not
-available for general allocation of values that must live across
-function calls.
-
-If a register has 0 in @code{CALL_USED_REGISTERS}, the compiler
-automatically saves it on function entry and restores it on function
-exit, if the register is used within the function.
-
-Exactly one of @code{CALL_USED_REGISTERS} and @code{CALL_REALLY_USED_REGISTERS}
-must be defined. Modern ports should define @code{CALL_REALLY_USED_REGISTERS}.
-@end defmac
-
-@defmac CALL_REALLY_USED_REGISTERS
-@cindex call-used register
-@cindex call-clobbered register
-@cindex call-saved register
-Like @code{CALL_USED_REGISTERS} except this macro doesn't require
-that the entire set of @code{FIXED_REGISTERS} be included.
-(@code{CALL_USED_REGISTERS} must be a superset of @code{FIXED_REGISTERS}).
-
-Exactly one of @code{CALL_USED_REGISTERS} and @code{CALL_REALLY_USED_REGISTERS}
-must be defined. Modern ports should define @code{CALL_REALLY_USED_REGISTERS}.
-@end defmac
-
-@cindex call-used register
-@cindex call-clobbered register
-@cindex call-saved register
-@hook TARGET_FNTYPE_ABI
-
-@hook TARGET_INSN_CALLEE_ABI
-
-@cindex call-used register
-@cindex call-clobbered register
-@cindex call-saved register
-@hook TARGET_HARD_REGNO_CALL_PART_CLOBBERED
-
-@hook TARGET_GET_MULTILIB_ABI_NAME
-
-@findex fixed_regs
-@findex call_used_regs
-@findex global_regs
-@findex reg_names
-@findex reg_class_contents
-@hook TARGET_CONDITIONAL_REGISTER_USAGE
-
-@defmac INCOMING_REGNO (@var{out})
-Define this macro if the target machine has register windows. This C
-expression returns the register number as seen by the called function
-corresponding to the register number @var{out} as seen by the calling
-function. Return @var{out} if register number @var{out} is not an
-outbound register.
-@end defmac
-
-@defmac OUTGOING_REGNO (@var{in})
-Define this macro if the target machine has register windows. This C
-expression returns the register number as seen by the calling function
-corresponding to the register number @var{in} as seen by the called
-function. Return @var{in} if register number @var{in} is not an inbound
-register.
-@end defmac
-
-@defmac LOCAL_REGNO (@var{regno})
-Define this macro if the target machine has register windows. This C
-expression returns true if the register is call-saved but is in the
-register window. Unlike most call-saved registers, such registers
-need not be explicitly restored on function exit or during non-local
-gotos.
-@end defmac
-
-@defmac PC_REGNUM
-If the program counter has a register number, define this as that
-register number. Otherwise, do not define it.
-@end defmac
-
-@node Allocation Order
-@subsection Order of Allocation of Registers
-@cindex order of register allocation
-@cindex register allocation order
-
-@c prevent bad page break with this line
-Registers are allocated in order.
-
-@defmac REG_ALLOC_ORDER
-If defined, an initializer for a vector of integers, containing the
-numbers of hard registers in the order in which GCC should prefer
-to use them (from most preferred to least).
-
-If this macro is not defined, registers are used lowest numbered first
-(all else being equal).
-
-One use of this macro is on machines where the highest numbered
-registers must always be saved and the save-multiple-registers
-instruction supports only sequences of consecutive registers. On such
-machines, define @code{REG_ALLOC_ORDER} to be an initializer that lists
-the highest numbered allocable register first.
-@end defmac
-
-@defmac ADJUST_REG_ALLOC_ORDER
-A C statement (sans semicolon) to choose the order in which to allocate
-hard registers for pseudo-registers local to a basic block.
-
-Store the desired register order in the array @code{reg_alloc_order}.
-Element 0 should be the register to allocate first; element 1, the next
-register; and so on.
-
-The macro body should not assume anything about the contents of
-@code{reg_alloc_order} before execution of the macro.
-
-On most machines, it is not necessary to define this macro.
-@end defmac
-
-@defmac HONOR_REG_ALLOC_ORDER
-Normally, IRA tries to estimate the costs for saving a register in the
-prologue and restoring it in the epilogue. This discourages it from
-using call-saved registers. If a machine wants to ensure that IRA
-allocates registers in the order given by REG_ALLOC_ORDER even if some
-call-saved registers appear earlier than call-used ones, then define this
-macro as a C expression to nonzero. Default is 0.
-@end defmac
-
-@defmac IRA_HARD_REGNO_ADD_COST_MULTIPLIER (@var{regno})
-In some case register allocation order is not enough for the
-Integrated Register Allocator (@acronym{IRA}) to generate a good code.
-If this macro is defined, it should return a floating point value
-based on @var{regno}. The cost of using @var{regno} for a pseudo will
-be increased by approximately the pseudo's usage frequency times the
-value returned by this macro. Not defining this macro is equivalent
-to having it always return @code{0.0}.
-
-On most machines, it is not necessary to define this macro.
-@end defmac
-
-@node Values in Registers
-@subsection How Values Fit in Registers
-
-This section discusses the macros that describe which kinds of values
-(specifically, which machine modes) each register can hold, and how many
-consecutive registers are needed for a given mode.
-
-@hook TARGET_HARD_REGNO_NREGS
-
-@defmac HARD_REGNO_NREGS_HAS_PADDING (@var{regno}, @var{mode})
-A C expression that is nonzero if a value of mode @var{mode}, stored
-in memory, ends with padding that causes it to take up more space than
-in registers starting at register number @var{regno} (as determined by
-multiplying GCC's notion of the size of the register when containing
-this mode by the number of registers returned by
-@code{TARGET_HARD_REGNO_NREGS}). By default this is zero.
-
-For example, if a floating-point value is stored in three 32-bit
-registers but takes up 128 bits in memory, then this would be
-nonzero.
-
-This macros only needs to be defined if there are cases where
-@code{subreg_get_info}
-would otherwise wrongly determine that a @code{subreg} can be
-represented by an offset to the register number, when in fact such a
-@code{subreg} would contain some of the padding not stored in
-registers and so not be representable.
-@end defmac
-
-@defmac HARD_REGNO_NREGS_WITH_PADDING (@var{regno}, @var{mode})
-For values of @var{regno} and @var{mode} for which
-@code{HARD_REGNO_NREGS_HAS_PADDING} returns nonzero, a C expression
-returning the greater number of registers required to hold the value
-including any padding. In the example above, the value would be four.
-@end defmac
-
-@defmac REGMODE_NATURAL_SIZE (@var{mode})
-Define this macro if the natural size of registers that hold values
-of mode @var{mode} is not the word size. It is a C expression that
-should give the natural size in bytes for the specified mode. It is
-used by the register allocator to try to optimize its results. This
-happens for example on SPARC 64-bit where the natural size of
-floating-point registers is still 32-bit.
-@end defmac
-
-@hook TARGET_HARD_REGNO_MODE_OK
-
-@defmac HARD_REGNO_RENAME_OK (@var{from}, @var{to})
-A C expression that is nonzero if it is OK to rename a hard register
-@var{from} to another hard register @var{to}.
-
-One common use of this macro is to prevent renaming of a register to
-another register that is not saved by a prologue in an interrupt
-handler.
-
-The default is always nonzero.
-@end defmac
-
-@hook TARGET_MODES_TIEABLE_P
-
-@hook TARGET_HARD_REGNO_SCRATCH_OK
-
-@defmac AVOID_CCMODE_COPIES
-Define this macro if the compiler should avoid copies to/from @code{CCmode}
-registers. You should only define this macro if support for copying to/from
-@code{CCmode} is incomplete.
-@end defmac
-
-@node Leaf Functions
-@subsection Handling Leaf Functions
-
-@cindex leaf functions
-@cindex functions, leaf
-On some machines, a leaf function (i.e., one which makes no calls) can run
-more efficiently if it does not make its own register window. Often this
-means it is required to receive its arguments in the registers where they
-are passed by the caller, instead of the registers where they would
-normally arrive.
-
-The special treatment for leaf functions generally applies only when
-other conditions are met; for example, often they may use only those
-registers for its own variables and temporaries. We use the term ``leaf
-function'' to mean a function that is suitable for this special
-handling, so that functions with no calls are not necessarily ``leaf
-functions''.
-
-GCC assigns register numbers before it knows whether the function is
-suitable for leaf function treatment. So it needs to renumber the
-registers in order to output a leaf function. The following macros
-accomplish this.
-
-@defmac LEAF_REGISTERS
-Name of a char vector, indexed by hard register number, which
-contains 1 for a register that is allowable in a candidate for leaf
-function treatment.
-
-If leaf function treatment involves renumbering the registers, then the
-registers marked here should be the ones before renumbering---those that
-GCC would ordinarily allocate. The registers which will actually be
-used in the assembler code, after renumbering, should not be marked with 1
-in this vector.
-
-Define this macro only if the target machine offers a way to optimize
-the treatment of leaf functions.
-@end defmac
-
-@defmac LEAF_REG_REMAP (@var{regno})
-A C expression whose value is the register number to which @var{regno}
-should be renumbered, when a function is treated as a leaf function.
-
-If @var{regno} is a register number which should not appear in a leaf
-function before renumbering, then the expression should yield @minus{}1, which
-will cause the compiler to abort.
-
-Define this macro only if the target machine offers a way to optimize the
-treatment of leaf functions, and registers need to be renumbered to do
-this.
-@end defmac
-
-@findex current_function_is_leaf
-@findex current_function_uses_only_leaf_regs
-@code{TARGET_ASM_FUNCTION_PROLOGUE} and
-@code{TARGET_ASM_FUNCTION_EPILOGUE} must usually treat leaf functions
-specially. They can test the C variable @code{current_function_is_leaf}
-which is nonzero for leaf functions. @code{current_function_is_leaf} is
-set prior to local register allocation and is valid for the remaining
-compiler passes. They can also test the C variable
-@code{current_function_uses_only_leaf_regs} which is nonzero for leaf
-functions which only use leaf registers.
-@code{current_function_uses_only_leaf_regs} is valid after all passes
-that modify the instructions have been run and is only useful if
-@code{LEAF_REGISTERS} is defined.
-@c changed this to fix overfull. ALSO: why the "it" at the beginning
-@c of the next paragraph?! --mew 2feb93
-
-@node Stack Registers
-@subsection Registers That Form a Stack
-
-There are special features to handle computers where some of the
-``registers'' form a stack. Stack registers are normally written by
-pushing onto the stack, and are numbered relative to the top of the
-stack.
-
-Currently, GCC can only handle one group of stack-like registers, and
-they must be consecutively numbered. Furthermore, the existing
-support for stack-like registers is specific to the 80387 floating
-point coprocessor. If you have a new architecture that uses
-stack-like registers, you will need to do substantial work on
-@file{reg-stack.cc} and write your machine description to cooperate
-with it, as well as defining these macros.
-
-@defmac STACK_REGS
-Define this if the machine has any stack-like registers.
-@end defmac
-
-@defmac STACK_REG_COVER_CLASS
-This is a cover class containing the stack registers. Define this if
-the machine has any stack-like registers.
-@end defmac
-
-@defmac FIRST_STACK_REG
-The number of the first stack-like register. This one is the top
-of the stack.
-@end defmac
-
-@defmac LAST_STACK_REG
-The number of the last stack-like register. This one is the bottom of
-the stack.
-@end defmac
-
-@node Register Classes
-@section Register Classes
-@cindex register class definitions
-@cindex class definitions, register
-
-On many machines, the numbered registers are not all equivalent.
-For example, certain registers may not be allowed for indexed addressing;
-certain registers may not be allowed in some instructions. These machine
-restrictions are described to the compiler using @dfn{register classes}.
-
-You define a number of register classes, giving each one a name and saying
-which of the registers belong to it. Then you can specify register classes
-that are allowed as operands to particular instruction patterns.
-
-@findex ALL_REGS
-@findex NO_REGS
-In general, each register will belong to several classes. In fact, one
-class must be named @code{ALL_REGS} and contain all the registers. Another
-class must be named @code{NO_REGS} and contain no registers. Often the
-union of two classes will be another class; however, this is not required.
-
-@findex GENERAL_REGS
-One of the classes must be named @code{GENERAL_REGS}. There is nothing
-terribly special about the name, but the operand constraint letters
-@samp{r} and @samp{g} specify this class. If @code{GENERAL_REGS} is
-the same as @code{ALL_REGS}, just define it as a macro which expands
-to @code{ALL_REGS}.
-
-Order the classes so that if class @var{x} is contained in class @var{y}
-then @var{x} has a lower class number than @var{y}.
-
-The way classes other than @code{GENERAL_REGS} are specified in operand
-constraints is through machine-dependent operand constraint letters.
-You can define such letters to correspond to various classes, then use
-them in operand constraints.
-
-You must define the narrowest register classes for allocatable
-registers, so that each class either has no subclasses, or that for
-some mode, the move cost between registers within the class is
-cheaper than moving a register in the class to or from memory
-(@pxref{Costs}).
-
-You should define a class for the union of two classes whenever some
-instruction allows both classes. For example, if an instruction allows
-either a floating point (coprocessor) register or a general register for a
-certain operand, you should define a class @code{FLOAT_OR_GENERAL_REGS}
-which includes both of them. Otherwise you will get suboptimal code,
-or even internal compiler errors when reload cannot find a register in the
-class computed via @code{reg_class_subunion}.
-
-You must also specify certain redundant information about the register
-classes: for each class, which classes contain it and which ones are
-contained in it; for each pair of classes, the largest class contained
-in their union.
-
-When a value occupying several consecutive registers is expected in a
-certain class, all the registers used must belong to that class.
-Therefore, register classes cannot be used to enforce a requirement for
-a register pair to start with an even-numbered register. The way to
-specify this requirement is with @code{TARGET_HARD_REGNO_MODE_OK}.
-
-Register classes used for input-operands of bitwise-and or shift
-instructions have a special requirement: each such class must have, for
-each fixed-point machine mode, a subclass whose registers can transfer that
-mode to or from memory. For example, on some machines, the operations for
-single-byte values (@code{QImode}) are limited to certain registers. When
-this is so, each register class that is used in a bitwise-and or shift
-instruction must have a subclass consisting of registers from which
-single-byte values can be loaded or stored. This is so that
-@code{PREFERRED_RELOAD_CLASS} can always have a possible value to return.
-
-@deftp {Data type} {enum reg_class}
-An enumerated type that must be defined with all the register class names
-as enumerated values. @code{NO_REGS} must be first. @code{ALL_REGS}
-must be the last register class, followed by one more enumerated value,
-@code{LIM_REG_CLASSES}, which is not a register class but rather
-tells how many classes there are.
-
-Each register class has a number, which is the value of casting
-the class name to type @code{int}. The number serves as an index
-in many of the tables described below.
-@end deftp
-
-@defmac N_REG_CLASSES
-The number of distinct register classes, defined as follows:
-
-@smallexample
-#define N_REG_CLASSES (int) LIM_REG_CLASSES
-@end smallexample
-@end defmac
-
-@defmac REG_CLASS_NAMES
-An initializer containing the names of the register classes as C string
-constants. These names are used in writing some of the debugging dumps.
-@end defmac
-
-@defmac REG_CLASS_CONTENTS
-An initializer containing the contents of the register classes, as integers
-which are bit masks. The @var{n}th integer specifies the contents of class
-@var{n}. The way the integer @var{mask} is interpreted is that
-register @var{r} is in the class if @code{@var{mask} & (1 << @var{r})} is 1.
-
-When the machine has more than 32 registers, an integer does not suffice.
-Then the integers are replaced by sub-initializers, braced groupings containing
-several integers. Each sub-initializer must be suitable as an initializer
-for the type @code{HARD_REG_SET} which is defined in @file{hard-reg-set.h}.
-In this situation, the first integer in each sub-initializer corresponds to
-registers 0 through 31, the second integer to registers 32 through 63, and
-so on.
-@end defmac
-
-@defmac REGNO_REG_CLASS (@var{regno})
-A C expression whose value is a register class containing hard register
-@var{regno}. In general there is more than one such class; choose a class
-which is @dfn{minimal}, meaning that no smaller class also contains the
-register.
-@end defmac
-
-@defmac BASE_REG_CLASS
-A macro whose definition is the name of the class to which a valid
-base register must belong. A base register is one used in an address
-which is the register value plus a displacement.
-@end defmac
-
-@defmac MODE_BASE_REG_CLASS (@var{mode})
-This is a variation of the @code{BASE_REG_CLASS} macro which allows
-the selection of a base register in a mode dependent manner. If
-@var{mode} is VOIDmode then it should return the same value as
-@code{BASE_REG_CLASS}.
-@end defmac
-
-@defmac MODE_BASE_REG_REG_CLASS (@var{mode})
-A C expression whose value is the register class to which a valid
-base register must belong in order to be used in a base plus index
-register address. You should define this macro if base plus index
-addresses have different requirements than other base register uses.
-@end defmac
-
-@defmac MODE_CODE_BASE_REG_CLASS (@var{mode}, @var{address_space}, @var{outer_code}, @var{index_code})
-A C expression whose value is the register class to which a valid
-base register for a memory reference in mode @var{mode} to address
-space @var{address_space} must belong. @var{outer_code} and @var{index_code}
-define the context in which the base register occurs. @var{outer_code} is
-the code of the immediately enclosing expression (@code{MEM} for the top level
-of an address, @code{ADDRESS} for something that occurs in an
-@code{address_operand}). @var{index_code} is the code of the corresponding
-index expression if @var{outer_code} is @code{PLUS}; @code{SCRATCH} otherwise.
-@end defmac
-
-@defmac INDEX_REG_CLASS
-A macro whose definition is the name of the class to which a valid
-index register must belong. An index register is one used in an
-address where its value is either multiplied by a scale factor or
-added to another register (as well as added to a displacement).
-@end defmac
-
-@defmac REGNO_OK_FOR_BASE_P (@var{num})
-A C expression which is nonzero if register number @var{num} is
-suitable for use as a base register in operand addresses.
-@end defmac
-
-@defmac REGNO_MODE_OK_FOR_BASE_P (@var{num}, @var{mode})
-A C expression that is just like @code{REGNO_OK_FOR_BASE_P}, except that
-that expression may examine the mode of the memory reference in
-@var{mode}. You should define this macro if the mode of the memory
-reference affects whether a register may be used as a base register. If
-you define this macro, the compiler will use it instead of
-@code{REGNO_OK_FOR_BASE_P}. The mode may be @code{VOIDmode} for
-addresses that appear outside a @code{MEM}, i.e., as an
-@code{address_operand}.
-@end defmac
-
-@defmac REGNO_MODE_OK_FOR_REG_BASE_P (@var{num}, @var{mode})
-A C expression which is nonzero if register number @var{num} is suitable for
-use as a base register in base plus index operand addresses, accessing
-memory in mode @var{mode}. It may be either a suitable hard register or a
-pseudo register that has been allocated such a hard register. You should
-define this macro if base plus index addresses have different requirements
-than other base register uses.
-
-Use of this macro is deprecated; please use the more general
-@code{REGNO_MODE_CODE_OK_FOR_BASE_P}.
-@end defmac
-
-@defmac REGNO_MODE_CODE_OK_FOR_BASE_P (@var{num}, @var{mode}, @var{address_space}, @var{outer_code}, @var{index_code})
-A C expression which is nonzero if register number @var{num} is
-suitable for use as a base register in operand addresses, accessing
-memory in mode @var{mode} in address space @var{address_space}.
-This is similar to @code{REGNO_MODE_OK_FOR_BASE_P}, except
-that that expression may examine the context in which the register
-appears in the memory reference. @var{outer_code} is the code of the
-immediately enclosing expression (@code{MEM} if at the top level of the
-address, @code{ADDRESS} for something that occurs in an
-@code{address_operand}). @var{index_code} is the code of the
-corresponding index expression if @var{outer_code} is @code{PLUS};
-@code{SCRATCH} otherwise. The mode may be @code{VOIDmode} for addresses
-that appear outside a @code{MEM}, i.e., as an @code{address_operand}.
-@end defmac
-
-@defmac REGNO_OK_FOR_INDEX_P (@var{num})
-A C expression which is nonzero if register number @var{num} is
-suitable for use as an index register in operand addresses. It may be
-either a suitable hard register or a pseudo register that has been
-allocated such a hard register.
-
-The difference between an index register and a base register is that
-the index register may be scaled. If an address involves the sum of
-two registers, neither one of them scaled, then either one may be
-labeled the ``base'' and the other the ``index''; but whichever
-labeling is used must fit the machine's constraints of which registers
-may serve in each capacity. The compiler will try both labelings,
-looking for one that is valid, and will reload one or both registers
-only if neither labeling works.
-@end defmac
-
-@hook TARGET_PREFERRED_RENAME_CLASS
-
-@hook TARGET_PREFERRED_RELOAD_CLASS
-
-@defmac PREFERRED_RELOAD_CLASS (@var{x}, @var{class})
-A C expression that places additional restrictions on the register class
-to use when it is necessary to copy value @var{x} into a register in class
-@var{class}. The value is a register class; perhaps @var{class}, or perhaps
-another, smaller class. On many machines, the following definition is
-safe:
-
-@smallexample
-#define PREFERRED_RELOAD_CLASS(X,CLASS) CLASS
-@end smallexample
-
-Sometimes returning a more restrictive class makes better code. For
-example, on the 68000, when @var{x} is an integer constant that is in range
-for a @samp{moveq} instruction, the value of this macro is always
-@code{DATA_REGS} as long as @var{class} includes the data registers.
-Requiring a data register guarantees that a @samp{moveq} will be used.
-
-One case where @code{PREFERRED_RELOAD_CLASS} must not return
-@var{class} is if @var{x} is a legitimate constant which cannot be
-loaded into some register class. By returning @code{NO_REGS} you can
-force @var{x} into a memory location. For example, rs6000 can load
-immediate values into general-purpose registers, but does not have an
-instruction for loading an immediate value into a floating-point
-register, so @code{PREFERRED_RELOAD_CLASS} returns @code{NO_REGS} when
-@var{x} is a floating-point constant. If the constant cannot be loaded
-into any kind of register, code generation will be better if
-@code{TARGET_LEGITIMATE_CONSTANT_P} makes the constant illegitimate instead
-of using @code{TARGET_PREFERRED_RELOAD_CLASS}.
-
-If an insn has pseudos in it after register allocation, reload will go
-through the alternatives and call repeatedly @code{PREFERRED_RELOAD_CLASS}
-to find the best one. Returning @code{NO_REGS}, in this case, makes
-reload add a @code{!} in front of the constraint: the x86 back-end uses
-this feature to discourage usage of 387 registers when math is done in
-the SSE registers (and vice versa).
-@end defmac
-
-@hook TARGET_PREFERRED_OUTPUT_RELOAD_CLASS
-
-@defmac LIMIT_RELOAD_CLASS (@var{mode}, @var{class})
-A C expression that places additional restrictions on the register class
-to use when it is necessary to be able to hold a value of mode
-@var{mode} in a reload register for which class @var{class} would
-ordinarily be used.
-
-Unlike @code{PREFERRED_RELOAD_CLASS}, this macro should be used when
-there are certain modes that simply cannot go in certain reload classes.
-
-The value is a register class; perhaps @var{class}, or perhaps another,
-smaller class.
-
-Don't define this macro unless the target machine has limitations which
-require the macro to do something nontrivial.
-@end defmac
-
-@hook TARGET_SECONDARY_RELOAD
-
-@defmac SECONDARY_RELOAD_CLASS (@var{class}, @var{mode}, @var{x})
-@defmacx SECONDARY_INPUT_RELOAD_CLASS (@var{class}, @var{mode}, @var{x})
-@defmacx SECONDARY_OUTPUT_RELOAD_CLASS (@var{class}, @var{mode}, @var{x})
-These macros are obsolete, new ports should use the target hook
-@code{TARGET_SECONDARY_RELOAD} instead.
-
-These are obsolete macros, replaced by the @code{TARGET_SECONDARY_RELOAD}
-target hook. Older ports still define these macros to indicate to the
-reload phase that it may
-need to allocate at least one register for a reload in addition to the
-register to contain the data. Specifically, if copying @var{x} to a
-register @var{class} in @var{mode} requires an intermediate register,
-you were supposed to define @code{SECONDARY_INPUT_RELOAD_CLASS} to return the
-largest register class all of whose registers can be used as
-intermediate registers or scratch registers.
-
-If copying a register @var{class} in @var{mode} to @var{x} requires an
-intermediate or scratch register, @code{SECONDARY_OUTPUT_RELOAD_CLASS}
-was supposed to be defined to return the largest register
-class required. If the
-requirements for input and output reloads were the same, the macro
-@code{SECONDARY_RELOAD_CLASS} should have been used instead of defining both
-macros identically.
-
-The values returned by these macros are often @code{GENERAL_REGS}.
-Return @code{NO_REGS} if no spare register is needed; i.e., if @var{x}
-can be directly copied to or from a register of @var{class} in
-@var{mode} without requiring a scratch register. Do not define this
-macro if it would always return @code{NO_REGS}.
-
-If a scratch register is required (either with or without an
-intermediate register), you were supposed to define patterns for
-@samp{reload_in@var{m}} or @samp{reload_out@var{m}}, as required
-(@pxref{Standard Names}. These patterns, which were normally
-implemented with a @code{define_expand}, should be similar to the
-@samp{mov@var{m}} patterns, except that operand 2 is the scratch
-register.
-
-These patterns need constraints for the reload register and scratch
-register that
-contain a single register class. If the original reload register (whose
-class is @var{class}) can meet the constraint given in the pattern, the
-value returned by these macros is used for the class of the scratch
-register. Otherwise, two additional reload registers are required.
-Their classes are obtained from the constraints in the insn pattern.
-
-@var{x} might be a pseudo-register or a @code{subreg} of a
-pseudo-register, which could either be in a hard register or in memory.
-Use @code{true_regnum} to find out; it will return @minus{}1 if the pseudo is
-in memory and the hard register number if it is in a register.
-
-These macros should not be used in the case where a particular class of
-registers can only be copied to memory and not to another class of
-registers. In that case, secondary reload registers are not needed and
-would not be helpful. Instead, a stack location must be used to perform
-the copy and the @code{mov@var{m}} pattern should use memory as an
-intermediate storage. This case often occurs between floating-point and
-general registers.
-@end defmac
-
-@hook TARGET_SECONDARY_MEMORY_NEEDED
-
-@defmac SECONDARY_MEMORY_NEEDED_RTX (@var{mode})
-Normally when @code{TARGET_SECONDARY_MEMORY_NEEDED} is defined, the compiler
-allocates a stack slot for a memory location needed for register copies.
-If this macro is defined, the compiler instead uses the memory location
-defined by this macro.
-
-Do not define this macro if you do not define
-@code{TARGET_SECONDARY_MEMORY_NEEDED}.
-@end defmac
-
-@hook TARGET_SECONDARY_MEMORY_NEEDED_MODE
-
-@hook TARGET_SELECT_EARLY_REMAT_MODES
-
-@hook TARGET_CLASS_LIKELY_SPILLED_P
-
-@hook TARGET_CLASS_MAX_NREGS
-
-@defmac CLASS_MAX_NREGS (@var{class}, @var{mode})
-A C expression for the maximum number of consecutive registers
-of class @var{class} needed to hold a value of mode @var{mode}.
-
-This is closely related to the macro @code{TARGET_HARD_REGNO_NREGS}. In fact,
-the value of the macro @code{CLASS_MAX_NREGS (@var{class}, @var{mode})}
-should be the maximum value of @code{TARGET_HARD_REGNO_NREGS (@var{regno},
-@var{mode})} for all @var{regno} values in the class @var{class}.
-
-This macro helps control the handling of multiple-word values
-in the reload pass.
-@end defmac
-
-@hook TARGET_CAN_CHANGE_MODE_CLASS
-
-@hook TARGET_IRA_CHANGE_PSEUDO_ALLOCNO_CLASS
-
-@hook TARGET_LRA_P
-
-@hook TARGET_REGISTER_PRIORITY
-
-@hook TARGET_REGISTER_USAGE_LEVELING_P
-
-@hook TARGET_DIFFERENT_ADDR_DISPLACEMENT_P
-
-@hook TARGET_CANNOT_SUBSTITUTE_MEM_EQUIV_P
-
-@hook TARGET_LEGITIMIZE_ADDRESS_DISPLACEMENT
-
-@hook TARGET_SPILL_CLASS
-
-@hook TARGET_ADDITIONAL_ALLOCNO_CLASS_P
-
-@hook TARGET_CSTORE_MODE
-
-@hook TARGET_COMPUTE_PRESSURE_CLASSES
-
-@node Stack and Calling
-@section Stack Layout and Calling Conventions
-@cindex calling conventions
-
-@c prevent bad page break with this line
-This describes the stack layout and calling conventions.
-
-@menu
-* Frame Layout::
-* Exception Handling::
-* Stack Checking::
-* Frame Registers::
-* Elimination::
-* Stack Arguments::
-* Register Arguments::
-* Scalar Return::
-* Aggregate Return::
-* Caller Saves::
-* Function Entry::
-* Profiling::
-* Tail Calls::
-* Shrink-wrapping separate components::
-* Stack Smashing Protection::
-* Miscellaneous Register Hooks::
-@end menu
-
-@node Frame Layout
-@subsection Basic Stack Layout
-@cindex stack frame layout
-@cindex frame layout
-
-@c prevent bad page break with this line
-Here is the basic stack layout.
-
-@defmac STACK_GROWS_DOWNWARD
-Define this macro to be true if pushing a word onto the stack moves the stack
-pointer to a smaller address, and false otherwise.
-@end defmac
-
-@defmac STACK_PUSH_CODE
-This macro defines the operation used when something is pushed
-on the stack. In RTL, a push operation will be
-@code{(set (mem (STACK_PUSH_CODE (reg sp))) @dots{})}
-
-The choices are @code{PRE_DEC}, @code{POST_DEC}, @code{PRE_INC},
-and @code{POST_INC}. Which of these is correct depends on
-the stack direction and on whether the stack pointer points
-to the last item on the stack or whether it points to the
-space for the next item on the stack.
-
-The default is @code{PRE_DEC} when @code{STACK_GROWS_DOWNWARD} is
-true, which is almost always right, and @code{PRE_INC} otherwise,
-which is often wrong.
-@end defmac
-
-@defmac FRAME_GROWS_DOWNWARD
-Define this macro to nonzero value if the addresses of local variable slots
-are at negative offsets from the frame pointer.
-@end defmac
-
-@defmac ARGS_GROW_DOWNWARD
-Define this macro if successive arguments to a function occupy decreasing
-addresses on the stack.
-@end defmac
-
-@hook TARGET_STARTING_FRAME_OFFSET
-
-@defmac STACK_ALIGNMENT_NEEDED
-Define to zero to disable final alignment of the stack during reload.
-The nonzero default for this macro is suitable for most ports.
-
-On ports where @code{TARGET_STARTING_FRAME_OFFSET} is nonzero or where there
-is a register save block following the local block that doesn't require
-alignment to @code{STACK_BOUNDARY}, it may be beneficial to disable
-stack alignment and do it in the backend.
-@end defmac
-
-@defmac STACK_POINTER_OFFSET
-Offset from the stack pointer register to the first location at which
-outgoing arguments are placed. If not specified, the default value of
-zero is used. This is the proper value for most machines.
-
-If @code{ARGS_GROW_DOWNWARD}, this is the offset to the location above
-the first location at which outgoing arguments are placed.
-@end defmac
-
-@defmac FIRST_PARM_OFFSET (@var{fundecl})
-Offset from the argument pointer register to the first argument's
-address. On some machines it may depend on the data type of the
-function.
-
-If @code{ARGS_GROW_DOWNWARD}, this is the offset to the location above
-the first argument's address.
-@end defmac
-
-@defmac STACK_DYNAMIC_OFFSET (@var{fundecl})
-Offset from the stack pointer register to an item dynamically allocated
-on the stack, e.g., by @code{alloca}.
-
-The default value for this macro is @code{STACK_POINTER_OFFSET} plus the
-length of the outgoing arguments. The default is correct for most
-machines. See @file{function.cc} for details.
-@end defmac
-
-@defmac INITIAL_FRAME_ADDRESS_RTX
-A C expression whose value is RTL representing the address of the initial
-stack frame. This address is passed to @code{RETURN_ADDR_RTX} and
-@code{DYNAMIC_CHAIN_ADDRESS}. If you don't define this macro, a reasonable
-default value will be used. Define this macro in order to make frame pointer
-elimination work in the presence of @code{__builtin_frame_address (count)} and
-@code{__builtin_return_address (count)} for @code{count} not equal to zero.
-@end defmac
-
-@defmac DYNAMIC_CHAIN_ADDRESS (@var{frameaddr})
-A C expression whose value is RTL representing the address in a stack
-frame where the pointer to the caller's frame is stored. Assume that
-@var{frameaddr} is an RTL expression for the address of the stack frame
-itself.
-
-If you don't define this macro, the default is to return the value
-of @var{frameaddr}---that is, the stack frame address is also the
-address of the stack word that points to the previous frame.
-@end defmac
-
-@defmac SETUP_FRAME_ADDRESSES
-A C expression that produces the machine-specific code to
-setup the stack so that arbitrary frames can be accessed. For example,
-on the SPARC, we must flush all of the register windows to the stack
-before we can access arbitrary stack frames. You will seldom need to
-define this macro. The default is to do nothing.
-@end defmac
-
-@hook TARGET_BUILTIN_SETJMP_FRAME_VALUE
-
-@defmac FRAME_ADDR_RTX (@var{frameaddr})
-A C expression whose value is RTL representing the value of the frame
-address for the current frame. @var{frameaddr} is the frame pointer
-of the current frame. This is used for __builtin_frame_address.
-You need only define this macro if the frame address is not the same
-as the frame pointer. Most machines do not need to define it.
-@end defmac
-
-@defmac RETURN_ADDR_RTX (@var{count}, @var{frameaddr})
-A C expression whose value is RTL representing the value of the return
-address for the frame @var{count} steps up from the current frame, after
-the prologue. @var{frameaddr} is the frame pointer of the @var{count}
-frame, or the frame pointer of the @var{count} @minus{} 1 frame if
-@code{RETURN_ADDR_IN_PREVIOUS_FRAME} is nonzero.
-
-The value of the expression must always be the correct address when
-@var{count} is zero, but may be @code{NULL_RTX} if there is no way to
-determine the return address of other frames.
-@end defmac
-
-@defmac RETURN_ADDR_IN_PREVIOUS_FRAME
-Define this macro to nonzero value if the return address of a particular
-stack frame is accessed from the frame pointer of the previous stack
-frame. The zero default for this macro is suitable for most ports.
-@end defmac
-
-@defmac INCOMING_RETURN_ADDR_RTX
-A C expression whose value is RTL representing the location of the
-incoming return address at the beginning of any function, before the
-prologue. This RTL is either a @code{REG}, indicating that the return
-value is saved in @samp{REG}, or a @code{MEM} representing a location in
-the stack.
-
-You only need to define this macro if you want to support call frame
-debugging information like that provided by DWARF 2.
-
-If this RTL is a @code{REG}, you should also define
-@code{DWARF_FRAME_RETURN_COLUMN} to @code{DWARF_FRAME_REGNUM (REGNO)}.
-@end defmac
-
-@defmac DWARF_ALT_FRAME_RETURN_COLUMN
-A C expression whose value is an integer giving a DWARF 2 column
-number that may be used as an alternative return column. The column
-must not correspond to any gcc hard register (that is, it must not
-be in the range of @code{DWARF_FRAME_REGNUM}).
-
-This macro can be useful if @code{DWARF_FRAME_RETURN_COLUMN} is set to a
-general register, but an alternative column needs to be used for signal
-frames. Some targets have also used different frame return columns
-over time.
-@end defmac
-
-@defmac DWARF_ZERO_REG
-A C expression whose value is an integer giving a DWARF 2 register
-number that is considered to always have the value zero. This should
-only be defined if the target has an architected zero register, and
-someone decided it was a good idea to use that register number to
-terminate the stack backtrace. New ports should avoid this.
-@end defmac
-
-@defmac DWARF_VERSION_DEFAULT
-A C expression whose value is the default dwarf standard version we'll honor
-and advertise when generating dwarf debug information, in absence of
-an explicit @option{-gdwarf-@var{version}} option on the command line.
-@end defmac
-
-@hook TARGET_DWARF_HANDLE_FRAME_UNSPEC
-
-@hook TARGET_DWARF_POLY_INDETERMINATE_VALUE
-
-@defmac INCOMING_FRAME_SP_OFFSET
-A C expression whose value is an integer giving the offset, in bytes,
-from the value of the stack pointer register to the top of the stack
-frame at the beginning of any function, before the prologue. The top of
-the frame is defined to be the value of the stack pointer in the
-previous frame, just before the call instruction.
-
-You only need to define this macro if you want to support call frame
-debugging information like that provided by DWARF 2.
-@end defmac
-
-@defmac DEFAULT_INCOMING_FRAME_SP_OFFSET
-Like @code{INCOMING_FRAME_SP_OFFSET}, but must be the same for all
-functions of the same ABI, and when using GAS @code{.cfi_*} directives
-must also agree with the default CFI GAS emits. Define this macro
-only if @code{INCOMING_FRAME_SP_OFFSET} can have different values
-between different functions of the same ABI or when
-@code{INCOMING_FRAME_SP_OFFSET} does not agree with GAS default CFI.
-@end defmac
-
-@defmac ARG_POINTER_CFA_OFFSET (@var{fundecl})
-A C expression whose value is an integer giving the offset, in bytes,
-from the argument pointer to the canonical frame address (cfa). The
-final value should coincide with that calculated by
-@code{INCOMING_FRAME_SP_OFFSET}. Which is unfortunately not usable
-during virtual register instantiation.
-
-The default value for this macro is
-@code{FIRST_PARM_OFFSET (fundecl) + crtl->args.pretend_args_size},
-which is correct for most machines; in general, the arguments are found
-immediately before the stack frame. Note that this is not the case on
-some targets that save registers into the caller's frame, such as SPARC
-and rs6000, and so such targets need to define this macro.
-
-You only need to define this macro if the default is incorrect, and you
-want to support call frame debugging information like that provided by
-DWARF 2.
-@end defmac
-
-@defmac FRAME_POINTER_CFA_OFFSET (@var{fundecl})
-If defined, a C expression whose value is an integer giving the offset
-in bytes from the frame pointer to the canonical frame address (cfa).
-The final value should coincide with that calculated by
-@code{INCOMING_FRAME_SP_OFFSET}.
-
-Normally the CFA is calculated as an offset from the argument pointer,
-via @code{ARG_POINTER_CFA_OFFSET}, but if the argument pointer is
-variable due to the ABI, this may not be possible. If this macro is
-defined, it implies that the virtual register instantiation should be
-based on the frame pointer instead of the argument pointer. Only one
-of @code{FRAME_POINTER_CFA_OFFSET} and @code{ARG_POINTER_CFA_OFFSET}
-should be defined.
-@end defmac
-
-@defmac CFA_FRAME_BASE_OFFSET (@var{fundecl})
-If defined, a C expression whose value is an integer giving the offset
-in bytes from the canonical frame address (cfa) to the frame base used
-in DWARF 2 debug information. The default is zero. A different value
-may reduce the size of debug information on some ports.
-@end defmac
-
-@node Exception Handling
-@subsection Exception Handling Support
-@cindex exception handling
-
-@defmac EH_RETURN_DATA_REGNO (@var{N})
-A C expression whose value is the @var{N}th register number used for
-data by exception handlers, or @code{INVALID_REGNUM} if fewer than
-@var{N} registers are usable.
-
-The exception handling library routines communicate with the exception
-handlers via a set of agreed upon registers. Ideally these registers
-should be call-clobbered; it is possible to use call-saved registers,
-but may negatively impact code size. The target must support at least
-2 data registers, but should define 4 if there are enough free registers.
-
-You must define this macro if you want to support call frame exception
-handling like that provided by DWARF 2.
-@end defmac
-
-@defmac EH_RETURN_STACKADJ_RTX
-A C expression whose value is RTL representing a location in which
-to store a stack adjustment to be applied before function return.
-This is used to unwind the stack to an exception handler's call frame.
-It will be assigned zero on code paths that return normally.
-
-Typically this is a call-clobbered hard register that is otherwise
-untouched by the epilogue, but could also be a stack slot.
-
-Do not define this macro if the stack pointer is saved and restored
-by the regular prolog and epilog code in the call frame itself; in
-this case, the exception handling library routines will update the
-stack location to be restored in place. Otherwise, you must define
-this macro if you want to support call frame exception handling like
-that provided by DWARF 2.
-@end defmac
-
-@defmac EH_RETURN_HANDLER_RTX
-A C expression whose value is RTL representing a location in which
-to store the address of an exception handler to which we should
-return. It will not be assigned on code paths that return normally.
-
-Typically this is the location in the call frame at which the normal
-return address is stored. For targets that return by popping an
-address off the stack, this might be a memory address just below
-the @emph{target} call frame rather than inside the current call
-frame. If defined, @code{EH_RETURN_STACKADJ_RTX} will have already
-been assigned, so it may be used to calculate the location of the
-target call frame.
-
-Some targets have more complex requirements than storing to an
-address calculable during initial code generation. In that case
-the @code{eh_return} instruction pattern should be used instead.
-
-If you want to support call frame exception handling, you must
-define either this macro or the @code{eh_return} instruction pattern.
-@end defmac
-
-@defmac RETURN_ADDR_OFFSET
-If defined, an integer-valued C expression for which rtl will be generated
-to add it to the exception handler address before it is searched in the
-exception handling tables, and to subtract it again from the address before
-using it to return to the exception handler.
-@end defmac
-
-@defmac ASM_PREFERRED_EH_DATA_FORMAT (@var{code}, @var{global})
-This macro chooses the encoding of pointers embedded in the exception
-handling sections. If at all possible, this should be defined such
-that the exception handling section will not require dynamic relocations,
-and so may be read-only.
-
-@var{code} is 0 for data, 1 for code labels, 2 for function pointers.
-@var{global} is true if the symbol may be affected by dynamic relocations.
-The macro should return a combination of the @code{DW_EH_PE_*} defines
-as found in @file{dwarf2.h}.
-
-If this macro is not defined, pointers will not be encoded but
-represented directly.
-@end defmac
-
-@defmac ASM_MAYBE_OUTPUT_ENCODED_ADDR_RTX (@var{file}, @var{encoding}, @var{size}, @var{addr}, @var{done})
-This macro allows the target to emit whatever special magic is required
-to represent the encoding chosen by @code{ASM_PREFERRED_EH_DATA_FORMAT}.
-Generic code takes care of pc-relative and indirect encodings; this must
-be defined if the target uses text-relative or data-relative encodings.
-
-This is a C statement that branches to @var{done} if the format was
-handled. @var{encoding} is the format chosen, @var{size} is the number
-of bytes that the format occupies, @var{addr} is the @code{SYMBOL_REF}
-to be emitted.
-@end defmac
-
-@defmac MD_FALLBACK_FRAME_STATE_FOR (@var{context}, @var{fs})
-This macro allows the target to add CPU and operating system specific
-code to the call-frame unwinder for use when there is no unwind data
-available. The most common reason to implement this macro is to unwind
-through signal frames.
-
-This macro is called from @code{uw_frame_state_for} in
-@file{unwind-dw2.c}, @file{unwind-dw2-xtensa.c} and
-@file{unwind-ia64.c}. @var{context} is an @code{_Unwind_Context};
-@var{fs} is an @code{_Unwind_FrameState}. Examine @code{context->ra}
-for the address of the code being executed and @code{context->cfa} for
-the stack pointer value. If the frame can be decoded, the register
-save addresses should be updated in @var{fs} and the macro should
-evaluate to @code{_URC_NO_REASON}. If the frame cannot be decoded,
-the macro should evaluate to @code{_URC_END_OF_STACK}.
-
-For proper signal handling in Java this macro is accompanied by
-@code{MAKE_THROW_FRAME}, defined in @file{libjava/include/*-signal.h} headers.
-@end defmac
-
-@defmac MD_HANDLE_UNWABI (@var{context}, @var{fs})
-This macro allows the target to add operating system specific code to the
-call-frame unwinder to handle the IA-64 @code{.unwabi} unwinding directive,
-usually used for signal or interrupt frames.
-
-This macro is called from @code{uw_update_context} in libgcc's
-@file{unwind-ia64.c}. @var{context} is an @code{_Unwind_Context};
-@var{fs} is an @code{_Unwind_FrameState}. Examine @code{fs->unwabi}
-for the abi and context in the @code{.unwabi} directive. If the
-@code{.unwabi} directive can be handled, the register save addresses should
-be updated in @var{fs}.
-@end defmac
-
-@defmac TARGET_USES_WEAK_UNWIND_INFO
-A C expression that evaluates to true if the target requires unwind
-info to be given comdat linkage. Define it to be @code{1} if comdat
-linkage is necessary. The default is @code{0}.
-@end defmac
-
-@node Stack Checking
-@subsection Specifying How Stack Checking is Done
-
-GCC will check that stack references are within the boundaries of the
-stack, if the option @option{-fstack-check} is specified, in one of
-three ways:
-
-@enumerate
-@item
-If the value of the @code{STACK_CHECK_BUILTIN} macro is nonzero, GCC
-will assume that you have arranged for full stack checking to be done
-at appropriate places in the configuration files. GCC will not do
-other special processing.
-
-@item
-If @code{STACK_CHECK_BUILTIN} is zero and the value of the
-@code{STACK_CHECK_STATIC_BUILTIN} macro is nonzero, GCC will assume
-that you have arranged for static stack checking (checking of the
-static stack frame of functions) to be done at appropriate places
-in the configuration files. GCC will only emit code to do dynamic
-stack checking (checking on dynamic stack allocations) using the third
-approach below.
-
-@item
-If neither of the above are true, GCC will generate code to periodically
-``probe'' the stack pointer using the values of the macros defined below.
-@end enumerate
-
-If neither STACK_CHECK_BUILTIN nor STACK_CHECK_STATIC_BUILTIN is defined,
-GCC will change its allocation strategy for large objects if the option
-@option{-fstack-check} is specified: they will always be allocated
-dynamically if their size exceeds @code{STACK_CHECK_MAX_VAR_SIZE} bytes.
-
-@defmac STACK_CHECK_BUILTIN
-A nonzero value if stack checking is done by the configuration files in a
-machine-dependent manner. You should define this macro if stack checking
-is required by the ABI of your machine or if you would like to do stack
-checking in some more efficient way than the generic approach. The default
-value of this macro is zero.
-@end defmac
-
-@defmac STACK_CHECK_STATIC_BUILTIN
-A nonzero value if static stack checking is done by the configuration files
-in a machine-dependent manner. You should define this macro if you would
-like to do static stack checking in some more efficient way than the generic
-approach. The default value of this macro is zero.
-@end defmac
-
-@defmac STACK_CHECK_PROBE_INTERVAL_EXP
-An integer specifying the interval at which GCC must generate stack probe
-instructions, defined as 2 raised to this integer. You will normally
-define this macro so that the interval be no larger than the size of
-the ``guard pages'' at the end of a stack area. The default value
-of 12 (4096-byte interval) is suitable for most systems.
-@end defmac
-
-@defmac STACK_CHECK_MOVING_SP
-An integer which is nonzero if GCC should move the stack pointer page by page
-when doing probes. This can be necessary on systems where the stack pointer
-contains the bottom address of the memory area accessible to the executing
-thread at any point in time. In this situation an alternate signal stack
-is required in order to be able to recover from a stack overflow. The
-default value of this macro is zero.
-@end defmac
-
-@defmac STACK_CHECK_PROTECT
-The number of bytes of stack needed to recover from a stack overflow, for
-languages where such a recovery is supported. The default value of 4KB/8KB
-with the @code{setjmp}/@code{longjmp}-based exception handling mechanism and
-8KB/12KB with other exception handling mechanisms should be adequate for most
-architectures and operating systems.
-@end defmac
-
-The following macros are relevant only if neither STACK_CHECK_BUILTIN
-nor STACK_CHECK_STATIC_BUILTIN is defined; you can omit them altogether
-in the opposite case.
-
-@defmac STACK_CHECK_MAX_FRAME_SIZE
-The maximum size of a stack frame, in bytes. GCC will generate probe
-instructions in non-leaf functions to ensure at least this many bytes of
-stack are available. If a stack frame is larger than this size, stack
-checking will not be reliable and GCC will issue a warning. The
-default is chosen so that GCC only generates one instruction on most
-systems. You should normally not change the default value of this macro.
-@end defmac
-
-@defmac STACK_CHECK_FIXED_FRAME_SIZE
-GCC uses this value to generate the above warning message. It
-represents the amount of fixed frame used by a function, not including
-space for any callee-saved registers, temporaries and user variables.
-You need only specify an upper bound for this amount and will normally
-use the default of four words.
-@end defmac
-
-@defmac STACK_CHECK_MAX_VAR_SIZE
-The maximum size, in bytes, of an object that GCC will place in the
-fixed area of the stack frame when the user specifies
-@option{-fstack-check}.
-GCC computed the default from the values of the above macros and you will
-normally not need to override that default.
-@end defmac
-
-@hook TARGET_STACK_CLASH_PROTECTION_ALLOCA_PROBE_RANGE
-
-@need 2000
-@node Frame Registers
-@subsection Registers That Address the Stack Frame
-
-@c prevent bad page break with this line
-This discusses registers that address the stack frame.
-
-@defmac STACK_POINTER_REGNUM
-The register number of the stack pointer register, which must also be a
-fixed register according to @code{FIXED_REGISTERS}. On most machines,
-the hardware determines which register this is.
-@end defmac
-
-@defmac FRAME_POINTER_REGNUM
-The register number of the frame pointer register, which is used to
-access automatic variables in the stack frame. On some machines, the
-hardware determines which register this is. On other machines, you can
-choose any register you wish for this purpose.
-@end defmac
-
-@defmac HARD_FRAME_POINTER_REGNUM
-On some machines the offset between the frame pointer and starting
-offset of the automatic variables is not known until after register
-allocation has been done (for example, because the saved registers are
-between these two locations). On those machines, define
-@code{FRAME_POINTER_REGNUM} the number of a special, fixed register to
-be used internally until the offset is known, and define
-@code{HARD_FRAME_POINTER_REGNUM} to be the actual hard register number
-used for the frame pointer.
-
-You should define this macro only in the very rare circumstances when it
-is not possible to calculate the offset between the frame pointer and
-the automatic variables until after register allocation has been
-completed. When this macro is defined, you must also indicate in your
-definition of @code{ELIMINABLE_REGS} how to eliminate
-@code{FRAME_POINTER_REGNUM} into either @code{HARD_FRAME_POINTER_REGNUM}
-or @code{STACK_POINTER_REGNUM}.
-
-Do not define this macro if it would be the same as
-@code{FRAME_POINTER_REGNUM}.
-@end defmac
-
-@defmac ARG_POINTER_REGNUM
-The register number of the arg pointer register, which is used to access
-the function's argument list. On some machines, this is the same as the
-frame pointer register. On some machines, the hardware determines which
-register this is. On other machines, you can choose any register you
-wish for this purpose. If this is not the same register as the frame
-pointer register, then you must mark it as a fixed register according to
-@code{FIXED_REGISTERS}, or arrange to be able to eliminate it
-(@pxref{Elimination}).
-@end defmac
-
-@defmac HARD_FRAME_POINTER_IS_FRAME_POINTER
-Define this to a preprocessor constant that is nonzero if
-@code{hard_frame_pointer_rtx} and @code{frame_pointer_rtx} should be
-the same. The default definition is @samp{(HARD_FRAME_POINTER_REGNUM
-== FRAME_POINTER_REGNUM)}; you only need to define this macro if that
-definition is not suitable for use in preprocessor conditionals.
-@end defmac
-
-@defmac HARD_FRAME_POINTER_IS_ARG_POINTER
-Define this to a preprocessor constant that is nonzero if
-@code{hard_frame_pointer_rtx} and @code{arg_pointer_rtx} should be the
-same. The default definition is @samp{(HARD_FRAME_POINTER_REGNUM ==
-ARG_POINTER_REGNUM)}; you only need to define this macro if that
-definition is not suitable for use in preprocessor conditionals.
-@end defmac
-
-@defmac RETURN_ADDRESS_POINTER_REGNUM
-The register number of the return address pointer register, which is used to
-access the current function's return address from the stack. On some
-machines, the return address is not at a fixed offset from the frame
-pointer or stack pointer or argument pointer. This register can be defined
-to point to the return address on the stack, and then be converted by
-@code{ELIMINABLE_REGS} into either the frame pointer or stack pointer.
-
-Do not define this macro unless there is no other way to get the return
-address from the stack.
-@end defmac
-
-@defmac STATIC_CHAIN_REGNUM
-@defmacx STATIC_CHAIN_INCOMING_REGNUM
-Register numbers used for passing a function's static chain pointer. If
-register windows are used, the register number as seen by the called
-function is @code{STATIC_CHAIN_INCOMING_REGNUM}, while the register
-number as seen by the calling function is @code{STATIC_CHAIN_REGNUM}. If
-these registers are the same, @code{STATIC_CHAIN_INCOMING_REGNUM} need
-not be defined.
-
-The static chain register need not be a fixed register.
-
-If the static chain is passed in memory, these macros should not be
-defined; instead, the @code{TARGET_STATIC_CHAIN} hook should be used.
-@end defmac
-
-@hook TARGET_STATIC_CHAIN
-
-@defmac DWARF_FRAME_REGISTERS
-This macro specifies the maximum number of hard registers that can be
-saved in a call frame. This is used to size data structures used in
-DWARF2 exception handling.
-
-Prior to GCC 3.0, this macro was needed in order to establish a stable
-exception handling ABI in the face of adding new hard registers for ISA
-extensions. In GCC 3.0 and later, the EH ABI is insulated from changes
-in the number of hard registers. Nevertheless, this macro can still be
-used to reduce the runtime memory requirements of the exception handling
-routines, which can be substantial if the ISA contains a lot of
-registers that are not call-saved.
-
-If this macro is not defined, it defaults to
-@code{FIRST_PSEUDO_REGISTER}.
-@end defmac
-
-@defmac PRE_GCC3_DWARF_FRAME_REGISTERS
-
-This macro is similar to @code{DWARF_FRAME_REGISTERS}, but is provided
-for backward compatibility in pre GCC 3.0 compiled code.
-
-If this macro is not defined, it defaults to
-@code{DWARF_FRAME_REGISTERS}.
-@end defmac
-
-@defmac DWARF_REG_TO_UNWIND_COLUMN (@var{regno})
-
-Define this macro if the target's representation for dwarf registers
-is different than the internal representation for unwind column.
-Given a dwarf register, this macro should return the internal unwind
-column number to use instead.
-@end defmac
-
-@defmac DWARF_FRAME_REGNUM (@var{regno})
-
-Define this macro if the target's representation for dwarf registers
-used in .eh_frame or .debug_frame is different from that used in other
-debug info sections. Given a GCC hard register number, this macro
-should return the .eh_frame register number. The default is
-@code{DEBUGGER_REGNO (@var{regno})}.
-
-@end defmac
-
-@defmac DWARF2_FRAME_REG_OUT (@var{regno}, @var{for_eh})
-
-Define this macro to map register numbers held in the call frame info
-that GCC has collected using @code{DWARF_FRAME_REGNUM} to those that
-should be output in .debug_frame (@code{@var{for_eh}} is zero) and
-.eh_frame (@code{@var{for_eh}} is nonzero). The default is to
-return @code{@var{regno}}.
-
-@end defmac
-
-@defmac REG_VALUE_IN_UNWIND_CONTEXT
-
-Define this macro if the target stores register values as
-@code{_Unwind_Word} type in unwind context. It should be defined if
-target register size is larger than the size of @code{void *}. The
-default is to store register values as @code{void *} type.
-
-@end defmac
-
-@defmac ASSUME_EXTENDED_UNWIND_CONTEXT
-
-Define this macro to be 1 if the target always uses extended unwind
-context with version, args_size and by_value fields. If it is undefined,
-it will be defined to 1 when @code{REG_VALUE_IN_UNWIND_CONTEXT} is
-defined and 0 otherwise.
-
-@end defmac
-
-@defmac DWARF_LAZY_REGISTER_VALUE (@var{regno}, @var{value})
-Define this macro if the target has pseudo DWARF registers whose
-values need to be computed lazily on demand by the unwinder (such as when
-referenced in a CFA expression). The macro returns true if @var{regno}
-is such a register and stores its value in @samp{*@var{value}} if so.
-@end defmac
-
-@node Elimination
-@subsection Eliminating Frame Pointer and Arg Pointer
-
-@c prevent bad page break with this line
-This is about eliminating the frame pointer and arg pointer.
-
-@hook TARGET_FRAME_POINTER_REQUIRED
-
-@defmac ELIMINABLE_REGS
-This macro specifies a table of register pairs used to eliminate
-unneeded registers that point into the stack frame.
-
-The definition of this macro is a list of structure initializations, each
-of which specifies an original and replacement register.
-
-On some machines, the position of the argument pointer is not known until
-the compilation is completed. In such a case, a separate hard register
-must be used for the argument pointer. This register can be eliminated by
-replacing it with either the frame pointer or the argument pointer,
-depending on whether or not the frame pointer has been eliminated.
-
-In this case, you might specify:
-@smallexample
-#define ELIMINABLE_REGS \
-@{@{ARG_POINTER_REGNUM, STACK_POINTER_REGNUM@}, \
- @{ARG_POINTER_REGNUM, FRAME_POINTER_REGNUM@}, \
- @{FRAME_POINTER_REGNUM, STACK_POINTER_REGNUM@}@}
-@end smallexample
-
-Note that the elimination of the argument pointer with the stack pointer is
-specified first since that is the preferred elimination.
-@end defmac
-
-@hook TARGET_CAN_ELIMINATE
-
-@defmac INITIAL_ELIMINATION_OFFSET (@var{from-reg}, @var{to-reg}, @var{offset-var})
-This macro returns the initial difference between the specified pair
-of registers. The value would be computed from information
-such as the result of @code{get_frame_size ()} and the tables of
-registers @code{df_regs_ever_live_p} and @code{call_used_regs}.
-@end defmac
-
-@hook TARGET_COMPUTE_FRAME_LAYOUT
-
-@node Stack Arguments
-@subsection Passing Function Arguments on the Stack
-@cindex arguments on stack
-@cindex stack arguments
-
-The macros in this section control how arguments are passed
-on the stack. See the following section for other macros that
-control passing certain arguments in registers.
-
-@hook TARGET_PROMOTE_PROTOTYPES
-
-@hook TARGET_PUSH_ARGUMENT
-
-@defmac PUSH_ARGS_REVERSED
-A C expression. If nonzero, function arguments will be evaluated from
-last to first, rather than from first to last. If this macro is not
-defined, it defaults to @code{PUSH_ARGS} on targets where the stack
-and args grow in opposite directions, and 0 otherwise.
-@end defmac
-
-@defmac PUSH_ROUNDING (@var{npushed})
-A C expression that is the number of bytes actually pushed onto the
-stack when an instruction attempts to push @var{npushed} bytes.
-
-On some machines, the definition
-
-@smallexample
-#define PUSH_ROUNDING(BYTES) (BYTES)
-@end smallexample
-
-@noindent
-will suffice. But on other machines, instructions that appear
-to push one byte actually push two bytes in an attempt to maintain
-alignment. Then the definition should be
-
-@smallexample
-#define PUSH_ROUNDING(BYTES) (((BYTES) + 1) & ~1)
-@end smallexample
-
-If the value of this macro has a type, it should be an unsigned type.
-@end defmac
-
-@findex outgoing_args_size
-@findex crtl->outgoing_args_size
-@defmac ACCUMULATE_OUTGOING_ARGS
-A C expression. If nonzero, the maximum amount of space required for outgoing arguments
-will be computed and placed into
-@code{crtl->outgoing_args_size}. No space will be pushed
-onto the stack for each call; instead, the function prologue should
-increase the stack frame size by this amount.
-
-Setting both @code{PUSH_ARGS} and @code{ACCUMULATE_OUTGOING_ARGS}
-is not proper.
-@end defmac
-
-@defmac REG_PARM_STACK_SPACE (@var{fndecl})
-Define this macro if functions should assume that stack space has been
-allocated for arguments even when their values are passed in
-registers.
-
-The value of this macro is the size, in bytes, of the area reserved for
-arguments passed in registers for the function represented by @var{fndecl},
-which can be zero if GCC is calling a library function.
-The argument @var{fndecl} can be the FUNCTION_DECL, or the type itself
-of the function.
-
-This space can be allocated by the caller, or be a part of the
-machine-dependent stack frame: @code{OUTGOING_REG_PARM_STACK_SPACE} says
-which.
-@end defmac
-@c above is overfull. not sure what to do. --mew 5feb93 did
-@c something, not sure if it looks good. --mew 10feb93
-
-@defmac INCOMING_REG_PARM_STACK_SPACE (@var{fndecl})
-Like @code{REG_PARM_STACK_SPACE}, but for incoming register arguments.
-Define this macro if space guaranteed when compiling a function body
-is different to space required when making a call, a situation that
-can arise with K&R style function definitions.
-@end defmac
-
-@defmac OUTGOING_REG_PARM_STACK_SPACE (@var{fntype})
-Define this to a nonzero value if it is the responsibility of the
-caller to allocate the area reserved for arguments passed in registers
-when calling a function of @var{fntype}. @var{fntype} may be NULL
-if the function called is a library function.
-
-If @code{ACCUMULATE_OUTGOING_ARGS} is defined, this macro controls
-whether the space for these arguments counts in the value of
-@code{crtl->outgoing_args_size}.
-@end defmac
-
-@defmac STACK_PARMS_IN_REG_PARM_AREA
-Define this macro if @code{REG_PARM_STACK_SPACE} is defined, but the
-stack parameters don't skip the area specified by it.
-@c i changed this, makes more sens and it should have taken care of the
-@c overfull.. not as specific, tho. --mew 5feb93
-
-Normally, when a parameter is not passed in registers, it is placed on the
-stack beyond the @code{REG_PARM_STACK_SPACE} area. Defining this macro
-suppresses this behavior and causes the parameter to be passed on the
-stack in its natural location.
-@end defmac
-
-@hook TARGET_RETURN_POPS_ARGS
-
-@defmac CALL_POPS_ARGS (@var{cum})
-A C expression that should indicate the number of bytes a call sequence
-pops off the stack. It is added to the value of @code{RETURN_POPS_ARGS}
-when compiling a function call.
-
-@var{cum} is the variable in which all arguments to the called function
-have been accumulated.
-
-On certain architectures, such as the SH5, a call trampoline is used
-that pops certain registers off the stack, depending on the arguments
-that have been passed to the function. Since this is a property of the
-call site, not of the called function, @code{RETURN_POPS_ARGS} is not
-appropriate.
-@end defmac
-
-@node Register Arguments
-@subsection Passing Arguments in Registers
-@cindex arguments in registers
-@cindex registers arguments
-
-This section describes the macros which let you control how various
-types of arguments are passed in registers or how they are arranged in
-the stack.
-
-@hook TARGET_FUNCTION_ARG
-
-@hook TARGET_MUST_PASS_IN_STACK
-
-@hook TARGET_FUNCTION_INCOMING_ARG
-
-@hook TARGET_USE_PSEUDO_PIC_REG
-
-@hook TARGET_INIT_PIC_REG
-
-@hook TARGET_ARG_PARTIAL_BYTES
-
-@hook TARGET_PASS_BY_REFERENCE
-
-@hook TARGET_CALLEE_COPIES
-
-@defmac CUMULATIVE_ARGS
-A C type for declaring a variable that is used as the first argument
-of @code{TARGET_FUNCTION_ARG} and other related values. For some
-target machines, the type @code{int} suffices and can hold the number
-of bytes of argument so far.
-
-There is no need to record in @code{CUMULATIVE_ARGS} anything about the
-arguments that have been passed on the stack. The compiler has other
-variables to keep track of that. For target machines on which all
-arguments are passed on the stack, there is no need to store anything in
-@code{CUMULATIVE_ARGS}; however, the data structure must exist and
-should not be empty, so use @code{int}.
-@end defmac
-
-@defmac OVERRIDE_ABI_FORMAT (@var{fndecl})
-If defined, this macro is called before generating any code for a
-function, but after the @var{cfun} descriptor for the function has been
-created. The back end may use this macro to update @var{cfun} to
-reflect an ABI other than that which would normally be used by default.
-If the compiler is generating code for a compiler-generated function,
-@var{fndecl} may be @code{NULL}.
-@end defmac
-
-@defmac INIT_CUMULATIVE_ARGS (@var{cum}, @var{fntype}, @var{libname}, @var{fndecl}, @var{n_named_args})
-A C statement (sans semicolon) for initializing the variable
-@var{cum} for the state at the beginning of the argument list. The
-variable has type @code{CUMULATIVE_ARGS}. The value of @var{fntype}
-is the tree node for the data type of the function which will receive
-the args, or 0 if the args are to a compiler support library function.
-For direct calls that are not libcalls, @var{fndecl} contain the
-declaration node of the function. @var{fndecl} is also set when
-@code{INIT_CUMULATIVE_ARGS} is used to find arguments for the function
-being compiled. @var{n_named_args} is set to the number of named
-arguments, including a structure return address if it is passed as a
-parameter, when making a call. When processing incoming arguments,
-@var{n_named_args} is set to @minus{}1.
-
-When processing a call to a compiler support library function,
-@var{libname} identifies which one. It is a @code{symbol_ref} rtx which
-contains the name of the function, as a string. @var{libname} is 0 when
-an ordinary C function call is being processed. Thus, each time this
-macro is called, either @var{libname} or @var{fntype} is nonzero, but
-never both of them at once.
-@end defmac
-
-@defmac INIT_CUMULATIVE_LIBCALL_ARGS (@var{cum}, @var{mode}, @var{libname})
-Like @code{INIT_CUMULATIVE_ARGS} but only used for outgoing libcalls,
-it gets a @code{MODE} argument instead of @var{fntype}, that would be
-@code{NULL}. @var{indirect} would always be zero, too. If this macro
-is not defined, @code{INIT_CUMULATIVE_ARGS (cum, NULL_RTX, libname,
-0)} is used instead.
-@end defmac
-
-@defmac INIT_CUMULATIVE_INCOMING_ARGS (@var{cum}, @var{fntype}, @var{libname})
-Like @code{INIT_CUMULATIVE_ARGS} but overrides it for the purposes of
-finding the arguments for the function being compiled. If this macro is
-undefined, @code{INIT_CUMULATIVE_ARGS} is used instead.
-
-The value passed for @var{libname} is always 0, since library routines
-with special calling conventions are never compiled with GCC@. The
-argument @var{libname} exists for symmetry with
-@code{INIT_CUMULATIVE_ARGS}.
-@c could use "this macro" in place of @code{INIT_CUMULATIVE_ARGS}, maybe.
-@c --mew 5feb93 i switched the order of the sentences. --mew 10feb93
-@end defmac
-
-@hook TARGET_FUNCTION_ARG_ADVANCE
-
-@hook TARGET_FUNCTION_ARG_OFFSET
-
-@hook TARGET_FUNCTION_ARG_PADDING
-
-@defmac PAD_VARARGS_DOWN
-If defined, a C expression which determines whether the default
-implementation of va_arg will attempt to pad down before reading the
-next argument, if that argument is smaller than its aligned space as
-controlled by @code{PARM_BOUNDARY}. If this macro is not defined, all such
-arguments are padded down if @code{BYTES_BIG_ENDIAN} is true.
-@end defmac
-
-@defmac BLOCK_REG_PADDING (@var{mode}, @var{type}, @var{first})
-Specify padding for the last element of a block move between registers and
-memory. @var{first} is nonzero if this is the only element. Defining this
-macro allows better control of register function parameters on big-endian
-machines, without using @code{PARALLEL} rtl. In particular,
-@code{MUST_PASS_IN_STACK} need not test padding and mode of types in
-registers, as there is no longer a "wrong" part of a register; For example,
-a three byte aggregate may be passed in the high part of a register if so
-required.
-@end defmac
-
-@hook TARGET_FUNCTION_ARG_BOUNDARY
-
-@hook TARGET_FUNCTION_ARG_ROUND_BOUNDARY
-
-@defmac FUNCTION_ARG_REGNO_P (@var{regno})
-A C expression that is nonzero if @var{regno} is the number of a hard
-register in which function arguments are sometimes passed. This does
-@emph{not} include implicit arguments such as the static chain and
-the structure-value address. On many machines, no registers can be
-used for this purpose since all function arguments are pushed on the
-stack.
-@end defmac
-
-@hook TARGET_SPLIT_COMPLEX_ARG
-
-@hook TARGET_BUILD_BUILTIN_VA_LIST
-
-@hook TARGET_ENUM_VA_LIST_P
-
-@hook TARGET_FN_ABI_VA_LIST
-
-@hook TARGET_CANONICAL_VA_LIST_TYPE
-
-@hook TARGET_GIMPLIFY_VA_ARG_EXPR
-
-@hook TARGET_VALID_POINTER_MODE
-
-@hook TARGET_REF_MAY_ALIAS_ERRNO
-
-@hook TARGET_TRANSLATE_MODE_ATTRIBUTE
-
-@hook TARGET_SCALAR_MODE_SUPPORTED_P
-
-@hook TARGET_VECTOR_MODE_SUPPORTED_P
-
-@hook TARGET_COMPATIBLE_VECTOR_TYPES_P
-
-@hook TARGET_ARRAY_MODE
-
-@hook TARGET_ARRAY_MODE_SUPPORTED_P
-
-@hook TARGET_LIBGCC_FLOATING_MODE_SUPPORTED_P
-
-@hook TARGET_FLOATN_MODE
-
-@hook TARGET_FLOATN_BUILTIN_P
-
-@hook TARGET_SMALL_REGISTER_CLASSES_FOR_MODE_P
-
-@node Scalar Return
-@subsection How Scalar Function Values Are Returned
-@cindex return values in registers
-@cindex values, returned by functions
-@cindex scalars, returned as values
-
-This section discusses the macros that control returning scalars as
-values---values that can fit in registers.
-
-@hook TARGET_FUNCTION_VALUE
-
-@defmac FUNCTION_VALUE (@var{valtype}, @var{func})
-This macro has been deprecated. Use @code{TARGET_FUNCTION_VALUE} for
-a new target instead.
-@end defmac
-
-@defmac LIBCALL_VALUE (@var{mode})
-A C expression to create an RTX representing the place where a library
-function returns a value of mode @var{mode}.
-
-Note that ``library function'' in this context means a compiler
-support routine, used to perform arithmetic, whose name is known
-specially by the compiler and was not mentioned in the C code being
-compiled.
-@end defmac
-
-@hook TARGET_LIBCALL_VALUE
-
-@defmac FUNCTION_VALUE_REGNO_P (@var{regno})
-A C expression that is nonzero if @var{regno} is the number of a hard
-register in which the values of called function may come back.
-
-A register whose use for returning values is limited to serving as the
-second of a pair (for a value of type @code{double}, say) need not be
-recognized by this macro. So for most machines, this definition
-suffices:
-
-@smallexample
-#define FUNCTION_VALUE_REGNO_P(N) ((N) == 0)
-@end smallexample
-
-If the machine has register windows, so that the caller and the called
-function use different registers for the return value, this macro
-should recognize only the caller's register numbers.
-
-This macro has been deprecated. Use @code{TARGET_FUNCTION_VALUE_REGNO_P}
-for a new target instead.
-@end defmac
-
-@hook TARGET_FUNCTION_VALUE_REGNO_P
-
-@defmac APPLY_RESULT_SIZE
-Define this macro if @samp{untyped_call} and @samp{untyped_return}
-need more space than is implied by @code{FUNCTION_VALUE_REGNO_P} for
-saving and restoring an arbitrary return value.
-@end defmac
-
-@hook TARGET_OMIT_STRUCT_RETURN_REG
-
-@hook TARGET_RETURN_IN_MSB
-
-@node Aggregate Return
-@subsection How Large Values Are Returned
-@cindex aggregates as return values
-@cindex large return values
-@cindex returning aggregate values
-@cindex structure value address
-
-When a function value's mode is @code{BLKmode} (and in some other
-cases), the value is not returned according to
-@code{TARGET_FUNCTION_VALUE} (@pxref{Scalar Return}). Instead, the
-caller passes the address of a block of memory in which the value
-should be stored. This address is called the @dfn{structure value
-address}.
-
-This section describes how to control returning structure values in
-memory.
-
-@hook TARGET_RETURN_IN_MEMORY
-
-@defmac DEFAULT_PCC_STRUCT_RETURN
-Define this macro to be 1 if all structure and union return values must be
-in memory. Since this results in slower code, this should be defined
-only if needed for compatibility with other compilers or with an ABI@.
-If you define this macro to be 0, then the conventions used for structure
-and union return values are decided by the @code{TARGET_RETURN_IN_MEMORY}
-target hook.
-
-If not defined, this defaults to the value 1.
-@end defmac
-
-@hook TARGET_STRUCT_VALUE_RTX
-
-@defmac PCC_STATIC_STRUCT_RETURN
-Define this macro if the usual system convention on the target machine
-for returning structures and unions is for the called function to return
-the address of a static variable containing the value.
-
-Do not define this if the usual system convention is for the caller to
-pass an address to the subroutine.
-
-This macro has effect in @option{-fpcc-struct-return} mode, but it does
-nothing when you use @option{-freg-struct-return} mode.
-@end defmac
-
-@hook TARGET_GET_RAW_RESULT_MODE
-
-@hook TARGET_GET_RAW_ARG_MODE
-
-@hook TARGET_EMPTY_RECORD_P
-
-@hook TARGET_WARN_PARAMETER_PASSING_ABI
-
-@node Caller Saves
-@subsection Caller-Saves Register Allocation
-
-If you enable it, GCC can save registers around function calls. This
-makes it possible to use call-clobbered registers to hold variables that
-must live across calls.
-
-@defmac HARD_REGNO_CALLER_SAVE_MODE (@var{regno}, @var{nregs})
-A C expression specifying which mode is required for saving @var{nregs}
-of a pseudo-register in call-clobbered hard register @var{regno}. If
-@var{regno} is unsuitable for caller save, @code{VOIDmode} should be
-returned. For most machines this macro need not be defined since GCC
-will select the smallest suitable mode.
-@end defmac
-
-@node Function Entry
-@subsection Function Entry and Exit
-@cindex function entry and exit
-@cindex prologue
-@cindex epilogue
-
-This section describes the macros that output function entry
-(@dfn{prologue}) and exit (@dfn{epilogue}) code.
-
-@hook TARGET_ASM_PRINT_PATCHABLE_FUNCTION_ENTRY
-
-@hook TARGET_ASM_FUNCTION_PROLOGUE
-
-@hook TARGET_ASM_FUNCTION_END_PROLOGUE
-
-@hook TARGET_ASM_FUNCTION_BEGIN_EPILOGUE
-
-@hook TARGET_ASM_FUNCTION_EPILOGUE
-
-@itemize @bullet
-@item
-@findex pretend_args_size
-@findex crtl->args.pretend_args_size
-A region of @code{crtl->args.pretend_args_size} bytes of
-uninitialized space just underneath the first argument arriving on the
-stack. (This may not be at the very start of the allocated stack region
-if the calling sequence has pushed anything else since pushing the stack
-arguments. But usually, on such machines, nothing else has been pushed
-yet, because the function prologue itself does all the pushing.) This
-region is used on machines where an argument may be passed partly in
-registers and partly in memory, and, in some cases to support the
-features in @code{<stdarg.h>}.
-
-@item
-An area of memory used to save certain registers used by the function.
-The size of this area, which may also include space for such things as
-the return address and pointers to previous stack frames, is
-machine-specific and usually depends on which registers have been used
-in the function. Machines with register windows often do not require
-a save area.
-
-@item
-A region of at least @var{size} bytes, possibly rounded up to an allocation
-boundary, to contain the local variables of the function. On some machines,
-this region and the save area may occur in the opposite order, with the
-save area closer to the top of the stack.
-
-@item
-@cindex @code{ACCUMULATE_OUTGOING_ARGS} and stack frames
-Optionally, when @code{ACCUMULATE_OUTGOING_ARGS} is defined, a region of
-@code{crtl->outgoing_args_size} bytes to be used for outgoing
-argument lists of the function. @xref{Stack Arguments}.
-@end itemize
-
-@defmac EXIT_IGNORE_STACK
-Define this macro as a C expression that is nonzero if the return
-instruction or the function epilogue ignores the value of the stack
-pointer; in other words, if it is safe to delete an instruction to
-adjust the stack pointer before a return from the function. The
-default is 0.
-
-Note that this macro's value is relevant only for functions for which
-frame pointers are maintained. It is never safe to delete a final
-stack adjustment in a function that has no frame pointer, and the
-compiler knows this regardless of @code{EXIT_IGNORE_STACK}.
-@end defmac
-
-@defmac EPILOGUE_USES (@var{regno})
-Define this macro as a C expression that is nonzero for registers that are
-used by the epilogue or the @samp{return} pattern. The stack and frame
-pointer registers are already assumed to be used as needed.
-@end defmac
-
-@defmac EH_USES (@var{regno})
-Define this macro as a C expression that is nonzero for registers that are
-used by the exception handling mechanism, and so should be considered live
-on entry to an exception edge.
-@end defmac
-
-@hook TARGET_ASM_OUTPUT_MI_THUNK
-
-@hook TARGET_ASM_CAN_OUTPUT_MI_THUNK
-
-@node Profiling
-@subsection Generating Code for Profiling
-@cindex profiling, code generation
-
-These macros will help you generate code for profiling.
-
-@defmac FUNCTION_PROFILER (@var{file}, @var{labelno})
-A C statement or compound statement to output to @var{file} some
-assembler code to call the profiling subroutine @code{mcount}.
-
-@findex mcount
-The details of how @code{mcount} expects to be called are determined by
-your operating system environment, not by GCC@. To figure them out,
-compile a small program for profiling using the system's installed C
-compiler and look at the assembler code that results.
-
-Older implementations of @code{mcount} expect the address of a counter
-variable to be loaded into some register. The name of this variable is
-@samp{LP} followed by the number @var{labelno}, so you would generate
-the name using @samp{LP%d} in a @code{fprintf}.
-@end defmac
-
-@defmac PROFILE_HOOK
-A C statement or compound statement to output to @var{file} some assembly
-code to call the profiling subroutine @code{mcount} even the target does
-not support profiling.
-@end defmac
-
-@defmac NO_PROFILE_COUNTERS
-Define this macro to be an expression with a nonzero value if the
-@code{mcount} subroutine on your system does not need a counter variable
-allocated for each function. This is true for almost all modern
-implementations. If you define this macro, you must not use the
-@var{labelno} argument to @code{FUNCTION_PROFILER}.
-@end defmac
-
-@defmac PROFILE_BEFORE_PROLOGUE
-Define this macro if the code for function profiling should come before
-the function prologue. Normally, the profiling code comes after.
-@end defmac
-
-@hook TARGET_KEEP_LEAF_WHEN_PROFILED
-
-@node Tail Calls
-@subsection Permitting tail calls
-@cindex tail calls
-
-@hook TARGET_FUNCTION_OK_FOR_SIBCALL
-
-@hook TARGET_EXTRA_LIVE_ON_ENTRY
-
-@hook TARGET_SET_UP_BY_PROLOGUE
-
-@hook TARGET_WARN_FUNC_RETURN
-
-@node Shrink-wrapping separate components
-@subsection Shrink-wrapping separate components
-@cindex shrink-wrapping separate components
-
-The prologue may perform a variety of target dependent tasks such as
-saving callee-saved registers, saving the return address, aligning the
-stack, creating a stack frame, initializing the PIC register, setting
-up the static chain, etc.
-
-On some targets some of these tasks may be independent of others and
-thus may be shrink-wrapped separately. These independent tasks are
-referred to as components and are handled generically by the target
-independent parts of GCC.
-
-Using the following hooks those prologue or epilogue components can be
-shrink-wrapped separately, so that the initialization (and possibly
-teardown) those components do is not done as frequently on execution
-paths where this would unnecessary.
-
-What exactly those components are is up to the target code; the generic
-code treats them abstractly, as a bit in an @code{sbitmap}. These
-@code{sbitmap}s are allocated by the @code{shrink_wrap.get_separate_components}
-and @code{shrink_wrap.components_for_bb} hooks, and deallocated by the
-generic code.
-
-@hook TARGET_SHRINK_WRAP_GET_SEPARATE_COMPONENTS
-
-@hook TARGET_SHRINK_WRAP_COMPONENTS_FOR_BB
-
-@hook TARGET_SHRINK_WRAP_DISQUALIFY_COMPONENTS
-
-@hook TARGET_SHRINK_WRAP_EMIT_PROLOGUE_COMPONENTS
-
-@hook TARGET_SHRINK_WRAP_EMIT_EPILOGUE_COMPONENTS
-
-@hook TARGET_SHRINK_WRAP_SET_HANDLED_COMPONENTS
-
-@node Stack Smashing Protection
-@subsection Stack smashing protection
-@cindex stack smashing protection
-
-@hook TARGET_STACK_PROTECT_GUARD
-
-@hook TARGET_STACK_PROTECT_FAIL
-
-@hook TARGET_STACK_PROTECT_RUNTIME_ENABLED_P
-
-@hook TARGET_SUPPORTS_SPLIT_STACK
-
-@hook TARGET_GET_VALID_OPTION_VALUES
-
-@node Miscellaneous Register Hooks
-@subsection Miscellaneous register hooks
-@cindex miscellaneous register hooks
-
-@hook TARGET_CALL_FUSAGE_CONTAINS_NON_CALLEE_CLOBBERS
-
-@node Varargs
-@section Implementing the Varargs Macros
-@cindex varargs implementation
-
-GCC comes with an implementation of @code{<varargs.h>} and
-@code{<stdarg.h>} that work without change on machines that pass arguments
-on the stack. Other machines require their own implementations of
-varargs, and the two machine independent header files must have
-conditionals to include it.
-
-ISO @code{<stdarg.h>} differs from traditional @code{<varargs.h>} mainly in
-the calling convention for @code{va_start}. The traditional
-implementation takes just one argument, which is the variable in which
-to store the argument pointer. The ISO implementation of
-@code{va_start} takes an additional second argument. The user is
-supposed to write the last named argument of the function here.
-
-However, @code{va_start} should not use this argument. The way to find
-the end of the named arguments is with the built-in functions described
-below.
-
-@defmac __builtin_saveregs ()
-Use this built-in function to save the argument registers in memory so
-that the varargs mechanism can access them. Both ISO and traditional
-versions of @code{va_start} must use @code{__builtin_saveregs}, unless
-you use @code{TARGET_SETUP_INCOMING_VARARGS} (see below) instead.
-
-On some machines, @code{__builtin_saveregs} is open-coded under the
-control of the target hook @code{TARGET_EXPAND_BUILTIN_SAVEREGS}. On
-other machines, it calls a routine written in assembler language,
-found in @file{libgcc2.c}.
-
-Code generated for the call to @code{__builtin_saveregs} appears at the
-beginning of the function, as opposed to where the call to
-@code{__builtin_saveregs} is written, regardless of what the code is.
-This is because the registers must be saved before the function starts
-to use them for its own purposes.
-@c i rewrote the first sentence above to fix an overfull hbox. --mew
-@c 10feb93
-@end defmac
-
-@defmac __builtin_next_arg (@var{lastarg})
-This builtin returns the address of the first anonymous stack
-argument, as type @code{void *}. If @code{ARGS_GROW_DOWNWARD}, it
-returns the address of the location above the first anonymous stack
-argument. Use it in @code{va_start} to initialize the pointer for
-fetching arguments from the stack. Also use it in @code{va_start} to
-verify that the second parameter @var{lastarg} is the last named argument
-of the current function.
-@end defmac
-
-@defmac __builtin_classify_type (@var{object})
-Since each machine has its own conventions for which data types are
-passed in which kind of register, your implementation of @code{va_arg}
-has to embody these conventions. The easiest way to categorize the
-specified data type is to use @code{__builtin_classify_type} together
-with @code{sizeof} and @code{__alignof__}.
-
-@code{__builtin_classify_type} ignores the value of @var{object},
-considering only its data type. It returns an integer describing what
-kind of type that is---integer, floating, pointer, structure, and so on.
-
-The file @file{typeclass.h} defines an enumeration that you can use to
-interpret the values of @code{__builtin_classify_type}.
-@end defmac
-
-These machine description macros help implement varargs:
-
-@hook TARGET_EXPAND_BUILTIN_SAVEREGS
-
-@hook TARGET_SETUP_INCOMING_VARARGS
-
-@hook TARGET_STRICT_ARGUMENT_NAMING
-
-@hook TARGET_CALL_ARGS
-
-@hook TARGET_END_CALL_ARGS
-
-@hook TARGET_PRETEND_OUTGOING_VARARGS_NAMED
-
-@node Trampolines
-@section Support for Nested Functions
-@cindex support for nested functions
-@cindex trampolines for nested functions
-@cindex descriptors for nested functions
-@cindex nested functions, support for
-
-Taking the address of a nested function requires special compiler
-handling to ensure that the static chain register is loaded when
-the function is invoked via an indirect call.
-
-GCC has traditionally supported nested functions by creating an
-executable @dfn{trampoline} at run time when the address of a nested
-function is taken. This is a small piece of code which normally
-resides on the stack, in the stack frame of the containing function.
-The trampoline loads the static chain register and then jumps to the
-real address of the nested function.
-
-The use of trampolines requires an executable stack, which is a
-security risk. To avoid this problem, GCC also supports another
-strategy: using descriptors for nested functions. Under this model,
-taking the address of a nested function results in a pointer to a
-non-executable function descriptor object. Initializing the static chain
-from the descriptor is handled at indirect call sites.
-
-On some targets, including HPPA and IA-64, function descriptors may be
-mandated by the ABI or be otherwise handled in a target-specific way
-by the back end in its code generation strategy for indirect calls.
-GCC also provides its own generic descriptor implementation to support the
-@option{-fno-trampolines} option. In this case runtime detection of
-function descriptors at indirect call sites relies on descriptor
-pointers being tagged with a bit that is never set in bare function
-addresses. Since GCC's generic function descriptors are
-not ABI-compliant, this option is typically used only on a
-per-language basis (notably by Ada) or when it can otherwise be
-applied to the whole program.
-
-For languages other than Ada, the @code{-ftrampolines} and
-@code{-fno-trampolines} options currently have no effect, and
-trampolines are always generated on platforms that need them
-for nested functions.
-
-Define the following hook if your backend either implements ABI-specified
-descriptor support, or can use GCC's generic descriptor implementation
-for nested functions.
-
-@hook TARGET_CUSTOM_FUNCTION_DESCRIPTORS
-
-The following macros tell GCC how to generate code to allocate and
-initialize an executable trampoline. You can also use this interface
-if your back end needs to create ABI-specified non-executable descriptors; in
-this case the "trampoline" created is the descriptor containing data only.
-
-The instructions in an executable trampoline must do two things: load
-a constant address into the static chain register, and jump to the real
-address of the nested function. On CISC machines such as the m68k,
-this requires two instructions, a move immediate and a jump. Then the
-two addresses exist in the trampoline as word-long immediate operands.
-On RISC machines, it is often necessary to load each address into a
-register in two parts. Then pieces of each address form separate
-immediate operands.
-
-The code generated to initialize the trampoline must store the variable
-parts---the static chain value and the function address---into the
-immediate operands of the instructions. On a CISC machine, this is
-simply a matter of copying each address to a memory reference at the
-proper offset from the start of the trampoline. On a RISC machine, it
-may be necessary to take out pieces of the address and store them
-separately.
-
-@hook TARGET_ASM_TRAMPOLINE_TEMPLATE
-
-@defmac TRAMPOLINE_SECTION
-Return the section into which the trampoline template is to be placed
-(@pxref{Sections}). The default value is @code{readonly_data_section}.
-@end defmac
-
-@defmac TRAMPOLINE_SIZE
-A C expression for the size in bytes of the trampoline, as an integer.
-@end defmac
-
-@defmac TRAMPOLINE_ALIGNMENT
-Alignment required for trampolines, in bits.
-
-If you don't define this macro, the value of @code{FUNCTION_ALIGNMENT}
-is used for aligning trampolines.
-@end defmac
-
-@hook TARGET_TRAMPOLINE_INIT
-
-@hook TARGET_EMIT_CALL_BUILTIN___CLEAR_CACHE
-
-@hook TARGET_TRAMPOLINE_ADJUST_ADDRESS
-
-Implementing trampolines is difficult on many machines because they have
-separate instruction and data caches. Writing into a stack location
-fails to clear the memory in the instruction cache, so when the program
-jumps to that location, it executes the old contents.
-
-Here are two possible solutions. One is to clear the relevant parts of
-the instruction cache whenever a trampoline is set up. The other is to
-make all trampolines identical, by having them jump to a standard
-subroutine. The former technique makes trampoline execution faster; the
-latter makes initialization faster.
-
-To clear the instruction cache when a trampoline is initialized, define
-the following macro.
-
-@defmac CLEAR_INSN_CACHE (@var{beg}, @var{end})
-If defined, expands to a C expression clearing the @emph{instruction
-cache} in the specified interval. The definition of this macro would
-typically be a series of @code{asm} statements. Both @var{beg} and
-@var{end} are pointer expressions.
-@end defmac
-
-To use a standard subroutine, define the following macro. In addition,
-you must make sure that the instructions in a trampoline fill an entire
-cache line with identical instructions, or else ensure that the
-beginning of the trampoline code is always aligned at the same point in
-its cache line. Look in @file{m68k.h} as a guide.
-
-@defmac TRANSFER_FROM_TRAMPOLINE
-Define this macro if trampolines need a special subroutine to do their
-work. The macro should expand to a series of @code{asm} statements
-which will be compiled with GCC@. They go in a library function named
-@code{__transfer_from_trampoline}.
-
-If you need to avoid executing the ordinary prologue code of a compiled
-C function when you jump to the subroutine, you can do so by placing a
-special label of your own in the assembler code. Use one @code{asm}
-statement to generate an assembler label, and another to make the label
-global. Then trampolines can use that label to jump directly to your
-special assembler code.
-@end defmac
-
-@node Library Calls
-@section Implicit Calls to Library Routines
-@cindex library subroutine names
-@cindex @file{libgcc.a}
-
-@c prevent bad page break with this line
-Here is an explanation of implicit calls to library routines.
-
-@defmac DECLARE_LIBRARY_RENAMES
-This macro, if defined, should expand to a piece of C code that will get
-expanded when compiling functions for libgcc.a. It can be used to
-provide alternate names for GCC's internal library functions if there
-are ABI-mandated names that the compiler should provide.
-@end defmac
-
-@findex set_optab_libfunc
-@findex init_one_libfunc
-@hook TARGET_INIT_LIBFUNCS
-
-@hook TARGET_LIBFUNC_GNU_PREFIX
-
-@defmac FLOAT_LIB_COMPARE_RETURNS_BOOL (@var{mode}, @var{comparison})
-This macro should return @code{true} if the library routine that
-implements the floating point comparison operator @var{comparison} in
-mode @var{mode} will return a boolean, and @var{false} if it will
-return a tristate.
-
-GCC's own floating point libraries return tristates from the
-comparison operators, so the default returns false always. Most ports
-don't need to define this macro.
-@end defmac
-
-@defmac TARGET_LIB_INT_CMP_BIASED
-This macro should evaluate to @code{true} if the integer comparison
-functions (like @code{__cmpdi2}) return 0 to indicate that the first
-operand is smaller than the second, 1 to indicate that they are equal,
-and 2 to indicate that the first operand is greater than the second.
-If this macro evaluates to @code{false} the comparison functions return
-@minus{}1, 0, and 1 instead of 0, 1, and 2. If the target uses the routines
-in @file{libgcc.a}, you do not need to define this macro.
-@end defmac
-
-@defmac TARGET_HAS_NO_HW_DIVIDE
-This macro should be defined if the target has no hardware divide
-instructions. If this macro is defined, GCC will use an algorithm which
-make use of simple logical and arithmetic operations for 64-bit
-division. If the macro is not defined, GCC will use an algorithm which
-make use of a 64-bit by 32-bit divide primitive.
-@end defmac
-
-@cindex @code{EDOM}, implicit usage
-@findex matherr
-@defmac TARGET_EDOM
-The value of @code{EDOM} on the target machine, as a C integer constant
-expression. If you don't define this macro, GCC does not attempt to
-deposit the value of @code{EDOM} into @code{errno} directly. Look in
-@file{/usr/include/errno.h} to find the value of @code{EDOM} on your
-system.
-
-If you do not define @code{TARGET_EDOM}, then compiled code reports
-domain errors by calling the library function and letting it report the
-error. If mathematical functions on your system use @code{matherr} when
-there is an error, then you should leave @code{TARGET_EDOM} undefined so
-that @code{matherr} is used normally.
-@end defmac
-
-@cindex @code{errno}, implicit usage
-@defmac GEN_ERRNO_RTX
-Define this macro as a C expression to create an rtl expression that
-refers to the global ``variable'' @code{errno}. (On certain systems,
-@code{errno} may not actually be a variable.) If you don't define this
-macro, a reasonable default is used.
-@end defmac
-
-@hook TARGET_LIBC_HAS_FUNCTION
-
-@hook TARGET_LIBC_HAS_FAST_FUNCTION
-
-@defmac NEXT_OBJC_RUNTIME
-Set this macro to 1 to use the "NeXT" Objective-C message sending conventions
-by default. This calling convention involves passing the object, the selector
-and the method arguments all at once to the method-lookup library function.
-This is the usual setting when targeting Darwin/Mac OS X systems, which have
-the NeXT runtime installed.
-
-If the macro is set to 0, the "GNU" Objective-C message sending convention
-will be used by default. This convention passes just the object and the
-selector to the method-lookup function, which returns a pointer to the method.
-
-In either case, it remains possible to select code-generation for the alternate
-scheme, by means of compiler command line switches.
-@end defmac
-
-@node Addressing Modes
-@section Addressing Modes
-@cindex addressing modes
-
-@c prevent bad page break with this line
-This is about addressing modes.
-
-@defmac HAVE_PRE_INCREMENT
-@defmacx HAVE_PRE_DECREMENT
-@defmacx HAVE_POST_INCREMENT
-@defmacx HAVE_POST_DECREMENT
-A C expression that is nonzero if the machine supports pre-increment,
-pre-decrement, post-increment, or post-decrement addressing respectively.
-@end defmac
-
-@defmac HAVE_PRE_MODIFY_DISP
-@defmacx HAVE_POST_MODIFY_DISP
-A C expression that is nonzero if the machine supports pre- or
-post-address side-effect generation involving constants other than
-the size of the memory operand.
-@end defmac
-
-@defmac HAVE_PRE_MODIFY_REG
-@defmacx HAVE_POST_MODIFY_REG
-A C expression that is nonzero if the machine supports pre- or
-post-address side-effect generation involving a register displacement.
-@end defmac
-
-@defmac CONSTANT_ADDRESS_P (@var{x})
-A C expression that is 1 if the RTX @var{x} is a constant which
-is a valid address. On most machines the default definition of
-@code{(CONSTANT_P (@var{x}) && GET_CODE (@var{x}) != CONST_DOUBLE)}
-is acceptable, but a few machines are more restrictive as to which
-constant addresses are supported.
-@end defmac
-
-@defmac CONSTANT_P (@var{x})
-@code{CONSTANT_P}, which is defined by target-independent code,
-accepts integer-values expressions whose values are not explicitly
-known, such as @code{symbol_ref}, @code{label_ref}, and @code{high}
-expressions and @code{const} arithmetic expressions, in addition to
-@code{const_int} and @code{const_double} expressions.
-@end defmac
-
-@defmac MAX_REGS_PER_ADDRESS
-A number, the maximum number of registers that can appear in a valid
-memory address. Note that it is up to you to specify a value equal to
-the maximum number that @code{TARGET_LEGITIMATE_ADDRESS_P} would ever
-accept.
-@end defmac
-
-@hook TARGET_LEGITIMATE_ADDRESS_P
-
-@defmac TARGET_MEM_CONSTRAINT
-A single character to be used instead of the default @code{'m'}
-character for general memory addresses. This defines the constraint
-letter which matches the memory addresses accepted by
-@code{TARGET_LEGITIMATE_ADDRESS_P}. Define this macro if you want to
-support new address formats in your back end without changing the
-semantics of the @code{'m'} constraint. This is necessary in order to
-preserve functionality of inline assembly constructs using the
-@code{'m'} constraint.
-@end defmac
-
-@defmac FIND_BASE_TERM (@var{x})
-A C expression to determine the base term of address @var{x},
-or to provide a simplified version of @var{x} from which @file{alias.cc}
-can easily find the base term. This macro is used in only two places:
-@code{find_base_value} and @code{find_base_term} in @file{alias.cc}.
-
-It is always safe for this macro to not be defined. It exists so
-that alias analysis can understand machine-dependent addresses.
-
-The typical use of this macro is to handle addresses containing
-a label_ref or symbol_ref within an UNSPEC@.
-@end defmac
-
-@hook TARGET_LEGITIMIZE_ADDRESS
-
-@defmac LEGITIMIZE_RELOAD_ADDRESS (@var{x}, @var{mode}, @var{opnum}, @var{type}, @var{ind_levels}, @var{win})
-A C compound statement that attempts to replace @var{x}, which is an address
-that needs reloading, with a valid memory address for an operand of mode
-@var{mode}. @var{win} will be a C statement label elsewhere in the code.
-It is not necessary to define this macro, but it might be useful for
-performance reasons.
-
-For example, on the i386, it is sometimes possible to use a single
-reload register instead of two by reloading a sum of two pseudo
-registers into a register. On the other hand, for number of RISC
-processors offsets are limited so that often an intermediate address
-needs to be generated in order to address a stack slot. By defining
-@code{LEGITIMIZE_RELOAD_ADDRESS} appropriately, the intermediate addresses
-generated for adjacent some stack slots can be made identical, and thus
-be shared.
-
-@emph{Note}: This macro should be used with caution. It is necessary
-to know something of how reload works in order to effectively use this,
-and it is quite easy to produce macros that build in too much knowledge
-of reload internals.
-
-@emph{Note}: This macro must be able to reload an address created by a
-previous invocation of this macro. If it fails to handle such addresses
-then the compiler may generate incorrect code or abort.
-
-@findex push_reload
-The macro definition should use @code{push_reload} to indicate parts that
-need reloading; @var{opnum}, @var{type} and @var{ind_levels} are usually
-suitable to be passed unaltered to @code{push_reload}.
-
-The code generated by this macro must not alter the substructure of
-@var{x}. If it transforms @var{x} into a more legitimate form, it
-should assign @var{x} (which will always be a C variable) a new value.
-This also applies to parts that you change indirectly by calling
-@code{push_reload}.
-
-@findex strict_memory_address_p
-The macro definition may use @code{strict_memory_address_p} to test if
-the address has become legitimate.
-
-@findex copy_rtx
-If you want to change only a part of @var{x}, one standard way of doing
-this is to use @code{copy_rtx}. Note, however, that it unshares only a
-single level of rtl. Thus, if the part to be changed is not at the
-top level, you'll need to replace first the top level.
-It is not necessary for this macro to come up with a legitimate
-address; but often a machine-dependent strategy can generate better code.
-@end defmac
-
-@hook TARGET_MODE_DEPENDENT_ADDRESS_P
-
-@hook TARGET_LEGITIMATE_CONSTANT_P
-
-@hook TARGET_PRECOMPUTE_TLS_P
-
-@hook TARGET_DELEGITIMIZE_ADDRESS
-
-@hook TARGET_CONST_NOT_OK_FOR_DEBUG_P
-
-@hook TARGET_CANNOT_FORCE_CONST_MEM
-
-@hook TARGET_USE_BLOCKS_FOR_CONSTANT_P
-
-@hook TARGET_USE_BLOCKS_FOR_DECL_P
-
-@hook TARGET_BUILTIN_RECIPROCAL
-
-@hook TARGET_VECTORIZE_BUILTIN_MASK_FOR_LOAD
-
-@hook TARGET_VECTORIZE_BUILTIN_VECTORIZATION_COST
-
-@hook TARGET_VECTORIZE_PREFERRED_VECTOR_ALIGNMENT
-
-@hook TARGET_VECTORIZE_VECTOR_ALIGNMENT_REACHABLE
-
-@hook TARGET_VECTORIZE_VEC_PERM_CONST
-
-@hook TARGET_VECTORIZE_BUILTIN_VECTORIZED_FUNCTION
-
-@hook TARGET_VECTORIZE_BUILTIN_MD_VECTORIZED_FUNCTION
-
-@hook TARGET_VECTORIZE_SUPPORT_VECTOR_MISALIGNMENT
-
-@hook TARGET_VECTORIZE_PREFERRED_SIMD_MODE
-
-@hook TARGET_VECTORIZE_SPLIT_REDUCTION
-
-@hook TARGET_VECTORIZE_AUTOVECTORIZE_VECTOR_MODES
-
-@hook TARGET_VECTORIZE_RELATED_MODE
-
-@hook TARGET_VECTORIZE_GET_MASK_MODE
-
-@hook TARGET_VECTORIZE_EMPTY_MASK_IS_EXPENSIVE
-
-@hook TARGET_VECTORIZE_CREATE_COSTS
-
-@hook TARGET_VECTORIZE_BUILTIN_GATHER
-
-@hook TARGET_VECTORIZE_BUILTIN_SCATTER
-
-@hook TARGET_SIMD_CLONE_COMPUTE_VECSIZE_AND_SIMDLEN
-
-@hook TARGET_SIMD_CLONE_ADJUST
-
-@hook TARGET_SIMD_CLONE_USABLE
-
-@hook TARGET_SIMT_VF
-
-@hook TARGET_OMP_DEVICE_KIND_ARCH_ISA
-
-@hook TARGET_GOACC_VALIDATE_DIMS
-
-@hook TARGET_GOACC_DIM_LIMIT
-
-@hook TARGET_GOACC_FORK_JOIN
-
-@hook TARGET_GOACC_REDUCTION
-
-@hook TARGET_PREFERRED_ELSE_VALUE
-
-@hook TARGET_GOACC_ADJUST_PRIVATE_DECL
-
-@hook TARGET_GOACC_EXPAND_VAR_DECL
-
-@hook TARGET_GOACC_CREATE_WORKER_BROADCAST_RECORD
-
-@hook TARGET_GOACC_SHARED_MEM_LAYOUT
-
-@node Anchored Addresses
-@section Anchored Addresses
-@cindex anchored addresses
-@cindex @option{-fsection-anchors}
-
-GCC usually addresses every static object as a separate entity.
-For example, if we have:
-
-@smallexample
-static int a, b, c;
-int foo (void) @{ return a + b + c; @}
-@end smallexample
-
-the code for @code{foo} will usually calculate three separate symbolic
-addresses: those of @code{a}, @code{b} and @code{c}. On some targets,
-it would be better to calculate just one symbolic address and access
-the three variables relative to it. The equivalent pseudocode would
-be something like:
-
-@smallexample
-int foo (void)
-@{
- register int *xr = &x;
- return xr[&a - &x] + xr[&b - &x] + xr[&c - &x];
-@}
-@end smallexample
-
-(which isn't valid C). We refer to shared addresses like @code{x} as
-``section anchors''. Their use is controlled by @option{-fsection-anchors}.
-
-The hooks below describe the target properties that GCC needs to know
-in order to make effective use of section anchors. It won't use
-section anchors at all unless either @code{TARGET_MIN_ANCHOR_OFFSET}
-or @code{TARGET_MAX_ANCHOR_OFFSET} is set to a nonzero value.
-
-@hook TARGET_MIN_ANCHOR_OFFSET
-
-@hook TARGET_MAX_ANCHOR_OFFSET
-
-@hook TARGET_ASM_OUTPUT_ANCHOR
-
-@hook TARGET_USE_ANCHORS_FOR_SYMBOL_P
-
-@node Condition Code
-@section Condition Code Status
-@cindex condition code status
-
-Condition codes in GCC are represented as registers,
-which provides better schedulability for
-architectures that do have a condition code register, but on which
-most instructions do not affect it. The latter category includes
-most RISC machines.
-
-Implicit clobbering would pose a strong restriction on the placement of
-the definition and use of the condition code. In the past the definition
-and use were always adjacent. However, recent changes to support trapping
-arithmetic may result in the definition and user being in different blocks.
-Thus, there may be a @code{NOTE_INSN_BASIC_BLOCK} between them. Additionally,
-the definition may be the source of exception handling edges.
-
-These restrictions can prevent important
-optimizations on some machines. For example, on the IBM RS/6000, there
-is a delay for taken branches unless the condition code register is set
-three instructions earlier than the conditional branch. The instruction
-scheduler cannot perform this optimization if it is not permitted to
-separate the definition and use of the condition code register.
-
-If there is a specific
-condition code register in the machine, use a hard register. If the
-condition code or comparison result can be placed in any general register,
-or if there are multiple condition registers, use a pseudo register.
-Registers used to store the condition code value will usually have a mode
-that is in class @code{MODE_CC}.
-
-Alternatively, you can use @code{BImode} if the comparison operator is
-specified already in the compare instruction. In this case, you are not
-interested in most macros in this section.
-
-@menu
-* MODE_CC Condition Codes:: Modern representation of condition codes.
-@end menu
-
-@node MODE_CC Condition Codes
-@subsection Representation of condition codes using registers
-@findex CCmode
-@findex MODE_CC
-
-@defmac SELECT_CC_MODE (@var{op}, @var{x}, @var{y})
-On many machines, the condition code may be produced by other instructions
-than compares, for example the branch can use directly the condition
-code set by a subtract instruction. However, on some machines
-when the condition code is set this way some bits (such as the overflow
-bit) are not set in the same way as a test instruction, so that a different
-branch instruction must be used for some conditional branches. When
-this happens, use the machine mode of the condition code register to
-record different formats of the condition code register. Modes can
-also be used to record which compare instruction (e.g.@: a signed or an
-unsigned comparison) produced the condition codes.
-
-If other modes than @code{CCmode} are required, add them to
-@file{@var{machine}-modes.def} and define @code{SELECT_CC_MODE} to choose
-a mode given an operand of a compare. This is needed because the modes
-have to be chosen not only during RTL generation but also, for example,
-by instruction combination. The result of @code{SELECT_CC_MODE} should
-be consistent with the mode used in the patterns; for example to support
-the case of the add on the SPARC discussed above, we have the pattern
-
-@smallexample
-(define_insn ""
- [(set (reg:CCNZ 0)
- (compare:CCNZ
- (plus:SI (match_operand:SI 0 "register_operand" "%r")
- (match_operand:SI 1 "arith_operand" "rI"))
- (const_int 0)))]
- ""
- "@dots{}")
-@end smallexample
-
-@noindent
-together with a @code{SELECT_CC_MODE} that returns @code{CCNZmode}
-for comparisons whose argument is a @code{plus}:
-
-@smallexample
-#define SELECT_CC_MODE(OP,X,Y) \
- (GET_MODE_CLASS (GET_MODE (X)) == MODE_FLOAT \
- ? ((OP == LT || OP == LE || OP == GT || OP == GE) \
- ? CCFPEmode : CCFPmode) \
- : ((GET_CODE (X) == PLUS || GET_CODE (X) == MINUS \
- || GET_CODE (X) == NEG || GET_CODE (x) == ASHIFT) \
- ? CCNZmode : CCmode))
-@end smallexample
-
-Another reason to use modes is to retain information on which operands
-were used by the comparison; see @code{REVERSIBLE_CC_MODE} later in
-this section.
-
-You should define this macro if and only if you define extra CC modes
-in @file{@var{machine}-modes.def}.
-@end defmac
-
-@hook TARGET_CANONICALIZE_COMPARISON
-
-@defmac REVERSIBLE_CC_MODE (@var{mode})
-A C expression whose value is one if it is always safe to reverse a
-comparison whose mode is @var{mode}. If @code{SELECT_CC_MODE}
-can ever return @var{mode} for a floating-point inequality comparison,
-then @code{REVERSIBLE_CC_MODE (@var{mode})} must be zero.
-
-You need not define this macro if it would always returns zero or if the
-floating-point format is anything other than @code{IEEE_FLOAT_FORMAT}.
-For example, here is the definition used on the SPARC, where floating-point
-inequality comparisons are given either @code{CCFPEmode} or @code{CCFPmode}:
-
-@smallexample
-#define REVERSIBLE_CC_MODE(MODE) \
- ((MODE) != CCFPEmode && (MODE) != CCFPmode)
-@end smallexample
-@end defmac
-
-@defmac REVERSE_CONDITION (@var{code}, @var{mode})
-A C expression whose value is reversed condition code of the @var{code} for
-comparison done in CC_MODE @var{mode}. The macro is used only in case
-@code{REVERSIBLE_CC_MODE (@var{mode})} is nonzero. Define this macro in case
-machine has some non-standard way how to reverse certain conditionals. For
-instance in case all floating point conditions are non-trapping, compiler may
-freely convert unordered compares to ordered ones. Then definition may look
-like:
-
-@smallexample
-#define REVERSE_CONDITION(CODE, MODE) \
- ((MODE) != CCFPmode ? reverse_condition (CODE) \
- : reverse_condition_maybe_unordered (CODE))
-@end smallexample
-@end defmac
-
-@hook TARGET_FIXED_CONDITION_CODE_REGS
-
-@hook TARGET_CC_MODES_COMPATIBLE
-
-@hook TARGET_FLAGS_REGNUM
-
-@node Costs
-@section Describing Relative Costs of Operations
-@cindex costs of instructions
-@cindex relative costs
-@cindex speed of instructions
-
-These macros let you describe the relative speed of various operations
-on the target machine.
-
-@defmac REGISTER_MOVE_COST (@var{mode}, @var{from}, @var{to})
-A C expression for the cost of moving data of mode @var{mode} from a
-register in class @var{from} to one in class @var{to}. The classes are
-expressed using the enumeration values such as @code{GENERAL_REGS}. A
-value of 2 is the default; other values are interpreted relative to
-that.
-
-It is not required that the cost always equal 2 when @var{from} is the
-same as @var{to}; on some machines it is expensive to move between
-registers if they are not general registers.
-
-If reload sees an insn consisting of a single @code{set} between two
-hard registers, and if @code{REGISTER_MOVE_COST} applied to their
-classes returns a value of 2, reload does not check to ensure that the
-constraints of the insn are met. Setting a cost of other than 2 will
-allow reload to verify that the constraints are met. You should do this
-if the @samp{mov@var{m}} pattern's constraints do not allow such copying.
-
-These macros are obsolete, new ports should use the target hook
-@code{TARGET_REGISTER_MOVE_COST} instead.
-@end defmac
-
-@hook TARGET_REGISTER_MOVE_COST
-
-@defmac MEMORY_MOVE_COST (@var{mode}, @var{class}, @var{in})
-A C expression for the cost of moving data of mode @var{mode} between a
-register of class @var{class} and memory; @var{in} is zero if the value
-is to be written to memory, nonzero if it is to be read in. This cost
-is relative to those in @code{REGISTER_MOVE_COST}. If moving between
-registers and memory is more expensive than between two registers, you
-should define this macro to express the relative cost.
-
-If you do not define this macro, GCC uses a default cost of 4 plus
-the cost of copying via a secondary reload register, if one is
-needed. If your machine requires a secondary reload register to copy
-between memory and a register of @var{class} but the reload mechanism is
-more complex than copying via an intermediate, define this macro to
-reflect the actual cost of the move.
-
-GCC defines the function @code{memory_move_secondary_cost} if
-secondary reloads are needed. It computes the costs due to copying via
-a secondary register. If your machine copies from memory using a
-secondary register in the conventional way but the default base value of
-4 is not correct for your machine, define this macro to add some other
-value to the result of that function. The arguments to that function
-are the same as to this macro.
-
-These macros are obsolete, new ports should use the target hook
-@code{TARGET_MEMORY_MOVE_COST} instead.
-@end defmac
-
-@hook TARGET_MEMORY_MOVE_COST
-
-@defmac BRANCH_COST (@var{speed_p}, @var{predictable_p})
-A C expression for the cost of a branch instruction. A value of 1 is
-the default; other values are interpreted relative to that. Parameter
-@var{speed_p} is true when the branch in question should be optimized
-for speed. When it is false, @code{BRANCH_COST} should return a value
-optimal for code size rather than performance. @var{predictable_p} is
-true for well-predicted branches. On many architectures the
-@code{BRANCH_COST} can be reduced then.
-@end defmac
-
-Here are additional macros which do not specify precise relative costs,
-but only that certain actions are more expensive than GCC would
-ordinarily expect.
-
-@defmac SLOW_BYTE_ACCESS
-Define this macro as a C expression which is nonzero if accessing less
-than a word of memory (i.e.@: a @code{char} or a @code{short}) is no
-faster than accessing a word of memory, i.e., if such access
-require more than one instruction or if there is no difference in cost
-between byte and (aligned) word loads.
-
-When this macro is not defined, the compiler will access a field by
-finding the smallest containing object; when it is defined, a fullword
-load will be used if alignment permits. Unless bytes accesses are
-faster than word accesses, using word accesses is preferable since it
-may eliminate subsequent memory access if subsequent accesses occur to
-other fields in the same word of the structure, but to different bytes.
-@end defmac
-
-@hook TARGET_SLOW_UNALIGNED_ACCESS
-
-@defmac MOVE_RATIO (@var{speed})
-The threshold of number of scalar memory-to-memory move insns, @emph{below}
-which a sequence of insns should be generated instead of a
-string move insn or a library call. Increasing the value will always
-make code faster, but eventually incurs high cost in increased code size.
-
-Note that on machines where the corresponding move insn is a
-@code{define_expand} that emits a sequence of insns, this macro counts
-the number of such sequences.
-
-The parameter @var{speed} is true if the code is currently being
-optimized for speed rather than size.
-
-If you don't define this, a reasonable default is used.
-@end defmac
-
-@hook TARGET_USE_BY_PIECES_INFRASTRUCTURE_P
-
-@hook TARGET_OVERLAP_OP_BY_PIECES_P
-
-@hook TARGET_COMPARE_BY_PIECES_BRANCH_RATIO
-
-@defmac MOVE_MAX_PIECES
-A C expression used by @code{move_by_pieces} to determine the largest unit
-a load or store used to copy memory is. Defaults to @code{MOVE_MAX}.
-@end defmac
-
-@defmac STORE_MAX_PIECES
-A C expression used by @code{store_by_pieces} to determine the largest unit
-a store used to memory is. Defaults to @code{MOVE_MAX_PIECES}, or two times
-the size of @code{HOST_WIDE_INT}, whichever is smaller.
-@end defmac
-
-@defmac COMPARE_MAX_PIECES
-A C expression used by @code{compare_by_pieces} to determine the largest unit
-a load or store used to compare memory is. Defaults to
-@code{MOVE_MAX_PIECES}.
-@end defmac
-
-@defmac CLEAR_RATIO (@var{speed})
-The threshold of number of scalar move insns, @emph{below} which a sequence
-of insns should be generated to clear memory instead of a string clear insn
-or a library call. Increasing the value will always make code faster, but
-eventually incurs high cost in increased code size.
-
-The parameter @var{speed} is true if the code is currently being
-optimized for speed rather than size.
-
-If you don't define this, a reasonable default is used.
-@end defmac
-
-@defmac SET_RATIO (@var{speed})
-The threshold of number of scalar move insns, @emph{below} which a sequence
-of insns should be generated to set memory to a constant value, instead of
-a block set insn or a library call.
-Increasing the value will always make code faster, but
-eventually incurs high cost in increased code size.
-
-The parameter @var{speed} is true if the code is currently being
-optimized for speed rather than size.
-
-If you don't define this, it defaults to the value of @code{MOVE_RATIO}.
-@end defmac
-
-@defmac USE_LOAD_POST_INCREMENT (@var{mode})
-A C expression used to determine whether a load postincrement is a good
-thing to use for a given mode. Defaults to the value of
-@code{HAVE_POST_INCREMENT}.
-@end defmac
-
-@defmac USE_LOAD_POST_DECREMENT (@var{mode})
-A C expression used to determine whether a load postdecrement is a good
-thing to use for a given mode. Defaults to the value of
-@code{HAVE_POST_DECREMENT}.
-@end defmac
-
-@defmac USE_LOAD_PRE_INCREMENT (@var{mode})
-A C expression used to determine whether a load preincrement is a good
-thing to use for a given mode. Defaults to the value of
-@code{HAVE_PRE_INCREMENT}.
-@end defmac
-
-@defmac USE_LOAD_PRE_DECREMENT (@var{mode})
-A C expression used to determine whether a load predecrement is a good
-thing to use for a given mode. Defaults to the value of
-@code{HAVE_PRE_DECREMENT}.
-@end defmac
-
-@defmac USE_STORE_POST_INCREMENT (@var{mode})
-A C expression used to determine whether a store postincrement is a good
-thing to use for a given mode. Defaults to the value of
-@code{HAVE_POST_INCREMENT}.
-@end defmac
-
-@defmac USE_STORE_POST_DECREMENT (@var{mode})
-A C expression used to determine whether a store postdecrement is a good
-thing to use for a given mode. Defaults to the value of
-@code{HAVE_POST_DECREMENT}.
-@end defmac
-
-@defmac USE_STORE_PRE_INCREMENT (@var{mode})
-This macro is used to determine whether a store preincrement is a good
-thing to use for a given mode. Defaults to the value of
-@code{HAVE_PRE_INCREMENT}.
-@end defmac
-
-@defmac USE_STORE_PRE_DECREMENT (@var{mode})
-This macro is used to determine whether a store predecrement is a good
-thing to use for a given mode. Defaults to the value of
-@code{HAVE_PRE_DECREMENT}.
-@end defmac
-
-@defmac NO_FUNCTION_CSE
-Define this macro to be true if it is as good or better to call a constant
-function address than to call an address kept in a register.
-@end defmac
-
-@defmac LOGICAL_OP_NON_SHORT_CIRCUIT
-Define this macro if a non-short-circuit operation produced by
-@samp{fold_range_test ()} is optimal. This macro defaults to true if
-@code{BRANCH_COST} is greater than or equal to the value 2.
-@end defmac
-
-@hook TARGET_OPTAB_SUPPORTED_P
-
-@hook TARGET_RTX_COSTS
-
-@hook TARGET_ADDRESS_COST
-
-@hook TARGET_INSN_COST
-
-@hook TARGET_MAX_NOCE_IFCVT_SEQ_COST
-
-@hook TARGET_NOCE_CONVERSION_PROFITABLE_P
-
-@hook TARGET_NEW_ADDRESS_PROFITABLE_P
-
-@hook TARGET_NO_SPECULATION_IN_DELAY_SLOTS_P
-
-@hook TARGET_ESTIMATED_POLY_VALUE
-
-@node Scheduling
-@section Adjusting the Instruction Scheduler
-
-The instruction scheduler may need a fair amount of machine-specific
-adjustment in order to produce good code. GCC provides several target
-hooks for this purpose. It is usually enough to define just a few of
-them: try the first ones in this list first.
-
-@hook TARGET_SCHED_ISSUE_RATE
-
-@hook TARGET_SCHED_VARIABLE_ISSUE
-
-@hook TARGET_SCHED_ADJUST_COST
-
-@hook TARGET_SCHED_ADJUST_PRIORITY
-
-@hook TARGET_SCHED_REORDER
-
-@hook TARGET_SCHED_REORDER2
-
-@hook TARGET_SCHED_MACRO_FUSION_P
-
-@hook TARGET_SCHED_MACRO_FUSION_PAIR_P
-
-@hook TARGET_SCHED_DEPENDENCIES_EVALUATION_HOOK
-
-@hook TARGET_SCHED_INIT
-
-@hook TARGET_SCHED_FINISH
-
-@hook TARGET_SCHED_INIT_GLOBAL
-
-@hook TARGET_SCHED_FINISH_GLOBAL
-
-@hook TARGET_SCHED_DFA_PRE_CYCLE_INSN
-
-@hook TARGET_SCHED_INIT_DFA_PRE_CYCLE_INSN
-
-@hook TARGET_SCHED_DFA_POST_CYCLE_INSN
-
-@hook TARGET_SCHED_INIT_DFA_POST_CYCLE_INSN
-
-@hook TARGET_SCHED_DFA_PRE_ADVANCE_CYCLE
-
-@hook TARGET_SCHED_DFA_POST_ADVANCE_CYCLE
-
-@hook TARGET_SCHED_FIRST_CYCLE_MULTIPASS_DFA_LOOKAHEAD
-
-@hook TARGET_SCHED_FIRST_CYCLE_MULTIPASS_DFA_LOOKAHEAD_GUARD
-
-@hook TARGET_SCHED_FIRST_CYCLE_MULTIPASS_BEGIN
-
-@hook TARGET_SCHED_FIRST_CYCLE_MULTIPASS_ISSUE
-
-@hook TARGET_SCHED_FIRST_CYCLE_MULTIPASS_BACKTRACK
-
-@hook TARGET_SCHED_FIRST_CYCLE_MULTIPASS_END
-
-@hook TARGET_SCHED_FIRST_CYCLE_MULTIPASS_INIT
-
-@hook TARGET_SCHED_FIRST_CYCLE_MULTIPASS_FINI
-
-@hook TARGET_SCHED_DFA_NEW_CYCLE
-
-@hook TARGET_SCHED_IS_COSTLY_DEPENDENCE
-
-@hook TARGET_SCHED_H_I_D_EXTENDED
-
-@hook TARGET_SCHED_ALLOC_SCHED_CONTEXT
-
-@hook TARGET_SCHED_INIT_SCHED_CONTEXT
-
-@hook TARGET_SCHED_SET_SCHED_CONTEXT
-
-@hook TARGET_SCHED_CLEAR_SCHED_CONTEXT
-
-@hook TARGET_SCHED_FREE_SCHED_CONTEXT
-
-@hook TARGET_SCHED_SPECULATE_INSN
-
-@hook TARGET_SCHED_NEEDS_BLOCK_P
-
-@hook TARGET_SCHED_GEN_SPEC_CHECK
-
-@hook TARGET_SCHED_SET_SCHED_FLAGS
-
-@hook TARGET_SCHED_CAN_SPECULATE_INSN
-
-@hook TARGET_SCHED_SMS_RES_MII
-
-@hook TARGET_SCHED_DISPATCH
-
-@hook TARGET_SCHED_DISPATCH_DO
-
-@hook TARGET_SCHED_EXPOSED_PIPELINE
-
-@hook TARGET_SCHED_REASSOCIATION_WIDTH
-
-@hook TARGET_SCHED_FUSION_PRIORITY
-
-@hook TARGET_EXPAND_DIVMOD_LIBFUNC
-
-@node Sections
-@section Dividing the Output into Sections (Texts, Data, @dots{})
-@c the above section title is WAY too long. maybe cut the part between
-@c the (...)? --mew 10feb93
-
-An object file is divided into sections containing different types of
-data. In the most common case, there are three sections: the @dfn{text
-section}, which holds instructions and read-only data; the @dfn{data
-section}, which holds initialized writable data; and the @dfn{bss
-section}, which holds uninitialized data. Some systems have other kinds
-of sections.
-
-@file{varasm.cc} provides several well-known sections, such as
-@code{text_section}, @code{data_section} and @code{bss_section}.
-The normal way of controlling a @code{@var{foo}_section} variable
-is to define the associated @code{@var{FOO}_SECTION_ASM_OP} macro,
-as described below. The macros are only read once, when @file{varasm.cc}
-initializes itself, so their values must be run-time constants.
-They may however depend on command-line flags.
-
-@emph{Note:} Some run-time files, such @file{crtstuff.c}, also make
-use of the @code{@var{FOO}_SECTION_ASM_OP} macros, and expect them
-to be string literals.
-
-Some assemblers require a different string to be written every time a
-section is selected. If your assembler falls into this category, you
-should define the @code{TARGET_ASM_INIT_SECTIONS} hook and use
-@code{get_unnamed_section} to set up the sections.
-
-You must always create a @code{text_section}, either by defining
-@code{TEXT_SECTION_ASM_OP} or by initializing @code{text_section}
-in @code{TARGET_ASM_INIT_SECTIONS}. The same is true of
-@code{data_section} and @code{DATA_SECTION_ASM_OP}. If you do not
-create a distinct @code{readonly_data_section}, the default is to
-reuse @code{text_section}.
-
-All the other @file{varasm.cc} sections are optional, and are null
-if the target does not provide them.
-
-@defmac TEXT_SECTION_ASM_OP
-A C expression whose value is a string, including spacing, containing the
-assembler operation that should precede instructions and read-only data.
-Normally @code{"\t.text"} is right.
-@end defmac
-
-@defmac HOT_TEXT_SECTION_NAME
-If defined, a C string constant for the name of the section containing most
-frequently executed functions of the program. If not defined, GCC will provide
-a default definition if the target supports named sections.
-@end defmac
-
-@defmac UNLIKELY_EXECUTED_TEXT_SECTION_NAME
-If defined, a C string constant for the name of the section containing unlikely
-executed functions in the program.
-@end defmac
-
-@defmac DATA_SECTION_ASM_OP
-A C expression whose value is a string, including spacing, containing the
-assembler operation to identify the following data as writable initialized
-data. Normally @code{"\t.data"} is right.
-@end defmac
-
-@defmac SDATA_SECTION_ASM_OP
-If defined, a C expression whose value is a string, including spacing,
-containing the assembler operation to identify the following data as
-initialized, writable small data.
-@end defmac
-
-@defmac READONLY_DATA_SECTION_ASM_OP
-A C expression whose value is a string, including spacing, containing the
-assembler operation to identify the following data as read-only initialized
-data.
-@end defmac
-
-@defmac BSS_SECTION_ASM_OP
-If defined, a C expression whose value is a string, including spacing,
-containing the assembler operation to identify the following data as
-uninitialized global data. If not defined, and
-@code{ASM_OUTPUT_ALIGNED_BSS} not defined,
-uninitialized global data will be output in the data section if
-@option{-fno-common} is passed, otherwise @code{ASM_OUTPUT_COMMON} will be
-used.
-@end defmac
-
-@defmac SBSS_SECTION_ASM_OP
-If defined, a C expression whose value is a string, including spacing,
-containing the assembler operation to identify the following data as
-uninitialized, writable small data.
-@end defmac
-
-@defmac TLS_COMMON_ASM_OP
-If defined, a C expression whose value is a string containing the
-assembler operation to identify the following data as thread-local
-common data. The default is @code{".tls_common"}.
-@end defmac
-
-@defmac TLS_SECTION_ASM_FLAG
-If defined, a C expression whose value is a character constant
-containing the flag used to mark a section as a TLS section. The
-default is @code{'T'}.
-@end defmac
-
-@defmac INIT_SECTION_ASM_OP
-If defined, a C expression whose value is a string, including spacing,
-containing the assembler operation to identify the following data as
-initialization code. If not defined, GCC will assume such a section does
-not exist. This section has no corresponding @code{init_section}
-variable; it is used entirely in runtime code.
-@end defmac
-
-@defmac FINI_SECTION_ASM_OP
-If defined, a C expression whose value is a string, including spacing,
-containing the assembler operation to identify the following data as
-finalization code. If not defined, GCC will assume such a section does
-not exist. This section has no corresponding @code{fini_section}
-variable; it is used entirely in runtime code.
-@end defmac
-
-@defmac INIT_ARRAY_SECTION_ASM_OP
-If defined, a C expression whose value is a string, including spacing,
-containing the assembler operation to identify the following data as
-part of the @code{.init_array} (or equivalent) section. If not
-defined, GCC will assume such a section does not exist. Do not define
-both this macro and @code{INIT_SECTION_ASM_OP}.
-@end defmac
-
-@defmac FINI_ARRAY_SECTION_ASM_OP
-If defined, a C expression whose value is a string, including spacing,
-containing the assembler operation to identify the following data as
-part of the @code{.fini_array} (or equivalent) section. If not
-defined, GCC will assume such a section does not exist. Do not define
-both this macro and @code{FINI_SECTION_ASM_OP}.
-@end defmac
-
-@defmac MACH_DEP_SECTION_ASM_FLAG
-If defined, a C expression whose value is a character constant
-containing the flag used to mark a machine-dependent section. This
-corresponds to the @code{SECTION_MACH_DEP} section flag.
-@end defmac
-
-@defmac CRT_CALL_STATIC_FUNCTION (@var{section_op}, @var{function})
-If defined, an ASM statement that switches to a different section
-via @var{section_op}, calls @var{function}, and switches back to
-the text section. This is used in @file{crtstuff.c} if
-@code{INIT_SECTION_ASM_OP} or @code{FINI_SECTION_ASM_OP} to calls
-to initialization and finalization functions from the init and fini
-sections. By default, this macro uses a simple function call. Some
-ports need hand-crafted assembly code to avoid dependencies on
-registers initialized in the function prologue or to ensure that
-constant pools don't end up too far way in the text section.
-@end defmac
-
-@defmac TARGET_LIBGCC_SDATA_SECTION
-If defined, a string which names the section into which small
-variables defined in crtstuff and libgcc should go. This is useful
-when the target has options for optimizing access to small data, and
-you want the crtstuff and libgcc routines to be conservative in what
-they expect of your application yet liberal in what your application
-expects. For example, for targets with a @code{.sdata} section (like
-MIPS), you could compile crtstuff with @code{-G 0} so that it doesn't
-require small data support from your application, but use this macro
-to put small data into @code{.sdata} so that your application can
-access these variables whether it uses small data or not.
-@end defmac
-
-@defmac FORCE_CODE_SECTION_ALIGN
-If defined, an ASM statement that aligns a code section to some
-arbitrary boundary. This is used to force all fragments of the
-@code{.init} and @code{.fini} sections to have to same alignment
-and thus prevent the linker from having to add any padding.
-@end defmac
-
-@defmac JUMP_TABLES_IN_TEXT_SECTION
-Define this macro to be an expression with a nonzero value if jump
-tables (for @code{tablejump} insns) should be output in the text
-section, along with the assembler instructions. Otherwise, the
-readonly data section is used.
-
-This macro is irrelevant if there is no separate readonly data section.
-@end defmac
-
-@hook TARGET_ASM_INIT_SECTIONS
-
-@hook TARGET_ASM_RELOC_RW_MASK
-
-@hook TARGET_ASM_GENERATE_PIC_ADDR_DIFF_VEC
-
-@hook TARGET_ASM_SELECT_SECTION
-
-@defmac USE_SELECT_SECTION_FOR_FUNCTIONS
-Define this macro if you wish TARGET_ASM_SELECT_SECTION to be called
-for @code{FUNCTION_DECL}s as well as for variables and constants.
-
-In the case of a @code{FUNCTION_DECL}, @var{reloc} will be zero if the
-function has been determined to be likely to be called, and nonzero if
-it is unlikely to be called.
-@end defmac
-
-@hook TARGET_ASM_UNIQUE_SECTION
-
-@hook TARGET_ASM_FUNCTION_RODATA_SECTION
-
-@hook TARGET_ASM_MERGEABLE_RODATA_PREFIX
-
-@hook TARGET_ASM_TM_CLONE_TABLE_SECTION
-
-@hook TARGET_ASM_SELECT_RTX_SECTION
-
-@hook TARGET_MANGLE_DECL_ASSEMBLER_NAME
-
-@hook TARGET_ENCODE_SECTION_INFO
-
-@hook TARGET_STRIP_NAME_ENCODING
-
-@hook TARGET_IN_SMALL_DATA_P
-
-@hook TARGET_HAVE_SRODATA_SECTION
-
-@hook TARGET_PROFILE_BEFORE_PROLOGUE
-
-@hook TARGET_BINDS_LOCAL_P
-
-@hook TARGET_HAVE_TLS
-
-
-@node PIC
-@section Position Independent Code
-@cindex position independent code
-@cindex PIC
-
-This section describes macros that help implement generation of position
-independent code. Simply defining these macros is not enough to
-generate valid PIC; you must also add support to the hook
-@code{TARGET_LEGITIMATE_ADDRESS_P} and to the macro
-@code{PRINT_OPERAND_ADDRESS}, as well as @code{LEGITIMIZE_ADDRESS}. You
-must modify the definition of @samp{movsi} to do something appropriate
-when the source operand contains a symbolic address. You may also
-need to alter the handling of switch statements so that they use
-relative addresses.
-@c i rearranged the order of the macros above to try to force one of
-@c them to the next line, to eliminate an overfull hbox. --mew 10feb93
-
-@defmac PIC_OFFSET_TABLE_REGNUM
-The register number of the register used to address a table of static
-data addresses in memory. In some cases this register is defined by a
-processor's ``application binary interface'' (ABI)@. When this macro
-is defined, RTL is generated for this register once, as with the stack
-pointer and frame pointer registers. If this macro is not defined, it
-is up to the machine-dependent files to allocate such a register (if
-necessary). Note that this register must be fixed when in use (e.g.@:
-when @code{flag_pic} is true).
-@end defmac
-
-@defmac PIC_OFFSET_TABLE_REG_CALL_CLOBBERED
-A C expression that is nonzero if the register defined by
-@code{PIC_OFFSET_TABLE_REGNUM} is clobbered by calls. If not defined,
-the default is zero. Do not define
-this macro if @code{PIC_OFFSET_TABLE_REGNUM} is not defined.
-@end defmac
-
-@defmac LEGITIMATE_PIC_OPERAND_P (@var{x})
-A C expression that is nonzero if @var{x} is a legitimate immediate
-operand on the target machine when generating position independent code.
-You can assume that @var{x} satisfies @code{CONSTANT_P}, so you need not
-check this. You can also assume @var{flag_pic} is true, so you need not
-check it either. You need not define this macro if all constants
-(including @code{SYMBOL_REF}) can be immediate operands when generating
-position independent code.
-@end defmac
-
-@node Assembler Format
-@section Defining the Output Assembler Language
-
-This section describes macros whose principal purpose is to describe how
-to write instructions in assembler language---rather than what the
-instructions do.
-
-@menu
-* File Framework:: Structural information for the assembler file.
-* Data Output:: Output of constants (numbers, strings, addresses).
-* Uninitialized Data:: Output of uninitialized variables.
-* Label Output:: Output and generation of labels.
-* Initialization:: General principles of initialization
- and termination routines.
-* Macros for Initialization::
- Specific macros that control the handling of
- initialization and termination routines.
-* Instruction Output:: Output of actual instructions.
-* Dispatch Tables:: Output of jump tables.
-* Exception Region Output:: Output of exception region code.
-* Alignment Output:: Pseudo ops for alignment and skipping data.
-@end menu
-
-@node File Framework
-@subsection The Overall Framework of an Assembler File
-@cindex assembler format
-@cindex output of assembler code
-
-@c prevent bad page break with this line
-This describes the overall framework of an assembly file.
-
-@findex default_file_start
-@hook TARGET_ASM_FILE_START
-
-@hook TARGET_ASM_FILE_START_APP_OFF
-
-@hook TARGET_ASM_FILE_START_FILE_DIRECTIVE
-
-@hook TARGET_ASM_FILE_END
-
-@deftypefun void file_end_indicate_exec_stack ()
-Some systems use a common convention, the @samp{.note.GNU-stack}
-special section, to indicate whether or not an object file relies on
-the stack being executable. If your system uses this convention, you
-should define @code{TARGET_ASM_FILE_END} to this function. If you
-need to do other things in that hook, have your hook function call
-this function.
-@end deftypefun
-
-@hook TARGET_ASM_LTO_START
-
-@hook TARGET_ASM_LTO_END
-
-@hook TARGET_ASM_CODE_END
-
-@defmac ASM_COMMENT_START
-A C string constant describing how to begin a comment in the target
-assembler language. The compiler assumes that the comment will end at
-the end of the line.
-@end defmac
-
-@defmac ASM_APP_ON
-A C string constant for text to be output before each @code{asm}
-statement or group of consecutive ones. Normally this is
-@code{"#APP"}, which is a comment that has no effect on most
-assemblers but tells the GNU assembler that it must check the lines
-that follow for all valid assembler constructs.
-@end defmac
-
-@defmac ASM_APP_OFF
-A C string constant for text to be output after each @code{asm}
-statement or group of consecutive ones. Normally this is
-@code{"#NO_APP"}, which tells the GNU assembler to resume making the
-time-saving assumptions that are valid for ordinary compiler output.
-@end defmac
-
-@defmac ASM_OUTPUT_SOURCE_FILENAME (@var{stream}, @var{name})
-A C statement to output COFF information or DWARF debugging information
-which indicates that filename @var{name} is the current source file to
-the stdio stream @var{stream}.
-
-This macro need not be defined if the standard form of output
-for the file format in use is appropriate.
-@end defmac
-
-@hook TARGET_ASM_OUTPUT_SOURCE_FILENAME
-
-@hook TARGET_ASM_OUTPUT_IDENT
-
-@defmac OUTPUT_QUOTED_STRING (@var{stream}, @var{string})
-A C statement to output the string @var{string} to the stdio stream
-@var{stream}. If you do not call the function @code{output_quoted_string}
-in your config files, GCC will only call it to output filenames to
-the assembler source. So you can use it to canonicalize the format
-of the filename using this macro.
-@end defmac
-
-@hook TARGET_ASM_NAMED_SECTION
-
-@hook TARGET_ASM_ELF_FLAGS_NUMERIC
-
-@hook TARGET_ASM_FUNCTION_SECTION
-
-@hook TARGET_ASM_FUNCTION_SWITCHED_TEXT_SECTIONS
-
-@hook TARGET_HAVE_NAMED_SECTIONS
-This flag is true if the target supports @code{TARGET_ASM_NAMED_SECTION}.
-It must not be modified by command-line option processing.
-@end deftypevr
-
-@anchor{TARGET_HAVE_SWITCHABLE_BSS_SECTIONS}
-@hook TARGET_HAVE_SWITCHABLE_BSS_SECTIONS
-
-@hook TARGET_SECTION_TYPE_FLAGS
-
-@hook TARGET_ASM_RECORD_GCC_SWITCHES
-
-@hook TARGET_ASM_RECORD_GCC_SWITCHES_SECTION
-
-@need 2000
-@node Data Output
-@subsection Output of Data
-
-
-@hook TARGET_ASM_BYTE_OP
-
-@hook TARGET_ASM_INTEGER
-
-@hook TARGET_ASM_DECL_END
-
-@hook TARGET_ASM_OUTPUT_ADDR_CONST_EXTRA
-
-@defmac ASM_OUTPUT_ASCII (@var{stream}, @var{ptr}, @var{len})
-A C statement to output to the stdio stream @var{stream} an assembler
-instruction to assemble a string constant containing the @var{len}
-bytes at @var{ptr}. @var{ptr} will be a C expression of type
-@code{char *} and @var{len} a C expression of type @code{int}.
-
-If the assembler has a @code{.ascii} pseudo-op as found in the
-Berkeley Unix assembler, do not define the macro
-@code{ASM_OUTPUT_ASCII}.
-@end defmac
-
-@defmac ASM_OUTPUT_FDESC (@var{stream}, @var{decl}, @var{n})
-A C statement to output word @var{n} of a function descriptor for
-@var{decl}. This must be defined if @code{TARGET_VTABLE_USES_DESCRIPTORS}
-is defined, and is otherwise unused.
-@end defmac
-
-@defmac CONSTANT_POOL_BEFORE_FUNCTION
-You may define this macro as a C expression. You should define the
-expression to have a nonzero value if GCC should output the constant
-pool for a function before the code for the function, or a zero value if
-GCC should output the constant pool after the function. If you do
-not define this macro, the usual case, GCC will output the constant
-pool before the function.
-@end defmac
-
-@defmac ASM_OUTPUT_POOL_PROLOGUE (@var{file}, @var{funname}, @var{fundecl}, @var{size})
-A C statement to output assembler commands to define the start of the
-constant pool for a function. @var{funname} is a string giving
-the name of the function. Should the return type of the function
-be required, it can be obtained via @var{fundecl}. @var{size}
-is the size, in bytes, of the constant pool that will be written
-immediately after this call.
-
-If no constant-pool prefix is required, the usual case, this macro need
-not be defined.
-@end defmac
-
-@defmac ASM_OUTPUT_SPECIAL_POOL_ENTRY (@var{file}, @var{x}, @var{mode}, @var{align}, @var{labelno}, @var{jumpto})
-A C statement (with or without semicolon) to output a constant in the
-constant pool, if it needs special treatment. (This macro need not do
-anything for RTL expressions that can be output normally.)
-
-The argument @var{file} is the standard I/O stream to output the
-assembler code on. @var{x} is the RTL expression for the constant to
-output, and @var{mode} is the machine mode (in case @var{x} is a
-@samp{const_int}). @var{align} is the required alignment for the value
-@var{x}; you should output an assembler directive to force this much
-alignment.
-
-The argument @var{labelno} is a number to use in an internal label for
-the address of this pool entry. The definition of this macro is
-responsible for outputting the label definition at the proper place.
-Here is how to do this:
-
-@smallexample
-@code{(*targetm.asm_out.internal_label)} (@var{file}, "LC", @var{labelno});
-@end smallexample
-
-When you output a pool entry specially, you should end with a
-@code{goto} to the label @var{jumpto}. This will prevent the same pool
-entry from being output a second time in the usual manner.
-
-You need not define this macro if it would do nothing.
-@end defmac
-
-@defmac ASM_OUTPUT_POOL_EPILOGUE (@var{file} @var{funname} @var{fundecl} @var{size})
-A C statement to output assembler commands to at the end of the constant
-pool for a function. @var{funname} is a string giving the name of the
-function. Should the return type of the function be required, you can
-obtain it via @var{fundecl}. @var{size} is the size, in bytes, of the
-constant pool that GCC wrote immediately before this call.
-
-If no constant-pool epilogue is required, the usual case, you need not
-define this macro.
-@end defmac
-
-@defmac IS_ASM_LOGICAL_LINE_SEPARATOR (@var{C}, @var{STR})
-Define this macro as a C expression which is nonzero if @var{C} is
-used as a logical line separator by the assembler. @var{STR} points
-to the position in the string where @var{C} was found; this can be used if
-a line separator uses multiple characters.
-
-If you do not define this macro, the default is that only
-the character @samp{;} is treated as a logical line separator.
-@end defmac
-
-@hook TARGET_ASM_OPEN_PAREN
-
-These macros are provided by @file{real.h} for writing the definitions
-of @code{ASM_OUTPUT_DOUBLE} and the like:
-
-@defmac REAL_VALUE_TO_TARGET_SINGLE (@var{x}, @var{l})
-@defmacx REAL_VALUE_TO_TARGET_DOUBLE (@var{x}, @var{l})
-@defmacx REAL_VALUE_TO_TARGET_LONG_DOUBLE (@var{x}, @var{l})
-@defmacx REAL_VALUE_TO_TARGET_DECIMAL32 (@var{x}, @var{l})
-@defmacx REAL_VALUE_TO_TARGET_DECIMAL64 (@var{x}, @var{l})
-@defmacx REAL_VALUE_TO_TARGET_DECIMAL128 (@var{x}, @var{l})
-These translate @var{x}, of type @code{REAL_VALUE_TYPE}, to the
-target's floating point representation, and store its bit pattern in
-the variable @var{l}. For @code{REAL_VALUE_TO_TARGET_SINGLE} and
-@code{REAL_VALUE_TO_TARGET_DECIMAL32}, this variable should be a
-simple @code{long int}. For the others, it should be an array of
-@code{long int}. The number of elements in this array is determined
-by the size of the desired target floating point data type: 32 bits of
-it go in each @code{long int} array element. Each array element holds
-32 bits of the result, even if @code{long int} is wider than 32 bits
-on the host machine.
-
-The array element values are designed so that you can print them out
-using @code{fprintf} in the order they should appear in the target
-machine's memory.
-@end defmac
-
-@node Uninitialized Data
-@subsection Output of Uninitialized Variables
-
-Each of the macros in this section is used to do the whole job of
-outputting a single uninitialized variable.
-
-@defmac ASM_OUTPUT_COMMON (@var{stream}, @var{name}, @var{size}, @var{rounded})
-A C statement (sans semicolon) to output to the stdio stream
-@var{stream} the assembler definition of a common-label named
-@var{name} whose size is @var{size} bytes. The variable @var{rounded}
-is the size rounded up to whatever alignment the caller wants. It is
-possible that @var{size} may be zero, for instance if a struct with no
-other member than a zero-length array is defined. In this case, the
-backend must output a symbol definition that allocates at least one
-byte, both so that the address of the resulting object does not compare
-equal to any other, and because some object formats cannot even express
-the concept of a zero-sized common symbol, as that is how they represent
-an ordinary undefined external.
-
-Use the expression @code{assemble_name (@var{stream}, @var{name})} to
-output the name itself; before and after that, output the additional
-assembler syntax for defining the name, and a newline.
-
-This macro controls how the assembler definitions of uninitialized
-common global variables are output.
-@end defmac
-
-@defmac ASM_OUTPUT_ALIGNED_COMMON (@var{stream}, @var{name}, @var{size}, @var{alignment})
-Like @code{ASM_OUTPUT_COMMON} except takes the required alignment as a
-separate, explicit argument. If you define this macro, it is used in
-place of @code{ASM_OUTPUT_COMMON}, and gives you more flexibility in
-handling the required alignment of the variable. The alignment is specified
-as the number of bits.
-@end defmac
-
-@defmac ASM_OUTPUT_ALIGNED_DECL_COMMON (@var{stream}, @var{decl}, @var{name}, @var{size}, @var{alignment})
-Like @code{ASM_OUTPUT_ALIGNED_COMMON} except that @var{decl} of the
-variable to be output, if there is one, or @code{NULL_TREE} if there
-is no corresponding variable. If you define this macro, GCC will use it
-in place of both @code{ASM_OUTPUT_COMMON} and
-@code{ASM_OUTPUT_ALIGNED_COMMON}. Define this macro when you need to see
-the variable's decl in order to chose what to output.
-@end defmac
-
-@defmac ASM_OUTPUT_ALIGNED_BSS (@var{stream}, @var{decl}, @var{name}, @var{size}, @var{alignment})
-A C statement (sans semicolon) to output to the stdio stream
-@var{stream} the assembler definition of uninitialized global @var{decl} named
-@var{name} whose size is @var{size} bytes. The variable @var{alignment}
-is the alignment specified as the number of bits.
-
-Try to use function @code{asm_output_aligned_bss} defined in file
-@file{varasm.cc} when defining this macro. If unable, use the expression
-@code{assemble_name (@var{stream}, @var{name})} to output the name itself;
-before and after that, output the additional assembler syntax for defining
-the name, and a newline.
-
-There are two ways of handling global BSS@. One is to define this macro.
-The other is to have @code{TARGET_ASM_SELECT_SECTION} return a
-switchable BSS section (@pxref{TARGET_HAVE_SWITCHABLE_BSS_SECTIONS}).
-You do not need to do both.
-
-Some languages do not have @code{common} data, and require a
-non-common form of global BSS in order to handle uninitialized globals
-efficiently. C++ is one example of this. However, if the target does
-not support global BSS, the front end may choose to make globals
-common in order to save space in the object file.
-@end defmac
-
-@defmac ASM_OUTPUT_LOCAL (@var{stream}, @var{name}, @var{size}, @var{rounded})
-A C statement (sans semicolon) to output to the stdio stream
-@var{stream} the assembler definition of a local-common-label named
-@var{name} whose size is @var{size} bytes. The variable @var{rounded}
-is the size rounded up to whatever alignment the caller wants.
-
-Use the expression @code{assemble_name (@var{stream}, @var{name})} to
-output the name itself; before and after that, output the additional
-assembler syntax for defining the name, and a newline.
-
-This macro controls how the assembler definitions of uninitialized
-static variables are output.
-@end defmac
-
-@defmac ASM_OUTPUT_ALIGNED_LOCAL (@var{stream}, @var{name}, @var{size}, @var{alignment})
-Like @code{ASM_OUTPUT_LOCAL} except takes the required alignment as a
-separate, explicit argument. If you define this macro, it is used in
-place of @code{ASM_OUTPUT_LOCAL}, and gives you more flexibility in
-handling the required alignment of the variable. The alignment is specified
-as the number of bits.
-@end defmac
-
-@defmac ASM_OUTPUT_ALIGNED_DECL_LOCAL (@var{stream}, @var{decl}, @var{name}, @var{size}, @var{alignment})
-Like @code{ASM_OUTPUT_ALIGNED_LOCAL} except that @var{decl} of the
-variable to be output, if there is one, or @code{NULL_TREE} if there
-is no corresponding variable. If you define this macro, GCC will use it
-in place of both @code{ASM_OUTPUT_LOCAL} and
-@code{ASM_OUTPUT_ALIGNED_LOCAL}. Define this macro when you need to see
-the variable's decl in order to chose what to output.
-@end defmac
-
-@node Label Output
-@subsection Output and Generation of Labels
-
-@c prevent bad page break with this line
-This is about outputting labels.
-
-@findex assemble_name
-@defmac ASM_OUTPUT_LABEL (@var{stream}, @var{name})
-A C statement (sans semicolon) to output to the stdio stream
-@var{stream} the assembler definition of a label named @var{name}.
-Use the expression @code{assemble_name (@var{stream}, @var{name})} to
-output the name itself; before and after that, output the additional
-assembler syntax for defining the name, and a newline. A default
-definition of this macro is provided which is correct for most systems.
-@end defmac
-
-@defmac ASM_OUTPUT_FUNCTION_LABEL (@var{stream}, @var{name}, @var{decl})
-A C statement (sans semicolon) to output to the stdio stream
-@var{stream} the assembler definition of a label named @var{name} of
-a function.
-Use the expression @code{assemble_name (@var{stream}, @var{name})} to
-output the name itself; before and after that, output the additional
-assembler syntax for defining the name, and a newline. A default
-definition of this macro is provided which is correct for most systems.
-
-If this macro is not defined, then the function name is defined in the
-usual manner as a label (by means of @code{ASM_OUTPUT_LABEL}).
-@end defmac
-
-@findex assemble_name_raw
-@defmac ASM_OUTPUT_INTERNAL_LABEL (@var{stream}, @var{name})
-Identical to @code{ASM_OUTPUT_LABEL}, except that @var{name} is known
-to refer to a compiler-generated label. The default definition uses
-@code{assemble_name_raw}, which is like @code{assemble_name} except
-that it is more efficient.
-@end defmac
-
-@defmac SIZE_ASM_OP
-A C string containing the appropriate assembler directive to specify the
-size of a symbol, without any arguments. On systems that use ELF, the
-default (in @file{config/elfos.h}) is @samp{"\t.size\t"}; on other
-systems, the default is not to define this macro.
-
-Define this macro only if it is correct to use the default definitions
-of @code{ASM_OUTPUT_SIZE_DIRECTIVE} and @code{ASM_OUTPUT_MEASURED_SIZE}
-for your system. If you need your own custom definitions of those
-macros, or if you do not need explicit symbol sizes at all, do not
-define this macro.
-@end defmac
-
-@defmac ASM_OUTPUT_SIZE_DIRECTIVE (@var{stream}, @var{name}, @var{size})
-A C statement (sans semicolon) to output to the stdio stream
-@var{stream} a directive telling the assembler that the size of the
-symbol @var{name} is @var{size}. @var{size} is a @code{HOST_WIDE_INT}.
-If you define @code{SIZE_ASM_OP}, a default definition of this macro is
-provided.
-@end defmac
-
-@defmac ASM_OUTPUT_MEASURED_SIZE (@var{stream}, @var{name})
-A C statement (sans semicolon) to output to the stdio stream
-@var{stream} a directive telling the assembler to calculate the size of
-the symbol @var{name} by subtracting its address from the current
-address.
-
-If you define @code{SIZE_ASM_OP}, a default definition of this macro is
-provided. The default assumes that the assembler recognizes a special
-@samp{.} symbol as referring to the current address, and can calculate
-the difference between this and another symbol. If your assembler does
-not recognize @samp{.} or cannot do calculations with it, you will need
-to redefine @code{ASM_OUTPUT_MEASURED_SIZE} to use some other technique.
-@end defmac
-
-@defmac NO_DOLLAR_IN_LABEL
-Define this macro if the assembler does not accept the character
-@samp{$} in label names. By default constructors and destructors in
-G++ have @samp{$} in the identifiers. If this macro is defined,
-@samp{.} is used instead.
-@end defmac
-
-@defmac NO_DOT_IN_LABEL
-Define this macro if the assembler does not accept the character
-@samp{.} in label names. By default constructors and destructors in G++
-have names that use @samp{.}. If this macro is defined, these names
-are rewritten to avoid @samp{.}.
-@end defmac
-
-@defmac TYPE_ASM_OP
-A C string containing the appropriate assembler directive to specify the
-type of a symbol, without any arguments. On systems that use ELF, the
-default (in @file{config/elfos.h}) is @samp{"\t.type\t"}; on other
-systems, the default is not to define this macro.
-
-Define this macro only if it is correct to use the default definition of
-@code{ASM_OUTPUT_TYPE_DIRECTIVE} for your system. If you need your own
-custom definition of this macro, or if you do not need explicit symbol
-types at all, do not define this macro.
-@end defmac
-
-@defmac TYPE_OPERAND_FMT
-A C string which specifies (using @code{printf} syntax) the format of
-the second operand to @code{TYPE_ASM_OP}. On systems that use ELF, the
-default (in @file{config/elfos.h}) is @samp{"@@%s"}; on other systems,
-the default is not to define this macro.
-
-Define this macro only if it is correct to use the default definition of
-@code{ASM_OUTPUT_TYPE_DIRECTIVE} for your system. If you need your own
-custom definition of this macro, or if you do not need explicit symbol
-types at all, do not define this macro.
-@end defmac
-
-@defmac ASM_OUTPUT_TYPE_DIRECTIVE (@var{stream}, @var{type})
-A C statement (sans semicolon) to output to the stdio stream
-@var{stream} a directive telling the assembler that the type of the
-symbol @var{name} is @var{type}. @var{type} is a C string; currently,
-that string is always either @samp{"function"} or @samp{"object"}, but
-you should not count on this.
-
-If you define @code{TYPE_ASM_OP} and @code{TYPE_OPERAND_FMT}, a default
-definition of this macro is provided.
-@end defmac
-
-@defmac ASM_DECLARE_FUNCTION_NAME (@var{stream}, @var{name}, @var{decl})
-A C statement (sans semicolon) to output to the stdio stream
-@var{stream} any text necessary for declaring the name @var{name} of a
-function which is being defined. This macro is responsible for
-outputting the label definition (perhaps using
-@code{ASM_OUTPUT_FUNCTION_LABEL}). The argument @var{decl} is the
-@code{FUNCTION_DECL} tree node representing the function.
-
-If this macro is not defined, then the function name is defined in the
-usual manner as a label (by means of @code{ASM_OUTPUT_FUNCTION_LABEL}).
-
-You may wish to use @code{ASM_OUTPUT_TYPE_DIRECTIVE} in the definition
-of this macro.
-@end defmac
-
-@defmac ASM_DECLARE_FUNCTION_SIZE (@var{stream}, @var{name}, @var{decl})
-A C statement (sans semicolon) to output to the stdio stream
-@var{stream} any text necessary for declaring the size of a function
-which is being defined. The argument @var{name} is the name of the
-function. The argument @var{decl} is the @code{FUNCTION_DECL} tree node
-representing the function.
-
-If this macro is not defined, then the function size is not defined.
-
-You may wish to use @code{ASM_OUTPUT_MEASURED_SIZE} in the definition
-of this macro.
-@end defmac
-
-@defmac ASM_DECLARE_COLD_FUNCTION_NAME (@var{stream}, @var{name}, @var{decl})
-A C statement (sans semicolon) to output to the stdio stream
-@var{stream} any text necessary for declaring the name @var{name} of a
-cold function partition which is being defined. This macro is responsible
-for outputting the label definition (perhaps using
-@code{ASM_OUTPUT_FUNCTION_LABEL}). The argument @var{decl} is the
-@code{FUNCTION_DECL} tree node representing the function.
-
-If this macro is not defined, then the cold partition name is defined in the
-usual manner as a label (by means of @code{ASM_OUTPUT_LABEL}).
-
-You may wish to use @code{ASM_OUTPUT_TYPE_DIRECTIVE} in the definition
-of this macro.
-@end defmac
-
-@defmac ASM_DECLARE_COLD_FUNCTION_SIZE (@var{stream}, @var{name}, @var{decl})
-A C statement (sans semicolon) to output to the stdio stream
-@var{stream} any text necessary for declaring the size of a cold function
-partition which is being defined. The argument @var{name} is the name of the
-cold partition of the function. The argument @var{decl} is the
-@code{FUNCTION_DECL} tree node representing the function.
-
-If this macro is not defined, then the partition size is not defined.
-
-You may wish to use @code{ASM_OUTPUT_MEASURED_SIZE} in the definition
-of this macro.
-@end defmac
-
-@defmac ASM_DECLARE_OBJECT_NAME (@var{stream}, @var{name}, @var{decl})
-A C statement (sans semicolon) to output to the stdio stream
-@var{stream} any text necessary for declaring the name @var{name} of an
-initialized variable which is being defined. This macro must output the
-label definition (perhaps using @code{ASM_OUTPUT_LABEL}). The argument
-@var{decl} is the @code{VAR_DECL} tree node representing the variable.
-
-If this macro is not defined, then the variable name is defined in the
-usual manner as a label (by means of @code{ASM_OUTPUT_LABEL}).
-
-You may wish to use @code{ASM_OUTPUT_TYPE_DIRECTIVE} and/or
-@code{ASM_OUTPUT_SIZE_DIRECTIVE} in the definition of this macro.
-@end defmac
-
-@hook TARGET_ASM_DECLARE_CONSTANT_NAME
-
-@defmac ASM_DECLARE_REGISTER_GLOBAL (@var{stream}, @var{decl}, @var{regno}, @var{name})
-A C statement (sans semicolon) to output to the stdio stream
-@var{stream} any text necessary for claiming a register @var{regno}
-for a global variable @var{decl} with name @var{name}.
-
-If you don't define this macro, that is equivalent to defining it to do
-nothing.
-@end defmac
-
-@defmac ASM_FINISH_DECLARE_OBJECT (@var{stream}, @var{decl}, @var{toplevel}, @var{atend})
-A C statement (sans semicolon) to finish up declaring a variable name
-once the compiler has processed its initializer fully and thus has had a
-chance to determine the size of an array when controlled by an
-initializer. This is used on systems where it's necessary to declare
-something about the size of the object.
-
-If you don't define this macro, that is equivalent to defining it to do
-nothing.
-
-You may wish to use @code{ASM_OUTPUT_SIZE_DIRECTIVE} and/or
-@code{ASM_OUTPUT_MEASURED_SIZE} in the definition of this macro.
-@end defmac
-
-@hook TARGET_ASM_GLOBALIZE_LABEL
-
-@hook TARGET_ASM_GLOBALIZE_DECL_NAME
-
-@hook TARGET_ASM_ASSEMBLE_UNDEFINED_DECL
-
-@defmac ASM_WEAKEN_LABEL (@var{stream}, @var{name})
-A C statement (sans semicolon) to output to the stdio stream
-@var{stream} some commands that will make the label @var{name} weak;
-that is, available for reference from other files but only used if
-no other definition is available. Use the expression
-@code{assemble_name (@var{stream}, @var{name})} to output the name
-itself; before and after that, output the additional assembler syntax
-for making that name weak, and a newline.
-
-If you don't define this macro or @code{ASM_WEAKEN_DECL}, GCC will not
-support weak symbols and you should not define the @code{SUPPORTS_WEAK}
-macro.
-@end defmac
-
-@defmac ASM_WEAKEN_DECL (@var{stream}, @var{decl}, @var{name}, @var{value})
-Combines (and replaces) the function of @code{ASM_WEAKEN_LABEL} and
-@code{ASM_OUTPUT_WEAK_ALIAS}, allowing access to the associated function
-or variable decl. If @var{value} is not @code{NULL}, this C statement
-should output to the stdio stream @var{stream} assembler code which
-defines (equates) the weak symbol @var{name} to have the value
-@var{value}. If @var{value} is @code{NULL}, it should output commands
-to make @var{name} weak.
-@end defmac
-
-@defmac ASM_OUTPUT_WEAKREF (@var{stream}, @var{decl}, @var{name}, @var{value})
-Outputs a directive that enables @var{name} to be used to refer to
-symbol @var{value} with weak-symbol semantics. @code{decl} is the
-declaration of @code{name}.
-@end defmac
-
-@defmac SUPPORTS_WEAK
-A preprocessor constant expression which evaluates to true if the target
-supports weak symbols.
-
-If you don't define this macro, @file{defaults.h} provides a default
-definition. If either @code{ASM_WEAKEN_LABEL} or @code{ASM_WEAKEN_DECL}
-is defined, the default definition is @samp{1}; otherwise, it is @samp{0}.
-@end defmac
-
-@defmac TARGET_SUPPORTS_WEAK
-A C expression which evaluates to true if the target supports weak symbols.
-
-If you don't define this macro, @file{defaults.h} provides a default
-definition. The default definition is @samp{(SUPPORTS_WEAK)}. Define
-this macro if you want to control weak symbol support with a compiler
-flag such as @option{-melf}.
-@end defmac
-
-@defmac MAKE_DECL_ONE_ONLY (@var{decl})
-A C statement (sans semicolon) to mark @var{decl} to be emitted as a
-public symbol such that extra copies in multiple translation units will
-be discarded by the linker. Define this macro if your object file
-format provides support for this concept, such as the @samp{COMDAT}
-section flags in the Microsoft Windows PE/COFF format, and this support
-requires changes to @var{decl}, such as putting it in a separate section.
-@end defmac
-
-@defmac SUPPORTS_ONE_ONLY
-A C expression which evaluates to true if the target supports one-only
-semantics.
-
-If you don't define this macro, @file{varasm.cc} provides a default
-definition. If @code{MAKE_DECL_ONE_ONLY} is defined, the default
-definition is @samp{1}; otherwise, it is @samp{0}. Define this macro if
-you want to control one-only symbol support with a compiler flag, or if
-setting the @code{DECL_ONE_ONLY} flag is enough to mark a declaration to
-be emitted as one-only.
-@end defmac
-
-@hook TARGET_ASM_ASSEMBLE_VISIBILITY
-
-@defmac TARGET_WEAK_NOT_IN_ARCHIVE_TOC
-A C expression that evaluates to true if the target's linker expects
-that weak symbols do not appear in a static archive's table of contents.
-The default is @code{0}.
-
-Leaving weak symbols out of an archive's table of contents means that,
-if a symbol will only have a definition in one translation unit and
-will have undefined references from other translation units, that
-symbol should not be weak. Defining this macro to be nonzero will
-thus have the effect that certain symbols that would normally be weak
-(explicit template instantiations, and vtables for polymorphic classes
-with noninline key methods) will instead be nonweak.
-
-The C++ ABI requires this macro to be zero. Define this macro for
-targets where full C++ ABI compliance is impossible and where linker
-restrictions require weak symbols to be left out of a static archive's
-table of contents.
-@end defmac
-
-@defmac ASM_OUTPUT_EXTERNAL (@var{stream}, @var{decl}, @var{name})
-A C statement (sans semicolon) to output to the stdio stream
-@var{stream} any text necessary for declaring the name of an external
-symbol named @var{name} which is referenced in this compilation but
-not defined. The value of @var{decl} is the tree node for the
-declaration.
-
-This macro need not be defined if it does not need to output anything.
-The GNU assembler and most Unix assemblers don't require anything.
-@end defmac
-
-@hook TARGET_ASM_EXTERNAL_LIBCALL
-
-@hook TARGET_ASM_MARK_DECL_PRESERVED
-
-@defmac ASM_OUTPUT_LABELREF (@var{stream}, @var{name})
-A C statement (sans semicolon) to output to the stdio stream
-@var{stream} a reference in assembler syntax to a label named
-@var{name}. This should add @samp{_} to the front of the name, if that
-is customary on your operating system, as it is in most Berkeley Unix
-systems. This macro is used in @code{assemble_name}.
-@end defmac
-
-@hook TARGET_MANGLE_ASSEMBLER_NAME
-
-@defmac ASM_OUTPUT_SYMBOL_REF (@var{stream}, @var{sym})
-A C statement (sans semicolon) to output a reference to
-@code{SYMBOL_REF} @var{sym}. If not defined, @code{assemble_name}
-will be used to output the name of the symbol. This macro may be used
-to modify the way a symbol is referenced depending on information
-encoded by @code{TARGET_ENCODE_SECTION_INFO}.
-@end defmac
-
-@defmac ASM_OUTPUT_LABEL_REF (@var{stream}, @var{buf})
-A C statement (sans semicolon) to output a reference to @var{buf}, the
-result of @code{ASM_GENERATE_INTERNAL_LABEL}. If not defined,
-@code{assemble_name} will be used to output the name of the symbol.
-This macro is not used by @code{output_asm_label}, or the @code{%l}
-specifier that calls it; the intention is that this macro should be set
-when it is necessary to output a label differently when its address is
-being taken.
-@end defmac
-
-@hook TARGET_ASM_INTERNAL_LABEL
-
-@defmac ASM_OUTPUT_DEBUG_LABEL (@var{stream}, @var{prefix}, @var{num})
-A C statement to output to the stdio stream @var{stream} a debug info
-label whose name is made from the string @var{prefix} and the number
-@var{num}. This is useful for VLIW targets, where debug info labels
-may need to be treated differently than branch target labels. On some
-systems, branch target labels must be at the beginning of instruction
-bundles, but debug info labels can occur in the middle of instruction
-bundles.
-
-If this macro is not defined, then @code{(*targetm.asm_out.internal_label)} will be
-used.
-@end defmac
-
-@defmac ASM_GENERATE_INTERNAL_LABEL (@var{string}, @var{prefix}, @var{num})
-A C statement to store into the string @var{string} a label whose name
-is made from the string @var{prefix} and the number @var{num}.
-
-This string, when output subsequently by @code{assemble_name}, should
-produce the output that @code{(*targetm.asm_out.internal_label)} would produce
-with the same @var{prefix} and @var{num}.
-
-If the string begins with @samp{*}, then @code{assemble_name} will
-output the rest of the string unchanged. It is often convenient for
-@code{ASM_GENERATE_INTERNAL_LABEL} to use @samp{*} in this way. If the
-string doesn't start with @samp{*}, then @code{ASM_OUTPUT_LABELREF} gets
-to output the string, and may change it. (Of course,
-@code{ASM_OUTPUT_LABELREF} is also part of your machine description, so
-you should know what it does on your machine.)
-@end defmac
-
-@defmac ASM_FORMAT_PRIVATE_NAME (@var{outvar}, @var{name}, @var{number})
-A C expression to assign to @var{outvar} (which is a variable of type
-@code{char *}) a newly allocated string made from the string
-@var{name} and the number @var{number}, with some suitable punctuation
-added. Use @code{alloca} to get space for the string.
-
-The string will be used as an argument to @code{ASM_OUTPUT_LABELREF} to
-produce an assembler label for an internal static variable whose name is
-@var{name}. Therefore, the string must be such as to result in valid
-assembler code. The argument @var{number} is different each time this
-macro is executed; it prevents conflicts between similarly-named
-internal static variables in different scopes.
-
-Ideally this string should not be a valid C identifier, to prevent any
-conflict with the user's own symbols. Most assemblers allow periods
-or percent signs in assembler symbols; putting at least one of these
-between the name and the number will suffice.
-
-If this macro is not defined, a default definition will be provided
-which is correct for most systems.
-@end defmac
-
-@defmac ASM_OUTPUT_DEF (@var{stream}, @var{name}, @var{value})
-A C statement to output to the stdio stream @var{stream} assembler code
-which defines (equates) the symbol @var{name} to have the value @var{value}.
-
-@findex SET_ASM_OP
-If @code{SET_ASM_OP} is defined, a default definition is provided which is
-correct for most systems.
-@end defmac
-
-@defmac ASM_OUTPUT_DEF_FROM_DECLS (@var{stream}, @var{decl_of_name}, @var{decl_of_value})
-A C statement to output to the stdio stream @var{stream} assembler code
-which defines (equates) the symbol whose tree node is @var{decl_of_name}
-to have the value of the tree node @var{decl_of_value}. This macro will
-be used in preference to @samp{ASM_OUTPUT_DEF} if it is defined and if
-the tree nodes are available.
-
-@findex SET_ASM_OP
-If @code{SET_ASM_OP} is defined, a default definition is provided which is
-correct for most systems.
-@end defmac
-
-@defmac TARGET_DEFERRED_OUTPUT_DEFS (@var{decl_of_name}, @var{decl_of_value})
-A C statement that evaluates to true if the assembler code which defines
-(equates) the symbol whose tree node is @var{decl_of_name} to have the value
-of the tree node @var{decl_of_value} should be emitted near the end of the
-current compilation unit. The default is to not defer output of defines.
-This macro affects defines output by @samp{ASM_OUTPUT_DEF} and
-@samp{ASM_OUTPUT_DEF_FROM_DECLS}.
-@end defmac
-
-@defmac ASM_OUTPUT_WEAK_ALIAS (@var{stream}, @var{name}, @var{value})
-A C statement to output to the stdio stream @var{stream} assembler code
-which defines (equates) the weak symbol @var{name} to have the value
-@var{value}. If @var{value} is @code{NULL}, it defines @var{name} as
-an undefined weak symbol.
-
-Define this macro if the target only supports weak aliases; define
-@code{ASM_OUTPUT_DEF} instead if possible.
-@end defmac
-
-@defmac OBJC_GEN_METHOD_LABEL (@var{buf}, @var{is_inst}, @var{class_name}, @var{cat_name}, @var{sel_name})
-Define this macro to override the default assembler names used for
-Objective-C methods.
-
-The default name is a unique method number followed by the name of the
-class (e.g.@: @samp{_1_Foo}). For methods in categories, the name of
-the category is also included in the assembler name (e.g.@:
-@samp{_1_Foo_Bar}).
-
-These names are safe on most systems, but make debugging difficult since
-the method's selector is not present in the name. Therefore, particular
-systems define other ways of computing names.
-
-@var{buf} is an expression of type @code{char *} which gives you a
-buffer in which to store the name; its length is as long as
-@var{class_name}, @var{cat_name} and @var{sel_name} put together, plus
-50 characters extra.
-
-The argument @var{is_inst} specifies whether the method is an instance
-method or a class method; @var{class_name} is the name of the class;
-@var{cat_name} is the name of the category (or @code{NULL} if the method is not
-in a category); and @var{sel_name} is the name of the selector.
-
-On systems where the assembler can handle quoted names, you can use this
-macro to provide more human-readable names.
-@end defmac
-
-@node Initialization
-@subsection How Initialization Functions Are Handled
-@cindex initialization routines
-@cindex termination routines
-@cindex constructors, output of
-@cindex destructors, output of
-
-The compiled code for certain languages includes @dfn{constructors}
-(also called @dfn{initialization routines})---functions to initialize
-data in the program when the program is started. These functions need
-to be called before the program is ``started''---that is to say, before
-@code{main} is called.
-
-Compiling some languages generates @dfn{destructors} (also called
-@dfn{termination routines}) that should be called when the program
-terminates.
-
-To make the initialization and termination functions work, the compiler
-must output something in the assembler code to cause those functions to
-be called at the appropriate time. When you port the compiler to a new
-system, you need to specify how to do this.
-
-There are two major ways that GCC currently supports the execution of
-initialization and termination functions. Each way has two variants.
-Much of the structure is common to all four variations.
-
-@findex __CTOR_LIST__
-@findex __DTOR_LIST__
-The linker must build two lists of these functions---a list of
-initialization functions, called @code{__CTOR_LIST__}, and a list of
-termination functions, called @code{__DTOR_LIST__}.
-
-Each list always begins with an ignored function pointer (which may hold
-0, @minus{}1, or a count of the function pointers after it, depending on
-the environment). This is followed by a series of zero or more function
-pointers to constructors (or destructors), followed by a function
-pointer containing zero.
-
-Depending on the operating system and its executable file format, either
-@file{crtstuff.c} or @file{libgcc2.c} traverses these lists at startup
-time and exit time. Constructors are called in reverse order of the
-list; destructors in forward order.
-
-The best way to handle static constructors works only for object file
-formats which provide arbitrarily-named sections. A section is set
-aside for a list of constructors, and another for a list of destructors.
-Traditionally these are called @samp{.ctors} and @samp{.dtors}. Each
-object file that defines an initialization function also puts a word in
-the constructor section to point to that function. The linker
-accumulates all these words into one contiguous @samp{.ctors} section.
-Termination functions are handled similarly.
-
-This method will be chosen as the default by @file{target-def.h} if
-@code{TARGET_ASM_NAMED_SECTION} is defined. A target that does not
-support arbitrary sections, but does support special designated
-constructor and destructor sections may define @code{CTORS_SECTION_ASM_OP}
-and @code{DTORS_SECTION_ASM_OP} to achieve the same effect.
-
-When arbitrary sections are available, there are two variants, depending
-upon how the code in @file{crtstuff.c} is called. On systems that
-support a @dfn{.init} section which is executed at program startup,
-parts of @file{crtstuff.c} are compiled into that section. The
-program is linked by the @command{gcc} driver like this:
-
-@smallexample
-ld -o @var{output_file} crti.o crtbegin.o @dots{} -lgcc crtend.o crtn.o
-@end smallexample
-
-The prologue of a function (@code{__init}) appears in the @code{.init}
-section of @file{crti.o}; the epilogue appears in @file{crtn.o}. Likewise
-for the function @code{__fini} in the @dfn{.fini} section. Normally these
-files are provided by the operating system or by the GNU C library, but
-are provided by GCC for a few targets.
-
-The objects @file{crtbegin.o} and @file{crtend.o} are (for most targets)
-compiled from @file{crtstuff.c}. They contain, among other things, code
-fragments within the @code{.init} and @code{.fini} sections that branch
-to routines in the @code{.text} section. The linker will pull all parts
-of a section together, which results in a complete @code{__init} function
-that invokes the routines we need at startup.
-
-To use this variant, you must define the @code{INIT_SECTION_ASM_OP}
-macro properly.
-
-If no init section is available, when GCC compiles any function called
-@code{main} (or more accurately, any function designated as a program
-entry point by the language front end calling @code{expand_main_function}),
-it inserts a procedure call to @code{__main} as the first executable code
-after the function prologue. The @code{__main} function is defined
-in @file{libgcc2.c} and runs the global constructors.
-
-In file formats that don't support arbitrary sections, there are again
-two variants. In the simplest variant, the GNU linker (GNU @code{ld})
-and an `a.out' format must be used. In this case,
-@code{TARGET_ASM_CONSTRUCTOR} is defined to produce a @code{.stabs}
-entry of type @samp{N_SETT}, referencing the name @code{__CTOR_LIST__},
-and with the address of the void function containing the initialization
-code as its value. The GNU linker recognizes this as a request to add
-the value to a @dfn{set}; the values are accumulated, and are eventually
-placed in the executable as a vector in the format described above, with
-a leading (ignored) count and a trailing zero element.
-@code{TARGET_ASM_DESTRUCTOR} is handled similarly. Since no init
-section is available, the absence of @code{INIT_SECTION_ASM_OP} causes
-the compilation of @code{main} to call @code{__main} as above, starting
-the initialization process.
-
-The last variant uses neither arbitrary sections nor the GNU linker.
-This is preferable when you want to do dynamic linking and when using
-file formats which the GNU linker does not support, such as `ECOFF'@. In
-this case, @code{TARGET_HAVE_CTORS_DTORS} is false, initialization and
-termination functions are recognized simply by their names. This requires
-an extra program in the linkage step, called @command{collect2}. This program
-pretends to be the linker, for use with GCC; it does its job by running
-the ordinary linker, but also arranges to include the vectors of
-initialization and termination functions. These functions are called
-via @code{__main} as described above. In order to use this method,
-@code{use_collect2} must be defined in the target in @file{config.gcc}.
-
-@ifinfo
-The following section describes the specific macros that control and
-customize the handling of initialization and termination functions.
-@end ifinfo
-
-@node Macros for Initialization
-@subsection Macros Controlling Initialization Routines
-
-Here are the macros that control how the compiler handles initialization
-and termination functions:
-
-@defmac INIT_SECTION_ASM_OP
-If defined, a C string constant, including spacing, for the assembler
-operation to identify the following data as initialization code. If not
-defined, GCC will assume such a section does not exist. When you are
-using special sections for initialization and termination functions, this
-macro also controls how @file{crtstuff.c} and @file{libgcc2.c} arrange to
-run the initialization functions.
-@end defmac
-
-@defmac HAS_INIT_SECTION
-If defined, @code{main} will not call @code{__main} as described above.
-This macro should be defined for systems that control start-up code
-on a symbol-by-symbol basis, such as OSF/1, and should not
-be defined explicitly for systems that support @code{INIT_SECTION_ASM_OP}.
-@end defmac
-
-@defmac LD_INIT_SWITCH
-If defined, a C string constant for a switch that tells the linker that
-the following symbol is an initialization routine.
-@end defmac
-
-@defmac LD_FINI_SWITCH
-If defined, a C string constant for a switch that tells the linker that
-the following symbol is a finalization routine.
-@end defmac
-
-@defmac COLLECT_SHARED_INIT_FUNC (@var{stream}, @var{func})
-If defined, a C statement that will write a function that can be
-automatically called when a shared library is loaded. The function
-should call @var{func}, which takes no arguments. If not defined, and
-the object format requires an explicit initialization function, then a
-function called @code{_GLOBAL__DI} will be generated.
-
-This function and the following one are used by collect2 when linking a
-shared library that needs constructors or destructors, or has DWARF2
-exception tables embedded in the code.
-@end defmac
-
-@defmac COLLECT_SHARED_FINI_FUNC (@var{stream}, @var{func})
-If defined, a C statement that will write a function that can be
-automatically called when a shared library is unloaded. The function
-should call @var{func}, which takes no arguments. If not defined, and
-the object format requires an explicit finalization function, then a
-function called @code{_GLOBAL__DD} will be generated.
-@end defmac
-
-@defmac INVOKE__main
-If defined, @code{main} will call @code{__main} despite the presence of
-@code{INIT_SECTION_ASM_OP}. This macro should be defined for systems
-where the init section is not actually run automatically, but is still
-useful for collecting the lists of constructors and destructors.
-@end defmac
-
-@defmac SUPPORTS_INIT_PRIORITY
-If nonzero, the C++ @code{init_priority} attribute is supported and the
-compiler should emit instructions to control the order of initialization
-of objects. If zero, the compiler will issue an error message upon
-encountering an @code{init_priority} attribute.
-@end defmac
-
-@hook TARGET_HAVE_CTORS_DTORS
-
-@hook TARGET_DTORS_FROM_CXA_ATEXIT
-
-@hook TARGET_ASM_CONSTRUCTOR
-
-@hook TARGET_ASM_DESTRUCTOR
-
-If @code{TARGET_HAVE_CTORS_DTORS} is true, the initialization routine
-generated for the generated object file will have static linkage.
-
-If your system uses @command{collect2} as the means of processing
-constructors, then that program normally uses @command{nm} to scan
-an object file for constructor functions to be called.
-
-On certain kinds of systems, you can define this macro to make
-@command{collect2} work faster (and, in some cases, make it work at all):
-
-@defmac OBJECT_FORMAT_COFF
-Define this macro if the system uses COFF (Common Object File Format)
-object files, so that @command{collect2} can assume this format and scan
-object files directly for dynamic constructor/destructor functions.
-
-This macro is effective only in a native compiler; @command{collect2} as
-part of a cross compiler always uses @command{nm} for the target machine.
-@end defmac
-
-@defmac REAL_NM_FILE_NAME
-Define this macro as a C string constant containing the file name to use
-to execute @command{nm}. The default is to search the path normally for
-@command{nm}.
-@end defmac
-
-@defmac NM_FLAGS
-@command{collect2} calls @command{nm} to scan object files for static
-constructors and destructors and LTO info. By default, @option{-n} is
-passed. Define @code{NM_FLAGS} to a C string constant if other options
-are needed to get the same output format as GNU @command{nm -n}
-produces.
-@end defmac
-
-If your system supports shared libraries and has a program to list the
-dynamic dependencies of a given library or executable, you can define
-these macros to enable support for running initialization and
-termination functions in shared libraries:
-
-@defmac LDD_SUFFIX
-Define this macro to a C string constant containing the name of the program
-which lists dynamic dependencies, like @command{ldd} under SunOS 4.
-@end defmac
-
-@defmac PARSE_LDD_OUTPUT (@var{ptr})
-Define this macro to be C code that extracts filenames from the output
-of the program denoted by @code{LDD_SUFFIX}. @var{ptr} is a variable
-of type @code{char *} that points to the beginning of a line of output
-from @code{LDD_SUFFIX}. If the line lists a dynamic dependency, the
-code must advance @var{ptr} to the beginning of the filename on that
-line. Otherwise, it must set @var{ptr} to @code{NULL}.
-@end defmac
-
-@defmac SHLIB_SUFFIX
-Define this macro to a C string constant containing the default shared
-library extension of the target (e.g., @samp{".so"}). @command{collect2}
-strips version information after this suffix when generating global
-constructor and destructor names. This define is only needed on targets
-that use @command{collect2} to process constructors and destructors.
-@end defmac
-
-@node Instruction Output
-@subsection Output of Assembler Instructions
-
-@c prevent bad page break with this line
-This describes assembler instruction output.
-
-@defmac REGISTER_NAMES
-A C initializer containing the assembler's names for the machine
-registers, each one as a C string constant. This is what translates
-register numbers in the compiler into assembler language.
-@end defmac
-
-@defmac ADDITIONAL_REGISTER_NAMES
-If defined, a C initializer for an array of structures containing a name
-and a register number. This macro defines additional names for hard
-registers, thus allowing the @code{asm} option in declarations to refer
-to registers using alternate names.
-@end defmac
-
-@defmac OVERLAPPING_REGISTER_NAMES
-If defined, a C initializer for an array of structures containing a
-name, a register number and a count of the number of consecutive
-machine registers the name overlaps. This macro defines additional
-names for hard registers, thus allowing the @code{asm} option in
-declarations to refer to registers using alternate names. Unlike
-@code{ADDITIONAL_REGISTER_NAMES}, this macro should be used when the
-register name implies multiple underlying registers.
-
-This macro should be used when it is important that a clobber in an
-@code{asm} statement clobbers all the underlying values implied by the
-register name. For example, on ARM, clobbering the double-precision
-VFP register ``d0'' implies clobbering both single-precision registers
-``s0'' and ``s1''.
-@end defmac
-
-@defmac ASM_OUTPUT_OPCODE (@var{stream}, @var{ptr})
-Define this macro if you are using an unusual assembler that
-requires different names for the machine instructions.
-
-The definition is a C statement or statements which output an
-assembler instruction opcode to the stdio stream @var{stream}. The
-macro-operand @var{ptr} is a variable of type @code{char *} which
-points to the opcode name in its ``internal'' form---the form that is
-written in the machine description. The definition should output the
-opcode name to @var{stream}, performing any translation you desire, and
-increment the variable @var{ptr} to point at the end of the opcode
-so that it will not be output twice.
-
-In fact, your macro definition may process less than the entire opcode
-name, or more than the opcode name; but if you want to process text
-that includes @samp{%}-sequences to substitute operands, you must take
-care of the substitution yourself. Just be sure to increment
-@var{ptr} over whatever text should not be output normally.
-
-@findex recog_data.operand
-If you need to look at the operand values, they can be found as the
-elements of @code{recog_data.operand}.
-
-If the macro definition does nothing, the instruction is output
-in the usual way.
-@end defmac
-
-@defmac FINAL_PRESCAN_INSN (@var{insn}, @var{opvec}, @var{noperands})
-If defined, a C statement to be executed just prior to the output of
-assembler code for @var{insn}, to modify the extracted operands so
-they will be output differently.
-
-Here the argument @var{opvec} is the vector containing the operands
-extracted from @var{insn}, and @var{noperands} is the number of
-elements of the vector which contain meaningful data for this insn.
-The contents of this vector are what will be used to convert the insn
-template into assembler code, so you can change the assembler output
-by changing the contents of the vector.
-
-This macro is useful when various assembler syntaxes share a single
-file of instruction patterns; by defining this macro differently, you
-can cause a large class of instructions to be output differently (such
-as with rearranged operands). Naturally, variations in assembler
-syntax affecting individual insn patterns ought to be handled by
-writing conditional output routines in those patterns.
-
-If this macro is not defined, it is equivalent to a null statement.
-@end defmac
-
-@hook TARGET_ASM_FINAL_POSTSCAN_INSN
-
-@defmac PRINT_OPERAND (@var{stream}, @var{x}, @var{code})
-A C compound statement to output to stdio stream @var{stream} the
-assembler syntax for an instruction operand @var{x}. @var{x} is an
-RTL expression.
-
-@var{code} is a value that can be used to specify one of several ways
-of printing the operand. It is used when identical operands must be
-printed differently depending on the context. @var{code} comes from
-the @samp{%} specification that was used to request printing of the
-operand. If the specification was just @samp{%@var{digit}} then
-@var{code} is 0; if the specification was @samp{%@var{ltr}
-@var{digit}} then @var{code} is the ASCII code for @var{ltr}.
-
-@findex reg_names
-If @var{x} is a register, this macro should print the register's name.
-The names can be found in an array @code{reg_names} whose type is
-@code{char *[]}. @code{reg_names} is initialized from
-@code{REGISTER_NAMES}.
-
-When the machine description has a specification @samp{%@var{punct}}
-(a @samp{%} followed by a punctuation character), this macro is called
-with a null pointer for @var{x} and the punctuation character for
-@var{code}.
-@end defmac
-
-@defmac PRINT_OPERAND_PUNCT_VALID_P (@var{code})
-A C expression which evaluates to true if @var{code} is a valid
-punctuation character for use in the @code{PRINT_OPERAND} macro. If
-@code{PRINT_OPERAND_PUNCT_VALID_P} is not defined, it means that no
-punctuation characters (except for the standard one, @samp{%}) are used
-in this way.
-@end defmac
-
-@defmac PRINT_OPERAND_ADDRESS (@var{stream}, @var{x})
-A C compound statement to output to stdio stream @var{stream} the
-assembler syntax for an instruction operand that is a memory reference
-whose address is @var{x}. @var{x} is an RTL expression.
-
-@cindex @code{TARGET_ENCODE_SECTION_INFO} usage
-On some machines, the syntax for a symbolic address depends on the
-section that the address refers to. On these machines, define the hook
-@code{TARGET_ENCODE_SECTION_INFO} to store the information into the
-@code{symbol_ref}, and then check for it here. @xref{Assembler
-Format}.
-@end defmac
-
-@findex dbr_sequence_length
-@defmac DBR_OUTPUT_SEQEND (@var{file})
-A C statement, to be executed after all slot-filler instructions have
-been output. If necessary, call @code{dbr_sequence_length} to
-determine the number of slots filled in a sequence (zero if not
-currently outputting a sequence), to decide how many no-ops to output,
-or whatever.
-
-Don't define this macro if it has nothing to do, but it is helpful in
-reading assembly output if the extent of the delay sequence is made
-explicit (e.g.@: with white space).
-@end defmac
-
-@findex final_sequence
-Note that output routines for instructions with delay slots must be
-prepared to deal with not being output as part of a sequence
-(i.e.@: when the scheduling pass is not run, or when no slot fillers could be
-found.) The variable @code{final_sequence} is null when not
-processing a sequence, otherwise it contains the @code{sequence} rtx
-being output.
-
-@findex asm_fprintf
-@defmac REGISTER_PREFIX
-@defmacx LOCAL_LABEL_PREFIX
-@defmacx USER_LABEL_PREFIX
-@defmacx IMMEDIATE_PREFIX
-If defined, C string expressions to be used for the @samp{%R}, @samp{%L},
-@samp{%U}, and @samp{%I} options of @code{asm_fprintf} (see
-@file{final.cc}). These are useful when a single @file{md} file must
-support multiple assembler formats. In that case, the various @file{tm.h}
-files can define these macros differently.
-@end defmac
-
-@defmac ASM_FPRINTF_EXTENSIONS (@var{file}, @var{argptr}, @var{format})
-If defined this macro should expand to a series of @code{case}
-statements which will be parsed inside the @code{switch} statement of
-the @code{asm_fprintf} function. This allows targets to define extra
-printf formats which may useful when generating their assembler
-statements. Note that uppercase letters are reserved for future
-generic extensions to asm_fprintf, and so are not available to target
-specific code. The output file is given by the parameter @var{file}.
-The varargs input pointer is @var{argptr} and the rest of the format
-string, starting the character after the one that is being switched
-upon, is pointed to by @var{format}.
-@end defmac
-
-@defmac ASSEMBLER_DIALECT
-If your target supports multiple dialects of assembler language (such as
-different opcodes), define this macro as a C expression that gives the
-numeric index of the assembler language dialect to use, with zero as the
-first variant.
-
-If this macro is defined, you may use constructs of the form
-@smallexample
-@samp{@{option0|option1|option2@dots{}@}}
-@end smallexample
-@noindent
-in the output templates of patterns (@pxref{Output Template}) or in the
-first argument of @code{asm_fprintf}. This construct outputs
-@samp{option0}, @samp{option1}, @samp{option2}, etc., if the value of
-@code{ASSEMBLER_DIALECT} is zero, one, two, etc. Any special characters
-within these strings retain their usual meaning. If there are fewer
-alternatives within the braces than the value of
-@code{ASSEMBLER_DIALECT}, the construct outputs nothing. If it's needed
-to print curly braces or @samp{|} character in assembler output directly,
-@samp{%@{}, @samp{%@}} and @samp{%|} can be used.
-
-If you do not define this macro, the characters @samp{@{}, @samp{|} and
-@samp{@}} do not have any special meaning when used in templates or
-operands to @code{asm_fprintf}.
-
-Define the macros @code{REGISTER_PREFIX}, @code{LOCAL_LABEL_PREFIX},
-@code{USER_LABEL_PREFIX} and @code{IMMEDIATE_PREFIX} if you can express
-the variations in assembler language syntax with that mechanism. Define
-@code{ASSEMBLER_DIALECT} and use the @samp{@{option0|option1@}} syntax
-if the syntax variant are larger and involve such things as different
-opcodes or operand order.
-@end defmac
-
-@defmac ASM_OUTPUT_REG_PUSH (@var{stream}, @var{regno})
-A C expression to output to @var{stream} some assembler code
-which will push hard register number @var{regno} onto the stack.
-The code need not be optimal, since this macro is used only when
-profiling.
-@end defmac
-
-@defmac ASM_OUTPUT_REG_POP (@var{stream}, @var{regno})
-A C expression to output to @var{stream} some assembler code
-which will pop hard register number @var{regno} off of the stack.
-The code need not be optimal, since this macro is used only when
-profiling.
-@end defmac
-
-@node Dispatch Tables
-@subsection Output of Dispatch Tables
-
-@c prevent bad page break with this line
-This concerns dispatch tables.
-
-@cindex dispatch table
-@defmac ASM_OUTPUT_ADDR_DIFF_ELT (@var{stream}, @var{body}, @var{value}, @var{rel})
-A C statement to output to the stdio stream @var{stream} an assembler
-pseudo-instruction to generate a difference between two labels.
-@var{value} and @var{rel} are the numbers of two internal labels. The
-definitions of these labels are output using
-@code{(*targetm.asm_out.internal_label)}, and they must be printed in the same
-way here. For example,
-
-@smallexample
-fprintf (@var{stream}, "\t.word L%d-L%d\n",
- @var{value}, @var{rel})
-@end smallexample
-
-You must provide this macro on machines where the addresses in a
-dispatch table are relative to the table's own address. If defined, GCC
-will also use this macro on all machines when producing PIC@.
-@var{body} is the body of the @code{ADDR_DIFF_VEC}; it is provided so that the
-mode and flags can be read.
-@end defmac
-
-@defmac ASM_OUTPUT_ADDR_VEC_ELT (@var{stream}, @var{value})
-This macro should be provided on machines where the addresses
-in a dispatch table are absolute.
-
-The definition should be a C statement to output to the stdio stream
-@var{stream} an assembler pseudo-instruction to generate a reference to
-a label. @var{value} is the number of an internal label whose
-definition is output using @code{(*targetm.asm_out.internal_label)}.
-For example,
-
-@smallexample
-fprintf (@var{stream}, "\t.word L%d\n", @var{value})
-@end smallexample
-@end defmac
-
-@defmac ASM_OUTPUT_CASE_LABEL (@var{stream}, @var{prefix}, @var{num}, @var{table})
-Define this if the label before a jump-table needs to be output
-specially. The first three arguments are the same as for
-@code{(*targetm.asm_out.internal_label)}; the fourth argument is the
-jump-table which follows (a @code{jump_table_data} containing an
-@code{addr_vec} or @code{addr_diff_vec}).
-
-This feature is used on system V to output a @code{swbeg} statement
-for the table.
-
-If this macro is not defined, these labels are output with
-@code{(*targetm.asm_out.internal_label)}.
-@end defmac
-
-@defmac ASM_OUTPUT_CASE_END (@var{stream}, @var{num}, @var{table})
-Define this if something special must be output at the end of a
-jump-table. The definition should be a C statement to be executed
-after the assembler code for the table is written. It should write
-the appropriate code to stdio stream @var{stream}. The argument
-@var{table} is the jump-table insn, and @var{num} is the label-number
-of the preceding label.
-
-If this macro is not defined, nothing special is output at the end of
-the jump-table.
-@end defmac
-
-@hook TARGET_ASM_POST_CFI_STARTPROC
-
-@hook TARGET_ASM_EMIT_UNWIND_LABEL
-
-@hook TARGET_ASM_EMIT_EXCEPT_TABLE_LABEL
-
-@hook TARGET_ASM_EMIT_EXCEPT_PERSONALITY
-
-@hook TARGET_ASM_UNWIND_EMIT
-
-@hook TARGET_ASM_MAKE_EH_SYMBOL_INDIRECT
-
-@hook TARGET_ASM_UNWIND_EMIT_BEFORE_INSN
-
-@hook TARGET_ASM_SHOULD_RESTORE_CFA_STATE
-
-@node Exception Region Output
-@subsection Assembler Commands for Exception Regions
-
-@c prevent bad page break with this line
-
-This describes commands marking the start and the end of an exception
-region.
-
-@defmac EH_FRAME_SECTION_NAME
-If defined, a C string constant for the name of the section containing
-exception handling frame unwind information. If not defined, GCC will
-provide a default definition if the target supports named sections.
-@file{crtstuff.c} uses this macro to switch to the appropriate section.
-
-You should define this symbol if your target supports DWARF 2 frame
-unwind information and the default definition does not work.
-@end defmac
-
-@defmac EH_FRAME_THROUGH_COLLECT2
-If defined, DWARF 2 frame unwind information will identified by
-specially named labels. The collect2 process will locate these
-labels and generate code to register the frames.
-
-This might be necessary, for instance, if the system linker will not
-place the eh_frames in-between the sentinals from @file{crtstuff.c},
-or if the system linker does garbage collection and sections cannot
-be marked as not to be collected.
-@end defmac
-
-@defmac EH_TABLES_CAN_BE_READ_ONLY
-Define this macro to 1 if your target is such that no frame unwind
-information encoding used with non-PIC code will ever require a
-runtime relocation, but the linker may not support merging read-only
-and read-write sections into a single read-write section.
-@end defmac
-
-@defmac MASK_RETURN_ADDR
-An rtx used to mask the return address found via @code{RETURN_ADDR_RTX}, so
-that it does not contain any extraneous set bits in it.
-@end defmac
-
-@defmac DWARF2_UNWIND_INFO
-Define this macro to 0 if your target supports DWARF 2 frame unwind
-information, but it does not yet work with exception handling.
-Otherwise, if your target supports this information (if it defines
-@code{INCOMING_RETURN_ADDR_RTX} and @code{OBJECT_FORMAT_ELF}),
-GCC will provide a default definition of 1.
-@end defmac
-
-@hook TARGET_EXCEPT_UNWIND_INFO
-This hook defines the mechanism that will be used for exception handling
-by the target. If the target has ABI specified unwind tables, the hook
-should return @code{UI_TARGET}. If the target is to use the
-@code{setjmp}/@code{longjmp}-based exception handling scheme, the hook
-should return @code{UI_SJLJ}. If the target supports DWARF 2 frame unwind
-information, the hook should return @code{UI_DWARF2}.
-
-A target may, if exceptions are disabled, choose to return @code{UI_NONE}.
-This may end up simplifying other parts of target-specific code. The
-default implementation of this hook never returns @code{UI_NONE}.
-
-Note that the value returned by this hook should be constant. It should
-not depend on anything except the command-line switches described by
-@var{opts}. In particular, the
-setting @code{UI_SJLJ} must be fixed at compiler start-up as C pre-processor
-macros and builtin functions related to exception handling are set up
-depending on this setting.
-
-The default implementation of the hook first honors the
-@option{--enable-sjlj-exceptions} configure option, then
-@code{DWARF2_UNWIND_INFO}, and finally defaults to @code{UI_SJLJ}. If
-@code{DWARF2_UNWIND_INFO} depends on command-line options, the target
-must define this hook so that @var{opts} is used correctly.
-@end deftypefn
-
-@hook TARGET_UNWIND_TABLES_DEFAULT
-This variable should be set to @code{true} if the target ABI requires unwinding
-tables even when exceptions are not used. It must not be modified by
-command-line option processing.
-@end deftypevr
-
-@defmac DONT_USE_BUILTIN_SETJMP
-Define this macro to 1 if the @code{setjmp}/@code{longjmp}-based scheme
-should use the @code{setjmp}/@code{longjmp} functions from the C library
-instead of the @code{__builtin_setjmp}/@code{__builtin_longjmp} machinery.
-@end defmac
-
-@defmac JMP_BUF_SIZE
-This macro has no effect unless @code{DONT_USE_BUILTIN_SETJMP} is also
-defined. Define this macro if the default size of @code{jmp_buf} buffer
-for the @code{setjmp}/@code{longjmp}-based exception handling mechanism
-is not large enough, or if it is much too large.
-The default size is @code{FIRST_PSEUDO_REGISTER * sizeof(void *)}.
-@end defmac
-
-@defmac DWARF_CIE_DATA_ALIGNMENT
-This macro need only be defined if the target might save registers in the
-function prologue at an offset to the stack pointer that is not aligned to
-@code{UNITS_PER_WORD}. The definition should be the negative minimum
-alignment if @code{STACK_GROWS_DOWNWARD} is true, and the positive
-minimum alignment otherwise. @xref{DWARF}. Only applicable if
-the target supports DWARF 2 frame unwind information.
-@end defmac
-
-@hook TARGET_TERMINATE_DW2_EH_FRAME_INFO
-
-@hook TARGET_DWARF_REGISTER_SPAN
-
-@hook TARGET_DWARF_FRAME_REG_MODE
-
-@hook TARGET_INIT_DWARF_REG_SIZES_EXTRA
-
-@hook TARGET_ASM_TTYPE
-
-@hook TARGET_ARM_EABI_UNWINDER
-
-@node Alignment Output
-@subsection Assembler Commands for Alignment
-
-@c prevent bad page break with this line
-This describes commands for alignment.
-
-@defmac JUMP_ALIGN (@var{label})
-The alignment (log base 2) to put in front of @var{label}, which is
-a common destination of jumps and has no fallthru incoming edge.
-
-This macro need not be defined if you don't want any special alignment
-to be done at such a time. Most machine descriptions do not currently
-define the macro.
-
-Unless it's necessary to inspect the @var{label} parameter, it is better
-to set the variable @var{align_jumps} in the target's
-@code{TARGET_OPTION_OVERRIDE}. Otherwise, you should try to honor the user's
-selection in @var{align_jumps} in a @code{JUMP_ALIGN} implementation.
-@end defmac
-
-@defmac LABEL_ALIGN_AFTER_BARRIER (@var{label})
-The alignment (log base 2) to put in front of @var{label}, which follows
-a @code{BARRIER}.
-
-This macro need not be defined if you don't want any special alignment
-to be done at such a time. Most machine descriptions do not currently
-define the macro.
-@end defmac
-
-@defmac LOOP_ALIGN (@var{label})
-The alignment (log base 2) to put in front of @var{label} that heads
-a frequently executed basic block (usually the header of a loop).
-
-This macro need not be defined if you don't want any special alignment
-to be done at such a time. Most machine descriptions do not currently
-define the macro.
-
-Unless it's necessary to inspect the @var{label} parameter, it is better
-to set the variable @code{align_loops} in the target's
-@code{TARGET_OPTION_OVERRIDE}. Otherwise, you should try to honor the user's
-selection in @code{align_loops} in a @code{LOOP_ALIGN} implementation.
-@end defmac
-
-@defmac LABEL_ALIGN (@var{label})
-The alignment (log base 2) to put in front of @var{label}.
-If @code{LABEL_ALIGN_AFTER_BARRIER} / @code{LOOP_ALIGN} specify a different alignment,
-the maximum of the specified values is used.
-
-Unless it's necessary to inspect the @var{label} parameter, it is better
-to set the variable @code{align_labels} in the target's
-@code{TARGET_OPTION_OVERRIDE}. Otherwise, you should try to honor the user's
-selection in @code{align_labels} in a @code{LABEL_ALIGN} implementation.
-@end defmac
-
-@defmac ASM_OUTPUT_SKIP (@var{stream}, @var{nbytes})
-A C statement to output to the stdio stream @var{stream} an assembler
-instruction to advance the location counter by @var{nbytes} bytes.
-Those bytes should be zero when loaded. @var{nbytes} will be a C
-expression of type @code{unsigned HOST_WIDE_INT}.
-@end defmac
-
-@defmac ASM_NO_SKIP_IN_TEXT
-Define this macro if @code{ASM_OUTPUT_SKIP} should not be used in the
-text section because it fails to put zeros in the bytes that are skipped.
-This is true on many Unix systems, where the pseudo--op to skip bytes
-produces no-op instructions rather than zeros when used in the text
-section.
-@end defmac
-
-@defmac ASM_OUTPUT_ALIGN (@var{stream}, @var{power})
-A C statement to output to the stdio stream @var{stream} an assembler
-command to advance the location counter to a multiple of 2 to the
-@var{power} bytes. @var{power} will be a C expression of type @code{int}.
-@end defmac
-
-@defmac ASM_OUTPUT_ALIGN_WITH_NOP (@var{stream}, @var{power})
-Like @code{ASM_OUTPUT_ALIGN}, except that the ``nop'' instruction is used
-for padding, if necessary.
-@end defmac
-
-@defmac ASM_OUTPUT_MAX_SKIP_ALIGN (@var{stream}, @var{power}, @var{max_skip})
-A C statement to output to the stdio stream @var{stream} an assembler
-command to advance the location counter to a multiple of 2 to the
-@var{power} bytes, but only if @var{max_skip} or fewer bytes are needed to
-satisfy the alignment request. @var{power} and @var{max_skip} will be
-a C expression of type @code{int}.
-@end defmac
-
-@need 3000
-@node Debugging Info
-@section Controlling Debugging Information Format
-
-@c prevent bad page break with this line
-This describes how to specify debugging information.
-
-@menu
-* All Debuggers:: Macros that affect all debugging formats uniformly.
-* DWARF:: Macros for DWARF format.
-* VMS Debug:: Macros for VMS debug format.
-* CTF Debug:: Macros for CTF debug format.
-* BTF Debug:: Macros for BTF debug format.
-@end menu
-
-@node All Debuggers
-@subsection Macros Affecting All Debugging Formats
-
-@c prevent bad page break with this line
-These macros affect all debugging formats.
-
-@defmac DEBUGGER_REGNO (@var{regno})
-A C expression that returns the debugger register number for the compiler
-register number @var{regno}. In the default macro provided, the value
-of this expression will be @var{regno} itself. But sometimes there are
-some registers that the compiler knows about and debugger does not, or vice
-versa. In such cases, some register may need to have one number in the
-compiler and another for debugger@.
-
-If two registers have consecutive numbers inside GCC, and they can be
-used as a pair to hold a multiword value, then they @emph{must} have
-consecutive numbers after renumbering with @code{DEBUGGER_REGNO}.
-Otherwise, debuggers will be unable to access such a pair, because they
-expect register pairs to be consecutive in their own numbering scheme.
-
-If you find yourself defining @code{DEBUGGER_REGNO} in way that
-does not preserve register pairs, then what you must do instead is
-redefine the actual register numbering scheme.
-@end defmac
-
-@defmac DEBUGGER_AUTO_OFFSET (@var{x})
-A C expression that returns the integer offset value for an automatic
-variable having address @var{x} (an RTL expression). The default
-computation assumes that @var{x} is based on the frame-pointer and
-gives the offset from the frame-pointer. This is required for targets
-that produce debugging output for debugger and allow the frame-pointer to be
-eliminated when the @option{-g} option is used.
-@end defmac
-
-@defmac DEBUGGER_ARG_OFFSET (@var{offset}, @var{x})
-A C expression that returns the integer offset value for an argument
-having address @var{x} (an RTL expression). The nominal offset is
-@var{offset}.
-@end defmac
-
-@defmac PREFERRED_DEBUGGING_TYPE
-A C expression that returns the type of debugging output GCC should
-produce when the user specifies just @option{-g}. Define
-this if you have arranged for GCC to support more than one format of
-debugging output. Currently, the allowable values are
-@code{DWARF2_DEBUG}, @code{VMS_DEBUG},
-and @code{VMS_AND_DWARF2_DEBUG}.
-
-When the user specifies @option{-ggdb}, GCC normally also uses the
-value of this macro to select the debugging output format, but with two
-exceptions. If @code{DWARF2_DEBUGGING_INFO} is defined, GCC uses the
-value @code{DWARF2_DEBUG}.
-
-The value of this macro only affects the default debugging output; the
-user can always get a specific type of output by using @option{-gdwarf-2},
-or @option{-gvms}.
-@end defmac
-
-@defmac DEFAULT_GDB_EXTENSIONS
-Define this macro to control whether GCC should by default generate
-GDB's extended version of debugging information. If you don't define the
-macro, the default is 1: always generate the extended information
-if there is any occasion to.
-@end defmac
-
-@need 2000
-@node DWARF
-@subsection Macros for DWARF Output
-
-@c prevent bad page break with this line
-Here are macros for DWARF output.
-
-@defmac DWARF2_DEBUGGING_INFO
-Define this macro if GCC should produce dwarf version 2 format
-debugging output in response to the @option{-g} option.
-
-To support optional call frame debugging information, you must also
-define @code{INCOMING_RETURN_ADDR_RTX} and either set
-@code{RTX_FRAME_RELATED_P} on the prologue insns if you use RTL for the
-prologue, or call @code{dwarf2out_def_cfa} and @code{dwarf2out_reg_save}
-as appropriate from @code{TARGET_ASM_FUNCTION_PROLOGUE} if you don't.
-@end defmac
-
-@hook TARGET_DWARF_CALLING_CONVENTION
-
-@defmac DWARF2_FRAME_INFO
-Define this macro to a nonzero value if GCC should always output
-Dwarf 2 frame information. If @code{TARGET_EXCEPT_UNWIND_INFO}
-(@pxref{Exception Region Output}) returns @code{UI_DWARF2}, and
-exceptions are enabled, GCC will output this information not matter
-how you define @code{DWARF2_FRAME_INFO}.
-@end defmac
-
-@hook TARGET_DEBUG_UNWIND_INFO
-
-@defmac DWARF2_ASM_LINE_DEBUG_INFO
-Define this macro to be a nonzero value if the assembler can generate Dwarf 2
-line debug info sections. This will result in much more compact line number
-tables, and hence is desirable if it works.
-@end defmac
-
-@defmac DWARF2_ASM_VIEW_DEBUG_INFO
-Define this macro to be a nonzero value if the assembler supports view
-assignment and verification in @code{.loc}. If it does not, but the
-user enables location views, the compiler may have to fallback to
-internal line number tables.
-@end defmac
-
-@hook TARGET_RESET_LOCATION_VIEW
-
-@hook TARGET_WANT_DEBUG_PUB_SECTIONS
-
-@hook TARGET_DELAY_SCHED2
-
-@hook TARGET_DELAY_VARTRACK
-
-@hook TARGET_NO_REGISTER_ALLOCATION
-
-@defmac ASM_OUTPUT_DWARF_DELTA (@var{stream}, @var{size}, @var{label1}, @var{label2})
-A C statement to issue assembly directives that create a difference
-@var{lab1} minus @var{lab2}, using an integer of the given @var{size}.
-@end defmac
-
-@defmac ASM_OUTPUT_DWARF_VMS_DELTA (@var{stream}, @var{size}, @var{label1}, @var{label2})
-A C statement to issue assembly directives that create a difference
-between the two given labels in system defined units, e.g.@: instruction
-slots on IA64 VMS, using an integer of the given size.
-@end defmac
-
-@defmac ASM_OUTPUT_DWARF_OFFSET (@var{stream}, @var{size}, @var{label}, @var{offset}, @var{section})
-A C statement to issue assembly directives that create a
-section-relative reference to the given @var{label} plus @var{offset}, using
-an integer of the given @var{size}. The label is known to be defined in the
-given @var{section}.
-@end defmac
-
-@defmac ASM_OUTPUT_DWARF_PCREL (@var{stream}, @var{size}, @var{label})
-A C statement to issue assembly directives that create a self-relative
-reference to the given @var{label}, using an integer of the given @var{size}.
-@end defmac
-
-@defmac ASM_OUTPUT_DWARF_DATAREL (@var{stream}, @var{size}, @var{label})
-A C statement to issue assembly directives that create a reference to the
-given @var{label} relative to the dbase, using an integer of the given @var{size}.
-@end defmac
-
-@defmac ASM_OUTPUT_DWARF_TABLE_REF (@var{label})
-A C statement to issue assembly directives that create a reference to
-the DWARF table identifier @var{label} from the current section. This
-is used on some systems to avoid garbage collecting a DWARF table which
-is referenced by a function.
-@end defmac
-
-@hook TARGET_ASM_OUTPUT_DWARF_DTPREL
-
-@need 2000
-@node VMS Debug
-@subsection Macros for VMS Debug Format
-
-@c prevent bad page break with this line
-Here are macros for VMS debug format.
-
-@defmac VMS_DEBUGGING_INFO
-Define this macro if GCC should produce debugging output for VMS
-in response to the @option{-g} option. The default behavior for VMS
-is to generate minimal debug info for a traceback in the absence of
-@option{-g} unless explicitly overridden with @option{-g0}. This
-behavior is controlled by @code{TARGET_OPTION_OPTIMIZATION} and
-@code{TARGET_OPTION_OVERRIDE}.
-@end defmac
-
-@need 2000
-@node CTF Debug
-@subsection Macros for CTF Debug Format
-
-@c prevent bad page break with this line
-Here are macros for CTF debug format.
-
-@defmac CTF_DEBUGGING_INFO
-Define this macro if GCC should produce debugging output in CTF debug
-format in response to the @option{-gctf} option.
-@end defmac
-
-@need 2000
-@node BTF Debug
-@subsection Macros for BTF Debug Format
-
-@c prevent bad page break with this line
-Here are macros for BTF debug format.
-
-@defmac BTF_DEBUGGING_INFO
-Define this macro if GCC should produce debugging output in BTF debug
-format in response to the @option{-gbtf} option.
-@end defmac
-
-@node Floating Point
-@section Cross Compilation and Floating Point
-@cindex cross compilation and floating point
-@cindex floating point and cross compilation
-
-While all modern machines use twos-complement representation for integers,
-there are a variety of representations for floating point numbers. This
-means that in a cross-compiler the representation of floating point numbers
-in the compiled program may be different from that used in the machine
-doing the compilation.
-
-Because different representation systems may offer different amounts of
-range and precision, all floating point constants must be represented in
-the target machine's format. Therefore, the cross compiler cannot
-safely use the host machine's floating point arithmetic; it must emulate
-the target's arithmetic. To ensure consistency, GCC always uses
-emulation to work with floating point values, even when the host and
-target floating point formats are identical.
-
-The following macros are provided by @file{real.h} for the compiler to
-use. All parts of the compiler which generate or optimize
-floating-point calculations must use these macros. They may evaluate
-their operands more than once, so operands must not have side effects.
-
-@defmac REAL_VALUE_TYPE
-The C data type to be used to hold a floating point value in the target
-machine's format. Typically this is a @code{struct} containing an
-array of @code{HOST_WIDE_INT}, but all code should treat it as an opaque
-quantity.
-@end defmac
-
-@deftypefn Macro HOST_WIDE_INT REAL_VALUE_FIX (REAL_VALUE_TYPE @var{x})
-Truncates @var{x} to a signed integer, rounding toward zero.
-@end deftypefn
-
-@deftypefn Macro {unsigned HOST_WIDE_INT} REAL_VALUE_UNSIGNED_FIX (REAL_VALUE_TYPE @var{x})
-Truncates @var{x} to an unsigned integer, rounding toward zero. If
-@var{x} is negative, returns zero.
-@end deftypefn
-
-@deftypefn Macro REAL_VALUE_TYPE REAL_VALUE_ATOF (const char *@var{string}, machine_mode @var{mode})
-Converts @var{string} into a floating point number in the target machine's
-representation for mode @var{mode}. This routine can handle both
-decimal and hexadecimal floating point constants, using the syntax
-defined by the C language for both.
-@end deftypefn
-
-@deftypefn Macro int REAL_VALUE_NEGATIVE (REAL_VALUE_TYPE @var{x})
-Returns 1 if @var{x} is negative (including negative zero), 0 otherwise.
-@end deftypefn
-
-@deftypefn Macro int REAL_VALUE_ISINF (REAL_VALUE_TYPE @var{x})
-Determines whether @var{x} represents infinity (positive or negative).
-@end deftypefn
-
-@deftypefn Macro int REAL_VALUE_ISNAN (REAL_VALUE_TYPE @var{x})
-Determines whether @var{x} represents a ``NaN'' (not-a-number).
-@end deftypefn
-
-@deftypefn Macro REAL_VALUE_TYPE REAL_VALUE_NEGATE (REAL_VALUE_TYPE @var{x})
-Returns the negative of the floating point value @var{x}.
-@end deftypefn
-
-@deftypefn Macro REAL_VALUE_TYPE REAL_VALUE_ABS (REAL_VALUE_TYPE @var{x})
-Returns the absolute value of @var{x}.
-@end deftypefn
-
-@node Mode Switching
-@section Mode Switching Instructions
-@cindex mode switching
-The following macros control mode switching optimizations:
-
-@defmac OPTIMIZE_MODE_SWITCHING (@var{entity})
-Define this macro if the port needs extra instructions inserted for mode
-switching in an optimizing compilation.
-
-For an example, the SH4 can perform both single and double precision
-floating point operations, but to perform a single precision operation,
-the FPSCR PR bit has to be cleared, while for a double precision
-operation, this bit has to be set. Changing the PR bit requires a general
-purpose register as a scratch register, hence these FPSCR sets have to
-be inserted before reload, i.e.@: you cannot put this into instruction emitting
-or @code{TARGET_MACHINE_DEPENDENT_REORG}.
-
-You can have multiple entities that are mode-switched, and select at run time
-which entities actually need it. @code{OPTIMIZE_MODE_SWITCHING} should
-return nonzero for any @var{entity} that needs mode-switching.
-If you define this macro, you also have to define
-@code{NUM_MODES_FOR_MODE_SWITCHING}, @code{TARGET_MODE_NEEDED},
-@code{TARGET_MODE_PRIORITY} and @code{TARGET_MODE_EMIT}.
-@code{TARGET_MODE_AFTER}, @code{TARGET_MODE_ENTRY}, and @code{TARGET_MODE_EXIT}
-are optional.
-@end defmac
-
-@defmac NUM_MODES_FOR_MODE_SWITCHING
-If you define @code{OPTIMIZE_MODE_SWITCHING}, you have to define this as
-initializer for an array of integers. Each initializer element
-N refers to an entity that needs mode switching, and specifies the number
-of different modes that might need to be set for this entity.
-The position of the initializer in the initializer---starting counting at
-zero---determines the integer that is used to refer to the mode-switched
-entity in question.
-In macros that take mode arguments / yield a mode result, modes are
-represented as numbers 0 @dots{} N @minus{} 1. N is used to specify that no mode
-switch is needed / supplied.
-@end defmac
-
-@hook TARGET_MODE_EMIT
-
-@hook TARGET_MODE_NEEDED
-
-@hook TARGET_MODE_AFTER
-
-@hook TARGET_MODE_ENTRY
-
-@hook TARGET_MODE_EXIT
-
-@hook TARGET_MODE_PRIORITY
-
-@node Target Attributes
-@section Defining target-specific uses of @code{__attribute__}
-@cindex target attributes
-@cindex machine attributes
-@cindex attributes, target-specific
-
-Target-specific attributes may be defined for functions, data and types.
-These are described using the following target hooks; they also need to
-be documented in @file{extend.texi}.
-
-@hook TARGET_ATTRIBUTE_TABLE
-
-@hook TARGET_ATTRIBUTE_TAKES_IDENTIFIER_P
-
-@hook TARGET_COMP_TYPE_ATTRIBUTES
-
-@hook TARGET_SET_DEFAULT_TYPE_ATTRIBUTES
-
-@hook TARGET_MERGE_TYPE_ATTRIBUTES
-
-@hook TARGET_MERGE_DECL_ATTRIBUTES
-
-@hook TARGET_VALID_DLLIMPORT_ATTRIBUTE_P
-
-@defmac TARGET_DECLSPEC
-Define this macro to a nonzero value if you want to treat
-@code{__declspec(X)} as equivalent to @code{__attribute((X))}. By
-default, this behavior is enabled only for targets that define
-@code{TARGET_DLLIMPORT_DECL_ATTRIBUTES}. The current implementation
-of @code{__declspec} is via a built-in macro, but you should not rely
-on this implementation detail.
-@end defmac
-
-@hook TARGET_INSERT_ATTRIBUTES
-
-@hook TARGET_HANDLE_GENERIC_ATTRIBUTE
-
-@hook TARGET_FUNCTION_ATTRIBUTE_INLINABLE_P
-
-@hook TARGET_OPTION_VALID_ATTRIBUTE_P
-
-@hook TARGET_OPTION_SAVE
-
-@hook TARGET_OPTION_RESTORE
-
-@hook TARGET_OPTION_POST_STREAM_IN
-
-@hook TARGET_OPTION_PRINT
-
-@hook TARGET_OPTION_PRAGMA_PARSE
-
-@hook TARGET_OPTION_OVERRIDE
-
-@hook TARGET_OPTION_FUNCTION_VERSIONS
-
-@hook TARGET_CAN_INLINE_P
-
-@hook TARGET_UPDATE_IPA_FN_TARGET_INFO
-
-@hook TARGET_NEED_IPA_FN_TARGET_INFO
-
-@hook TARGET_RELAYOUT_FUNCTION
-
-@node Emulated TLS
-@section Emulating TLS
-@cindex Emulated TLS
-
-For targets whose psABI does not provide Thread Local Storage via
-specific relocations and instruction sequences, an emulation layer is
-used. A set of target hooks allows this emulation layer to be
-configured for the requirements of a particular target. For instance
-the psABI may in fact specify TLS support in terms of an emulation
-layer.
-
-The emulation layer works by creating a control object for every TLS
-object. To access the TLS object, a lookup function is provided
-which, when given the address of the control object, will return the
-address of the current thread's instance of the TLS object.
-
-@hook TARGET_EMUTLS_GET_ADDRESS
-
-@hook TARGET_EMUTLS_REGISTER_COMMON
-
-@hook TARGET_EMUTLS_VAR_SECTION
-
-@hook TARGET_EMUTLS_TMPL_SECTION
-
-@hook TARGET_EMUTLS_VAR_PREFIX
-
-@hook TARGET_EMUTLS_TMPL_PREFIX
-
-@hook TARGET_EMUTLS_VAR_FIELDS
-
-@hook TARGET_EMUTLS_VAR_INIT
-
-@hook TARGET_EMUTLS_VAR_ALIGN_FIXED
-
-@hook TARGET_EMUTLS_DEBUG_FORM_TLS_ADDRESS
-
-@node MIPS Coprocessors
-@section Defining coprocessor specifics for MIPS targets.
-@cindex MIPS coprocessor-definition macros
-
-The MIPS specification allows MIPS implementations to have as many as 4
-coprocessors, each with as many as 32 private registers. GCC supports
-accessing these registers and transferring values between the registers
-and memory using asm-ized variables. For example:
-
-@smallexample
- register unsigned int cp0count asm ("c0r1");
- unsigned int d;
-
- d = cp0count + 3;
-@end smallexample
-
-(``c0r1'' is the default name of register 1 in coprocessor 0; alternate
-names may be added as described below, or the default names may be
-overridden entirely in @code{SUBTARGET_CONDITIONAL_REGISTER_USAGE}.)
-
-Coprocessor registers are assumed to be epilogue-used; sets to them will
-be preserved even if it does not appear that the register is used again
-later in the function.
-
-Another note: according to the MIPS spec, coprocessor 1 (if present) is
-the FPU@. One accesses COP1 registers through standard mips
-floating-point support; they are not included in this mechanism.
-
-@node PCH Target
-@section Parameters for Precompiled Header Validity Checking
-@cindex parameters, precompiled headers
-
-@hook TARGET_GET_PCH_VALIDITY
-
-@hook TARGET_PCH_VALID_P
-
-@hook TARGET_CHECK_PCH_TARGET_FLAGS
-
-@hook TARGET_PREPARE_PCH_SAVE
-
-@node C++ ABI
-@section C++ ABI parameters
-@cindex parameters, c++ abi
-
-@hook TARGET_CXX_GUARD_TYPE
-
-@hook TARGET_CXX_GUARD_MASK_BIT
-
-@hook TARGET_CXX_GET_COOKIE_SIZE
-
-@hook TARGET_CXX_COOKIE_HAS_SIZE
-
-@hook TARGET_CXX_IMPORT_EXPORT_CLASS
-
-@hook TARGET_CXX_CDTOR_RETURNS_THIS
-
-@hook TARGET_CXX_KEY_METHOD_MAY_BE_INLINE
-
-@hook TARGET_CXX_DETERMINE_CLASS_DATA_VISIBILITY
-
-@hook TARGET_CXX_CLASS_DATA_ALWAYS_COMDAT
-
-@hook TARGET_CXX_LIBRARY_RTTI_COMDAT
-
-@hook TARGET_CXX_USE_AEABI_ATEXIT
-
-@hook TARGET_CXX_USE_ATEXIT_FOR_CXA_ATEXIT
-
-@hook TARGET_CXX_ADJUST_CLASS_AT_DEFINITION
-
-@hook TARGET_CXX_DECL_MANGLING_CONTEXT
-
-@node D Language and ABI
-@section D ABI parameters
-@cindex parameters, d abi
-
-@hook TARGET_D_CPU_VERSIONS
-
-@hook TARGET_D_OS_VERSIONS
-
-@hook TARGET_D_REGISTER_CPU_TARGET_INFO
-
-@hook TARGET_D_REGISTER_OS_TARGET_INFO
-
-@hook TARGET_D_MINFO_SECTION
-
-@hook TARGET_D_MINFO_SECTION_START
-
-@hook TARGET_D_MINFO_SECTION_END
-
-@hook TARGET_D_HAS_STDCALL_CONVENTION
-
-@hook TARGET_D_TEMPLATES_ALWAYS_COMDAT
-
-@node Named Address Spaces
-@section Adding support for named address spaces
-@cindex named address spaces
-
-The draft technical report of the ISO/IEC JTC1 S22 WG14 N1275
-standards committee, @cite{Programming Languages - C - Extensions to
-support embedded processors}, specifies a syntax for embedded
-processors to specify alternate address spaces. You can configure a
-GCC port to support section 5.1 of the draft report to add support for
-address spaces other than the default address space. These address
-spaces are new keywords that are similar to the @code{volatile} and
-@code{const} type attributes.
-
-Pointers to named address spaces can have a different size than
-pointers to the generic address space.
-
-For example, the SPU port uses the @code{__ea} address space to refer
-to memory in the host processor, rather than memory local to the SPU
-processor. Access to memory in the @code{__ea} address space involves
-issuing DMA operations to move data between the host processor and the
-local processor memory address space. Pointers in the @code{__ea}
-address space are either 32 bits or 64 bits based on the
-@option{-mea32} or @option{-mea64} switches (native SPU pointers are
-always 32 bits).
-
-Internally, address spaces are represented as a small integer in the
-range 0 to 15 with address space 0 being reserved for the generic
-address space.
-
-To register a named address space qualifier keyword with the C front end,
-the target may call the @code{c_register_addr_space} routine. For example,
-the SPU port uses the following to declare @code{__ea} as the keyword for
-named address space #1:
-@smallexample
-#define ADDR_SPACE_EA 1
-c_register_addr_space ("__ea", ADDR_SPACE_EA);
-@end smallexample
-
-@hook TARGET_ADDR_SPACE_POINTER_MODE
-
-@hook TARGET_ADDR_SPACE_ADDRESS_MODE
-
-@hook TARGET_ADDR_SPACE_VALID_POINTER_MODE
-
-@hook TARGET_ADDR_SPACE_LEGITIMATE_ADDRESS_P
-
-@hook TARGET_ADDR_SPACE_LEGITIMIZE_ADDRESS
-
-@hook TARGET_ADDR_SPACE_SUBSET_P
-
-@hook TARGET_ADDR_SPACE_ZERO_ADDRESS_VALID
-
-@hook TARGET_ADDR_SPACE_CONVERT
-
-@hook TARGET_ADDR_SPACE_DEBUG
-
-@hook TARGET_ADDR_SPACE_DIAGNOSE_USAGE
-
-@node Misc
-@section Miscellaneous Parameters
-@cindex parameters, miscellaneous
-
-@c prevent bad page break with this line
-Here are several miscellaneous parameters.
-
-@defmac HAS_LONG_COND_BRANCH
-Define this boolean macro to indicate whether or not your architecture
-has conditional branches that can span all of memory. It is used in
-conjunction with an optimization that partitions hot and cold basic
-blocks into separate sections of the executable. If this macro is
-set to false, gcc will convert any conditional branches that attempt
-to cross between sections into unconditional branches or indirect jumps.
-@end defmac
-
-@defmac HAS_LONG_UNCOND_BRANCH
-Define this boolean macro to indicate whether or not your architecture
-has unconditional branches that can span all of memory. It is used in
-conjunction with an optimization that partitions hot and cold basic
-blocks into separate sections of the executable. If this macro is
-set to false, gcc will convert any unconditional branches that attempt
-to cross between sections into indirect jumps.
-@end defmac
-
-@defmac CASE_VECTOR_MODE
-An alias for a machine mode name. This is the machine mode that
-elements of a jump-table should have.
-@end defmac
-
-@defmac CASE_VECTOR_SHORTEN_MODE (@var{min_offset}, @var{max_offset}, @var{body})
-Optional: return the preferred mode for an @code{addr_diff_vec}
-when the minimum and maximum offset are known. If you define this,
-it enables extra code in branch shortening to deal with @code{addr_diff_vec}.
-To make this work, you also have to define @code{INSN_ALIGN} and
-make the alignment for @code{addr_diff_vec} explicit.
-The @var{body} argument is provided so that the offset_unsigned and scale
-flags can be updated.
-@end defmac
-
-@defmac CASE_VECTOR_PC_RELATIVE
-Define this macro to be a C expression to indicate when jump-tables
-should contain relative addresses. You need not define this macro if
-jump-tables never contain relative addresses, or jump-tables should
-contain relative addresses only when @option{-fPIC} or @option{-fPIC}
-is in effect.
-@end defmac
-
-@hook TARGET_CASE_VALUES_THRESHOLD
-
-@defmac WORD_REGISTER_OPERATIONS
-Define this macro to 1 if operations between registers with integral mode
-smaller than a word are always performed on the entire register. To be
-more explicit, if you start with a pair of @code{word_mode} registers with
-known values and you do a subword, for example @code{QImode}, addition on
-the low part of the registers, then the compiler may consider that the
-result has a known value in @code{word_mode} too if the macro is defined
-to 1. Most RISC machines have this property and most CISC machines do not.
-@end defmac
-
-@hook TARGET_MIN_ARITHMETIC_PRECISION
-
-@defmac LOAD_EXTEND_OP (@var{mem_mode})
-Define this macro to be a C expression indicating when insns that read
-memory in @var{mem_mode}, an integral mode narrower than a word, set the
-bits outside of @var{mem_mode} to be either the sign-extension or the
-zero-extension of the data read. Return @code{SIGN_EXTEND} for values
-of @var{mem_mode} for which the
-insn sign-extends, @code{ZERO_EXTEND} for which it zero-extends, and
-@code{UNKNOWN} for other modes.
-
-This macro is not called with @var{mem_mode} non-integral or with a width
-greater than or equal to @code{BITS_PER_WORD}, so you may return any
-value in this case. Do not define this macro if it would always return
-@code{UNKNOWN}. On machines where this macro is defined, you will normally
-define it as the constant @code{SIGN_EXTEND} or @code{ZERO_EXTEND}.
-
-You may return a non-@code{UNKNOWN} value even if for some hard registers
-the sign extension is not performed, if for the @code{REGNO_REG_CLASS}
-of these hard registers @code{TARGET_CAN_CHANGE_MODE_CLASS} returns false
-when the @var{from} mode is @var{mem_mode} and the @var{to} mode is any
-integral mode larger than this but not larger than @code{word_mode}.
-
-You must return @code{UNKNOWN} if for some hard registers that allow this
-mode, @code{TARGET_CAN_CHANGE_MODE_CLASS} says that they cannot change to
-@code{word_mode}, but that they can change to another integral mode that
-is larger then @var{mem_mode} but still smaller than @code{word_mode}.
-@end defmac
-
-@defmac SHORT_IMMEDIATES_SIGN_EXTEND
-Define this macro to 1 if loading short immediate values into registers sign
-extends.
-@end defmac
-
-@hook TARGET_MIN_DIVISIONS_FOR_RECIP_MUL
-
-@defmac MOVE_MAX
-The maximum number of bytes that a single instruction can move quickly
-between memory and registers or between two memory locations.
-@end defmac
-
-@defmac MAX_MOVE_MAX
-The maximum number of bytes that a single instruction can move quickly
-between memory and registers or between two memory locations. If this
-is undefined, the default is @code{MOVE_MAX}. Otherwise, it is the
-constant value that is the largest value that @code{MOVE_MAX} can have
-at run-time.
-@end defmac
-
-@defmac SHIFT_COUNT_TRUNCATED
-A C expression that is nonzero if on this machine the number of bits
-actually used for the count of a shift operation is equal to the number
-of bits needed to represent the size of the object being shifted. When
-this macro is nonzero, the compiler will assume that it is safe to omit
-a sign-extend, zero-extend, and certain bitwise `and' instructions that
-truncates the count of a shift operation. On machines that have
-instructions that act on bit-fields at variable positions, which may
-include `bit test' instructions, a nonzero @code{SHIFT_COUNT_TRUNCATED}
-also enables deletion of truncations of the values that serve as
-arguments to bit-field instructions.
-
-If both types of instructions truncate the count (for shifts) and
-position (for bit-field operations), or if no variable-position bit-field
-instructions exist, you should define this macro.
-
-However, on some machines, such as the 80386 and the 680x0, truncation
-only applies to shift operations and not the (real or pretended)
-bit-field operations. Define @code{SHIFT_COUNT_TRUNCATED} to be zero on
-such machines. Instead, add patterns to the @file{md} file that include
-the implied truncation of the shift instructions.
-
-You need not define this macro if it would always have the value of zero.
-@end defmac
-
-@anchor{TARGET_SHIFT_TRUNCATION_MASK}
-@hook TARGET_SHIFT_TRUNCATION_MASK
-
-@hook TARGET_TRULY_NOOP_TRUNCATION
-
-@hook TARGET_MODE_REP_EXTENDED
-
-@hook TARGET_SETJMP_PRESERVES_NONVOLATILE_REGS_P
-
-@defmac STORE_FLAG_VALUE
-A C expression describing the value returned by a comparison operator
-with an integral mode and stored by a store-flag instruction
-(@samp{cstore@var{mode}4}) when the condition is true. This description must
-apply to @emph{all} the @samp{cstore@var{mode}4} patterns and all the
-comparison operators whose results have a @code{MODE_INT} mode.
-
-A value of 1 or @minus{}1 means that the instruction implementing the
-comparison operator returns exactly 1 or @minus{}1 when the comparison is true
-and 0 when the comparison is false. Otherwise, the value indicates
-which bits of the result are guaranteed to be 1 when the comparison is
-true. This value is interpreted in the mode of the comparison
-operation, which is given by the mode of the first operand in the
-@samp{cstore@var{mode}4} pattern. Either the low bit or the sign bit of
-@code{STORE_FLAG_VALUE} be on. Presently, only those bits are used by
-the compiler.
-
-If @code{STORE_FLAG_VALUE} is neither 1 or @minus{}1, the compiler will
-generate code that depends only on the specified bits. It can also
-replace comparison operators with equivalent operations if they cause
-the required bits to be set, even if the remaining bits are undefined.
-For example, on a machine whose comparison operators return an
-@code{SImode} value and where @code{STORE_FLAG_VALUE} is defined as
-@samp{0x80000000}, saying that just the sign bit is relevant, the
-expression
-
-@smallexample
-(ne:SI (and:SI @var{x} (const_int @var{power-of-2})) (const_int 0))
-@end smallexample
-
-@noindent
-can be converted to
-
-@smallexample
-(ashift:SI @var{x} (const_int @var{n}))
-@end smallexample
-
-@noindent
-where @var{n} is the appropriate shift count to move the bit being
-tested into the sign bit.
-
-There is no way to describe a machine that always sets the low-order bit
-for a true value, but does not guarantee the value of any other bits,
-but we do not know of any machine that has such an instruction. If you
-are trying to port GCC to such a machine, include an instruction to
-perform a logical-and of the result with 1 in the pattern for the
-comparison operators and let us know at @email{gcc@@gcc.gnu.org}.
-
-Often, a machine will have multiple instructions that obtain a value
-from a comparison (or the condition codes). Here are rules to guide the
-choice of value for @code{STORE_FLAG_VALUE}, and hence the instructions
-to be used:
-
-@itemize @bullet
-@item
-Use the shortest sequence that yields a valid definition for
-@code{STORE_FLAG_VALUE}. It is more efficient for the compiler to
-``normalize'' the value (convert it to, e.g., 1 or 0) than for the
-comparison operators to do so because there may be opportunities to
-combine the normalization with other operations.
-
-@item
-For equal-length sequences, use a value of 1 or @minus{}1, with @minus{}1 being
-slightly preferred on machines with expensive jumps and 1 preferred on
-other machines.
-
-@item
-As a second choice, choose a value of @samp{0x80000001} if instructions
-exist that set both the sign and low-order bits but do not define the
-others.
-
-@item
-Otherwise, use a value of @samp{0x80000000}.
-@end itemize
-
-Many machines can produce both the value chosen for
-@code{STORE_FLAG_VALUE} and its negation in the same number of
-instructions. On those machines, you should also define a pattern for
-those cases, e.g., one matching
-
-@smallexample
-(set @var{A} (neg:@var{m} (ne:@var{m} @var{B} @var{C})))
-@end smallexample
-
-Some machines can also perform @code{and} or @code{plus} operations on
-condition code values with less instructions than the corresponding
-@samp{cstore@var{mode}4} insn followed by @code{and} or @code{plus}. On those
-machines, define the appropriate patterns. Use the names @code{incscc}
-and @code{decscc}, respectively, for the patterns which perform
-@code{plus} or @code{minus} operations on condition code values. See
-@file{rs6000.md} for some examples. The GNU Superoptimizer can be used to
-find such instruction sequences on other machines.
-
-If this macro is not defined, the default value, 1, is used. You need
-not define @code{STORE_FLAG_VALUE} if the machine has no store-flag
-instructions, or if the value generated by these instructions is 1.
-@end defmac
-
-@defmac FLOAT_STORE_FLAG_VALUE (@var{mode})
-A C expression that gives a nonzero @code{REAL_VALUE_TYPE} value that is
-returned when comparison operators with floating-point results are true.
-Define this macro on machines that have comparison operations that return
-floating-point values. If there are no such operations, do not define
-this macro.
-@end defmac
-
-@defmac VECTOR_STORE_FLAG_VALUE (@var{mode})
-A C expression that gives an rtx representing the nonzero true element
-for vector comparisons. The returned rtx should be valid for the inner
-mode of @var{mode} which is guaranteed to be a vector mode. Define
-this macro on machines that have vector comparison operations that
-return a vector result. If there are no such operations, do not define
-this macro. Typically, this macro is defined as @code{const1_rtx} or
-@code{constm1_rtx}. This macro may return @code{NULL_RTX} to prevent
-the compiler optimizing such vector comparison operations for the
-given mode.
-@end defmac
-
-@defmac CLZ_DEFINED_VALUE_AT_ZERO (@var{mode}, @var{value})
-@defmacx CTZ_DEFINED_VALUE_AT_ZERO (@var{mode}, @var{value})
-A C expression that indicates whether the architecture defines a value
-for @code{clz} or @code{ctz} with a zero operand.
-A result of @code{0} indicates the value is undefined.
-If the value is defined for only the RTL expression, the macro should
-evaluate to @code{1}; if the value applies also to the corresponding optab
-entry (which is normally the case if it expands directly into
-the corresponding RTL), then the macro should evaluate to @code{2}.
-In the cases where the value is defined, @var{value} should be set to
-this value.
-
-If this macro is not defined, the value of @code{clz} or
-@code{ctz} at zero is assumed to be undefined.
-
-This macro must be defined if the target's expansion for @code{ffs}
-relies on a particular value to get correct results. Otherwise it
-is not necessary, though it may be used to optimize some corner cases, and
-to provide a default expansion for the @code{ffs} optab.
-
-Note that regardless of this macro the ``definedness'' of @code{clz}
-and @code{ctz} at zero do @emph{not} extend to the builtin functions
-visible to the user. Thus one may be free to adjust the value at will
-to match the target expansion of these operations without fear of
-breaking the API@.
-@end defmac
-
-@defmac Pmode
-An alias for the machine mode for pointers. On most machines, define
-this to be the integer mode corresponding to the width of a hardware
-pointer; @code{SImode} on 32-bit machine or @code{DImode} on 64-bit machines.
-On some machines you must define this to be one of the partial integer
-modes, such as @code{PSImode}.
-
-The width of @code{Pmode} must be at least as large as the value of
-@code{POINTER_SIZE}. If it is not equal, you must define the macro
-@code{POINTERS_EXTEND_UNSIGNED} to specify how pointers are extended
-to @code{Pmode}.
-@end defmac
-
-@defmac FUNCTION_MODE
-An alias for the machine mode used for memory references to functions
-being called, in @code{call} RTL expressions. On most CISC machines,
-where an instruction can begin at any byte address, this should be
-@code{QImode}. On most RISC machines, where all instructions have fixed
-size and alignment, this should be a mode with the same size and alignment
-as the machine instruction words - typically @code{SImode} or @code{HImode}.
-@end defmac
-
-@defmac STDC_0_IN_SYSTEM_HEADERS
-In normal operation, the preprocessor expands @code{__STDC__} to the
-constant 1, to signify that GCC conforms to ISO Standard C@. On some
-hosts, like Solaris, the system compiler uses a different convention,
-where @code{__STDC__} is normally 0, but is 1 if the user specifies
-strict conformance to the C Standard.
-
-Defining @code{STDC_0_IN_SYSTEM_HEADERS} makes GNU CPP follows the host
-convention when processing system header files, but when processing user
-files @code{__STDC__} will always expand to 1.
-@end defmac
-
-@hook TARGET_C_PREINCLUDE
-
-@hook TARGET_CXX_IMPLICIT_EXTERN_C
-
-@defmac SYSTEM_IMPLICIT_EXTERN_C
-Define this macro if the system header files do not support C++@.
-This macro handles system header files by pretending that system
-header files are enclosed in @samp{extern "C" @{@dots{}@}}.
-@end defmac
-
-@findex #pragma
-@findex pragma
-@defmac REGISTER_TARGET_PRAGMAS ()
-Define this macro if you want to implement any target-specific pragmas.
-If defined, it is a C expression which makes a series of calls to
-@code{c_register_pragma} or @code{c_register_pragma_with_expansion}
-for each pragma. The macro may also do any
-setup required for the pragmas.
-
-The primary reason to define this macro is to provide compatibility with
-other compilers for the same target. In general, we discourage
-definition of target-specific pragmas for GCC@.
-
-If the pragma can be implemented by attributes then you should consider
-defining the target hook @samp{TARGET_INSERT_ATTRIBUTES} as well.
-
-Preprocessor macros that appear on pragma lines are not expanded. All
-@samp{#pragma} directives that do not match any registered pragma are
-silently ignored, unless the user specifies @option{-Wunknown-pragmas}.
-@end defmac
-
-@deftypefun void c_register_pragma (const char *@var{space}, const char *@var{name}, void (*@var{callback}) (struct cpp_reader *))
-@deftypefunx void c_register_pragma_with_expansion (const char *@var{space}, const char *@var{name}, void (*@var{callback}) (struct cpp_reader *))
-
-Each call to @code{c_register_pragma} or
-@code{c_register_pragma_with_expansion} establishes one pragma. The
-@var{callback} routine will be called when the preprocessor encounters a
-pragma of the form
-
-@smallexample
-#pragma [@var{space}] @var{name} @dots{}
-@end smallexample
-
-@var{space} is the case-sensitive namespace of the pragma, or
-@code{NULL} to put the pragma in the global namespace. The callback
-routine receives @var{pfile} as its first argument, which can be passed
-on to cpplib's functions if necessary. You can lex tokens after the
-@var{name} by calling @code{pragma_lex}. Tokens that are not read by the
-callback will be silently ignored. The end of the line is indicated by
-a token of type @code{CPP_EOF}. Macro expansion occurs on the
-arguments of pragmas registered with
-@code{c_register_pragma_with_expansion} but not on the arguments of
-pragmas registered with @code{c_register_pragma}.
-
-Note that the use of @code{pragma_lex} is specific to the C and C++
-compilers. It will not work in the Java or Fortran compilers, or any
-other language compilers for that matter. Thus if @code{pragma_lex} is going
-to be called from target-specific code, it must only be done so when
-building the C and C++ compilers. This can be done by defining the
-variables @code{c_target_objs} and @code{cxx_target_objs} in the
-target entry in the @file{config.gcc} file. These variables should name
-the target-specific, language-specific object file which contains the
-code that uses @code{pragma_lex}. Note it will also be necessary to add a
-rule to the makefile fragment pointed to by @code{tmake_file} that shows
-how to build this object file.
-@end deftypefun
-
-@defmac HANDLE_PRAGMA_PACK_WITH_EXPANSION
-Define this macro if macros should be expanded in the
-arguments of @samp{#pragma pack}.
-@end defmac
-
-@defmac TARGET_DEFAULT_PACK_STRUCT
-If your target requires a structure packing default other than 0 (meaning
-the machine default), define this macro to the necessary value (in bytes).
-This must be a value that would also be valid to use with
-@samp{#pragma pack()} (that is, a small power of two).
-@end defmac
-
-@defmac DOLLARS_IN_IDENTIFIERS
-Define this macro to control use of the character @samp{$} in
-identifier names for the C family of languages. 0 means @samp{$} is
-not allowed by default; 1 means it is allowed. 1 is the default;
-there is no need to define this macro in that case.
-@end defmac
-
-@defmac INSN_SETS_ARE_DELAYED (@var{insn})
-Define this macro as a C expression that is nonzero if it is safe for the
-delay slot scheduler to place instructions in the delay slot of @var{insn},
-even if they appear to use a resource set or clobbered in @var{insn}.
-@var{insn} is always a @code{jump_insn} or an @code{insn}; GCC knows that
-every @code{call_insn} has this behavior. On machines where some @code{insn}
-or @code{jump_insn} is really a function call and hence has this behavior,
-you should define this macro.
-
-You need not define this macro if it would always return zero.
-@end defmac
-
-@defmac INSN_REFERENCES_ARE_DELAYED (@var{insn})
-Define this macro as a C expression that is nonzero if it is safe for the
-delay slot scheduler to place instructions in the delay slot of @var{insn},
-even if they appear to set or clobber a resource referenced in @var{insn}.
-@var{insn} is always a @code{jump_insn} or an @code{insn}. On machines where
-some @code{insn} or @code{jump_insn} is really a function call and its operands
-are registers whose use is actually in the subroutine it calls, you should
-define this macro. Doing so allows the delay slot scheduler to move
-instructions which copy arguments into the argument registers into the delay
-slot of @var{insn}.
-
-You need not define this macro if it would always return zero.
-@end defmac
-
-@defmac MULTIPLE_SYMBOL_SPACES
-Define this macro as a C expression that is nonzero if, in some cases,
-global symbols from one translation unit may not be bound to undefined
-symbols in another translation unit without user intervention. For
-instance, under Microsoft Windows symbols must be explicitly imported
-from shared libraries (DLLs).
-
-You need not define this macro if it would always evaluate to zero.
-@end defmac
-
-@hook TARGET_MD_ASM_ADJUST
-
-@defmac MATH_LIBRARY
-Define this macro as a C string constant for the linker argument to link
-in the system math library, minus the initial @samp{"-l"}, or
-@samp{""} if the target does not have a
-separate math library.
-
-You need only define this macro if the default of @samp{"m"} is wrong.
-@end defmac
-
-@defmac LIBRARY_PATH_ENV
-Define this macro as a C string constant for the environment variable that
-specifies where the linker should look for libraries.
-
-You need only define this macro if the default of @samp{"LIBRARY_PATH"}
-is wrong.
-@end defmac
-
-@defmac TARGET_POSIX_IO
-Define this macro if the target supports the following POSIX@ file
-functions, access, mkdir and file locking with fcntl / F_SETLKW@.
-Defining @code{TARGET_POSIX_IO} will enable the test coverage code
-to use file locking when exiting a program, which avoids race conditions
-if the program has forked. It will also create directories at run-time
-for cross-profiling.
-@end defmac
-
-@defmac MAX_CONDITIONAL_EXECUTE
-
-A C expression for the maximum number of instructions to execute via
-conditional execution instructions instead of a branch. A value of
-@code{BRANCH_COST}+1 is the default.
-@end defmac
-
-@defmac IFCVT_MODIFY_TESTS (@var{ce_info}, @var{true_expr}, @var{false_expr})
-Used if the target needs to perform machine-dependent modifications on the
-conditionals used for turning basic blocks into conditionally executed code.
-@var{ce_info} points to a data structure, @code{struct ce_if_block}, which
-contains information about the currently processed blocks. @var{true_expr}
-and @var{false_expr} are the tests that are used for converting the
-then-block and the else-block, respectively. Set either @var{true_expr} or
-@var{false_expr} to a null pointer if the tests cannot be converted.
-@end defmac
-
-@defmac IFCVT_MODIFY_MULTIPLE_TESTS (@var{ce_info}, @var{bb}, @var{true_expr}, @var{false_expr})
-Like @code{IFCVT_MODIFY_TESTS}, but used when converting more complicated
-if-statements into conditions combined by @code{and} and @code{or} operations.
-@var{bb} contains the basic block that contains the test that is currently
-being processed and about to be turned into a condition.
-@end defmac
-
-@defmac IFCVT_MODIFY_INSN (@var{ce_info}, @var{pattern}, @var{insn})
-A C expression to modify the @var{PATTERN} of an @var{INSN} that is to
-be converted to conditional execution format. @var{ce_info} points to
-a data structure, @code{struct ce_if_block}, which contains information
-about the currently processed blocks.
-@end defmac
-
-@defmac IFCVT_MODIFY_FINAL (@var{ce_info})
-A C expression to perform any final machine dependent modifications in
-converting code to conditional execution. The involved basic blocks
-can be found in the @code{struct ce_if_block} structure that is pointed
-to by @var{ce_info}.
-@end defmac
-
-@defmac IFCVT_MODIFY_CANCEL (@var{ce_info})
-A C expression to cancel any machine dependent modifications in
-converting code to conditional execution. The involved basic blocks
-can be found in the @code{struct ce_if_block} structure that is pointed
-to by @var{ce_info}.
-@end defmac
-
-@defmac IFCVT_MACHDEP_INIT (@var{ce_info})
-A C expression to initialize any machine specific data for if-conversion
-of the if-block in the @code{struct ce_if_block} structure that is pointed
-to by @var{ce_info}.
-@end defmac
-
-@hook TARGET_MACHINE_DEPENDENT_REORG
-
-@hook TARGET_INIT_BUILTINS
-
-@hook TARGET_BUILTIN_DECL
-
-@hook TARGET_EXPAND_BUILTIN
-
-@hook TARGET_RESOLVE_OVERLOADED_BUILTIN
-
-@hook TARGET_CHECK_BUILTIN_CALL
-
-@hook TARGET_FOLD_BUILTIN
-
-@hook TARGET_GIMPLE_FOLD_BUILTIN
-
-@hook TARGET_COMPARE_VERSION_PRIORITY
-
-@hook TARGET_GET_FUNCTION_VERSIONS_DISPATCHER
-
-@hook TARGET_GENERATE_VERSION_DISPATCHER_BODY
-
-@hook TARGET_PREDICT_DOLOOP_P
-
-@hook TARGET_HAVE_COUNT_REG_DECR_P
-
-@hook TARGET_DOLOOP_COST_FOR_GENERIC
-
-@hook TARGET_DOLOOP_COST_FOR_ADDRESS
-
-@hook TARGET_CAN_USE_DOLOOP_P
-
-@hook TARGET_INVALID_WITHIN_DOLOOP
-
-@hook TARGET_PREFERRED_DOLOOP_MODE
-
-@hook TARGET_LEGITIMATE_COMBINED_INSN
-
-@hook TARGET_CAN_FOLLOW_JUMP
-
-@hook TARGET_COMMUTATIVE_P
-
-@hook TARGET_ALLOCATE_INITIAL_VALUE
-
-@hook TARGET_UNSPEC_MAY_TRAP_P
-
-@hook TARGET_SET_CURRENT_FUNCTION
-
-@defmac TARGET_OBJECT_SUFFIX
-Define this macro to be a C string representing the suffix for object
-files on your target machine. If you do not define this macro, GCC will
-use @samp{.o} as the suffix for object files.
-@end defmac
-
-@defmac TARGET_EXECUTABLE_SUFFIX
-Define this macro to be a C string representing the suffix to be
-automatically added to executable files on your target machine. If you
-do not define this macro, GCC will use the null string as the suffix for
-executable files.
-@end defmac
-
-@defmac COLLECT_EXPORT_LIST
-If defined, @code{collect2} will scan the individual object files
-specified on its command line and create an export list for the linker.
-Define this macro for systems like AIX, where the linker discards
-object files that are not referenced from @code{main} and uses export
-lists.
-@end defmac
-
-@hook TARGET_CANNOT_MODIFY_JUMPS_P
-
-@hook TARGET_HAVE_CONDITIONAL_EXECUTION
-
-@hook TARGET_GEN_CCMP_FIRST
-
-@hook TARGET_GEN_CCMP_NEXT
-
-@hook TARGET_GEN_MEMSET_SCRATCH_RTX
-
-@hook TARGET_LOOP_UNROLL_ADJUST
-
-@defmac POWI_MAX_MULTS
-If defined, this macro is interpreted as a signed integer C expression
-that specifies the maximum number of floating point multiplications
-that should be emitted when expanding exponentiation by an integer
-constant inline. When this value is defined, exponentiation requiring
-more than this number of multiplications is implemented by calling the
-system library's @code{pow}, @code{powf} or @code{powl} routines.
-The default value places no upper bound on the multiplication count.
-@end defmac
-
-@deftypefn Macro void TARGET_EXTRA_INCLUDES (const char *@var{sysroot}, const char *@var{iprefix}, int @var{stdinc})
-This target hook should register any extra include files for the
-target. The parameter @var{stdinc} indicates if normal include files
-are present. The parameter @var{sysroot} is the system root directory.
-The parameter @var{iprefix} is the prefix for the gcc directory.
-@end deftypefn
-
-@deftypefn Macro void TARGET_EXTRA_PRE_INCLUDES (const char *@var{sysroot}, const char *@var{iprefix}, int @var{stdinc})
-This target hook should register any extra include files for the
-target before any standard headers. The parameter @var{stdinc}
-indicates if normal include files are present. The parameter
-@var{sysroot} is the system root directory. The parameter
-@var{iprefix} is the prefix for the gcc directory.
-@end deftypefn
-
-@deftypefn Macro void TARGET_OPTF (char *@var{path})
-This target hook should register special include paths for the target.
-The parameter @var{path} is the include to register. On Darwin
-systems, this is used for Framework includes, which have semantics
-that are different from @option{-I}.
-@end deftypefn
-
-@defmac bool TARGET_USE_LOCAL_THUNK_ALIAS_P (tree @var{fndecl})
-This target macro returns @code{true} if it is safe to use a local alias
-for a virtual function @var{fndecl} when constructing thunks,
-@code{false} otherwise. By default, the macro returns @code{true} for all
-functions, if a target supports aliases (i.e.@: defines
-@code{ASM_OUTPUT_DEF}), @code{false} otherwise,
-@end defmac
-
-@defmac TARGET_FORMAT_TYPES
-If defined, this macro is the name of a global variable containing
-target-specific format checking information for the @option{-Wformat}
-option. The default is to have no target-specific format checks.
-@end defmac
-
-@defmac TARGET_N_FORMAT_TYPES
-If defined, this macro is the number of entries in
-@code{TARGET_FORMAT_TYPES}.
-@end defmac
-
-@defmac TARGET_OVERRIDES_FORMAT_ATTRIBUTES
-If defined, this macro is the name of a global variable containing
-target-specific format overrides for the @option{-Wformat} option. The
-default is to have no target-specific format overrides. If defined,
-@code{TARGET_FORMAT_TYPES} and @code{TARGET_OVERRIDES_FORMAT_ATTRIBUTES_COUNT}
-must be defined, too.
-@end defmac
-
-@defmac TARGET_OVERRIDES_FORMAT_ATTRIBUTES_COUNT
-If defined, this macro specifies the number of entries in
-@code{TARGET_OVERRIDES_FORMAT_ATTRIBUTES}.
-@end defmac
-
-@defmac TARGET_OVERRIDES_FORMAT_INIT
-If defined, this macro specifies the optional initialization
-routine for target specific customizations of the system printf
-and scanf formatter settings.
-@end defmac
-
-@hook TARGET_INVALID_ARG_FOR_UNPROTOTYPED_FN
-
-@hook TARGET_INVALID_CONVERSION
-
-@hook TARGET_INVALID_UNARY_OP
-
-@hook TARGET_INVALID_BINARY_OP
-
-@hook TARGET_PROMOTED_TYPE
-
-@hook TARGET_CONVERT_TO_TYPE
-
-@hook TARGET_VERIFY_TYPE_CONTEXT
-
-@defmac OBJC_JBLEN
-This macro determines the size of the objective C jump buffer for the
-NeXT runtime. By default, OBJC_JBLEN is defined to an innocuous value.
-@end defmac
-
-@defmac LIBGCC2_UNWIND_ATTRIBUTE
-Define this macro if any target-specific attributes need to be attached
-to the functions in @file{libgcc} that provide low-level support for
-call stack unwinding. It is used in declarations in @file{unwind-generic.h}
-and the associated definitions of those functions.
-@end defmac
-
-@hook TARGET_UPDATE_STACK_BOUNDARY
-
-@hook TARGET_GET_DRAP_RTX
-
-@hook TARGET_ZERO_CALL_USED_REGS
-
-@hook TARGET_ALLOCATE_STACK_SLOTS_FOR_ARGS
-
-@hook TARGET_CONST_ANCHOR
-
-@hook TARGET_ASAN_SHADOW_OFFSET
-
-@hook TARGET_MEMMODEL_CHECK
-
-@hook TARGET_ATOMIC_TEST_AND_SET_TRUEVAL
-
-@hook TARGET_HAS_IFUNC_P
-
-@hook TARGET_IFUNC_REF_LOCAL_OK
-
-@hook TARGET_ATOMIC_ALIGN_FOR_MODE
-
-@hook TARGET_ATOMIC_ASSIGN_EXPAND_FENV
-
-@hook TARGET_RECORD_OFFLOAD_SYMBOL
-
-@hook TARGET_OFFLOAD_OPTIONS
-
-@defmac TARGET_SUPPORTS_WIDE_INT
-
-On older ports, large integers are stored in @code{CONST_DOUBLE} rtl
-objects. Newer ports define @code{TARGET_SUPPORTS_WIDE_INT} to be nonzero
-to indicate that large integers are stored in
-@code{CONST_WIDE_INT} rtl objects. The @code{CONST_WIDE_INT} allows
-very large integer constants to be represented. @code{CONST_DOUBLE}
-is limited to twice the size of the host's @code{HOST_WIDE_INT}
-representation.
-
-Converting a port mostly requires looking for the places where
-@code{CONST_DOUBLE}s are used with @code{VOIDmode} and replacing that
-code with code that accesses @code{CONST_WIDE_INT}s. @samp{"grep -i
-const_double"} at the port level gets you to 95% of the changes that
-need to be made. There are a few places that require a deeper look.
-
-@itemize @bullet
-@item
-There is no equivalent to @code{hval} and @code{lval} for
-@code{CONST_WIDE_INT}s. This would be difficult to express in the md
-language since there are a variable number of elements.
-
-Most ports only check that @code{hval} is either 0 or -1 to see if the
-value is small. As mentioned above, this will no longer be necessary
-since small constants are always @code{CONST_INT}. Of course there
-are still a few exceptions, the alpha's constraint used by the zap
-instruction certainly requires careful examination by C code.
-However, all the current code does is pass the hval and lval to C
-code, so evolving the c code to look at the @code{CONST_WIDE_INT} is
-not really a large change.
-
-@item
-Because there is no standard template that ports use to materialize
-constants, there is likely to be some futzing that is unique to each
-port in this code.
-
-@item
-The rtx costs may have to be adjusted to properly account for larger
-constants that are represented as @code{CONST_WIDE_INT}.
-@end itemize
-
-All and all it does not take long to convert ports that the
-maintainer is familiar with.
-
-@end defmac
-
-@hook TARGET_HAVE_SPECULATION_SAFE_VALUE
-
-@hook TARGET_SPECULATION_SAFE_VALUE
-
-@hook TARGET_RUN_TARGET_SELFTESTS
-
-@hook TARGET_MEMTAG_CAN_TAG_ADDRESSES
-
-@hook TARGET_MEMTAG_TAG_SIZE
-
-@hook TARGET_MEMTAG_GRANULE_SIZE
-
-@hook TARGET_MEMTAG_INSERT_RANDOM_TAG
-
-@hook TARGET_MEMTAG_ADD_TAG
-
-@hook TARGET_MEMTAG_SET_TAG
-
-@hook TARGET_MEMTAG_EXTRACT_TAG
-
-@hook TARGET_MEMTAG_UNTAGGED_POINTER
-
-@hook TARGET_GCOV_TYPE_SIZE
-
-@hook TARGET_HAVE_SHADOW_CALL_STACK
+++ /dev/null
-@c Copyright (C) 2004-2022 Free Software Foundation, Inc.
-@c This is part of the GCC manual.
-@c For copying conditions, see the file gcc.texi.
-
-@c ---------------------------------------------------------------------
-@c Tree SSA
-@c ---------------------------------------------------------------------
-
-@node Tree SSA
-@chapter Analysis and Optimization of GIMPLE tuples
-@cindex Tree SSA
-@cindex Optimization infrastructure for GIMPLE
-
-GCC uses three main intermediate languages to represent the program
-during compilation: GENERIC, GIMPLE and RTL@. GENERIC is a
-language-independent representation generated by each front end. It
-is used to serve as an interface between the parser and optimizer.
-GENERIC is a common representation that is able to represent programs
-written in all the languages supported by GCC@.
-
-GIMPLE and RTL are used to optimize the program. GIMPLE is used for
-target and language independent optimizations (e.g., inlining,
-constant propagation, tail call elimination, redundancy elimination,
-etc). Much like GENERIC, GIMPLE is a language independent, tree based
-representation. However, it differs from GENERIC in that the GIMPLE
-grammar is more restrictive: expressions contain no more than 3
-operands (except function calls), it has no control flow structures
-and expressions with side effects are only allowed on the right hand
-side of assignments. See the chapter describing GENERIC and GIMPLE
-for more details.
-
-This chapter describes the data structures and functions used in the
-GIMPLE optimizers (also known as ``tree optimizers'' or ``middle
-end''). In particular, it focuses on all the macros, data structures,
-functions and programming constructs needed to implement optimization
-passes for GIMPLE@.
-
-@menu
-* Annotations:: Attributes for variables.
-* SSA Operands:: SSA names referenced by GIMPLE statements.
-* SSA:: Static Single Assignment representation.
-* Alias analysis:: Representing aliased loads and stores.
-* Memory model:: Memory model used by the middle-end.
-@end menu
-
-@node Annotations
-@section Annotations
-@cindex annotations
-
-The optimizers need to associate attributes with variables during the
-optimization process. For instance, we need to know whether a
-variable has aliases. All these attributes are stored in data
-structures called annotations which are then linked to the field
-@code{ann} in @code{struct tree_common}.
-
-
-@node SSA Operands
-@section SSA Operands
-@cindex operands
-@cindex virtual operands
-@cindex real operands
-@findex update_stmt
-
-Almost every GIMPLE statement will contain a reference to a variable
-or memory location. Since statements come in different shapes and
-sizes, their operands are going to be located at various spots inside
-the statement's tree. To facilitate access to the statement's
-operands, they are organized into lists associated inside each
-statement's annotation. Each element in an operand list is a pointer
-to a @code{VAR_DECL}, @code{PARM_DECL} or @code{SSA_NAME} tree node.
-This provides a very convenient way of examining and replacing
-operands.
-
-Data flow analysis and optimization is done on all tree nodes
-representing variables. Any node for which @code{SSA_VAR_P} returns
-nonzero is considered when scanning statement operands. However, not
-all @code{SSA_VAR_P} variables are processed in the same way. For the
-purposes of optimization, we need to distinguish between references to
-local scalar variables and references to globals, statics, structures,
-arrays, aliased variables, etc. The reason is simple, the compiler
-can gather complete data flow information for a local scalar. On the
-other hand, a global variable may be modified by a function call, it
-may not be possible to keep track of all the elements of an array or
-the fields of a structure, etc.
-
-The operand scanner gathers two kinds of operands: @dfn{real} and
-@dfn{virtual}. An operand for which @code{is_gimple_reg} returns true
-is considered real, otherwise it is a virtual operand. We also
-distinguish between uses and definitions. An operand is used if its
-value is loaded by the statement (e.g., the operand at the RHS of an
-assignment). If the statement assigns a new value to the operand, the
-operand is considered a definition (e.g., the operand at the LHS of
-an assignment).
-
-Virtual and real operands also have very different data flow
-properties. Real operands are unambiguous references to the
-full object that they represent. For instance, given
-
-@smallexample
-@{
- int a, b;
- a = b
-@}
-@end smallexample
-
-Since @code{a} and @code{b} are non-aliased locals, the statement
-@code{a = b} will have one real definition and one real use because
-variable @code{a} is completely modified with the contents of
-variable @code{b}. Real definition are also known as @dfn{killing
-definitions}. Similarly, the use of @code{b} reads all its bits.
-
-In contrast, virtual operands are used with variables that can have
-a partial or ambiguous reference. This includes structures, arrays,
-globals, and aliased variables. In these cases, we have two types of
-definitions. For globals, structures, and arrays, we can determine from
-a statement whether a variable of these types has a killing definition.
-If the variable does, then the statement is marked as having a
-@dfn{must definition} of that variable. However, if a statement is only
-defining a part of the variable (i.e.@: a field in a structure), or if we
-know that a statement might define the variable but we cannot say for sure,
-then we mark that statement as having a @dfn{may definition}. For
-instance, given
-
-@smallexample
-@{
- int a, b, *p;
-
- if (@dots{})
- p = &a;
- else
- p = &b;
- *p = 5;
- return *p;
-@}
-@end smallexample
-
-The assignment @code{*p = 5} may be a definition of @code{a} or
-@code{b}. If we cannot determine statically where @code{p} is
-pointing to at the time of the store operation, we create virtual
-definitions to mark that statement as a potential definition site for
-@code{a} and @code{b}. Memory loads are similarly marked with virtual
-use operands. Virtual operands are shown in tree dumps right before
-the statement that contains them. To request a tree dump with virtual
-operands, use the @option{-vops} option to @option{-fdump-tree}:
-
-@smallexample
-@{
- int a, b, *p;
-
- if (@dots{})
- p = &a;
- else
- p = &b;
- # a = VDEF <a>
- # b = VDEF <b>
- *p = 5;
-
- # VUSE <a>
- # VUSE <b>
- return *p;
-@}
-@end smallexample
-
-Notice that @code{VDEF} operands have two copies of the referenced
-variable. This indicates that this is not a killing definition of
-that variable. In this case we refer to it as a @dfn{may definition}
-or @dfn{aliased store}. The presence of the second copy of the
-variable in the @code{VDEF} operand will become important when the
-function is converted into SSA form. This will be used to link all
-the non-killing definitions to prevent optimizations from making
-incorrect assumptions about them.
-
-Operands are updated as soon as the statement is finished via a call
-to @code{update_stmt}. If statement elements are changed via
-@code{SET_USE} or @code{SET_DEF}, then no further action is required
-(i.e., those macros take care of updating the statement). If changes
-are made by manipulating the statement's tree directly, then a call
-must be made to @code{update_stmt} when complete. Calling one of the
-@code{bsi_insert} routines or @code{bsi_replace} performs an implicit
-call to @code{update_stmt}.
-
-@subsection Operand Iterators And Access Routines
-@cindex Operand Iterators
-@cindex Operand Access Routines
-
-Operands are collected by @file{tree-ssa-operands.cc}. They are stored
-inside each statement's annotation and can be accessed through either the
-operand iterators or an access routine.
-
-The following access routines are available for examining operands:
-
-@enumerate
-@item @code{SINGLE_SSA_@{USE,DEF,TREE@}_OPERAND}: These accessors will return
-NULL unless there is exactly one operand matching the specified flags. If
-there is exactly one operand, the operand is returned as either a @code{tree},
-@code{def_operand_p}, or @code{use_operand_p}.
-
-@smallexample
-tree t = SINGLE_SSA_TREE_OPERAND (stmt, flags);
-use_operand_p u = SINGLE_SSA_USE_OPERAND (stmt, SSA_ALL_VIRTUAL_USES);
-def_operand_p d = SINGLE_SSA_DEF_OPERAND (stmt, SSA_OP_ALL_DEFS);
-@end smallexample
-
-@item @code{ZERO_SSA_OPERANDS}: This macro returns true if there are no
-operands matching the specified flags.
-
-@smallexample
-if (ZERO_SSA_OPERANDS (stmt, SSA_OP_ALL_VIRTUALS))
- return;
-@end smallexample
-
-@item @code{NUM_SSA_OPERANDS}: This macro Returns the number of operands
-matching 'flags'. This actually executes a loop to perform the count, so
-only use this if it is really needed.
-
-@smallexample
-int count = NUM_SSA_OPERANDS (stmt, flags)
-@end smallexample
-@end enumerate
-
-
-If you wish to iterate over some or all operands, use the
-@code{FOR_EACH_SSA_@{USE,DEF,TREE@}_OPERAND} iterator. For example, to print
-all the operands for a statement:
-
-@smallexample
-void
-print_ops (tree stmt)
-@{
- ssa_op_iter;
- tree var;
-
- FOR_EACH_SSA_TREE_OPERAND (var, stmt, iter, SSA_OP_ALL_OPERANDS)
- print_generic_expr (stderr, var, TDF_SLIM);
-@}
-@end smallexample
-
-
-How to choose the appropriate iterator:
-
-@enumerate
-@item Determine whether you are need to see the operand pointers, or just the
-trees, and choose the appropriate macro:
-
-@smallexample
-Need Macro:
----- -------
-use_operand_p FOR_EACH_SSA_USE_OPERAND
-def_operand_p FOR_EACH_SSA_DEF_OPERAND
-tree FOR_EACH_SSA_TREE_OPERAND
-@end smallexample
-
-@item You need to declare a variable of the type you are interested
-in, and an ssa_op_iter structure which serves as the loop controlling
-variable.
-
-@item Determine which operands you wish to use, and specify the flags of
-those you are interested in. They are documented in
-@file{tree-ssa-operands.h}:
-
-@smallexample
-#define SSA_OP_USE 0x01 /* @r{Real USE operands.} */
-#define SSA_OP_DEF 0x02 /* @r{Real DEF operands.} */
-#define SSA_OP_VUSE 0x04 /* @r{VUSE operands.} */
-#define SSA_OP_VDEF 0x08 /* @r{VDEF operands.} */
-
-/* @r{These are commonly grouped operand flags.} */
-#define SSA_OP_VIRTUAL_USES (SSA_OP_VUSE)
-#define SSA_OP_VIRTUAL_DEFS (SSA_OP_VDEF)
-#define SSA_OP_ALL_VIRTUALS (SSA_OP_VIRTUAL_USES | SSA_OP_VIRTUAL_DEFS)
-#define SSA_OP_ALL_USES (SSA_OP_VIRTUAL_USES | SSA_OP_USE)
-#define SSA_OP_ALL_DEFS (SSA_OP_VIRTUAL_DEFS | SSA_OP_DEF)
-#define SSA_OP_ALL_OPERANDS (SSA_OP_ALL_USES | SSA_OP_ALL_DEFS)
-@end smallexample
-@end enumerate
-
-So if you want to look at the use pointers for all the @code{USE} and
-@code{VUSE} operands, you would do something like:
-
-@smallexample
- use_operand_p use_p;
- ssa_op_iter iter;
-
- FOR_EACH_SSA_USE_OPERAND (use_p, stmt, iter, (SSA_OP_USE | SSA_OP_VUSE))
- @{
- process_use_ptr (use_p);
- @}
-@end smallexample
-
-The @code{TREE} macro is basically the same as the @code{USE} and
-@code{DEF} macros, only with the use or def dereferenced via
-@code{USE_FROM_PTR (use_p)} and @code{DEF_FROM_PTR (def_p)}. Since we
-aren't using operand pointers, use and defs flags can be mixed.
-
-@smallexample
- tree var;
- ssa_op_iter iter;
-
- FOR_EACH_SSA_TREE_OPERAND (var, stmt, iter, SSA_OP_VUSE)
- @{
- print_generic_expr (stderr, var, TDF_SLIM);
- @}
-@end smallexample
-
-@code{VDEF}s are broken into two flags, one for the
-@code{DEF} portion (@code{SSA_OP_VDEF}) and one for the USE portion
-(@code{SSA_OP_VUSE}).
-
-There are many examples in the code, in addition to the documentation
-in @file{tree-ssa-operands.h} and @file{ssa-iterators.h}.
-
-There are also a couple of variants on the stmt iterators regarding PHI
-nodes.
-
-@code{FOR_EACH_PHI_ARG} Works exactly like
-@code{FOR_EACH_SSA_USE_OPERAND}, except it works over @code{PHI} arguments
-instead of statement operands.
-
-@smallexample
-/* Look at every virtual PHI use. */
-FOR_EACH_PHI_ARG (use_p, phi_stmt, iter, SSA_OP_VIRTUAL_USES)
-@{
- my_code;
-@}
-
-/* Look at every real PHI use. */
-FOR_EACH_PHI_ARG (use_p, phi_stmt, iter, SSA_OP_USES)
- my_code;
-
-/* Look at every PHI use. */
-FOR_EACH_PHI_ARG (use_p, phi_stmt, iter, SSA_OP_ALL_USES)
- my_code;
-@end smallexample
-
-@code{FOR_EACH_PHI_OR_STMT_@{USE,DEF@}} works exactly like
-@code{FOR_EACH_SSA_@{USE,DEF@}_OPERAND}, except it will function on
-either a statement or a @code{PHI} node. These should be used when it is
-appropriate but they are not quite as efficient as the individual
-@code{FOR_EACH_PHI} and @code{FOR_EACH_SSA} routines.
-
-@smallexample
-FOR_EACH_PHI_OR_STMT_USE (use_operand_p, stmt, iter, flags)
- @{
- my_code;
- @}
-
-FOR_EACH_PHI_OR_STMT_DEF (def_operand_p, phi, iter, flags)
- @{
- my_code;
- @}
-@end smallexample
-
-@subsection Immediate Uses
-@cindex Immediate Uses
-
-Immediate use information is now always available. Using the immediate use
-iterators, you may examine every use of any @code{SSA_NAME}. For instance,
-to change each use of @code{ssa_var} to @code{ssa_var2} and call fold_stmt on
-each stmt after that is done:
-
-@smallexample
- use_operand_p imm_use_p;
- imm_use_iterator iterator;
- tree ssa_var, stmt;
-
-
- FOR_EACH_IMM_USE_STMT (stmt, iterator, ssa_var)
- @{
- FOR_EACH_IMM_USE_ON_STMT (imm_use_p, iterator)
- SET_USE (imm_use_p, ssa_var_2);
- fold_stmt (stmt);
- @}
-@end smallexample
-
-There are 2 iterators which can be used. @code{FOR_EACH_IMM_USE_FAST} is
-used when the immediate uses are not changed, i.e., you are looking at the
-uses, but not setting them.
-
-If they do get changed, then care must be taken that things are not changed
-under the iterators, so use the @code{FOR_EACH_IMM_USE_STMT} and
-@code{FOR_EACH_IMM_USE_ON_STMT} iterators. They attempt to preserve the
-sanity of the use list by moving all the uses for a statement into
-a controlled position, and then iterating over those uses. Then the
-optimization can manipulate the stmt when all the uses have been
-processed. This is a little slower than the FAST version since it adds a
-placeholder element and must sort through the list a bit for each statement.
-This placeholder element must be also be removed if the loop is
-terminated early; a destructor takes care of that when leaving the
-@code{FOR_EACH_IMM_USE_STMT} scope.
-
-There are checks in @code{verify_ssa} which verify that the immediate use list
-is up to date, as well as checking that an optimization didn't break from the
-loop without using this macro. It is safe to simply 'break'; from a
-@code{FOR_EACH_IMM_USE_FAST} traverse.
-
-Some useful functions and macros:
-@enumerate
-@item @code{has_zero_uses (ssa_var)} : Returns true if there are no uses of
-@code{ssa_var}.
-@item @code{has_single_use (ssa_var)} : Returns true if there is only a
-single use of @code{ssa_var}.
-@item @code{single_imm_use (ssa_var, use_operand_p *ptr, tree *stmt)} :
-Returns true if there is only a single use of @code{ssa_var}, and also returns
-the use pointer and statement it occurs in, in the second and third parameters.
-@item @code{num_imm_uses (ssa_var)} : Returns the number of immediate uses of
-@code{ssa_var}. It is better not to use this if possible since it simply
-utilizes a loop to count the uses.
-@item @code{PHI_ARG_INDEX_FROM_USE (use_p)} : Given a use within a @code{PHI}
-node, return the index number for the use. An assert is triggered if the use
-isn't located in a @code{PHI} node.
-@item @code{USE_STMT (use_p)} : Return the statement a use occurs in.
-@end enumerate
-
-Note that uses are not put into an immediate use list until their statement is
-actually inserted into the instruction stream via a @code{bsi_*} routine.
-
-It is also still possible to utilize lazy updating of statements, but this
-should be used only when absolutely required. Both alias analysis and the
-dominator optimizations currently do this.
-
-When lazy updating is being used, the immediate use information is out of date
-and cannot be used reliably. Lazy updating is achieved by simply marking
-statements modified via calls to @code{gimple_set_modified} instead of
-@code{update_stmt}. When lazy updating is no longer required, all the
-modified statements must have @code{update_stmt} called in order to bring them
-up to date. This must be done before the optimization is finished, or
-@code{verify_ssa} will trigger an abort.
-
-This is done with a simple loop over the instruction stream:
-@smallexample
- block_stmt_iterator bsi;
- basic_block bb;
- FOR_EACH_BB (bb)
- @{
- for (bsi = bsi_start (bb); !bsi_end_p (bsi); bsi_next (&bsi))
- update_stmt_if_modified (bsi_stmt (bsi));
- @}
-@end smallexample
-
-@node SSA
-@section Static Single Assignment
-@cindex SSA
-@cindex static single assignment
-
-Most of the tree optimizers rely on the data flow information provided
-by the Static Single Assignment (SSA) form. We implement the SSA form
-as described in @cite{R. Cytron, J. Ferrante, B. Rosen, M. Wegman, and
-K. Zadeck. Efficiently Computing Static Single Assignment Form and the
-Control Dependence Graph. ACM Transactions on Programming Languages
-and Systems, 13(4):451-490, October 1991}.
-
-The SSA form is based on the premise that program variables are
-assigned in exactly one location in the program. Multiple assignments
-to the same variable create new versions of that variable. Naturally,
-actual programs are seldom in SSA form initially because variables
-tend to be assigned multiple times. The compiler modifies the program
-representation so that every time a variable is assigned in the code,
-a new version of the variable is created. Different versions of the
-same variable are distinguished by subscripting the variable name with
-its version number. Variables used in the right-hand side of
-expressions are renamed so that their version number matches that of
-the most recent assignment.
-
-We represent variable versions using @code{SSA_NAME} nodes. The
-renaming process in @file{tree-ssa.cc} wraps every real and
-virtual operand with an @code{SSA_NAME} node which contains
-the version number and the statement that created the
-@code{SSA_NAME}. Only definitions and virtual definitions may
-create new @code{SSA_NAME} nodes.
-
-@cindex PHI nodes
-Sometimes, flow of control makes it impossible to determine the
-most recent version of a variable. In these cases, the compiler
-inserts an artificial definition for that variable called
-@dfn{PHI function} or @dfn{PHI node}. This new definition merges
-all the incoming versions of the variable to create a new name
-for it. For instance,
-
-@smallexample
-if (@dots{})
- a_1 = 5;
-else if (@dots{})
- a_2 = 2;
-else
- a_3 = 13;
-
-# a_4 = PHI <a_1, a_2, a_3>
-return a_4;
-@end smallexample
-
-Since it is not possible to determine which of the three branches
-will be taken at runtime, we don't know which of @code{a_1},
-@code{a_2} or @code{a_3} to use at the return statement. So, the
-SSA renamer creates a new version @code{a_4} which is assigned
-the result of ``merging'' @code{a_1}, @code{a_2} and @code{a_3}.
-Hence, PHI nodes mean ``one of these operands. I don't know
-which''.
-
-The following functions can be used to examine PHI nodes
-
-@defun gimple_phi_result (@var{phi})
-Returns the @code{SSA_NAME} created by PHI node @var{phi} (i.e.,
-@var{phi}'s LHS)@.
-@end defun
-
-@defun gimple_phi_num_args (@var{phi})
-Returns the number of arguments in @var{phi}. This number is exactly
-the number of incoming edges to the basic block holding @var{phi}@.
-@end defun
-
-@defun gimple_phi_arg (@var{phi}, @var{i})
-Returns @var{i}th argument of @var{phi}@.
-@end defun
-
-@defun gimple_phi_arg_edge (@var{phi}, @var{i})
-Returns the incoming edge for the @var{i}th argument of @var{phi}.
-@end defun
-
-@defun gimple_phi_arg_def (@var{phi}, @var{i})
-Returns the @code{SSA_NAME} for the @var{i}th argument of @var{phi}.
-@end defun
-
-
-@subsection Preserving the SSA form
-@findex update_ssa
-@cindex preserving SSA form
-Some optimization passes make changes to the function that
-invalidate the SSA property. This can happen when a pass has
-added new symbols or changed the program so that variables that
-were previously aliased aren't anymore. Whenever something like this
-happens, the affected symbols must be renamed into SSA form again.
-Transformations that emit new code or replicate existing statements
-will also need to update the SSA form@.
-
-Since GCC implements two different SSA forms for register and virtual
-variables, keeping the SSA form up to date depends on whether you are
-updating register or virtual names. In both cases, the general idea
-behind incremental SSA updates is similar: when new SSA names are
-created, they typically are meant to replace other existing names in
-the program@.
-
-For instance, given the following code:
-
-@smallexample
- 1 L0:
- 2 x_1 = PHI (0, x_5)
- 3 if (x_1 < 10)
- 4 if (x_1 > 7)
- 5 y_2 = 0
- 6 else
- 7 y_3 = x_1 + x_7
- 8 endif
- 9 x_5 = x_1 + 1
- 10 goto L0;
- 11 endif
-@end smallexample
-
-Suppose that we insert new names @code{x_10} and @code{x_11} (lines
-@code{4} and @code{8})@.
-
-@smallexample
- 1 L0:
- 2 x_1 = PHI (0, x_5)
- 3 if (x_1 < 10)
- 4 x_10 = @dots{}
- 5 if (x_1 > 7)
- 6 y_2 = 0
- 7 else
- 8 x_11 = @dots{}
- 9 y_3 = x_1 + x_7
- 10 endif
- 11 x_5 = x_1 + 1
- 12 goto L0;
- 13 endif
-@end smallexample
-
-We want to replace all the uses of @code{x_1} with the new definitions
-of @code{x_10} and @code{x_11}. Note that the only uses that should
-be replaced are those at lines @code{5}, @code{9} and @code{11}.
-Also, the use of @code{x_7} at line @code{9} should @emph{not} be
-replaced (this is why we cannot just mark symbol @code{x} for
-renaming)@.
-
-Additionally, we may need to insert a PHI node at line @code{11}
-because that is a merge point for @code{x_10} and @code{x_11}. So the
-use of @code{x_1} at line @code{11} will be replaced with the new PHI
-node. The insertion of PHI nodes is optional. They are not strictly
-necessary to preserve the SSA form, and depending on what the caller
-inserted, they may not even be useful for the optimizers@.
-
-Updating the SSA form is a two step process. First, the pass has to
-identify which names need to be updated and/or which symbols need to
-be renamed into SSA form for the first time. When new names are
-introduced to replace existing names in the program, the mapping
-between the old and the new names are registered by calling
-@code{register_new_name_mapping} (note that if your pass creates new
-code by duplicating basic blocks, the call to @code{tree_duplicate_bb}
-will set up the necessary mappings automatically).
-
-After the replacement mappings have been registered and new symbols
-marked for renaming, a call to @code{update_ssa} makes the registered
-changes. This can be done with an explicit call or by creating
-@code{TODO} flags in the @code{tree_opt_pass} structure for your pass.
-There are several @code{TODO} flags that control the behavior of
-@code{update_ssa}:
-
-@itemize @bullet
-@item @code{TODO_update_ssa}. Update the SSA form inserting PHI nodes
-for newly exposed symbols and virtual names marked for updating.
-When updating real names, only insert PHI nodes for a real name
-@code{O_j} in blocks reached by all the new and old definitions for
-@code{O_j}. If the iterated dominance frontier for @code{O_j}
-is not pruned, we may end up inserting PHI nodes in blocks that
-have one or more edges with no incoming definition for
-@code{O_j}. This would lead to uninitialized warnings for
-@code{O_j}'s symbol@.
-
-@item @code{TODO_update_ssa_no_phi}. Update the SSA form without
-inserting any new PHI nodes at all. This is used by passes that
-have either inserted all the PHI nodes themselves or passes that
-need only to patch use-def and def-def chains for virtuals
-(e.g., DCE)@.
-
-
-@item @code{TODO_update_ssa_full_phi}. Insert PHI nodes everywhere
-they are needed. No pruning of the IDF is done. This is used
-by passes that need the PHI nodes for @code{O_j} even if it
-means that some arguments will come from the default definition
-of @code{O_j}'s symbol (e.g., @code{pass_linear_transform})@.
-
-WARNING: If you need to use this flag, chances are that your
-pass may be doing something wrong. Inserting PHI nodes for an
-old name where not all edges carry a new replacement may lead to
-silent codegen errors or spurious uninitialized warnings@.
-
-@item @code{TODO_update_ssa_only_virtuals}. Passes that update the
-SSA form on their own may want to delegate the updating of
-virtual names to the generic updater. Since FUD chains are
-easier to maintain, this simplifies the work they need to do.
-NOTE: If this flag is used, any OLD->NEW mappings for real names
-are explicitly destroyed and only the symbols marked for
-renaming are processed@.
-@end itemize
-
-@subsection Examining @code{SSA_NAME} nodes
-@cindex examining SSA_NAMEs
-
-The following macros can be used to examine @code{SSA_NAME} nodes
-
-@defmac SSA_NAME_DEF_STMT (@var{var})
-Returns the statement @var{s} that creates the @code{SSA_NAME}
-@var{var}. If @var{s} is an empty statement (i.e., @code{IS_EMPTY_STMT
-(@var{s})} returns @code{true}), it means that the first reference to
-this variable is a USE or a VUSE@.
-@end defmac
-
-@defmac SSA_NAME_VERSION (@var{var})
-Returns the version number of the @code{SSA_NAME} object @var{var}.
-@end defmac
-
-
-@subsection Walking the dominator tree
-
-@deftypefn {Tree SSA function} void walk_dominator_tree (@var{walk_data}, @var{bb})
-
-This function walks the dominator tree for the current CFG calling a
-set of callback functions defined in @var{struct dom_walk_data} in
-@file{domwalk.h}. The call back functions you need to define give you
-hooks to execute custom code at various points during traversal:
-
-@enumerate
-@item Once to initialize any local data needed while processing
-@var{bb} and its children. This local data is pushed into an
-internal stack which is automatically pushed and popped as the
-walker traverses the dominator tree.
-
-@item Once before traversing all the statements in the @var{bb}.
-
-@item Once for every statement inside @var{bb}.
-
-@item Once after traversing all the statements and before recursing
-into @var{bb}'s dominator children.
-
-@item It then recurses into all the dominator children of @var{bb}.
-
-@item After recursing into all the dominator children of @var{bb} it
-can, optionally, traverse every statement in @var{bb} again
-(i.e., repeating steps 2 and 3).
-
-@item Once after walking the statements in @var{bb} and @var{bb}'s
-dominator children. At this stage, the block local data stack
-is popped.
-@end enumerate
-@end deftypefn
-
-@node Alias analysis
-@section Alias analysis
-@cindex alias
-@cindex flow-sensitive alias analysis
-@cindex flow-insensitive alias analysis
-
-Alias analysis in GIMPLE SSA form consists of two pieces. First
-the virtual SSA web ties conflicting memory accesses and provides
-a SSA use-def chain and SSA immediate-use chains for walking
-possibly dependent memory accesses. Second an alias-oracle can
-be queried to disambiguate explicit and implicit memory references.
-
-@enumerate
-@item Memory SSA form.
-
-All statements that may use memory have exactly one accompanied use of
-a virtual SSA name that represents the state of memory at the
-given point in the IL.
-
-All statements that may define memory have exactly one accompanied
-definition of a virtual SSA name using the previous state of memory
-and defining the new state of memory after the given point in the IL.
-
-@smallexample
-int i;
-int foo (void)
-@{
- # .MEM_3 = VDEF <.MEM_2(D)>
- i = 1;
- # VUSE <.MEM_3>
- return i;
-@}
-@end smallexample
-
-The virtual SSA names in this case are @code{.MEM_2(D)} and
-@code{.MEM_3}. The store to the global variable @code{i}
-defines @code{.MEM_3} invalidating @code{.MEM_2(D)}. The
-load from @code{i} uses that new state @code{.MEM_3}.
-
-The virtual SSA web serves as constraints to SSA optimizers
-preventing illegitimate code-motion and optimization. It
-also provides a way to walk related memory statements.
-
-@item Points-to and escape analysis.
-
-Points-to analysis builds a set of constraints from the GIMPLE
-SSA IL representing all pointer operations and facts we do
-or do not know about pointers. Solving this set of constraints
-yields a conservatively correct solution for each pointer
-variable in the program (though we are only interested in
-SSA name pointers) as to what it may possibly point to.
-
-This points-to solution for a given SSA name pointer is stored
-in the @code{pt_solution} sub-structure of the
-@code{SSA_NAME_PTR_INFO} record. The following accessor
-functions are available:
-
-@itemize @bullet
-@item @code{pt_solution_includes}
-@item @code{pt_solutions_intersect}
-@end itemize
-
-Points-to analysis also computes the solution for two special
-set of pointers, @code{ESCAPED} and @code{CALLUSED}. Those
-represent all memory that has escaped the scope of analysis
-or that is used by pure or nested const calls.
-
-@item Type-based alias analysis
-
-Type-based alias analysis is frontend dependent though generic
-support is provided by the middle-end in @code{alias.cc}. TBAA
-code is used by both tree optimizers and RTL optimizers.
-
-Every language that wishes to perform language-specific alias analysis
-should define a function that computes, given a @code{tree}
-node, an alias set for the node. Nodes in different alias sets are not
-allowed to alias. For an example, see the C front-end function
-@code{c_get_alias_set}.
-
-@item Tree alias-oracle
-
-The tree alias-oracle provides means to disambiguate two memory
-references and memory references against statements. The following
-queries are available:
-
-@itemize @bullet
-@item @code{refs_may_alias_p}
-@item @code{ref_maybe_used_by_stmt_p}
-@item @code{stmt_may_clobber_ref_p}
-@end itemize
-
-In addition to those two kind of statement walkers are available
-walking statements related to a reference ref.
-@code{walk_non_aliased_vuses} walks over dominating memory defining
-statements and calls back if the statement does not clobber ref
-providing the non-aliased VUSE. The walk stops at
-the first clobbering statement or if asked to.
-@code{walk_aliased_vdefs} walks over dominating memory defining
-statements and calls back on each statement clobbering ref
-providing its aliasing VDEF. The walk stops if asked to.
-
-@end enumerate
-
-
-@node Memory model
-@section Memory model
-@cindex memory model
-
-The memory model used by the middle-end models that of the C/C++
-languages. The middle-end has the notion of an effective type
-of a memory region which is used for type-based alias analysis.
-
-The following is a refinement of ISO C99 6.5/6, clarifying the block copy case
-to follow common sense and extending the concept of a dynamic effective
-type to objects with a declared type as required for C++.
-
-@smallexample
-The effective type of an object for an access to its stored value is
-the declared type of the object or the effective type determined by
-a previous store to it. If a value is stored into an object through
-an lvalue having a type that is not a character type, then the
-type of the lvalue becomes the effective type of the object for that
-access and for subsequent accesses that do not modify the stored value.
-If a value is copied into an object using @code{memcpy} or @code{memmove},
-or is copied as an array of character type, then the effective type
-of the modified object for that access and for subsequent accesses that
-do not modify the value is undetermined. For all other accesses to an
-object, the effective type of the object is simply the type of the
-lvalue used for the access.
-@end smallexample
-
+++ /dev/null
-@c Copyright (C) 1988-2022 Free Software Foundation, Inc.
-@c This is part of the GCC manual.
-@c For copying conditions, see the file gcc.texi.
-
-@node Trouble
-@chapter Known Causes of Trouble with GCC
-@cindex bugs, known
-@cindex installation trouble
-@cindex known causes of trouble
-
-This section describes known problems that affect users of GCC@. Most
-of these are not GCC bugs per se---if they were, we would fix them.
-But the result for a user may be like the result of a bug.
-
-Some of these problems are due to bugs in other software, some are
-missing features that are too much work to add, and some are places
-where people's opinions differ as to what is best.
-
-@menu
-* Actual Bugs:: Bugs we will fix later.
-* Interoperation:: Problems using GCC with other compilers,
- and with certain linkers, assemblers and debuggers.
-* Incompatibilities:: GCC is incompatible with traditional C.
-* Fixed Headers:: GCC uses corrected versions of system header files.
- This is necessary, but doesn't always work smoothly.
-* Standard Libraries:: GCC uses the system C library, which might not be
- compliant with the ISO C standard.
-* Disappointments:: Regrettable things we cannot change, but not quite bugs.
-* C++ Misunderstandings:: Common misunderstandings with GNU C++.
-* Non-bugs:: Things we think are right, but some others disagree.
-* Warnings and Errors:: Which problems in your code get warnings,
- and which get errors.
-@end menu
-
-@node Actual Bugs
-@section Actual Bugs We Haven't Fixed Yet
-
-@itemize @bullet
-@item
-The @code{fixincludes} script interacts badly with automounters; if the
-directory of system header files is automounted, it tends to be
-unmounted while @code{fixincludes} is running. This would seem to be a
-bug in the automounter. We don't know any good way to work around it.
-@end itemize
-
-@node Interoperation
-@section Interoperation
-
-This section lists various difficulties encountered in using GCC
-together with other compilers or with the assemblers, linkers,
-libraries and debuggers on certain systems.
-
-@itemize @bullet
-@item
-On many platforms, GCC supports a different ABI for C++ than do other
-compilers, so the object files compiled by GCC cannot be used with object
-files generated by another C++ compiler.
-
-An area where the difference is most apparent is name mangling. The use
-of different name mangling is intentional, to protect you from more subtle
-problems.
-Compilers differ as to many internal details of C++ implementation,
-including: how class instances are laid out, how multiple inheritance is
-implemented, and how virtual function calls are handled. If the name
-encoding were made the same, your programs would link against libraries
-provided from other compilers---but the programs would then crash when
-run. Incompatible libraries are then detected at link time, rather than
-at run time.
-
-@item
-On some BSD systems, including some versions of Ultrix, use of profiling
-causes static variable destructors (currently used only in C++) not to
-be run.
-
-@item
-On a SPARC, GCC aligns all values of type @code{double} on an 8-byte
-boundary, and it expects every @code{double} to be so aligned. The Sun
-compiler usually gives @code{double} values 8-byte alignment, with one
-exception: function arguments of type @code{double} may not be aligned.
-
-As a result, if a function compiled with Sun CC takes the address of an
-argument of type @code{double} and passes this pointer of type
-@code{double *} to a function compiled with GCC, dereferencing the
-pointer may cause a fatal signal.
-
-One way to solve this problem is to compile your entire program with GCC@.
-Another solution is to modify the function that is compiled with
-Sun CC to copy the argument into a local variable; local variables
-are always properly aligned. A third solution is to modify the function
-that uses the pointer to dereference it via the following function
-@code{access_double} instead of directly with @samp{*}:
-
-@smallexample
-inline double
-access_double (double *unaligned_ptr)
-@{
- union d2i @{ double d; int i[2]; @};
-
- union d2i *p = (union d2i *) unaligned_ptr;
- union d2i u;
-
- u.i[0] = p->i[0];
- u.i[1] = p->i[1];
-
- return u.d;
-@}
-@end smallexample
-
-@noindent
-Storing into the pointer can be done likewise with the same union.
-
-@item
-On Solaris, the @code{malloc} function in the @file{libmalloc.a} library
-may allocate memory that is only 4 byte aligned. Since GCC on the
-SPARC assumes that doubles are 8 byte aligned, this may result in a
-fatal signal if doubles are stored in memory allocated by the
-@file{libmalloc.a} library.
-
-The solution is to not use the @file{libmalloc.a} library. Use instead
-@code{malloc} and related functions from @file{libc.a}; they do not have
-this problem.
-
-@item
-On the HP PA machine, ADB sometimes fails to work on functions compiled
-with GCC@. Specifically, it fails to work on functions that use
-@code{alloca} or variable-size arrays. This is because GCC doesn't
-generate HP-UX unwind descriptors for such functions. It may even be
-impossible to generate them.
-
-@item
-Debugging (@option{-g}) is not supported on the HP PA machine, unless you use
-the preliminary GNU tools.
-
-@item
-Taking the address of a label may generate errors from the HP-UX
-PA assembler. GAS for the PA does not have this problem.
-
-@item
-Using floating point parameters for indirect calls to static functions
-will not work when using the HP assembler. There simply is no way for GCC
-to specify what registers hold arguments for static functions when using
-the HP assembler. GAS for the PA does not have this problem.
-
-@item
-In extremely rare cases involving some very large functions you may
-receive errors from the HP linker complaining about an out of bounds
-unconditional branch offset. This used to occur more often in previous
-versions of GCC, but is now exceptionally rare. If you should run
-into it, you can work around by making your function smaller.
-
-@item
-GCC compiled code sometimes emits warnings from the HP-UX assembler of
-the form:
-
-@smallexample
-(warning) Use of GR3 when
- frame >= 8192 may cause conflict.
-@end smallexample
-
-These warnings are harmless and can be safely ignored.
-
-@item
-In extremely rare cases involving some very large functions you may
-receive errors from the AIX Assembler complaining about a displacement
-that is too large. If you should run into it, you can work around by
-making your function smaller.
-
-@item
-The @file{libstdc++.a} library in GCC relies on the SVR4 dynamic
-linker semantics which merges global symbols between libraries and
-applications, especially necessary for C++ streams functionality.
-This is not the default behavior of AIX shared libraries and dynamic
-linking. @file{libstdc++.a} is built on AIX with ``runtime-linking''
-enabled so that symbol merging can occur. To utilize this feature,
-the application linked with @file{libstdc++.a} must include the
-@option{-Wl,-brtl} flag on the link line. G++ cannot impose this
-because this option may interfere with the semantics of the user
-program and users may not always use @samp{g++} to link his or her
-application. Applications are not required to use the
-@option{-Wl,-brtl} flag on the link line---the rest of the
-@file{libstdc++.a} library which is not dependent on the symbol
-merging semantics will continue to function correctly.
-
-@item
-An application can interpose its own definition of functions for
-functions invoked by @file{libstdc++.a} with ``runtime-linking''
-enabled on AIX@. To accomplish this the application must be linked
-with ``runtime-linking'' option and the functions explicitly must be
-exported by the application (@option{-Wl,-brtl,-bE:exportfile}).
-
-@item
-AIX on the RS/6000 provides support (NLS) for environments outside of
-the United States. Compilers and assemblers use NLS to support
-locale-specific representations of various objects including
-floating-point numbers (@samp{.} vs @samp{,} for separating decimal
-fractions). There have been problems reported where the library linked
-with GCC does not produce the same floating-point formats that the
-assembler accepts. If you have this problem, set the @env{LANG}
-environment variable to @samp{C} or @samp{En_US}.
-
-@item
-@opindex fdollars-in-identifiers
-Even if you specify @option{-fdollars-in-identifiers},
-you cannot successfully use @samp{$} in identifiers on the RS/6000 due
-to a restriction in the IBM assembler. GAS supports these
-identifiers.
-
-@end itemize
-
-@node Incompatibilities
-@section Incompatibilities of GCC
-@cindex incompatibilities of GCC
-@opindex traditional
-
-There are several noteworthy incompatibilities between GNU C and K&R
-(non-ISO) versions of C@.
-
-@itemize @bullet
-@cindex string constants
-@cindex read-only strings
-@cindex shared strings
-@item
-GCC normally makes string constants read-only. If several
-identical-looking string constants are used, GCC stores only one
-copy of the string.
-
-@cindex @code{mktemp}, and constant strings
-One consequence is that you cannot call @code{mktemp} with a string
-constant argument. The function @code{mktemp} always alters the
-string its argument points to.
-
-@cindex @code{sscanf}, and constant strings
-@cindex @code{fscanf}, and constant strings
-@cindex @code{scanf}, and constant strings
-Another consequence is that @code{sscanf} does not work on some very
-old systems when passed a string constant as its format control string
-or input. This is because @code{sscanf} incorrectly tries to write
-into the string constant. Likewise @code{fscanf} and @code{scanf}.
-
-The solution to these problems is to change the program to use
-@code{char}-array variables with initialization strings for these
-purposes instead of string constants.
-
-@item
-@code{-2147483648} is positive.
-
-This is because 2147483648 cannot fit in the type @code{int}, so
-(following the ISO C rules) its data type is @code{unsigned long int}.
-Negating this value yields 2147483648 again.
-
-@item
-GCC does not substitute macro arguments when they appear inside of
-string constants. For example, the following macro in GCC
-
-@smallexample
-#define foo(a) "a"
-@end smallexample
-
-@noindent
-will produce output @code{"a"} regardless of what the argument @var{a} is.
-
-@cindex @code{setjmp} incompatibilities
-@cindex @code{longjmp} incompatibilities
-@item
-When you use @code{setjmp} and @code{longjmp}, the only automatic
-variables guaranteed to remain valid are those declared
-@code{volatile}. This is a consequence of automatic register
-allocation. Consider this function:
-
-@smallexample
-jmp_buf j;
-
-foo ()
-@{
- int a, b;
-
- a = fun1 ();
- if (setjmp (j))
- return a;
-
- a = fun2 ();
- /* @r{@code{longjmp (j)} may occur in @code{fun3}.} */
- return a + fun3 ();
-@}
-@end smallexample
-
-Here @code{a} may or may not be restored to its first value when the
-@code{longjmp} occurs. If @code{a} is allocated in a register, then
-its first value is restored; otherwise, it keeps the last value stored
-in it.
-
-@opindex W
-If you use the @option{-W} option with the @option{-O} option, you will
-get a warning when GCC thinks such a problem might be possible.
-
-@item
-Programs that use preprocessing directives in the middle of macro
-arguments do not work with GCC@. For example, a program like this
-will not work:
-
-@smallexample
-@group
-foobar (
-#define luser
- hack)
-@end group
-@end smallexample
-
-ISO C does not permit such a construct.
-
-@item
-K&R compilers allow comments to cross over an inclusion boundary
-(i.e.@: started in an include file and ended in the including file).
-
-@cindex external declaration scope
-@cindex scope of external declarations
-@cindex declaration scope
-@item
-Declarations of external variables and functions within a block apply
-only to the block containing the declaration. In other words, they
-have the same scope as any other declaration in the same place.
-
-In some other C compilers, an @code{extern} declaration affects all the
-rest of the file even if it happens within a block.
-
-@item
-In traditional C, you can combine @code{long}, etc., with a typedef name,
-as shown here:
-
-@smallexample
-typedef int foo;
-typedef long foo bar;
-@end smallexample
-
-In ISO C, this is not allowed: @code{long} and other type modifiers
-require an explicit @code{int}.
-
-@cindex typedef names as function parameters
-@item
-PCC allows typedef names to be used as function parameters.
-
-@item
-Traditional C allows the following erroneous pair of declarations to
-appear together in a given scope:
-
-@smallexample
-typedef int foo;
-typedef foo foo;
-@end smallexample
-
-@item
-GCC treats all characters of identifiers as significant. According to
-K&R-1 (2.2), ``No more than the first eight characters are significant,
-although more may be used.''. Also according to K&R-1 (2.2), ``An
-identifier is a sequence of letters and digits; the first character must
-be a letter. The underscore _ counts as a letter.'', but GCC also
-allows dollar signs in identifiers.
-
-@cindex whitespace
-@item
-PCC allows whitespace in the middle of compound assignment operators
-such as @samp{+=}. GCC, following the ISO standard, does not
-allow this.
-
-@cindex apostrophes
-@cindex @code{'}
-@item
-GCC complains about unterminated character constants inside of
-preprocessing conditionals that fail. Some programs have English
-comments enclosed in conditionals that are guaranteed to fail; if these
-comments contain apostrophes, GCC will probably report an error. For
-example, this code would produce an error:
-
-@smallexample
-#if 0
-You can't expect this to work.
-#endif
-@end smallexample
-
-The best solution to such a problem is to put the text into an actual
-C comment delimited by @samp{/*@dots{}*/}.
-
-@item
-Many user programs contain the declaration @samp{long time ();}. In the
-past, the system header files on many systems did not actually declare
-@code{time}, so it did not matter what type your program declared it to
-return. But in systems with ISO C headers, @code{time} is declared to
-return @code{time_t}, and if that is not the same as @code{long}, then
-@samp{long time ();} is erroneous.
-
-The solution is to change your program to use appropriate system headers
-(@code{<time.h>} on systems with ISO C headers) and not to declare
-@code{time} if the system header files declare it, or failing that to
-use @code{time_t} as the return type of @code{time}.
-
-@cindex @code{float} as function value type
-@item
-When compiling functions that return @code{float}, PCC converts it to
-a double. GCC actually returns a @code{float}. If you are concerned
-with PCC compatibility, you should declare your functions to return
-@code{double}; you might as well say what you mean.
-
-@cindex structures
-@cindex unions
-@item
-When compiling functions that return structures or unions, GCC
-output code normally uses a method different from that used on most
-versions of Unix. As a result, code compiled with GCC cannot call
-a structure-returning function compiled with PCC, and vice versa.
-
-The method used by GCC is as follows: a structure or union which is
-1, 2, 4 or 8 bytes long is returned like a scalar. A structure or union
-with any other size is stored into an address supplied by the caller
-(usually in a special, fixed register, but on some machines it is passed
-on the stack). The target hook @code{TARGET_STRUCT_VALUE_RTX}
-tells GCC where to pass this address.
-
-By contrast, PCC on most target machines returns structures and unions
-of any size by copying the data into an area of static storage, and then
-returning the address of that storage as if it were a pointer value.
-The caller must copy the data from that memory area to the place where
-the value is wanted. GCC does not use this method because it is
-slower and nonreentrant.
-
-On some newer machines, PCC uses a reentrant convention for all
-structure and union returning. GCC on most of these machines uses a
-compatible convention when returning structures and unions in memory,
-but still returns small structures and unions in registers.
-
-@opindex fpcc-struct-return
-You can tell GCC to use a compatible convention for all structure and
-union returning with the option @option{-fpcc-struct-return}.
-
-@cindex preprocessing tokens
-@cindex preprocessing numbers
-@item
-GCC complains about program fragments such as @samp{0x74ae-0x4000}
-which appear to be two hexadecimal constants separated by the minus
-operator. Actually, this string is a single @dfn{preprocessing token}.
-Each such token must correspond to one token in C@. Since this does not,
-GCC prints an error message. Although it may appear obvious that what
-is meant is an operator and two values, the ISO C standard specifically
-requires that this be treated as erroneous.
-
-A @dfn{preprocessing token} is a @dfn{preprocessing number} if it
-begins with a digit and is followed by letters, underscores, digits,
-periods and @samp{e+}, @samp{e-}, @samp{E+}, @samp{E-}, @samp{p+},
-@samp{p-}, @samp{P+}, or @samp{P-} character sequences. (In strict C90
-mode, the sequences @samp{p+}, @samp{p-}, @samp{P+} and @samp{P-} cannot
-appear in preprocessing numbers.)
-
-To make the above program fragment valid, place whitespace in front of
-the minus sign. This whitespace will end the preprocessing number.
-@end itemize
-
-@node Fixed Headers
-@section Fixed Header Files
-
-GCC needs to install corrected versions of some system header files.
-This is because most target systems have some header files that won't
-work with GCC unless they are changed. Some have bugs, some are
-incompatible with ISO C, and some depend on special features of other
-compilers.
-
-Installing GCC automatically creates and installs the fixed header
-files, by running a program called @code{fixincludes}. Normally, you
-don't need to pay attention to this. But there are cases where it
-doesn't do the right thing automatically.
-
-@itemize @bullet
-@item
-If you update the system's header files, such as by installing a new
-system version, the fixed header files of GCC are not automatically
-updated. They can be updated using the @command{mkheaders} script
-installed in
-@file{@var{libexecdir}/gcc/@var{target}/@var{version}/install-tools/}.
-
-@item
-On some systems, header file directories contain
-machine-specific symbolic links in certain places. This makes it
-possible to share most of the header files among hosts running the
-same version of the system on different machine models.
-
-The programs that fix the header files do not understand this special
-way of using symbolic links; therefore, the directory of fixed header
-files is good only for the machine model used to build it.
-
-It is possible to make separate sets of fixed header files for the
-different machine models, and arrange a structure of symbolic links so
-as to use the proper set, but you'll have to do this by hand.
-@end itemize
-
-@node Standard Libraries
-@section Standard Libraries
-
-@opindex Wall
-GCC by itself attempts to be a conforming freestanding implementation.
-@xref{Standards,,Language Standards Supported by GCC}, for details of
-what this means. Beyond the library facilities required of such an
-implementation, the rest of the C library is supplied by the vendor of
-the operating system. If that C library doesn't conform to the C
-standards, then your programs might get warnings (especially when using
-@option{-Wall}) that you don't expect.
-
-For example, the @code{sprintf} function on SunOS 4.1.3 returns
-@code{char *} while the C standard says that @code{sprintf} returns an
-@code{int}. The @code{fixincludes} program could make the prototype for
-this function match the Standard, but that would be wrong, since the
-function will still return @code{char *}.
-
-If you need a Standard compliant library, then you need to find one, as
-GCC does not provide one. The GNU C library (called @code{glibc})
-provides ISO C, POSIX, BSD, SystemV and X/Open compatibility for
-GNU/Linux and HURD-based GNU systems; no recent version of it supports
-other systems, though some very old versions did. Version 2.2 of the
-GNU C library includes nearly complete C99 support. You could also ask
-your operating system vendor if newer libraries are available.
-
-@node Disappointments
-@section Disappointments and Misunderstandings
-
-These problems are perhaps regrettable, but we don't know any practical
-way around them.
-
-@itemize @bullet
-@item
-Certain local variables aren't recognized by debuggers when you compile
-with optimization.
-
-This occurs because sometimes GCC optimizes the variable out of
-existence. There is no way to tell the debugger how to compute the
-value such a variable ``would have had'', and it is not clear that would
-be desirable anyway. So GCC simply does not mention the eliminated
-variable when it writes debugging information.
-
-You have to expect a certain amount of disagreement between the
-executable and your source code, when you use optimization.
-
-@cindex conflicting types
-@cindex scope of declaration
-@item
-Users often think it is a bug when GCC reports an error for code
-like this:
-
-@smallexample
-int foo (struct mumble *);
-
-struct mumble @{ @dots{} @};
-
-int foo (struct mumble *x)
-@{ @dots{} @}
-@end smallexample
-
-This code really is erroneous, because the scope of @code{struct
-mumble} in the prototype is limited to the argument list containing it.
-It does not refer to the @code{struct mumble} defined with file scope
-immediately below---they are two unrelated types with similar names in
-different scopes.
-
-But in the definition of @code{foo}, the file-scope type is used
-because that is available to be inherited. Thus, the definition and
-the prototype do not match, and you get an error.
-
-This behavior may seem silly, but it's what the ISO standard specifies.
-It is easy enough for you to make your code work by moving the
-definition of @code{struct mumble} above the prototype. It's not worth
-being incompatible with ISO C just to avoid an error for the example
-shown above.
-
-@item
-Accesses to bit-fields even in volatile objects works by accessing larger
-objects, such as a byte or a word. You cannot rely on what size of
-object is accessed in order to read or write the bit-field; it may even
-vary for a given bit-field according to the precise usage.
-
-If you care about controlling the amount of memory that is accessed, use
-volatile but do not use bit-fields.
-
-@item
-GCC comes with shell scripts to fix certain known problems in system
-header files. They install corrected copies of various header files in
-a special directory where only GCC will normally look for them. The
-scripts adapt to various systems by searching all the system header
-files for the problem cases that we know about.
-
-If new system header files are installed, nothing automatically arranges
-to update the corrected header files. They can be updated using the
-@command{mkheaders} script installed in
-@file{@var{libexecdir}/gcc/@var{target}/@var{version}/install-tools/}.
-
-@item
-@cindex floating point precision
-On 68000 and x86 systems, for instance, you can get paradoxical results
-if you test the precise values of floating point numbers. For example,
-you can find that a floating point value which is not a NaN is not equal
-to itself. This results from the fact that the floating point registers
-hold a few more bits of precision than fit in a @code{double} in memory.
-Compiled code moves values between memory and floating point registers
-at its convenience, and moving them into memory truncates them.
-
-@opindex ffloat-store
-You can partially avoid this problem by using the @option{-ffloat-store}
-option (@pxref{Optimize Options}).
-
-@item
-On AIX and other platforms without weak symbol support, templates
-need to be instantiated explicitly and symbols for static members
-of templates will not be generated.
-
-@item
-On AIX, GCC scans object files and library archives for static
-constructors and destructors when linking an application before the
-linker prunes unreferenced symbols. This is necessary to prevent the
-AIX linker from mistakenly assuming that static constructor or
-destructor are unused and removing them before the scanning can occur.
-All static constructors and destructors found will be referenced even
-though the modules in which they occur may not be used by the program.
-This may lead to both increased executable size and unexpected symbol
-references.
-@end itemize
-
-@node C++ Misunderstandings
-@section Common Misunderstandings with GNU C++
-
-@cindex misunderstandings in C++
-@cindex surprises in C++
-@cindex C++ misunderstandings
-C++ is a complex language and an evolving one, and its standard
-definition (the ISO C++ standard) was only recently completed. As a
-result, your C++ compiler may occasionally surprise you, even when its
-behavior is correct. This section discusses some areas that frequently
-give rise to questions of this sort.
-
-@menu
-* Static Definitions:: Static member declarations are not definitions
-* Name lookup:: Name lookup, templates, and accessing members of base classes
-* Temporaries:: Temporaries may vanish before you expect
-* Copy Assignment:: Copy Assignment operators copy virtual bases twice
-@end menu
-
-@node Static Definitions
-@subsection Declare @emph{and} Define Static Members
-
-@cindex C++ static data, declaring and defining
-@cindex static data in C++, declaring and defining
-@cindex declaring static data in C++
-@cindex defining static data in C++
-When a class has static data members, it is not enough to @emph{declare}
-the static member; you must also @emph{define} it. For example:
-
-@smallexample
-class Foo
-@{
- @dots{}
- void method();
- static int bar;
-@};
-@end smallexample
-
-This declaration only establishes that the class @code{Foo} has an
-@code{int} named @code{Foo::bar}, and a member function named
-@code{Foo::method}. But you still need to define @emph{both}
-@code{method} and @code{bar} elsewhere. According to the ISO
-standard, you must supply an initializer in one (and only one) source
-file, such as:
-
-@smallexample
-int Foo::bar = 0;
-@end smallexample
-
-Other C++ compilers may not correctly implement the standard behavior.
-As a result, when you switch to @command{g++} from one of these compilers,
-you may discover that a program that appeared to work correctly in fact
-does not conform to the standard: @command{g++} reports as undefined
-symbols any static data members that lack definitions.
-
-
-@node Name lookup
-@subsection Name Lookup, Templates, and Accessing Members of Base Classes
-
-@cindex base class members
-@cindex two-stage name lookup
-@cindex dependent name lookup
-
-The C++ standard prescribes that all names that are not dependent on
-template parameters are bound to their present definitions when parsing
-a template function or class.@footnote{The C++ standard just uses the
-term ``dependent'' for names that depend on the type or value of
-template parameters. This shorter term will also be used in the rest of
-this section.} Only names that are dependent are looked up at the point
-of instantiation. For example, consider
-
-@smallexample
- void foo(double);
-
- struct A @{
- template <typename T>
- void f () @{
- foo (1); // @r{1}
- int i = N; // @r{2}
- T t;
- t.bar(); // @r{3}
- foo (t); // @r{4}
- @}
-
- static const int N;
- @};
-@end smallexample
-
-Here, the names @code{foo} and @code{N} appear in a context that does
-not depend on the type of @code{T}. The compiler will thus require that
-they are defined in the context of use in the template, not only before
-the point of instantiation, and will here use @code{::foo(double)} and
-@code{A::N}, respectively. In particular, it will convert the integer
-value to a @code{double} when passing it to @code{::foo(double)}.
-
-Conversely, @code{bar} and the call to @code{foo} in the fourth marked
-line are used in contexts that do depend on the type of @code{T}, so
-they are only looked up at the point of instantiation, and you can
-provide declarations for them after declaring the template, but before
-instantiating it. In particular, if you instantiate @code{A::f<int>},
-the last line will call an overloaded @code{::foo(int)} if one was
-provided, even if after the declaration of @code{struct A}.
-
-This distinction between lookup of dependent and non-dependent names is
-called two-stage (or dependent) name lookup. G++ implements it
-since version 3.4.
-
-Two-stage name lookup sometimes leads to situations with behavior
-different from non-template codes. The most common is probably this:
-
-@smallexample
- template <typename T> struct Base @{
- int i;
- @};
-
- template <typename T> struct Derived : public Base<T> @{
- int get_i() @{ return i; @}
- @};
-@end smallexample
-
-In @code{get_i()}, @code{i} is not used in a dependent context, so the
-compiler will look for a name declared at the enclosing namespace scope
-(which is the global scope here). It will not look into the base class,
-since that is dependent and you may declare specializations of
-@code{Base} even after declaring @code{Derived}, so the compiler cannot
-really know what @code{i} would refer to. If there is no global
-variable @code{i}, then you will get an error message.
-
-In order to make it clear that you want the member of the base class,
-you need to defer lookup until instantiation time, at which the base
-class is known. For this, you need to access @code{i} in a dependent
-context, by either using @code{this->i} (remember that @code{this} is of
-type @code{Derived<T>*}, so is obviously dependent), or using
-@code{Base<T>::i}. Alternatively, @code{Base<T>::i} might be brought
-into scope by a @code{using}-declaration.
-
-Another, similar example involves calling member functions of a base
-class:
-
-@smallexample
- template <typename T> struct Base @{
- int f();
- @};
-
- template <typename T> struct Derived : Base<T> @{
- int g() @{ return f(); @};
- @};
-@end smallexample
-
-Again, the call to @code{f()} is not dependent on template arguments
-(there are no arguments that depend on the type @code{T}, and it is also
-not otherwise specified that the call should be in a dependent context).
-Thus a global declaration of such a function must be available, since
-the one in the base class is not visible until instantiation time. The
-compiler will consequently produce the following error message:
-
-@smallexample
- x.cc: In member function `int Derived<T>::g()':
- x.cc:6: error: there are no arguments to `f' that depend on a template
- parameter, so a declaration of `f' must be available
- x.cc:6: error: (if you use `-fpermissive', G++ will accept your code, but
- allowing the use of an undeclared name is deprecated)
-@end smallexample
-
-To make the code valid either use @code{this->f()}, or
-@code{Base<T>::f()}. Using the @option{-fpermissive} flag will also let
-the compiler accept the code, by marking all function calls for which no
-declaration is visible at the time of definition of the template for
-later lookup at instantiation time, as if it were a dependent call.
-We do not recommend using @option{-fpermissive} to work around invalid
-code, and it will also only catch cases where functions in base classes
-are called, not where variables in base classes are used (as in the
-example above).
-
-Note that some compilers (including G++ versions prior to 3.4) get these
-examples wrong and accept above code without an error. Those compilers
-do not implement two-stage name lookup correctly.
-
-
-@node Temporaries
-@subsection Temporaries May Vanish Before You Expect
-
-@cindex temporaries, lifetime of
-@cindex portions of temporary objects, pointers to
-It is dangerous to use pointers or references to @emph{portions} of a
-temporary object. The compiler may very well delete the object before
-you expect it to, leaving a pointer to garbage. The most common place
-where this problem crops up is in classes like string classes,
-especially ones that define a conversion function to type @code{char *}
-or @code{const char *}---which is one reason why the standard
-@code{string} class requires you to call the @code{c_str} member
-function. However, any class that returns a pointer to some internal
-structure is potentially subject to this problem.
-
-For example, a program may use a function @code{strfunc} that returns
-@code{string} objects, and another function @code{charfunc} that
-operates on pointers to @code{char}:
-
-@smallexample
-string strfunc ();
-void charfunc (const char *);
-
-void
-f ()
-@{
- const char *p = strfunc().c_str();
- @dots{}
- charfunc (p);
- @dots{}
- charfunc (p);
-@}
-@end smallexample
-
-@noindent
-In this situation, it may seem reasonable to save a pointer to the C
-string returned by the @code{c_str} member function and use that rather
-than call @code{c_str} repeatedly. However, the temporary string
-created by the call to @code{strfunc} is destroyed after @code{p} is
-initialized, at which point @code{p} is left pointing to freed memory.
-
-Code like this may run successfully under some other compilers,
-particularly obsolete cfront-based compilers that delete temporaries
-along with normal local variables. However, the GNU C++ behavior is
-standard-conforming, so if your program depends on late destruction of
-temporaries it is not portable.
-
-The safe way to write such code is to give the temporary a name, which
-forces it to remain until the end of the scope of the name. For
-example:
-
-@smallexample
-const string& tmp = strfunc ();
-charfunc (tmp.c_str ());
-@end smallexample
-
-@node Copy Assignment
-@subsection Implicit Copy-Assignment for Virtual Bases
-
-When a base class is virtual, only one subobject of the base class
-belongs to each full object. Also, the constructors and destructors are
-invoked only once, and called from the most-derived class. However, such
-objects behave unspecified when being assigned. For example:
-
-@smallexample
-struct Base@{
- char *name;
- Base(const char *n) : name(strdup(n))@{@}
- Base& operator= (const Base& other)@{
- free (name);
- name = strdup (other.name);
- return *this;
- @}
-@};
-
-struct A:virtual Base@{
- int val;
- A():Base("A")@{@}
-@};
-
-struct B:virtual Base@{
- int bval;
- B():Base("B")@{@}
-@};
-
-struct Derived:public A, public B@{
- Derived():Base("Derived")@{@}
-@};
-
-void func(Derived &d1, Derived &d2)
-@{
- d1 = d2;
-@}
-@end smallexample
-
-The C++ standard specifies that @samp{Base::Base} is only called once
-when constructing or copy-constructing a Derived object. It is
-unspecified whether @samp{Base::operator=} is called more than once when
-the implicit copy-assignment for Derived objects is invoked (as it is
-inside @samp{func} in the example).
-
-G++ implements the ``intuitive'' algorithm for copy-assignment: assign all
-direct bases, then assign all members. In that algorithm, the virtual
-base subobject can be encountered more than once. In the example, copying
-proceeds in the following order: @samp{name} (via @code{strdup}),
-@samp{val}, @samp{name} again, and @samp{bval}.
-
-If application code relies on copy-assignment, a user-defined
-copy-assignment operator removes any uncertainties. With such an
-operator, the application can define whether and how the virtual base
-subobject is assigned.
-
-@node Non-bugs
-@section Certain Changes We Don't Want to Make
-
-This section lists changes that people frequently request, but which
-we do not make because we think GCC is better without them.
-
-@itemize @bullet
-@item
-Checking the number and type of arguments to a function which has an
-old-fashioned definition and no prototype.
-
-Such a feature would work only occasionally---only for calls that appear
-in the same file as the called function, following the definition. The
-only way to check all calls reliably is to add a prototype for the
-function. But adding a prototype eliminates the motivation for this
-feature. So the feature is not worthwhile.
-
-@item
-Warning about using an expression whose type is signed as a shift count.
-
-Shift count operands are probably signed more often than unsigned.
-Warning about this would cause far more annoyance than good.
-
-@item
-Warning about assigning a signed value to an unsigned variable.
-
-Such assignments must be very common; warning about them would cause
-more annoyance than good.
-
-@item
-Warning when a non-void function value is ignored.
-
-C contains many standard functions that return a value that most
-programs choose to ignore. One obvious example is @code{printf}.
-Warning about this practice only leads the defensive programmer to
-clutter programs with dozens of casts to @code{void}. Such casts are
-required so frequently that they become visual noise. Writing those
-casts becomes so automatic that they no longer convey useful
-information about the intentions of the programmer. For functions
-where the return value should never be ignored, use the
-@code{warn_unused_result} function attribute (@pxref{Function
-Attributes}).
-
-@item
-@opindex fshort-enums
-Making @option{-fshort-enums} the default.
-
-This would cause storage layout to be incompatible with most other C
-compilers. And it doesn't seem very important, given that you can get
-the same result in other ways. The case where it matters most is when
-the enumeration-valued object is inside a structure, and in that case
-you can specify a field width explicitly.
-
-@item
-Making bit-fields unsigned by default on particular machines where ``the
-ABI standard'' says to do so.
-
-The ISO C standard leaves it up to the implementation whether a bit-field
-declared plain @code{int} is signed or not. This in effect creates two
-alternative dialects of C@.
-
-@opindex fsigned-bitfields
-@opindex funsigned-bitfields
-The GNU C compiler supports both dialects; you can specify the signed
-dialect with @option{-fsigned-bitfields} and the unsigned dialect with
-@option{-funsigned-bitfields}. However, this leaves open the question of
-which dialect to use by default.
-
-Currently, the preferred dialect makes plain bit-fields signed, because
-this is simplest. Since @code{int} is the same as @code{signed int} in
-every other context, it is cleanest for them to be the same in bit-fields
-as well.
-
-Some computer manufacturers have published Application Binary Interface
-standards which specify that plain bit-fields should be unsigned. It is
-a mistake, however, to say anything about this issue in an ABI@. This is
-because the handling of plain bit-fields distinguishes two dialects of C@.
-Both dialects are meaningful on every type of machine. Whether a
-particular object file was compiled using signed bit-fields or unsigned
-is of no concern to other object files, even if they access the same
-bit-fields in the same data structures.
-
-A given program is written in one or the other of these two dialects.
-The program stands a chance to work on most any machine if it is
-compiled with the proper dialect. It is unlikely to work at all if
-compiled with the wrong dialect.
-
-Many users appreciate the GNU C compiler because it provides an
-environment that is uniform across machines. These users would be
-inconvenienced if the compiler treated plain bit-fields differently on
-certain machines.
-
-Occasionally users write programs intended only for a particular machine
-type. On these occasions, the users would benefit if the GNU C compiler
-were to support by default the same dialect as the other compilers on
-that machine. But such applications are rare. And users writing a
-program to run on more than one type of machine cannot possibly benefit
-from this kind of compatibility.
-
-This is why GCC does and will treat plain bit-fields in the same
-fashion on all types of machines (by default).
-
-There are some arguments for making bit-fields unsigned by default on all
-machines. If, for example, this becomes a universal de facto standard,
-it would make sense for GCC to go along with it. This is something
-to be considered in the future.
-
-(Of course, users strongly concerned about portability should indicate
-explicitly in each bit-field whether it is signed or not. In this way,
-they write programs which have the same meaning in both C dialects.)
-
-@item
-@opindex ansi
-@opindex std
-Undefining @code{__STDC__} when @option{-ansi} is not used.
-
-Currently, GCC defines @code{__STDC__} unconditionally. This provides
-good results in practice.
-
-Programmers normally use conditionals on @code{__STDC__} to ask whether
-it is safe to use certain features of ISO C, such as function
-prototypes or ISO token concatenation. Since plain @command{gcc} supports
-all the features of ISO C, the correct answer to these questions is
-``yes''.
-
-Some users try to use @code{__STDC__} to check for the availability of
-certain library facilities. This is actually incorrect usage in an ISO
-C program, because the ISO C standard says that a conforming
-freestanding implementation should define @code{__STDC__} even though it
-does not have the library facilities. @samp{gcc -ansi -pedantic} is a
-conforming freestanding implementation, and it is therefore required to
-define @code{__STDC__}, even though it does not come with an ISO C
-library.
-
-Sometimes people say that defining @code{__STDC__} in a compiler that
-does not completely conform to the ISO C standard somehow violates the
-standard. This is illogical. The standard is a standard for compilers
-that claim to support ISO C, such as @samp{gcc -ansi}---not for other
-compilers such as plain @command{gcc}. Whatever the ISO C standard says
-is relevant to the design of plain @command{gcc} without @option{-ansi} only
-for pragmatic reasons, not as a requirement.
-
-GCC normally defines @code{__STDC__} to be 1, and in addition
-defines @code{__STRICT_ANSI__} if you specify the @option{-ansi} option,
-or a @option{-std} option for strict conformance to some version of ISO C@.
-On some hosts, system include files use a different convention, where
-@code{__STDC__} is normally 0, but is 1 if the user specifies strict
-conformance to the C Standard. GCC follows the host convention when
-processing system include files, but when processing user files it follows
-the usual GNU C convention.
-
-@item
-Undefining @code{__STDC__} in C++.
-
-Programs written to compile with C++-to-C translators get the
-value of @code{__STDC__} that goes with the C compiler that is
-subsequently used. These programs must test @code{__STDC__}
-to determine what kind of C preprocessor that compiler uses:
-whether they should concatenate tokens in the ISO C fashion
-or in the traditional fashion.
-
-These programs work properly with GNU C++ if @code{__STDC__} is defined.
-They would not work otherwise.
-
-In addition, many header files are written to provide prototypes in ISO
-C but not in traditional C@. Many of these header files can work without
-change in C++ provided @code{__STDC__} is defined. If @code{__STDC__}
-is not defined, they will all fail, and will all need to be changed to
-test explicitly for C++ as well.
-
-@item
-Deleting ``empty'' loops.
-
-Historically, GCC has not deleted ``empty'' loops under the
-assumption that the most likely reason you would put one in a program is
-to have a delay, so deleting them will not make real programs run any
-faster.
-
-However, the rationale here is that optimization of a nonempty loop
-cannot produce an empty one. This held for carefully written C compiled
-with less powerful optimizers but is not always the case for carefully
-written C++ or with more powerful optimizers.
-Thus GCC will remove operations from loops whenever it can determine
-those operations are not externally visible (apart from the time taken
-to execute them, of course). In case the loop can be proved to be finite,
-GCC will also remove the loop itself.
-
-Be aware of this when performing timing tests, for instance the
-following loop can be completely removed, provided
-@code{some_expression} can provably not change any global state.
-
-@smallexample
-@{
- int sum = 0;
- int ix;
-
- for (ix = 0; ix != 10000; ix++)
- sum += some_expression;
-@}
-@end smallexample
-
-Even though @code{sum} is accumulated in the loop, no use is made of
-that summation, so the accumulation can be removed.
-
-@item
-Making side effects happen in the same order as in some other compiler.
-
-@cindex side effects, order of evaluation
-@cindex order of evaluation, side effects
-It is never safe to depend on the order of evaluation of side effects.
-For example, a function call like this may very well behave differently
-from one compiler to another:
-
-@smallexample
-void func (int, int);
-
-int i = 2;
-func (i++, i++);
-@end smallexample
-
-There is no guarantee (in either the C or the C++ standard language
-definitions) that the increments will be evaluated in any particular
-order. Either increment might happen first. @code{func} might get the
-arguments @samp{2, 3}, or it might get @samp{3, 2}, or even @samp{2, 2}.
-
-@item
-Making certain warnings into errors by default.
-
-Some ISO C testsuites report failure when the compiler does not produce
-an error message for a certain program.
-
-@opindex pedantic-errors
-ISO C requires a ``diagnostic'' message for certain kinds of invalid
-programs, but a warning is defined by GCC to count as a diagnostic. If
-GCC produces a warning but not an error, that is correct ISO C support.
-If testsuites call this ``failure'', they should be run with the GCC
-option @option{-pedantic-errors}, which will turn these warnings into
-errors.
-
-@end itemize
-
-@node Warnings and Errors
-@section Warning Messages and Error Messages
-
-@cindex error messages
-@cindex warnings vs errors
-@cindex messages, warning and error
-The GNU compiler can produce two kinds of diagnostics: errors and
-warnings. Each kind has a different purpose:
-
-@itemize @w{}
-@item
-@dfn{Errors} report problems that make it impossible to compile your
-program. GCC reports errors with the source file name and line
-number where the problem is apparent.
-
-@item
-@dfn{Warnings} report other unusual conditions in your code that
-@emph{may} indicate a problem, although compilation can (and does)
-proceed. Warning messages also report the source file name and line
-number, but include the text @samp{warning:} to distinguish them
-from error messages.
-@end itemize
-
-Warnings may indicate danger points where you should check to make sure
-that your program really does what you intend; or the use of obsolete
-features; or the use of nonstandard features of GNU C or C++. Many
-warnings are issued only if you ask for them, with one of the @option{-W}
-options (for instance, @option{-Wall} requests a variety of useful
-warnings).
-
-@opindex pedantic
-@opindex pedantic-errors
-GCC always tries to compile your program if possible; it never
-gratuitously rejects a program whose meaning is clear merely because
-(for instance) it fails to conform to a standard. In some cases,
-however, the C and C++ standards specify that certain extensions are
-forbidden, and a diagnostic @emph{must} be issued by a conforming
-compiler. The @option{-pedantic} option tells GCC to issue warnings in
-such cases; @option{-pedantic-errors} says to make them errors instead.
-This does not mean that @emph{all} non-ISO constructs get warnings
-or errors.
-
-@xref{Warning Options,,Options to Request or Suppress Warnings}, for
-more detail on these and related command-line options.
+++ /dev/null
-@c Copyright (C) 2018-2022 Free Software Foundation, Inc.
-@c Free Software Foundation, Inc.
-@c This is part of the GCC manual.
-@c For copying conditions, see the file gcc.texi.
-
-@node User Experience Guidelines
-@chapter User Experience Guidelines
-@cindex user experience guidelines
-@cindex guidelines, user experience
-
-To borrow a slogan from
-@uref{https://elm-lang.org/news/compilers-as-assistants, Elm},
-
-@quotation
-@strong{Compilers should be assistants, not adversaries.} A compiler should
-not just detect bugs, it should then help you understand why there is a bug.
-It should not berate you in a robot voice, it should give you specific hints
-that help you write better code. Ultimately, a compiler should make
-programming faster and more fun!
-@author Evan Czaplicki
-@end quotation
-
-This chapter provides guidelines on how to implement diagnostics and
-command-line options in ways that we hope achieve the above ideal.
-
-@menu
-* Guidelines for Diagnostics:: How to implement diagnostics.
-* Guidelines for Options:: Guidelines for command-line options.
-@end menu
-
-
-@node Guidelines for Diagnostics
-@section Guidelines for Diagnostics
-@cindex guidelines for diagnostics
-@cindex diagnostics, guidelines for
-
-@subsection Talk in terms of the user's code
-
-Diagnostics should be worded in terms of the user's source code, and the
-source language, rather than GCC's own implementation details.
-
-@subsection Diagnostics are actionable
-@cindex diagnostics, actionable
-
-A good diagnostic is @dfn{actionable}: it should assist the user in
-taking action.
-
-Consider what an end user will want to do when encountering a diagnostic.
-
-Given an error, an end user will think: ``How do I fix this?''
-
-Given a warning, an end user will think:
-
-@itemize @bullet
-@item
-``Is this a real problem?''
-@item
-``Do I care?''
-@item
-if they decide it's genuine: ``How do I fix this?''
-@end itemize
-
-A good diagnostic provides pertinent information to allow the user to
-easily answer the above questions.
-
-@subsection The user's attention is important
-
-A perfect compiler would issue a warning on every aspect of the user's
-source code that ought to be fixed, and issue no other warnings.
-Naturally, this ideal is impossible to achieve.
-
-@cindex signal-to-noise ratio (metaphorical usage for diagnostics)
-@cindex diagnostics, false positive
-@cindex diagnostics, true positive
-@cindex false positive
-@cindex true positive
-
-Warnings should have a good @dfn{signal-to-noise ratio}: we should have few
-@dfn{false positives} (falsely issuing a warning when no warning is
-warranted) and few @dfn{false negatives} (failing to issue a warning when
-one @emph{is} justified).
-
-Note that a false positive can mean, in practice, a warning that the
-user doesn't agree with. Ideally a diagnostic should contain enough
-information to allow the user to make an informed choice about whether
-they should care (and how to fix it), but a balance must be drawn against
-overloading the user with irrelevant data.
-
-@subsection Sometimes the user didn't write the code
-
-GCC is typically used in two different ways:
-
-@itemize @bullet
-@item
-Semi-interactive usage: GCC is used as a development tool when the user
-is writing code, as the ``compile'' part of the ``edit-compile-debug''
-cycle. The user is actively hacking on the code themself (perhaps a
-project they wrote, or someone else's), where they just made a change
-to the code and want to see what happens, and to be warned about
-mistakes.
-
-@item
-Batch rebuilds: where the user is recompiling one or more existing
-packages, and GCC is a detail that's being invoked by various build
-scripts. Examples include a user trying to bring up an operating system
-consisting of hundreds of packages on a new CPU architecture, where the
-packages were written by many different people, or simply rebuilding
-packages after a dependency changed, where the user is hoping
-``nothing breaks'', since they are unfamiliar with the code.
-@end itemize
-
-Keep both of these styles of usage in mind when implementing diagnostics.
-
-@subsection Precision of Wording
-
-Provide the user with details that allow them to identify what the
-problem is. For example, the vaguely-worded message:
-
-@smallexample
-demo.c:1:1: warning: 'noinline' attribute ignored [-Wattributes]
- 1 | int foo __attribute__((noinline));
- | ^~~
-@end smallexample
-
-@noindent
-doesn't tell the user why the attribute was ignored, or what kind of
-entity the compiler thought the attribute was being applied to (the
-source location for the diagnostic is also poor;
-@pxref{input_location_example,,discussion of @code{input_location}}).
-A better message would be:
-
-@smallexample
-demo.c:1:24: warning: attribute 'noinline' on variable 'foo' was
- ignored [-Wattributes]
- 1 | int foo __attribute__((noinline));
- | ~~~ ~~~~~~~~~~~~~~~^~~~~~~~~
-demo.c:1:24: note: attribute 'noinline' is only applicable to functions
-@end smallexample
-
-@noindent
-which spells out the missing information (and fixes the location
-information, as discussed below).
-
-The above example uses a note to avoid a combinatorial explosion of possible
-messages.
-
-@subsection Try the diagnostic on real-world code
-
-It's worth testing a new warning on many instances of real-world code,
-written by different people, and seeing what it complains about, and
-what it doesn't complain about.
-
-This may suggest heuristics that silence common false positives.
-
-It may also suggest ways to improve the precision of the message.
-
-@subsection Make mismatches clear
-
-Many diagnostics relate to a mismatch between two different places in the
-user's source code. Examples include:
-@itemize @bullet
- @item
- a type mismatch, where the type at a usage site does not match the type
- at a declaration
-
- @item
- the argument count at a call site does not match the parameter count
- at the declaration
-
- @item
- something is erroneously duplicated (e.g.@: an error, due to breaking a
- uniqueness requirement, or a warning, if it's suggestive of a bug)
-
- @item
- an ``opened'' syntactic construct (such as an open-parenthesis) is not
- closed
-
- @c TODO: more examples?
-@end itemize
-
-In each case, the diagnostic should indicate @strong{both} pertinent
-locations (so that the user can easily see the problem and how to fix it).
-
-The standard way to do this is with a note (via @code{inform}). For
-example:
-
-@smallexample
- auto_diagnostic_group d;
- if (warning_at (loc, OPT_Wduplicated_cond,
- "duplicated %<if%> condition"))
- inform (EXPR_LOCATION (t), "previously used here");
-@end smallexample
-
-@noindent
-which leads to:
-
-@smallexample
-demo.c: In function 'test':
-demo.c:5:17: warning: duplicated 'if' condition [-Wduplicated-cond]
- 5 | else if (flag > 3)
- | ~~~~~^~~
-demo.c:3:12: note: previously used here
- 3 | if (flag > 3)
- | ~~~~~^~~
-@end smallexample
-
-@noindent
-The @code{inform} call should be guarded by the return value from the
-@code{warning_at} call so that the note isn't emitted when the warning
-is suppressed.
-
-For cases involving punctuation where the locations might be near
-each other, they can be conditionally consolidated via
-@code{gcc_rich_location::add_location_if_nearby}:
-
-@smallexample
- auto_diagnostic_group d;
- gcc_rich_location richloc (primary_loc);
- bool added secondary = richloc.add_location_if_nearby (secondary_loc);
- error_at (&richloc, "main message");
- if (!added secondary)
- inform (secondary_loc, "message for secondary");
-@end smallexample
-
-@noindent
-This will emit either one diagnostic with two locations:
-@smallexample
- demo.c:42:10: error: main message
- (foo)
- ~ ^
-@end smallexample
-
-@noindent
-or two diagnostics:
-
-@smallexample
- demo.c:42:4: error: main message
- foo)
- ^
- demo.c:40:2: note: message for secondary
- (
- ^
-@end smallexample
-
-@subsection Location Information
-@cindex diagnostics, locations
-@cindex location information
-@cindex source code, location information
-@cindex caret
-
-GCC's @code{location_t} type can support both ordinary locations,
-and locations relating to a macro expansion.
-
-As of GCC 6, ordinary locations changed from supporting just a
-point in the user's source code to supporting three points: the
-@dfn{caret} location, plus a start and a finish:
-
-@smallexample
- a = foo && bar;
- ~~~~^~~~~~
- | | |
- | | finish
- | caret
- start
-@end smallexample
-
-Tokens coming out of libcpp have locations of the form @code{caret == start},
-such as for @code{foo} here:
-
-@smallexample
- a = foo && bar;
- ^~~
- | |
- | finish
- caret == start
-@end smallexample
-
-Compound expressions should be reported using the location of the
-expression as a whole, rather than just of one token within it.
-
-For example, in @code{-Wformat}, rather than underlining just the first
-token of a bad argument:
-
-@smallexample
- printf("hello %i %s", (long)0, "world");
- ~^ ~
- %li
-@end smallexample
-
-@noindent
-the whole of the expression should be underlined, so that the user can
-easily identify what is being referred to:
-
-@smallexample
- printf("hello %i %s", (long)0, "world");
- ~^ ~~~~~~~
- %li
-@end smallexample
-
-@c this was r251239
-
-Avoid using the @code{input_location} global, and the diagnostic functions
-that implicitly use it---use @code{error_at} and @code{warning_at} rather
-than @code{error} and @code{warning}, and provide the most appropriate
-@code{location_t} value available at that phase of the compilation. It's
-possible to supply secondary @code{location_t} values via
-@code{rich_location}.
-
-@noindent
-@anchor{input_location_example}
-For example, in the example of imprecise wording above, generating the
-diagnostic using @code{warning}:
-
-@smallexample
- // BAD: implicitly uses @code{input_location}
- warning (OPT_Wattributes, "%qE attribute ignored", name);
-@end smallexample
-
-@noindent
-leads to:
-
-@smallexample
-// BAD: uses @code{input_location}
-demo.c:1:1: warning: 'noinline' attribute ignored [-Wattributes]
- 1 | int foo __attribute__((noinline));
- | ^~~
-@end smallexample
-
-@noindent
-which thus happened to use the location of the @code{int} token, rather
-than that of the attribute. Using @code{warning_at} with the location of
-the attribute, providing the location of the declaration in question
-as a secondary location, and adding a note:
-
-@smallexample
- auto_diagnostic_group d;
- gcc_rich_location richloc (attrib_loc);
- richloc.add_range (decl_loc);
- if (warning_at (OPT_Wattributes, &richloc,
- "attribute %qE on variable %qE was ignored", name))
- inform (attrib_loc, "attribute %qE is only applicable to functions");
-@end smallexample
-
-@noindent
-would lead to:
-
-@smallexample
-// OK: use location of attribute, with a secondary location
-demo.c:1:24: warning: attribute 'noinline' on variable 'foo' was
- ignored [-Wattributes]
- 1 | int foo __attribute__((noinline));
- | ~~~ ~~~~~~~~~~~~~~~^~~~~~~~~
-demo.c:1:24: note: attribute 'noinline' is only applicable to functions
-@end smallexample
-
-@c TODO labelling of ranges
-
-@subsection Coding Conventions
-
-See the @uref{https://gcc.gnu.org/codingconventions.html#Diagnostics,
-diagnostics section} of the GCC coding conventions.
-
-In the C++ front end, when comparing two types in a message, use @samp{%H}
-and @samp{%I} rather than @samp{%T}, as this allows the diagnostics
-subsystem to highlight differences between template-based types.
-For example, rather than using @samp{%qT}:
-
-@smallexample
- // BAD: a pair of %qT used in C++ front end for type comparison
- error_at (loc, "could not convert %qE from %qT to %qT", expr,
- TREE_TYPE (expr), type);
-@end smallexample
-
-@noindent
-which could lead to:
-
-@smallexample
-error: could not convert 'map<int, double>()' from 'map<int,double>'
- to 'map<int,int>'
-@end smallexample
-
-@noindent
-using @samp{%H} and @samp{%I} (via @samp{%qH} and @samp{%qI}):
-
-@smallexample
- // OK: compare types in C++ front end via %qH and %qI
- error_at (loc, "could not convert %qE from %qH to %qI", expr,
- TREE_TYPE (expr), type);
-@end smallexample
-
-@noindent
-allows the above output to be simplified to:
-
-@smallexample
-error: could not convert 'map<int, double>()' from 'map<[...],double>'
- to 'map<[...],int>'
-@end smallexample
-
-@noindent
-where the @code{double} and @code{int} are colorized to highlight them.
-
-@c %H and %I were added in r248698.
-
-@subsection Group logically-related diagnostics
-
-Use @code{auto_diagnostic_group} when issuing multiple related
-diagnostics (seen in various examples on this page). This informs the
-diagnostic subsystem that all diagnostics issued within the lifetime
-of the @code{auto_diagnostic_group} are related. For example,
-@option{-fdiagnostics-format=json} will treat the first diagnostic
-emitted within the group as a top-level diagnostic, and all subsequent
-diagnostics within the group as its children.
-
-@subsection Quoting
-Text should be quoted by either using the @samp{q} modifier in a directive
-such as @samp{%qE}, or by enclosing the quoted text in a pair of @samp{%<}
-and @samp{%>} directives, and never by using explicit quote characters.
-The directives handle the appropriate quote characters for each language
-and apply the correct color or highlighting.
-
-The following elements should be quoted in GCC diagnostics:
-
-@itemize @bullet
-@item
-Language keywords.
-@item
-Tokens.
-@item
-Boolean, numerical, character, and string constants that appear in the
-source code.
-@item
-Identifiers, including function, macro, type, and variable names.
-@end itemize
-
-Other elements such as numbers that do not refer to numeric constants that
-appear in the source code should not be quoted. For example, in the message:
-
-@smallexample
-argument %d of %qE must be a pointer type
-@end smallexample
-
-@noindent
-since the argument number does not refer to a numerical constant in the
-source code it should not be quoted.
-
-@subsection Spelling and Terminology
-
-See the @uref{https://gcc.gnu.org/codingconventions.html#Spelling
-Spelling, terminology and markup} section of the GCC coding conventions.
-
-@subsection Fix-it hints
-@cindex fix-it hints
-@cindex diagnostics guidelines, fix-it hints
-
-GCC's diagnostic subsystem can emit @dfn{fix-it hints}: small suggested
-edits to the user's source code.
-
-They are printed by default underneath the code in question. They
-can also be viewed via @option{-fdiagnostics-generate-patch} and
-@option{-fdiagnostics-parseable-fixits}. With the latter, an IDE
-ought to be able to offer to automatically apply the suggested fix.
-
-Fix-it hints contain code fragments, and thus they should not be marked
-for translation.
-
-Fix-it hints can be added to a diagnostic by using a @code{rich_location}
-rather than a @code{location_t} - the fix-it hints are added to the
-@code{rich_location} using one of the various @code{add_fixit} member
-functions of @code{rich_location}. They are documented with
-@code{rich_location} in @file{libcpp/line-map.h}.
-It's easiest to use the @code{gcc_rich_location} subclass of
-@code{rich_location} found in @file{gcc-rich-location.h}, as this
-implicitly supplies the @code{line_table} variable.
-
-For example:
-
-@smallexample
- if (const char *suggestion = hint.suggestion ())
- @{
- gcc_rich_location richloc (location);
- richloc.add_fixit_replace (suggestion);
- error_at (&richloc,
- "%qE does not name a type; did you mean %qs?",
- id, suggestion);
- @}
-@end smallexample
-
-@noindent
-which can lead to:
-
-@smallexample
-spellcheck-typenames.C:73:1: error: 'singed' does not name a type; did
- you mean 'signed'?
- 73 | singed char ch;
- | ^~~~~~
- | signed
-@end smallexample
-
-Non-trivial edits can be built up by adding multiple fix-it hints to one
-@code{rich_location}. It's best to express the edits in terms of the
-locations of individual tokens. Various handy functions for adding
-fix-it hints for idiomatic C and C++ can be seen in
-@file{gcc-rich-location.h}.
-
-@subsubsection Fix-it hints should work
-
-When implementing a fix-it hint, please verify that the suggested edit
-leads to fixed, compilable code. (Unfortunately, this currently must be
-done by hand using @option{-fdiagnostics-generate-patch}. It would be
-good to have an automated way of verifying that fix-it hints actually fix
-the code).
-
-For example, a ``gotcha'' here is to forget to add a space when adding a
-missing reserved word. Consider a C++ fix-it hint that adds
-@code{typename} in front of a template declaration. A naive way to
-implement this might be:
-
-@smallexample
-gcc_rich_location richloc (loc);
-// BAD: insertion is missing a trailing space
-richloc.add_fixit_insert_before ("typename");
-error_at (&richloc, "need %<typename%> before %<%T::%E%> because "
- "%qT is a dependent scope",
- parser->scope, id, parser->scope);
-@end smallexample
-
-@noindent
-When applied to the code, this might lead to:
-
-@smallexample
-T::type x;
-@end smallexample
-
-@noindent
-being ``corrected'' to:
-
-@smallexample
-typenameT::type x;
-@end smallexample
-
-@noindent
-In this case, the correct thing to do is to add a trailing space after
-@code{typename}:
-
-@smallexample
-gcc_rich_location richloc (loc);
-// OK: note that here we have a trailing space
-richloc.add_fixit_insert_before ("typename ");
-error_at (&richloc, "need %<typename%> before %<%T::%E%> because "
- "%qT is a dependent scope",
- parser->scope, id, parser->scope);
-@end smallexample
-
-@noindent
-leading to this corrected code:
-
-@smallexample
-typename T::type x;
-@end smallexample
-
-@subsubsection Express deletion in terms of deletion, not replacement
-
-It's best to express deletion suggestions in terms of deletion fix-it
-hints, rather than replacement fix-it hints. For example, consider this:
-
-@smallexample
- auto_diagnostic_group d;
- gcc_rich_location richloc (location_of (retval));
- tree name = DECL_NAME (arg);
- richloc.add_fixit_replace (IDENTIFIER_POINTER (name));
- warning_at (&richloc, OPT_Wredundant_move,
- "redundant move in return statement");
-@end smallexample
-
-@noindent
-which is intended to e.g.@: replace a @code{std::move} with the underlying
-value:
-
-@smallexample
- return std::move (retval);
- ~~~~~~~~~~^~~~~~~~
- retval
-@end smallexample
-
-@noindent
-where the change has been expressed as replacement, replacing
-with the name of the declaration.
-This works for simple cases, but consider this case:
-
-@smallexample
-#ifdef SOME_CONFIG_FLAG
-# define CONFIGURY_GLOBAL global_a
-#else
-# define CONFIGURY_GLOBAL global_b
-#endif
-
-int fn ()
-@{
- return std::move (CONFIGURY_GLOBAL /* some comment */);
-@}
-@end smallexample
-
-@noindent
-The above implementation erroneously strips out the macro and the
-comment in the fix-it hint:
-
-@smallexample
- return std::move (CONFIGURY_GLOBAL /* some comment */);
- ~~~~~~~~~~^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- global_a
-@end smallexample
-
-@noindent
-and thus this resulting code:
-
-@smallexample
- return global_a;
-@end smallexample
-
-@noindent
-It's better to do deletions in terms of deletions; deleting the
-@code{std::move (} and the trailing close-paren, leading to
-this:
-
-@smallexample
- return std::move (CONFIGURY_GLOBAL /* some comment */);
- ~~~~~~~~~~^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- CONFIGURY_GLOBAL /* some comment */
-@end smallexample
-
-@noindent
-and thus this result:
-
-@smallexample
- return CONFIGURY_GLOBAL /* some comment */;
-@end smallexample
-
-@noindent
-Unfortunately, the pertinent @code{location_t} values are not always
-available.
-
-@c the above was https://gcc.gnu.org/ml/gcc-patches/2018-08/msg01474.html
-
-@subsubsection Multiple suggestions
-
-In the rare cases where you need to suggest more than one mutually
-exclusive solution to a problem, this can be done by emitting
-multiple notes and calling
-@code{rich_location::fixits_cannot_be_auto_applied} on each note's
-@code{rich_location}. If this is called, then the fix-it hints in
-the @code{rich_location} will be printed, but will not be added to
-generated patches.
-
-
-@node Guidelines for Options
-@section Guidelines for Options
-@cindex command-line options, guidelines for
-@cindex options, guidelines for
-@cindex guidelines for options
-
-@c TODO
+++ /dev/null
-\input texinfo @c -*-texinfo-*-
-@c %**start of header
-@setfilename gfc-internals.info
-@set copyrights-gfortran 2007-2022
-
-@include gcc-common.texi
-
-@synindex tp cp
-
-@settitle GNU Fortran Compiler Internals
-
-@c %**end of header
-
-@c Use with @@smallbook.
-
-@c %** start of document
-
-@c Cause even numbered pages to be printed on the left hand side of
-@c the page and odd numbered pages to be printed on the right hand
-@c side of the page. Using this, you can print on both sides of a
-@c sheet of paper and have the text on the same part of the sheet.
-
-@c The text on right hand pages is pushed towards the right hand
-@c margin and the text on left hand pages is pushed toward the left
-@c hand margin.
-@c (To provide the reverse effect, set bindingoffset to -0.75in.)
-
-@c @tex
-@c \global\bindingoffset=0.75in
-@c \global\normaloffset =0.75in
-@c @end tex
-
-@copying
-Copyright @copyright{} @value{copyrights-gfortran} Free Software Foundation, Inc.
-
-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 the
-Invariant Sections being ``Funding Free Software'', the Front-Cover
-Texts being (a) (see below), and with the Back-Cover Texts being (b)
-(see below). A copy of the license is included in the section entitled
-``GNU Free Documentation License''.
-
-(a) The FSF's Front-Cover Text is:
-
- A GNU Manual
-
-(b) The FSF's Back-Cover Text is:
-
- You have freedom to copy and modify this GNU Manual, like GNU
- software. Copies published by the Free Software Foundation raise
- funds for GNU development.
-@end copying
-
-@ifinfo
-@dircategory Software development
-@direntry
-* gfortran: (gfortran). The GNU Fortran Compiler.
-@end direntry
-This file documents the internals of the GNU Fortran
-compiler, (@command{gfortran}).
-
-Published by the Free Software Foundation
-51 Franklin Street, Fifth Floor
-Boston, MA 02110-1301 USA
-
-@insertcopying
-@end ifinfo
-
-
-@setchapternewpage odd
-@titlepage
-@title GNU Fortran Internals
-@versionsubtitle
-@author The @t{gfortran} team
-@page
-@vskip 0pt plus 1filll
-Published by the Free Software Foundation@*
-51 Franklin Street, Fifth Floor@*
-Boston, MA 02110-1301, USA@*
-@c Last printed ??ber, 19??.@*
-@c Printed copies are available for $? each.@*
-@c ISBN ???
-@sp 1
-@insertcopying
-@end titlepage
-
-@summarycontents
-@contents
-
-@page
-
-@c ---------------------------------------------------------------------
-@c TexInfo table of contents.
-@c ---------------------------------------------------------------------
-
-@ifnottex
-@node Top
-@top Introduction
-@cindex Introduction
-
-This manual documents the internals of @command{gfortran},
-the GNU Fortran compiler.
-
-@ifset DEVELOPMENT
-@emph{Warning:} This document, and the compiler it describes, are still
-under development. While efforts are made to keep it up-to-date, it might
-not accurately reflect the status of the most recent GNU Fortran compiler.
-@end ifset
-
-@comment
-@comment When you add a new menu item, please keep the right hand
-@comment aligned to the same column. Do not use tabs. This provides
-@comment better formatting.
-@comment
-@menu
-* Introduction:: About this manual.
-* User Interface:: Code that Interacts with the User.
-* Frontend Data Structures::
- Data structures used by the frontend
-* Object Orientation:: Internals of Fortran 2003 OOP features.
-* Translating to GENERIC::
- Generating the intermediate language for later stages.
-* LibGFortran:: The LibGFortran Runtime Library.
-* GNU Free Documentation License::
- How you can copy and share this manual.
-* Index:: Index of this documentation.
-@end menu
-@end ifnottex
-
-@c ---------------------------------------------------------------------
-@c Introduction
-@c ---------------------------------------------------------------------
-
-@node Introduction
-@chapter Introduction
-
-@c The following duplicates the text on the TexInfo table of contents.
-@iftex
-This manual documents the internals of @command{gfortran}, the GNU Fortran
-compiler.
-
-@ifset DEVELOPMENT
-@emph{Warning:} This document, and the compiler it describes, are still
-under development. While efforts are made to keep it up-to-date, it
-might not accurately reflect the status of the most recent GNU Fortran
-compiler.
-@end ifset
-@end iftex
-
-At present, this manual is very much a work in progress, containing
-miscellaneous notes about the internals of the compiler. It is hoped
-that at some point in the future it will become a reasonably complete
-guide; in the interim, GNU Fortran developers are strongly encouraged to
-contribute to it as a way of keeping notes while working on the
-compiler.
-
-
-@c ---------------------------------------------------------------------
-@c Code that Interacts with the User
-@c ---------------------------------------------------------------------
-
-@node User Interface
-@chapter Code that Interacts with the User
-
-@menu
-* Command-Line Options:: Command-Line Options.
-* Error Handling:: Error Handling.
-@end menu
-
-
-@c ---------------------------------------------------------------------
-@c Command-Line Options
-@c ---------------------------------------------------------------------
-
-@node Command-Line Options
-@section Command-Line Options
-
-Command-line options for @command{gfortran} involve four interrelated
-pieces within the Fortran compiler code.
-
-The relevant command-line flag is defined in @file{lang.opt}, according
-to the documentation in @ref{Options,, Options, gccint, GNU Compiler
-Collection Internals}. This is then processed by the overall GCC
-machinery to create the code that enables @command{gfortran} and
-@command{gcc} to recognize the option in the command-line arguments and
-call the relevant handler function.
-
-This generated code calls the @code{gfc_handle_option} code in
-@file{options.cc} with an enumerator variable indicating which option is
-to be processed, and the relevant integer or string values associated
-with that option flag. Typically, @code{gfc_handle_option} uses these
-arguments to set global flags which record the option states.
-
-The global flags that record the option states are stored in the
-@code{gfc_option_t} struct, which is defined in @file{gfortran.h}.
-Before the options are processed, initial values for these flags are set
-in @code{gfc_init_option} in @file{options.cc}; these become the default
-values for the options.
-
-
-
-@c ---------------------------------------------------------------------
-@c Error Handling
-@c ---------------------------------------------------------------------
-
-@node Error Handling
-@section Error Handling
-
-The GNU Fortran compiler's parser operates by testing each piece of
-source code against a variety of matchers. In some cases, if these
-matchers do not match the source code, they will store an error message
-in a buffer. If the parser later finds a matcher that does correctly
-match the source code, then the buffered error is discarded. However,
-if the parser cannot find a match, then the buffered error message is
-reported to the user. This enables the compiler to provide more
-meaningful error messages even in the many cases where (erroneous)
-Fortran syntax is ambiguous due to things like the absence of reserved
-keywords.
-
-As an example of how this works, consider the following line:
-@smallexample
-IF = 3
-@end smallexample
-Hypothetically, this may get passed to the matcher for an @code{IF}
-statement. Since this could plausibly be an erroneous @code{IF}
-statement, the matcher will buffer an error message reporting the
-absence of an expected @samp{(} following an @code{IF}. Since no
-matchers reported an error-free match, however, the parser will also try
-matching this against a variable assignment. When @code{IF} is a valid
-variable, this will be parsed as an assignment statement, and the error
-discarded. However, when @code{IF} is not a valid variable, this
-buffered error message will be reported to the user.
-
-The error handling code is implemented in @file{error.cc}. Errors are
-normally entered into the buffer with the @code{gfc_error} function.
-Warnings go through a similar buffering process, and are entered into
-the buffer with @code{gfc_warning}. There is also a special-purpose
-function, @code{gfc_notify_std}, for things which have an error/warning
-status that depends on the currently-selected language standard.
-
-The @code{gfc_error_check} function checks the buffer for errors,
-reports the error message to the user if one exists, clears the buffer,
-and returns a flag to the user indicating whether or not an error
-existed. To check the state of the buffer without changing its state or
-reporting the errors, the @code{gfc_error_flag_test} function can be
-used. The @code{gfc_clear_error} function will clear out any errors in
-the buffer, without reporting them. The @code{gfc_warning_check} and
-@code{gfc_clear_warning} functions provide equivalent functionality for
-the warning buffer.
-
-Only one error and one warning can be in the buffers at a time, and
-buffering another will overwrite the existing one. In cases where one
-may wish to work on a smaller piece of source code without disturbing an
-existing error state, the @code{gfc_push_error}, @code{gfc_pop_error},
-and @code{gfc_free_error} mechanism exists to implement a stack for the
-error buffer.
-
-For cases where an error or warning should be reported immediately
-rather than buffered, the @code{gfc_error_now} and
-@code{gfc_warning_now} functions can be used. Normally, the compiler
-will continue attempting to parse the program after an error has
-occurred, but if this is not appropriate, the @code{gfc_fatal_error}
-function should be used instead. For errors that are always the result
-of a bug somewhere in the compiler, the @code{gfc_internal_error}
-function should be used.
-
-The syntax for the strings used to produce the error/warning message in
-the various error and warning functions is similar to the @code{printf}
-syntax, with @samp{%}-escapes to insert variable values. The details,
-and the allowable codes, are documented in the @code{error_print}
-function in @file{error.cc}.
-
-@c ---------------------------------------------------------------------
-@c Frontend Data Structures
-@c ---------------------------------------------------------------------
-
-@node Frontend Data Structures
-@chapter Frontend Data Structures
-@cindex data structures
-
-This chapter should describe the details necessary to understand how
-the various @code{gfc_*} data are used and interact. In general it is
-advisable to read the code in @file{dump-parse-tree.cc} as its routines
-should exhaust all possible valid combinations of content for these
-structures.
-
-@menu
-* gfc_code:: Representation of Executable Statements.
-* gfc_expr:: Representation of Values and Expressions.
-@end menu
-
-
-@c gfc_code
-@c --------
-
-@node gfc_code
-@section @code{gfc_code}
-@cindex statement chaining
-@tindex @code{gfc_code}
-@tindex @code{struct gfc_code}
-
-The executable statements in a program unit are represented by a
-nested chain of @code{gfc_code} structures. The type of statement is
-identified by the @code{op} member of the structure, the different
-possible values are enumerated in @code{gfc_exec_op}. A special
-member of this @code{enum} is @code{EXEC_NOP} which is used to
-represent the various @code{END} statements if they carry a label.
-Depending on the type of statement some of the other fields will be
-filled in. Fields that are generally applicable are the @code{next}
-and @code{here} fields. The former points to the next statement in
-the current block or is @code{NULL} if the current statement is the
-last in a block, @code{here} points to the statement label of the
-current statement.
-
-If the current statement is one of @code{IF}, @code{DO}, @code{SELECT}
-it starts a block, i.e.@: a nested level in the program. In order to
-represent this, the @code{block} member is set to point to a
-@code{gfc_code} structure whose @code{next} member starts the chain of
-statements inside the block; this structure's @code{op} member should be set to
-the same value as the parent structure's @code{op} member. The @code{SELECT}
-and @code{IF} statements may contain various blocks (the chain of @code{ELSE IF}
-and @code{ELSE} blocks or the various @code{CASE}s, respectively). These chains
-are linked-lists formed by the @code{block} members.
-
-Consider the following example code:
-
-@example
-IF (foo < 20) THEN
- PRINT *, "Too small"
- foo = 20
-ELSEIF (foo > 50) THEN
- PRINT *, "Too large"
- foo = 50
-ELSE
- PRINT *, "Good"
-END IF
-@end example
-
-This statement-block will be represented in the internal gfortran tree as
-follows, were the horizontal link-chains are those induced by the @code{next}
-members and vertical links down are those of @code{block}. @samp{==|} and
-@samp{--|} mean @code{NULL} pointers to mark the end of a chain:
-
-@example
-... ==> IF ==> ...
- |
- +--> IF foo < 20 ==> PRINT *, "Too small" ==> foo = 20 ==|
- |
- +--> IF foo > 50 ==> PRINT *, "Too large" ==> foo = 50 ==|
- |
- +--> ELSE ==> PRINT *, "Good" ==|
- |
- +--|
-@end example
-
-
-@subsection IF Blocks
-
-Conditionals are represented by @code{gfc_code} structures with their
-@code{op} member set to @code{EXEC_IF}. This structure's @code{block}
-member must point to another @code{gfc_code} node that is the header of the
-if-block. This header's @code{op} member must be set to @code{EXEC_IF}, too,
-its @code{expr} member holds the condition to check for, and its @code{next}
-should point to the code-chain of the statements to execute if the condition is
-true.
-
-If in addition an @code{ELSEIF} or @code{ELSE} block is present, the
-@code{block} member of the if-block-header node points to yet another
-@code{gfc_code} structure that is the header of the elseif- or else-block. Its
-structure is identical to that of the if-block-header, except that in case of an
-@code{ELSE} block without a new condition the @code{expr} member should be
-@code{NULL}. This block can itself have its @code{block} member point to the
-next @code{ELSEIF} or @code{ELSE} block if there's a chain of them.
-
-
-@subsection Loops
-
-@code{DO} loops are stored in the tree as @code{gfc_code} nodes with their
-@code{op} set to @code{EXEC_DO} for a @code{DO} loop with iterator variable and
-to @code{EXEC_DO_WHILE} for infinite @code{DO}s and @code{DO WHILE} blocks.
-Their @code{block} member should point to a @code{gfc_code} structure heading
-the code-chain of the loop body; its @code{op} member should be set to
-@code{EXEC_DO} or @code{EXEC_DO_WHILE}, too, respectively.
-
-For @code{DO WHILE} loops, the loop condition is stored on the top
-@code{gfc_code} structure's @code{expr} member; @code{DO} forever loops are
-simply @code{DO WHILE} loops with a constant @code{.TRUE.} loop condition in
-the internal representation.
-
-Similarly, @code{DO} loops with an iterator have instead of the condition their
-@code{ext.iterator} member set to the correct values for the loop iterator
-variable and its range.
-
-
-@subsection @code{SELECT} Statements
-
-A @code{SELECT} block is introduced by a @code{gfc_code} structure with an
-@code{op} member of @code{EXEC_SELECT} and @code{expr} containing the expression
-to evaluate and test. Its @code{block} member starts a list of @code{gfc_code}
-structures linked together by their @code{block} members that stores the various
-@code{CASE} parts.
-
-Each @code{CASE} node has its @code{op} member set to @code{EXEC_SELECT}, too,
-its @code{next} member points to the code-chain to be executed in the current
-case-block, and @code{extx.case_list} contains the case-values this block
-corresponds to. The @code{block} member links to the next case in the list.
-
-
-@subsection @code{BLOCK} and @code{ASSOCIATE}
-
-The code related to a @code{BLOCK} statement is stored inside an
-@code{gfc_code} structure (say @var{c})
-with @code{c.op} set to @code{EXEC_BLOCK}. The
-@code{gfc_namespace} holding the locally defined variables of the
-@code{BLOCK} is stored in @code{c.ext.block.ns}. The code inside the
-construct is in @code{c.code}.
-
-@code{ASSOCIATE} constructs are based on @code{BLOCK} and thus also have
-the internal storage structure described above (including @code{EXEC_BLOCK}).
-However, for them @code{c.ext.block.assoc} is set additionally and points
-to a linked list of @code{gfc_association_list} structures. Those
-structures basically store a link of associate-names to target expressions.
-The associate-names themselves are still also added to the @code{BLOCK}'s
-namespace as ordinary symbols, but they have their @code{gfc_symbol}'s
-member @code{assoc} set also pointing to the association-list structure.
-This way associate-names can be distinguished from ordinary variables
-and their target expressions identified.
-
-For association to expressions (as opposed to variables), at the very beginning
-of the @code{BLOCK} construct assignments are automatically generated to
-set the corresponding variables to their target expressions' values, and
-later on the compiler simply disallows using such associate-names in contexts
-that may change the value.
-
-
-@c gfc_expr
-@c --------
-
-@node gfc_expr
-@section @code{gfc_expr}
-@tindex @code{gfc_expr}
-@tindex @code{struct gfc_expr}
-
-Expressions and ``values'', including constants, variable-, array- and
-component-references as well as complex expressions consisting of operators and
-function calls are internally represented as one or a whole tree of
-@code{gfc_expr} objects. The member @code{expr_type} specifies the overall
-type of an expression (for instance, @code{EXPR_CONSTANT} for constants or
-@code{EXPR_VARIABLE} for variable references). The members @code{ts} and
-@code{rank} as well as @code{shape}, which can be @code{NULL}, specify
-the type, rank and, if applicable, shape of the whole expression or expression
-tree of which the current structure is the root. @code{where} is the locus of
-this expression in the source code.
-
-Depending on the flavor of the expression being described by the object
-(that is, the value of its @code{expr_type} member), the corresponding structure
-in the @code{value} union will usually contain additional data describing the
-expression's value in a type-specific manner. The @code{ref} member is used to
-build chains of (array-, component- and substring-) references if the expression
-in question contains such references, see below for details.
-
-
-@subsection Constants
-
-Scalar constants are represented by @code{gfc_expr} nodes with their
-@code{expr_type} set to @code{EXPR_CONSTANT}. The constant's value shall
-already be known at compile-time and is stored in the @code{logical},
-@code{integer}, @code{real}, @code{complex} or @code{character} struct inside
-@code{value}, depending on the constant's type specification.
-
-
-@subsection Operators
-
-Operator-expressions are expressions that are the result of the execution of
-some operator on one or two operands. The expressions have an @code{expr_type}
-of @code{EXPR_OP}. Their @code{value.op} structure contains additional data.
-
-@code{op1} and optionally @code{op2} if the operator is binary point to the
-two operands, and @code{operator} or @code{uop} describe the operator that
-should be evaluated on these operands, where @code{uop} describes a user-defined
-operator.
-
-
-@subsection Function Calls
-
-If the expression is the return value of a function-call, its @code{expr_type}
-is set to @code{EXPR_FUNCTION}, and @code{symtree} must point to the symtree
-identifying the function to be called. @code{value.function.actual} holds the
-actual arguments given to the function as a linked list of
-@code{gfc_actual_arglist} nodes.
-
-The other members of @code{value.function} describe the function being called
-in more detail, containing a link to the intrinsic symbol or user-defined
-function symbol if the call is to an intrinsic or external function,
-respectively. These values are determined during resolution-phase from the
-structure's @code{symtree} member.
-
-A special case of function calls are ``component calls'' to type-bound
-procedures; those have the @code{expr_type} @code{EXPR_COMPCALL} with
-@code{value.compcall} containing the argument list and the procedure called,
-while @code{symtree} and @code{ref} describe the object on which the procedure
-was called in the same way as a @code{EXPR_VARIABLE} expression would.
-@xref{Type-bound Procedures}.
-
-
-@subsection Array- and Structure-Constructors
-
-Array- and structure-constructors (one could probably call them ``array-'' and
-``derived-type constants'') are @code{gfc_expr} structures with their
-@code{expr_type} member set to @code{EXPR_ARRAY} or @code{EXPR_STRUCTURE},
-respectively. For structure constructors, @code{symtree} points to the
-derived-type symbol for the type being constructed.
-
-The values for initializing each array element or structure component are
-stored as linked-list of @code{gfc_constructor} nodes in the
-@code{value.constructor} member.
-
-
-@subsection Null
-
-@code{NULL} is a special value for pointers; it can be of different base types.
-Such a @code{NULL} value is represented in the internal tree by a
-@code{gfc_expr} node with @code{expr_type} @code{EXPR_NULL}. If the base type
-of the @code{NULL} expression is known, it is stored in @code{ts} (that's for
-instance the case for default-initializers of @code{ALLOCATABLE} components),
-but this member can also be set to @code{BT_UNKNOWN} if the information is not
-available (for instance, when the expression is a pointer-initializer
-@code{NULL()}).
-
-
-@subsection Variables and Reference Expressions
-
-Variable references are @code{gfc_expr} structures with their @code{expr_type}
-set to @code{EXPR_VARIABLE}; their @code{symtree} should point to the variable
-that is referenced.
-
-For this type of expression, it's also possible to chain array-, component-
-or substring-references to the original expression to get something like
-@samp{struct%component(2:5)}, where @code{component} is either an array or
-a @code{CHARACTER} member of @code{struct} that is of some derived-type. Such a
-chain of references is achieved by a linked list headed by @code{ref} of the
-@code{gfc_expr} node. For the example above it would be (@samp{==|} is the
-last @code{NULL} pointer):
-
-@smallexample
-EXPR_VARIABLE(struct) ==> REF_COMPONENT(component) ==> REF_ARRAY(2:5) ==|
-@end smallexample
-
-If @code{component} is a string rather than an array, the last element would be
-a @code{REF_SUBSTRING} reference, of course. If the variable itself or some
-component referenced is an array and the expression should reference the whole
-array rather than being followed by an array-element or -section reference, a
-@code{REF_ARRAY} reference must be built as the last element in the chain with
-an array-reference type of @code{AR_FULL}. Consider this example code:
-
-@smallexample
-TYPE :: mytype
- INTEGER :: array(42)
-END TYPE mytype
-
-TYPE(mytype) :: variable
-INTEGER :: local_array(5)
-
-CALL do_something (variable%array, local_array)
-@end smallexample
-
-The @code{gfc_expr} nodes representing the arguments to the @samp{do_something}
-call will have a reference-chain like this:
-
-@smallexample
-EXPR_VARIABLE(variable) ==> REF_COMPONENT(array) ==> REF_ARRAY(FULL) ==|
-EXPR_VARIABLE(local_array) ==> REF_ARRAY(FULL) ==|
-@end smallexample
-
-
-@subsection Constant Substring References
-
-@code{EXPR_SUBSTRING} is a special type of expression that encodes a substring
-reference of a constant string, as in the following code snippet:
-
-@smallexample
-x = "abcde"(1:2)
-@end smallexample
-
-In this case, @code{value.character} contains the full string's data as if it
-was a string constant, but the @code{ref} member is also set and points to a
-substring reference as described in the subsection above.
-
-
-@c ---------------------------------------------------------------------
-@c F2003 OOP
-@c ---------------------------------------------------------------------
-
-@node Object Orientation
-@chapter Internals of Fortran 2003 OOP Features
-
-@menu
-* Type-bound Procedures:: Type-bound procedures.
-* Type-bound Operators:: Type-bound operators.
-@end menu
-
-
-@c Type-bound procedures
-@c ---------------------
-
-@node Type-bound Procedures
-@section Type-bound Procedures
-
-Type-bound procedures are stored in the @code{tb_sym_root} of the namespace
-@code{f2k_derived} associated with the derived-type symbol as @code{gfc_symtree}
-nodes. The name and symbol of these symtrees corresponds to the binding-name
-of the procedure, i.e. the name that is used to call it from the context of an
-object of the derived-type.
-
-In addition, this type of symtrees stores in @code{n.tb} a struct of type
-@code{gfc_typebound_proc} containing the additional data needed: The
-binding attributes (like @code{PASS} and @code{NOPASS}, @code{NON_OVERRIDABLE}
-or the access-specifier), the binding's target(s) and, if the current binding
-overrides or extends an inherited binding of the same name, @code{overridden}
-points to this binding's @code{gfc_typebound_proc} structure.
-
-
-@subsection Specific Bindings
-@c --------------------------
-
-For specific bindings (declared with @code{PROCEDURE}), if they have a
-passed-object argument, the passed-object dummy argument is first saved by its
-name, and later during resolution phase the corresponding argument is looked for
-and its position remembered as @code{pass_arg_num} in @code{gfc_typebound_proc}.
-The binding's target procedure is pointed-to by @code{u.specific}.
-
-@code{DEFERRED} bindings are just like ordinary specific bindings, except
-that their @code{deferred} flag is set of course and that @code{u.specific}
-points to their ``interface'' defining symbol (might be an abstract interface)
-instead of the target procedure.
-
-At the moment, all type-bound procedure calls are statically dispatched and
-transformed into ordinary procedure calls at resolution time; their actual
-argument list is updated to include at the right position the passed-object
-argument, if applicable, and then a simple procedure call to the binding's
-target procedure is built. To handle dynamic dispatch in the future, this will
-be extended to allow special code generation during the trans-phase to dispatch
-based on the object's dynamic type.
-
-
-@subsection Generic Bindings
-@c -------------------------
-
-Bindings declared as @code{GENERIC} store the specific bindings they target as
-a linked list using nodes of type @code{gfc_tbp_generic} in @code{u.generic}.
-For each specific target, the parser records its symtree and during resolution
-this symtree is bound to the corresponding @code{gfc_typebound_proc} structure
-of the specific target.
-
-Calls to generic bindings are handled entirely in the resolution-phase, where
-for the actual argument list present the matching specific binding is found
-and the call's target procedure (@code{value.compcall.tbp}) is re-pointed to
-the found specific binding and this call is subsequently handled by the logic
-for specific binding calls.
-
-
-@subsection Calls to Type-bound Procedures
-@c ---------------------------------------
-
-Calls to type-bound procedures are stored in the parse-tree as @code{gfc_expr}
-nodes of type @code{EXPR_COMPCALL}. Their @code{value.compcall.actual} saves
-the actual argument list of the call and @code{value.compcall.tbp} points to the
-@code{gfc_typebound_proc} structure of the binding to be called. The object
-in whose context the procedure was called is saved by combination of
-@code{symtree} and @code{ref}, as if the expression was of type
-@code{EXPR_VARIABLE}.
-
-For code like this:
-@smallexample
-CALL myobj%procedure (arg1, arg2)
-@end smallexample
-@noindent
-the @code{CALL} is represented in the parse-tree as a @code{gfc_code} node of
-type @code{EXEC_COMPCALL}. The @code{expr} member of this node holds an
-expression of type @code{EXPR_COMPCALL} of the same structure as mentioned above
-except that its target procedure is of course a @code{SUBROUTINE} and not a
-@code{FUNCTION}.
-
-Expressions that are generated internally (as expansion of a type-bound
-operator call) may also use additional flags and members.
-@code{value.compcall.ignore_pass} signals that even though a @code{PASS}
-attribute may be present the actual argument list should not be updated because
-it already contains the passed-object.
-@code{value.compcall.base_object} overrides, if it is set, the base-object
-(that is normally stored in @code{symtree} and @code{ref} as mentioned above);
-this is needed because type-bound operators can be called on a base-object that
-need not be of type @code{EXPR_VARIABLE} and thus representable in this way.
-Finally, if @code{value.compcall.assign} is set, the call was produced in
-expansion of a type-bound assignment; this means that proper dependency-checking
-needs to be done when relevant.
-
-
-@c Type-bound operators
-@c --------------------
-
-@node Type-bound Operators
-@section Type-bound Operators
-
-Type-bound operators are in fact basically just @code{GENERIC} procedure
-bindings and are represented much in the same way as those (see
-@ref{Type-bound Procedures}).
-
-They come in two flavours:
-User-defined operators (like @code{.MYOPERATOR.})
-are stored in the @code{f2k_derived} namespace's @code{tb_uop_root}
-symtree exactly like ordinary type-bound procedures are stored in
-@code{tb_sym_root}; their symtrees' names are the operator-names (e.g.
-@samp{myoperator} in the example).
-Intrinsic operators on the other hand are stored in the namespace's
-array member @code{tb_op} indexed by the intrinsic operator's enum
-value. Those need not be packed into @code{gfc_symtree} structures and are
-only @code{gfc_typebound_proc} instances.
-
-When an operator call or assignment is found that cannot be handled in
-another way (i.e. neither matches an intrinsic nor interface operator
-definition) but that contains a derived-type expression, all type-bound
-operators defined on that derived-type are checked for a match with
-the operator call. If there's indeed a relevant definition, the
-operator call is replaced with an internally generated @code{GENERIC}
-type-bound procedure call to the respective definition and that call is
-further processed.
-
-@c ---------------------------------------------------------------------
-@c - Translating to GENERIC
-@c ---------------------------------------------------------------------
-
-@node Translating to GENERIC
-@chapter Generating the intermediate language for later stages.
-
-This chapter deals with the transformation of gfortran's frontend data
-structures to the intermediate language used by the later stages of
-the compiler, the so-called middle end.
-
-Data structures relating to this are found in the source files
-@file{trans*.h} and @file{trans-*.c}.
-
-@menu
-* Basic Data Structures:: Basic data structures.
-* Converting Expressions:: Converting expressions to tree.
-* Translating Statements:: Translating statements.
-* Accessing Declarations:: Accessing declarations.
-@end menu
-
-@node Basic Data Structures
-@section Basic data structures
-
-Gfortran creates GENERIC as an intermediate language for the
-middle-end. Details about GENERIC can be found in the GCC manual.
-
-The basic data structure of GENERIC is a @code{tree}. Everything in
-GENERIC is a @code{tree}, including types and statements. Fortunately
-for the gfortran programmer, @code{tree} variables are
-garbage-collected, so doing memory management for them is not
-necessary.
-
-@code{tree} expressions are built using functions such as, for
-example, @code{fold_build2_loc}. For two tree variables @code{a} and
-@code{b}, both of which have the type @code{gfc_arry_index_type},
-calculation @code{c = a * b} would be done by
-
-@smallexample
-c = fold_build2_loc (input_location, MULT_EXPR,
- gfc_array_index_type, a, b);
-@end smallexample
-
-The types have to agree, otherwise internal compiler errors will occur
-at a later stage. Expressions can be converted to a different type
-using @code{fold_convert}.
-
-Accessing individual members in the @code{tree} structures should not
-be done. Rather, access should be done via macros.
-
-One basic data structure is the @code{stmtblock_t} struct. This is
-used for holding a list of statements, expressed as @code{tree}
-expressions. If a block is created using @code{gfc_start_block}, it
-has its own scope for variables; if it is created using
-@code{gfc_init_block}, it does not have its own scope.
-
-It is possible to
-@itemize @bullet
-@item Add an expression to the end of a block using
- @code{gfc_add_expr_to_block}
-@item Add an expression to the beginning of a block using
- @code{void gfc_prepend_expr_to_block}
-@item Make a block into a single @code{tree} using
- @code{gfc_finish_block}. For example, this is needed to put the
- contents of a block into the @code{if} or @code{else} branch of
- a @code{COND_EXPR}.
-@end itemize
-
-Variables are also @code{tree} expressions, they can be created using
-@code{gfc_create_var}. Assigning to a variable can be done with
-@code{gfc_add_modify}.
-
-An example: Creating a default integer type variable in the current
-scope with the prefix ``everything'' in the @code{stmt_block}
-@code{block} and assigning the value 42 would be
-
-@smallexample
-tree var, *block;
-/* Initialize block somewhere here. */
-var = gfc_create_var (integer_type_node, "everything");
-gfc_add_modify (block, var, build_int_cst (integer_type_node, 42));
-@end smallexample
-
-@node Converting Expressions
-@section Converting Expressions to tree
-
-Converting expressions to @code{tree} is done by functions called
-@code{gfc_conv_*}.
-
-The central data structure for a GENERIC expression is the
-@code{gfc_se} structure. Its @code{expr} member is a @code{tree} that
-holds the value of the expression. A @code{gfc_se} structure is
-initialized using @code{gfc_init_se}; it needs to be embedded in an
-outer @code{gfc_se}.
-
-Evaluating Fortran expressions often require things to be done before
-and after evaluation of the expression, for example code for the
-allocation of a temporary variable and its subsequent deallocation.
-Therefore, @code{gfc_se} contains the members @code{pre} and
-@code{post}, which point to @code{stmt_block} blocks for code that
-needs to be executed before and after evaluation of the expression.
-
-When using a local @code{gfc_se} to convert some expression, it is
-often necessary to add the generated @code{pre} and @code{post} blocks
-to the @code{pre} or @code{post} blocks of the outer @code{gfc_se}.
-Code like this (lifted from @file{trans-expr.cc}) is fairly common:
-
-@smallexample
-gfc_se cont_se;
-tree cont_var;
-
-/* cont_var = is_contiguous (expr); . */
-gfc_init_se (&cont_se, parmse);
-gfc_conv_is_contiguous_expr (&cont_se, expr);
-gfc_add_block_to_block (&se->pre, &(&cont_se)->pre);
-gfc_add_modify (&se->pre, cont_var, cont_se.expr);
-gfc_add_block_to_block (&se->pre, &(&cont_se)->post);
-@end smallexample
-
-Conversion functions which need a @code{gfc_se} structure will have a
-corresponding argument.
-
-@code{gfc_se} also contains pointers to a @code{gfc_ss} and a
-@code{gfc_loopinfo} structure. These are needed by the scalarizer.
-
-@node Translating Statements
-@section Translating statements
-Translating statements to @code{tree} is done by functions called
-@code{gfc_trans_*}. These functions usually get passed a
-@code{gfc_code} structure, evaluate any expressions and then
-return a @code{tree} structure.
-
-@node Accessing Declarations
-@section Accessing declarations
-
-@code{gfc_symbol}, @code{gfc_charlen} and other front-end structures
-contain a @code{backend_decl} variable, which contains the @code{tree}
-used for accessing that entity in the middle-end.
-
-Accessing declarations is usually done by functions called
-@code{gfc_get*}.
-
-@c ---------------------------------------------------------------------
-@c LibGFortran
-@c ---------------------------------------------------------------------
-
-@node LibGFortran
-@chapter The LibGFortran Runtime Library
-
-@menu
-* Symbol Versioning:: Symbol Versioning.
-@end menu
-
-
-@c ---------------------------------------------------------------------
-@c Symbol Versioning
-@c ---------------------------------------------------------------------
-
-@node Symbol Versioning
-@section Symbol Versioning
-@comment Based on https://gcc.gnu.org/wiki/SymbolVersioning,
-@comment as of 2006-11-05, written by Janne Blomqvist.
-
-In general, this capability exists only on a few platforms, thus there
-is a need for configure magic so that it is used only on those targets
-where it is supported.
-
-The central concept in symbol versioning is the so-called map file,
-which specifies the version node(s) exported symbols are labeled with.
-Also, the map file is used to hide local symbols.
-
-Some relevant references:
-@itemize @bullet
-@item
-@uref{https://sourceware.org/binutils/docs/ld/VERSION.html,
-GNU @command{ld} manual}
-
-@item
-@uref{https://www.akkadia.org/drepper/symbol-versioning, ELF Symbol
-Versioning - Ulrich Depper}
-
-@item
-@uref{https://www.akkadia.org/drepper/dsohowto.pdf, How to Write Shared
-Libraries - Ulrich Drepper (see Chapter 3)}
-
-@end itemize
-
-If one adds a new symbol to a library that should be exported, the new
-symbol should be mentioned in the map file and a new version node
-defined, e.g., if one adds a new symbols @code{foo} and @code{bar} to
-libgfortran for the next GCC release, the following should be added to
-the map file:
-@smallexample
-GFORTRAN_1.1 @{
- global:
- foo;
- bar;
-@} GFORTRAN_1.0;
-@end smallexample
-@noindent
-where @code{GFORTRAN_1.0} is the version node of the current release,
-and @code{GFORTRAN_1.1} is the version node of the next release where
-foo and bar are made available.
-
-If one wants to change an existing interface, it is possible by using
-some asm trickery (from the @command{ld} manual referenced above):
-
-@smallexample
-__asm__(".symver original_foo,foo@@");
-__asm__(".symver old_foo,foo@@VERS_1.1");
-__asm__(".symver old_foo1,foo@@VERS_1.2");
-__asm__(".symver new_foo,foo@@VERS_2.0");
-@end smallexample
-
-In this example, @code{foo@@} represents the symbol @code{foo} bound to
-the unspecified base version of the symbol. The source file that
-contains this example would define 4 C functions: @code{original_foo},
-@code{old_foo}, @code{old_foo1}, and @code{new_foo}.
-
-In this case the map file must contain @code{foo} in @code{VERS_1.1}
-and @code{VERS_1.2} as well as in @code{VERS_2.0}.
-
-
-@c ---------------------------------------------------------------------
-@c GNU Free Documentation License
-@c ---------------------------------------------------------------------
-
-@include fdl.texi
-
-
-@c ---------------------------------------------------------------------
-@c Index
-@c ---------------------------------------------------------------------
-
-@node Index
-@unnumbered Index
-
-@printindex cp
-
-@bye
+++ /dev/null
-\input texinfo @c -*-texinfo-*-
-@c %**start of header
-@setfilename gfortran.info
-@set copyrights-gfortran 1999-2022
-
-@include gcc-common.texi
-
-@settitle The GNU Fortran Compiler
-
-@c Create a separate index for command line options
-@defcodeindex op
-@c Merge the standard indexes into a single one.
-@syncodeindex fn cp
-@syncodeindex vr cp
-@syncodeindex ky cp
-@syncodeindex pg cp
-@syncodeindex tp cp
-
-@c TODO: The following "Part" definitions are included here temporarily
-@c until they are incorporated into the official Texinfo distribution.
-@c They borrow heavily from Texinfo's \unnchapentry definitions.
-
-@tex
-\gdef\part#1#2{%
- \pchapsepmacro
- \gdef\thischapter{}
- \begingroup
- \vglue\titlepagetopglue
- \titlefonts \rm
- \leftline{Part #1:@* #2}
- \vskip4pt \hrule height 4pt width \hsize \vskip4pt
- \endgroup
- \writetocentry{part}{#2}{#1}
-}
-\gdef\blankpart{%
- \writetocentry{blankpart}{}{}
-}
-% Part TOC-entry definition for summary contents.
-\gdef\dosmallpartentry#1#2#3#4{%
- \vskip .5\baselineskip plus.2\baselineskip
- \begingroup
- \let\rm=\bf \rm
- \tocentry{Part #2: #1}{\doshortpageno\bgroup#4\egroup}
- \endgroup
-}
-\gdef\dosmallblankpartentry#1#2#3#4{%
- \vskip .5\baselineskip plus.2\baselineskip
-}
-% Part TOC-entry definition for regular contents. This has to be
-% equated to an existing entry to not cause problems when the PDF
-% outline is created.
-\gdef\dopartentry#1#2#3#4{%
- \unnchapentry{Part #2: #1}{}{#3}{#4}
-}
-\gdef\doblankpartentry#1#2#3#4{}
-@end tex
-
-@c %**end of header
-
-@c Use with @@smallbook.
-
-@c %** start of document
-
-@c Cause even numbered pages to be printed on the left hand side of
-@c the page and odd numbered pages to be printed on the right hand
-@c side of the page. Using this, you can print on both sides of a
-@c sheet of paper and have the text on the same part of the sheet.
-
-@c The text on right hand pages is pushed towards the right hand
-@c margin and the text on left hand pages is pushed toward the left
-@c hand margin.
-@c (To provide the reverse effect, set bindingoffset to -0.75in.)
-
-@c @tex
-@c \global\bindingoffset=0.75in
-@c \global\normaloffset =0.75in
-@c @end tex
-
-@copying
-Copyright @copyright{} @value{copyrights-gfortran} Free Software Foundation, Inc.
-
-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 the
-Invariant Sections being ``Funding Free Software'', the Front-Cover
-Texts being (a) (see below), and with the Back-Cover Texts being (b)
-(see below). A copy of the license is included in the section entitled
-``GNU Free Documentation License''.
-
-(a) The FSF's Front-Cover Text is:
-
- A GNU Manual
-
-(b) The FSF's Back-Cover Text is:
-
- You have freedom to copy and modify this GNU Manual, like GNU
- software. Copies published by the Free Software Foundation raise
- funds for GNU development.
-@end copying
-
-@ifinfo
-@dircategory Software development
-@direntry
-* gfortran: (gfortran). The GNU Fortran Compiler.
-@end direntry
-This file documents the use and the internals of
-the GNU Fortran compiler, (@command{gfortran}).
-
-Published by the Free Software Foundation
-51 Franklin Street, Fifth Floor
-Boston, MA 02110-1301 USA
-
-@insertcopying
-@end ifinfo
-
-
-@setchapternewpage odd
-@titlepage
-@title Using GNU Fortran
-@versionsubtitle
-@author The @t{gfortran} team
-@page
-@vskip 0pt plus 1filll
-Published by the Free Software Foundation@*
-51 Franklin Street, Fifth Floor@*
-Boston, MA 02110-1301, USA@*
-@c Last printed ??ber, 19??.@*
-@c Printed copies are available for $? each.@*
-@c ISBN ???
-@sp 1
-@insertcopying
-@end titlepage
-
-@c TODO: The following "Part" definitions are included here temporarily
-@c until they are incorporated into the official Texinfo distribution.
-
-@tex
-\global\let\partentry=\dosmallpartentry
-\global\let\blankpartentry=\dosmallblankpartentry
-@end tex
-@summarycontents
-
-@tex
-\global\let\partentry=\dopartentry
-\global\let\blankpartentry=\doblankpartentry
-@end tex
-@contents
-
-@page
-
-@c ---------------------------------------------------------------------
-@c TexInfo table of contents.
-@c ---------------------------------------------------------------------
-
-@ifnottex
-@node Top
-@top Introduction
-@cindex Introduction
-
-This manual documents the use of @command{gfortran},
-the GNU Fortran compiler. You can find in this manual how to invoke
-@command{gfortran}, as well as its features and incompatibilities.
-
-@ifset DEVELOPMENT
-@emph{Warning:} This document, and the compiler it describes, are still
-under development. While efforts are made to keep it up-to-date, it might
-not accurately reflect the status of the most recent GNU Fortran compiler.
-@end ifset
-
-@comment
-@comment When you add a new menu item, please keep the right hand
-@comment aligned to the same column. Do not use tabs. This provides
-@comment better formatting.
-@comment
-@menu
-* Introduction::
-
-Part I: Invoking GNU Fortran
-* Invoking GNU Fortran:: Command options supported by @command{gfortran}.
-* Runtime:: Influencing runtime behavior with environment variables.
-
-Part II: Language Reference
-* Compiler Characteristics:: User-visible implementation details.
-* Extensions:: Language extensions implemented by GNU Fortran.
-* Mixed-Language Programming:: Interoperability with C
-* Coarray Programming::
-* Intrinsic Procedures:: Intrinsic procedures supported by GNU Fortran.
-* Intrinsic Modules:: Intrinsic modules supported by GNU Fortran.
-
-* Contributing:: How you can help.
-* Copying:: GNU General Public License says
- how you can copy and share GNU Fortran.
-* GNU Free Documentation License::
- How you can copy and share this manual.
-* Funding:: How to help assure continued work for free software.
-* Option Index:: Index of command line options
-* Keyword Index:: Index of concepts
-@end menu
-@end ifnottex
-
-@c ---------------------------------------------------------------------
-@c Introduction
-@c ---------------------------------------------------------------------
-
-@node Introduction
-@chapter Introduction
-
-@c The following duplicates the text on the TexInfo table of contents.
-@iftex
-This manual documents the use of @command{gfortran}, the GNU Fortran
-compiler. You can find in this manual how to invoke @command{gfortran},
-as well as its features and incompatibilities.
-
-@ifset DEVELOPMENT
-@emph{Warning:} This document, and the compiler it describes, are still
-under development. While efforts are made to keep it up-to-date, it
-might not accurately reflect the status of the most recent GNU Fortran
-compiler.
-@end ifset
-@end iftex
-
-@menu
-* About GNU Fortran:: What you should know about the GNU Fortran compiler.
-* GNU Fortran and GCC:: You can compile Fortran, C, or other programs.
-* Standards:: Standards supported by GNU Fortran.
-@end menu
-
-
-@c ---------------------------------------------------------------------
-@c About GNU Fortran
-@c ---------------------------------------------------------------------
-
-@node About GNU Fortran
-@section About GNU Fortran
-
-The GNU Fortran compiler is the successor to @command{g77}, the
-Fortran 77 front end included in GCC prior to version 4 (released in
-2005). While it is backward-compatible with most @command{g77}
-extensions and command-line options, @command{gfortran} is a completely new
-implemention designed to support more modern dialects of Fortran.
-GNU Fortran implements the Fortran 77, 90 and 95 standards
-completely, most of the Fortran 2003 and 2008 standards, and some
-features from the 2018 standard. It also implements several extensions
-including OpenMP and OpenACC support for parallel programming.
-
-The GNU Fortran compiler passes the
-@uref{http://www.fortran-2000.com/ArnaudRecipes/fcvs21_f95.html,
-NIST Fortran 77 Test Suite}, and produces acceptable results on the
-@uref{https://www.netlib.org/lapack/faq.html, LAPACK Test Suite}.
-It also provides respectable performance on
-the @uref{https://polyhedron.com/?page_id=175,
-Polyhedron Fortran compiler benchmarks} and the
-@uref{https://www.netlib.org/benchmark/livermore,
-Livermore Fortran Kernels test}. It has been used to compile a number of
-large real-world programs, including
-@uref{http://hirlam.org/, the HARMONIE and HIRLAM weather forecasting code} and
-@uref{https://github.com/dylan-jayatilaka/tonto,
-the Tonto quantum chemistry package}; see
-@url{https://gcc.gnu.org/@/wiki/@/GfortranApps} for an extended list.
-
-GNU Fortran provides the following functionality:
-
-@itemize @bullet
-@item
-Read a program, stored in a file and containing @dfn{source code}
-instructions written in Fortran 77.
-
-@item
-Translate the program into instructions a computer
-can carry out more quickly than it takes to translate the
-original Fortran instructions.
-The result after compilation of a program is
-@dfn{machine code},
-which is efficiently translated and processed
-by a machine such as your computer.
-Humans usually are not as good writing machine code
-as they are at writing Fortran (or C++, Ada, or Java),
-because it is easy to make tiny mistakes writing machine code.
-
-@item
-Provide information about the reasons why
-the compiler may be unable to create a binary from the source code,
-for example if the source code is flawed.
-The Fortran language standards require that the compiler can point out
-mistakes in your code.
-An incorrect usage of the language causes an @dfn{error message}.
-
-The compiler also attempts to diagnose cases where your
-program contains a correct usage of the language,
-but instructs the computer to do something questionable.
-This kind of diagnostic message is called a @dfn{warning message}.
-
-@item
-Provide optional information about the translation passes
-from the source code to machine code.
-This can help you to find the cause of
-certain bugs which may not be obvious in the source code,
-but may be more easily found at a lower level compiler output.
-It also helps developers to find bugs in the compiler itself.
-
-@item
-Provide information in the generated machine code that can
-make it easier to find bugs in the program (using a debugging tool,
-called a @dfn{debugger}, such as the GNU Debugger @command{gdb}).
-
-@item
-Locate and gather machine code already generated to
-perform actions requested by statements in the program.
-This machine code is organized into @dfn{modules} and is located
-and @dfn{linked} to the user program.
-@end itemize
-
-The GNU Fortran compiler consists of several components:
-
-@itemize @bullet
-@item
-A version of the @command{gcc} command
-(which also might be installed as the system's @command{cc} command)
-that also understands and accepts Fortran source code.
-The @command{gcc} command is the @dfn{driver} program for
-all the languages in the GNU Compiler Collection (GCC);
-With @command{gcc},
-you can compile the source code of any language for
-which a front end is available in GCC.
-
-@item
-The @command{gfortran} command itself,
-which also might be installed as the
-system's @command{f95} command.
-@command{gfortran} is just another driver program,
-but specifically for the Fortran compiler only.
-The primary difference between the @command{gcc} and @command{gfortran}
-commands is that the latter automatically links the correct libraries
-to your program.
-
-@item
-A collection of run-time libraries.
-These libraries contain the machine code needed to support
-capabilities of the Fortran language that are not directly
-provided by the machine code generated by the
-@command{gfortran} compilation phase,
-such as intrinsic functions and subroutines,
-and routines for interaction with files and the operating system.
-@c and mechanisms to spawn,
-@c unleash and pause threads in parallelized code.
-
-@item
-The Fortran compiler itself, (@command{f951}).
-This is the GNU Fortran parser and code generator,
-linked to and interfaced with the GCC backend library.
-@command{f951} ``translates'' the source code to
-assembler code. You would typically not use this
-program directly;
-instead, the @command{gcc} or @command{gfortran} driver
-programs call it for you.
-@end itemize
-
-
-@c ---------------------------------------------------------------------
-@c GNU Fortran and GCC
-@c ---------------------------------------------------------------------
-
-@node GNU Fortran and GCC
-@section GNU Fortran and GCC
-@cindex GNU Compiler Collection
-@cindex GCC
-
-GNU Fortran is a part of GCC, the @dfn{GNU Compiler Collection}. GCC
-consists of a collection of front ends for various languages, which
-translate the source code into a language-independent form called
-@dfn{GENERIC}. This is then processed by a common middle end which
-provides optimization, and then passed to one of a collection of back
-ends which generate code for different computer architectures and
-operating systems.
-
-Functionally, this is implemented with a driver program (@command{gcc})
-which provides the command-line interface for the compiler. It calls
-the relevant compiler front-end program (e.g., @command{f951} for
-Fortran) for each file in the source code, and then calls the assembler
-and linker as appropriate to produce the compiled output. In a copy of
-GCC that has been compiled with Fortran language support enabled,
-@command{gcc} recognizes files with @file{.f}, @file{.for}, @file{.ftn},
-@file{.f90}, @file{.f95}, @file{.f03} and @file{.f08} extensions as
-Fortran source code, and compiles it accordingly. A @command{gfortran}
-driver program is also provided, which is identical to @command{gcc}
-except that it automatically links the Fortran runtime libraries into the
-compiled program.
-
-Source files with @file{.f}, @file{.for}, @file{.fpp}, @file{.ftn}, @file{.F},
-@file{.FOR}, @file{.FPP}, and @file{.FTN} extensions are treated as fixed form.
-Source files with @file{.f90}, @file{.f95}, @file{.f03}, @file{.f08},
-@file{.F90}, @file{.F95}, @file{.F03} and @file{.F08} extensions are
-treated as free form. The capitalized versions of either form are run
-through preprocessing. Source files with the lower case @file{.fpp}
-extension are also run through preprocessing.
-
-This manual specifically documents the Fortran front end, which handles
-the programming language's syntax and semantics. The aspects of GCC
-that relate to the optimization passes and the back-end code generation
-are documented in the GCC manual; see
-@ref{Top,,Introduction,gcc,Using the GNU Compiler Collection (GCC)}.
-The two manuals together provide a complete reference for the GNU
-Fortran compiler.
-
-@c ---------------------------------------------------------------------
-@c Standards
-@c ---------------------------------------------------------------------
-
-@node Standards
-@section Standards
-@cindex Standards
-
-@menu
-* Fortran 95 status::
-* Fortran 2003 status::
-* Fortran 2008 status::
-* Fortran 2018 status::
-@end menu
-
-Fortran is developed by the Working Group 5 of Sub-Committee 22 of the
-Joint Technical Committee 1 of the International Organization for
-Standardization and the International Electrotechnical Commission (IEC).
-This group is known as @uref{http://www.nag.co.uk/sc22wg5/, WG5}.
-Official Fortran standard documents are available for purchase
-from ISO; a collection of free documents (typically final drafts) are
-also available on the @uref{https://gcc.gnu.org/wiki/GFortranStandards, wiki}.
-
-The GNU Fortran compiler implements ISO/IEC 1539:1997 (Fortran 95).
-As such, it can also compile essentially all standard-compliant
-Fortran 90 and Fortran 77 programs. It also supports the ISO/IEC
-TR-15581 enhancements to allocatable arrays.
-
-GNU Fortran also supports almost all of ISO/IEC 1539-1:2004
-(Fortran 2003) and ISO/IEC 1539-1:2010 (Fortran 2008).
-It has partial support for features introduced in ISO/IEC
-1539:2018 (Fortran 2018), the most recent version of the Fortran
-language standard, including full support for the Technical Specification
-@code{Further Interoperability of Fortran with C} (ISO/IEC TS 29113:2012).
-More details on support for these standards can be
-found in the following sections of the documentation.
-
-Additionally, the GNU Fortran compilers supports the OpenMP specification
-(version 4.5 and partial support of the features of the 5.0 version,
-@url{https://openmp.org/@/specifications/}).
-There also is support for the OpenACC specification (targeting
-version 2.6, @uref{https://www.openacc.org/}). See
-@uref{https://gcc.gnu.org/wiki/OpenACC} for more information.
-
-@node Fortran 95 status
-@subsection Fortran 95 status
-@cindex Varying length strings
-@cindex strings, varying length
-@cindex conditional compilation
-
-The Fortran 95 standard specifies in Part 2 (ISO/IEC 1539-2:2000)
-varying length character strings. While GNU Fortran currently does not
-support such strings directly, there exist two Fortran implementations
-for them, which work with GNU Fortran. One can be found at
-@uref{http://user.astro.wisc.edu/~townsend/static.php?ref=iso-varying-string}.
-
-Deferred-length character strings of Fortran 2003 supports part of
-the features of @code{ISO_VARYING_STRING} and should be considered as
-replacement. (Namely, allocatable or pointers of the type
-@code{character(len=:)}.)
-
-Part 3 of the Fortran 95 standard (ISO/IEC 1539-3:1998) defines
-Conditional Compilation, which is not widely used and not directly
-supported by the GNU Fortran compiler. You can use the program coco
-to preprocess such files (@uref{http://www.daniellnagle.com/coco.html}).
-
-@node Fortran 2003 status
-@subsection Fortran 2003 status
-
-GNU Fortran implements the Fortran 2003 (ISO/IEC 1539-1:2004) standard
-except for finalization support, which is incomplete.
-See the
-@uref{https://gcc.gnu.org/wiki/Fortran2003, wiki page} for a full list
-of new features introduced by Fortran 2003 and their implementation status.
-
-@node Fortran 2008 status
-@subsection Fortran 2008 status
-
-The GNU Fortran compiler supports almost all features of Fortran 2008;
-the @uref{https://gcc.gnu.org/wiki/Fortran2008Status, wiki}
-has some information about the current implementation status.
-In particular, the following are not yet supported:
-
-@itemize @bullet
-@item
-@code{DO CONCURRENT} and @code{FORALL} do not recognize a
-type-spec in the loop header.
-
-@item
-The change to permit any constant expression in subscripts and
-nested implied-do limits in a @code{DATA} statement has not been implemented.
-@end itemize
-
-
-@node Fortran 2018 status
-@subsection Fortran 2018 status
-
-Fortran 2018 (ISO/IEC 1539:2018) is the most recent version
-of the Fortran language standard. GNU Fortran implements some of the
-new features of this standard:
-
-@itemize @bullet
-@item
-All Fortran 2018 features derived from ISO/IEC TS 29113:2012,
-``Further Interoperability of Fortran with C'', are supported by GNU Fortran.
-This includes assumed-type and assumed-rank objects and
-the @code{SELECT RANK} construct as well as the parts relating to
-@code{BIND(C)} functions.
-See also @ref{Further Interoperability of Fortran with C}.
-
-@item
-GNU Fortran supports a subset of features derived from ISO/IEC TS 18508:2015,
-``Additional Parallel Features in Fortran'':
-
-@itemize @bullet
-@item
-The new atomic ADD, CAS, FETCH and ADD/OR/XOR, OR and XOR intrinsics.
-
-@item
-The @code{CO_MIN} and @code{CO_MAX} and @code{SUM} reduction intrinsics,
-and the @code{CO_BROADCAST} and @code{CO_REDUCE} intrinsic, except that those
-do not support polymorphic types or types with allocatable, pointer or
-polymorphic components.
-
-@item
-Events (@code{EVENT POST}, @code{EVENT WAIT}, @code{EVENT_QUERY}).
-
-@item
-Failed images (@code{FAIL IMAGE}, @code{IMAGE_STATUS},
-@code{FAILED_IMAGES}, @code{STOPPED_IMAGES}).
-
-@end itemize
-
-@item
-An @code{ERROR STOP} statement is permitted in a @code{PURE}
-procedure.
-
-@item
-GNU Fortran supports the @code{IMPLICIT NONE} statement with an
-@code{implicit-none-spec-list}.
-
-@item
-The behavior of the @code{INQUIRE} statement with the @code{RECL=}
-specifier now conforms to Fortran 2018.
-
-@end itemize
-
-
-@c =====================================================================
-@c PART I: INVOCATION REFERENCE
-@c =====================================================================
-
-@tex
-\part{I}{Invoking GNU Fortran}
-@end tex
-
-@c ---------------------------------------------------------------------
-@c Compiler Options
-@c ---------------------------------------------------------------------
-
-@include invoke.texi
-
-
-@c ---------------------------------------------------------------------
-@c Runtime
-@c ---------------------------------------------------------------------
-
-@node Runtime
-@chapter Runtime: Influencing runtime behavior with environment variables
-@cindex environment variable
-
-The behavior of the @command{gfortran} can be influenced by
-environment variables.
-
-Malformed environment variables are silently ignored.
-
-@menu
-* TMPDIR:: Directory for scratch files
-* GFORTRAN_STDIN_UNIT:: Unit number for standard input
-* GFORTRAN_STDOUT_UNIT:: Unit number for standard output
-* GFORTRAN_STDERR_UNIT:: Unit number for standard error
-* GFORTRAN_UNBUFFERED_ALL:: Do not buffer I/O for all units
-* GFORTRAN_UNBUFFERED_PRECONNECTED:: Do not buffer I/O for preconnected units.
-* GFORTRAN_SHOW_LOCUS:: Show location for runtime errors
-* GFORTRAN_OPTIONAL_PLUS:: Print leading + where permitted
-* GFORTRAN_LIST_SEPARATOR:: Separator for list output
-* GFORTRAN_CONVERT_UNIT:: Set conversion for unformatted I/O
-* GFORTRAN_ERROR_BACKTRACE:: Show backtrace on run-time errors
-* GFORTRAN_FORMATTED_BUFFER_SIZE:: Buffer size for formatted files
-* GFORTRAN_UNFORMATTED_BUFFER_SIZE:: Buffer size for unformatted files
-@end menu
-
-@node TMPDIR
-@section @env{TMPDIR}---Directory for scratch files
-
-When opening a file with @code{STATUS='SCRATCH'}, GNU Fortran tries to
-create the file in one of the potential directories by testing each
-directory in the order below.
-
-@enumerate
-@item
-The environment variable @env{TMPDIR}, if it exists.
-
-@item
-On the MinGW target, the directory returned by the @code{GetTempPath}
-function. Alternatively, on the Cygwin target, the @env{TMP} and
-@env{TEMP} environment variables, if they exist, in that order.
-
-@item
-The @code{P_tmpdir} macro if it is defined, otherwise the directory
-@file{/tmp}.
-@end enumerate
-
-@node GFORTRAN_STDIN_UNIT
-@section @env{GFORTRAN_STDIN_UNIT}---Unit number for standard input
-
-This environment variable can be used to select the unit number
-preconnected to standard input. This must be a positive integer.
-The default value is 5.
-
-@node GFORTRAN_STDOUT_UNIT
-@section @env{GFORTRAN_STDOUT_UNIT}---Unit number for standard output
-
-This environment variable can be used to select the unit number
-preconnected to standard output. This must be a positive integer.
-The default value is 6.
-
-@node GFORTRAN_STDERR_UNIT
-@section @env{GFORTRAN_STDERR_UNIT}---Unit number for standard error
-
-This environment variable can be used to select the unit number
-preconnected to standard error. This must be a positive integer.
-The default value is 0.
-
-@node GFORTRAN_UNBUFFERED_ALL
-@section @env{GFORTRAN_UNBUFFERED_ALL}---Do not buffer I/O on all units
-
-This environment variable controls whether all I/O is unbuffered. If
-the first letter is @samp{y}, @samp{Y} or @samp{1}, all I/O is
-unbuffered. This will slow down small sequential reads and writes. If
-the first letter is @samp{n}, @samp{N} or @samp{0}, I/O is buffered.
-This is the default.
-
-@node GFORTRAN_UNBUFFERED_PRECONNECTED
-@section @env{GFORTRAN_UNBUFFERED_PRECONNECTED}---Do not buffer I/O on preconnected units
-
-The environment variable named @env{GFORTRAN_UNBUFFERED_PRECONNECTED} controls
-whether I/O on a preconnected unit (i.e.@: STDOUT or STDERR) is unbuffered. If
-the first letter is @samp{y}, @samp{Y} or @samp{1}, I/O is unbuffered. This
-will slow down small sequential reads and writes. If the first letter
-is @samp{n}, @samp{N} or @samp{0}, I/O is buffered. This is the default.
-
-@node GFORTRAN_SHOW_LOCUS
-@section @env{GFORTRAN_SHOW_LOCUS}---Show location for runtime errors
-
-If the first letter is @samp{y}, @samp{Y} or @samp{1}, filename and
-line numbers for runtime errors are printed. If the first letter is
-@samp{n}, @samp{N} or @samp{0}, do not print filename and line numbers
-for runtime errors. The default is to print the location.
-
-@node GFORTRAN_OPTIONAL_PLUS
-@section @env{GFORTRAN_OPTIONAL_PLUS}---Print leading + where permitted
-
-If the first letter is @samp{y}, @samp{Y} or @samp{1},
-a plus sign is printed
-where permitted by the Fortran standard. If the first letter
-is @samp{n}, @samp{N} or @samp{0}, a plus sign is not printed
-in most cases. Default is not to print plus signs.
-
-@node GFORTRAN_LIST_SEPARATOR
-@section @env{GFORTRAN_LIST_SEPARATOR}---Separator for list output
-
-This environment variable specifies the separator when writing
-list-directed output. It may contain any number of spaces and
-at most one comma. If you specify this on the command line,
-be sure to quote spaces, as in
-@smallexample
-$ GFORTRAN_LIST_SEPARATOR=' , ' ./a.out
-@end smallexample
-when @command{a.out} is the compiled Fortran program that you want to run.
-Default is a single space.
-
-@node GFORTRAN_CONVERT_UNIT
-@section @env{GFORTRAN_CONVERT_UNIT}---Set conversion for unformatted I/O
-
-By setting the @env{GFORTRAN_CONVERT_UNIT} variable, it is possible
-to change the representation of data for unformatted files.
-The syntax for the @env{GFORTRAN_CONVERT_UNIT} variable for
-most systems is:
-@smallexample
-GFORTRAN_CONVERT_UNIT: mode | mode ';' exception | exception ;
-mode: 'native' | 'swap' | 'big_endian' | 'little_endian' ;
-exception: mode ':' unit_list | unit_list ;
-unit_list: unit_spec | unit_list unit_spec ;
-unit_spec: INTEGER | INTEGER '-' INTEGER ;
-@end smallexample
-The variable consists of an optional default mode, followed by
-a list of optional exceptions, which are separated by semicolons
-from the preceding default and each other. Each exception consists
-of a format and a comma-separated list of units. Valid values for
-the modes are the same as for the @code{CONVERT} specifier:
-
-@itemize @w{}
-@item @code{NATIVE} Use the native format. This is the default.
-@item @code{SWAP} Swap between little- and big-endian.
-@item @code{LITTLE_ENDIAN} Use the little-endian format
-for unformatted files.
-@item @code{BIG_ENDIAN} Use the big-endian format for unformatted files.
-@end itemize
-For POWER systems which support @option{-mabi=ieeelongdouble},
-there are additional options, which can be combined with the
-others with commas. Those are
-@itemize @w{}
-@item @code{R16_IEEE} Use IEEE 128-bit format for @code{REAL(KIND=16)}.
-@item @code{R16_IBM} Use IBM @code{long double} format for
-@code{REAL(KIND=16)}.
-@end itemize
-A missing mode for an exception is taken to mean @code{BIG_ENDIAN}.
-Examples of values for @env{GFORTRAN_CONVERT_UNIT} are:
-@itemize @w{}
-@item @code{'big_endian'} Do all unformatted I/O in big_endian mode.
-@item @code{'little_endian;native:10-20,25'} Do all unformatted I/O
-in little_endian mode, except for units 10 to 20 and 25, which are in
-native format.
-@item @code{'10-20'} Units 10 to 20 are big-endian, the rest is native.
-@item @code{'big_endian,r16_ibm'} Do all unformatted I/O in big-endian
-mode and use IBM long double for output of @code{REAL(KIND=16)} values.
-@end itemize
-
-Setting the environment variables should be done on the command
-line or via the @command{export}
-command for @command{sh}-compatible shells and via @command{setenv}
-for @command{csh}-compatible shells.
-
-Example for @command{sh}:
-@smallexample
-$ gfortran foo.f90
-$ GFORTRAN_CONVERT_UNIT='big_endian;native:10-20' ./a.out
-@end smallexample
-
-Example code for @command{csh}:
-@smallexample
-% gfortran foo.f90
-% setenv GFORTRAN_CONVERT_UNIT 'big_endian;native:10-20'
-% ./a.out
-@end smallexample
-
-Using anything but the native representation for unformatted data
-carries a significant speed overhead. If speed in this area matters
-to you, it is best if you use this only for data that needs to be
-portable.
-
-@xref{CONVERT specifier}, for an alternative way to specify the
-data representation for unformatted files. @xref{Runtime Options}, for
-setting a default data representation for the whole program. The
-@code{CONVERT} specifier overrides the @option{-fconvert} compile options.
-
-@emph{Note that the values specified via the GFORTRAN_CONVERT_UNIT
-environment variable will override the CONVERT specifier in the
-open statement}. This is to give control over data formats to
-users who do not have the source code of their program available.
-
-@node GFORTRAN_ERROR_BACKTRACE
-@section @env{GFORTRAN_ERROR_BACKTRACE}---Show backtrace on run-time errors
-
-If the @env{GFORTRAN_ERROR_BACKTRACE} variable is set to @samp{y},
-@samp{Y} or @samp{1} (only the first letter is relevant) then a
-backtrace is printed when a serious run-time error occurs. To disable
-the backtracing, set the variable to @samp{n}, @samp{N}, @samp{0}.
-Default is to print a backtrace unless the @option{-fno-backtrace}
-compile option was used.
-
-@node GFORTRAN_FORMATTED_BUFFER_SIZE
-@section @env{GFORTRAN_FORMATTED_BUFFER_SIZE}---Set buffer size for formatted I/O
-
-The @env{GFORTRAN_FORMATTED_BUFFER_SIZE} environment variable
-specifies buffer size in bytes to be used for formatted output.
-The default value is 8192.
-
-@node GFORTRAN_UNFORMATTED_BUFFER_SIZE
-@section @env{GFORTRAN_UNFORMATTED_BUFFER_SIZE}---Set buffer size for unformatted I/O
-
-The @env{GFORTRAN_UNFORMATTED_BUFFER_SIZE} environment variable
-specifies buffer size in bytes to be used for unformatted output.
-The default value is 131072.
-
-@c =====================================================================
-@c PART II: LANGUAGE REFERENCE
-@c =====================================================================
-
-@tex
-\part{II}{Language Reference}
-@end tex
-
-
-
-@c ---------------------------------------------------------------------
-@c Compiler Characteristics
-@c ---------------------------------------------------------------------
-
-@node Compiler Characteristics
-@chapter Compiler Characteristics
-
-This chapter describes certain characteristics of the GNU Fortran
-compiler, that are not specified by the Fortran standard, but which
-might in some way or another become visible to the programmer.
-
-@menu
-* KIND Type Parameters::
-* Internal representation of LOGICAL variables::
-* Evaluation of logical expressions::
-* MAX and MIN intrinsics with REAL NaN arguments::
-* Thread-safety of the runtime library::
-* Data consistency and durability::
-* Files opened without an explicit ACTION= specifier::
-* File operations on symbolic links::
-* File format of unformatted sequential files::
-* Asynchronous I/O::
-@end menu
-
-
-@node KIND Type Parameters
-@section KIND Type Parameters
-@cindex kind
-
-The @code{KIND} type parameters supported by GNU Fortran for the primitive
-data types are:
-
-@table @code
-
-@item INTEGER
-1, 2, 4, 8*, 16*, default: 4**
-
-@item LOGICAL
-1, 2, 4, 8*, 16*, default: 4**
-
-@item REAL
-4, 8, 10*, 16*, default: 4***
-
-@item COMPLEX
-4, 8, 10*, 16*, default: 4***
-
-@item DOUBLE PRECISION
-4, 8, 10*, 16*, default: 8***
-
-@item CHARACTER
-1, 4, default: 1
-
-@end table
-
-@noindent
-* not available on all systems @*
-** unless @option{-fdefault-integer-8} is used @*
-*** unless @option{-fdefault-real-8} is used (see @ref{Fortran Dialect Options})
-
-@noindent
-The @code{KIND} value matches the storage size in bytes, except for
-@code{COMPLEX} where the storage size is twice as much (or both real and
-imaginary part are a real value of the given size). It is recommended to use
-the @ref{SELECTED_CHAR_KIND}, @ref{SELECTED_INT_KIND} and
-@ref{SELECTED_REAL_KIND} intrinsics or the @code{INT8}, @code{INT16},
-@code{INT32}, @code{INT64}, @code{REAL32}, @code{REAL64}, and @code{REAL128}
-parameters of the @code{ISO_FORTRAN_ENV} module instead of the concrete values.
-The available kind parameters can be found in the constant arrays
-@code{CHARACTER_KINDS}, @code{INTEGER_KINDS}, @code{LOGICAL_KINDS} and
-@code{REAL_KINDS} in the @ref{ISO_FORTRAN_ENV} module. For C interoperability,
-the kind parameters of the @ref{ISO_C_BINDING} module should be used.
-
-
-@node Internal representation of LOGICAL variables
-@section Internal representation of LOGICAL variables
-@cindex logical, variable representation
-
-The Fortran standard does not specify how variables of @code{LOGICAL}
-type are represented, beyond requiring that @code{LOGICAL} variables
-of default kind have the same storage size as default @code{INTEGER}
-and @code{REAL} variables. The GNU Fortran internal representation is
-as follows.
-
-A @code{LOGICAL(KIND=N)} variable is represented as an
-@code{INTEGER(KIND=N)} variable, however, with only two permissible
-values: @code{1} for @code{.TRUE.} and @code{0} for
-@code{.FALSE.}. Any other integer value results in undefined behavior.
-
-See also @ref{Argument passing conventions} and @ref{Interoperability with C}.
-
-
-@node Evaluation of logical expressions
-@section Evaluation of logical expressions
-
-The Fortran standard does not require the compiler to evaluate all parts of an
-expression, if they do not contribute to the final result. For logical
-expressions with @code{.AND.} or @code{.OR.} operators, in particular, GNU
-Fortran will optimize out function calls (even to impure functions) if the
-result of the expression can be established without them. However, since not
-all compilers do that, and such an optimization can potentially modify the
-program flow and subsequent results, GNU Fortran throws warnings for such
-situations with the @option{-Wfunction-elimination} flag.
-
-
-@node MAX and MIN intrinsics with REAL NaN arguments
-@section MAX and MIN intrinsics with REAL NaN arguments
-@cindex MAX, MIN, NaN
-
-The Fortran standard does not specify what the result of the
-@code{MAX} and @code{MIN} intrinsics are if one of the arguments is a
-@code{NaN}. Accordingly, the GNU Fortran compiler does not specify
-that either, as this allows for faster and more compact code to be
-generated. If the programmer wishes to take some specific action in
-case one of the arguments is a @code{NaN}, it is necessary to
-explicitly test the arguments before calling @code{MAX} or @code{MIN},
-e.g. with the @code{IEEE_IS_NAN} function from the intrinsic module
-@code{IEEE_ARITHMETIC}.
-
-
-@node Thread-safety of the runtime library
-@section Thread-safety of the runtime library
-@cindex thread-safety, threads
-
-GNU Fortran can be used in programs with multiple threads, e.g.@: by
-using OpenMP, by calling OS thread handling functions via the
-@code{ISO_C_BINDING} facility, or by GNU Fortran compiled library code
-being called from a multi-threaded program.
-
-The GNU Fortran runtime library, (@code{libgfortran}), supports being
-called concurrently from multiple threads with the following
-exceptions.
-
-During library initialization, the C @code{getenv} function is used,
-which need not be thread-safe. Similarly, the @code{getenv}
-function is used to implement the @code{GET_ENVIRONMENT_VARIABLE} and
-@code{GETENV} intrinsics. It is the responsibility of the user to
-ensure that the environment is not being updated concurrently when any
-of these actions are taking place.
-
-The @code{EXECUTE_COMMAND_LINE} and @code{SYSTEM} intrinsics are
-implemented with the @code{system} function, which need not be
-thread-safe. It is the responsibility of the user to ensure that
-@code{system} is not called concurrently.
-
-For platforms not supporting thread-safe POSIX functions, further
-functionality might not be thread-safe. For details, please consult
-the documentation for your operating system.
-
-The GNU Fortran runtime library uses various C library functions that
-depend on the locale, such as @code{strtod} and @code{snprintf}. In
-order to work correctly in locale-aware programs that set the locale
-using @code{setlocale}, the locale is reset to the default ``C''
-locale while executing a formatted @code{READ} or @code{WRITE}
-statement. On targets supporting the POSIX 2008 per-thread locale
-functions (e.g. @code{newlocale}, @code{uselocale},
-@code{freelocale}), these are used and thus the global locale set
-using @code{setlocale} or the per-thread locales in other threads are
-not affected. However, on targets lacking this functionality, the
-global LC_NUMERIC locale is set to ``C'' during the formatted I/O.
-Thus, on such targets it's not safe to call @code{setlocale}
-concurrently from another thread while a Fortran formatted I/O
-operation is in progress. Also, other threads doing something
-dependent on the LC_NUMERIC locale might not work correctly if a
-formatted I/O operation is in progress in another thread.
-
-@node Data consistency and durability
-@section Data consistency and durability
-@cindex consistency, durability
-
-This section contains a brief overview of data and metadata
-consistency and durability issues when doing I/O.
-
-With respect to durability, GNU Fortran makes no effort to ensure that
-data is committed to stable storage. If this is required, the GNU
-Fortran programmer can use the intrinsic @code{FNUM} to retrieve the
-low level file descriptor corresponding to an open Fortran unit. Then,
-using e.g. the @code{ISO_C_BINDING} feature, one can call the
-underlying system call to flush dirty data to stable storage, such as
-@code{fsync} on POSIX, @code{_commit} on MingW, or @code{fcntl(fd,
-F_FULLSYNC, 0)} on Mac OS X. The following example shows how to call
-fsync:
-
-@smallexample
- ! Declare the interface for POSIX fsync function
- interface
- function fsync (fd) bind(c,name="fsync")
- use iso_c_binding, only: c_int
- integer(c_int), value :: fd
- integer(c_int) :: fsync
- end function fsync
- end interface
-
- ! Variable declaration
- integer :: ret
-
- ! Opening unit 10
- open (10,file="foo")
-
- ! ...
- ! Perform I/O on unit 10
- ! ...
-
- ! Flush and sync
- flush(10)
- ret = fsync(fnum(10))
-
- ! Handle possible error
- if (ret /= 0) stop "Error calling FSYNC"
-@end smallexample
-
-With respect to consistency, for regular files GNU Fortran uses
-buffered I/O in order to improve performance. This buffer is flushed
-automatically when full and in some other situations, e.g. when
-closing a unit. It can also be explicitly flushed with the
-@code{FLUSH} statement. Also, the buffering can be turned off with the
-@code{GFORTRAN_UNBUFFERED_ALL} and
-@code{GFORTRAN_UNBUFFERED_PRECONNECTED} environment variables. Special
-files, such as terminals and pipes, are always unbuffered. Sometimes,
-however, further things may need to be done in order to allow other
-processes to see data that GNU Fortran has written, as follows.
-
-The Windows platform supports a relaxed metadata consistency model,
-where file metadata is written to the directory lazily. This means
-that, for instance, the @code{dir} command can show a stale size for a
-file. One can force a directory metadata update by closing the unit,
-or by calling @code{_commit} on the file descriptor. Note, though,
-that @code{_commit} will force all dirty data to stable storage, which
-is often a very slow operation.
-
-The Network File System (NFS) implements a relaxed consistency model
-called open-to-close consistency. Closing a file forces dirty data and
-metadata to be flushed to the server, and opening a file forces the
-client to contact the server in order to revalidate cached
-data. @code{fsync} will also force a flush of dirty data and metadata
-to the server. Similar to @code{open} and @code{close}, acquiring and
-releasing @code{fcntl} file locks, if the server supports them, will
-also force cache validation and flushing dirty data and metadata.
-
-
-@node Files opened without an explicit ACTION= specifier
-@section Files opened without an explicit ACTION= specifier
-@cindex open, action
-
-The Fortran standard says that if an @code{OPEN} statement is executed
-without an explicit @code{ACTION=} specifier, the default value is
-processor dependent. GNU Fortran behaves as follows:
-
-@enumerate
-@item Attempt to open the file with @code{ACTION='READWRITE'}
-@item If that fails, try to open with @code{ACTION='READ'}
-@item If that fails, try to open with @code{ACTION='WRITE'}
-@item If that fails, generate an error
-@end enumerate
-
-
-@node File operations on symbolic links
-@section File operations on symbolic links
-@cindex file, symbolic link
-
-This section documents the behavior of GNU Fortran for file operations on
-symbolic links, on systems that support them.
-
-@itemize
-
-@item Results of INQUIRE statements of the ``inquire by file'' form will
-relate to the target of the symbolic link. For example,
-@code{INQUIRE(FILE="foo",EXIST=ex)} will set @var{ex} to @var{.true.} if
-@var{foo} is a symbolic link pointing to an existing file, and @var{.false.}
-if @var{foo} points to an non-existing file (``dangling'' symbolic link).
-
-@item Using the @code{OPEN} statement with a @code{STATUS="NEW"} specifier
-on a symbolic link will result in an error condition, whether the symbolic
-link points to an existing target or is dangling.
-
-@item If a symbolic link was connected, using the @code{CLOSE} statement
-with a @code{STATUS="DELETE"} specifier will cause the symbolic link itself
-to be deleted, not its target.
-
-@end itemize
-
-@node File format of unformatted sequential files
-@section File format of unformatted sequential files
-@cindex file, unformatted sequential
-@cindex unformatted sequential
-@cindex sequential, unformatted
-@cindex record marker
-@cindex subrecord
-
-Unformatted sequential files are stored as logical records using
-record markers. Each logical record consists of one of more
-subrecords.
-
-Each subrecord consists of a leading record marker, the data written
-by the user program, and a trailing record marker. The record markers
-are four-byte integers by default, and eight-byte integers if the
-@option{-fmax-subrecord-length=8} option (which exists for backwards
-compability only) is in effect.
-
-The representation of the record markers is that of unformatted files
-given with the @option{-fconvert} option, the @ref{CONVERT specifier}
-in an open statement or the @ref{GFORTRAN_CONVERT_UNIT} environment
-variable.
-
-The maximum number of bytes of user data in a subrecord is 2147483639
-(2 GiB - 9) for a four-byte record marker. This limit can be lowered
-with the @option{-fmax-subrecord-length} option, although this is
-rarely useful. If the length of a logical record exceeds this limit,
-the data is distributed among several subrecords.
-
-The absolute of the number stored in the record markers is the number
-of bytes of user data in the corresponding subrecord. If the leading
-record marker of a subrecord contains a negative number, another
-subrecord follows the current one. If the trailing record marker
-contains a negative number, then there is a preceding subrecord.
-
-In the most simple case, with only one subrecord per logical record,
-both record markers contain the number of bytes of user data in the
-record.
-
-The format for unformatted sequential data can be duplicated using
-unformatted stream, as shown in the example program for an unformatted
-record containing a single subrecord:
-
-@smallexample
-program main
- use iso_fortran_env, only: int32
- implicit none
- integer(int32) :: i
- real, dimension(10) :: a, b
- call random_number(a)
- open (10,file='test.dat',form='unformatted',access='stream')
- inquire (iolength=i) a
- write (10) i, a, i
- close (10)
- open (10,file='test.dat',form='unformatted')
- read (10) b
- if (all (a == b)) print *,'success!'
-end program main
-@end smallexample
-
-@node Asynchronous I/O
-@section Asynchronous I/O
-@cindex input/output, asynchronous
-@cindex asynchronous I/O
-
-Asynchronous I/O is supported if the program is linked against the
-POSIX thread library. If that is not the case, all I/O is performed
-as synchronous. On systems which do not support pthread condition
-variables, such as AIX, I/O is also performed as synchronous.
-
-On some systems, such as Darwin or Solaris, the POSIX thread library
-is always linked in, so asynchronous I/O is always performed. On other
-sytems, such as Linux, it is necessary to specify @option{-pthread},
-@option{-lpthread} or @option{-fopenmp} during the linking step.
-
-@c ---------------------------------------------------------------------
-@c Extensions
-@c ---------------------------------------------------------------------
-
-@c Maybe this chapter should be merged with the 'Standards' section,
-@c whenever that is written :-)
-
-@node Extensions
-@chapter Extensions
-@cindex extensions
-
-The two sections below detail the extensions to standard Fortran that are
-implemented in GNU Fortran, as well as some of the popular or
-historically important extensions that are not (or not yet) implemented.
-For the latter case, we explain the alternatives available to GNU Fortran
-users, including replacement by standard-conforming code or GNU
-extensions.
-
-@menu
-* Extensions implemented in GNU Fortran::
-* Extensions not implemented in GNU Fortran::
-@end menu
-
-
-@node Extensions implemented in GNU Fortran
-@section Extensions implemented in GNU Fortran
-@cindex extensions, implemented
-
-GNU Fortran implements a number of extensions over standard Fortran.
-This chapter contains information on their syntax and meaning. There
-are currently two categories of GNU Fortran extensions, those that
-provide functionality beyond that provided by any standard, and those
-that are supported by GNU Fortran purely for backward compatibility
-with legacy compilers. By default, @option{-std=gnu} allows the
-compiler to accept both types of extensions, but to warn about the use
-of the latter. Specifying either @option{-std=f95},
-@option{-std=f2003}, @option{-std=f2008}, or @option{-std=f2018}
-disables both types of extensions, and @option{-std=legacy} allows
-both without warning. The special compile flag @option{-fdec} enables
-additional compatibility extensions along with those enabled by
-@option{-std=legacy}.
-
-@menu
-* Old-style kind specifications::
-* Old-style variable initialization::
-* Extensions to namelist::
-* X format descriptor without count field::
-* Commas in FORMAT specifications::
-* Missing period in FORMAT specifications::
-* Default widths for F@comma{} G and I format descriptors::
-* I/O item lists::
-* @code{Q} exponent-letter::
-* BOZ literal constants::
-* Real array indices::
-* Unary operators::
-* Implicitly convert LOGICAL and INTEGER values::
-* Hollerith constants support::
-* Character conversion::
-* Cray pointers::
-* CONVERT specifier::
-* OpenMP::
-* OpenACC::
-* Argument list functions::
-* Read/Write after EOF marker::
-* STRUCTURE and RECORD::
-* UNION and MAP::
-* Type variants for integer intrinsics::
-* AUTOMATIC and STATIC attributes::
-* Extended math intrinsics::
-* Form feed as whitespace::
-* TYPE as an alias for PRINT::
-* %LOC as an rvalue::
-* .XOR. operator::
-* Bitwise logical operators::
-* Extended I/O specifiers::
-* Legacy PARAMETER statements::
-* Default exponents::
-@end menu
-
-@node Old-style kind specifications
-@subsection Old-style kind specifications
-@cindex kind, old-style
-
-GNU Fortran allows old-style kind specifications in declarations. These
-look like:
-@smallexample
- TYPESPEC*size x,y,z
-@end smallexample
-@noindent
-where @code{TYPESPEC} is a basic type (@code{INTEGER}, @code{REAL},
-etc.), and where @code{size} is a byte count corresponding to the
-storage size of a valid kind for that type. (For @code{COMPLEX}
-variables, @code{size} is the total size of the real and imaginary
-parts.) The statement then declares @code{x}, @code{y} and @code{z} to
-be of type @code{TYPESPEC} with the appropriate kind. This is
-equivalent to the standard-conforming declaration
-@smallexample
- TYPESPEC(k) x,y,z
-@end smallexample
-@noindent
-where @code{k} is the kind parameter suitable for the intended precision. As
-kind parameters are implementation-dependent, use the @code{KIND},
-@code{SELECTED_INT_KIND} and @code{SELECTED_REAL_KIND} intrinsics to retrieve
-the correct value, for instance @code{REAL*8 x} can be replaced by:
-@smallexample
-INTEGER, PARAMETER :: dbl = KIND(1.0d0)
-REAL(KIND=dbl) :: x
-@end smallexample
-
-@node Old-style variable initialization
-@subsection Old-style variable initialization
-
-GNU Fortran allows old-style initialization of variables of the
-form:
-@smallexample
- INTEGER i/1/,j/2/
- REAL x(2,2) /3*0.,1./
-@end smallexample
-The syntax for the initializers is as for the @code{DATA} statement, but
-unlike in a @code{DATA} statement, an initializer only applies to the
-variable immediately preceding the initialization. In other words,
-something like @code{INTEGER I,J/2,3/} is not valid. This style of
-initialization is only allowed in declarations without double colons
-(@code{::}); the double colons were introduced in Fortran 90, which also
-introduced a standard syntax for initializing variables in type
-declarations.
-
-Examples of standard-conforming code equivalent to the above example
-are:
-@smallexample
-! Fortran 90
- INTEGER :: i = 1, j = 2
- REAL :: x(2,2) = RESHAPE((/0.,0.,0.,1./),SHAPE(x))
-! Fortran 77
- INTEGER i, j
- REAL x(2,2)
- DATA i/1/, j/2/, x/3*0.,1./
-@end smallexample
-
-Note that variables which are explicitly initialized in declarations
-or in @code{DATA} statements automatically acquire the @code{SAVE}
-attribute.
-
-@node Extensions to namelist
-@subsection Extensions to namelist
-@cindex Namelist
-
-GNU Fortran fully supports the Fortran 95 standard for namelist I/O
-including array qualifiers, substrings and fully qualified derived types.
-The output from a namelist write is compatible with namelist read. The
-output has all names in upper case and indentation to column 1 after the
-namelist name. Two extensions are permitted:
-
-Old-style use of @samp{$} instead of @samp{&}
-@smallexample
-$MYNML
- X(:)%Y(2) = 1.0 2.0 3.0
- CH(1:4) = "abcd"
-$END
-@end smallexample
-
-It should be noted that the default terminator is @samp{/} rather than
-@samp{&END}.
-
-Querying of the namelist when inputting from stdin. After at least
-one space, entering @samp{?} sends to stdout the namelist name and the names of
-the variables in the namelist:
-@smallexample
- ?
-
-&mynml
- x
- x%y
- ch
-&end
-@end smallexample
-
-Entering @samp{=?} outputs the namelist to stdout, as if
-@code{WRITE(*,NML = mynml)} had been called:
-@smallexample
-=?
-
-&MYNML
- X(1)%Y= 0.000000 , 1.000000 , 0.000000 ,
- X(2)%Y= 0.000000 , 2.000000 , 0.000000 ,
- X(3)%Y= 0.000000 , 3.000000 , 0.000000 ,
- CH=abcd, /
-@end smallexample
-
-To aid this dialog, when input is from stdin, errors send their
-messages to stderr and execution continues, even if @code{IOSTAT} is set.
-
-@code{PRINT} namelist is permitted. This causes an error if
-@option{-std=f95} is used.
-@smallexample
-PROGRAM test_print
- REAL, dimension (4) :: x = (/1.0, 2.0, 3.0, 4.0/)
- NAMELIST /mynml/ x
- PRINT mynml
-END PROGRAM test_print
-@end smallexample
-
-Expanded namelist reads are permitted. This causes an error if
-@option{-std=f95} is used. In the following example, the first element
-of the array will be given the value 0.00 and the two succeeding
-elements will be given the values 1.00 and 2.00.
-@smallexample
-&MYNML
- X(1,1) = 0.00 , 1.00 , 2.00
-/
-@end smallexample
-
-When writing a namelist, if no @code{DELIM=} is specified, by default a
-double quote is used to delimit character strings. If -std=F95, F2003,
-or F2008, etc, the delim status is set to 'none'. Defaulting to
-quotes ensures that namelists with character strings can be subsequently
-read back in accurately.
-
-@node X format descriptor without count field
-@subsection @code{X} format descriptor without count field
-
-To support legacy codes, GNU Fortran permits the count field of the
-@code{X} edit descriptor in @code{FORMAT} statements to be omitted.
-When omitted, the count is implicitly assumed to be one.
-
-@smallexample
- PRINT 10, 2, 3
-10 FORMAT (I1, X, I1)
-@end smallexample
-
-@node Commas in FORMAT specifications
-@subsection Commas in @code{FORMAT} specifications
-
-To support legacy codes, GNU Fortran allows the comma separator
-to be omitted immediately before and after character string edit
-descriptors in @code{FORMAT} statements. A comma with no following format
-decriptor is permited if the @option{-fdec-blank-format-item} is given on
-the command line. This is considered non-conforming code and is
-discouraged.
-
-@smallexample
- PRINT 10, 2, 3
-10 FORMAT ('FOO='I1' BAR='I2)
- print 20, 5, 6
-20 FORMAT (I3, I3,)
-@end smallexample
-
-
-@node Missing period in FORMAT specifications
-@subsection Missing period in @code{FORMAT} specifications
-
-To support legacy codes, GNU Fortran allows missing periods in format
-specifications if and only if @option{-std=legacy} is given on the
-command line. This is considered non-conforming code and is
-discouraged.
-
-@smallexample
- REAL :: value
- READ(*,10) value
-10 FORMAT ('F4')
-@end smallexample
-
-@node Default widths for F@comma{} G and I format descriptors
-@subsection Default widths for @code{F}, @code{G} and @code{I} format descriptors
-
-To support legacy codes, GNU Fortran allows width to be omitted from format
-specifications if and only if @option{-fdec-format-defaults} is given on the
-command line. Default widths will be used. This is considered non-conforming
-code and is discouraged.
-
-@smallexample
- REAL :: value1
- INTEGER :: value2
- WRITE(*,10) value1, value1, value2
-10 FORMAT ('F, G, I')
-@end smallexample
-
-
-@node I/O item lists
-@subsection I/O item lists
-@cindex I/O item lists
-
-To support legacy codes, GNU Fortran allows the input item list
-of the @code{READ} statement, and the output item lists of the
-@code{WRITE} and @code{PRINT} statements, to start with a comma.
-
-@node @code{Q} exponent-letter
-@subsection @code{Q} exponent-letter
-@cindex @code{Q} exponent-letter
-
-GNU Fortran accepts real literal constants with an exponent-letter
-of @code{Q}, for example, @code{1.23Q45}. The constant is interpreted
-as a @code{REAL(16)} entity on targets that support this type. If
-the target does not support @code{REAL(16)} but has a @code{REAL(10)}
-type, then the real-literal-constant will be interpreted as a
-@code{REAL(10)} entity. In the absence of @code{REAL(16)} and
-@code{REAL(10)}, an error will occur.
-
-@node BOZ literal constants
-@subsection BOZ literal constants
-@cindex BOZ literal constants
-
-Besides decimal constants, Fortran also supports binary (@code{b}),
-octal (@code{o}) and hexadecimal (@code{z}) integer constants. The
-syntax is: @samp{prefix quote digits quote}, where the prefix is
-either @code{b}, @code{o} or @code{z}, quote is either @code{'} or
-@code{"} and the digits are @code{0} or @code{1} for binary,
-between @code{0} and @code{7} for octal, and between @code{0} and
-@code{F} for hexadecimal. (Example: @code{b'01011101'}.)
-
-Up to Fortran 95, BOZ literal constants were only allowed to initialize
-integer variables in DATA statements. Since Fortran 2003 BOZ literal
-constants are also allowed as actual arguments to the @code{REAL},
-@code{DBLE}, @code{INT} and @code{CMPLX} intrinsic functions.
-The BOZ literal constant is simply a string of bits, which is padded
-or truncated as needed, during conversion to a numeric type. The
-Fortran standard states that the treatment of the sign bit is processor
-dependent. Gfortran interprets the sign bit as a user would expect.
-
-As a deprecated extension, GNU Fortran allows hexadecimal BOZ literal
-constants to be specified using the @code{X} prefix. That the BOZ literal
-constant can also be specified by adding a suffix to the string, for
-example, @code{Z'ABC'} and @code{'ABC'X} are equivalent. Additionally,
-as extension, BOZ literals are permitted in some contexts outside of
-@code{DATA} and the intrinsic functions listed in the Fortran standard.
-Use @option{-fallow-invalid-boz} to enable the extension.
-
-@node Real array indices
-@subsection Real array indices
-@cindex array, indices of type real
-
-As an extension, GNU Fortran allows the use of @code{REAL} expressions
-or variables as array indices.
-
-@node Unary operators
-@subsection Unary operators
-@cindex operators, unary
-
-As an extension, GNU Fortran allows unary plus and unary minus operators
-to appear as the second operand of binary arithmetic operators without
-the need for parenthesis.
-
-@smallexample
- X = Y * -Z
-@end smallexample
-
-@node Implicitly convert LOGICAL and INTEGER values
-@subsection Implicitly convert @code{LOGICAL} and @code{INTEGER} values
-@cindex conversion, to integer
-@cindex conversion, to logical
-
-As an extension for backwards compatibility with other compilers, GNU
-Fortran allows the implicit conversion of @code{LOGICAL} values to
-@code{INTEGER} values and vice versa. When converting from a
-@code{LOGICAL} to an @code{INTEGER}, @code{.FALSE.} is interpreted as
-zero, and @code{.TRUE.} is interpreted as one. When converting from
-@code{INTEGER} to @code{LOGICAL}, the value zero is interpreted as
-@code{.FALSE.} and any nonzero value is interpreted as @code{.TRUE.}.
-
-@smallexample
- LOGICAL :: l
- l = 1
-@end smallexample
-@smallexample
- INTEGER :: i
- i = .TRUE.
-@end smallexample
-
-However, there is no implicit conversion of @code{INTEGER} values in
-@code{if}-statements, nor of @code{LOGICAL} or @code{INTEGER} values
-in I/O operations.
-
-@node Hollerith constants support
-@subsection Hollerith constants support
-@cindex Hollerith constants
-
-GNU Fortran supports Hollerith constants in assignments, @code{DATA}
-statements, function and subroutine arguments. A Hollerith constant is
-written as a string of characters preceded by an integer constant
-indicating the character count, and the letter @code{H} or
-@code{h}, and stored in bytewise fashion in a numeric (@code{INTEGER},
-@code{REAL}, or @code{COMPLEX}), @code{LOGICAL} or @code{CHARACTER} variable.
-The constant will be padded with spaces or truncated to fit the size of
-the variable in which it is stored.
-
-Examples of valid uses of Hollerith constants:
-@smallexample
- complex*16 x(2)
- data x /16Habcdefghijklmnop, 16Hqrstuvwxyz012345/
- x(1) = 16HABCDEFGHIJKLMNOP
- call foo (4h abc)
-@end smallexample
-
-Examples of Hollerith constants:
-@smallexample
- integer*4 a
- a = 0H ! Invalid, at least one character is needed.
- a = 4HAB12 ! Valid
- a = 8H12345678 ! Valid, but the Hollerith constant will be truncated.
- a = 3Hxyz ! Valid, but the Hollerith constant will be padded.
-@end smallexample
-
-In general, Hollerith constants were used to provide a rudimentary
-facility for handling character strings in early Fortran compilers,
-prior to the introduction of @code{CHARACTER} variables in Fortran 77;
-in those cases, the standard-compliant equivalent is to convert the
-program to use proper character strings. On occasion, there may be a
-case where the intent is specifically to initialize a numeric variable
-with a given byte sequence. In these cases, the same result can be
-obtained by using the @code{TRANSFER} statement, as in this example.
-@smallexample
- integer(kind=4) :: a
- a = transfer ("abcd", a) ! equivalent to: a = 4Habcd
-@end smallexample
-
-The use of the @option{-fdec} option extends support of Hollerith constants
-to comparisons:
-@smallexample
- integer*4 a
- a = 4hABCD
- if (a .ne. 4habcd) then
- write(*,*) "no match"
- end if
-@end smallexample
-
-Supported types are numeric (@code{INTEGER}, @code{REAL}, or @code{COMPLEX}),
-and @code{CHARACTER}.
-
-@node Character conversion
-@subsection Character conversion
-@cindex conversion, to character
-
-Allowing character literals to be used in a similar way to Hollerith constants
-is a non-standard extension. This feature is enabled using
--fdec-char-conversions and only applies to character literals of @code{kind=1}.
-
-Character literals can be used in @code{DATA} statements and assignments with
-numeric (@code{INTEGER}, @code{REAL}, or @code{COMPLEX}) or @code{LOGICAL}
-variables. Like Hollerith constants they are copied byte-wise fashion. The
-constant will be padded with spaces or truncated to fit the size of the
-variable in which it is stored.
-
-Examples:
-@smallexample
- integer*4 x
- data x / 'abcd' /
-
- x = 'A' ! Will be padded.
- x = 'ab1234' ! Will be truncated.
-@end smallexample
-
-
-@node Cray pointers
-@subsection Cray pointers
-@cindex pointer, Cray
-
-Cray pointers are part of a non-standard extension that provides a
-C-like pointer in Fortran. This is accomplished through a pair of
-variables: an integer "pointer" that holds a memory address, and a
-"pointee" that is used to dereference the pointer.
-
-Pointer/pointee pairs are declared in statements of the form:
-@smallexample
- pointer ( <pointer> , <pointee> )
-@end smallexample
-or,
-@smallexample
- pointer ( <pointer1> , <pointee1> ), ( <pointer2> , <pointee2> ), ...
-@end smallexample
-The pointer is an integer that is intended to hold a memory address.
-The pointee may be an array or scalar.
-If an assumed-size array is permitted within the scoping unit, a
-pointee can be an assumed-size array.
-That is, the last dimension may be left unspecified by using a @code{*}
-in place of a value. A pointee cannot be an assumed shape array.
-No space is allocated for the pointee.
-
-The pointee may have its type declared before or after the pointer
-statement, and its array specification (if any) may be declared
-before, during, or after the pointer statement. The pointer may be
-declared as an integer prior to the pointer statement. However, some
-machines have default integer sizes that are different than the size
-of a pointer, and so the following code is not portable:
-@smallexample
- integer ipt
- pointer (ipt, iarr)
-@end smallexample
-If a pointer is declared with a kind that is too small, the compiler
-will issue a warning; the resulting binary will probably not work
-correctly, because the memory addresses stored in the pointers may be
-truncated. It is safer to omit the first line of the above example;
-if explicit declaration of ipt's type is omitted, then the compiler
-will ensure that ipt is an integer variable large enough to hold a
-pointer.
-
-Pointer arithmetic is valid with Cray pointers, but it is not the same
-as C pointer arithmetic. Cray pointers are just ordinary integers, so
-the user is responsible for determining how many bytes to add to a
-pointer in order to increment it. Consider the following example:
-@smallexample
- real target(10)
- real pointee(10)
- pointer (ipt, pointee)
- ipt = loc (target)
- ipt = ipt + 1
-@end smallexample
-The last statement does not set @code{ipt} to the address of
-@code{target(1)}, as it would in C pointer arithmetic. Adding @code{1}
-to @code{ipt} just adds one byte to the address stored in @code{ipt}.
-
-Any expression involving the pointee will be translated to use the
-value stored in the pointer as the base address.
-
-To get the address of elements, this extension provides an intrinsic
-function @code{LOC()}. The @code{LOC()} function is equivalent to the
-@code{&} operator in C, except the address is cast to an integer type:
-@smallexample
- real ar(10)
- pointer(ipt, arpte(10))
- real arpte
- ipt = loc(ar) ! Makes arpte is an alias for ar
- arpte(1) = 1.0 ! Sets ar(1) to 1.0
-@end smallexample
-The pointer can also be set by a call to the @code{MALLOC} intrinsic
-(see @ref{MALLOC}).
-
-Cray pointees often are used to alias an existing variable. For
-example:
-@smallexample
- integer target(10)
- integer iarr(10)
- pointer (ipt, iarr)
- ipt = loc(target)
-@end smallexample
-As long as @code{ipt} remains unchanged, @code{iarr} is now an alias for
-@code{target}. The optimizer, however, will not detect this aliasing, so
-it is unsafe to use @code{iarr} and @code{target} simultaneously. Using
-a pointee in any way that violates the Fortran aliasing rules or
-assumptions is illegal. It is the user's responsibility to avoid doing
-this; the compiler works under the assumption that no such aliasing
-occurs.
-
-Cray pointers will work correctly when there is no aliasing (i.e., when
-they are used to access a dynamically allocated block of memory), and
-also in any routine where a pointee is used, but any variable with which
-it shares storage is not used. Code that violates these rules may not
-run as the user intends. This is not a bug in the optimizer; any code
-that violates the aliasing rules is illegal. (Note that this is not
-unique to GNU Fortran; any Fortran compiler that supports Cray pointers
-will ``incorrectly'' optimize code with illegal aliasing.)
-
-There are a number of restrictions on the attributes that can be applied
-to Cray pointers and pointees. Pointees may not have the
-@code{ALLOCATABLE}, @code{INTENT}, @code{OPTIONAL}, @code{DUMMY},
-@code{TARGET}, @code{INTRINSIC}, or @code{POINTER} attributes. Pointers
-may not have the @code{DIMENSION}, @code{POINTER}, @code{TARGET},
-@code{ALLOCATABLE}, @code{EXTERNAL}, or @code{INTRINSIC} attributes, nor
-may they be function results. Pointees may not occur in more than one
-pointer statement. A pointee cannot be a pointer. Pointees cannot occur
-in equivalence, common, or data statements.
-
-A Cray pointer may also point to a function or a subroutine. For
-example, the following excerpt is valid:
-@smallexample
- implicit none
- external sub
- pointer (subptr,subpte)
- external subpte
- subptr = loc(sub)
- call subpte()
- [...]
- subroutine sub
- [...]
- end subroutine sub
-@end smallexample
-
-A pointer may be modified during the course of a program, and this
-will change the location to which the pointee refers. However, when
-pointees are passed as arguments, they are treated as ordinary
-variables in the invoked function. Subsequent changes to the pointer
-will not change the base address of the array that was passed.
-
-@node CONVERT specifier
-@subsection @code{CONVERT} specifier
-@cindex @code{CONVERT} specifier
-
-GNU Fortran allows the conversion of unformatted data between little-
-and big-endian representation to facilitate moving of data
-between different systems. The conversion can be indicated with
-the @code{CONVERT} specifier on the @code{OPEN} statement.
-@xref{GFORTRAN_CONVERT_UNIT}, for an alternative way of specifying
-the data format via an environment variable.
-
-Valid values for @code{CONVERT} on most systems are:
-@itemize @w{}
-@item @code{CONVERT='NATIVE'} Use the native format. This is the default.
-@item @code{CONVERT='SWAP'} Swap between little- and big-endian.
-@item @code{CONVERT='LITTLE_ENDIAN'} Use the little-endian representation
-for unformatted files.
-@item @code{CONVERT='BIG_ENDIAN'} Use the big-endian representation for
-unformatted files.
-@end itemize
-On POWER systems which support @option{-mabi=ieeelongdouble},
-there are additional options, which can be combined with the others
-with commas. Those are
-@itemize @w{}
-@item @code{CONVERT='R16_IEEE'} Use IEEE 128-bit format for
-@code{REAL(KIND=16)}.
-@item @code{CONVERT='R16_IBM'} Use IBM @code{long double} format for
-real@code{REAL(KIND=16)}.
-@end itemize
-
-Using the option could look like this:
-@smallexample
- open(file='big.dat',form='unformatted',access='sequential', &
- convert='big_endian')
-@end smallexample
-
-The value of the conversion can be queried by using
-@code{INQUIRE(CONVERT=ch)}. The values returned are
-@code{'BIG_ENDIAN'} and @code{'LITTLE_ENDIAN'}.
-
-@code{CONVERT} works between big- and little-endian for
-@code{INTEGER} values of all supported kinds and for @code{REAL}
-on IEEE systems of kinds 4 and 8. Conversion between different
-``extended double'' types on different architectures such as
-m68k and x86_64, which GNU Fortran
-supports as @code{REAL(KIND=10)} and @code{REAL(KIND=16)}, will
-probably not work.
-
-@emph{Note that the values specified via the GFORTRAN_CONVERT_UNIT
-environment variable will override the CONVERT specifier in the
-open statement}. This is to give control over data formats to
-users who do not have the source code of their program available.
-
-Using anything but the native representation for unformatted data
-carries a significant speed overhead. If speed in this area matters
-to you, it is best if you use this only for data that needs to be
-portable.
-
-@node OpenMP
-@subsection OpenMP
-@cindex OpenMP
-
-OpenMP (Open Multi-Processing) is an application programming
-interface (API) that supports multi-platform shared memory
-multiprocessing programming in C/C++ and Fortran on many
-architectures, including Unix and Microsoft Windows platforms.
-It consists of a set of compiler directives, library routines,
-and environment variables that influence run-time behavior.
-
-GNU Fortran strives to be compatible to the
-@uref{https://openmp.org/specifications/,
-OpenMP Application Program Interface v4.5}.
-
-To enable the processing of the OpenMP directive @code{!$omp} in
-free-form source code; the @code{c$omp}, @code{*$omp} and @code{!$omp}
-directives in fixed form; the @code{!$} conditional compilation sentinels
-in free form; and the @code{c$}, @code{*$} and @code{!$} sentinels
-in fixed form, @command{gfortran} needs to be invoked with the
-@option{-fopenmp}. This also arranges for automatic linking of the
-GNU Offloading and Multi Processing Runtime Library
-@ref{Top,,libgomp,libgomp,GNU Offloading and Multi Processing Runtime
-Library}.
-
-The OpenMP Fortran runtime library routines are provided both in a
-form of a Fortran 90 module named @code{omp_lib} and in a form of
-a Fortran @code{include} file named @file{omp_lib.h}.
-
-An example of a parallelized loop taken from Appendix A.1 of
-the OpenMP Application Program Interface v2.5:
-@smallexample
-SUBROUTINE A1(N, A, B)
- INTEGER I, N
- REAL B(N), A(N)
-!$OMP PARALLEL DO !I is private by default
- DO I=2,N
- B(I) = (A(I) + A(I-1)) / 2.0
- ENDDO
-!$OMP END PARALLEL DO
-END SUBROUTINE A1
-@end smallexample
-
-Please note:
-@itemize
-@item
-@option{-fopenmp} implies @option{-frecursive}, i.e., all local arrays
-will be allocated on the stack. When porting existing code to OpenMP,
-this may lead to surprising results, especially to segmentation faults
-if the stacksize is limited.
-
-@item
-On glibc-based systems, OpenMP enabled applications cannot be statically
-linked due to limitations of the underlying pthreads-implementation. It
-might be possible to get a working solution if
-@command{-Wl,--whole-archive -lpthread -Wl,--no-whole-archive} is added
-to the command line. However, this is not supported by @command{gcc} and
-thus not recommended.
-@end itemize
-
-@node OpenACC
-@subsection OpenACC
-@cindex OpenACC
-
-OpenACC is an application programming interface (API) that supports
-offloading of code to accelerator devices. It consists of a set of
-compiler directives, library routines, and environment variables that
-influence run-time behavior.
-
-GNU Fortran strives to be compatible to the
-@uref{https://www.openacc.org/, OpenACC Application Programming
-Interface v2.6}.
-
-To enable the processing of the OpenACC directive @code{!$acc} in
-free-form source code; the @code{c$acc}, @code{*$acc} and @code{!$acc}
-directives in fixed form; the @code{!$} conditional compilation
-sentinels in free form; and the @code{c$}, @code{*$} and @code{!$}
-sentinels in fixed form, @command{gfortran} needs to be invoked with
-the @option{-fopenacc}. This also arranges for automatic linking of
-the GNU Offloading and Multi Processing Runtime Library
-@ref{Top,,libgomp,libgomp,GNU Offloading and Multi Processing Runtime
-Library}.
-
-The OpenACC Fortran runtime library routines are provided both in a
-form of a Fortran 90 module named @code{openacc} and in a form of a
-Fortran @code{include} file named @file{openacc_lib.h}.
-
-@node Argument list functions
-@subsection Argument list functions @code{%VAL}, @code{%REF} and @code{%LOC}
-@cindex argument list functions
-@cindex @code{%VAL}
-@cindex @code{%REF}
-@cindex @code{%LOC}
-
-GNU Fortran supports argument list functions @code{%VAL}, @code{%REF}
-and @code{%LOC} statements, for backward compatibility with g77.
-It is recommended that these should be used only for code that is
-accessing facilities outside of GNU Fortran, such as operating system
-or windowing facilities. It is best to constrain such uses to isolated
-portions of a program--portions that deal specifically and exclusively
-with low-level, system-dependent facilities. Such portions might well
-provide a portable interface for use by the program as a whole, but are
-themselves not portable, and should be thoroughly tested each time they
-are rebuilt using a new compiler or version of a compiler.
-
-@code{%VAL} passes a scalar argument by value, @code{%REF} passes it by
-reference and @code{%LOC} passes its memory location. Since gfortran
-already passes scalar arguments by reference, @code{%REF} is in effect
-a do-nothing. @code{%LOC} has the same effect as a Fortran pointer.
-
-An example of passing an argument by value to a C subroutine foo.:
-@smallexample
-C
-C prototype void foo_ (float x);
-C
- external foo
- real*4 x
- x = 3.14159
- call foo (%VAL (x))
- end
-@end smallexample
-
-For details refer to the g77 manual
-@uref{https://gcc.gnu.org/@/onlinedocs/@/gcc-3.4.6/@/g77/@/index.html#Top}.
-
-Also, @code{c_by_val.f} and its partner @code{c_by_val.c} of the
-GNU Fortran testsuite are worth a look.
-
-@node Read/Write after EOF marker
-@subsection Read/Write after EOF marker
-@cindex @code{EOF}
-@cindex @code{BACKSPACE}
-@cindex @code{REWIND}
-
-Some legacy codes rely on allowing @code{READ} or @code{WRITE} after the
-EOF file marker in order to find the end of a file. GNU Fortran normally
-rejects these codes with a run-time error message and suggests the user
-consider @code{BACKSPACE} or @code{REWIND} to properly position
-the file before the EOF marker. As an extension, the run-time error may
-be disabled using -std=legacy.
-
-
-@node STRUCTURE and RECORD
-@subsection @code{STRUCTURE} and @code{RECORD}
-@cindex @code{STRUCTURE}
-@cindex @code{RECORD}
-
-Record structures are a pre-Fortran-90 vendor extension to create
-user-defined aggregate data types. Support for record structures in GNU
-Fortran can be enabled with the @option{-fdec-structure} compile flag.
-If you have a choice, you should instead use Fortran 90's ``derived types'',
-which have a different syntax.
-
-In many cases, record structures can easily be converted to derived types.
-To convert, replace @code{STRUCTURE /}@var{structure-name}@code{/}
-by @code{TYPE} @var{type-name}. Additionally, replace
-@code{RECORD /}@var{structure-name}@code{/} by
-@code{TYPE(}@var{type-name}@code{)}. Finally, in the component access,
-replace the period (@code{.}) by the percent sign (@code{%}).
-
-Here is an example of code using the non portable record structure syntax:
-
-@example
-! Declaring a structure named ``item'' and containing three fields:
-! an integer ID, an description string and a floating-point price.
-STRUCTURE /item/
- INTEGER id
- CHARACTER(LEN=200) description
- REAL price
-END STRUCTURE
-
-! Define two variables, an single record of type ``item''
-! named ``pear'', and an array of items named ``store_catalog''
-RECORD /item/ pear, store_catalog(100)
-
-! We can directly access the fields of both variables
-pear.id = 92316
-pear.description = "juicy D'Anjou pear"
-pear.price = 0.15
-store_catalog(7).id = 7831
-store_catalog(7).description = "milk bottle"
-store_catalog(7).price = 1.2
-
-! We can also manipulate the whole structure
-store_catalog(12) = pear
-print *, store_catalog(12)
-@end example
-
-@noindent
-This code can easily be rewritten in the Fortran 90 syntax as following:
-
-@example
-! ``STRUCTURE /name/ ... END STRUCTURE'' becomes
-! ``TYPE name ... END TYPE''
-TYPE item
- INTEGER id
- CHARACTER(LEN=200) description
- REAL price
-END TYPE
-
-! ``RECORD /name/ variable'' becomes ``TYPE(name) variable''
-TYPE(item) pear, store_catalog(100)
-
-! Instead of using a dot (.) to access fields of a record, the
-! standard syntax uses a percent sign (%)
-pear%id = 92316
-pear%description = "juicy D'Anjou pear"
-pear%price = 0.15
-store_catalog(7)%id = 7831
-store_catalog(7)%description = "milk bottle"
-store_catalog(7)%price = 1.2
-
-! Assignments of a whole variable do not change
-store_catalog(12) = pear
-print *, store_catalog(12)
-@end example
-
-@noindent
-GNU Fortran implements STRUCTURES like derived types with the following
-rules and exceptions:
-
-@itemize @bullet
-@item Structures act like derived types with the @code{SEQUENCE} attribute.
-Otherwise they may contain no specifiers.
-
-@item Structures may contain a special field with the name @code{%FILL}.
-This will create an anonymous component which cannot be accessed but occupies
-space just as if a component of the same type was declared in its place, useful
-for alignment purposes. As an example, the following structure will consist
-of at least sixteen bytes:
-
-@smallexample
-structure /padded/
- character(4) start
- character(8) %FILL
- character(4) end
-end structure
-@end smallexample
-
-@item Structures may share names with other symbols. For example, the following
-is invalid for derived types, but valid for structures:
-
-@smallexample
-structure /header/
- ! ...
-end structure
-record /header/ header
-@end smallexample
-
-@item Structure types may be declared nested within another parent structure.
-The syntax is:
-@smallexample
-structure /type-name/
- ...
- structure [/<type-name>/] <field-list>
-...
-@end smallexample
-
-The type name may be ommitted, in which case the structure type itself is
-anonymous, and other structures of the same type cannot be instantiated. The
-following shows some examples:
-
-@example
-structure /appointment/
- ! nested structure definition: app_time is an array of two 'time'
- structure /time/ app_time (2)
- integer(1) hour, minute
- end structure
- character(10) memo
-end structure
-
-! The 'time' structure is still usable
-record /time/ now
-now = time(5, 30)
-
-...
-
-structure /appointment/
- ! anonymous nested structure definition
- structure start, end
- integer(1) hour, minute
- end structure
- character(10) memo
-end structure
-@end example
-
-@item Structures may contain @code{UNION} blocks. For more detail see the
-section on @ref{UNION and MAP}.
-
-@item Structures support old-style initialization of components, like
-those described in @ref{Old-style variable initialization}. For array
-initializers, an initializer may contain a repeat specification of the form
-@code{<literal-integer> * <constant-initializer>}. The value of the integer
-indicates the number of times to repeat the constant initializer when expanding
-the initializer list.
-@end itemize
-
-@node UNION and MAP
-@subsection @code{UNION} and @code{MAP}
-@cindex @code{UNION}
-@cindex @code{MAP}
-
-Unions are an old vendor extension which were commonly used with the
-non-standard @ref{STRUCTURE and RECORD} extensions. Use of @code{UNION} and
-@code{MAP} is automatically enabled with @option{-fdec-structure}.
-
-A @code{UNION} declaration occurs within a structure; within the definition of
-each union is a number of @code{MAP} blocks. Each @code{MAP} shares storage
-with its sibling maps (in the same union), and the size of the union is the
-size of the largest map within it, just as with unions in C. The major
-difference is that component references do not indicate which union or map the
-component is in (the compiler gets to figure that out).
-
-Here is a small example:
-@smallexample
-structure /myunion/
-union
- map
- character(2) w0, w1, w2
- end map
- map
- character(6) long
- end map
-end union
-end structure
-
-record /myunion/ rec
-! After this assignment...
-rec.long = 'hello!'
-
-! The following is true:
-! rec.w0 === 'he'
-! rec.w1 === 'll'
-! rec.w2 === 'o!'
-@end smallexample
-
-The two maps share memory, and the size of the union is ultimately six bytes:
-
-@example
-0 1 2 3 4 5 6 Byte offset
--------------------------------
-| | | | | | |
--------------------------------
-
-^ W0 ^ W1 ^ W2 ^
- \-------/ \-------/ \-------/
-
-^ LONG ^
- \---------------------------/
-@end example
-
-Following is an example mirroring the layout of an Intel x86_64 register:
-
-@example
-structure /reg/
- union ! U0 ! rax
- map
- character(16) rx
- end map
- map
- character(8) rh ! rah
- union ! U1
- map
- character(8) rl ! ral
- end map
- map
- character(8) ex ! eax
- end map
- map
- character(4) eh ! eah
- union ! U2
- map
- character(4) el ! eal
- end map
- map
- character(4) x ! ax
- end map
- map
- character(2) h ! ah
- character(2) l ! al
- end map
- end union
- end map
- end union
- end map
- end union
-end structure
-record /reg/ a
-
-! After this assignment...
-a.rx = 'AAAAAAAA.BBB.C.D'
-
-! The following is true:
-a.rx === 'AAAAAAAA.BBB.C.D'
-a.rh === 'AAAAAAAA'
-a.rl === '.BBB.C.D'
-a.ex === '.BBB.C.D'
-a.eh === '.BBB'
-a.el === '.C.D'
-a.x === '.C.D'
-a.h === '.C'
-a.l === '.D'
-@end example
-
-@node Type variants for integer intrinsics
-@subsection Type variants for integer intrinsics
-@cindex intrinsics, integer
-
-Similar to the D/C prefixes to real functions to specify the input/output
-types, GNU Fortran offers B/I/J/K prefixes to integer functions for
-compatibility with DEC programs. The types implied by each are:
-
-@example
-@code{B} - @code{INTEGER(kind=1)}
-@code{I} - @code{INTEGER(kind=2)}
-@code{J} - @code{INTEGER(kind=4)}
-@code{K} - @code{INTEGER(kind=8)}
-@end example
-
-GNU Fortran supports these with the flag @option{-fdec-intrinsic-ints}.
-Intrinsics for which prefixed versions are available and in what form are noted
-in @ref{Intrinsic Procedures}. The complete list of supported intrinsics is
-here:
-
-@multitable @columnfractions .2 .2 .2 .2 .2
-
-@headitem Intrinsic @tab B @tab I @tab J @tab K
-
-@item @code{@ref{ABS}}
- @tab @code{BABS} @tab @code{IIABS} @tab @code{JIABS} @tab @code{KIABS}
-@item @code{@ref{BTEST}}
- @tab @code{BBTEST} @tab @code{BITEST} @tab @code{BJTEST} @tab @code{BKTEST}
-@item @code{@ref{IAND}}
- @tab @code{BIAND} @tab @code{IIAND} @tab @code{JIAND} @tab @code{KIAND}
-@item @code{@ref{IBCLR}}
- @tab @code{BBCLR} @tab @code{IIBCLR} @tab @code{JIBCLR} @tab @code{KIBCLR}
-@item @code{@ref{IBITS}}
- @tab @code{BBITS} @tab @code{IIBITS} @tab @code{JIBITS} @tab @code{KIBITS}
-@item @code{@ref{IBSET}}
- @tab @code{BBSET} @tab @code{IIBSET} @tab @code{JIBSET} @tab @code{KIBSET}
-@item @code{@ref{IEOR}}
- @tab @code{BIEOR} @tab @code{IIEOR} @tab @code{JIEOR} @tab @code{KIEOR}
-@item @code{@ref{IOR}}
- @tab @code{BIOR} @tab @code{IIOR} @tab @code{JIOR} @tab @code{KIOR}
-@item @code{@ref{ISHFT}}
- @tab @code{BSHFT} @tab @code{IISHFT} @tab @code{JISHFT} @tab @code{KISHFT}
-@item @code{@ref{ISHFTC}}
- @tab @code{BSHFTC} @tab @code{IISHFTC} @tab @code{JISHFTC} @tab @code{KISHFTC}
-@item @code{@ref{MOD}}
- @tab @code{BMOD} @tab @code{IMOD} @tab @code{JMOD} @tab @code{KMOD}
-@item @code{@ref{NOT}}
- @tab @code{BNOT} @tab @code{INOT} @tab @code{JNOT} @tab @code{KNOT}
-@item @code{@ref{REAL}}
- @tab @code{--} @tab @code{FLOATI} @tab @code{FLOATJ} @tab @code{FLOATK}
-@end multitable
-
-@node AUTOMATIC and STATIC attributes
-@subsection @code{AUTOMATIC} and @code{STATIC} attributes
-@cindex variable attributes
-@cindex @code{AUTOMATIC}
-@cindex @code{STATIC}
-
-With @option{-fdec-static} GNU Fortran supports the DEC extended attributes
-@code{STATIC} and @code{AUTOMATIC} to provide explicit specification of entity
-storage. These follow the syntax of the Fortran standard @code{SAVE} attribute.
-
-@code{STATIC} is exactly equivalent to @code{SAVE}, and specifies that
-an entity should be allocated in static memory. As an example, @code{STATIC}
-local variables will retain their values across multiple calls to a function.
-
-Entities marked @code{AUTOMATIC} will be stack automatic whenever possible.
-@code{AUTOMATIC} is the default for local variables smaller than
-@option{-fmax-stack-var-size}, unless @option{-fno-automatic} is given. This
-attribute overrides @option{-fno-automatic}, @option{-fmax-stack-var-size}, and
-blanket @code{SAVE} statements.
-
-
-Examples:
-
-@example
-subroutine f
- integer, automatic :: i ! automatic variable
- integer x, y ! static variables
- save
- ...
-endsubroutine
-@end example
-@example
-subroutine f
- integer a, b, c, x, y, z
- static :: x
- save y
- automatic z, c
- ! a, b, c, and z are automatic
- ! x and y are static
-endsubroutine
-@end example
-@example
-! Compiled with -fno-automatic
-subroutine f
- integer a, b, c, d
- automatic :: a
- ! a is automatic; b, c, and d are static
-endsubroutine
-@end example
-
-@node Extended math intrinsics
-@subsection Extended math intrinsics
-@cindex intrinsics, math
-@cindex intrinsics, trigonometric functions
-
-GNU Fortran supports an extended list of mathematical intrinsics with the
-compile flag @option{-fdec-math} for compatability with legacy code.
-These intrinsics are described fully in @ref{Intrinsic Procedures} where it is
-noted that they are extensions and should be avoided whenever possible.
-
-Specifically, @option{-fdec-math} enables the @ref{COTAN} intrinsic, and
-trigonometric intrinsics which accept or produce values in degrees instead of
-radians. Here is a summary of the new intrinsics:
-
-@multitable @columnfractions .5 .5
-@headitem Radians @tab Degrees
-@item @code{@ref{ACOS}} @tab @code{@ref{ACOSD}}*
-@item @code{@ref{ASIN}} @tab @code{@ref{ASIND}}*
-@item @code{@ref{ATAN}} @tab @code{@ref{ATAND}}*
-@item @code{@ref{ATAN2}} @tab @code{@ref{ATAN2D}}*
-@item @code{@ref{COS}} @tab @code{@ref{COSD}}*
-@item @code{@ref{COTAN}}* @tab @code{@ref{COTAND}}*
-@item @code{@ref{SIN}} @tab @code{@ref{SIND}}*
-@item @code{@ref{TAN}} @tab @code{@ref{TAND}}*
-@end multitable
-
-* Enabled with @option{-fdec-math}.
-
-For advanced users, it may be important to know the implementation of these
-functions. They are simply wrappers around the standard radian functions, which
-have more accurate builtin versions. These functions convert their arguments
-(or results) to degrees (or radians) by taking the value modulus 360 (or 2*pi)
-and then multiplying it by a constant radian-to-degree (or degree-to-radian)
-factor, as appropriate. The factor is computed at compile-time as 180/pi (or
-pi/180).
-
-@node Form feed as whitespace
-@subsection Form feed as whitespace
-@cindex form feed whitespace
-
-Historically, legacy compilers allowed insertion of form feed characters ('\f',
-ASCII 0xC) at the beginning of lines for formatted output to line printers,
-though the Fortran standard does not mention this. GNU Fortran supports the
-interpretation of form feed characters in source as whitespace for
-compatibility.
-
-@node TYPE as an alias for PRINT
-@subsection TYPE as an alias for PRINT
-@cindex type alias print
-For compatibility, GNU Fortran will interpret @code{TYPE} statements as
-@code{PRINT} statements with the flag @option{-fdec}. With this flag asserted,
-the following two examples are equivalent:
-
-@smallexample
-TYPE *, 'hello world'
-@end smallexample
-
-@smallexample
-PRINT *, 'hello world'
-@end smallexample
-
-@node %LOC as an rvalue
-@subsection %LOC as an rvalue
-@cindex LOC
-Normally @code{%LOC} is allowed only in parameter lists. However the intrinsic
-function @code{LOC} does the same thing, and is usable as the right-hand-side of
-assignments. For compatibility, GNU Fortran supports the use of @code{%LOC} as
-an alias for the builtin @code{LOC} with @option{-std=legacy}. With this
-feature enabled the following two examples are equivalent:
-
-@smallexample
-integer :: i, l
-l = %loc(i)
-call sub(l)
-@end smallexample
-
-@smallexample
-integer :: i
-call sub(%loc(i))
-@end smallexample
-
-@node .XOR. operator
-@subsection .XOR. operator
-@cindex operators, xor
-
-GNU Fortran supports @code{.XOR.} as a logical operator with @code{-std=legacy}
-for compatibility with legacy code. @code{.XOR.} is equivalent to
-@code{.NEQV.}. That is, the output is true if and only if the inputs differ.
-
-@node Bitwise logical operators
-@subsection Bitwise logical operators
-@cindex logical, bitwise
-
-With @option{-fdec}, GNU Fortran relaxes the type constraints on
-logical operators to allow integer operands, and performs the corresponding
-bitwise operation instead. This flag is for compatibility only, and should be
-avoided in new code. Consider:
-
-@smallexample
- INTEGER :: i, j
- i = z'33'
- j = z'cc'
- print *, i .AND. j
-@end smallexample
-
-In this example, compiled with @option{-fdec}, GNU Fortran will
-replace the @code{.AND.} operation with a call to the intrinsic
-@code{@ref{IAND}} function, yielding the bitwise-and of @code{i} and @code{j}.
-
-Note that this conversion will occur if at least one operand is of integral
-type. As a result, a logical operand will be converted to an integer when the
-other operand is an integer in a logical operation. In this case,
-@code{.TRUE.} is converted to @code{1} and @code{.FALSE.} to @code{0}.
-
-Here is the mapping of logical operator to bitwise intrinsic used with
-@option{-fdec}:
-
-@multitable @columnfractions .25 .25 .5
-@headitem Operator @tab Intrinsic @tab Bitwise operation
-@item @code{.NOT.} @tab @code{@ref{NOT}} @tab complement
-@item @code{.AND.} @tab @code{@ref{IAND}} @tab intersection
-@item @code{.OR.} @tab @code{@ref{IOR}} @tab union
-@item @code{.NEQV.} @tab @code{@ref{IEOR}} @tab exclusive or
-@item @code{.EQV.} @tab @code{@ref{NOT}(@ref{IEOR})} @tab complement of exclusive or
-@end multitable
-
-@node Extended I/O specifiers
-@subsection Extended I/O specifiers
-@cindex @code{CARRIAGECONTROL}
-@cindex @code{READONLY}
-@cindex @code{SHARE}
-@cindex @code{SHARED}
-@cindex @code{NOSHARED}
-@cindex I/O specifiers
-
-GNU Fortran supports the additional legacy I/O specifiers
-@code{CARRIAGECONTROL}, @code{READONLY}, and @code{SHARE} with the
-compile flag @option{-fdec}, for compatibility.
-
-@table @code
-@item CARRIAGECONTROL
-The @code{CARRIAGECONTROL} specifier allows a user to control line
-termination settings between output records for an I/O unit. The specifier has
-no meaning for readonly files. When @code{CARRAIGECONTROL} is specified upon
-opening a unit for formatted writing, the exact @code{CARRIAGECONTROL} setting
-determines what characters to write between output records. The syntax is:
-
-@smallexample
-OPEN(..., CARRIAGECONTROL=cc)
-@end smallexample
-
-Where @emph{cc} is a character expression that evaluates to one of the
-following values:
-
-@multitable @columnfractions .2 .8
-@item @code{'LIST'} @tab One line feed between records (default)
-@item @code{'FORTRAN'} @tab Legacy interpretation of the first character (see below)
-@item @code{'NONE'} @tab No separator between records
-@end multitable
-
-With @code{CARRIAGECONTROL='FORTRAN'}, when a record is written, the first
-character of the input record is not written, and instead determines the output
-record separator as follows:
-
-@multitable @columnfractions .3 .3 .4
-@headitem Leading character @tab Meaning @tab Output separating character(s)
-@item @code{'+'} @tab Overprinting @tab Carriage return only
-@item @code{'-'} @tab New line @tab Line feed and carriage return
-@item @code{'0'} @tab Skip line @tab Two line feeds and carriage return
-@item @code{'1'} @tab New page @tab Form feed and carriage return
-@item @code{'$'} @tab Prompting @tab Line feed (no carriage return)
-@item @code{CHAR(0)} @tab Overprinting (no advance) @tab None
-@end multitable
-
-@item READONLY
-The @code{READONLY} specifier may be given upon opening a unit, and is
-equivalent to specifying @code{ACTION='READ'}, except that the file may not be
-deleted on close (i.e. @code{CLOSE} with @code{STATUS="DELETE"}). The syntax
-is:
-
-@smallexample
-@code{OPEN(..., READONLY)}
-@end smallexample
-
-@item SHARE
-The @code{SHARE} specifier allows system-level locking on a unit upon opening
-it for controlled access from multiple processes/threads. The @code{SHARE}
-specifier has several forms:
-
-@smallexample
-OPEN(..., SHARE=sh)
-OPEN(..., SHARED)
-OPEN(..., NOSHARED)
-@end smallexample
-
-Where @emph{sh} in the first form is a character expression that evaluates to
-a value as seen in the table below. The latter two forms are aliases
-for particular values of @emph{sh}:
-
-@multitable @columnfractions .3 .3 .4
-@headitem Explicit form @tab Short form @tab Meaning
-@item @code{SHARE='DENYRW'} @tab @code{NOSHARED} @tab Exclusive (write) lock
-@item @code{SHARE='DENYNONE'} @tab @code{SHARED} @tab Shared (read) lock
-@end multitable
-
-In general only one process may hold an exclusive (write) lock for a given file
-at a time, whereas many processes may hold shared (read) locks for the same
-file.
-
-The behavior of locking may vary with your operating system. On POSIX systems,
-locking is implemented with @code{fcntl}. Consult your corresponding operating
-system's manual pages for further details. Locking via @code{SHARE=} is not
-supported on other systems.
-
-@end table
-
-@node Legacy PARAMETER statements
-@subsection Legacy PARAMETER statements
-@cindex PARAMETER
-
-For compatibility, GNU Fortran supports legacy PARAMETER statements without
-parentheses with @option{-std=legacy}. A warning is emitted if used with
-@option{-std=gnu}, and an error is acknowledged with a real Fortran standard
-flag (@option{-std=f95}, etc...). These statements take the following form:
-
-@smallexample
-implicit real (E)
-parameter e = 2.718282
-real c
-parameter c = 3.0e8
-@end smallexample
-
-@node Default exponents
-@subsection Default exponents
-@cindex exponent
-
-For compatibility, GNU Fortran supports a default exponent of zero in real
-constants with @option{-fdec}. For example, @code{9e} would be
-interpreted as @code{9e0}, rather than an error.
-
-
-@node Extensions not implemented in GNU Fortran
-@section Extensions not implemented in GNU Fortran
-@cindex extensions, not implemented
-
-The long history of the Fortran language, its wide use and broad
-userbase, the large number of different compiler vendors and the lack of
-some features crucial to users in the first standards have lead to the
-existence of a number of important extensions to the language. While
-some of the most useful or popular extensions are supported by the GNU
-Fortran compiler, not all existing extensions are supported. This section
-aims at listing these extensions and offering advice on how best make
-code that uses them running with the GNU Fortran compiler.
-
-@c More can be found here:
-@c -- https://gcc.gnu.org/onlinedocs/gcc-3.4.6/g77/Missing-Features.html
-@c -- the list of Fortran and libgfortran bugs closed as WONTFIX:
-@c http://tinyurl.com/2u4h5y
-
-@menu
-* ENCODE and DECODE statements::
-* Variable FORMAT expressions::
-@c * TYPE and ACCEPT I/O Statements::
-@c * DEFAULTFILE, DISPOSE and RECORDTYPE I/O specifiers::
-@c * Omitted arguments in procedure call::
-* Alternate complex function syntax::
-* Volatile COMMON blocks::
-* OPEN( ... NAME=)::
-* Q edit descriptor::
-@end menu
-
-@node ENCODE and DECODE statements
-@subsection @code{ENCODE} and @code{DECODE} statements
-@cindex @code{ENCODE}
-@cindex @code{DECODE}
-
-GNU Fortran does not support the @code{ENCODE} and @code{DECODE}
-statements. These statements are best replaced by @code{READ} and
-@code{WRITE} statements involving internal files (@code{CHARACTER}
-variables and arrays), which have been part of the Fortran standard since
-Fortran 77. For example, replace a code fragment like
-
-@smallexample
- INTEGER*1 LINE(80)
- REAL A, B, C
-c ... Code that sets LINE
- DECODE (80, 9000, LINE) A, B, C
- 9000 FORMAT (1X, 3(F10.5))
-@end smallexample
-
-@noindent
-with the following:
-
-@smallexample
- CHARACTER(LEN=80) LINE
- REAL A, B, C
-c ... Code that sets LINE
- READ (UNIT=LINE, FMT=9000) A, B, C
- 9000 FORMAT (1X, 3(F10.5))
-@end smallexample
-
-Similarly, replace a code fragment like
-
-@smallexample
- INTEGER*1 LINE(80)
- REAL A, B, C
-c ... Code that sets A, B and C
- ENCODE (80, 9000, LINE) A, B, C
- 9000 FORMAT (1X, 'OUTPUT IS ', 3(F10.5))
-@end smallexample
-
-@noindent
-with the following:
-
-@smallexample
- CHARACTER(LEN=80) LINE
- REAL A, B, C
-c ... Code that sets A, B and C
- WRITE (UNIT=LINE, FMT=9000) A, B, C
- 9000 FORMAT (1X, 'OUTPUT IS ', 3(F10.5))
-@end smallexample
-
-
-@node Variable FORMAT expressions
-@subsection Variable @code{FORMAT} expressions
-@cindex @code{FORMAT}
-
-A variable @code{FORMAT} expression is format statement which includes
-angle brackets enclosing a Fortran expression: @code{FORMAT(I<N>)}. GNU
-Fortran does not support this legacy extension. The effect of variable
-format expressions can be reproduced by using the more powerful (and
-standard) combination of internal output and string formats. For example,
-replace a code fragment like this:
-
-@smallexample
- WRITE(6,20) INT1
- 20 FORMAT(I<N+1>)
-@end smallexample
-
-@noindent
-with the following:
-
-@smallexample
-c Variable declaration
- CHARACTER(LEN=20) FMT
-c
-c Other code here...
-c
- WRITE(FMT,'("(I", I0, ")")') N+1
- WRITE(6,FMT) INT1
-@end smallexample
-
-@noindent
-or with:
-
-@smallexample
-c Variable declaration
- CHARACTER(LEN=20) FMT
-c
-c Other code here...
-c
- WRITE(FMT,*) N+1
- WRITE(6,"(I" // ADJUSTL(FMT) // ")") INT1
-@end smallexample
-
-
-@node Alternate complex function syntax
-@subsection Alternate complex function syntax
-@cindex Complex function
-
-Some Fortran compilers, including @command{g77}, let the user declare
-complex functions with the syntax @code{COMPLEX FUNCTION name*16()}, as
-well as @code{COMPLEX*16 FUNCTION name()}. Both are non-standard, legacy
-extensions. @command{gfortran} accepts the latter form, which is more
-common, but not the former.
-
-
-@node Volatile COMMON blocks
-@subsection Volatile @code{COMMON} blocks
-@cindex @code{VOLATILE}
-@cindex @code{COMMON}
-
-Some Fortran compilers, including @command{g77}, let the user declare
-@code{COMMON} with the @code{VOLATILE} attribute. This is
-invalid standard Fortran syntax and is not supported by
-@command{gfortran}. Note that @command{gfortran} accepts
-@code{VOLATILE} variables in @code{COMMON} blocks since revision 4.3.
-
-
-@node OPEN( ... NAME=)
-@subsection @code{OPEN( ... NAME=)}
-@cindex @code{NAME}
-
-Some Fortran compilers, including @command{g77}, let the user declare
-@code{OPEN( ... NAME=)}. This is
-invalid standard Fortran syntax and is not supported by
-@command{gfortran}. @code{OPEN( ... NAME=)} should be replaced
-with @code{OPEN( ... FILE=)}.
-
-@node Q edit descriptor
-@subsection @code{Q} edit descriptor
-@cindex @code{Q} edit descriptor
-
-Some Fortran compilers provide the @code{Q} edit descriptor, which
-transfers the number of characters left within an input record into an
-integer variable.
-
-A direct replacement of the @code{Q} edit descriptor is not available
-in @command{gfortran}. How to replicate its functionality using
-standard-conforming code depends on what the intent of the original
-code is.
-
-Options to replace @code{Q} may be to read the whole line into a
-character variable and then counting the number of non-blank
-characters left using @code{LEN_TRIM}. Another method may be to use
-formatted stream, read the data up to the position where the @code{Q}
-descriptor occurred, use @code{INQUIRE} to get the file position,
-count the characters up to the next @code{NEW_LINE} and then start
-reading from the position marked previously.
-
-
-@c ---------------------------------------------------------------------
-@c ---------------------------------------------------------------------
-@c Mixed-Language Programming
-@c ---------------------------------------------------------------------
-
-@node Mixed-Language Programming
-@chapter Mixed-Language Programming
-@cindex Interoperability
-@cindex Mixed-language programming
-
-@menu
-* Interoperability with C::
-* GNU Fortran Compiler Directives::
-* Non-Fortran Main Program::
-* Naming and argument-passing conventions::
-@end menu
-
-This chapter is about mixed-language interoperability, but also
-applies if you link Fortran code compiled by different compilers. In
-most cases, use of the C Binding features of the Fortran 2003 and
-later standards is sufficient.
-
-For example, it is possible to mix Fortran code with C++ code as well
-as C, if you declare the interface functions as @code{extern "C"} on
-the C++ side and @code{BIND(C)} on the Fortran side, and follow the
-rules for interoperability with C. Note that you cannot manipulate
-C++ class objects in Fortran or vice versa except as opaque pointers.
-
-You can use the @command{gfortran} command to link both Fortran and
-non-Fortran code into the same program, or you can use @command{gcc}
-or @command{g++} if you also add an explicit @option{-lgfortran} option
-to link with the Fortran library. If your main program is written in
-C or some other language instead of Fortran, see
-@ref{Non-Fortran Main Program}, below.
-
-@node Interoperability with C
-@section Interoperability with C
-@cindex interoperability with C
-@cindex C interoperability
-
-@menu
-* Intrinsic Types::
-* Derived Types and struct::
-* Interoperable Global Variables::
-* Interoperable Subroutines and Functions::
-* Working with C Pointers::
-* Further Interoperability of Fortran with C::
-@end menu
-
-Since Fortran 2003 (ISO/IEC 1539-1:2004(E)) there is a
-standardized way to generate procedure and derived-type
-declarations and global variables that are interoperable with C
-(ISO/IEC 9899:1999). The @code{BIND(C)} attribute has been added
-to inform the compiler that a symbol shall be interoperable with C;
-also, some constraints are added. Note, however, that not
-all C features have a Fortran equivalent or vice versa. For instance,
-neither C's unsigned integers nor C's functions with variable number
-of arguments have an equivalent in Fortran.
-
-Note that array dimensions are reversely ordered in C and that arrays in
-C always start with index 0 while in Fortran they start by default with
-1. Thus, an array declaration @code{A(n,m)} in Fortran matches
-@code{A[m][n]} in C and accessing the element @code{A(i,j)} matches
-@code{A[j-1][i-1]}. The element following @code{A(i,j)} (C: @code{A[j-1][i-1]};
-assuming @math{i < n}) in memory is @code{A(i+1,j)} (C: @code{A[j-1][i]}).
-
-@node Intrinsic Types
-@subsection Intrinsic Types
-@cindex C intrinsic type interoperability
-@cindex intrinsic type interoperability with C
-@cindex interoperability, intrinsic type
-
-In order to ensure that exactly the same variable type and kind is used
-in C and Fortran, you should use the named constants for kind parameters
-that are defined in the @code{ISO_C_BINDING} intrinsic module.
-That module contains named constants of character type representing
-the escaped special characters in C, such as newline.
-For a list of the constants, see @ref{ISO_C_BINDING}.
-
-For logical types, please note that the Fortran standard only guarantees
-interoperability between C99's @code{_Bool} and Fortran's @code{C_Bool}-kind
-logicals and C99 defines that @code{true} has the value 1 and @code{false}
-the value 0. Using any other integer value with GNU Fortran's @code{LOGICAL}
-(with any kind parameter) gives an undefined result. (Passing other integer
-values than 0 and 1 to GCC's @code{_Bool} is also undefined, unless the
-integer is explicitly or implicitly casted to @code{_Bool}.)
-
-@node Derived Types and struct
-@subsection Derived Types and struct
-@cindex C derived type and struct interoperability
-@cindex derived type interoperability with C
-@cindex interoperability, derived type and struct
-
-For compatibility of derived types with @code{struct}, use
-the @code{BIND(C)} attribute in the type declaration. For instance, the
-following type declaration
-
-@smallexample
- USE ISO_C_BINDING
- TYPE, BIND(C) :: myType
- INTEGER(C_INT) :: i1, i2
- INTEGER(C_SIGNED_CHAR) :: i3
- REAL(C_DOUBLE) :: d1
- COMPLEX(C_FLOAT_COMPLEX) :: c1
- CHARACTER(KIND=C_CHAR) :: str(5)
- END TYPE
-@end smallexample
-
-@noindent
-matches the following @code{struct} declaration in C
-
-@smallexample
- struct @{
- int i1, i2;
- /* Note: "char" might be signed or unsigned. */
- signed char i3;
- double d1;
- float _Complex c1;
- char str[5];
- @} myType;
-@end smallexample
-
-Derived types with the C binding attribute shall not have the @code{sequence}
-attribute, type parameters, the @code{extends} attribute, nor type-bound
-procedures. Every component must be of interoperable type and kind and may not
-have the @code{pointer} or @code{allocatable} attribute. The names of the
-components are irrelevant for interoperability.
-
-As there exist no direct Fortran equivalents, neither unions nor structs
-with bit field or variable-length array members are interoperable.
-
-@node Interoperable Global Variables
-@subsection Interoperable Global Variables
-@cindex C variable interoperability
-@cindex variable interoperability with C
-@cindex interoperability, variable
-
-Variables can be made accessible from C using the C binding attribute,
-optionally together with specifying a binding name. Those variables
-have to be declared in the declaration part of a @code{MODULE},
-be of interoperable type, and have neither the @code{pointer} nor
-the @code{allocatable} attribute.
-
-@smallexample
- MODULE m
- USE myType_module
- USE ISO_C_BINDING
- integer(C_INT), bind(C, name="_MyProject_flags") :: global_flag
- type(myType), bind(C) :: tp
- END MODULE
-@end smallexample
-
-Here, @code{_MyProject_flags} is the case-sensitive name of the variable
-as seen from C programs while @code{global_flag} is the case-insensitive
-name as seen from Fortran. If no binding name is specified, as for
-@var{tp}, the C binding name is the (lowercase) Fortran binding name.
-If a binding name is specified, only a single variable may be after the
-double colon. Note of warning: You cannot use a global variable to
-access @var{errno} of the C library as the C standard allows it to be
-a macro. Use the @code{IERRNO} intrinsic (GNU extension) instead.
-
-@node Interoperable Subroutines and Functions
-@subsection Interoperable Subroutines and Functions
-@cindex C procedure interoperability
-@cindex procedure interoperability with C
-@cindex function interoperability with C
-@cindex subroutine interoperability with C
-@cindex interoperability, subroutine and function
-
-Subroutines and functions have to have the @code{BIND(C)} attribute to
-be compatible with C. The dummy argument declaration is relatively
-straightforward. However, one needs to be careful because C uses
-call-by-value by default while Fortran behaves usually similar to
-call-by-reference. Furthermore, strings and pointers are handled
-differently.
-
-To pass a variable by value, use the @code{VALUE} attribute.
-Thus, the following C prototype
-
-@smallexample
-@code{int func(int i, int *j)}
-@end smallexample
-
-@noindent
-matches the Fortran declaration
-
-@smallexample
- integer(c_int) function func(i,j)
- use iso_c_binding, only: c_int
- integer(c_int), VALUE :: i
- integer(c_int) :: j
-@end smallexample
-
-Note that pointer arguments also frequently need the @code{VALUE} attribute,
-see @ref{Working with C Pointers}.
-
-Strings are handled quite differently in C and Fortran. In C a string
-is a @code{NUL}-terminated array of characters while in Fortran each string
-has a length associated with it and is thus not terminated (by e.g.
-@code{NUL}). For example, if you want to use the following C function,
-
-@smallexample
- #include <stdio.h>
- void print_C(char *string) /* equivalent: char string[] */
- @{
- printf("%s\n", string);
- @}
-@end smallexample
-
-@noindent
-to print ``Hello World'' from Fortran, you can call it using
-
-@smallexample
- use iso_c_binding, only: C_CHAR, C_NULL_CHAR
- interface
- subroutine print_c(string) bind(C, name="print_C")
- use iso_c_binding, only: c_char
- character(kind=c_char) :: string(*)
- end subroutine print_c
- end interface
- call print_c(C_CHAR_"Hello World"//C_NULL_CHAR)
-@end smallexample
-
-As the example shows, you need to ensure that the
-string is @code{NUL} terminated. Additionally, the dummy argument
-@var{string} of @code{print_C} is a length-one assumed-size
-array; using @code{character(len=*)} is not allowed. The example
-above uses @code{c_char_"Hello World"} to ensure the string
-literal has the right type; typically the default character
-kind and @code{c_char} are the same and thus @code{"Hello World"}
-is equivalent. However, the standard does not guarantee this.
-
-The use of strings is now further illustrated using the C library
-function @code{strncpy}, whose prototype is
-
-@smallexample
- char *strncpy(char *restrict s1, const char *restrict s2, size_t n);
-@end smallexample
-
-@noindent
-The function @code{strncpy} copies at most @var{n} characters from
-string @var{s2} to @var{s1} and returns @var{s1}. In the following
-example, we ignore the return value:
-
-@smallexample
- use iso_c_binding
- implicit none
- character(len=30) :: str,str2
- interface
- ! Ignore the return value of strncpy -> subroutine
- ! "restrict" is always assumed if we do not pass a pointer
- subroutine strncpy(dest, src, n) bind(C)
- import
- character(kind=c_char), intent(out) :: dest(*)
- character(kind=c_char), intent(in) :: src(*)
- integer(c_size_t), value, intent(in) :: n
- end subroutine strncpy
- end interface
- str = repeat('X',30) ! Initialize whole string with 'X'
- call strncpy(str, c_char_"Hello World"//C_NULL_CHAR, &
- len(c_char_"Hello World",kind=c_size_t))
- print '(a)', str ! prints: "Hello WorldXXXXXXXXXXXXXXXXXXX"
- end
-@end smallexample
-
-The intrinsic procedures are described in @ref{Intrinsic Procedures}.
-
-@node Working with C Pointers
-@subsection Working with C Pointers
-@cindex C pointers
-@cindex pointers, C
-
-C pointers are represented in Fortran via the special opaque derived
-type @code{type(c_ptr)} (with private components). C pointers are distinct
-from Fortran objects with the @code{POINTER} attribute. Thus one needs to
-use intrinsic conversion procedures to convert from or to C pointers.
-For some applications, using an assumed type (@code{TYPE(*)}) can be
-an alternative to a C pointer, and you can also use library routines
-to access Fortran pointers from C. See @ref{Further Interoperability
-of Fortran with C}.
-
-Here is an example of using C pointers in Fortran:
-
-@smallexample
- use iso_c_binding
- type(c_ptr) :: cptr1, cptr2
- integer, target :: array(7), scalar
- integer, pointer :: pa(:), ps
- cptr1 = c_loc(array(1)) ! The programmer needs to ensure that the
- ! array is contiguous if required by the C
- ! procedure
- cptr2 = c_loc(scalar)
- call c_f_pointer(cptr2, ps)
- call c_f_pointer(cptr2, pa, shape=[7])
-@end smallexample
-
-When converting C to Fortran arrays, the one-dimensional @code{SHAPE} argument
-has to be passed.
-
-If a pointer is a dummy argument of an interoperable procedure, it usually
-has to be declared using the @code{VALUE} attribute. @code{void*}
-matches @code{TYPE(C_PTR), VALUE}, while @code{TYPE(C_PTR)} alone
-matches @code{void**}.
-
-Procedure pointers are handled analogously to pointers; the C type is
-@code{TYPE(C_FUNPTR)} and the intrinsic conversion procedures are
-@code{C_F_PROCPOINTER} and @code{C_FUNLOC}.
-
-Let us consider two examples of actually passing a procedure pointer from
-C to Fortran and vice versa. Note that these examples are also very
-similar to passing ordinary pointers between both languages. First,
-consider this code in C:
-
-@smallexample
-/* Procedure implemented in Fortran. */
-void get_values (void (*)(double));
-
-/* Call-back routine we want called from Fortran. */
-void
-print_it (double x)
-@{
- printf ("Number is %f.\n", x);
-@}
-
-/* Call Fortran routine and pass call-back to it. */
-void
-foobar ()
-@{
- get_values (&print_it);
-@}
-@end smallexample
-
-A matching implementation for @code{get_values} in Fortran, that correctly
-receives the procedure pointer from C and is able to call it, is given
-in the following @code{MODULE}:
-
-@smallexample
-MODULE m
- IMPLICIT NONE
-
- ! Define interface of call-back routine.
- ABSTRACT INTERFACE
- SUBROUTINE callback (x)
- USE, INTRINSIC :: ISO_C_BINDING
- REAL(KIND=C_DOUBLE), INTENT(IN), VALUE :: x
- END SUBROUTINE callback
- END INTERFACE
-
-CONTAINS
-
- ! Define C-bound procedure.
- SUBROUTINE get_values (cproc) BIND(C)
- USE, INTRINSIC :: ISO_C_BINDING
- TYPE(C_FUNPTR), INTENT(IN), VALUE :: cproc
-
- PROCEDURE(callback), POINTER :: proc
-
- ! Convert C to Fortran procedure pointer.
- CALL C_F_PROCPOINTER (cproc, proc)
-
- ! Call it.
- CALL proc (1.0_C_DOUBLE)
- CALL proc (-42.0_C_DOUBLE)
- CALL proc (18.12_C_DOUBLE)
- END SUBROUTINE get_values
-
-END MODULE m
-@end smallexample
-
-Next, we want to call a C routine that expects a procedure pointer argument
-and pass it a Fortran procedure (which clearly must be interoperable!).
-Again, the C function may be:
-
-@smallexample
-int
-call_it (int (*func)(int), int arg)
-@{
- return func (arg);
-@}
-@end smallexample
-
-It can be used as in the following Fortran code:
-
-@smallexample
-MODULE m
- USE, INTRINSIC :: ISO_C_BINDING
- IMPLICIT NONE
-
- ! Define interface of C function.
- INTERFACE
- INTEGER(KIND=C_INT) FUNCTION call_it (func, arg) BIND(C)
- USE, INTRINSIC :: ISO_C_BINDING
- TYPE(C_FUNPTR), INTENT(IN), VALUE :: func
- INTEGER(KIND=C_INT), INTENT(IN), VALUE :: arg
- END FUNCTION call_it
- END INTERFACE
-
-CONTAINS
-
- ! Define procedure passed to C function.
- ! It must be interoperable!
- INTEGER(KIND=C_INT) FUNCTION double_it (arg) BIND(C)
- INTEGER(KIND=C_INT), INTENT(IN), VALUE :: arg
- double_it = arg + arg
- END FUNCTION double_it
-
- ! Call C function.
- SUBROUTINE foobar ()
- TYPE(C_FUNPTR) :: cproc
- INTEGER(KIND=C_INT) :: i
-
- ! Get C procedure pointer.
- cproc = C_FUNLOC (double_it)
-
- ! Use it.
- DO i = 1_C_INT, 10_C_INT
- PRINT *, call_it (cproc, i)
- END DO
- END SUBROUTINE foobar
-
-END MODULE m
-@end smallexample
-
-@node Further Interoperability of Fortran with C
-@subsection Further Interoperability of Fortran with C
-@cindex Further Interoperability of Fortran with C
-@cindex TS 29113
-@cindex array descriptor
-@cindex dope vector
-@cindex assumed-type
-@cindex assumed-rank
-
-GNU Fortran implements the Technical Specification ISO/IEC TS
-29113:2012, which extends the interoperability support of Fortran 2003
-and Fortran 2008 and is now part of the 2018 Fortran standard.
-Besides removing some restrictions and constraints, the Technical
-Specification adds assumed-type (@code{TYPE(*)}) and assumed-rank
-(@code{DIMENSION(..)}) variables and allows for interoperability of
-assumed-shape, assumed-rank, and deferred-shape arrays, as well as
-allocatables and pointers. Objects of these types are passed to
-@code{BIND(C)} functions as descriptors with a standard interface,
-declared in the header file @code{<ISO_Fortran_binding.h>}.
-
-Note: Currently, GNU Fortran does not use internally the array descriptor
-(dope vector) as specified in the Technical Specification, but uses
-an array descriptor with different fields in functions without the
-@code{BIND(C)} attribute. Arguments to functions marked @code{BIND(C)}
-are converted to the specified form. If you need to access GNU Fortran's
-internal array descriptor, you can use the Chasm Language Interoperability
-Tools, @url{http://chasm-interop.sourceforge.net/}.
-
-@node GNU Fortran Compiler Directives
-@section GNU Fortran Compiler Directives
-
-@menu
-* ATTRIBUTES directive::
-* UNROLL directive::
-* BUILTIN directive::
-* IVDEP directive::
-* VECTOR directive::
-* NOVECTOR directive::
-@end menu
-
-@node ATTRIBUTES directive
-@subsection ATTRIBUTES directive
-
-The Fortran standard describes how a conforming program shall
-behave; however, the exact implementation is not standardized. In order
-to allow the user to choose specific implementation details, compiler
-directives can be used to set attributes of variables and procedures
-which are not part of the standard. Whether a given attribute is
-supported and its exact effects depend on both the operating system and
-on the processor; see
-@ref{Top,,C Extensions,gcc,Using the GNU Compiler Collection (GCC)}
-for details.
-
-For procedures and procedure pointers, the following attributes can
-be used to change the calling convention:
-
-@itemize
-@item @code{CDECL} -- standard C calling convention
-@item @code{STDCALL} -- convention where the called procedure pops the stack
-@item @code{FASTCALL} -- part of the arguments are passed via registers
-instead using the stack
-@end itemize
-
-Besides changing the calling convention, the attributes also influence
-the decoration of the symbol name, e.g., by a leading underscore or by
-a trailing at-sign followed by the number of bytes on the stack. When
-assigning a procedure to a procedure pointer, both should use the same
-calling convention.
-
-On some systems, procedures and global variables (module variables and
-@code{COMMON} blocks) need special handling to be accessible when they
-are in a shared library. The following attributes are available:
-
-@itemize
-@item @code{DLLEXPORT} -- provide a global pointer to a pointer in the DLL
-@item @code{DLLIMPORT} -- reference the function or variable using a
-global pointer
-@end itemize
-
-For dummy arguments, the @code{NO_ARG_CHECK} attribute can be used; in
-other compilers, it is also known as @code{IGNORE_TKR}. For dummy arguments
-with this attribute actual arguments of any type and kind (similar to
-@code{TYPE(*)}), scalars and arrays of any rank (no equivalent
-in Fortran standard) are accepted. As with @code{TYPE(*)}, the argument
-is unlimited polymorphic and no type information is available.
-Additionally, the argument may only be passed to dummy arguments
-with the @code{NO_ARG_CHECK} attribute and as argument to the
-@code{PRESENT} intrinsic function and to @code{C_LOC} of the
-@code{ISO_C_BINDING} module.
-
-Variables with @code{NO_ARG_CHECK} attribute shall be of assumed-type
-(@code{TYPE(*)}; recommended) or of type @code{INTEGER}, @code{LOGICAL},
-@code{REAL} or @code{COMPLEX}. They shall not have the @code{ALLOCATE},
-@code{CODIMENSION}, @code{INTENT(OUT)}, @code{POINTER} or @code{VALUE}
-attribute; furthermore, they shall be either scalar or of assumed-size
-(@code{dimension(*)}). As @code{TYPE(*)}, the @code{NO_ARG_CHECK} attribute
-requires an explicit interface.
-
-@itemize
-@item @code{NO_ARG_CHECK} -- disable the type, kind and rank checking
-@item @code{DEPRECATED} -- print a warning when using a such-tagged
-deprecated procedure, variable or parameter; the warning can be suppressed
-with @option{-Wno-deprecated-declarations}.
-@end itemize
-
-
-The attributes are specified using the syntax
-
-@code{!GCC$ ATTRIBUTES} @var{attribute-list} @code{::} @var{variable-list}
-
-where in free-form source code only whitespace is allowed before @code{!GCC$}
-and in fixed-form source code @code{!GCC$}, @code{cGCC$} or @code{*GCC$} shall
-start in the first column.
-
-For procedures, the compiler directives shall be placed into the body
-of the procedure; for variables and procedure pointers, they shall be in
-the same declaration part as the variable or procedure pointer.
-
-
-@node UNROLL directive
-@subsection UNROLL directive
-
-The syntax of the directive is
-
-@code{!GCC$ unroll N}
-
-You can use this directive to control how many times a loop should be unrolled.
-It must be placed immediately before a @code{DO} loop and applies only to the
-loop that follows. N is an integer constant specifying the unrolling factor.
-The values of 0 and 1 block any unrolling of the loop.
-
-
-@node BUILTIN directive
-@subsection BUILTIN directive
-
-The syntax of the directive is
-
-@code{!GCC$ BUILTIN (B) attributes simd FLAGS IF('target')}
-
-You can use this directive to define which middle-end built-ins provide vector
-implementations. @code{B} is name of the middle-end built-in. @code{FLAGS}
-are optional and must be either "(inbranch)" or "(notinbranch)".
-@code{IF} statement is optional and is used to filter multilib ABIs
-for the built-in that should be vectorized. Example usage:
-
-@smallexample
-!GCC$ builtin (sinf) attributes simd (notinbranch) if('x86_64')
-@end smallexample
-
-The purpose of the directive is to provide an API among the GCC compiler and
-the GNU C Library which would define vector implementations of math routines.
-
-
-@node IVDEP directive
-@subsection IVDEP directive
-
-The syntax of the directive is
-
-@code{!GCC$ ivdep}
-
-This directive tells the compiler to ignore vector dependencies in the
-following loop. It must be placed immediately before a @code{DO} loop
-and applies only to the loop that follows.
-
-Sometimes the compiler may not have sufficient information to decide
-whether a particular loop is vectorizable due to potential
-dependencies between iterations. The purpose of the directive is to
-tell the compiler that vectorization is safe.
-
-This directive is intended for annotation of existing code. For new
-code it is recommended to consider OpenMP SIMD directives as potential
-alternative.
-
-
-@node VECTOR directive
-@subsection VECTOR directive
-
-The syntax of the directive is
-
-@code{!GCC$ vector}
-
-This directive tells the compiler to vectorize the following loop. It
-must be placed immediately before a @code{DO} loop and applies only to
-the loop that follows.
-
-
-@node NOVECTOR directive
-@subsection NOVECTOR directive
-
-The syntax of the directive is
-
-@code{!GCC$ novector}
-
-This directive tells the compiler to not vectorize the following loop.
-It must be placed immediately before a @code{DO} loop and applies only
-to the loop that follows.
-
-
-@node Non-Fortran Main Program
-@section Non-Fortran Main Program
-
-@menu
-* _gfortran_set_args:: Save command-line arguments
-* _gfortran_set_options:: Set library option flags
-* _gfortran_set_convert:: Set endian conversion
-* _gfortran_set_record_marker:: Set length of record markers
-* _gfortran_set_fpe:: Set when a Floating Point Exception should be raised
-* _gfortran_set_max_subrecord_length:: Set subrecord length
-@end menu
-
-Even if you are doing mixed-language programming, it is very
-likely that you do not need to know or use the information in this
-section. Since it is about the internal structure of GNU Fortran,
-it may also change in GCC minor releases.
-
-When you compile a @code{PROGRAM} with GNU Fortran, a function
-with the name @code{main} (in the symbol table of the object file)
-is generated, which initializes the libgfortran library and then
-calls the actual program which uses the name @code{MAIN__}, for
-historic reasons. If you link GNU Fortran compiled procedures
-to, e.g., a C or C++ program or to a Fortran program compiled by
-a different compiler, the libgfortran library is not initialized
-and thus a few intrinsic procedures do not work properly, e.g.
-those for obtaining the command-line arguments.
-
-Therefore, if your @code{PROGRAM} is not compiled with
-GNU Fortran and the GNU Fortran compiled procedures require
-intrinsics relying on the library initialization, you need to
-initialize the library yourself. Using the default options,
-gfortran calls @code{_gfortran_set_args} and
-@code{_gfortran_set_options}. The initialization of the former
-is needed if the called procedures access the command line
-(and for backtracing); the latter sets some flags based on the
-standard chosen or to enable backtracing. In typical programs,
-it is not necessary to call any initialization function.
-
-If your @code{PROGRAM} is compiled with GNU Fortran, you shall
-not call any of the following functions. The libgfortran
-initialization functions are shown in C syntax but using C
-bindings they are also accessible from Fortran.
-
-
-@node _gfortran_set_args
-@subsection @code{_gfortran_set_args} --- Save command-line arguments
-@fnindex _gfortran_set_args
-@cindex libgfortran initialization, set_args
-
-@table @asis
-@item @emph{Description}:
-@code{_gfortran_set_args} saves the command-line arguments; this
-initialization is required if any of the command-line intrinsics
-is called. Additionally, it shall be called if backtracing is
-enabled (see @code{_gfortran_set_options}).
-
-@item @emph{Syntax}:
-@code{void _gfortran_set_args (int argc, char *argv[])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{argc} @tab number of command line argument strings
-@item @var{argv} @tab the command-line argument strings; argv[0]
-is the pathname of the executable itself.
-@end multitable
-
-@item @emph{Example}:
-@smallexample
-int main (int argc, char *argv[])
-@{
- /* Initialize libgfortran. */
- _gfortran_set_args (argc, argv);
- return 0;
-@}
-@end smallexample
-@end table
-
-
-@node _gfortran_set_options
-@subsection @code{_gfortran_set_options} --- Set library option flags
-@fnindex _gfortran_set_options
-@cindex libgfortran initialization, set_options
-
-@table @asis
-@item @emph{Description}:
-@code{_gfortran_set_options} sets several flags related to the Fortran
-standard to be used, whether backtracing should be enabled
-and whether range checks should be performed. The syntax allows for
-upward compatibility since the number of passed flags is specified; for
-non-passed flags, the default value is used. See also
-@pxref{Code Gen Options}. Please note that not all flags are actually
-used.
-
-@item @emph{Syntax}:
-@code{void _gfortran_set_options (int num, int options[])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{num} @tab number of options passed
-@item @var{argv} @tab The list of flag values
-@end multitable
-
-@item @emph{option flag list}:
-@multitable @columnfractions .15 .70
-@item @var{option}[0] @tab Allowed standard; can give run-time errors
-if e.g. an input-output edit descriptor is invalid in a given
-standard. Possible values are (bitwise or-ed) @code{GFC_STD_F77} (1),
-@code{GFC_STD_F95_OBS} (2), @code{GFC_STD_F95_DEL} (4),
-@code{GFC_STD_F95} (8), @code{GFC_STD_F2003} (16), @code{GFC_STD_GNU}
-(32), @code{GFC_STD_LEGACY} (64), @code{GFC_STD_F2008} (128),
-@code{GFC_STD_F2008_OBS} (256), @code{GFC_STD_F2008_TS} (512),
-@code{GFC_STD_F2018} (1024), @code{GFC_STD_F2018_OBS} (2048), and
-@code{GFC_STD=F2018_DEL} (4096). Default: @code{GFC_STD_F95_OBS |
-GFC_STD_F95_DEL | GFC_STD_F95 | GFC_STD_F2003 | GFC_STD_F2008 |
-GFC_STD_F2008_TS | GFC_STD_F2008_OBS | GFC_STD_F77 | GFC_STD_F2018 |
-GFC_STD_F2018_OBS | GFC_STD_F2018_DEL | GFC_STD_GNU | GFC_STD_LEGACY}.
-@item @var{option}[1] @tab Standard-warning flag; prints a warning to
-standard error. Default: @code{GFC_STD_F95_DEL | GFC_STD_LEGACY}.
-@item @var{option}[2] @tab If non zero, enable pedantic checking.
-Default: off.
-@item @var{option}[3] @tab Unused.
-@item @var{option}[4] @tab If non zero, enable backtracing on run-time
-errors. Default: off. (Default in the compiler: on.)
-Note: Installs a signal handler and requires command-line
-initialization using @code{_gfortran_set_args}.
-@item @var{option}[5] @tab If non zero, supports signed zeros.
-Default: enabled.
-@item @var{option}[6] @tab Enables run-time checking. Possible values
-are (bitwise or-ed): GFC_RTCHECK_BOUNDS (1), GFC_RTCHECK_ARRAY_TEMPS (2),
-GFC_RTCHECK_RECURSION (4), GFC_RTCHECK_DO (8), GFC_RTCHECK_POINTER (16),
-GFC_RTCHECK_MEM (32), GFC_RTCHECK_BITS (64).
-Default: disabled.
-@item @var{option}[7] @tab Unused.
-@item @var{option}[8] @tab Show a warning when invoking @code{STOP} and
-@code{ERROR STOP} if a floating-point exception occurred. Possible values
-are (bitwise or-ed) @code{GFC_FPE_INVALID} (1), @code{GFC_FPE_DENORMAL} (2),
-@code{GFC_FPE_ZERO} (4), @code{GFC_FPE_OVERFLOW} (8),
-@code{GFC_FPE_UNDERFLOW} (16), @code{GFC_FPE_INEXACT} (32). Default: None (0).
-(Default in the compiler: @code{GFC_FPE_INVALID | GFC_FPE_DENORMAL |
-GFC_FPE_ZERO | GFC_FPE_OVERFLOW | GFC_FPE_UNDERFLOW}.)
-@end multitable
-
-@item @emph{Example}:
-@smallexample
- /* Use gfortran 4.9 default options. */
- static int options[] = @{68, 511, 0, 0, 1, 1, 0, 0, 31@};
- _gfortran_set_options (9, &options);
-@end smallexample
-@end table
-
-
-@node _gfortran_set_convert
-@subsection @code{_gfortran_set_convert} --- Set endian conversion
-@fnindex _gfortran_set_convert
-@cindex libgfortran initialization, set_convert
-
-@table @asis
-@item @emph{Description}:
-@code{_gfortran_set_convert} set the representation of data for
-unformatted files.
-
-@item @emph{Syntax}:
-@code{void _gfortran_set_convert (int conv)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{conv} @tab Endian conversion, possible values:
-GFC_CONVERT_NATIVE (0, default), GFC_CONVERT_SWAP (1),
-GFC_CONVERT_BIG (2), GFC_CONVERT_LITTLE (3).
-@end multitable
-
-@item @emph{Example}:
-@smallexample
-int main (int argc, char *argv[])
-@{
- /* Initialize libgfortran. */
- _gfortran_set_args (argc, argv);
- _gfortran_set_convert (1);
- return 0;
-@}
-@end smallexample
-@end table
-
-
-@node _gfortran_set_record_marker
-@subsection @code{_gfortran_set_record_marker} --- Set length of record markers
-@fnindex _gfortran_set_record_marker
-@cindex libgfortran initialization, set_record_marker
-
-@table @asis
-@item @emph{Description}:
-@code{_gfortran_set_record_marker} sets the length of record markers
-for unformatted files.
-
-@item @emph{Syntax}:
-@code{void _gfortran_set_record_marker (int val)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{val} @tab Length of the record marker; valid values
-are 4 and 8. Default is 4.
-@end multitable
-
-@item @emph{Example}:
-@smallexample
-int main (int argc, char *argv[])
-@{
- /* Initialize libgfortran. */
- _gfortran_set_args (argc, argv);
- _gfortran_set_record_marker (8);
- return 0;
-@}
-@end smallexample
-@end table
-
-
-@node _gfortran_set_fpe
-@subsection @code{_gfortran_set_fpe} --- Enable floating point exception traps
-@fnindex _gfortran_set_fpe
-@cindex libgfortran initialization, set_fpe
-
-@table @asis
-@item @emph{Description}:
-@code{_gfortran_set_fpe} enables floating point exception traps for
-the specified exceptions. On most systems, this will result in a
-SIGFPE signal being sent and the program being aborted.
-
-@item @emph{Syntax}:
-@code{void _gfortran_set_fpe (int val)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{option}[0] @tab IEEE exceptions. Possible values are
-(bitwise or-ed) zero (0, default) no trapping,
-@code{GFC_FPE_INVALID} (1), @code{GFC_FPE_DENORMAL} (2),
-@code{GFC_FPE_ZERO} (4), @code{GFC_FPE_OVERFLOW} (8),
-@code{GFC_FPE_UNDERFLOW} (16), and @code{GFC_FPE_INEXACT} (32).
-@end multitable
-
-@item @emph{Example}:
-@smallexample
-int main (int argc, char *argv[])
-@{
- /* Initialize libgfortran. */
- _gfortran_set_args (argc, argv);
- /* FPE for invalid operations such as SQRT(-1.0). */
- _gfortran_set_fpe (1);
- return 0;
-@}
-@end smallexample
-@end table
-
-
-@node _gfortran_set_max_subrecord_length
-@subsection @code{_gfortran_set_max_subrecord_length} --- Set subrecord length
-@fnindex _gfortran_set_max_subrecord_length
-@cindex libgfortran initialization, set_max_subrecord_length
-
-@table @asis
-@item @emph{Description}:
-@code{_gfortran_set_max_subrecord_length} set the maximum length
-for a subrecord. This option only makes sense for testing and
-debugging of unformatted I/O.
-
-@item @emph{Syntax}:
-@code{void _gfortran_set_max_subrecord_length (int val)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{val} @tab the maximum length for a subrecord;
-the maximum permitted value is 2147483639, which is also
-the default.
-@end multitable
-
-@item @emph{Example}:
-@smallexample
-int main (int argc, char *argv[])
-@{
- /* Initialize libgfortran. */
- _gfortran_set_args (argc, argv);
- _gfortran_set_max_subrecord_length (8);
- return 0;
-@}
-@end smallexample
-@end table
-
-
-@node Naming and argument-passing conventions
-@section Naming and argument-passing conventions
-
-This section gives an overview about the naming convention of procedures
-and global variables and about the argument passing conventions used by
-GNU Fortran. If a C binding has been specified, the naming convention
-and some of the argument-passing conventions change. If possible,
-mixed-language and mixed-compiler projects should use the better defined
-C binding for interoperability. See @pxref{Interoperability with C}.
-
-@menu
-* Naming conventions::
-* Argument passing conventions::
-@end menu
-
-
-@node Naming conventions
-@subsection Naming conventions
-
-According the Fortran standard, valid Fortran names consist of a letter
-between @code{A} to @code{Z}, @code{a} to @code{z}, digits @code{0},
-@code{1} to @code{9} and underscores (@code{_}) with the restriction
-that names may only start with a letter. As vendor extension, the
-dollar sign (@code{$}) is additionally permitted with the option
-@option{-fdollar-ok}, but not as first character and only if the
-target system supports it.
-
-By default, the procedure name is the lower-cased Fortran name with an
-appended underscore (@code{_}); using @option{-fno-underscoring} no
-underscore is appended while @code{-fsecond-underscore} appends two
-underscores. Depending on the target system and the calling convention,
-the procedure might be additionally dressed; for instance, on 32bit
-Windows with @code{stdcall}, an at-sign @code{@@} followed by an integer
-number is appended. For the changing the calling convention, see
-@pxref{GNU Fortran Compiler Directives}.
-
-For common blocks, the same convention is used, i.e. by default an
-underscore is appended to the lower-cased Fortran name. Blank commons
-have the name @code{__BLNK__}.
-
-For procedures and variables declared in the specification space of a
-module, the name is formed by @code{__}, followed by the lower-cased
-module name, @code{_MOD_}, and the lower-cased Fortran name. Note that
-no underscore is appended.
-
-
-@node Argument passing conventions
-@subsection Argument passing conventions
-
-Subroutines do not return a value (matching C99's @code{void}) while
-functions either return a value as specified in the platform ABI or
-the result variable is passed as hidden argument to the function and
-no result is returned. A hidden result variable is used when the
-result variable is an array or of type @code{CHARACTER}.
-
-Arguments are passed according to the platform ABI. In particular,
-complex arguments might not be compatible to a struct with two real
-components for the real and imaginary part. The argument passing
-matches the one of C99's @code{_Complex}. Functions with scalar
-complex result variables return their value and do not use a
-by-reference argument. Note that with the @option{-ff2c} option,
-the argument passing is modified and no longer completely matches
-the platform ABI. Some other Fortran compilers use @code{f2c}
-semantic by default; this might cause problems with
-interoperablility.
-
-GNU Fortran passes most arguments by reference, i.e. by passing a
-pointer to the data. Note that the compiler might use a temporary
-variable into which the actual argument has been copied, if required
-semantically (copy-in/copy-out).
-
-For arguments with @code{ALLOCATABLE} and @code{POINTER}
-attribute (including procedure pointers), a pointer to the pointer
-is passed such that the pointer address can be modified in the
-procedure.
-
-For dummy arguments with the @code{VALUE} attribute: Scalar arguments
-of the type @code{INTEGER}, @code{LOGICAL}, @code{REAL} and
-@code{COMPLEX} are passed by value according to the platform ABI.
-(As vendor extension and not recommended, using @code{%VAL()} in the
-call to a procedure has the same effect.) For @code{TYPE(C_PTR)} and
-procedure pointers, the pointer itself is passed such that it can be
-modified without affecting the caller.
-@c FIXME: Document how VALUE is handled for CHARACTER, TYPE,
-@c CLASS and arrays, i.e. whether the copy-in is done in the caller
-@c or in the callee.
-
-For Boolean (@code{LOGICAL}) arguments, please note that GCC expects
-only the integer value 0 and 1. If a GNU Fortran @code{LOGICAL}
-variable contains another integer value, the result is undefined.
-As some other Fortran compilers use @math{-1} for @code{.TRUE.},
-extra care has to be taken -- such as passing the value as
-@code{INTEGER}. (The same value restriction also applies to other
-front ends of GCC, e.g. to GCC's C99 compiler for @code{_Bool}
-or GCC's Ada compiler for @code{Boolean}.)
-
-For arguments of @code{CHARACTER} type, the character length is passed
-as a hidden argument at the end of the argument list. For
-deferred-length strings, the value is passed by reference, otherwise
-by value. The character length has the C type @code{size_t} (or
-@code{INTEGER(kind=C_SIZE_T)} in Fortran). Note that this is
-different to older versions of the GNU Fortran compiler, where the
-type of the hidden character length argument was a C @code{int}. In
-order to retain compatibility with older versions, one can e.g. for
-the following Fortran procedure
-
-@smallexample
-subroutine fstrlen (s, a)
- character(len=*) :: s
- integer :: a
- print*, len(s)
-end subroutine fstrlen
-@end smallexample
-
-define the corresponding C prototype as follows:
-
-@smallexample
-#if __GNUC__ > 7
-typedef size_t fortran_charlen_t;
-#else
-typedef int fortran_charlen_t;
-#endif
-
-void fstrlen_ (char*, int*, fortran_charlen_t);
-@end smallexample
-
-In order to avoid such compiler-specific details, for new code it is
-instead recommended to use the ISO_C_BINDING feature.
-
-Note with C binding, @code{CHARACTER(len=1)} result variables are
-returned according to the platform ABI and no hidden length argument
-is used for dummy arguments; with @code{VALUE}, those variables are
-passed by value.
-
-For @code{OPTIONAL} dummy arguments, an absent argument is denoted
-by a NULL pointer, except for scalar dummy arguments of type
-@code{INTEGER}, @code{LOGICAL}, @code{REAL} and @code{COMPLEX}
-which have the @code{VALUE} attribute. For those, a hidden Boolean
-argument (@code{logical(kind=C_bool),value}) is used to indicate
-whether the argument is present.
-
-Arguments which are assumed-shape, assumed-rank or deferred-rank
-arrays or, with @option{-fcoarray=lib}, allocatable scalar coarrays use
-an array descriptor. All other arrays pass the address of the
-first element of the array. With @option{-fcoarray=lib}, the token
-and the offset belonging to nonallocatable coarrays dummy arguments
-are passed as hidden argument along the character length hidden
-arguments. The token is an opaque pointer identifying the coarray
-and the offset is a passed-by-value integer of kind @code{C_PTRDIFF_T},
-denoting the byte offset between the base address of the coarray and
-the passed scalar or first element of the passed array.
-
-The arguments are passed in the following order
-@itemize @bullet
-@item Result variable, when the function result is passed by reference
-@item Character length of the function result, if it is a of type
-@code{CHARACTER} and no C binding is used
-@item The arguments in the order in which they appear in the Fortran
-declaration
-@item The present status for optional arguments with value attribute,
-which are internally passed by value
-@item The character length and/or coarray token and offset for the first
-argument which is a @code{CHARACTER} or a nonallocatable coarray dummy
-argument, followed by the hidden arguments of the next dummy argument
-of such a type
-@end itemize
-
-
-@c ---------------------------------------------------------------------
-@c Coarray Programming
-@c ---------------------------------------------------------------------
-
-@node Coarray Programming
-@chapter Coarray Programming
-@cindex Coarrays
-
-@menu
-* Type and enum ABI Documentation::
-* Function ABI Documentation::
-@end menu
-
-
-@node Type and enum ABI Documentation
-@section Type and enum ABI Documentation
-
-@menu
-* caf_token_t::
-* caf_register_t::
-* caf_deregister_t::
-* caf_reference_t::
-* caf_team_t::
-@end menu
-
-@node caf_token_t
-@subsection @code{caf_token_t}
-
-Typedef of type @code{void *} on the compiler side. Can be any data
-type on the library side.
-
-@node caf_register_t
-@subsection @code{caf_register_t}
-
-Indicates which kind of coarray variable should be registered.
-
-@verbatim
-typedef enum caf_register_t {
- CAF_REGTYPE_COARRAY_STATIC,
- CAF_REGTYPE_COARRAY_ALLOC,
- CAF_REGTYPE_LOCK_STATIC,
- CAF_REGTYPE_LOCK_ALLOC,
- CAF_REGTYPE_CRITICAL,
- CAF_REGTYPE_EVENT_STATIC,
- CAF_REGTYPE_EVENT_ALLOC,
- CAF_REGTYPE_COARRAY_ALLOC_REGISTER_ONLY,
- CAF_REGTYPE_COARRAY_ALLOC_ALLOCATE_ONLY
-}
-caf_register_t;
-@end verbatim
-
-The values @code{CAF_REGTYPE_COARRAY_ALLOC_REGISTER_ONLY} and
-@code{CAF_REGTYPE_COARRAY_ALLOC_ALLOCATE_ONLY} are for allocatable components
-in derived type coarrays only. The first one sets up the token without
-allocating memory for allocatable component. The latter one only allocates the
-memory for an allocatable component in a derived type coarray. The token
-needs to be setup previously by the REGISTER_ONLY. This allows to have
-allocatable components un-allocated on some images. The status whether an
-allocatable component is allocated on a remote image can be queried by
-@code{_caf_is_present} which used internally by the @code{ALLOCATED}
-intrinsic.
-
-@node caf_deregister_t
-@subsection @code{caf_deregister_t}
-
-@verbatim
-typedef enum caf_deregister_t {
- CAF_DEREGTYPE_COARRAY_DEREGISTER,
- CAF_DEREGTYPE_COARRAY_DEALLOCATE_ONLY
-}
-caf_deregister_t;
-@end verbatim
-
-Allows to specifiy the type of deregistration of a coarray object. The
-@code{CAF_DEREGTYPE_COARRAY_DEALLOCATE_ONLY} flag is only allowed for
-allocatable components in derived type coarrays.
-
-@node caf_reference_t
-@subsection @code{caf_reference_t}
-
-The structure used for implementing arbitrary reference chains.
-A @code{CAF_REFERENCE_T} allows to specify a component reference or any kind
-of array reference of any rank supported by gfortran. For array references all
-kinds as known by the compiler/Fortran standard are supported indicated by
-a @code{MODE}.
-
-@verbatim
-typedef enum caf_ref_type_t {
- /* Reference a component of a derived type, either regular one or an
- allocatable or pointer type. For regular ones idx in caf_reference_t is
- set to -1. */
- CAF_REF_COMPONENT,
- /* Reference an allocatable array. */
- CAF_REF_ARRAY,
- /* Reference a non-allocatable/non-pointer array. I.e., the coarray object
- has no array descriptor associated and the addressing is done
- completely using the ref. */
- CAF_REF_STATIC_ARRAY
-} caf_ref_type_t;
-@end verbatim
-
-@verbatim
-typedef enum caf_array_ref_t {
- /* No array ref. This terminates the array ref. */
- CAF_ARR_REF_NONE = 0,
- /* Reference array elements given by a vector. Only for this mode
- caf_reference_t.u.a.dim[i].v is valid. */
- CAF_ARR_REF_VECTOR,
- /* A full array ref (:). */
- CAF_ARR_REF_FULL,
- /* Reference a range on elements given by start, end and stride. */
- CAF_ARR_REF_RANGE,
- /* Only a single item is referenced given in the start member. */
- CAF_ARR_REF_SINGLE,
- /* An array ref of the kind (i:), where i is an arbitrary valid index in the
- array. The index i is given in the start member. */
- CAF_ARR_REF_OPEN_END,
- /* An array ref of the kind (:i), where the lower bound of the array ref
- is given by the remote side. The index i is given in the end member. */
- CAF_ARR_REF_OPEN_START
-} caf_array_ref_t;
-@end verbatim
-
-@verbatim
-/* References to remote components of a derived type. */
-typedef struct caf_reference_t {
- /* A pointer to the next ref or NULL. */
- struct caf_reference_t *next;
- /* The type of the reference. */
- /* caf_ref_type_t, replaced by int to allow specification in fortran FE. */
- int type;
- /* The size of an item referenced in bytes. I.e. in an array ref this is
- the factor to advance the array pointer with to get to the next item.
- For component refs this gives just the size of the element referenced. */
- size_t item_size;
- union {
- struct {
- /* The offset (in bytes) of the component in the derived type.
- Unused for allocatable or pointer components. */
- ptrdiff_t offset;
- /* The offset (in bytes) to the caf_token associated with this
- component. NULL, when not allocatable/pointer ref. */
- ptrdiff_t caf_token_offset;
- } c;
- struct {
- /* The mode of the array ref. See CAF_ARR_REF_*. */
- /* caf_array_ref_t, replaced by unsigend char to allow specification in
- fortran FE. */
- unsigned char mode[GFC_MAX_DIMENSIONS];
- /* The type of a static array. Unset for array's with descriptors. */
- int static_array_type;
- /* Subscript refs (s) or vector refs (v). */
- union {
- struct {
- /* The start and end boundary of the ref and the stride. */
- index_type start, end, stride;
- } s;
- struct {
- /* nvec entries of kind giving the elements to reference. */
- void *vector;
- /* The number of entries in vector. */
- size_t nvec;
- /* The integer kind used for the elements in vector. */
- int kind;
- } v;
- } dim[GFC_MAX_DIMENSIONS];
- } a;
- } u;
-} caf_reference_t;
-@end verbatim
-
-The references make up a single linked list of reference operations. The
-@code{NEXT} member links to the next reference or NULL to indicate the end of
-the chain. Component and array refs can be arbitrarily mixed as long as they
-comply to the Fortran standard.
-
-@emph{NOTES}
-The member @code{STATIC_ARRAY_TYPE} is used only when the @code{TYPE} is
-@code{CAF_REF_STATIC_ARRAY}. The member gives the type of the data referenced.
-Because no array descriptor is available for a descriptor-less array and
-type conversion still needs to take place the type is transported here.
-
-At the moment @code{CAF_ARR_REF_VECTOR} is not implemented in the front end for
-descriptor-less arrays. The library caf_single has untested support for it.
-
-@node caf_team_t
-@subsection @code{caf_team_t}
-
-Opaque pointer to represent a team-handle. This type is a stand-in for the
-future implementation of teams. It is about to change without further notice.
-
-@node Function ABI Documentation
-@section Function ABI Documentation
-
-@menu
-* _gfortran_caf_init:: Initialiation function
-* _gfortran_caf_finish:: Finalization function
-* _gfortran_caf_this_image:: Querying the image number
-* _gfortran_caf_num_images:: Querying the maximal number of images
-* _gfortran_caf_image_status :: Query the status of an image
-* _gfortran_caf_failed_images :: Get an array of the indexes of the failed images
-* _gfortran_caf_stopped_images :: Get an array of the indexes of the stopped images
-* _gfortran_caf_register:: Registering coarrays
-* _gfortran_caf_deregister:: Deregistering coarrays
-* _gfortran_caf_is_present:: Query whether an allocatable or pointer component in a derived type coarray is allocated
-* _gfortran_caf_send:: Sending data from a local image to a remote image
-* _gfortran_caf_get:: Getting data from a remote image
-* _gfortran_caf_sendget:: Sending data between remote images
-* _gfortran_caf_send_by_ref:: Sending data from a local image to a remote image using enhanced references
-* _gfortran_caf_get_by_ref:: Getting data from a remote image using enhanced references
-* _gfortran_caf_sendget_by_ref:: Sending data between remote images using enhanced references
-* _gfortran_caf_lock:: Locking a lock variable
-* _gfortran_caf_unlock:: Unlocking a lock variable
-* _gfortran_caf_event_post:: Post an event
-* _gfortran_caf_event_wait:: Wait that an event occurred
-* _gfortran_caf_event_query:: Query event count
-* _gfortran_caf_sync_all:: All-image barrier
-* _gfortran_caf_sync_images:: Barrier for selected images
-* _gfortran_caf_sync_memory:: Wait for completion of segment-memory operations
-* _gfortran_caf_error_stop:: Error termination with exit code
-* _gfortran_caf_error_stop_str:: Error termination with string
-* _gfortran_caf_fail_image :: Mark the image failed and end its execution
-* _gfortran_caf_atomic_define:: Atomic variable assignment
-* _gfortran_caf_atomic_ref:: Atomic variable reference
-* _gfortran_caf_atomic_cas:: Atomic compare and swap
-* _gfortran_caf_atomic_op:: Atomic operation
-* _gfortran_caf_co_broadcast:: Sending data to all images
-* _gfortran_caf_co_max:: Collective maximum reduction
-* _gfortran_caf_co_min:: Collective minimum reduction
-* _gfortran_caf_co_sum:: Collective summing reduction
-* _gfortran_caf_co_reduce:: Generic collective reduction
-@end menu
-
-
-@node _gfortran_caf_init
-@subsection @code{_gfortran_caf_init} --- Initialiation function
-@cindex Coarray, _gfortran_caf_init
-
-@table @asis
-@item @emph{Description}:
-This function is called at startup of the program before the Fortran main
-program, if the latter has been compiled with @option{-fcoarray=lib}.
-It takes as arguments the command-line arguments of the program. It is
-permitted to pass two @code{NULL} pointers as argument; if non-@code{NULL},
-the library is permitted to modify the arguments.
-
-@item @emph{Syntax}:
-@code{void _gfortran_caf_init (int *argc, char ***argv)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{argc} @tab intent(inout) An integer pointer with the number of
-arguments passed to the program or @code{NULL}.
-@item @var{argv} @tab intent(inout) A pointer to an array of strings with the
-command-line arguments or @code{NULL}.
-@end multitable
-
-@item @emph{NOTES}
-The function is modelled after the initialization function of the Message
-Passing Interface (MPI) specification. Due to the way coarray registration
-works, it might not be the first call to the library. If the main program is
-not written in Fortran and only a library uses coarrays, it can happen that
-this function is never called. Therefore, it is recommended that the library
-does not rely on the passed arguments and whether the call has been done.
-@end table
-
-
-@node _gfortran_caf_finish
-@subsection @code{_gfortran_caf_finish} --- Finalization function
-@cindex Coarray, _gfortran_caf_finish
-
-@table @asis
-@item @emph{Description}:
-This function is called at the end of the Fortran main program, if it has
-been compiled with the @option{-fcoarray=lib} option.
-
-@item @emph{Syntax}:
-@code{void _gfortran_caf_finish (void)}
-
-@item @emph{NOTES}
-For non-Fortran programs, it is recommended to call the function at the end
-of the main program. To ensure that the shutdown is also performed for
-programs where this function is not explicitly invoked, for instance
-non-Fortran programs or calls to the system's exit() function, the library
-can use a destructor function. Note that programs can also be terminated
-using the STOP and ERROR STOP statements; those use different library calls.
-@end table
-
-
-@node _gfortran_caf_this_image
-@subsection @code{_gfortran_caf_this_image} --- Querying the image number
-@cindex Coarray, _gfortran_caf_this_image
-
-@table @asis
-@item @emph{Description}:
-This function returns the current image number, which is a positive number.
-
-@item @emph{Syntax}:
-@code{int _gfortran_caf_this_image (int distance)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{distance} @tab As specified for the @code{this_image} intrinsic
-in TS18508. Shall be a non-negative number.
-@end multitable
-
-@item @emph{NOTES}
-If the Fortran intrinsic @code{this_image} is invoked without an argument, which
-is the only permitted form in Fortran 2008, GCC passes @code{0} as
-first argument.
-@end table
-
-
-@node _gfortran_caf_num_images
-@subsection @code{_gfortran_caf_num_images} --- Querying the maximal number of images
-@cindex Coarray, _gfortran_caf_num_images
-
-@table @asis
-@item @emph{Description}:
-This function returns the number of images in the current team, if
-@var{distance} is 0 or the number of images in the parent team at the specified
-distance. If failed is -1, the function returns the number of all images at
-the specified distance; if it is 0, the function returns the number of
-nonfailed images, and if it is 1, it returns the number of failed images.
-
-@item @emph{Syntax}:
-@code{int _gfortran_caf_num_images(int distance, int failed)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{distance} @tab the distance from this image to the ancestor.
-Shall be positive.
-@item @var{failed} @tab shall be -1, 0, or 1
-@end multitable
-
-@item @emph{NOTES}
-This function follows TS18508. If the num_image intrinsic has no arguments,
-then the compiler passes @code{distance=0} and @code{failed=-1} to the function.
-@end table
-
-
-@node _gfortran_caf_image_status
-@subsection @code{_gfortran_caf_image_status} --- Query the status of an image
-@cindex Coarray, _gfortran_caf_image_status
-
-@table @asis
-@item @emph{Description}:
-Get the status of the image given by the id @var{image} of the team given by
-@var{team}. Valid results are zero, for image is ok, @code{STAT_STOPPED_IMAGE}
-from the ISO_FORTRAN_ENV module to indicate that the image has been stopped and
-@code{STAT_FAILED_IMAGE} also from ISO_FORTRAN_ENV to indicate that the image
-has executed a @code{FAIL IMAGE} statement.
-
-@item @emph{Syntax}:
-@code{int _gfortran_caf_image_status (int image, caf_team_t * team)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{image} @tab the positive scalar id of the image in the current TEAM.
-@item @var{team} @tab optional; team on the which the inquiry is to be
-performed.
-@end multitable
-
-@item @emph{NOTES}
-This function follows TS18508. Because team-functionality is not yet
-implemented a null-pointer is passed for the @var{team} argument at the moment.
-@end table
-
-
-@node _gfortran_caf_failed_images
-@subsection @code{_gfortran_caf_failed_images} --- Get an array of the indexes of the failed images
-@cindex Coarray, _gfortran_caf_failed_images
-
-@table @asis
-@item @emph{Description}:
-Get an array of image indexes in the current @var{team} that have failed. The
-array is sorted ascendingly. When @var{team} is not provided the current team
-is to be used. When @var{kind} is provided then the resulting array is of that
-integer kind else it is of default integer kind. The returns an unallocated
-size zero array when no images have failed.
-
-@item @emph{Syntax}:
-@code{int _gfortran_caf_failed_images (caf_team_t * team, int * kind)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{team} @tab optional; team on the which the inquiry is to be
-performed.
-@item @var{image} @tab optional; the kind of the resulting integer array.
-@end multitable
-
-@item @emph{NOTES}
-This function follows TS18508. Because team-functionality is not yet
-implemented a null-pointer is passed for the @var{team} argument at the moment.
-@end table
-
-
-@node _gfortran_caf_stopped_images
-@subsection @code{_gfortran_caf_stopped_images} --- Get an array of the indexes of the stopped images
-@cindex Coarray, _gfortran_caf_stopped_images
-
-@table @asis
-@item @emph{Description}:
-Get an array of image indexes in the current @var{team} that have stopped. The
-array is sorted ascendingly. When @var{team} is not provided the current team
-is to be used. When @var{kind} is provided then the resulting array is of that
-integer kind else it is of default integer kind. The returns an unallocated
-size zero array when no images have failed.
-
-@item @emph{Syntax}:
-@code{int _gfortran_caf_stopped_images (caf_team_t * team, int * kind)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{team} @tab optional; team on the which the inquiry is to be
-performed.
-@item @var{image} @tab optional; the kind of the resulting integer array.
-@end multitable
-
-@item @emph{NOTES}
-This function follows TS18508. Because team-functionality is not yet
-implemented a null-pointer is passed for the @var{team} argument at the moment.
-@end table
-
-
-@node _gfortran_caf_register
-@subsection @code{_gfortran_caf_register} --- Registering coarrays
-@cindex Coarray, _gfortran_caf_register
-
-@table @asis
-@item @emph{Description}:
-Registers memory for a coarray and creates a token to identify the coarray. The
-routine is called for both coarrays with @code{SAVE} attribute and using an
-explicit @code{ALLOCATE} statement. If an error occurs and @var{STAT} is a
-@code{NULL} pointer, the function shall abort with printing an error message
-and starting the error termination. If no error occurs and @var{STAT} is
-present, it shall be set to zero. Otherwise, it shall be set to a positive
-value and, if not-@code{NULL}, @var{ERRMSG} shall be set to a string describing
-the failure. The routine shall register the memory provided in the
-@code{DATA}-component of the array descriptor @var{DESC}, when that component
-is non-@code{NULL}, else it shall allocate sufficient memory and provide a
-pointer to it in the @code{DATA}-component of @var{DESC}. The array descriptor
-has rank zero, when a scalar object is to be registered and the array
-descriptor may be invalid after the call to @code{_gfortran_caf_register}.
-When an array is to be allocated the descriptor persists.
-
-For @code{CAF_REGTYPE_COARRAY_STATIC} and @code{CAF_REGTYPE_COARRAY_ALLOC},
-the passed size is the byte size requested. For @code{CAF_REGTYPE_LOCK_STATIC},
-@code{CAF_REGTYPE_LOCK_ALLOC} and @code{CAF_REGTYPE_CRITICAL} it is the array
-size or one for a scalar.
-
-When @code{CAF_REGTYPE_COARRAY_ALLOC_REGISTER_ONLY} is used, then only a token
-for an allocatable or pointer component is created. The @code{SIZE} parameter
-is not used then. On the contrary when
-@code{CAF_REGTYPE_COARRAY_ALLOC_ALLOCATE_ONLY} is specified, then the
-@var{token} needs to be registered by a previous call with regtype
-@code{CAF_REGTYPE_COARRAY_ALLOC_REGISTER_ONLY} and either the memory specified
-in the @var{DESC}'s data-ptr is registered or allocate when the data-ptr is
-@code{NULL}.
-
-@item @emph{Syntax}:
-@code{void caf_register (size_t size, caf_register_t type, caf_token_t *token,
-gfc_descriptor_t *desc, int *stat, char *errmsg, size_t errmsg_len)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{size} @tab For normal coarrays, the byte size of the coarray to be
-allocated; for lock types and event types, the number of elements.
-@item @var{type} @tab one of the caf_register_t types.
-@item @var{token} @tab intent(out) An opaque pointer identifying the coarray.
-@item @var{desc} @tab intent(inout) The (pseudo) array descriptor.
-@item @var{stat} @tab intent(out) For allocatable coarrays, stores the STAT=;
-may be @code{NULL}
-@item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
-an error message; may be @code{NULL}
-@item @var{errmsg_len} @tab the buffer size of errmsg.
-@end multitable
-
-@item @emph{NOTES}
-Nonallocatable coarrays have to be registered prior use from remote images.
-In order to guarantee this, they have to be registered before the main
-program. This can be achieved by creating constructor functions. That is what
-GCC does such that also for nonallocatable coarrays the memory is allocated and
-no static memory is used. The token permits to identify the coarray; to the
-processor, the token is a nonaliasing pointer. The library can, for instance,
-store the base address of the coarray in the token, some handle or a more
-complicated struct. The library may also store the array descriptor
-@var{DESC} when its rank is non-zero.
-
-For lock types, the value shall only be used for checking the allocation
-status. Note that for critical blocks, the locking is only required on one
-image; in the locking statement, the processor shall always pass an
-image index of one for critical-block lock variables
-(@code{CAF_REGTYPE_CRITICAL}). For lock types and critical-block variables,
-the initial value shall be unlocked (or, respectively, not in critical
-section) such as the value false; for event types, the initial state should
-be no event, e.g. zero.
-@end table
-
-
-@node _gfortran_caf_deregister
-@subsection @code{_gfortran_caf_deregister} --- Deregistering coarrays
-@cindex Coarray, _gfortran_caf_deregister
-
-@table @asis
-@item @emph{Description}:
-Called to free or deregister the memory of a coarray; the processor calls this
-function for automatic and explicit deallocation. In case of an error, this
-function shall fail with an error message, unless the @var{STAT} variable is
-not null. The library is only expected to free memory it allocated itself
-during a call to @code{_gfortran_caf_register}.
-
-@item @emph{Syntax}:
-@code{void caf_deregister (caf_token_t *token, caf_deregister_t type,
-int *stat, char *errmsg, size_t errmsg_len)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{token} @tab the token to free.
-@item @var{type} @tab the type of action to take for the coarray. A
-@code{CAF_DEREGTYPE_COARRAY_DEALLOCATE_ONLY} is allowed only for allocatable or
-pointer components of derived type coarrays. The action only deallocates the
-local memory without deleting the token.
-@item @var{stat} @tab intent(out) Stores the STAT=; may be NULL
-@item @var{errmsg} @tab intent(out) When an error occurs, this will be set
-to an error message; may be NULL
-@item @var{errmsg_len} @tab the buffer size of errmsg.
-@end multitable
-
-@item @emph{NOTES}
-For nonalloatable coarrays this function is never called. If a cleanup is
-required, it has to be handled via the finish, stop and error stop functions,
-and via destructors.
-@end table
-
-
-@node _gfortran_caf_is_present
-@subsection @code{_gfortran_caf_is_present} --- Query whether an allocatable or pointer component in a derived type coarray is allocated
-@cindex Coarray, _gfortran_caf_is_present
-
-@table @asis
-@item @emph{Description}:
-Used to query the coarray library whether an allocatable component in a derived
-type coarray is allocated on a remote image.
-
-@item @emph{Syntax}:
-@code{void _gfortran_caf_is_present (caf_token_t token, int image_index,
-gfc_reference_t *ref)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{token} @tab An opaque pointer identifying the coarray.
-@item @var{image_index} @tab The ID of the remote image; must be a positive
-number.
-@item @var{ref} @tab A chain of references to address the allocatable or
-pointer component in the derived type coarray. The object reference needs to be
-a scalar or a full array reference, respectively.
-@end multitable
-
-@end table
-
-@node _gfortran_caf_send
-@subsection @code{_gfortran_caf_send} --- Sending data from a local image to a remote image
-@cindex Coarray, _gfortran_caf_send
-
-@table @asis
-@item @emph{Description}:
-Called to send a scalar, an array section or a whole array from a local
-to a remote image identified by the image_index.
-
-@item @emph{Syntax}:
-@code{void _gfortran_caf_send (caf_token_t token, size_t offset,
-int image_index, gfc_descriptor_t *dest, caf_vector_t *dst_vector,
-gfc_descriptor_t *src, int dst_kind, int src_kind, bool may_require_tmp,
-int *stat)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
-@item @var{offset} @tab intent(in) By which amount of bytes the actual data is
-shifted compared to the base address of the coarray.
-@item @var{image_index} @tab intent(in) The ID of the remote image; must be a
-positive number.
-@item @var{dest} @tab intent(in) Array descriptor for the remote image for the
-bounds and the size. The @code{base_addr} shall not be accessed.
-@item @var{dst_vector} @tab intent(in) If not NULL, it contains the vector
-subscript of the destination array; the values are relative to the dimension
-triplet of the dest argument.
-@item @var{src} @tab intent(in) Array descriptor of the local array to be
-transferred to the remote image
-@item @var{dst_kind} @tab intent(in) Kind of the destination argument
-@item @var{src_kind} @tab intent(in) Kind of the source argument
-@item @var{may_require_tmp} @tab intent(in) The variable is @code{false} when
-it is known at compile time that the @var{dest} and @var{src} either cannot
-overlap or overlap (fully or partially) such that walking @var{src} and
-@var{dest} in element wise element order (honoring the stride value) will not
-lead to wrong results. Otherwise, the value is @code{true}.
-@item @var{stat} @tab intent(out) when non-NULL give the result of the
-operation, i.e., zero on success and non-zero on error. When NULL and an error
-occurs, then an error message is printed and the program is terminated.
-@end multitable
-
-@item @emph{NOTES}
-It is permitted to have @var{image_index} equal the current image; the memory
-of the send-to and the send-from might (partially) overlap in that case. The
-implementation has to take care that it handles this case, e.g. using
-@code{memmove} which handles (partially) overlapping memory. If
-@var{may_require_tmp} is true, the library might additionally create a
-temporary variable, unless additional checks show that this is not required
-(e.g. because walking backward is possible or because both arrays are
-contiguous and @code{memmove} takes care of overlap issues).
-
-Note that the assignment of a scalar to an array is permitted. In addition,
-the library has to handle numeric-type conversion and for strings, padding
-and different character kinds.
-@end table
-
-
-@node _gfortran_caf_get
-@subsection @code{_gfortran_caf_get} --- Getting data from a remote image
-@cindex Coarray, _gfortran_caf_get
-
-@table @asis
-@item @emph{Description}:
-Called to get an array section or a whole array from a remote,
-image identified by the image_index.
-
-@item @emph{Syntax}:
-@code{void _gfortran_caf_get (caf_token_t token, size_t offset,
-int image_index, gfc_descriptor_t *src, caf_vector_t *src_vector,
-gfc_descriptor_t *dest, int src_kind, int dst_kind, bool may_require_tmp,
-int *stat)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
-@item @var{offset} @tab intent(in) By which amount of bytes the actual data is
-shifted compared to the base address of the coarray.
-@item @var{image_index} @tab intent(in) The ID of the remote image; must be a
-positive number.
-@item @var{dest} @tab intent(out) Array descriptor of the local array to store
-the data retrieved from the remote image
-@item @var{src} @tab intent(in) Array descriptor for the remote image for the
-bounds and the size. The @code{base_addr} shall not be accessed.
-@item @var{src_vector} @tab intent(in) If not NULL, it contains the vector
-subscript of the source array; the values are relative to the dimension
-triplet of the @var{src} argument.
-@item @var{dst_kind} @tab intent(in) Kind of the destination argument
-@item @var{src_kind} @tab intent(in) Kind of the source argument
-@item @var{may_require_tmp} @tab intent(in) The variable is @code{false} when
-it is known at compile time that the @var{dest} and @var{src} either cannot
-overlap or overlap (fully or partially) such that walking @var{src} and
-@var{dest} in element wise element order (honoring the stride value) will not
-lead to wrong results. Otherwise, the value is @code{true}.
-@item @var{stat} @tab intent(out) When non-NULL give the result of the
-operation, i.e., zero on success and non-zero on error. When NULL and an error
-occurs, then an error message is printed and the program is terminated.
-@end multitable
-
-@item @emph{NOTES}
-It is permitted to have @var{image_index} equal the current image; the memory of
-the send-to and the send-from might (partially) overlap in that case. The
-implementation has to take care that it handles this case, e.g. using
-@code{memmove} which handles (partially) overlapping memory. If
-@var{may_require_tmp} is true, the library might additionally create a
-temporary variable, unless additional checks show that this is not required
-(e.g. because walking backward is possible or because both arrays are
-contiguous and @code{memmove} takes care of overlap issues).
-
-Note that the library has to handle numeric-type conversion and for strings,
-padding and different character kinds.
-@end table
-
-
-@node _gfortran_caf_sendget
-@subsection @code{_gfortran_caf_sendget} --- Sending data between remote images
-@cindex Coarray, _gfortran_caf_sendget
-
-@table @asis
-@item @emph{Description}:
-Called to send a scalar, an array section or a whole array from a remote image
-identified by the @var{src_image_index} to a remote image identified by the
-@var{dst_image_index}.
-
-@item @emph{Syntax}:
-@code{void _gfortran_caf_sendget (caf_token_t dst_token, size_t dst_offset,
-int dst_image_index, gfc_descriptor_t *dest, caf_vector_t *dst_vector,
-caf_token_t src_token, size_t src_offset, int src_image_index,
-gfc_descriptor_t *src, caf_vector_t *src_vector, int dst_kind, int src_kind,
-bool may_require_tmp, int *stat)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{dst_token} @tab intent(in) An opaque pointer identifying the
-destination coarray.
-@item @var{dst_offset} @tab intent(in) By which amount of bytes the actual data
-is shifted compared to the base address of the destination coarray.
-@item @var{dst_image_index} @tab intent(in) The ID of the destination remote
-image; must be a positive number.
-@item @var{dest} @tab intent(in) Array descriptor for the destination
-remote image for the bounds and the size. The @code{base_addr} shall not be
-accessed.
-@item @var{dst_vector} @tab intent(int) If not NULL, it contains the vector
-subscript of the destination array; the values are relative to the dimension
-triplet of the @var{dest} argument.
-@item @var{src_token} @tab intent(in) An opaque pointer identifying the source
-coarray.
-@item @var{src_offset} @tab intent(in) By which amount of bytes the actual data
-is shifted compared to the base address of the source coarray.
-@item @var{src_image_index} @tab intent(in) The ID of the source remote image;
-must be a positive number.
-@item @var{src} @tab intent(in) Array descriptor of the local array to be
-transferred to the remote image.
-@item @var{src_vector} @tab intent(in) Array descriptor of the local array to
-be transferred to the remote image
-@item @var{dst_kind} @tab intent(in) Kind of the destination argument
-@item @var{src_kind} @tab intent(in) Kind of the source argument
-@item @var{may_require_tmp} @tab intent(in) The variable is @code{false} when
-it is known at compile time that the @var{dest} and @var{src} either cannot
-overlap or overlap (fully or partially) such that walking @var{src} and
-@var{dest} in element wise element order (honoring the stride value) will not
-lead to wrong results. Otherwise, the value is @code{true}.
-@item @var{stat} @tab intent(out) when non-NULL give the result of the
-operation, i.e., zero on success and non-zero on error. When NULL and an error
-occurs, then an error message is printed and the program is terminated.
-@end multitable
-
-@item @emph{NOTES}
-It is permitted to have the same image index for both @var{src_image_index} and
-@var{dst_image_index}; the memory of the send-to and the send-from might
-(partially) overlap in that case. The implementation has to take care that it
-handles this case, e.g. using @code{memmove} which handles (partially)
-overlapping memory. If @var{may_require_tmp} is true, the library
-might additionally create a temporary variable, unless additional checks show
-that this is not required (e.g. because walking backward is possible or because
-both arrays are contiguous and @code{memmove} takes care of overlap issues).
-
-Note that the assignment of a scalar to an array is permitted. In addition,
-the library has to handle numeric-type conversion and for strings, padding and
-different character kinds.
-@end table
-
-@node _gfortran_caf_send_by_ref
-@subsection @code{_gfortran_caf_send_by_ref} --- Sending data from a local image to a remote image with enhanced referencing options
-@cindex Coarray, _gfortran_caf_send_by_ref
-
-@table @asis
-@item @emph{Description}:
-Called to send a scalar, an array section or a whole array from a local to a
-remote image identified by the @var{image_index}.
-
-@item @emph{Syntax}:
-@code{void _gfortran_caf_send_by_ref (caf_token_t token, int image_index,
-gfc_descriptor_t *src, caf_reference_t *refs, int dst_kind, int src_kind,
-bool may_require_tmp, bool dst_reallocatable, int *stat, int dst_type)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
-@item @var{image_index} @tab intent(in) The ID of the remote image; must be a
-positive number.
-@item @var{src} @tab intent(in) Array descriptor of the local array to be
-transferred to the remote image
-@item @var{refs} @tab intent(in) The references on the remote array to store
-the data given by src. Guaranteed to have at least one entry.
-@item @var{dst_kind} @tab intent(in) Kind of the destination argument
-@item @var{src_kind} @tab intent(in) Kind of the source argument
-@item @var{may_require_tmp} @tab intent(in) The variable is @code{false} when
-it is known at compile time that the @var{dest} and @var{src} either cannot
-overlap or overlap (fully or partially) such that walking @var{src} and
-@var{dest} in element wise element order (honoring the stride value) will not
-lead to wrong results. Otherwise, the value is @code{true}.
-@item @var{dst_reallocatable} @tab intent(in) Set when the destination is of
-allocatable or pointer type and the refs will allow reallocation, i.e., the ref
-is a full array or component ref.
-@item @var{stat} @tab intent(out) When non-@code{NULL} give the result of the
-operation, i.e., zero on success and non-zero on error. When @code{NULL} and
-an error occurs, then an error message is printed and the program is terminated.
-@item @var{dst_type} @tab intent(in) Give the type of the destination. When
-the destination is not an array, than the precise type, e.g. of a component in
-a derived type, is not known, but provided here.
-@end multitable
-
-@item @emph{NOTES}
-It is permitted to have @var{image_index} equal the current image; the memory of
-the send-to and the send-from might (partially) overlap in that case. The
-implementation has to take care that it handles this case, e.g. using
-@code{memmove} which handles (partially) overlapping memory. If
-@var{may_require_tmp} is true, the library might additionally create a
-temporary variable, unless additional checks show that this is not required
-(e.g. because walking backward is possible or because both arrays are
-contiguous and @code{memmove} takes care of overlap issues).
-
-Note that the assignment of a scalar to an array is permitted. In addition,
-the library has to handle numeric-type conversion and for strings, padding
-and different character kinds.
-
-Because of the more complicated references possible some operations may be
-unsupported by certain libraries. The library is expected to issue a precise
-error message why the operation is not permitted.
-@end table
-
-
-@node _gfortran_caf_get_by_ref
-@subsection @code{_gfortran_caf_get_by_ref} --- Getting data from a remote image using enhanced references
-@cindex Coarray, _gfortran_caf_get_by_ref
-
-@table @asis
-@item @emph{Description}:
-Called to get a scalar, an array section or a whole array from a remote image
-identified by the @var{image_index}.
-
-@item @emph{Syntax}:
-@code{void _gfortran_caf_get_by_ref (caf_token_t token, int image_index,
-caf_reference_t *refs, gfc_descriptor_t *dst, int dst_kind, int src_kind,
-bool may_require_tmp, bool dst_reallocatable, int *stat, int src_type)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
-@item @var{image_index} @tab intent(in) The ID of the remote image; must be a
-positive number.
-@item @var{refs} @tab intent(in) The references to apply to the remote structure
-to get the data.
-@item @var{dst} @tab intent(in) Array descriptor of the local array to store
-the data transferred from the remote image. May be reallocated where needed
-and when @var{DST_REALLOCATABLE} allows it.
-@item @var{dst_kind} @tab intent(in) Kind of the destination argument
-@item @var{src_kind} @tab intent(in) Kind of the source argument
-@item @var{may_require_tmp} @tab intent(in) The variable is @code{false} when
-it is known at compile time that the @var{dest} and @var{src} either cannot
-overlap or overlap (fully or partially) such that walking @var{src} and
-@var{dest} in element wise element order (honoring the stride value) will not
-lead to wrong results. Otherwise, the value is @code{true}.
-@item @var{dst_reallocatable} @tab intent(in) Set when @var{DST} is of
-allocatable or pointer type and its refs allow reallocation, i.e., the full
-array or a component is referenced.
-@item @var{stat} @tab intent(out) When non-@code{NULL} give the result of the
-operation, i.e., zero on success and non-zero on error. When @code{NULL} and an
-error occurs, then an error message is printed and the program is terminated.
-@item @var{src_type} @tab intent(in) Give the type of the source. When the
-source is not an array, than the precise type, e.g. of a component in a
-derived type, is not known, but provided here.
-@end multitable
-
-@item @emph{NOTES}
-It is permitted to have @code{image_index} equal the current image; the memory
-of the send-to and the send-from might (partially) overlap in that case. The
-implementation has to take care that it handles this case, e.g. using
-@code{memmove} which handles (partially) overlapping memory. If
-@var{may_require_tmp} is true, the library might additionally create a
-temporary variable, unless additional checks show that this is not required
-(e.g. because walking backward is possible or because both arrays are
-contiguous and @code{memmove} takes care of overlap issues).
-
-Note that the library has to handle numeric-type conversion and for strings,
-padding and different character kinds.
-
-Because of the more complicated references possible some operations may be
-unsupported by certain libraries. The library is expected to issue a precise
-error message why the operation is not permitted.
-@end table
-
-
-@node _gfortran_caf_sendget_by_ref
-@subsection @code{_gfortran_caf_sendget_by_ref} --- Sending data between remote images using enhanced references on both sides
-@cindex Coarray, _gfortran_caf_sendget_by_ref
-
-@table @asis
-@item @emph{Description}:
-Called to send a scalar, an array section or a whole array from a remote image
-identified by the @var{src_image_index} to a remote image identified by the
-@var{dst_image_index}.
-
-@item @emph{Syntax}:
-@code{void _gfortran_caf_sendget_by_ref (caf_token_t dst_token,
-int dst_image_index, caf_reference_t *dst_refs,
-caf_token_t src_token, int src_image_index, caf_reference_t *src_refs,
-int dst_kind, int src_kind, bool may_require_tmp, int *dst_stat,
-int *src_stat, int dst_type, int src_type)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{dst_token} @tab intent(in) An opaque pointer identifying the
-destination coarray.
-@item @var{dst_image_index} @tab intent(in) The ID of the destination remote
-image; must be a positive number.
-@item @var{dst_refs} @tab intent(in) The references on the remote array to store
-the data given by the source. Guaranteed to have at least one entry.
-@item @var{src_token} @tab intent(in) An opaque pointer identifying the source
-coarray.
-@item @var{src_image_index} @tab intent(in) The ID of the source remote image;
-must be a positive number.
-@item @var{src_refs} @tab intent(in) The references to apply to the remote
-structure to get the data.
-@item @var{dst_kind} @tab intent(in) Kind of the destination argument
-@item @var{src_kind} @tab intent(in) Kind of the source argument
-@item @var{may_require_tmp} @tab intent(in) The variable is @code{false} when
-it is known at compile time that the @var{dest} and @var{src} either cannot
-overlap or overlap (fully or partially) such that walking @var{src} and
-@var{dest} in element wise element order (honoring the stride value) will not
-lead to wrong results. Otherwise, the value is @code{true}.
-@item @var{dst_stat} @tab intent(out) when non-@code{NULL} give the result of
-the send-operation, i.e., zero on success and non-zero on error. When
-@code{NULL} and an error occurs, then an error message is printed and the
-program is terminated.
-@item @var{src_stat} @tab intent(out) When non-@code{NULL} give the result of
-the get-operation, i.e., zero on success and non-zero on error. When
-@code{NULL} and an error occurs, then an error message is printed and the
-program is terminated.
-@item @var{dst_type} @tab intent(in) Give the type of the destination. When
-the destination is not an array, than the precise type, e.g. of a component in
-a derived type, is not known, but provided here.
-@item @var{src_type} @tab intent(in) Give the type of the source. When the
-source is not an array, than the precise type, e.g. of a component in a
-derived type, is not known, but provided here.
-@end multitable
-
-@item @emph{NOTES}
-It is permitted to have the same image index for both @var{src_image_index} and
-@var{dst_image_index}; the memory of the send-to and the send-from might
-(partially) overlap in that case. The implementation has to take care that it
-handles this case, e.g. using @code{memmove} which handles (partially)
-overlapping memory. If @var{may_require_tmp} is true, the library
-might additionally create a temporary variable, unless additional checks show
-that this is not required (e.g. because walking backward is possible or because
-both arrays are contiguous and @code{memmove} takes care of overlap issues).
-
-Note that the assignment of a scalar to an array is permitted. In addition,
-the library has to handle numeric-type conversion and for strings, padding and
-different character kinds.
-
-Because of the more complicated references possible some operations may be
-unsupported by certain libraries. The library is expected to issue a precise
-error message why the operation is not permitted.
-@end table
-
-
-@node _gfortran_caf_lock
-@subsection @code{_gfortran_caf_lock} --- Locking a lock variable
-@cindex Coarray, _gfortran_caf_lock
-
-@table @asis
-@item @emph{Description}:
-Acquire a lock on the given image on a scalar locking variable or for the
-given array element for an array-valued variable. If the @var{acquired_lock}
-is @code{NULL}, the function returns after having obtained the lock. If it is
-non-@code{NULL}, then @var{acquired_lock} is assigned the value true (one) when
-the lock could be obtained and false (zero) otherwise. Locking a lock variable
-which has already been locked by the same image is an error.
-
-@item @emph{Syntax}:
-@code{void _gfortran_caf_lock (caf_token_t token, size_t index, int image_index,
-int *acquired_lock, int *stat, char *errmsg, size_t errmsg_len)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
-@item @var{index} @tab intent(in) Array index; first array index is 0. For
-scalars, it is always 0.
-@item @var{image_index} @tab intent(in) The ID of the remote image; must be a
-positive number.
-@item @var{acquired_lock} @tab intent(out) If not NULL, it returns whether lock
-could be obtained.
-@item @var{stat} @tab intent(out) Stores the STAT=; may be NULL.
-@item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
-an error message; may be NULL.
-@item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
-@end multitable
-
-@item @emph{NOTES}
-This function is also called for critical blocks; for those, the array index
-is always zero and the image index is one. Libraries are permitted to use other
-images for critical-block locking variables.
-@end table
-
-@node _gfortran_caf_unlock
-@subsection @code{_gfortran_caf_lock} --- Unlocking a lock variable
-@cindex Coarray, _gfortran_caf_unlock
-
-@table @asis
-@item @emph{Description}:
-Release a lock on the given image on a scalar locking variable or for the
-given array element for an array-valued variable. Unlocking a lock variable
-which is unlocked or has been locked by a different image is an error.
-
-@item @emph{Syntax}:
-@code{void _gfortran_caf_unlock (caf_token_t token, size_t index, int image_index,
-int *stat, char *errmsg, size_t errmsg_len)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
-@item @var{index} @tab intent(in) Array index; first array index is 0. For
-scalars, it is always 0.
-@item @var{image_index} @tab intent(in) The ID of the remote image; must be a
-positive number.
-@item @var{stat} @tab intent(out) For allocatable coarrays, stores the STAT=;
-may be NULL.
-@item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
-an error message; may be NULL.
-@item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
-@end multitable
-
-@item @emph{NOTES}
-This function is also called for critical block; for those, the array index
-is always zero and the image index is one. Libraries are permitted to use other
-images for critical-block locking variables.
-@end table
-
-@node _gfortran_caf_event_post
-@subsection @code{_gfortran_caf_event_post} --- Post an event
-@cindex Coarray, _gfortran_caf_event_post
-
-@table @asis
-@item @emph{Description}:
-Increment the event count of the specified event variable.
-
-@item @emph{Syntax}:
-@code{void _gfortran_caf_event_post (caf_token_t token, size_t index,
-int image_index, int *stat, char *errmsg, size_t errmsg_len)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
-@item @var{index} @tab intent(in) Array index; first array index is 0. For
-scalars, it is always 0.
-@item @var{image_index} @tab intent(in) The ID of the remote image; must be a
-positive number; zero indicates the current image, when accessed noncoindexed.
-@item @var{stat} @tab intent(out) Stores the STAT=; may be NULL.
-@item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
-an error message; may be NULL.
-@item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
-@end multitable
-
-@item @emph{NOTES}
-This acts like an atomic add of one to the remote image's event variable.
-The statement is an image-control statement but does not imply sync memory.
-Still, all preceeding push communications of this image to the specified
-remote image have to be completed before @code{event_wait} on the remote
-image returns.
-@end table
-
-
-
-@node _gfortran_caf_event_wait
-@subsection @code{_gfortran_caf_event_wait} --- Wait that an event occurred
-@cindex Coarray, _gfortran_caf_event_wait
-
-@table @asis
-@item @emph{Description}:
-Wait until the event count has reached at least the specified
-@var{until_count}; if so, atomically decrement the event variable by this
-amount and return.
-
-@item @emph{Syntax}:
-@code{void _gfortran_caf_event_wait (caf_token_t token, size_t index,
-int until_count, int *stat, char *errmsg, size_t errmsg_len)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
-@item @var{index} @tab intent(in) Array index; first array index is 0. For
-scalars, it is always 0.
-@item @var{until_count} @tab intent(in) The number of events which have to be
-available before the function returns.
-@item @var{stat} @tab intent(out) Stores the STAT=; may be NULL.
-@item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
-an error message; may be NULL.
-@item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
-@end multitable
-
-@item @emph{NOTES}
-This function only operates on a local coarray. It acts like a loop checking
-atomically the value of the event variable, breaking if the value is greater
-or equal the requested number of counts. Before the function returns, the
-event variable has to be decremented by the requested @var{until_count} value.
-A possible implementation would be a busy loop for a certain number of spins
-(possibly depending on the number of threads relative to the number of available
-cores) followed by another waiting strategy such as a sleeping wait (possibly
-with an increasing number of sleep time) or, if possible, a futex wait.
-
-The statement is an image-control statement but does not imply sync memory.
-Still, all preceeding push communications of this image to the specified
-remote image have to be completed before @code{event_wait} on the remote
-image returns.
-@end table
-
-
-
-@node _gfortran_caf_event_query
-@subsection @code{_gfortran_caf_event_query} --- Query event count
-@cindex Coarray, _gfortran_caf_event_query
-
-@table @asis
-@item @emph{Description}:
-Return the event count of the specified event variable.
-
-@item @emph{Syntax}:
-@code{void _gfortran_caf_event_query (caf_token_t token, size_t index,
-int image_index, int *count, int *stat)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
-@item @var{index} @tab intent(in) Array index; first array index is 0. For
-scalars, it is always 0.
-@item @var{image_index} @tab intent(in) The ID of the remote image; must be a
-positive number; zero indicates the current image when accessed noncoindexed.
-@item @var{count} @tab intent(out) The number of events currently posted to
-the event variable.
-@item @var{stat} @tab intent(out) Stores the STAT=; may be NULL.
-@end multitable
-
-@item @emph{NOTES}
-The typical use is to check the local event variable to only call
-@code{event_wait} when the data is available. However, a coindexed variable
-is permitted; there is no ordering or synchronization implied. It acts like
-an atomic fetch of the value of the event variable.
-@end table
-
-
-
-@node _gfortran_caf_sync_all
-@subsection @code{_gfortran_caf_sync_all} --- All-image barrier
-@cindex Coarray, _gfortran_caf_sync_all
-
-@table @asis
-@item @emph{Description}:
-Synchronization of all images in the current team; the program only continues
-on a given image after this function has been called on all images of the
-current team. Additionally, it ensures that all pending data transfers of
-previous segment have completed.
-
-@item @emph{Syntax}:
-@code{void _gfortran_caf_sync_all (int *stat, char *errmsg, size_t errmsg_len)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
-@item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
-an error message; may be NULL.
-@item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
-@end multitable
-@end table
-
-
-
-@node _gfortran_caf_sync_images
-@subsection @code{_gfortran_caf_sync_images} --- Barrier for selected images
-@cindex Coarray, _gfortran_caf_sync_images
-
-@table @asis
-@item @emph{Description}:
-Synchronization between the specified images; the program only continues on a
-given image after this function has been called on all images specified for
-that image. Note that one image can wait for all other images in the current
-team (e.g. via @code{sync images(*)}) while those only wait for that specific
-image. Additionally, @code{sync images} ensures that all pending data
-transfers of previous segments have completed.
-
-@item @emph{Syntax}:
-@code{void _gfortran_caf_sync_images (int count, int images[], int *stat,
-char *errmsg, size_t errmsg_len)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{count} @tab intent(in) The number of images which are provided in
-the next argument. For a zero-sized array, the value is zero. For
-@code{sync images (*)}, the value is @math{-1}.
-@item @var{images} @tab intent(in) An array with the images provided by the
-user. If @var{count} is zero, a NULL pointer is passed.
-@item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
-@item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
-an error message; may be NULL.
-@item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
-@end multitable
-@end table
-
-
-
-@node _gfortran_caf_sync_memory
-@subsection @code{_gfortran_caf_sync_memory} --- Wait for completion of segment-memory operations
-@cindex Coarray, _gfortran_caf_sync_memory
-
-@table @asis
-@item @emph{Description}:
-Acts as optimization barrier between different segments. It also ensures that
-all pending memory operations of this image have been completed.
-
-@item @emph{Syntax}:
-@code{void _gfortran_caf_sync_memory (int *stat, char *errmsg, size_t errmsg_len)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
-@item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
-an error message; may be NULL.
-@item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
-@end multitable
-
-@item @emph{NOTE} A simple implementation could be
-@code{__asm__ __volatile__ ("":::"memory")} to prevent code movements.
-@end table
-
-
-
-@node _gfortran_caf_error_stop
-@subsection @code{_gfortran_caf_error_stop} --- Error termination with exit code
-@cindex Coarray, _gfortran_caf_error_stop
-
-@table @asis
-@item @emph{Description}:
-Invoked for an @code{ERROR STOP} statement which has an integer argument. The
-function should terminate the program with the specified exit code.
-
-
-@item @emph{Syntax}:
-@code{void _gfortran_caf_error_stop (int error)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{error} @tab intent(in) The exit status to be used.
-@end multitable
-@end table
-
-
-
-@node _gfortran_caf_error_stop_str
-@subsection @code{_gfortran_caf_error_stop_str} --- Error termination with string
-@cindex Coarray, _gfortran_caf_error_stop_str
-
-@table @asis
-@item @emph{Description}:
-Invoked for an @code{ERROR STOP} statement which has a string as argument. The
-function should terminate the program with a nonzero-exit code.
-
-@item @emph{Syntax}:
-@code{void _gfortran_caf_error_stop (const char *string, size_t len)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{string} @tab intent(in) the error message (not zero terminated)
-@item @var{len} @tab intent(in) the length of the string
-@end multitable
-@end table
-
-
-
-@node _gfortran_caf_fail_image
-@subsection @code{_gfortran_caf_fail_image} --- Mark the image failed and end its execution
-@cindex Coarray, _gfortran_caf_fail_image
-
-@table @asis
-@item @emph{Description}:
-Invoked for an @code{FAIL IMAGE} statement. The function should terminate the
-current image.
-
-@item @emph{Syntax}:
-@code{void _gfortran_caf_fail_image ()}
-
-@item @emph{NOTES}
-This function follows TS18508.
-@end table
-
-
-
-@node _gfortran_caf_atomic_define
-@subsection @code{_gfortran_caf_atomic_define} --- Atomic variable assignment
-@cindex Coarray, _gfortran_caf_atomic_define
-
-@table @asis
-@item @emph{Description}:
-Assign atomically a value to an integer or logical variable.
-
-@item @emph{Syntax}:
-@code{void _gfortran_caf_atomic_define (caf_token_t token, size_t offset,
-int image_index, void *value, int *stat, int type, int kind)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
-@item @var{offset} @tab intent(in) By which amount of bytes the actual data is
-shifted compared to the base address of the coarray.
-@item @var{image_index} @tab intent(in) The ID of the remote image; must be a
-positive number; zero indicates the current image when used noncoindexed.
-@item @var{value} @tab intent(in) the value to be assigned, passed by reference
-@item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
-@item @var{type} @tab intent(in) The data type, i.e. @code{BT_INTEGER} (1) or
-@code{BT_LOGICAL} (2).
-@item @var{kind} @tab intent(in) The kind value (only 4; always @code{int})
-@end multitable
-@end table
-
-
-
-@node _gfortran_caf_atomic_ref
-@subsection @code{_gfortran_caf_atomic_ref} --- Atomic variable reference
-@cindex Coarray, _gfortran_caf_atomic_ref
-
-@table @asis
-@item @emph{Description}:
-Reference atomically a value of a kind-4 integer or logical variable.
-
-@item @emph{Syntax}:
-@code{void _gfortran_caf_atomic_ref (caf_token_t token, size_t offset,
-int image_index, void *value, int *stat, int type, int kind)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
-@item @var{offset} @tab intent(in) By which amount of bytes the actual data is
-shifted compared to the base address of the coarray.
-@item @var{image_index} @tab intent(in) The ID of the remote image; must be a
-positive number; zero indicates the current image when used noncoindexed.
-@item @var{value} @tab intent(out) The variable assigned the atomically
-referenced variable.
-@item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
-@item @var{type} @tab the data type, i.e. @code{BT_INTEGER} (1) or
-@code{BT_LOGICAL} (2).
-@item @var{kind} @tab The kind value (only 4; always @code{int})
-@end multitable
-@end table
-
-
-
-@node _gfortran_caf_atomic_cas
-@subsection @code{_gfortran_caf_atomic_cas} --- Atomic compare and swap
-@cindex Coarray, _gfortran_caf_atomic_cas
-
-@table @asis
-@item @emph{Description}:
-Atomic compare and swap of a kind-4 integer or logical variable. Assigns
-atomically the specified value to the atomic variable, if the latter has
-the value specified by the passed condition value.
-
-@item @emph{Syntax}:
-@code{void _gfortran_caf_atomic_cas (caf_token_t token, size_t offset,
-int image_index, void *old, void *compare, void *new_val, int *stat,
-int type, int kind)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
-@item @var{offset} @tab intent(in) By which amount of bytes the actual data is
-shifted compared to the base address of the coarray.
-@item @var{image_index} @tab intent(in) The ID of the remote image; must be a
-positive number; zero indicates the current image when used noncoindexed.
-@item @var{old} @tab intent(out) The value which the atomic variable had
-just before the cas operation.
-@item @var{compare} @tab intent(in) The value used for comparision.
-@item @var{new_val} @tab intent(in) The new value for the atomic variable,
-assigned to the atomic variable, if @code{compare} equals the value of the
-atomic variable.
-@item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
-@item @var{type} @tab intent(in) the data type, i.e. @code{BT_INTEGER} (1) or
-@code{BT_LOGICAL} (2).
-@item @var{kind} @tab intent(in) The kind value (only 4; always @code{int})
-@end multitable
-@end table
-
-
-
-@node _gfortran_caf_atomic_op
-@subsection @code{_gfortran_caf_atomic_op} --- Atomic operation
-@cindex Coarray, _gfortran_caf_atomic_op
-
-@table @asis
-@item @emph{Description}:
-Apply an operation atomically to an atomic integer or logical variable.
-After the operation, @var{old} contains the value just before the operation,
-which, respectively, adds (GFC_CAF_ATOMIC_ADD) atomically the @code{value} to
-the atomic integer variable or does a bitwise AND, OR or exclusive OR
-between the atomic variable and @var{value}; the result is then stored in the
-atomic variable.
-
-@item @emph{Syntax}:
-@code{void _gfortran_caf_atomic_op (int op, caf_token_t token, size_t offset,
-int image_index, void *value, void *old, int *stat, int type, int kind)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{op} @tab intent(in) the operation to be performed; possible values
-@code{GFC_CAF_ATOMIC_ADD} (1), @code{GFC_CAF_ATOMIC_AND} (2),
-@code{GFC_CAF_ATOMIC_OR} (3), @code{GFC_CAF_ATOMIC_XOR} (4).
-@item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
-@item @var{offset} @tab intent(in) By which amount of bytes the actual data is
-shifted compared to the base address of the coarray.
-@item @var{image_index} @tab intent(in) The ID of the remote image; must be a
-positive number; zero indicates the current image when used noncoindexed.
-@item @var{old} @tab intent(out) The value which the atomic variable had
-just before the atomic operation.
-@item @var{val} @tab intent(in) The new value for the atomic variable,
-assigned to the atomic variable, if @code{compare} equals the value of the
-atomic variable.
-@item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
-@item @var{type} @tab intent(in) the data type, i.e. @code{BT_INTEGER} (1) or
-@code{BT_LOGICAL} (2)
-@item @var{kind} @tab intent(in) the kind value (only 4; always @code{int})
-@end multitable
-@end table
-
-
-
-
-@node _gfortran_caf_co_broadcast
-@subsection @code{_gfortran_caf_co_broadcast} --- Sending data to all images
-@cindex Coarray, _gfortran_caf_co_broadcast
-
-@table @asis
-@item @emph{Description}:
-Distribute a value from a given image to all other images in the team. Has to
-be called collectively.
-
-@item @emph{Syntax}:
-@code{void _gfortran_caf_co_broadcast (gfc_descriptor_t *a,
-int source_image, int *stat, char *errmsg, size_t errmsg_len)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{a} @tab intent(inout) An array descriptor with the data to be
-broadcasted (on @var{source_image}) or to be received (other images).
-@item @var{source_image} @tab intent(in) The ID of the image from which the
-data should be broadcasted.
-@item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
-@item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
-an error message; may be NULL.
-@item @var{errmsg_len} @tab intent(in) the buffer size of errmsg.
-@end multitable
-@end table
-
-
-
-@node _gfortran_caf_co_max
-@subsection @code{_gfortran_caf_co_max} --- Collective maximum reduction
-@cindex Coarray, _gfortran_caf_co_max
-
-@table @asis
-@item @emph{Description}:
-Calculates for each array element of the variable @var{a} the maximum
-value for that element in the current team; if @var{result_image} has the
-value 0, the result shall be stored on all images, otherwise, only on the
-specified image. This function operates on numeric values and character
-strings.
-
-@item @emph{Syntax}:
-@code{void _gfortran_caf_co_max (gfc_descriptor_t *a, int result_image,
-int *stat, char *errmsg, int a_len, size_t errmsg_len)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{a} @tab intent(inout) An array descriptor for the data to be
-processed. On the destination image(s) the result overwrites the old content.
-@item @var{result_image} @tab intent(in) The ID of the image to which the
-reduced value should be copied to; if zero, it has to be copied to all images.
-@item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
-@item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
-an error message; may be NULL.
-@item @var{a_len} @tab intent(in) the string length of argument @var{a}
-@item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
-@end multitable
-
-@item @emph{NOTES}
-If @var{result_image} is nonzero, the data in the array descriptor @var{a} on
-all images except of the specified one become undefined; hence, the library may
-make use of this.
-@end table
-
-
-
-@node _gfortran_caf_co_min
-@subsection @code{_gfortran_caf_co_min} --- Collective minimum reduction
-@cindex Coarray, _gfortran_caf_co_min
-
-@table @asis
-@item @emph{Description}:
-Calculates for each array element of the variable @var{a} the minimum
-value for that element in the current team; if @var{result_image} has the
-value 0, the result shall be stored on all images, otherwise, only on the
-specified image. This function operates on numeric values and character
-strings.
-
-@item @emph{Syntax}:
-@code{void _gfortran_caf_co_min (gfc_descriptor_t *a, int result_image,
-int *stat, char *errmsg, int a_len, size_t errmsg_len)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{a} @tab intent(inout) An array descriptor for the data to be
-processed. On the destination image(s) the result overwrites the old content.
-@item @var{result_image} @tab intent(in) The ID of the image to which the
-reduced value should be copied to; if zero, it has to be copied to all images.
-@item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
-@item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
-an error message; may be NULL.
-@item @var{a_len} @tab intent(in) the string length of argument @var{a}
-@item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
-@end multitable
-
-@item @emph{NOTES}
-If @var{result_image} is nonzero, the data in the array descriptor @var{a} on
-all images except of the specified one become undefined; hence, the library may
-make use of this.
-@end table
-
-
-
-@node _gfortran_caf_co_sum
-@subsection @code{_gfortran_caf_co_sum} --- Collective summing reduction
-@cindex Coarray, _gfortran_caf_co_sum
-
-@table @asis
-@item @emph{Description}:
-Calculates for each array element of the variable @var{a} the sum of all
-values for that element in the current team; if @var{result_image} has the
-value 0, the result shall be stored on all images, otherwise, only on the
-specified image. This function operates on numeric values only.
-
-@item @emph{Syntax}:
-@code{void _gfortran_caf_co_sum (gfc_descriptor_t *a, int result_image,
-int *stat, char *errmsg, size_t errmsg_len)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{a} @tab intent(inout) An array descriptor with the data to be
-processed. On the destination image(s) the result overwrites the old content.
-@item @var{result_image} @tab intent(in) The ID of the image to which the
-reduced value should be copied to; if zero, it has to be copied to all images.
-@item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
-@item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
-an error message; may be NULL.
-@item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
-@end multitable
-
-@item @emph{NOTES}
-If @var{result_image} is nonzero, the data in the array descriptor @var{a} on
-all images except of the specified one become undefined; hence, the library may
-make use of this.
-@end table
-
-
-
-@node _gfortran_caf_co_reduce
-@subsection @code{_gfortran_caf_co_reduce} --- Generic collective reduction
-@cindex Coarray, _gfortran_caf_co_reduce
-
-@table @asis
-@item @emph{Description}:
-Calculates for each array element of the variable @var{a} the reduction
-value for that element in the current team; if @var{result_image} has the
-value 0, the result shall be stored on all images, otherwise, only on the
-specified image. The @var{opr} is a pure function doing a mathematically
-commutative and associative operation.
-
-The @var{opr_flags} denote the following; the values are bitwise ored.
-@code{GFC_CAF_BYREF} (1) if the result should be returned
-by reference; @code{GFC_CAF_HIDDENLEN} (2) whether the result and argument
-string lengths shall be specified as hidden arguments;
-@code{GFC_CAF_ARG_VALUE} (4) whether the arguments shall be passed by value,
-@code{GFC_CAF_ARG_DESC} (8) whether the arguments shall be passed by descriptor.
-
-
-@item @emph{Syntax}:
-@code{void _gfortran_caf_co_reduce (gfc_descriptor_t *a,
-void * (*opr) (void *, void *), int opr_flags, int result_image,
-int *stat, char *errmsg, int a_len, size_t errmsg_len)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{a} @tab intent(inout) An array descriptor with the data to be
-processed. On the destination image(s) the result overwrites the old content.
-@item @var{opr} @tab intent(in) Function pointer to the reduction function
-@item @var{opr_flags} @tab intent(in) Flags regarding the reduction function
-@item @var{result_image} @tab intent(in) The ID of the image to which the
-reduced value should be copied to; if zero, it has to be copied to all images.
-@item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
-@item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
-an error message; may be NULL.
-@item @var{a_len} @tab intent(in) the string length of argument @var{a}
-@item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
-@end multitable
-
-@item @emph{NOTES}
-If @var{result_image} is nonzero, the data in the array descriptor @var{a} on
-all images except of the specified one become undefined; hence, the library may
-make use of this.
-
-For character arguments, the result is passed as first argument, followed
-by the result string length, next come the two string arguments, followed
-by the two hidden string length arguments. With C binding, there are no hidden
-arguments and by-reference passing and either only a single character is passed
-or an array descriptor.
-@end table
-
-
-@c Intrinsic Procedures
-@c ---------------------------------------------------------------------
-
-@include intrinsic.texi
-
-
-@tex
-\blankpart
-@end tex
-
-@c ---------------------------------------------------------------------
-@c Contributing
-@c ---------------------------------------------------------------------
-
-@node Contributing
-@unnumbered Contributing
-@cindex Contributing
-
-Free software is only possible if people contribute to efforts
-to create it.
-We're always in need of more people helping out with ideas
-and comments, writing documentation and contributing code.
-
-If you want to contribute to GNU Fortran,
-have a look at the long lists of projects you can take on.
-Some of these projects are small,
-some of them are large;
-some are completely orthogonal to the rest of what is
-happening on GNU Fortran,
-but others are ``mainstream'' projects in need of enthusiastic hackers.
-All of these projects are important!
-We will eventually get around to the things here,
-but they are also things doable by someone who is willing and able.
-
-@menu
-* Contributors::
-* Projects::
-@end menu
-
-
-@node Contributors
-@section Contributors to GNU Fortran
-@cindex Contributors
-@cindex Credits
-@cindex Authors
-
-Most of the parser was hand-crafted by @emph{Andy Vaught}, who is
-also the initiator of the whole project. Thanks Andy!
-Most of the interface with GCC was written by @emph{Paul Brook}.
-
-The following individuals have contributed code and/or
-ideas and significant help to the GNU Fortran project
-(in alphabetical order):
-
-@itemize @minus
-@item Janne Blomqvist
-@item Steven Bosscher
-@item Paul Brook
-@item Tobias Burnus
-@item Fran@,{c}ois-Xavier Coudert
-@item Bud Davis
-@item Jerry DeLisle
-@item Erik Edelmann
-@item Bernhard Fischer
-@item Daniel Franke
-@item Richard Guenther
-@item Richard Henderson
-@item Katherine Holcomb
-@item Jakub Jelinek
-@item Niels Kristian Bech Jensen
-@item Steven Johnson
-@item Steven G. Kargl
-@item Thomas Koenig
-@item Asher Langton
-@item H. J. Lu
-@item Toon Moene
-@item Brooks Moses
-@item Andrew Pinski
-@item Tim Prince
-@item Christopher D. Rickett
-@item Richard Sandiford
-@item Tobias Schl@"uter
-@item Roger Sayle
-@item Paul Thomas
-@item Andy Vaught
-@item Feng Wang
-@item Janus Weil
-@item Daniel Kraft
-@end itemize
-
-The following people have contributed bug reports,
-smaller or larger patches,
-and much needed feedback and encouragement for the
-GNU Fortran project:
-
-@itemize @minus
-@item Bill Clodius
-@item Dominique d'Humi@`eres
-@item Kate Hedstrom
-@item Erik Schnetter
-@item Gerhard Steinmetz
-@item Joost VandeVondele
-@end itemize
-
-Many other individuals have helped debug,
-test and improve the GNU Fortran compiler over the past few years,
-and we welcome you to do the same!
-If you already have done so,
-and you would like to see your name listed in the
-list above, please contact us.
-
-
-@node Projects
-@section Projects
-
-@table @emph
-
-@item Help build the test suite
-Solicit more code for donation to the test suite: the more extensive the
-testsuite, the smaller the risk of breaking things in the future! We can
-keep code private on request.
-
-@item Bug hunting/squishing
-Find bugs and write more test cases! Test cases are especially very
-welcome, because it allows us to concentrate on fixing bugs instead of
-isolating them. Going through the bugzilla database at
-@url{https://gcc.gnu.org/@/bugzilla/} to reduce testcases posted there and
-add more information (for example, for which version does the testcase
-work, for which versions does it fail?) is also very helpful.
-
-@item Missing features
-For a larger project, consider working on the missing features required for
-Fortran language standards compliance (@pxref{Standards}), or contributing
-to the implementation of extensions such as OpenMP (@pxref{OpenMP}) or
-OpenACC (@pxref{OpenACC}) that are under active development. Again,
-contributing test cases for these features is useful too!
-
-@end table
-
-
-@c ---------------------------------------------------------------------
-@c GNU General Public License
-@c ---------------------------------------------------------------------
-
-@include gpl_v3.texi
-
-
-
-@c ---------------------------------------------------------------------
-@c GNU Free Documentation License
-@c ---------------------------------------------------------------------
-
-@include fdl.texi
-
-
-
-@c ---------------------------------------------------------------------
-@c Funding Free Software
-@c ---------------------------------------------------------------------
-
-@include funding.texi
-
-@c ---------------------------------------------------------------------
-@c Indices
-@c ---------------------------------------------------------------------
-
-@node Option Index
-@unnumbered Option Index
-@command{gfortran}'s command line options are indexed here without any
-initial @samp{-} or @samp{--}. Where an option has both positive and
-negative forms (such as -foption and -fno-option), relevant entries in
-the manual are indexed under the most appropriate form; it may sometimes
-be useful to look up both forms.
-@printindex op
-
-@node Keyword Index
-@unnumbered Keyword Index
-@printindex cp
-
-@bye
+++ /dev/null
-@ignore
-Copyright (C) 2005-2022 Free Software Foundation, Inc.
-This is part of the GNU Fortran manual.
-For copying conditions, see the file gfortran.texi.
-
-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 the
-Invariant Sections being ``Funding Free Software'', the Front-Cover
-Texts being (a) (see below), and with the Back-Cover Texts being (b)
-(see below). A copy of the license is included in the gfdl(7) man page.
-
-
-Some basic guidelines for editing this document:
-
- (1) The intrinsic procedures are to be listed in alphabetical order.
- (2) The generic name is to be used.
- (3) The specific names are included in the function index and in a
- table at the end of the node (See ABS entry).
- (4) Try to maintain the same style for each entry.
-
-
-@end ignore
-
-@tex
-\gdef\acosd{\mathop{\rm acosd}\nolimits}
-\gdef\asind{\mathop{\rm asind}\nolimits}
-\gdef\atand{\mathop{\rm atand}\nolimits}
-\gdef\acos{\mathop{\rm acos}\nolimits}
-\gdef\asin{\mathop{\rm asin}\nolimits}
-\gdef\atan{\mathop{\rm atan}\nolimits}
-\gdef\acosh{\mathop{\rm acosh}\nolimits}
-\gdef\asinh{\mathop{\rm asinh}\nolimits}
-\gdef\atanh{\mathop{\rm atanh}\nolimits}
-\gdef\cosd{\mathop{\rm cosd}\nolimits}
-@end tex
-
-
-@node Intrinsic Procedures
-@chapter Intrinsic Procedures
-@cindex intrinsic procedures
-
-@menu
-* Introduction: Introduction to Intrinsics
-* @code{ABORT}: ABORT, Abort the program
-* @code{ABS}: ABS, Absolute value
-* @code{ACCESS}: ACCESS, Checks file access modes
-* @code{ACHAR}: ACHAR, Character in @acronym{ASCII} collating sequence
-* @code{ACOS}: ACOS, Arccosine function
-* @code{ACOSD}: ACOSD, Arccosine function, degrees
-* @code{ACOSH}: ACOSH, Inverse hyperbolic cosine function
-* @code{ADJUSTL}: ADJUSTL, Left adjust a string
-* @code{ADJUSTR}: ADJUSTR, Right adjust a string
-* @code{AIMAG}: AIMAG, Imaginary part of complex number
-* @code{AINT}: AINT, Truncate to a whole number
-* @code{ALARM}: ALARM, Set an alarm clock
-* @code{ALL}: ALL, Determine if all values are true
-* @code{ALLOCATED}: ALLOCATED, Status of allocatable entity
-* @code{AND}: AND, Bitwise logical AND
-* @code{ANINT}: ANINT, Nearest whole number
-* @code{ANY}: ANY, Determine if any values are true
-* @code{ASIN}: ASIN, Arcsine function
-* @code{ASIND}: ASIND, Arcsine function, degrees
-* @code{ASINH}: ASINH, Inverse hyperbolic sine function
-* @code{ASSOCIATED}: ASSOCIATED, Status of a pointer or pointer/target pair
-* @code{ATAN}: ATAN, Arctangent function
-* @code{ATAND}: ATAND, Arctangent function, degrees
-* @code{ATAN2}: ATAN2, Arctangent function
-* @code{ATAN2D}: ATAN2D, Arctangent function, degrees
-* @code{ATANH}: ATANH, Inverse hyperbolic tangent function
-* @code{ATOMIC_ADD}: ATOMIC_ADD, Atomic ADD operation
-* @code{ATOMIC_AND}: ATOMIC_AND, Atomic bitwise AND operation
-* @code{ATOMIC_CAS}: ATOMIC_CAS, Atomic compare and swap
-* @code{ATOMIC_DEFINE}: ATOMIC_DEFINE, Setting a variable atomically
-* @code{ATOMIC_FETCH_ADD}: ATOMIC_FETCH_ADD, Atomic ADD operation with prior fetch
-* @code{ATOMIC_FETCH_AND}: ATOMIC_FETCH_AND, Atomic bitwise AND operation with prior fetch
-* @code{ATOMIC_FETCH_OR}: ATOMIC_FETCH_OR, Atomic bitwise OR operation with prior fetch
-* @code{ATOMIC_FETCH_XOR}: ATOMIC_FETCH_XOR, Atomic bitwise XOR operation with prior fetch
-* @code{ATOMIC_OR}: ATOMIC_OR, Atomic bitwise OR operation
-* @code{ATOMIC_REF}: ATOMIC_REF, Obtaining the value of a variable atomically
-* @code{ATOMIC_XOR}: ATOMIC_XOR, Atomic bitwise OR operation
-* @code{BACKTRACE}: BACKTRACE, Show a backtrace
-* @code{BESSEL_J0}: BESSEL_J0, Bessel function of the first kind of order 0
-* @code{BESSEL_J1}: BESSEL_J1, Bessel function of the first kind of order 1
-* @code{BESSEL_JN}: BESSEL_JN, Bessel function of the first kind
-* @code{BESSEL_Y0}: BESSEL_Y0, Bessel function of the second kind of order 0
-* @code{BESSEL_Y1}: BESSEL_Y1, Bessel function of the second kind of order 1
-* @code{BESSEL_YN}: BESSEL_YN, Bessel function of the second kind
-* @code{BGE}: BGE, Bitwise greater than or equal to
-* @code{BGT}: BGT, Bitwise greater than
-* @code{BIT_SIZE}: BIT_SIZE, Bit size inquiry function
-* @code{BLE}: BLE, Bitwise less than or equal to
-* @code{BLT}: BLT, Bitwise less than
-* @code{BTEST}: BTEST, Bit test function
-* @code{C_ASSOCIATED}: C_ASSOCIATED, Status of a C pointer
-* @code{C_F_POINTER}: C_F_POINTER, Convert C into Fortran pointer
-* @code{C_F_PROCPOINTER}: C_F_PROCPOINTER, Convert C into Fortran procedure pointer
-* @code{C_FUNLOC}: C_FUNLOC, Obtain the C address of a procedure
-* @code{C_LOC}: C_LOC, Obtain the C address of an object
-* @code{C_SIZEOF}: C_SIZEOF, Size in bytes of an expression
-* @code{CEILING}: CEILING, Integer ceiling function
-* @code{CHAR}: CHAR, Integer-to-character conversion function
-* @code{CHDIR}: CHDIR, Change working directory
-* @code{CHMOD}: CHMOD, Change access permissions of files
-* @code{CMPLX}: CMPLX, Complex conversion function
-* @code{CO_BROADCAST}: CO_BROADCAST, Copy a value to all images the current set of images
-* @code{CO_MAX}: CO_MAX, Maximal value on the current set of images
-* @code{CO_MIN}: CO_MIN, Minimal value on the current set of images
-* @code{CO_REDUCE}: CO_REDUCE, Reduction of values on the current set of images
-* @code{CO_SUM}: CO_SUM, Sum of values on the current set of images
-* @code{COMMAND_ARGUMENT_COUNT}: COMMAND_ARGUMENT_COUNT, Get number of command line arguments
-* @code{COMPILER_OPTIONS}: COMPILER_OPTIONS, Options passed to the compiler
-* @code{COMPILER_VERSION}: COMPILER_VERSION, Compiler version string
-* @code{COMPLEX}: COMPLEX, Complex conversion function
-* @code{CONJG}: CONJG, Complex conjugate function
-* @code{COS}: COS, Cosine function
-* @code{COSD}: COSD, Cosine function, degrees
-* @code{COSH}: COSH, Hyperbolic cosine function
-* @code{COTAN}: COTAN, Cotangent function
-* @code{COTAND}: COTAND, Cotangent function, degrees
-* @code{COUNT}: COUNT, Count occurrences of TRUE in an array
-* @code{CPU_TIME}: CPU_TIME, CPU time subroutine
-* @code{CSHIFT}: CSHIFT, Circular shift elements of an array
-* @code{CTIME}: CTIME, Subroutine (or function) to convert a time into a string
-* @code{DATE_AND_TIME}: DATE_AND_TIME, Date and time subroutine
-* @code{DBLE}: DBLE, Double precision conversion function
-* @code{DCMPLX}: DCMPLX, Double complex conversion function
-* @code{DIGITS}: DIGITS, Significant digits function
-* @code{DIM}: DIM, Positive difference
-* @code{DOT_PRODUCT}: DOT_PRODUCT, Dot product function
-* @code{DPROD}: DPROD, Double product function
-* @code{DREAL}: DREAL, Double real part function
-* @code{DSHIFTL}: DSHIFTL, Combined left shift
-* @code{DSHIFTR}: DSHIFTR, Combined right shift
-* @code{DTIME}: DTIME, Execution time subroutine (or function)
-* @code{EOSHIFT}: EOSHIFT, End-off shift elements of an array
-* @code{EPSILON}: EPSILON, Epsilon function
-* @code{ERF}: ERF, Error function
-* @code{ERFC}: ERFC, Complementary error function
-* @code{ERFC_SCALED}: ERFC_SCALED, Exponentially-scaled complementary error function
-* @code{ETIME}: ETIME, Execution time subroutine (or function)
-* @code{EVENT_QUERY}: EVENT_QUERY, Query whether a coarray event has occurred
-* @code{EXECUTE_COMMAND_LINE}: EXECUTE_COMMAND_LINE, Execute a shell command
-* @code{EXIT}: EXIT, Exit the program with status.
-* @code{EXP}: EXP, Exponential function
-* @code{EXPONENT}: EXPONENT, Exponent function
-* @code{EXTENDS_TYPE_OF}: EXTENDS_TYPE_OF, Query dynamic type for extension
-* @code{FDATE}: FDATE, Subroutine (or function) to get the current time as a string
-* @code{FGET}: FGET, Read a single character in stream mode from stdin
-* @code{FGETC}: FGETC, Read a single character in stream mode
-* @code{FINDLOC}: FINDLOC, Search an array for a value
-* @code{FLOOR}: FLOOR, Integer floor function
-* @code{FLUSH}: FLUSH, Flush I/O unit(s)
-* @code{FNUM}: FNUM, File number function
-* @code{FPUT}: FPUT, Write a single character in stream mode to stdout
-* @code{FPUTC}: FPUTC, Write a single character in stream mode
-* @code{FRACTION}: FRACTION, Fractional part of the model representation
-* @code{FREE}: FREE, Memory de-allocation subroutine
-* @code{FSEEK}: FSEEK, Low level file positioning subroutine
-* @code{FSTAT}: FSTAT, Get file status
-* @code{FTELL}: FTELL, Current stream position
-* @code{GAMMA}: GAMMA, Gamma function
-* @code{GERROR}: GERROR, Get last system error message
-* @code{GETARG}: GETARG, Get command line arguments
-* @code{GET_COMMAND}: GET_COMMAND, Get the entire command line
-* @code{GET_COMMAND_ARGUMENT}: GET_COMMAND_ARGUMENT, Get command line arguments
-* @code{GETCWD}: GETCWD, Get current working directory
-* @code{GETENV}: GETENV, Get an environmental variable
-* @code{GET_ENVIRONMENT_VARIABLE}: GET_ENVIRONMENT_VARIABLE, Get an environmental variable
-* @code{GETGID}: GETGID, Group ID function
-* @code{GETLOG}: GETLOG, Get login name
-* @code{GETPID}: GETPID, Process ID function
-* @code{GETUID}: GETUID, User ID function
-* @code{GMTIME}: GMTIME, Convert time to GMT info
-* @code{HOSTNM}: HOSTNM, Get system host name
-* @code{HUGE}: HUGE, Largest number of a kind
-* @code{HYPOT}: HYPOT, Euclidean distance function
-* @code{IACHAR}: IACHAR, Code in @acronym{ASCII} collating sequence
-* @code{IALL}: IALL, Bitwise AND of array elements
-* @code{IAND}: IAND, Bitwise logical and
-* @code{IANY}: IANY, Bitwise OR of array elements
-* @code{IARGC}: IARGC, Get the number of command line arguments
-* @code{IBCLR}: IBCLR, Clear bit
-* @code{IBITS}: IBITS, Bit extraction
-* @code{IBSET}: IBSET, Set bit
-* @code{ICHAR}: ICHAR, Character-to-integer conversion function
-* @code{IDATE}: IDATE, Current local time (day/month/year)
-* @code{IEOR}: IEOR, Bitwise logical exclusive or
-* @code{IERRNO}: IERRNO, Function to get the last system error number
-* @code{IMAGE_INDEX}: IMAGE_INDEX, Cosubscript to image index conversion
-* @code{INDEX}: INDEX intrinsic, Position of a substring within a string
-* @code{INT}: INT, Convert to integer type
-* @code{INT2}: INT2, Convert to 16-bit integer type
-* @code{INT8}: INT8, Convert to 64-bit integer type
-* @code{IOR}: IOR, Bitwise logical or
-* @code{IPARITY}: IPARITY, Bitwise XOR of array elements
-* @code{IRAND}: IRAND, Integer pseudo-random number
-* @code{IS_CONTIGUOUS}: IS_CONTIGUOUS, Test whether an array is contiguous
-* @code{IS_IOSTAT_END}: IS_IOSTAT_END, Test for end-of-file value
-* @code{IS_IOSTAT_EOR}: IS_IOSTAT_EOR, Test for end-of-record value
-* @code{ISATTY}: ISATTY, Whether a unit is a terminal device
-* @code{ISHFT}: ISHFT, Shift bits
-* @code{ISHFTC}: ISHFTC, Shift bits circularly
-* @code{ISNAN}: ISNAN, Tests for a NaN
-* @code{ITIME}: ITIME, Current local time (hour/minutes/seconds)
-* @code{KILL}: KILL, Send a signal to a process
-* @code{KIND}: KIND, Kind of an entity
-* @code{LBOUND}: LBOUND, Lower dimension bounds of an array
-* @code{LCOBOUND}: LCOBOUND, Lower codimension bounds of an array
-* @code{LEADZ}: LEADZ, Number of leading zero bits of an integer
-* @code{LEN}: LEN, Length of a character entity
-* @code{LEN_TRIM}: LEN_TRIM, Length of a character entity without trailing blank characters
-* @code{LGE}: LGE, Lexical greater than or equal
-* @code{LGT}: LGT, Lexical greater than
-* @code{LINK}: LINK, Create a hard link
-* @code{LLE}: LLE, Lexical less than or equal
-* @code{LLT}: LLT, Lexical less than
-* @code{LNBLNK}: LNBLNK, Index of the last non-blank character in a string
-* @code{LOC}: LOC, Returns the address of a variable
-* @code{LOG}: LOG, Logarithm function
-* @code{LOG10}: LOG10, Base 10 logarithm function
-* @code{LOG_GAMMA}: LOG_GAMMA, Logarithm of the Gamma function
-* @code{LOGICAL}: LOGICAL, Convert to logical type
-* @code{LSHIFT}: LSHIFT, Left shift bits
-* @code{LSTAT}: LSTAT, Get file status
-* @code{LTIME}: LTIME, Convert time to local time info
-* @code{MALLOC}: MALLOC, Dynamic memory allocation function
-* @code{MASKL}: MASKL, Left justified mask
-* @code{MASKR}: MASKR, Right justified mask
-* @code{MATMUL}: MATMUL, matrix multiplication
-* @code{MAX}: MAX, Maximum value of an argument list
-* @code{MAXEXPONENT}: MAXEXPONENT, Maximum exponent of a real kind
-* @code{MAXLOC}: MAXLOC, Location of the maximum value within an array
-* @code{MAXVAL}: MAXVAL, Maximum value of an array
-* @code{MCLOCK}: MCLOCK, Time function
-* @code{MCLOCK8}: MCLOCK8, Time function (64-bit)
-* @code{MERGE}: MERGE, Merge arrays
-* @code{MERGE_BITS}: MERGE_BITS, Merge of bits under mask
-* @code{MIN}: MIN, Minimum value of an argument list
-* @code{MINEXPONENT}: MINEXPONENT, Minimum exponent of a real kind
-* @code{MINLOC}: MINLOC, Location of the minimum value within an array
-* @code{MINVAL}: MINVAL, Minimum value of an array
-* @code{MOD}: MOD, Remainder function
-* @code{MODULO}: MODULO, Modulo function
-* @code{MOVE_ALLOC}: MOVE_ALLOC, Move allocation from one object to another
-* @code{MVBITS}: MVBITS, Move bits from one integer to another
-* @code{NEAREST}: NEAREST, Nearest representable number
-* @code{NEW_LINE}: NEW_LINE, New line character
-* @code{NINT}: NINT, Nearest whole number
-* @code{NORM2}: NORM2, Euclidean vector norm
-* @code{NOT}: NOT, Logical negation
-* @code{NULL}: NULL, Function that returns an disassociated pointer
-* @code{NUM_IMAGES}: NUM_IMAGES, Number of images
-* @code{OR}: OR, Bitwise logical OR
-* @code{PACK}: PACK, Pack an array into an array of rank one
-* @code{PARITY}: PARITY, Reduction with exclusive OR
-* @code{PERROR}: PERROR, Print system error message
-* @code{POPCNT}: POPCNT, Number of bits set
-* @code{POPPAR}: POPPAR, Parity of the number of bits set
-* @code{PRECISION}: PRECISION, Decimal precision of a real kind
-* @code{PRESENT}: PRESENT, Determine whether an optional dummy argument is specified
-* @code{PRODUCT}: PRODUCT, Product of array elements
-* @code{RADIX}: RADIX, Base of a data model
-* @code{RAN}: RAN, Real pseudo-random number
-* @code{RAND}: RAND, Real pseudo-random number
-* @code{RANDOM_INIT}: RANDOM_INIT, Initialize pseudo-random number generator
-* @code{RANDOM_NUMBER}: RANDOM_NUMBER, Pseudo-random number
-* @code{RANDOM_SEED}: RANDOM_SEED, Initialize a pseudo-random number sequence
-* @code{RANGE}: RANGE, Decimal exponent range
-* @code{RANK} : RANK, Rank of a data object
-* @code{REAL}: REAL, Convert to real type
-* @code{RENAME}: RENAME, Rename a file
-* @code{REPEAT}: REPEAT, Repeated string concatenation
-* @code{RESHAPE}: RESHAPE, Function to reshape an array
-* @code{RRSPACING}: RRSPACING, Reciprocal of the relative spacing
-* @code{RSHIFT}: RSHIFT, Right shift bits
-* @code{SAME_TYPE_AS}: SAME_TYPE_AS, Query dynamic types for equality
-* @code{SCALE}: SCALE, Scale a real value
-* @code{SCAN}: SCAN, Scan a string for the presence of a set of characters
-* @code{SECNDS}: SECNDS, Time function
-* @code{SECOND}: SECOND, CPU time function
-* @code{SELECTED_CHAR_KIND}: SELECTED_CHAR_KIND, Choose character kind
-* @code{SELECTED_INT_KIND}: SELECTED_INT_KIND, Choose integer kind
-* @code{SELECTED_REAL_KIND}: SELECTED_REAL_KIND, Choose real kind
-* @code{SET_EXPONENT}: SET_EXPONENT, Set the exponent of the model
-* @code{SHAPE}: SHAPE, Determine the shape of an array
-* @code{SHIFTA}: SHIFTA, Right shift with fill
-* @code{SHIFTL}: SHIFTL, Left shift
-* @code{SHIFTR}: SHIFTR, Right shift
-* @code{SIGN}: SIGN, Sign copying function
-* @code{SIGNAL}: SIGNAL, Signal handling subroutine (or function)
-* @code{SIN}: SIN, Sine function
-* @code{SIND}: SIND, Sine function, degrees
-* @code{SINH}: SINH, Hyperbolic sine function
-* @code{SIZE}: SIZE, Function to determine the size of an array
-* @code{SIZEOF}: SIZEOF, Determine the size in bytes of an expression
-* @code{SLEEP}: SLEEP, Sleep for the specified number of seconds
-* @code{SPACING}: SPACING, Smallest distance between two numbers of a given type
-* @code{SPREAD}: SPREAD, Add a dimension to an array
-* @code{SQRT}: SQRT, Square-root function
-* @code{SRAND}: SRAND, Reinitialize the random number generator
-* @code{STAT}: STAT, Get file status
-* @code{STORAGE_SIZE}: STORAGE_SIZE, Storage size in bits
-* @code{SUM}: SUM, Sum of array elements
-* @code{SYMLNK}: SYMLNK, Create a symbolic link
-* @code{SYSTEM}: SYSTEM, Execute a shell command
-* @code{SYSTEM_CLOCK}: SYSTEM_CLOCK, Time function
-* @code{TAN}: TAN, Tangent function
-* @code{TAND}: TAND, Tangent function, degrees
-* @code{TANH}: TANH, Hyperbolic tangent function
-* @code{THIS_IMAGE}: THIS_IMAGE, Cosubscript index of this image
-* @code{TIME}: TIME, Time function
-* @code{TIME8}: TIME8, Time function (64-bit)
-* @code{TINY}: TINY, Smallest positive number of a real kind
-* @code{TRAILZ}: TRAILZ, Number of trailing zero bits of an integer
-* @code{TRANSFER}: TRANSFER, Transfer bit patterns
-* @code{TRANSPOSE}: TRANSPOSE, Transpose an array of rank two
-* @code{TRIM}: TRIM, Remove trailing blank characters of a string
-* @code{TTYNAM}: TTYNAM, Get the name of a terminal device
-* @code{UBOUND}: UBOUND, Upper dimension bounds of an array
-* @code{UCOBOUND}: UCOBOUND, Upper codimension bounds of an array
-* @code{UMASK}: UMASK, Set the file creation mask
-* @code{UNLINK}: UNLINK, Remove a file from the file system
-* @code{UNPACK}: UNPACK, Unpack an array of rank one into an array
-* @code{VERIFY}: VERIFY, Scan a string for the absence of a set of characters
-* @code{XOR}: XOR, Bitwise logical exclusive or
-@end menu
-
-@node Introduction to Intrinsics
-@section Introduction to intrinsic procedures
-
-The intrinsic procedures provided by GNU Fortran include procedures required
-by the Fortran 95 and later supported standards, and a set of intrinsic
-procedures for backwards compatibility with G77. Any conflict between
-a description here and a description in the Fortran standards is
-unintentional, and the standard(s) should be considered authoritative.
-
-The enumeration of the @code{KIND} type parameter is processor defined in
-the Fortran 95 standard. GNU Fortran defines the default integer type and
-default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)},
-respectively. The standard mandates that both data types shall have
-another kind, which have more precision. On typical target architectures
-supported by @command{gfortran}, this kind type parameter is @code{KIND=8}.
-Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent.
-In the description of generic intrinsic procedures, the kind type parameter
-will be specified by @code{KIND=*}, and in the description of specific
-names for an intrinsic procedure the kind type parameter will be explicitly
-given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}). Finally, for
-brevity the optional @code{KIND=} syntax will be omitted.
-
-Many of the intrinsic procedures take one or more optional arguments.
-This document follows the convention used in the Fortran 95 standard,
-and denotes such arguments by square brackets.
-
-GNU Fortran offers the @option{-std=} command-line option,
-which can be used to restrict the set of intrinsic procedures to a
-given standard. By default, @command{gfortran} sets the @option{-std=gnu}
-option, and so all intrinsic procedures described here are accepted. There
-is one caveat. For a select group of intrinsic procedures, @command{g77}
-implemented both a function and a subroutine. Both classes
-have been implemented in @command{gfortran} for backwards compatibility
-with @command{g77}. It is noted here that these functions and subroutines
-cannot be intermixed in a given subprogram. In the descriptions that follow,
-the applicable standard for each intrinsic procedure is noted.
-
-
-
-@node ABORT
-@section @code{ABORT} --- Abort the program
-@fnindex ABORT
-@cindex program termination, with core dump
-@cindex terminate program, with core dump
-@cindex core, dump
-
-@table @asis
-@item @emph{Description}:
-@code{ABORT} causes immediate termination of the program. On operating
-systems that support a core dump, @code{ABORT} will produce a core dump.
-It will also print a backtrace, unless @code{-fno-backtrace} is given.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Subroutine
-
-@item @emph{Syntax}:
-@code{CALL ABORT}
-
-@item @emph{Return value}:
-Does not return.
-
-@item @emph{Example}:
-@smallexample
-program test_abort
- integer :: i = 1, j = 2
- if (i /= j) call abort
-end program test_abort
-@end smallexample
-
-@item @emph{See also}:
-@ref{EXIT}, @gol
-@ref{KILL}, @gol
-@ref{BACKTRACE}
-@end table
-
-
-
-@node ABS
-@section @code{ABS} --- Absolute value
-@fnindex ABS
-@fnindex CABS
-@fnindex DABS
-@fnindex IABS
-@fnindex ZABS
-@fnindex CDABS
-@fnindex BABS
-@fnindex IIABS
-@fnindex JIABS
-@fnindex KIABS
-@cindex absolute value
-
-@table @asis
-@item @emph{Description}:
-@code{ABS(A)} computes the absolute value of @code{A}.
-
-@item @emph{Standard}:
-Fortran 77 and later, has overloads that are GNU extensions
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = ABS(A)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{A} @tab The type of the argument shall be an @code{INTEGER},
-@code{REAL}, or @code{COMPLEX}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of the same type and
-kind as the argument except the return value is @code{REAL} for a
-@code{COMPLEX} argument.
-
-@item @emph{Example}:
-@smallexample
-program test_abs
- integer :: i = -1
- real :: x = -1.e0
- complex :: z = (-1.e0,0.e0)
- i = abs(i)
- x = abs(x)
- x = abs(z)
-end program test_abs
-@end smallexample
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .23 .20 .33
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{ABS(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
-@item @code{CABS(A)} @tab @code{COMPLEX(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
-@item @code{DABS(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
-@item @code{IABS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab Fortran 77 and later
-@item @code{BABS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
-@item @code{IIABS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
-@item @code{JIABS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
-@item @code{KIABS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
-@item @code{ZABS(A)} @tab @code{COMPLEX(8) A} @tab @code{REAL(8)} @tab GNU extension
-@item @code{CDABS(A)} @tab @code{COMPLEX(8) A} @tab @code{REAL(8)} @tab GNU extension
-@end multitable
-@end table
-
-
-
-@node ACCESS
-@section @code{ACCESS} --- Checks file access modes
-@fnindex ACCESS
-@cindex file system, access mode
-
-@table @asis
-@item @emph{Description}:
-@code{ACCESS(NAME, MODE)} checks whether the file @var{NAME}
-exists, is readable, writable or executable. Except for the
-executable check, @code{ACCESS} can be replaced by
-Fortran 95's @code{INQUIRE}.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Inquiry function
-
-@item @emph{Syntax}:
-@code{RESULT = ACCESS(NAME, MODE)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
-file name. Trailing blank are ignored unless the character @code{achar(0)}
-is present, then all characters up to and excluding @code{achar(0)} are
-used as file name.
-@item @var{MODE} @tab Scalar @code{CHARACTER} of default kind with the
-file access mode, may be any concatenation of @code{"r"} (readable),
-@code{"w"} (writable) and @code{"x"} (executable), or @code{" "} to check
-for existence.
-@end multitable
-
-@item @emph{Return value}:
-Returns a scalar @code{INTEGER}, which is @code{0} if the file is
-accessible in the given mode; otherwise or if an invalid argument
-has been given for @code{MODE} the value @code{1} is returned.
-
-@item @emph{Example}:
-@smallexample
-program access_test
- implicit none
- character(len=*), parameter :: file = 'test.dat'
- character(len=*), parameter :: file2 = 'test.dat '//achar(0)
- if(access(file,' ') == 0) print *, trim(file),' is exists'
- if(access(file,'r') == 0) print *, trim(file),' is readable'
- if(access(file,'w') == 0) print *, trim(file),' is writable'
- if(access(file,'x') == 0) print *, trim(file),' is executable'
- if(access(file2,'rwx') == 0) &
- print *, trim(file2),' is readable, writable and executable'
-end program access_test
-@end smallexample
-@end table
-
-
-
-@node ACHAR
-@section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence
-@fnindex ACHAR
-@cindex @acronym{ASCII} collating sequence
-@cindex collating sequence, @acronym{ASCII}
-
-@table @asis
-@item @emph{Description}:
-@code{ACHAR(I)} returns the character located at position @code{I}
-in the @acronym{ASCII} collating sequence.
-
-@item @emph{Standard}:
-Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = ACHAR(I [, KIND])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{I} @tab The type shall be @code{INTEGER}.
-@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
-expression indicating the kind parameter of the result.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{CHARACTER} with a length of one.
-If the @var{KIND} argument is present, the return value is of the
-specified kind and of the default kind otherwise.
-
-@item @emph{Example}:
-@smallexample
-program test_achar
- character c
- c = achar(32)
-end program test_achar
-@end smallexample
-
-@item @emph{Note}:
-See @ref{ICHAR} for a discussion of converting between numerical values
-and formatted string representations.
-
-@item @emph{See also}:
-@ref{CHAR}, @gol
-@ref{IACHAR}, @gol
-@ref{ICHAR}
-@end table
-
-
-
-@node ACOS
-@section @code{ACOS} --- Arccosine function
-@fnindex ACOS
-@fnindex DACOS
-@cindex trigonometric function, cosine, inverse
-@cindex cosine, inverse
-
-@table @asis
-@item @emph{Description}:
-@code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}).
-
-@item @emph{Standard}:
-Fortran 77 and later, for a complex argument Fortran 2008 or later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = ACOS(X)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is
-less than or equal to one - or the type shall be @code{COMPLEX}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of the same type and kind as @var{X}.
-The real part of the result is in radians and lies in the range
-@math{0 \leq \Re \acos(x) \leq \pi}.
-
-@item @emph{Example}:
-@smallexample
-program test_acos
- real(8) :: x = 0.866_8
- x = acos(x)
-end program test_acos
-@end smallexample
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .23 .20 .33
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{ACOS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
-@item @code{DACOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
-@end multitable
-
-@item @emph{See also}:
-Inverse function: @gol
-@ref{COS} @gol
-Degrees function: @gol
-@ref{ACOSD}
-@end table
-
-
-
-@node ACOSD
-@section @code{ACOSD} --- Arccosine function, degrees
-@fnindex ACOSD
-@fnindex DACOSD
-@cindex trigonometric function, cosine, inverse, degrees
-@cindex cosine, inverse, degrees
-
-@table @asis
-@item @emph{Description}:
-@code{ACOSD(X)} computes the arccosine of @var{X} in degrees (inverse of
-@code{COSD(X)}).
-
-This function is for compatibility only and should be avoided in favor of
-standard constructs wherever possible.
-
-@item @emph{Standard}:
-GNU extension, enabled with @option{-fdec-math}
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = ACOSD(X)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is
-less than or equal to one - or the type shall be @code{COMPLEX}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of the same type and kind as @var{X}.
-The real part of the result is in degrees and lies in the range
-@math{0 \leq \Re \acos(x) \leq 180}.
-
-@item @emph{Example}:
-@smallexample
-program test_acosd
- real(8) :: x = 0.866_8
- x = acosd(x)
-end program test_acosd
-@end smallexample
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .23 .20 .33
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{ACOSD(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension
-@item @code{DACOSD(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
-@end multitable
-
-@item @emph{See also}:
-Inverse function: @gol
-@ref{COSD} @gol
-Radians function: @gol
-@ref{ACOS} @gol
-@end table
-
-
-
-@node ACOSH
-@section @code{ACOSH} --- Inverse hyperbolic cosine function
-@fnindex ACOSH
-@fnindex DACOSH
-@cindex area hyperbolic cosine
-@cindex inverse hyperbolic cosine
-@cindex hyperbolic function, cosine, inverse
-@cindex cosine, hyperbolic, inverse
-
-@table @asis
-@item @emph{Description}:
-@code{ACOSH(X)} computes the inverse hyperbolic cosine of @var{X}.
-
-@item @emph{Standard}:
-Fortran 2008 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = ACOSH(X)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
-@end multitable
-
-@item @emph{Return value}:
-The return value has the same type and kind as @var{X}. If @var{X} is
-complex, the imaginary part of the result is in radians and lies between
-@math{ 0 \leq \Im \acosh(x) \leq \pi}.
-
-@item @emph{Example}:
-@smallexample
-PROGRAM test_acosh
- REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /)
- WRITE (*,*) ACOSH(x)
-END PROGRAM
-@end smallexample
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .23 .20 .33
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{DACOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
-@end multitable
-
-@item @emph{See also}:
-Inverse function: @gol
-@ref{COSH}
-@end table
-
-
-
-@node ADJUSTL
-@section @code{ADJUSTL} --- Left adjust a string
-@fnindex ADJUSTL
-@cindex string, adjust left
-@cindex adjust string
-
-@table @asis
-@item @emph{Description}:
-@code{ADJUSTL(STRING)} will left adjust a string by removing leading spaces.
-Spaces are inserted at the end of the string as needed.
-
-@item @emph{Standard}:
-Fortran 90 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = ADJUSTL(STRING)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{STRING} @tab The type shall be @code{CHARACTER}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{CHARACTER} and of the same kind as
-@var{STRING} where leading spaces are removed and the same number of
-spaces are inserted on the end of @var{STRING}.
-
-@item @emph{Example}:
-@smallexample
-program test_adjustl
- character(len=20) :: str = ' gfortran'
- str = adjustl(str)
- print *, str
-end program test_adjustl
-@end smallexample
-
-@item @emph{See also}:
-@ref{ADJUSTR}, @gol
-@ref{TRIM}
-@end table
-
-
-
-@node ADJUSTR
-@section @code{ADJUSTR} --- Right adjust a string
-@fnindex ADJUSTR
-@cindex string, adjust right
-@cindex adjust string
-
-@table @asis
-@item @emph{Description}:
-@code{ADJUSTR(STRING)} will right adjust a string by removing trailing spaces.
-Spaces are inserted at the start of the string as needed.
-
-@item @emph{Standard}:
-Fortran 90 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = ADJUSTR(STRING)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{STR} @tab The type shall be @code{CHARACTER}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{CHARACTER} and of the same kind as
-@var{STRING} where trailing spaces are removed and the same number of
-spaces are inserted at the start of @var{STRING}.
-
-@item @emph{Example}:
-@smallexample
-program test_adjustr
- character(len=20) :: str = 'gfortran'
- str = adjustr(str)
- print *, str
-end program test_adjustr
-@end smallexample
-
-@item @emph{See also}:
-@ref{ADJUSTL}, @gol
-@ref{TRIM}
-@end table
-
-
-
-@node AIMAG
-@section @code{AIMAG} --- Imaginary part of complex number
-@fnindex AIMAG
-@fnindex DIMAG
-@fnindex IMAG
-@fnindex IMAGPART
-@cindex complex numbers, imaginary part
-
-@table @asis
-@item @emph{Description}:
-@code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}.
-The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided
-for compatibility with @command{g77}, and their use in new code is
-strongly discouraged.
-
-@item @emph{Standard}:
-Fortran 77 and later, has overloads that are GNU extensions
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = AIMAG(Z)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{Z} @tab The type of the argument shall be @code{COMPLEX}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{REAL} with the
-kind type parameter of the argument.
-
-@item @emph{Example}:
-@smallexample
-program test_aimag
- complex(4) z4
- complex(8) z8
- z4 = cmplx(1.e0_4, 0.e0_4)
- z8 = cmplx(0.e0_8, 1.e0_8)
- print *, aimag(z4), dimag(z8)
-end program test_aimag
-@end smallexample
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .23 .20 .33
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{AIMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab Fortran 77 and later
-@item @code{DIMAG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)} @tab GNU extension
-@item @code{IMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
-@item @code{IMAGPART(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
-@end multitable
-@end table
-
-
-
-@node AINT
-@section @code{AINT} --- Truncate to a whole number
-@fnindex AINT
-@fnindex DINT
-@cindex floor
-@cindex rounding, floor
-
-@table @asis
-@item @emph{Description}:
-@code{AINT(A [, KIND])} truncates its argument to a whole number.
-
-@item @emph{Standard}:
-Fortran 77 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = AINT(A [, KIND])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{A} @tab The type of the argument shall be @code{REAL}.
-@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
-expression indicating the kind parameter of the result.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{REAL} with the kind type parameter of the
-argument if the optional @var{KIND} is absent; otherwise, the kind
-type parameter will be given by @var{KIND}. If the magnitude of
-@var{X} is less than one, @code{AINT(X)} returns zero. If the
-magnitude is equal to or greater than one then it returns the largest
-whole number that does not exceed its magnitude. The sign is the same
-as the sign of @var{X}.
-
-@item @emph{Example}:
-@smallexample
-program test_aint
- real(4) x4
- real(8) x8
- x4 = 1.234E0_4
- x8 = 4.321_8
- print *, aint(x4), dint(x8)
- x8 = aint(x4,8)
-end program test_aint
-@end smallexample
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .23 .20 .33
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
-@item @code{DINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
-@end multitable
-@end table
-
-
-
-@node ALARM
-@section @code{ALARM} --- Execute a routine after a given delay
-@fnindex ALARM
-@cindex delayed execution
-
-@table @asis
-@item @emph{Description}:
-@code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER}
-to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to
-set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is
-supplied, it will be returned with the number of seconds remaining until
-any previously scheduled alarm was due to be delivered, or zero if there
-was no previously scheduled alarm.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Subroutine
-
-@item @emph{Syntax}:
-@code{CALL ALARM(SECONDS, HANDLER [, STATUS])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{SECONDS} @tab The type of the argument shall be a scalar
-@code{INTEGER}. It is @code{INTENT(IN)}.
-@item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or
-@code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar
-values may be either @code{SIG_IGN=1} to ignore the alarm generated
-or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}.
-@item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
-variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}.
-@end multitable
-
-@item @emph{Example}:
-@smallexample
-program test_alarm
- external handler_print
- integer i
- call alarm (3, handler_print, i)
- print *, i
- call sleep(10)
-end program test_alarm
-@end smallexample
-This will cause the external routine @var{handler_print} to be called
-after 3 seconds.
-@end table
-
-
-
-@node ALL
-@section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true
-@fnindex ALL
-@cindex array, apply condition
-@cindex array, condition testing
-
-@table @asis
-@item @emph{Description}:
-@code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK}
-in the array along dimension @var{DIM}.
-
-@item @emph{Standard}:
-Fortran 90 and later
-
-@item @emph{Class}:
-Transformational function
-
-@item @emph{Syntax}:
-@code{RESULT = ALL(MASK [, DIM])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
-it shall not be scalar.
-@item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
-with a value that lies between one and the rank of @var{MASK}.
-@end multitable
-
-@item @emph{Return value}:
-@code{ALL(MASK)} returns a scalar value of type @code{LOGICAL} where
-the kind type parameter is the same as the kind type parameter of
-@var{MASK}. If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns
-an array with the rank of @var{MASK} minus 1. The shape is determined from
-the shape of @var{MASK} where the @var{DIM} dimension is elided.
-
-@table @asis
-@item (A)
-@code{ALL(MASK)} is true if all elements of @var{MASK} are true.
-It also is true if @var{MASK} has zero size; otherwise, it is false.
-@item (B)
-If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent
-to @code{ALL(MASK)}. If the rank is greater than one, then @code{ALL(MASK,DIM)}
-is determined by applying @code{ALL} to the array sections.
-@end table
-
-@item @emph{Example}:
-@smallexample
-program test_all
- logical l
- l = all((/.true., .true., .true./))
- print *, l
- call section
- contains
- subroutine section
- integer a(2,3), b(2,3)
- a = 1
- b = 1
- b(2,2) = 2
- print *, all(a .eq. b, 1)
- print *, all(a .eq. b, 2)
- end subroutine section
-end program test_all
-@end smallexample
-@end table
-
-
-
-@node ALLOCATED
-@section @code{ALLOCATED} --- Status of an allocatable entity
-@fnindex ALLOCATED
-@cindex allocation, status
-
-@table @asis
-@item @emph{Description}:
-@code{ALLOCATED(ARRAY)} and @code{ALLOCATED(SCALAR)} check the allocation
-status of @var{ARRAY} and @var{SCALAR}, respectively.
-
-@item @emph{Standard}:
-Fortran 90 and later. Note, the @code{SCALAR=} keyword and allocatable
-scalar entities are available in Fortran 2003 and later.
-
-@item @emph{Class}:
-Inquiry function
-
-@item @emph{Syntax}:
-@multitable @columnfractions .80
-@item @code{RESULT = ALLOCATED(ARRAY)}
-@item @code{RESULT = ALLOCATED(SCALAR)}
-@end multitable
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{ARRAY} @tab The argument shall be an @code{ALLOCATABLE} array.
-@item @var{SCALAR} @tab The argument shall be an @code{ALLOCATABLE} scalar.
-@end multitable
-
-@item @emph{Return value}:
-The return value is a scalar @code{LOGICAL} with the default logical
-kind type parameter. If the argument is allocated, then the result is
-@code{.TRUE.}; otherwise, it returns @code{.FALSE.}
-
-@item @emph{Example}:
-@smallexample
-program test_allocated
- integer :: i = 4
- real(4), allocatable :: x(:)
- if (.not. allocated(x)) allocate(x(i))
-end program test_allocated
-@end smallexample
-@end table
-
-
-
-@node AND
-@section @code{AND} --- Bitwise logical AND
-@fnindex AND
-@cindex bitwise logical and
-@cindex logical and, bitwise
-
-@table @asis
-@item @emph{Description}:
-Bitwise logical @code{AND}.
-
-This intrinsic routine is provided for backwards compatibility with
-GNU Fortran 77. For integer arguments, programmers should consider
-the use of the @ref{IAND} intrinsic defined by the Fortran standard.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Function
-
-@item @emph{Syntax}:
-@code{RESULT = AND(I, J)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{I} @tab The type shall be either a scalar @code{INTEGER}
-type or a scalar @code{LOGICAL} type or a boz-literal-constant.
-@item @var{J} @tab The type shall be the same as the type of @var{I} or
-a boz-literal-constant. @var{I} and @var{J} shall not both be
-boz-literal-constants. If either @var{I} or @var{J} is a
-boz-literal-constant, then the other argument must be a scalar @code{INTEGER}.
-@end multitable
-
-@item @emph{Return value}:
-The return type is either a scalar @code{INTEGER} or a scalar
-@code{LOGICAL}. If the kind type parameters differ, then the
-smaller kind type is implicitly converted to larger kind, and the
-return has the larger kind. A boz-literal-constant is
-converted to an @code{INTEGER} with the kind type parameter of
-the other argument as-if a call to @ref{INT} occurred.
-
-@item @emph{Example}:
-@smallexample
-PROGRAM test_and
- LOGICAL :: T = .TRUE., F = .FALSE.
- INTEGER :: a, b
- DATA a / Z'F' /, b / Z'3' /
-
- WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F)
- WRITE (*,*) AND(a, b)
-END PROGRAM
-@end smallexample
-
-@item @emph{See also}:
-Fortran 95 elemental function: @gol
-@ref{IAND}
-@end table
-
-
-
-@node ANINT
-@section @code{ANINT} --- Nearest whole number
-@fnindex ANINT
-@fnindex DNINT
-@cindex ceiling
-@cindex rounding, ceiling
-
-@table @asis
-@item @emph{Description}:
-@code{ANINT(A [, KIND])} rounds its argument to the nearest whole number.
-
-@item @emph{Standard}:
-Fortran 77 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = ANINT(A [, KIND])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{A} @tab The type of the argument shall be @code{REAL}.
-@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
-expression indicating the kind parameter of the result.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type real with the kind type parameter of the
-argument if the optional @var{KIND} is absent; otherwise, the kind
-type parameter will be given by @var{KIND}. If @var{A} is greater than
-zero, @code{ANINT(A)} returns @code{AINT(X+0.5)}. If @var{A} is
-less than or equal to zero then it returns @code{AINT(X-0.5)}.
-
-@item @emph{Example}:
-@smallexample
-program test_anint
- real(4) x4
- real(8) x8
- x4 = 1.234E0_4
- x8 = 4.321_8
- print *, anint(x4), dnint(x8)
- x8 = anint(x4,8)
-end program test_anint
-@end smallexample
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .23 .20 .33
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{ANINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
-@item @code{DNINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
-@end multitable
-@end table
-
-
-
-@node ANY
-@section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true
-@fnindex ANY
-@cindex array, apply condition
-@cindex array, condition testing
-
-@table @asis
-@item @emph{Description}:
-@code{ANY(MASK [, DIM])} determines if any of the values in the logical array
-@var{MASK} along dimension @var{DIM} are @code{.TRUE.}.
-
-@item @emph{Standard}:
-Fortran 90 and later
-
-@item @emph{Class}:
-Transformational function
-
-@item @emph{Syntax}:
-@code{RESULT = ANY(MASK [, DIM])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
-it shall not be scalar.
-@item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
-with a value that lies between one and the rank of @var{MASK}.
-@end multitable
-
-@item @emph{Return value}:
-@code{ANY(MASK)} returns a scalar value of type @code{LOGICAL} where
-the kind type parameter is the same as the kind type parameter of
-@var{MASK}. If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns
-an array with the rank of @var{MASK} minus 1. The shape is determined from
-the shape of @var{MASK} where the @var{DIM} dimension is elided.
-
-@table @asis
-@item (A)
-@code{ANY(MASK)} is true if any element of @var{MASK} is true;
-otherwise, it is false. It also is false if @var{MASK} has zero size.
-@item (B)
-If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent
-to @code{ANY(MASK)}. If the rank is greater than one, then @code{ANY(MASK,DIM)}
-is determined by applying @code{ANY} to the array sections.
-@end table
-
-@item @emph{Example}:
-@smallexample
-program test_any
- logical l
- l = any((/.true., .true., .true./))
- print *, l
- call section
- contains
- subroutine section
- integer a(2,3), b(2,3)
- a = 1
- b = 1
- b(2,2) = 2
- print *, any(a .eq. b, 1)
- print *, any(a .eq. b, 2)
- end subroutine section
-end program test_any
-@end smallexample
-@end table
-
-
-
-@node ASIN
-@section @code{ASIN} --- Arcsine function
-@fnindex ASIN
-@fnindex DASIN
-@cindex trigonometric function, sine, inverse
-@cindex sine, inverse
-
-@table @asis
-@item @emph{Description}:
-@code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}).
-
-@item @emph{Standard}:
-Fortran 77 and later, for a complex argument Fortran 2008 or later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = ASIN(X)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is
-less than or equal to one - or be @code{COMPLEX}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of the same type and kind as @var{X}.
-The real part of the result is in radians and lies in the range
-@math{-\pi/2 \leq \Re \asin(x) \leq \pi/2}.
-
-@item @emph{Example}:
-@smallexample
-program test_asin
- real(8) :: x = 0.866_8
- x = asin(x)
-end program test_asin
-@end smallexample
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .23 .20 .33
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{ASIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
-@item @code{DASIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
-@end multitable
-
-@item @emph{See also}:
-Inverse function: @gol
-@ref{SIN} @gol
-Degrees function: @gol
-@ref{ASIND}
-@end table
-
-
-
-@node ASIND
-@section @code{ASIND} --- Arcsine function, degrees
-@fnindex ASIND
-@fnindex DASIND
-@cindex trigonometric function, sine, inverse, degrees
-@cindex sine, inverse, degrees
-
-@table @asis
-@item @emph{Description}:
-@code{ASIND(X)} computes the arcsine of its @var{X} in degrees (inverse of
-@code{SIND(X)}).
-
-This function is for compatibility only and should be avoided in favor of
-standard constructs wherever possible.
-
-@item @emph{Standard}:
-GNU extension, enabled with @option{-fdec-math}.
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = ASIND(X)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is
-less than or equal to one - or be @code{COMPLEX}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of the same type and kind as @var{X}.
-The real part of the result is in degrees and lies in the range
-@math{-90 \leq \Re \asin(x) \leq 90}.
-
-@item @emph{Example}:
-@smallexample
-program test_asind
- real(8) :: x = 0.866_8
- x = asind(x)
-end program test_asind
-@end smallexample
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .23 .20 .33
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{ASIND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension
-@item @code{DASIND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
-@end multitable
-
-@item @emph{See also}:
-Inverse function: @gol
-@ref{SIND} @gol
-Radians function: @gol
-@ref{ASIN}
-@end table
-
-
-
-@node ASINH
-@section @code{ASINH} --- Inverse hyperbolic sine function
-@fnindex ASINH
-@fnindex DASINH
-@cindex area hyperbolic sine
-@cindex inverse hyperbolic sine
-@cindex hyperbolic function, sine, inverse
-@cindex sine, hyperbolic, inverse
-
-@table @asis
-@item @emph{Description}:
-@code{ASINH(X)} computes the inverse hyperbolic sine of @var{X}.
-
-@item @emph{Standard}:
-Fortran 2008 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = ASINH(X)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of the same type and kind as @var{X}. If @var{X} is
-complex, the imaginary part of the result is in radians and lies between
-@math{-\pi/2 \leq \Im \asinh(x) \leq \pi/2}.
-
-@item @emph{Example}:
-@smallexample
-PROGRAM test_asinh
- REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
- WRITE (*,*) ASINH(x)
-END PROGRAM
-@end smallexample
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .23 .20 .33
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{DASINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension.
-@end multitable
-
-@item @emph{See also}:
-Inverse function: @gol
-@ref{SINH}
-@end table
-
-
-
-@node ASSOCIATED
-@section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair
-@fnindex ASSOCIATED
-@cindex pointer, status
-@cindex association status
-
-@table @asis
-@item @emph{Description}:
-@code{ASSOCIATED(POINTER [, TARGET])} determines the status of the pointer
-@var{POINTER} or if @var{POINTER} is associated with the target @var{TARGET}.
-
-@item @emph{Standard}:
-Fortran 90 and later
-
-@item @emph{Class}:
-Inquiry function
-
-@item @emph{Syntax}:
-@code{RESULT = ASSOCIATED(POINTER [, TARGET])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{POINTER} @tab @var{POINTER} shall have the @code{POINTER} attribute
-and it can be of any type.
-@item @var{TARGET} @tab (Optional) @var{TARGET} shall be a pointer or
-a target. It must have the same type, kind type parameter, and
-array rank as @var{POINTER}.
-@end multitable
-The association status of neither @var{POINTER} nor @var{TARGET} shall be
-undefined.
-
-@item @emph{Return value}:
-@code{ASSOCIATED(POINTER)} returns a scalar value of type @code{LOGICAL(4)}.
-There are several cases:
-@table @asis
-@item (A) When the optional @var{TARGET} is not present then
-@code{ASSOCIATED(POINTER)} is true if @var{POINTER} is associated with a target; otherwise, it returns false.
-@item (B) If @var{TARGET} is present and a scalar target, the result is true if
-@var{TARGET} is not a zero-sized storage sequence and the target associated with @var{POINTER} occupies the same storage units. If @var{POINTER} is
-disassociated, the result is false.
-@item (C) If @var{TARGET} is present and an array target, the result is true if
-@var{TARGET} and @var{POINTER} have the same shape, are not zero-sized arrays,
-are arrays whose elements are not zero-sized storage sequences, and
-@var{TARGET} and @var{POINTER} occupy the same storage units in array element
-order.
-As in case(B), the result is false, if @var{POINTER} is disassociated.
-@item (D) If @var{TARGET} is present and an scalar pointer, the result is true
-if @var{TARGET} is associated with @var{POINTER}, the target associated with
-@var{TARGET} are not zero-sized storage sequences and occupy the same storage
-units.
-The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
-@item (E) If @var{TARGET} is present and an array pointer, the result is true if
-target associated with @var{POINTER} and the target associated with @var{TARGET}
-have the same shape, are not zero-sized arrays, are arrays whose elements are
-not zero-sized storage sequences, and @var{TARGET} and @var{POINTER} occupy
-the same storage units in array element order.
-The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
-@end table
-
-@item @emph{Example}:
-@smallexample
-program test_associated
- implicit none
- real, target :: tgt(2) = (/1., 2./)
- real, pointer :: ptr(:)
- ptr => tgt
- if (associated(ptr) .eqv. .false.) call abort
- if (associated(ptr,tgt) .eqv. .false.) call abort
-end program test_associated
-@end smallexample
-
-@item @emph{See also}:
-@ref{NULL}
-@end table
-
-
-
-@node ATAN
-@section @code{ATAN} --- Arctangent function
-@fnindex ATAN
-@fnindex DATAN
-@cindex trigonometric function, tangent, inverse
-@cindex tangent, inverse
-
-@table @asis
-@item @emph{Description}:
-@code{ATAN(X)} computes the arctangent of @var{X}.
-
-@item @emph{Standard}:
-Fortran 77 and later, for a complex argument and for two arguments
-Fortran 2008 or later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@multitable @columnfractions .80
-@item @code{RESULT = ATAN(X)}
-@item @code{RESULT = ATAN(Y, X)}
-@end multitable
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX};
-if @var{Y} is present, @var{X} shall be REAL.
-@item @var{Y} @tab The type and kind type parameter shall be the same as @var{X}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of the same type and kind as @var{X}.
-If @var{Y} is present, the result is identical to @code{ATAN2(Y,X)}.
-Otherwise, it the arcus tangent of @var{X}, where the real part of
-the result is in radians and lies in the range
-@math{-\pi/2 \leq \Re \atan(x) \leq \pi/2}.
-
-@item @emph{Example}:
-@smallexample
-program test_atan
- real(8) :: x = 2.866_8
- x = atan(x)
-end program test_atan
-@end smallexample
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .23 .20 .33
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{ATAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
-@item @code{DATAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
-@end multitable
-
-@item @emph{See also}:
-Inverse function: @gol
-@ref{TAN} @gol
-Degrees function: @gol
-@ref{ATAND}
-@end table
-
-
-
-@node ATAND
-@section @code{ATAND} --- Arctangent function, degrees
-@fnindex ATAND
-@fnindex DATAND
-@cindex trigonometric function, tangent, inverse, degrees
-@cindex tangent, inverse, degrees
-
-@table @asis
-@item @emph{Description}:
-@code{ATAND(X)} computes the arctangent of @var{X} in degrees (inverse of
-@ref{TAND}).
-
-This function is for compatibility only and should be avoided in favor of
-standard constructs wherever possible.
-
-@item @emph{Standard}:
-GNU extension, enabled with @option{-fdec-math}.
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@multitable @columnfractions .80
-@item @code{RESULT = ATAND(X)}
-@item @code{RESULT = ATAND(Y, X)}
-@end multitable
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX};
-if @var{Y} is present, @var{X} shall be REAL.
-@item @var{Y} @tab The type and kind type parameter shall be the same as @var{X}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of the same type and kind as @var{X}.
-If @var{Y} is present, the result is identical to @code{ATAND2(Y,X)}.
-Otherwise, it is the arcus tangent of @var{X}, where the real part of
-the result is in degrees and lies in the range
-@math{-90 \leq \Re \atand(x) \leq 90}.
-
-@item @emph{Example}:
-@smallexample
-program test_atand
- real(8) :: x = 2.866_8
- x = atand(x)
-end program test_atand
-@end smallexample
-
-@item @emph{Specific names}:
-@multitable @columnfractions .23 .23 .20 .30
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{ATAND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension
-@item @code{DATAND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
-@end multitable
-
-@item @emph{See also}:
-Inverse function: @gol
-@ref{TAND} @gol
-Radians function: @gol
-@ref{ATAN}
-@end table
-
-
-
-@node ATAN2
-@section @code{ATAN2} --- Arctangent function
-@fnindex ATAN2
-@fnindex DATAN2
-@cindex trigonometric function, tangent, inverse
-@cindex tangent, inverse
-
-@table @asis
-@item @emph{Description}:
-@code{ATAN2(Y, X)} computes the principal value of the argument
-function of the complex number @math{X + i Y}. This function can
-be used to transform from Cartesian into polar coordinates and
-allows to determine the angle in the correct quadrant.
-
-@item @emph{Standard}:
-Fortran 77 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = ATAN2(Y, X)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{Y} @tab The type shall be @code{REAL}.
-@item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
-If @var{Y} is zero, then @var{X} must be nonzero.
-@end multitable
-
-@item @emph{Return value}:
-The return value has the same type and kind type parameter as @var{Y}. It
-is the principal value of the complex number @math{X + i Y}. If @var{X}
-is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}.
-The sign is positive if @var{Y} is positive. If @var{Y} is zero, then
-the return value is zero if @var{X} is strictly positive, @math{\pi} if
-@var{X} is negative and @var{Y} is positive zero (or the processor does
-not handle signed zeros), and @math{-\pi} if @var{X} is negative and
-@var{Y} is negative zero. Finally, if @var{X} is zero, then the
-magnitude of the result is @math{\pi/2}.
-
-@item @emph{Example}:
-@smallexample
-program test_atan2
- real(4) :: x = 1.e0_4, y = 0.5e0_4
- x = atan2(y,x)
-end program test_atan2
-@end smallexample
-
-@item @emph{Specific names}:
-@multitable @columnfractions .22 .22 .20 .32
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{ATAN2(X, Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
-@item @code{DATAN2(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
-@end multitable
-
-@item @emph{See also}:
-Alias: @gol
-@ref{ATAN} @gol
-Degrees function: @gol
-@ref{ATAN2D}
-@end table
-
-
-
-@node ATAN2D
-@section @code{ATAN2D} --- Arctangent function, degrees
-@fnindex ATAN2D
-@fnindex DATAN2D
-@cindex trigonometric function, tangent, inverse, degrees
-@cindex tangent, inverse, degrees
-
-@table @asis
-@item @emph{Description}:
-@code{ATAN2D(Y, X)} computes the principal value of the argument
-function of the complex number @math{X + i Y} in degrees. This function can
-be used to transform from Cartesian into polar coordinates and
-allows to determine the angle in the correct quadrant.
-
-This function is for compatibility only and should be avoided in favor of
-standard constructs wherever possible.
-
-@item @emph{Standard}:
-GNU extension, enabled with @option{-fdec-math}.
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = ATAN2D(Y, X)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{Y} @tab The type shall be @code{REAL}.
-@item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
-If @var{Y} is zero, then @var{X} must be nonzero.
-@end multitable
-
-@item @emph{Return value}:
-The return value has the same type and kind type parameter as @var{Y}. It
-is the principal value of the complex number @math{X + i Y}. If @var{X}
-is nonzero, then it lies in the range @math{-180 \le \atan (x) \leq 180}.
-The sign is positive if @var{Y} is positive. If @var{Y} is zero, then
-the return value is zero if @var{X} is strictly positive, @math{180} if
-@var{X} is negative and @var{Y} is positive zero (or the processor does
-not handle signed zeros), and @math{-180} if @var{X} is negative and
-@var{Y} is negative zero. Finally, if @var{X} is zero, then the
-magnitude of the result is @math{90}.
-
-@item @emph{Example}:
-@smallexample
-program test_atan2d
- real(4) :: x = 1.e0_4, y = 0.5e0_4
- x = atan2d(y,x)
-end program test_atan2d
-@end smallexample
-
-@item @emph{Specific names}:
-@multitable @columnfractions .23 .23 .20 .30
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{ATAN2D(X, Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab GNU extension
-@item @code{DATAN2D(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab GNU extension
-@end multitable
-
-@item @emph{See also}:
-Alias: @gol
-@ref{ATAND} @gol
-Radians function: @gol
-@ref{ATAN2}
-@end table
-
-
-
-@node ATANH
-@section @code{ATANH} --- Inverse hyperbolic tangent function
-@fnindex ATANH
-@fnindex DATANH
-@cindex area hyperbolic tangent
-@cindex inverse hyperbolic tangent
-@cindex hyperbolic function, tangent, inverse
-@cindex tangent, hyperbolic, inverse
-
-@table @asis
-@item @emph{Description}:
-@code{ATANH(X)} computes the inverse hyperbolic tangent of @var{X}.
-
-@item @emph{Standard}:
-Fortran 2008 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = ATANH(X)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
-@end multitable
-
-@item @emph{Return value}:
-The return value has same type and kind as @var{X}. If @var{X} is
-complex, the imaginary part of the result is in radians and lies between
-@math{-\pi/2 \leq \Im \atanh(x) \leq \pi/2}.
-
-@item @emph{Example}:
-@smallexample
-PROGRAM test_atanh
- REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
- WRITE (*,*) ATANH(x)
-END PROGRAM
-@end smallexample
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .23 .20 .33
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{DATANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
-@end multitable
-
-@item @emph{See also}:
-Inverse function: @gol
-@ref{TANH}
-@end table
-
-
-
-@node ATOMIC_ADD
-@section @code{ATOMIC_ADD} --- Atomic ADD operation
-@fnindex ATOMIC_ADD
-@cindex Atomic subroutine, add
-
-@table @asis
-@item @emph{Description}:
-@code{ATOMIC_ADD(ATOM, VALUE)} atomically adds the value of @var{VALUE} to the
-variable @var{ATOM}. When @var{STAT} is present and the invocation was
-successful, it is assigned the value 0. If it is present and the invocation
-has failed, it is assigned a positive value; in particular, for a coindexed
-@var{ATOM}, if the remote image has stopped, it is assigned the value of
-@code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
-failed, the value @code{STAT_FAILED_IMAGE}.
-
-@item @emph{Standard}:
-TS 18508 or later
-
-@item @emph{Class}:
-Atomic subroutine
-
-@item @emph{Syntax}:
-@code{CALL ATOMIC_ADD (ATOM, VALUE [, STAT])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
-type with @code{ATOMIC_INT_KIND} kind.
-@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
-is different, the value is converted to the kind of @var{ATOM}.
-@item @var{STAT} @tab (optional) Scalar default-kind integer variable.
-@end multitable
-
-@item @emph{Example}:
-@smallexample
-program atomic
- use iso_fortran_env
- integer(atomic_int_kind) :: atom[*]
- call atomic_add (atom[1], this_image())
-end program atomic
-@end smallexample
-
-@item @emph{See also}:
-@ref{ATOMIC_DEFINE}, @gol
-@ref{ATOMIC_FETCH_ADD}, @gol
-@ref{ISO_FORTRAN_ENV}, @gol
-@ref{ATOMIC_AND}, @gol
-@ref{ATOMIC_OR}, @gol
-@ref{ATOMIC_XOR}
-@end table
-
-
-
-
-@node ATOMIC_AND
-@section @code{ATOMIC_AND} --- Atomic bitwise AND operation
-@fnindex ATOMIC_AND
-@cindex Atomic subroutine, AND
-
-@table @asis
-@item @emph{Description}:
-@code{ATOMIC_AND(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise
-AND between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present
-and the invocation was successful, it is assigned the value 0. If it is present
-and the invocation has failed, it is assigned a positive value; in particular,
-for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the
-value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote
-image has failed, the value @code{STAT_FAILED_IMAGE}.
-
-@item @emph{Standard}:
-TS 18508 or later
-
-@item @emph{Class}:
-Atomic subroutine
-
-@item @emph{Syntax}:
-@code{CALL ATOMIC_AND (ATOM, VALUE [, STAT])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
-type with @code{ATOMIC_INT_KIND} kind.
-@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
-is different, the value is converted to the kind of @var{ATOM}.
-@item @var{STAT} @tab (optional) Scalar default-kind integer variable.
-@end multitable
-
-@item @emph{Example}:
-@smallexample
-program atomic
- use iso_fortran_env
- integer(atomic_int_kind) :: atom[*]
- call atomic_and (atom[1], int(b'10100011101'))
-end program atomic
-@end smallexample
-
-@item @emph{See also}:
-@ref{ATOMIC_DEFINE}, @gol
-@ref{ATOMIC_FETCH_AND}, @gol
-@ref{ISO_FORTRAN_ENV}, @gol
-@ref{ATOMIC_ADD}, @gol
-@ref{ATOMIC_OR}, @gol
-@ref{ATOMIC_XOR}
-@end table
-
-
-
-@node ATOMIC_CAS
-@section @code{ATOMIC_CAS} --- Atomic compare and swap
-@fnindex ATOMIC_DEFINE
-@cindex Atomic subroutine, compare and swap
-
-@table @asis
-@item @emph{Description}:
-@code{ATOMIC_CAS} compares the variable @var{ATOM} with the value of
-@var{COMPARE}; if the value is the same, @var{ATOM} is set to the value
-of @var{NEW}. Additionally, @var{OLD} is set to the value of @var{ATOM}
-that was used for the comparison. When @var{STAT} is present and the invocation
-was successful, it is assigned the value 0. If it is present and the invocation
-has failed, it is assigned a positive value; in particular, for a coindexed
-@var{ATOM}, if the remote image has stopped, it is assigned the value of
-@code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
-failed, the value @code{STAT_FAILED_IMAGE}.
-
-@item @emph{Standard}:
-TS 18508 or later
-
-@item @emph{Class}:
-Atomic subroutine
-
-@item @emph{Syntax}:
-@code{CALL ATOMIC_CAS (ATOM, OLD, COMPARE, NEW [, STAT])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer
-type with @code{ATOMIC_INT_KIND} kind or logical type with
-@code{ATOMIC_LOGICAL_KIND} kind.
-@item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
-@item @var{COMPARE} @tab Scalar variable of the same type and kind as
-@var{ATOM}.
-@item @var{NEW} @tab Scalar variable of the same type as @var{ATOM}. If kind
-is different, the value is converted to the kind of @var{ATOM}.
-@item @var{STAT} @tab (optional) Scalar default-kind integer variable.
-@end multitable
-
-@item @emph{Example}:
-@smallexample
-program atomic
- use iso_fortran_env
- logical(atomic_logical_kind) :: atom[*], prev
- call atomic_cas (atom[1], prev, .false., .true.))
-end program atomic
-@end smallexample
-
-@item @emph{See also}:
-@ref{ATOMIC_DEFINE}, @gol
-@ref{ATOMIC_REF}, @gol
-@ref{ISO_FORTRAN_ENV}
-@end table
-
-
-
-@node ATOMIC_DEFINE
-@section @code{ATOMIC_DEFINE} --- Setting a variable atomically
-@fnindex ATOMIC_DEFINE
-@cindex Atomic subroutine, define
-
-@table @asis
-@item @emph{Description}:
-@code{ATOMIC_DEFINE(ATOM, VALUE)} defines the variable @var{ATOM} with the value
-@var{VALUE} atomically. When @var{STAT} is present and the invocation was
-successful, it is assigned the value 0. If it is present and the invocation
-has failed, it is assigned a positive value; in particular, for a coindexed
-@var{ATOM}, if the remote image has stopped, it is assigned the value of
-@code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
-failed, the value @code{STAT_FAILED_IMAGE}.
-
-@item @emph{Standard}:
-Fortran 2008 and later; with @var{STAT}, TS 18508 or later
-
-@item @emph{Class}:
-Atomic subroutine
-
-@item @emph{Syntax}:
-@code{CALL ATOMIC_DEFINE (ATOM, VALUE [, STAT])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer
-type with @code{ATOMIC_INT_KIND} kind or logical type with
-@code{ATOMIC_LOGICAL_KIND} kind.
-
-@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
-is different, the value is converted to the kind of @var{ATOM}.
-@item @var{STAT} @tab (optional) Scalar default-kind integer variable.
-@end multitable
-
-@item @emph{Example}:
-@smallexample
-program atomic
- use iso_fortran_env
- integer(atomic_int_kind) :: atom[*]
- call atomic_define (atom[1], this_image())
-end program atomic
-@end smallexample
-
-@item @emph{See also}:
-@ref{ATOMIC_REF}, @gol
-@ref{ATOMIC_CAS}, @gol
-@ref{ISO_FORTRAN_ENV}, @gol
-@ref{ATOMIC_ADD}, @gol
-@ref{ATOMIC_AND}, @gol
-@ref{ATOMIC_OR}, @gol
-@ref{ATOMIC_XOR}
-@end table
-
-
-
-@node ATOMIC_FETCH_ADD
-@section @code{ATOMIC_FETCH_ADD} --- Atomic ADD operation with prior fetch
-@fnindex ATOMIC_FETCH_ADD
-@cindex Atomic subroutine, ADD with fetch
-
-@table @asis
-@item @emph{Description}:
-@code{ATOMIC_FETCH_ADD(ATOM, VALUE, OLD)} atomically stores the value of
-@var{ATOM} in @var{OLD} and adds the value of @var{VALUE} to the
-variable @var{ATOM}. When @var{STAT} is present and the invocation was
-successful, it is assigned the value 0. If it is present and the invocation
-has failed, it is assigned a positive value; in particular, for a coindexed
-@var{ATOM}, if the remote image has stopped, it is assigned the value of
-@code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
-failed, the value @code{STAT_FAILED_IMAGE}.
-
-@item @emph{Standard}:
-TS 18508 or later
-
-@item @emph{Class}:
-Atomic subroutine
-
-@item @emph{Syntax}:
-@code{CALL ATOMIC_FETCH_ADD (ATOM, VALUE, old [, STAT])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
-type with @code{ATOMIC_INT_KIND} kind.
-@code{ATOMIC_LOGICAL_KIND} kind.
-
-@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
-is different, the value is converted to the kind of @var{ATOM}.
-@item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
-@item @var{STAT} @tab (optional) Scalar default-kind integer variable.
-@end multitable
-
-@item @emph{Example}:
-@smallexample
-program atomic
- use iso_fortran_env
- integer(atomic_int_kind) :: atom[*], old
- call atomic_add (atom[1], this_image(), old)
-end program atomic
-@end smallexample
-
-@item @emph{See also}:
-@ref{ATOMIC_DEFINE}, @gol
-@ref{ATOMIC_ADD}, @gol
-@ref{ISO_FORTRAN_ENV}, @gol
-@ref{ATOMIC_FETCH_AND}, @gol
-@ref{ATOMIC_FETCH_OR}, @gol
-@ref{ATOMIC_FETCH_XOR}
-@end table
-
-
-
-@node ATOMIC_FETCH_AND
-@section @code{ATOMIC_FETCH_AND} --- Atomic bitwise AND operation with prior fetch
-@fnindex ATOMIC_FETCH_AND
-@cindex Atomic subroutine, AND with fetch
-
-@table @asis
-@item @emph{Description}:
-@code{ATOMIC_AND(ATOM, VALUE)} atomically stores the value of @var{ATOM} in
-@var{OLD} and defines @var{ATOM} with the bitwise AND between the values of
-@var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invocation was
-successful, it is assigned the value 0. If it is present and the invocation has
-failed, it is assigned a positive value; in particular, for a coindexed
-@var{ATOM}, if the remote image has stopped, it is assigned the value of
-@code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
-failed, the value @code{STAT_FAILED_IMAGE}.
-
-@item @emph{Standard}:
-TS 18508 or later
-
-@item @emph{Class}:
-Atomic subroutine
-
-@item @emph{Syntax}:
-@code{CALL ATOMIC_FETCH_AND (ATOM, VALUE, OLD [, STAT])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
-type with @code{ATOMIC_INT_KIND} kind.
-@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
-is different, the value is converted to the kind of @var{ATOM}.
-@item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
-@item @var{STAT} @tab (optional) Scalar default-kind integer variable.
-@end multitable
-
-@item @emph{Example}:
-@smallexample
-program atomic
- use iso_fortran_env
- integer(atomic_int_kind) :: atom[*], old
- call atomic_fetch_and (atom[1], int(b'10100011101'), old)
-end program atomic
-@end smallexample
-
-@item @emph{See also}:
-@ref{ATOMIC_DEFINE}, @gol
-@ref{ATOMIC_AND}, @gol
-@ref{ISO_FORTRAN_ENV}, @gol
-@ref{ATOMIC_FETCH_ADD}, @gol
-@ref{ATOMIC_FETCH_OR}, @gol
-@ref{ATOMIC_FETCH_XOR}
-@end table
-
-
-
-@node ATOMIC_FETCH_OR
-@section @code{ATOMIC_FETCH_OR} --- Atomic bitwise OR operation with prior fetch
-@fnindex ATOMIC_FETCH_OR
-@cindex Atomic subroutine, OR with fetch
-
-@table @asis
-@item @emph{Description}:
-@code{ATOMIC_OR(ATOM, VALUE)} atomically stores the value of @var{ATOM} in
-@var{OLD} and defines @var{ATOM} with the bitwise OR between the values of
-@var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invocation was
-successful, it is assigned the value 0. If it is present and the invocation has
-failed, it is assigned a positive value; in particular, for a coindexed
-@var{ATOM}, if the remote image has stopped, it is assigned the value of
-@code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
-failed, the value @code{STAT_FAILED_IMAGE}.
-
-@item @emph{Standard}:
-TS 18508 or later
-
-@item @emph{Class}:
-Atomic subroutine
-
-@item @emph{Syntax}:
-@code{CALL ATOMIC_FETCH_OR (ATOM, VALUE, OLD [, STAT])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
-type with @code{ATOMIC_INT_KIND} kind.
-@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
-is different, the value is converted to the kind of @var{ATOM}.
-@item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
-@item @var{STAT} @tab (optional) Scalar default-kind integer variable.
-@end multitable
-
-@item @emph{Example}:
-@smallexample
-program atomic
- use iso_fortran_env
- integer(atomic_int_kind) :: atom[*], old
- call atomic_fetch_or (atom[1], int(b'10100011101'), old)
-end program atomic
-@end smallexample
-
-@item @emph{See also}:
-@ref{ATOMIC_DEFINE}, @gol
-@ref{ATOMIC_OR}, @gol
-@ref{ISO_FORTRAN_ENV}, @gol
-@ref{ATOMIC_FETCH_ADD}, @gol
-@ref{ATOMIC_FETCH_AND}, @gol
-@ref{ATOMIC_FETCH_XOR}
-@end table
-
-
-
-@node ATOMIC_FETCH_XOR
-@section @code{ATOMIC_FETCH_XOR} --- Atomic bitwise XOR operation with prior fetch
-@fnindex ATOMIC_FETCH_XOR
-@cindex Atomic subroutine, XOR with fetch
-
-@table @asis
-@item @emph{Description}:
-@code{ATOMIC_XOR(ATOM, VALUE)} atomically stores the value of @var{ATOM} in
-@var{OLD} and defines @var{ATOM} with the bitwise XOR between the values of
-@var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invocation was
-successful, it is assigned the value 0. If it is present and the invocation has
-failed, it is assigned a positive value; in particular, for a coindexed
-@var{ATOM}, if the remote image has stopped, it is assigned the value of
-@code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
-failed, the value @code{STAT_FAILED_IMAGE}.
-
-@item @emph{Standard}:
-TS 18508 or later
-
-@item @emph{Class}:
-Atomic subroutine
-
-@item @emph{Syntax}:
-@code{CALL ATOMIC_FETCH_XOR (ATOM, VALUE, OLD [, STAT])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
-type with @code{ATOMIC_INT_KIND} kind.
-@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
-is different, the value is converted to the kind of @var{ATOM}.
-@item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
-@item @var{STAT} @tab (optional) Scalar default-kind integer variable.
-@end multitable
-
-@item @emph{Example}:
-@smallexample
-program atomic
- use iso_fortran_env
- integer(atomic_int_kind) :: atom[*], old
- call atomic_fetch_xor (atom[1], int(b'10100011101'), old)
-end program atomic
-@end smallexample
-
-@item @emph{See also}:
-@ref{ATOMIC_DEFINE}, @gol
-@ref{ATOMIC_XOR}, @gol
-@ref{ISO_FORTRAN_ENV}, @gol
-@ref{ATOMIC_FETCH_ADD}, @gol
-@ref{ATOMIC_FETCH_AND}, @gol
-@ref{ATOMIC_FETCH_OR}
-@end table
-
-
-
-@node ATOMIC_OR
-@section @code{ATOMIC_OR} --- Atomic bitwise OR operation
-@fnindex ATOMIC_OR
-@cindex Atomic subroutine, OR
-
-@table @asis
-@item @emph{Description}:
-@code{ATOMIC_OR(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise
-AND between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present
-and the invocation was successful, it is assigned the value 0. If it is present
-and the invocation has failed, it is assigned a positive value; in particular,
-for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the
-value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote
-image has failed, the value @code{STAT_FAILED_IMAGE}.
-
-@item @emph{Standard}:
-TS 18508 or later
-
-@item @emph{Class}:
-Atomic subroutine
-
-@item @emph{Syntax}:
-@code{CALL ATOMIC_OR (ATOM, VALUE [, STAT])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
-type with @code{ATOMIC_INT_KIND} kind.
-@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
-is different, the value is converted to the kind of @var{ATOM}.
-@item @var{STAT} @tab (optional) Scalar default-kind integer variable.
-@end multitable
-
-@item @emph{Example}:
-@smallexample
-program atomic
- use iso_fortran_env
- integer(atomic_int_kind) :: atom[*]
- call atomic_or (atom[1], int(b'10100011101'))
-end program atomic
-@end smallexample
-
-@item @emph{See also}:
-@ref{ATOMIC_DEFINE}, @gol
-@ref{ATOMIC_FETCH_OR}, @gol
-@ref{ISO_FORTRAN_ENV}, @gol
-@ref{ATOMIC_ADD}, @gol
-@ref{ATOMIC_OR}, @gol
-@ref{ATOMIC_XOR}
-@end table
-
-
-
-@node ATOMIC_REF
-@section @code{ATOMIC_REF} --- Obtaining the value of a variable atomically
-@fnindex ATOMIC_REF
-@cindex Atomic subroutine, reference
-
-@table @asis
-@item @emph{Description}:
-@code{ATOMIC_DEFINE(ATOM, VALUE)} atomically assigns the value of the
-variable @var{ATOM} to @var{VALUE}. When @var{STAT} is present and the
-invocation was successful, it is assigned the value 0. If it is present and the
-invocation has failed, it is assigned a positive value; in particular, for a
-coindexed @var{ATOM}, if the remote image has stopped, it is assigned the value
-of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image
-has failed, the value @code{STAT_FAILED_IMAGE}.
-
-
-@item @emph{Standard}:
-Fortran 2008 and later; with @var{STAT}, TS 18508 or later
-
-@item @emph{Class}:
-Atomic subroutine
-
-@item @emph{Syntax}:
-@code{CALL ATOMIC_REF(VALUE, ATOM [, STAT])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
-is different, the value is converted to the kind of @var{ATOM}.
-@item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer
-type with @code{ATOMIC_INT_KIND} kind or logical type with
-@code{ATOMIC_LOGICAL_KIND} kind.
-@item @var{STAT} @tab (optional) Scalar default-kind integer variable.
-@end multitable
-
-@item @emph{Example}:
-@smallexample
-program atomic
- use iso_fortran_env
- logical(atomic_logical_kind) :: atom[*]
- logical :: val
- call atomic_ref (atom, .false.)
- ! ...
- call atomic_ref (atom, val)
- if (val) then
- print *, "Obtained"
- end if
-end program atomic
-@end smallexample
-
-@item @emph{See also}:
-@ref{ATOMIC_DEFINE}, @gol
-@ref{ATOMIC_CAS}, @gol
-@ref{ISO_FORTRAN_ENV}, @gol
-@ref{ATOMIC_FETCH_ADD}, @gol
-@ref{ATOMIC_FETCH_AND}, @gol
-@ref{ATOMIC_FETCH_OR}, @gol
-@ref{ATOMIC_FETCH_XOR}
-@end table
-
-
-@node ATOMIC_XOR
-@section @code{ATOMIC_XOR} --- Atomic bitwise OR operation
-@fnindex ATOMIC_XOR
-@cindex Atomic subroutine, XOR
-
-@table @asis
-@item @emph{Description}:
-@code{ATOMIC_AND(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise
-XOR between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present
-and the invocation was successful, it is assigned the value 0. If it is present
-and the invocation has failed, it is assigned a positive value; in particular,
-for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the
-value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote
-image has failed, the value @code{STAT_FAILED_IMAGE}.
-
-@item @emph{Standard}:
-TS 18508 or later
-
-@item @emph{Class}:
-Atomic subroutine
-
-@item @emph{Syntax}:
-@code{CALL ATOMIC_XOR (ATOM, VALUE [, STAT])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
-type with @code{ATOMIC_INT_KIND} kind.
-@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
-is different, the value is converted to the kind of @var{ATOM}.
-@item @var{STAT} @tab (optional) Scalar default-kind integer variable.
-@end multitable
-
-@item @emph{Example}:
-@smallexample
-program atomic
- use iso_fortran_env
- integer(atomic_int_kind) :: atom[*]
- call atomic_xor (atom[1], int(b'10100011101'))
-end program atomic
-@end smallexample
-
-@item @emph{See also}:
-@ref{ATOMIC_DEFINE}, @gol
-@ref{ATOMIC_FETCH_XOR}, @gol
-@ref{ISO_FORTRAN_ENV}, @gol
-@ref{ATOMIC_ADD}, @gol
-@ref{ATOMIC_OR}, @gol
-@ref{ATOMIC_XOR}
-@end table
-
-
-@node BACKTRACE
-@section @code{BACKTRACE} --- Show a backtrace
-@fnindex BACKTRACE
-@cindex backtrace
-
-@table @asis
-@item @emph{Description}:
-@code{BACKTRACE} shows a backtrace at an arbitrary place in user code. Program
-execution continues normally afterwards. The backtrace information is printed
-to the unit corresponding to @code{ERROR_UNIT} in @code{ISO_FORTRAN_ENV}.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Subroutine
-
-@item @emph{Syntax}:
-@code{CALL BACKTRACE}
-
-@item @emph{Arguments}:
-None
-
-@item @emph{See also}:
-@ref{ABORT}
-@end table
-
-
-
-@node BESSEL_J0
-@section @code{BESSEL_J0} --- Bessel function of the first kind of order 0
-@fnindex BESSEL_J0
-@fnindex BESJ0
-@fnindex DBESJ0
-@cindex Bessel function, first kind
-
-@table @asis
-@item @emph{Description}:
-@code{BESSEL_J0(X)} computes the Bessel function of the first kind of
-order 0 of @var{X}. This function is available under the name
-@code{BESJ0} as a GNU extension.
-
-@item @emph{Standard}:
-Fortran 2008 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = BESSEL_J0(X)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab The type shall be @code{REAL}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{REAL} and lies in the
-range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}. It has the same
-kind as @var{X}.
-
-@item @emph{Example}:
-@smallexample
-program test_besj0
- real(8) :: x = 0.0_8
- x = bessel_j0(x)
-end program test_besj0
-@end smallexample
-
-@item @emph{Specific names}:
-@multitable @columnfractions .21 .22 .20 .33
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{DBESJ0(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
-@end multitable
-@end table
-
-
-
-@node BESSEL_J1
-@section @code{BESSEL_J1} --- Bessel function of the first kind of order 1
-@fnindex BESSEL_J1
-@fnindex BESJ1
-@fnindex DBESJ1
-@cindex Bessel function, first kind
-
-@table @asis
-@item @emph{Description}:
-@code{BESSEL_J1(X)} computes the Bessel function of the first kind of
-order 1 of @var{X}. This function is available under the name
-@code{BESJ1} as a GNU extension.
-
-@item @emph{Standard}:
-Fortran 2008
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = BESSEL_J1(X)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab The type shall be @code{REAL}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{REAL} and lies in the
-range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }. It has the same
-kind as @var{X}.
-
-@item @emph{Example}:
-@smallexample
-program test_besj1
- real(8) :: x = 1.0_8
- x = bessel_j1(x)
-end program test_besj1
-@end smallexample
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .23 .20 .33
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{DBESJ1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
-@end multitable
-@end table
-
-
-
-@node BESSEL_JN
-@section @code{BESSEL_JN} --- Bessel function of the first kind
-@fnindex BESSEL_JN
-@fnindex BESJN
-@fnindex DBESJN
-@cindex Bessel function, first kind
-
-@table @asis
-@item @emph{Description}:
-@code{BESSEL_JN(N, X)} computes the Bessel function of the first kind of
-order @var{N} of @var{X}. This function is available under the name
-@code{BESJN} as a GNU extension. If @var{N} and @var{X} are arrays,
-their ranks and shapes shall conform.
-
-@code{BESSEL_JN(N1, N2, X)} returns an array with the Bessel functions
-of the first kind of the orders @var{N1} to @var{N2}.
-
-@item @emph{Standard}:
-Fortran 2008 and later, negative @var{N} is allowed as GNU extension
-
-@item @emph{Class}:
-Elemental function, except for the transformational function
-@code{BESSEL_JN(N1, N2, X)}
-
-@item @emph{Syntax}:
-@multitable @columnfractions .80
-@item @code{RESULT = BESSEL_JN(N, X)}
-@item @code{RESULT = BESSEL_JN(N1, N2, X)}
-@end multitable
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER}.
-@item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}.
-@item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}.
-@item @var{X} @tab Shall be a scalar or an array of type @code{REAL};
-for @code{BESSEL_JN(N1, N2, X)} it shall be scalar.
-@end multitable
-
-@item @emph{Return value}:
-The return value is a scalar of type @code{REAL}. It has the same
-kind as @var{X}.
-
-@item @emph{Note}:
-The transformational function uses a recurrence algorithm which might,
-for some values of @var{X}, lead to different results than calls to
-the elemental function.
-
-@item @emph{Example}:
-@smallexample
-program test_besjn
- real(8) :: x = 1.0_8
- x = bessel_jn(5,x)
-end program test_besjn
-@end smallexample
-
-@item @emph{Specific names}:
-@multitable @columnfractions .22 .22 .20 .32
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{DBESJN(N, X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
-@item @tab @code{REAL(8) X} @tab @tab
-@end multitable
-@end table
-
-
-
-@node BESSEL_Y0
-@section @code{BESSEL_Y0} --- Bessel function of the second kind of order 0
-@fnindex BESSEL_Y0
-@fnindex BESY0
-@fnindex DBESY0
-@cindex Bessel function, second kind
-
-@table @asis
-@item @emph{Description}:
-@code{BESSEL_Y0(X)} computes the Bessel function of the second kind of
-order 0 of @var{X}. This function is available under the name
-@code{BESY0} as a GNU extension.
-
-@item @emph{Standard}:
-Fortran 2008 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = BESSEL_Y0(X)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab The type shall be @code{REAL}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{REAL}. It has the same kind as @var{X}.
-
-@item @emph{Example}:
-@smallexample
-program test_besy0
- real(8) :: x = 0.0_8
- x = bessel_y0(x)
-end program test_besy0
-@end smallexample
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .23 .20 .33
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{DBESY0(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
-@end multitable
-@end table
-
-
-
-@node BESSEL_Y1
-@section @code{BESSEL_Y1} --- Bessel function of the second kind of order 1
-@fnindex BESSEL_Y1
-@fnindex BESY1
-@fnindex DBESY1
-@cindex Bessel function, second kind
-
-@table @asis
-@item @emph{Description}:
-@code{BESSEL_Y1(X)} computes the Bessel function of the second kind of
-order 1 of @var{X}. This function is available under the name
-@code{BESY1} as a GNU extension.
-
-@item @emph{Standard}:
-Fortran 2008 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = BESSEL_Y1(X)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab The type shall be @code{REAL}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{REAL}. It has the same kind as @var{X}.
-
-@item @emph{Example}:
-@smallexample
-program test_besy1
- real(8) :: x = 1.0_8
- x = bessel_y1(x)
-end program test_besy1
-@end smallexample
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .23 .20 .33
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{DBESY1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
-@end multitable
-@end table
-
-
-
-@node BESSEL_YN
-@section @code{BESSEL_YN} --- Bessel function of the second kind
-@fnindex BESSEL_YN
-@fnindex BESYN
-@fnindex DBESYN
-@cindex Bessel function, second kind
-
-@table @asis
-@item @emph{Description}:
-@code{BESSEL_YN(N, X)} computes the Bessel function of the second kind of
-order @var{N} of @var{X}. This function is available under the name
-@code{BESYN} as a GNU extension. If @var{N} and @var{X} are arrays,
-their ranks and shapes shall conform.
-
-@code{BESSEL_YN(N1, N2, X)} returns an array with the Bessel functions
-of the first kind of the orders @var{N1} to @var{N2}.
-
-@item @emph{Standard}:
-Fortran 2008 and later, negative @var{N} is allowed as GNU extension
-
-@item @emph{Class}:
-Elemental function, except for the transformational function
-@code{BESSEL_YN(N1, N2, X)}
-
-@item @emph{Syntax}:
-@multitable @columnfractions .80
-@item @code{RESULT = BESSEL_YN(N, X)}
-@item @code{RESULT = BESSEL_YN(N1, N2, X)}
-@end multitable
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER} .
-@item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}.
-@item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}.
-@item @var{X} @tab Shall be a scalar or an array of type @code{REAL};
-for @code{BESSEL_YN(N1, N2, X)} it shall be scalar.
-@end multitable
-
-@item @emph{Return value}:
-The return value is a scalar of type @code{REAL}. It has the same
-kind as @var{X}.
-
-@item @emph{Note}:
-The transformational function uses a recurrence algorithm which might,
-for some values of @var{X}, lead to different results than calls to
-the elemental function.
-
-@item @emph{Example}:
-@smallexample
-program test_besyn
- real(8) :: x = 1.0_8
- x = bessel_yn(5,x)
-end program test_besyn
-@end smallexample
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .23 .20 .33
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{DBESYN(N,X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
-@item @tab @code{REAL(8) X} @tab @tab
-@end multitable
-@end table
-
-
-
-@node BGE
-@section @code{BGE} --- Bitwise greater than or equal to
-@fnindex BGE
-@cindex bitwise comparison
-
-@table @asis
-@item @emph{Description}:
-Determines whether an integral is a bitwise greater than or equal to
-another.
-
-@item @emph{Standard}:
-Fortran 2008 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = BGE(I, J)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{I} @tab Shall be of @code{INTEGER} type.
-@item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
-as @var{I}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{LOGICAL} and of the default kind.
-
-@item @emph{See also}:
-@ref{BGT}, @gol
-@ref{BLE}, @gol
-@ref{BLT}
-@end table
-
-
-
-@node BGT
-@section @code{BGT} --- Bitwise greater than
-@fnindex BGT
-@cindex bitwise comparison
-
-@table @asis
-@item @emph{Description}:
-Determines whether an integral is a bitwise greater than another.
-
-@item @emph{Standard}:
-Fortran 2008 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = BGT(I, J)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{I} @tab Shall be of @code{INTEGER} type.
-@item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
-as @var{I}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{LOGICAL} and of the default kind.
-
-@item @emph{See also}:
-@ref{BGE}, @gol
-@ref{BLE}, @gol
-@ref{BLT}
-@end table
-
-
-
-@node BIT_SIZE
-@section @code{BIT_SIZE} --- Bit size inquiry function
-@fnindex BIT_SIZE
-@cindex bits, number of
-@cindex size of a variable, in bits
-
-@table @asis
-@item @emph{Description}:
-@code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit)
-represented by the type of @var{I}. The result of @code{BIT_SIZE(I)} is
-independent of the actual value of @var{I}.
-
-@item @emph{Standard}:
-Fortran 90 and later
-
-@item @emph{Class}:
-Inquiry function
-
-@item @emph{Syntax}:
-@code{RESULT = BIT_SIZE(I)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{I} @tab The type shall be @code{INTEGER}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{INTEGER}
-
-@item @emph{Example}:
-@smallexample
-program test_bit_size
- integer :: i = 123
- integer :: size
- size = bit_size(i)
- print *, size
-end program test_bit_size
-@end smallexample
-@end table
-
-
-
-@node BLE
-@section @code{BLE} --- Bitwise less than or equal to
-@fnindex BLE
-@cindex bitwise comparison
-
-@table @asis
-@item @emph{Description}:
-Determines whether an integral is a bitwise less than or equal to
-another.
-
-@item @emph{Standard}:
-Fortran 2008 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = BLE(I, J)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{I} @tab Shall be of @code{INTEGER} type.
-@item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
-as @var{I}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{LOGICAL} and of the default kind.
-
-@item @emph{See also}:
-@ref{BGT}, @gol
-@ref{BGE}, @gol
-@ref{BLT}
-@end table
-
-
-
-@node BLT
-@section @code{BLT} --- Bitwise less than
-@fnindex BLT
-@cindex bitwise comparison
-
-@table @asis
-@item @emph{Description}:
-Determines whether an integral is a bitwise less than another.
-
-@item @emph{Standard}:
-Fortran 2008 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = BLT(I, J)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{I} @tab Shall be of @code{INTEGER} type.
-@item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
-as @var{I}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{LOGICAL} and of the default kind.
-
-@item @emph{See also}:
-@ref{BGE}, @gol
-@ref{BGT}, @gol
-@ref{BLE}
-@end table
-
-
-
-@node BTEST
-@section @code{BTEST} --- Bit test function
-@fnindex BTEST
-@fnindex BBTEST
-@fnindex BITEST
-@fnindex BJTEST
-@fnindex BKTEST
-@cindex bits, testing
-
-@table @asis
-@item @emph{Description}:
-@code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS}
-in @var{I} is set. The counting of the bits starts at 0.
-
-@item @emph{Standard}:
-Fortran 90 and later, has overloads that are GNU extensions
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = BTEST(I, POS)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{I} @tab The type shall be @code{INTEGER}.
-@item @var{POS} @tab The type shall be @code{INTEGER}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{LOGICAL}
-
-@item @emph{Example}:
-@smallexample
-program test_btest
- integer :: i = 32768 + 1024 + 64
- integer :: pos
- logical :: bool
- do pos=0,16
- bool = btest(i, pos)
- print *, pos, bool
- end do
-end program test_btest
-@end smallexample
-
-@item @emph{Specific names}:
-@multitable @columnfractions .21 .28 .18 .30
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{BTEST(I,POS)} @tab @code{INTEGER I,POS} @tab @code{LOGICAL} @tab Fortran 95 and later
-@item @code{BBTEST(I,POS)} @tab @code{INTEGER(1) I,POS} @tab @code{LOGICAL(1)} @tab GNU extension
-@item @code{BITEST(I,POS)} @tab @code{INTEGER(2) I,POS} @tab @code{LOGICAL(2)} @tab GNU extension
-@item @code{BJTEST(I,POS)} @tab @code{INTEGER(4) I,POS} @tab @code{LOGICAL(4)} @tab GNU extension
-@item @code{BKTEST(I,POS)} @tab @code{INTEGER(8) I,POS} @tab @code{LOGICAL(8)} @tab GNU extension
-@end multitable
-@end table
-
-@node C_ASSOCIATED
-@section @code{C_ASSOCIATED} --- Status of a C pointer
-@fnindex C_ASSOCIATED
-@cindex association status, C pointer
-@cindex pointer, C association status
-
-@table @asis
-@item @emph{Description}:
-@code{C_ASSOCIATED(c_ptr_1[, c_ptr_2])} determines the status of the C pointer
-@var{c_ptr_1} or if @var{c_ptr_1} is associated with the target @var{c_ptr_2}.
-
-@item @emph{Standard}:
-Fortran 2003 and later
-
-@item @emph{Class}:
-Inquiry function
-
-@item @emph{Syntax}:
-@code{RESULT = C_ASSOCIATED(c_ptr_1[, c_ptr_2])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{c_ptr_1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}.
-@item @var{c_ptr_2} @tab (Optional) Scalar of the same type as @var{c_ptr_1}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{LOGICAL}; it is @code{.false.} if either
-@var{c_ptr_1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr_2}
-point to different addresses.
-
-@item @emph{Example}:
-@smallexample
-subroutine association_test(a,b)
- use iso_c_binding, only: c_associated, c_loc, c_ptr
- implicit none
- real, pointer :: a
- type(c_ptr) :: b
- if(c_associated(b, c_loc(a))) &
- stop 'b and a do not point to same target'
-end subroutine association_test
-@end smallexample
-
-@item @emph{See also}:
-@ref{C_LOC}, @gol
-@ref{C_FUNLOC}
-@end table
-
-
-@node C_F_POINTER
-@section @code{C_F_POINTER} --- Convert C into Fortran pointer
-@fnindex C_F_POINTER
-@cindex pointer, convert C to Fortran
-
-@table @asis
-@item @emph{Description}:
-@code{C_F_POINTER(CPTR, FPTR[, SHAPE])} assigns the target of the C pointer
-@var{CPTR} to the Fortran pointer @var{FPTR} and specifies its shape.
-
-@item @emph{Standard}:
-Fortran 2003 and later
-
-@item @emph{Class}:
-Subroutine
-
-@item @emph{Syntax}:
-@code{CALL C_F_POINTER(CPTR, FPTR[, SHAPE])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{CPTR} @tab scalar of the type @code{C_PTR}. It is
-@code{INTENT(IN)}.
-@item @var{FPTR} @tab pointer interoperable with @var{cptr}. It is
-@code{INTENT(OUT)}.
-@item @var{SHAPE} @tab (Optional) Rank-one array of type @code{INTEGER}
-with @code{INTENT(IN)}. It shall be present
-if and only if @var{fptr} is an array. The size
-must be equal to the rank of @var{fptr}.
-@end multitable
-
-@item @emph{Example}:
-@smallexample
-program main
- use iso_c_binding
- implicit none
- interface
- subroutine my_routine(p) bind(c,name='myC_func')
- import :: c_ptr
- type(c_ptr), intent(out) :: p
- end subroutine
- end interface
- type(c_ptr) :: cptr
- real,pointer :: a(:)
- call my_routine(cptr)
- call c_f_pointer(cptr, a, [12])
-end program main
-@end smallexample
-
-@item @emph{See also}:
-@ref{C_LOC}, @gol
-@ref{C_F_PROCPOINTER}
-@end table
-
-
-@node C_F_PROCPOINTER
-@section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer
-@fnindex C_F_PROCPOINTER
-@cindex pointer, C address of pointers
-
-@table @asis
-@item @emph{Description}:
-@code{C_F_PROCPOINTER(CPTR, FPTR)} Assign the target of the C function pointer
-@var{CPTR} to the Fortran procedure pointer @var{FPTR}.
-
-@item @emph{Standard}:
-Fortran 2003 and later
-
-@item @emph{Class}:
-Subroutine
-
-@item @emph{Syntax}:
-@code{CALL C_F_PROCPOINTER(cptr, fptr)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{CPTR} @tab scalar of the type @code{C_FUNPTR}. It is
-@code{INTENT(IN)}.
-@item @var{FPTR} @tab procedure pointer interoperable with @var{cptr}. It is
-@code{INTENT(OUT)}.
-@end multitable
-
-@item @emph{Example}:
-@smallexample
-program main
- use iso_c_binding
- implicit none
- abstract interface
- function func(a)
- import :: c_float
- real(c_float), intent(in) :: a
- real(c_float) :: func
- end function
- end interface
- interface
- function getIterFunc() bind(c,name="getIterFunc")
- import :: c_funptr
- type(c_funptr) :: getIterFunc
- end function
- end interface
- type(c_funptr) :: cfunptr
- procedure(func), pointer :: myFunc
- cfunptr = getIterFunc()
- call c_f_procpointer(cfunptr, myFunc)
-end program main
-@end smallexample
-
-@item @emph{See also}:
-@ref{C_LOC}, @gol
-@ref{C_F_POINTER}
-@end table
-
-
-@node C_FUNLOC
-@section @code{C_FUNLOC} --- Obtain the C address of a procedure
-@fnindex C_FUNLOC
-@cindex pointer, C address of procedures
-
-@table @asis
-@item @emph{Description}:
-@code{C_FUNLOC(x)} determines the C address of the argument.
-
-@item @emph{Standard}:
-Fortran 2003 and later
-
-@item @emph{Class}:
-Inquiry function
-
-@item @emph{Syntax}:
-@code{RESULT = C_FUNLOC(x)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{x} @tab Interoperable function or pointer to such function.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{C_FUNPTR} and contains the C address
-of the argument.
-
-@item @emph{Example}:
-@smallexample
-module x
- use iso_c_binding
- implicit none
-contains
- subroutine sub(a) bind(c)
- real(c_float) :: a
- a = sqrt(a)+5.0
- end subroutine sub
-end module x
-program main
- use iso_c_binding
- use x
- implicit none
- interface
- subroutine my_routine(p) bind(c,name='myC_func')
- import :: c_funptr
- type(c_funptr), intent(in) :: p
- end subroutine
- end interface
- call my_routine(c_funloc(sub))
-end program main
-@end smallexample
-
-@item @emph{See also}:
-@ref{C_ASSOCIATED}, @gol
-@ref{C_LOC}, @gol
-@ref{C_F_POINTER}, @gol
-@ref{C_F_PROCPOINTER}
-@end table
-
-
-@node C_LOC
-@section @code{C_LOC} --- Obtain the C address of an object
-@fnindex C_LOC
-@cindex procedure pointer, convert C to Fortran
-
-@table @asis
-@item @emph{Description}:
-@code{C_LOC(X)} determines the C address of the argument.
-
-@item @emph{Standard}:
-Fortran 2003 and later
-
-@item @emph{Class}:
-Inquiry function
-
-@item @emph{Syntax}:
-@code{RESULT = C_LOC(X)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .10 .75
-@item @var{X} @tab Shall have either the POINTER or TARGET attribute. It shall not be a coindexed object. It shall either be a variable with interoperable type and kind type parameters, or be a scalar, nonpolymorphic variable with no length type parameters.
-
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{C_PTR} and contains the C address
-of the argument.
-
-@item @emph{Example}:
-@smallexample
-subroutine association_test(a,b)
- use iso_c_binding, only: c_associated, c_loc, c_ptr
- implicit none
- real, pointer :: a
- type(c_ptr) :: b
- if(c_associated(b, c_loc(a))) &
- stop 'b and a do not point to same target'
-end subroutine association_test
-@end smallexample
-
-@item @emph{See also}:
-@ref{C_ASSOCIATED}, @gol
-@ref{C_FUNLOC}, @gol
-@ref{C_F_POINTER}, @gol
-@ref{C_F_PROCPOINTER}
-@end table
-
-
-@node C_SIZEOF
-@section @code{C_SIZEOF} --- Size in bytes of an expression
-@fnindex C_SIZEOF
-@cindex expression size
-@cindex size of an expression
-
-@table @asis
-@item @emph{Description}:
-@code{C_SIZEOF(X)} calculates the number of bytes of storage the
-expression @code{X} occupies.
-
-@item @emph{Standard}:
-Fortran 2008
-
-@item @emph{Class}:
-Inquiry function of the module @code{ISO_C_BINDING}
-
-@item @emph{Syntax}:
-@code{N = C_SIZEOF(X)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab The argument shall be an interoperable data entity.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type integer and of the system-dependent kind
-@code{C_SIZE_T} (from the @code{ISO_C_BINDING} module). Its value is the
-number of bytes occupied by the argument. If the argument has the
-@code{POINTER} attribute, the number of bytes of the storage area pointed
-to is returned. If the argument is of a derived type with @code{POINTER}
-or @code{ALLOCATABLE} components, the return value does not account for
-the sizes of the data pointed to by these components.
-
-@item @emph{Example}:
-@smallexample
- use iso_c_binding
- integer(c_int) :: i
- real(c_float) :: r, s(5)
- print *, (c_sizeof(s)/c_sizeof(r) == 5)
- end
-@end smallexample
-The example will print @code{T} unless you are using a platform
-where default @code{REAL} variables are unusually padded.
-
-@item @emph{See also}:
-@ref{SIZEOF}, @gol
-@ref{STORAGE_SIZE}
-@end table
-
-
-@node CEILING
-@section @code{CEILING} --- Integer ceiling function
-@fnindex CEILING
-@cindex ceiling
-@cindex rounding, ceiling
-
-@table @asis
-@item @emph{Description}:
-@code{CEILING(A)} returns the least integer greater than or equal to @var{A}.
-
-@item @emph{Standard}:
-Fortran 95 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = CEILING(A [, KIND])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{A} @tab The type shall be @code{REAL}.
-@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
-expression indicating the kind parameter of the result.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
-and a default-kind @code{INTEGER} otherwise.
-
-@item @emph{Example}:
-@smallexample
-program test_ceiling
- real :: x = 63.29
- real :: y = -63.59
- print *, ceiling(x) ! returns 64
- print *, ceiling(y) ! returns -63
-end program test_ceiling
-@end smallexample
-
-@item @emph{See also}:
-@ref{FLOOR}, @gol
-@ref{NINT}
-@end table
-
-
-
-@node CHAR
-@section @code{CHAR} --- Character conversion function
-@fnindex CHAR
-@cindex conversion, to character
-
-@table @asis
-@item @emph{Description}:
-@code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}.
-
-@item @emph{Standard}:
-Fortran 77 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = CHAR(I [, KIND])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{I} @tab The type shall be @code{INTEGER}.
-@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
-expression indicating the kind parameter of the result.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{CHARACTER(1)}
-
-@item @emph{Example}:
-@smallexample
-program test_char
- integer :: i = 74
- character(1) :: c
- c = char(i)
- print *, i, c ! returns 'J'
-end program test_char
-@end smallexample
-
-@item @emph{Specific names}:
-@multitable @columnfractions .19 .19 .25 .33
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{CHAR(I)} @tab @code{INTEGER I} @tab @code{CHARACTER(LEN=1)} @tab Fortran 77 and later
-@end multitable
-
-@item @emph{Note}:
-See @ref{ICHAR} for a discussion of converting between numerical values
-and formatted string representations.
-
-@item @emph{See also}:
-@ref{ACHAR}, @gol
-@ref{IACHAR}, @gol
-@ref{ICHAR}
-
-@end table
-
-
-
-@node CHDIR
-@section @code{CHDIR} --- Change working directory
-@fnindex CHDIR
-@cindex system, working directory
-
-@table @asis
-@item @emph{Description}:
-Change current working directory to a specified path.
-
-This intrinsic is provided in both subroutine and function forms; however,
-only one form can be used in any given program unit.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Subroutine, function
-
-@item @emph{Syntax}:
-@multitable @columnfractions .80
-@item @code{CALL CHDIR(NAME [, STATUS])}
-@item @code{STATUS = CHDIR(NAME)}
-@end multitable
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{NAME} @tab The type shall be @code{CHARACTER} of default
-kind and shall specify a valid path within the file system.
-@item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default
-kind. Returns 0 on success, and a system specific and nonzero error code
-otherwise.
-@end multitable
-
-@item @emph{Example}:
-@smallexample
-PROGRAM test_chdir
- CHARACTER(len=255) :: path
- CALL getcwd(path)
- WRITE(*,*) TRIM(path)
- CALL chdir("/tmp")
- CALL getcwd(path)
- WRITE(*,*) TRIM(path)
-END PROGRAM
-@end smallexample
-
-@item @emph{See also}:
-@ref{GETCWD}
-@end table
-
-
-
-@node CHMOD
-@section @code{CHMOD} --- Change access permissions of files
-@fnindex CHMOD
-@cindex file system, change access mode
-
-@table @asis
-@item @emph{Description}:
-@code{CHMOD} changes the permissions of a file.
-
-This intrinsic is provided in both subroutine and function forms; however,
-only one form can be used in any given program unit.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Subroutine, function
-
-@item @emph{Syntax}:
-@multitable @columnfractions .80
-@item @code{CALL CHMOD(NAME, MODE[, STATUS])}
-@item @code{STATUS = CHMOD(NAME, MODE)}
-@end multitable
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-
-@item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
-file name. Trailing blanks are ignored unless the character
-@code{achar(0)} is present, then all characters up to and excluding
-@code{achar(0)} are used as the file name.
-
-@item @var{MODE} @tab Scalar @code{CHARACTER} of default kind giving the
-file permission. @var{MODE} uses the same syntax as the @code{chmod} utility
-as defined by the POSIX standard. The argument shall either be a string of
-a nonnegative octal number or a symbolic mode.
-
-@item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is
-@code{0} on success and nonzero otherwise.
-@end multitable
-
-@item @emph{Return value}:
-In either syntax, @var{STATUS} is set to @code{0} on success and nonzero
-otherwise.
-
-@item @emph{Example}:
-@code{CHMOD} as subroutine
-@smallexample
-program chmod_test
- implicit none
- integer :: status
- call chmod('test.dat','u+x',status)
- print *, 'Status: ', status
-end program chmod_test
-@end smallexample
-@code{CHMOD} as function:
-@smallexample
-program chmod_test
- implicit none
- integer :: status
- status = chmod('test.dat','u+x')
- print *, 'Status: ', status
-end program chmod_test
-@end smallexample
-
-@end table
-
-
-
-@node CMPLX
-@section @code{CMPLX} --- Complex conversion function
-@fnindex CMPLX
-@cindex complex numbers, conversion to
-@cindex conversion, to complex
-
-@table @asis
-@item @emph{Description}:
-@code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to
-the real component. If @var{Y} is present it is converted to the imaginary
-component. If @var{Y} is not present then the imaginary component is set to
-0.0. If @var{X} is complex then @var{Y} must not be present.
-
-@item @emph{Standard}:
-Fortran 77 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = CMPLX(X [, Y [, KIND]])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
-or @code{COMPLEX}.
-@item @var{Y} @tab (Optional; only allowed if @var{X} is not
-@code{COMPLEX}.) May be @code{INTEGER} or @code{REAL}.
-@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
-expression indicating the kind parameter of the result.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of @code{COMPLEX} type, with a kind equal to
-@var{KIND} if it is specified. If @var{KIND} is not specified, the
-result is of the default @code{COMPLEX} kind, regardless of the kinds of
-@var{X} and @var{Y}.
-
-@item @emph{Example}:
-@smallexample
-program test_cmplx
- integer :: i = 42
- real :: x = 3.14
- complex :: z
- z = cmplx(i, x)
- print *, z, cmplx(x)
-end program test_cmplx
-@end smallexample
-
-@item @emph{See also}:
-@ref{COMPLEX}
-@end table
-
-
-
-@node CO_BROADCAST
-@section @code{CO_BROADCAST} --- Copy a value to all images the current set of images
-@fnindex CO_BROADCAST
-@cindex Collectives, value broadcasting
-
-@table @asis
-@item @emph{Description}:
-@code{CO_BROADCAST} copies the value of argument @var{A} on the image with
-image index @code{SOURCE_IMAGE} to all images in the current team. @var{A}
-becomes defined as if by intrinsic assignment. If the execution was
-successful and @var{STAT} is present, it is assigned the value zero. If the
-execution failed, @var{STAT} gets assigned a nonzero value and, if present,
-@var{ERRMSG} gets assigned a value describing the occurred error.
-
-@item @emph{Standard}:
-Technical Specification (TS) 18508 or later
-
-@item @emph{Class}:
-Collective subroutine
-
-@item @emph{Syntax}:
-@code{CALL CO_BROADCAST(A, SOURCE_IMAGE [, STAT, ERRMSG])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .20 .65
-@item @var{A} @tab INTENT(INOUT) argument; shall have the same
-dynamic type and type parameters on all images of the current team. If it
-is an array, it shall have the same shape on all images.
-@item @var{SOURCE_IMAGE} @tab a scalar integer expression.
-It shall have the same value on all images and refer to an
-image of the current team.
-@item @var{STAT} @tab (optional) a scalar integer variable
-@item @var{ERRMSG} @tab (optional) a scalar character variable
-@end multitable
-
-@item @emph{Example}:
-@smallexample
-program test
- integer :: val(3)
- if (this_image() == 1) then
- val = [1, 5, 3]
- end if
- call co_broadcast (val, source_image=1)
- print *, this_image, ":", val
-end program test
-@end smallexample
-
-@item @emph{See also}:
-@ref{CO_MAX}, @gol
-@ref{CO_MIN}, @gol
-@ref{CO_SUM}, @gol
-@ref{CO_REDUCE}
-@end table
-
-
-
-@node CO_MAX
-@section @code{CO_MAX} --- Maximal value on the current set of images
-@fnindex CO_MAX
-@cindex Collectives, maximal value
-
-@table @asis
-@item @emph{Description}:
-@code{CO_MAX} determines element-wise the maximal value of @var{A} on all
-images of the current team. If @var{RESULT_IMAGE} is present, the maximum
-values are returned in @var{A} on the specified image only and the value
-of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is
-not present, the value is returned on all images. If the execution was
-successful and @var{STAT} is present, it is assigned the value zero. If the
-execution failed, @var{STAT} gets assigned a nonzero value and, if present,
-@var{ERRMSG} gets assigned a value describing the occurred error.
-
-@item @emph{Standard}:
-Technical Specification (TS) 18508 or later
-
-@item @emph{Class}:
-Collective subroutine
-
-@item @emph{Syntax}:
-@code{CALL CO_MAX(A [, RESULT_IMAGE, STAT, ERRMSG])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .20 .65
-@item @var{A} @tab shall be an integer, real or character variable,
-which has the same type and type parameters on all images of the team.
-@item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
-present, it shall have the same value on all images and refer to an
-image of the current team.
-@item @var{STAT} @tab (optional) a scalar integer variable
-@item @var{ERRMSG} @tab (optional) a scalar character variable
-@end multitable
-
-@item @emph{Example}:
-@smallexample
-program test
- integer :: val
- val = this_image ()
- call co_max (val, result_image=1)
- if (this_image() == 1) then
- write(*,*) "Maximal value", val ! prints num_images()
- end if
-end program test
-@end smallexample
-
-@item @emph{See also}:
-@ref{CO_MIN}, @gol
-@ref{CO_SUM}, @gol
-@ref{CO_REDUCE}, @gol
-@ref{CO_BROADCAST}
-@end table
-
-
-
-@node CO_MIN
-@section @code{CO_MIN} --- Minimal value on the current set of images
-@fnindex CO_MIN
-@cindex Collectives, minimal value
-
-@table @asis
-@item @emph{Description}:
-@code{CO_MIN} determines element-wise the minimal value of @var{A} on all
-images of the current team. If @var{RESULT_IMAGE} is present, the minimal
-values are returned in @var{A} on the specified image only and the value
-of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is
-not present, the value is returned on all images. If the execution was
-successful and @var{STAT} is present, it is assigned the value zero. If the
-execution failed, @var{STAT} gets assigned a nonzero value and, if present,
-@var{ERRMSG} gets assigned a value describing the occurred error.
-
-@item @emph{Standard}:
-Technical Specification (TS) 18508 or later
-
-@item @emph{Class}:
-Collective subroutine
-
-@item @emph{Syntax}:
-@code{CALL CO_MIN(A [, RESULT_IMAGE, STAT, ERRMSG])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .20 .65
-@item @var{A} @tab shall be an integer, real or character variable,
-which has the same type and type parameters on all images of the team.
-@item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
-present, it shall have the same value on all images and refer to an
-image of the current team.
-@item @var{STAT} @tab (optional) a scalar integer variable
-@item @var{ERRMSG} @tab (optional) a scalar character variable
-@end multitable
-
-@item @emph{Example}:
-@smallexample
-program test
- integer :: val
- val = this_image ()
- call co_min (val, result_image=1)
- if (this_image() == 1) then
- write(*,*) "Minimal value", val ! prints 1
- end if
-end program test
-@end smallexample
-
-@item @emph{See also}:
-@ref{CO_MAX}, @gol
-@ref{CO_SUM}, @gol
-@ref{CO_REDUCE}, @gol
-@ref{CO_BROADCAST}
-@end table
-
-
-
-@node CO_REDUCE
-@section @code{CO_REDUCE} --- Reduction of values on the current set of images
-@fnindex CO_REDUCE
-@cindex Collectives, generic reduction
-
-@table @asis
-@item @emph{Description}:
-@code{CO_REDUCE} determines element-wise the reduction of the value of @var{A}
-on all images of the current team. The pure function passed as @var{OPERATION}
-is used to pairwise reduce the values of @var{A} by passing either the value
-of @var{A} of different images or the result values of such a reduction as
-argument. If @var{A} is an array, the deduction is done element wise. If
-@var{RESULT_IMAGE} is present, the result values are returned in @var{A} on
-the specified image only and the value of @var{A} on the other images become
-undefined. If @var{RESULT_IMAGE} is not present, the value is returned on all
-images. If the execution was successful and @var{STAT} is present, it is
-assigned the value zero. If the execution failed, @var{STAT} gets assigned
-a nonzero value and, if present, @var{ERRMSG} gets assigned a value describing
-the occurred error.
-
-@item @emph{Standard}:
-Technical Specification (TS) 18508 or later
-
-@item @emph{Class}:
-Collective subroutine
-
-@item @emph{Syntax}:
-@code{CALL CO_REDUCE(A, OPERATION, [, RESULT_IMAGE, STAT, ERRMSG])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .20 .65
-@item @var{A} @tab is an @code{INTENT(INOUT)} argument and shall be
-nonpolymorphic. If it is allocatable, it shall be allocated; if it is a pointer,
-it shall be associated. @var{A} shall have the same type and type parameters on
-all images of the team; if it is an array, it shall have the same shape on all
-images.
-@item @var{OPERATION} @tab pure function with two scalar nonallocatable
-arguments, which shall be nonpolymorphic and have the same type and type
-parameters as @var{A}. The function shall return a nonallocatable scalar of
-the same type and type parameters as @var{A}. The function shall be the same on
-all images and with regards to the arguments mathematically commutative and
-associative. Note that @var{OPERATION} may not be an elemental function, unless
-it is an intrisic function.
-@item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
-present, it shall have the same value on all images and refer to an
-image of the current team.
-@item @var{STAT} @tab (optional) a scalar integer variable
-@item @var{ERRMSG} @tab (optional) a scalar character variable
-@end multitable
-
-@item @emph{Example}:
-@smallexample
-program test
- integer :: val
- val = this_image ()
- call co_reduce (val, result_image=1, operation=myprod)
- if (this_image() == 1) then
- write(*,*) "Product value", val ! prints num_images() factorial
- end if
-contains
- pure function myprod(a, b)
- integer, value :: a, b
- integer :: myprod
- myprod = a * b
- end function myprod
-end program test
-@end smallexample
-
-@item @emph{Note}:
-While the rules permit in principle an intrinsic function, none of the
-intrinsics in the standard fulfill the criteria of having a specific
-function, which takes two arguments of the same type and returning that
-type as result.
-
-@item @emph{See also}:
-@ref{CO_MIN}, @gol
-@ref{CO_MAX}, @gol
-@ref{CO_SUM}, @gol
-@ref{CO_BROADCAST}
-@end table
-
-
-
-@node CO_SUM
-@section @code{CO_SUM} --- Sum of values on the current set of images
-@fnindex CO_SUM
-@cindex Collectives, sum of values
-
-@table @asis
-@item @emph{Description}:
-@code{CO_SUM} sums up the values of each element of @var{A} on all
-images of the current team. If @var{RESULT_IMAGE} is present, the summed-up
-values are returned in @var{A} on the specified image only and the value
-of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is
-not present, the value is returned on all images. If the execution was
-successful and @var{STAT} is present, it is assigned the value zero. If the
-execution failed, @var{STAT} gets assigned a nonzero value and, if present,
-@var{ERRMSG} gets assigned a value describing the occurred error.
-
-@item @emph{Standard}:
-Technical Specification (TS) 18508 or later
-
-@item @emph{Class}:
-Collective subroutine
-
-@item @emph{Syntax}:
-@code{CALL CO_SUM(A [, RESULT_IMAGE, STAT, ERRMSG])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .20 .65
-@item @var{A} @tab shall be an integer, real or complex variable,
-which has the same type and type parameters on all images of the team.
-@item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
-present, it shall have the same value on all images and refer to an
-image of the current team.
-@item @var{STAT} @tab (optional) a scalar integer variable
-@item @var{ERRMSG} @tab (optional) a scalar character variable
-@end multitable
-
-@item @emph{Example}:
-@smallexample
-program test
- integer :: val
- val = this_image ()
- call co_sum (val, result_image=1)
- if (this_image() == 1) then
- write(*,*) "The sum is ", val ! prints (n**2 + n)/2,
- ! with n = num_images()
- end if
-end program test
-@end smallexample
-
-@item @emph{See also}:
-@ref{CO_MAX}, @gol
-@ref{CO_MIN}, @gol
-@ref{CO_REDUCE}, @gol
-@ref{CO_BROADCAST}
-@end table
-
-
-
-@node COMMAND_ARGUMENT_COUNT
-@section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments
-@fnindex COMMAND_ARGUMENT_COUNT
-@cindex command-line arguments
-@cindex command-line arguments, number of
-@cindex arguments, to program
-
-@table @asis
-@item @emph{Description}:
-@code{COMMAND_ARGUMENT_COUNT} returns the number of arguments passed on the
-command line when the containing program was invoked.
-
-@item @emph{Standard}:
-Fortran 2003 and later
-
-@item @emph{Class}:
-Inquiry function
-
-@item @emph{Syntax}:
-@code{RESULT = COMMAND_ARGUMENT_COUNT()}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item None
-@end multitable
-
-@item @emph{Return value}:
-The return value is an @code{INTEGER} of default kind.
-
-@item @emph{Example}:
-@smallexample
-program test_command_argument_count
- integer :: count
- count = command_argument_count()
- print *, count
-end program test_command_argument_count
-@end smallexample
-
-@item @emph{See also}:
-@ref{GET_COMMAND}, @gol
-@ref{GET_COMMAND_ARGUMENT}
-@end table
-
-
-
-@node COMPILER_OPTIONS
-@section @code{COMPILER_OPTIONS} --- Options passed to the compiler
-@fnindex COMPILER_OPTIONS
-@cindex flags inquiry function
-@cindex options inquiry function
-@cindex compiler flags inquiry function
-
-@table @asis
-@item @emph{Description}:
-@code{COMPILER_OPTIONS} returns a string with the options used for
-compiling.
-
-@item @emph{Standard}:
-Fortran 2008
-
-@item @emph{Class}:
-Inquiry function of the module @code{ISO_FORTRAN_ENV}
-
-@item @emph{Syntax}:
-@code{STR = COMPILER_OPTIONS()}
-
-@item @emph{Arguments}:
-None
-
-@item @emph{Return value}:
-The return value is a default-kind string with system-dependent length.
-It contains the compiler flags used to compile the file, which called
-the @code{COMPILER_OPTIONS} intrinsic.
-
-@item @emph{Example}:
-@smallexample
- use iso_fortran_env
- print '(4a)', 'This file was compiled by ', &
- compiler_version(), ' using the options ', &
- compiler_options()
- end
-@end smallexample
-
-@item @emph{See also}:
-@ref{COMPILER_VERSION}, @gol
-@ref{ISO_FORTRAN_ENV}
-@end table
-
-
-
-@node COMPILER_VERSION
-@section @code{COMPILER_VERSION} --- Compiler version string
-@fnindex COMPILER_VERSION
-@cindex compiler, name and version
-@cindex version of the compiler
-
-@table @asis
-@item @emph{Description}:
-@code{COMPILER_VERSION} returns a string with the name and the
-version of the compiler.
-
-@item @emph{Standard}:
-Fortran 2008
-
-@item @emph{Class}:
-Inquiry function of the module @code{ISO_FORTRAN_ENV}
-
-@item @emph{Syntax}:
-@code{STR = COMPILER_VERSION()}
-
-@item @emph{Arguments}:
-None
-
-@item @emph{Return value}:
-The return value is a default-kind string with system-dependent length.
-It contains the name of the compiler and its version number.
-
-@item @emph{Example}:
-@smallexample
- use iso_fortran_env
- print '(4a)', 'This file was compiled by ', &
- compiler_version(), ' using the options ', &
- compiler_options()
- end
-@end smallexample
-
-@item @emph{See also}:
-@ref{COMPILER_OPTIONS}, @gol
-@ref{ISO_FORTRAN_ENV}
-@end table
-
-
-
-@node COMPLEX
-@section @code{COMPLEX} --- Complex conversion function
-@fnindex COMPLEX
-@cindex complex numbers, conversion to
-@cindex conversion, to complex
-
-@table @asis
-@item @emph{Description}:
-@code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted
-to the real component and @var{Y} is converted to the imaginary
-component.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = COMPLEX(X, Y)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
-@item @var{Y} @tab The type may be @code{INTEGER} or @code{REAL}.
-@end multitable
-
-@item @emph{Return value}:
-If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return
-value is of default @code{COMPLEX} type.
-
-If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL}
-type and one is of @code{INTEGER} type, then the return value is of
-@code{COMPLEX} type with a kind equal to that of the @code{REAL}
-argument with the highest precision.
-
-@item @emph{Example}:
-@smallexample
-program test_complex
- integer :: i = 42
- real :: x = 3.14
- print *, complex(i, x)
-end program test_complex
-@end smallexample
-
-@item @emph{See also}:
-@ref{CMPLX}
-@end table
-
-
-
-@node CONJG
-@section @code{CONJG} --- Complex conjugate function
-@fnindex CONJG
-@fnindex DCONJG
-@cindex complex conjugate
-
-@table @asis
-@item @emph{Description}:
-@code{CONJG(Z)} returns the conjugate of @var{Z}. If @var{Z} is @code{(x, y)}
-then the result is @code{(x, -y)}
-
-@item @emph{Standard}:
-Fortran 77 and later, has an overload that is a GNU extension
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{Z = CONJG(Z)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{Z} @tab The type shall be @code{COMPLEX}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{COMPLEX}.
-
-@item @emph{Example}:
-@smallexample
-program test_conjg
- complex :: z = (2.0, 3.0)
- complex(8) :: dz = (2.71_8, -3.14_8)
- z= conjg(z)
- print *, z
- dz = dconjg(dz)
- print *, dz
-end program test_conjg
-@end smallexample
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .23 .20 .33
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
-@end multitable
-@end table
-
-
-
-@node COS
-@section @code{COS} --- Cosine function
-@fnindex COS
-@fnindex DCOS
-@fnindex CCOS
-@fnindex ZCOS
-@fnindex CDCOS
-@cindex trigonometric function, cosine
-@cindex cosine
-
-@table @asis
-@item @emph{Description}:
-@code{COS(X)} computes the cosine of @var{X}.
-
-@item @emph{Standard}:
-Fortran 77 and later, has overloads that are GNU extensions
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = COS(X)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab The type shall be @code{REAL} or
-@code{COMPLEX}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of the same type and kind as @var{X}. The real part
-of the result is in radians. If @var{X} is of the type @code{REAL},
-the return value lies in the range @math{ -1 \leq \cos (x) \leq 1}.
-
-@item @emph{Example}:
-@smallexample
-program test_cos
- real :: x = 0.0
- x = cos(x)
-end program test_cos
-@end smallexample
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .23 .20 .33
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{COS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
-@item @code{DCOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
-@item @code{CCOS(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
-@item @code{ZCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
-@item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
-@end multitable
-
-@item @emph{See also}:
-Inverse function: @gol
-@ref{ACOS} @gol
-Degrees function: @gol
-@ref{COSD}
-@end table
-
-
-
-@node COSD
-@section @code{COSD} --- Cosine function, degrees
-@fnindex COSD
-@fnindex DCOSD
-@fnindex CCOSD
-@fnindex ZCOSD
-@fnindex CDCOSD
-@cindex trigonometric function, cosine, degrees
-@cindex cosine, degrees
-
-@table @asis
-@item @emph{Description}:
-@code{COSD(X)} computes the cosine of @var{X} in degrees.
-
-This function is for compatibility only and should be avoided in favor of
-standard constructs wherever possible.
-
-@item @emph{Standard}:
-GNU extension, enabled with @option{-fdec-math}.
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = COSD(X)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab The type shall be @code{REAL} or
-@code{COMPLEX}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of the same type and kind as @var{X}. The real part
-of the result is in degrees. If @var{X} is of the type @code{REAL},
-the return value lies in the range @math{ -1 \leq \cosd (x) \leq 1}.
-
-@item @emph{Example}:
-@smallexample
-program test_cosd
- real :: x = 0.0
- x = cosd(x)
-end program test_cosd
-@end smallexample
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .23 .20 .33
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{COSD(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension
-@item @code{DCOSD(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
-@item @code{CCOSD(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab GNU extension
-@item @code{ZCOSD(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
-@item @code{CDCOSD(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
-@end multitable
-
-@item @emph{See also}:
-Inverse function: @gol
-@ref{ACOSD} @gol
-Radians function: @gol
-@ref{COS}
-@end table
-
-
-
-@node COSH
-@section @code{COSH} --- Hyperbolic cosine function
-@fnindex COSH
-@fnindex DCOSH
-@cindex hyperbolic cosine
-@cindex hyperbolic function, cosine
-@cindex cosine, hyperbolic
-
-@table @asis
-@item @emph{Description}:
-@code{COSH(X)} computes the hyperbolic cosine of @var{X}.
-
-@item @emph{Standard}:
-Fortran 77 and later, for a complex argument Fortran 2008 or later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{X = COSH(X)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
-@end multitable
-
-@item @emph{Return value}:
-The return value has same type and kind as @var{X}. If @var{X} is
-complex, the imaginary part of the result is in radians. If @var{X}
-is @code{REAL}, the return value has a lower bound of one,
-@math{\cosh (x) \geq 1}.
-
-@item @emph{Example}:
-@smallexample
-program test_cosh
- real(8) :: x = 1.0_8
- x = cosh(x)
-end program test_cosh
-@end smallexample
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .23 .20 .33
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{COSH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
-@item @code{DCOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
-@end multitable
-
-@item @emph{See also}:
-Inverse function: @gol
-@ref{ACOSH}
-@end table
-
-
-
-@node COTAN
-@section @code{COTAN} --- Cotangent function
-@fnindex COTAN
-@fnindex DCOTAN
-@cindex trigonometric function, cotangent
-@cindex cotangent
-
-@table @asis
-@item @emph{Description}:
-@code{COTAN(X)} computes the cotangent of @var{X}. Equivalent to @code{COS(x)}
-divided by @code{SIN(x)}, or @code{1 / TAN(x)}.
-
-This function is for compatibility only and should be avoided in favor of
-standard constructs wherever possible.
-
-@item @emph{Standard}:
-GNU extension, enabled with @option{-fdec-math}.
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = COTAN(X)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
-@end multitable
-
-@item @emph{Return value}:
-The return value has same type and kind as @var{X}, and its value is in radians.
-
-@item @emph{Example}:
-@smallexample
-program test_cotan
- real(8) :: x = 0.165_8
- x = cotan(x)
-end program test_cotan
-@end smallexample
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .23 .20 .33
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{COTAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension
-@item @code{DCOTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
-@end multitable
-
-@item @emph{See also}:
-Converse function: @gol
-@ref{TAN} @gol
-Degrees function: @gol
-@ref{COTAND}
-@end table
-
-
-
-@node COTAND
-@section @code{COTAND} --- Cotangent function, degrees
-@fnindex COTAND
-@fnindex DCOTAND
-@cindex trigonometric function, cotangent, degrees
-@cindex cotangent, degrees
-
-@table @asis
-@item @emph{Description}:
-@code{COTAND(X)} computes the cotangent of @var{X} in degrees. Equivalent to
-@code{COSD(x)} divided by @code{SIND(x)}, or @code{1 / TAND(x)}.
-
-@item @emph{Standard}:
-GNU extension, enabled with @option{-fdec-math}.
-
-This function is for compatibility only and should be avoided in favor of
-standard constructs wherever possible.
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = COTAND(X)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
-@end multitable
-
-@item @emph{Return value}:
-The return value has same type and kind as @var{X}, and its value is in degrees.
-
-@item @emph{Example}:
-@smallexample
-program test_cotand
- real(8) :: x = 0.165_8
- x = cotand(x)
-end program test_cotand
-@end smallexample
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .23 .20 .33
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{COTAND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension
-@item @code{DCOTAND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
-@end multitable
-
-@item @emph{See also}:
-Converse function: @gol
-@ref{TAND} @gol
-Radians function: @gol
-@ref{COTAN}
-@end table
-
-
-
-@node COUNT
-@section @code{COUNT} --- Count function
-@fnindex COUNT
-@cindex array, conditionally count elements
-@cindex array, element counting
-@cindex array, number of elements
-
-@table @asis
-@item @emph{Description}:
-
-Counts the number of @code{.TRUE.} elements in a logical @var{MASK},
-or, if the @var{DIM} argument is supplied, counts the number of
-elements along each row of the array in the @var{DIM} direction.
-If the array has zero size, or all of the elements of @var{MASK} are
-@code{.FALSE.}, then the result is @code{0}.
-
-@item @emph{Standard}:
-Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later
-
-@item @emph{Class}:
-Transformational function
-
-@item @emph{Syntax}:
-@code{RESULT = COUNT(MASK [, DIM, KIND])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{MASK} @tab The type shall be @code{LOGICAL}.
-@item @var{DIM} @tab (Optional) The type shall be @code{INTEGER}.
-@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
-expression indicating the kind parameter of the result.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{INTEGER} and of kind @var{KIND}. If
-@var{KIND} is absent, the return value is of default integer kind.
-If @var{DIM} is present, the result is an array with a rank one less
-than the rank of @var{ARRAY}, and a size corresponding to the shape
-of @var{ARRAY} with the @var{DIM} dimension removed.
-
-@item @emph{Example}:
-@smallexample
-program test_count
- integer, dimension(2,3) :: a, b
- logical, dimension(2,3) :: mask
- a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /))
- b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /))
- print '(3i3)', a(1,:)
- print '(3i3)', a(2,:)
- print *
- print '(3i3)', b(1,:)
- print '(3i3)', b(2,:)
- print *
- mask = a.ne.b
- print '(3l3)', mask(1,:)
- print '(3l3)', mask(2,:)
- print *
- print '(3i3)', count(mask)
- print *
- print '(3i3)', count(mask, 1)
- print *
- print '(3i3)', count(mask, 2)
-end program test_count
-@end smallexample
-@end table
-
-
-
-@node CPU_TIME
-@section @code{CPU_TIME} --- CPU elapsed time in seconds
-@fnindex CPU_TIME
-@cindex time, elapsed
-
-@table @asis
-@item @emph{Description}:
-Returns a @code{REAL} value representing the elapsed CPU time in
-seconds. This is useful for testing segments of code to determine
-execution time.
-
-If a time source is available, time will be reported with microsecond
-resolution. If no time source is available, @var{TIME} is set to
-@code{-1.0}.
-
-Note that @var{TIME} may contain a, system dependent, arbitrary offset
-and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute
-value is meaningless, only differences between subsequent calls to
-this subroutine, as shown in the example below, should be used.
-
-
-@item @emph{Standard}:
-Fortran 95 and later
-
-@item @emph{Class}:
-Subroutine
-
-@item @emph{Syntax}:
-@code{CALL CPU_TIME(TIME)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{TIME} @tab The type shall be @code{REAL} with @code{INTENT(OUT)}.
-@end multitable
-
-@item @emph{Return value}:
-None
-
-@item @emph{Example}:
-@smallexample
-program test_cpu_time
- real :: start, finish
- call cpu_time(start)
- ! put code to test here
- call cpu_time(finish)
- print '("Time = ",f6.3," seconds.")',finish-start
-end program test_cpu_time
-@end smallexample
-
-@item @emph{See also}:
-@ref{SYSTEM_CLOCK}, @gol
-@ref{DATE_AND_TIME}
-@end table
-
-
-
-@node CSHIFT
-@section @code{CSHIFT} --- Circular shift elements of an array
-@fnindex CSHIFT
-@cindex array, shift circularly
-@cindex array, permutation
-@cindex array, rotate
-
-@table @asis
-@item @emph{Description}:
-@code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of
-@var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is omitted it is
-taken to be @code{1}. @var{DIM} is a scalar of type @code{INTEGER} in the
-range of @math{1 \leq DIM \leq n)} where @math{n} is the rank of @var{ARRAY}.
-If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted
-by @var{SHIFT} places. If rank is greater than one, then all complete rank one
-sections of @var{ARRAY} along the given dimension are shifted. Elements
-shifted out one end of each rank one section are shifted back in the other end.
-
-@item @emph{Standard}:
-Fortran 90 and later
-
-@item @emph{Class}:
-Transformational function
-
-@item @emph{Syntax}:
-@code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{ARRAY} @tab Shall be an array of any type.
-@item @var{SHIFT} @tab The type shall be @code{INTEGER}.
-@item @var{DIM} @tab The type shall be @code{INTEGER}.
-@end multitable
-
-@item @emph{Return value}:
-Returns an array of same type and rank as the @var{ARRAY} argument.
-
-@item @emph{Example}:
-@smallexample
-program test_cshift
- integer, dimension(3,3) :: a
- a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
- print '(3i3)', a(1,:)
- print '(3i3)', a(2,:)
- print '(3i3)', a(3,:)
- a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2)
- print *
- print '(3i3)', a(1,:)
- print '(3i3)', a(2,:)
- print '(3i3)', a(3,:)
-end program test_cshift
-@end smallexample
-@end table
-
-
-
-@node CTIME
-@section @code{CTIME} --- Convert a time into a string
-@fnindex CTIME
-@cindex time, conversion to string
-@cindex conversion, to string
-
-@table @asis
-@item @emph{Description}:
-@code{CTIME} converts a system time value, such as returned by
-@ref{TIME8}, to a string. The output will be of the form @samp{Sat
-Aug 19 18:13:14 1995}.
-
-This intrinsic is provided in both subroutine and function forms; however,
-only one form can be used in any given program unit.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Subroutine, function
-
-@item @emph{Syntax}:
-@multitable @columnfractions .80
-@item @code{CALL CTIME(TIME, RESULT)}.
-@item @code{RESULT = CTIME(TIME)}.
-@end multitable
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{TIME} @tab The type shall be of type @code{INTEGER}.
-@item @var{RESULT} @tab The type shall be of type @code{CHARACTER} and
-of default kind. It is an @code{INTENT(OUT)} argument. If the length
-of this variable is too short for the time and date string to fit
-completely, it will be blank on procedure return.
-@end multitable
-
-@item @emph{Return value}:
-The converted date and time as a string.
-
-@item @emph{Example}:
-@smallexample
-program test_ctime
- integer(8) :: i
- character(len=30) :: date
- i = time8()
-
- ! Do something, main part of the program
-
- call ctime(i,date)
- print *, 'Program was started on ', date
-end program test_ctime
-@end smallexample
-
-@item @emph{See Also}:
-@ref{DATE_AND_TIME}, @gol
-@ref{GMTIME}, @gol
-@ref{LTIME}, @gol
-@ref{TIME}, @gol
-@ref{TIME8}
-@end table
-
-
-
-@node DATE_AND_TIME
-@section @code{DATE_AND_TIME} --- Date and time subroutine
-@fnindex DATE_AND_TIME
-@cindex date, current
-@cindex current date
-@cindex time, current
-@cindex current time
-
-@table @asis
-@item @emph{Description}:
-@code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and
-time information from the real-time system clock. @var{DATE} is
-@code{INTENT(OUT)} and has form ccyymmdd. @var{TIME} is @code{INTENT(OUT)} and
-has form hhmmss.sss. @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm,
-representing the difference with respect to Coordinated Universal Time (UTC).
-Unavailable time and date parameters return blanks.
-
-@var{VALUES} is @code{INTENT(OUT)} and provides the following:
-
-@multitable @columnfractions .15 .70
-@item @code{VALUE(1)}: @tab The year
-@item @code{VALUE(2)}: @tab The month
-@item @code{VALUE(3)}: @tab The day of the month
-@item @code{VALUE(4)}: @tab Time difference with UTC in minutes
-@item @code{VALUE(5)}: @tab The hour of the day
-@item @code{VALUE(6)}: @tab The minutes of the hour
-@item @code{VALUE(7)}: @tab The seconds of the minute
-@item @code{VALUE(8)}: @tab The milliseconds of the second
-@end multitable
-
-@item @emph{Standard}:
-Fortran 90 and later
-
-@item @emph{Class}:
-Subroutine
-
-@item @emph{Syntax}:
-@code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{DATE} @tab (Optional) The type shall be @code{CHARACTER(LEN=8)}
-or larger, and of default kind.
-@item @var{TIME} @tab (Optional) The type shall be @code{CHARACTER(LEN=10)}
-or larger, and of default kind.
-@item @var{ZONE} @tab (Optional) The type shall be @code{CHARACTER(LEN=5)}
-or larger, and of default kind.
-@item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}.
-@end multitable
-
-@item @emph{Return value}:
-None
-
-@item @emph{Example}:
-@smallexample
-program test_time_and_date
- character(8) :: date
- character(10) :: time
- character(5) :: zone
- integer,dimension(8) :: values
- ! using keyword arguments
- call date_and_time(date,time,zone,values)
- call date_and_time(DATE=date,ZONE=zone)
- call date_and_time(TIME=time)
- call date_and_time(VALUES=values)
- print '(a,2x,a,2x,a)', date, time, zone
- print '(8i5)', values
-end program test_time_and_date
-@end smallexample
-
-@item @emph{See also}:
-@ref{CPU_TIME}, @gol
-@ref{SYSTEM_CLOCK}
-@end table
-
-
-
-@node DBLE
-@section @code{DBLE} --- Double conversion function
-@fnindex DBLE
-@cindex conversion, to real
-
-@table @asis
-@item @emph{Description}:
-@code{DBLE(A)} Converts @var{A} to double precision real type.
-
-@item @emph{Standard}:
-Fortran 77 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = DBLE(A)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{A} @tab The type shall be @code{INTEGER}, @code{REAL},
-or @code{COMPLEX}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type double precision real.
-
-@item @emph{Example}:
-@smallexample
-program test_dble
- real :: x = 2.18
- integer :: i = 5
- complex :: z = (2.3,1.14)
- print *, dble(x), dble(i), dble(z)
-end program test_dble
-@end smallexample
-
-@item @emph{See also}:
-@ref{REAL}
-@end table
-
-
-
-@node DCMPLX
-@section @code{DCMPLX} --- Double complex conversion function
-@fnindex DCMPLX
-@cindex complex numbers, conversion to
-@cindex conversion, to complex
-
-@table @asis
-@item @emph{Description}:
-@code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is
-converted to the real component. If @var{Y} is present it is converted to the
-imaginary component. If @var{Y} is not present then the imaginary component is
-set to 0.0. If @var{X} is complex then @var{Y} must not be present.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = DCMPLX(X [, Y])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
-or @code{COMPLEX}.
-@item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX}.) May be
-@code{INTEGER} or @code{REAL}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{COMPLEX(8)}
-
-@item @emph{Example}:
-@smallexample
-program test_dcmplx
- integer :: i = 42
- real :: x = 3.14
- complex :: z
- z = cmplx(i, x)
- print *, dcmplx(i)
- print *, dcmplx(x)
- print *, dcmplx(z)
- print *, dcmplx(x,i)
-end program test_dcmplx
-@end smallexample
-@end table
-
-
-@node DIGITS
-@section @code{DIGITS} --- Significant binary digits function
-@fnindex DIGITS
-@cindex model representation, significant digits
-
-@table @asis
-@item @emph{Description}:
-@code{DIGITS(X)} returns the number of significant binary digits of the internal
-model representation of @var{X}. For example, on a system using a 32-bit
-floating point representation, a default real number would likely return 24.
-
-@item @emph{Standard}:
-Fortran 90 and later
-
-@item @emph{Class}:
-Inquiry function
-
-@item @emph{Syntax}:
-@code{RESULT = DIGITS(X)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{INTEGER}.
-
-@item @emph{Example}:
-@smallexample
-program test_digits
- integer :: i = 12345
- real :: x = 3.143
- real(8) :: y = 2.33
- print *, digits(i)
- print *, digits(x)
- print *, digits(y)
-end program test_digits
-@end smallexample
-@end table
-
-
-
-@node DIM
-@section @code{DIM} --- Positive difference
-@fnindex DIM
-@fnindex IDIM
-@fnindex DDIM
-@cindex positive difference
-
-@table @asis
-@item @emph{Description}:
-@code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive;
-otherwise returns zero.
-
-@item @emph{Standard}:
-Fortran 77 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = DIM(X, Y)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab The type shall be @code{INTEGER} or @code{REAL}
-@item @var{Y} @tab The type shall be the same type and kind as @var{X}. (As
-a GNU extension, arguments of different kinds are permitted.)
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{INTEGER} or @code{REAL}. (As a GNU
-extension, kind is the largest kind of the actual arguments.)
-
-@item @emph{Example}:
-@smallexample
-program test_dim
- integer :: i
- real(8) :: x
- i = dim(4, 15)
- x = dim(4.345_8, 2.111_8)
- print *, i
- print *, x
-end program test_dim
-@end smallexample
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .26 .20 .30
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{DIM(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
-@item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X, Y} @tab @code{INTEGER(4)} @tab Fortran 77 and later
-@item @code{DDIM(X,Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
-@end multitable
-@end table
-
-
-
-@node DOT_PRODUCT
-@section @code{DOT_PRODUCT} --- Dot product function
-@fnindex DOT_PRODUCT
-@cindex dot product
-@cindex vector product
-@cindex product, vector
-
-@table @asis
-@item @emph{Description}:
-@code{DOT_PRODUCT(VECTOR_A, VECTOR_B)} computes the dot product multiplication
-of two vectors @var{VECTOR_A} and @var{VECTOR_B}. The two vectors may be
-either numeric or logical and must be arrays of rank one and of equal size. If
-the vectors are @code{INTEGER} or @code{REAL}, the result is
-@code{SUM(VECTOR_A*VECTOR_B)}. If the vectors are @code{COMPLEX}, the result
-is @code{SUM(CONJG(VECTOR_A)*VECTOR_B)}. If the vectors are @code{LOGICAL},
-the result is @code{ANY(VECTOR_A .AND. VECTOR_B)}.
-
-@item @emph{Standard}:
-Fortran 90 and later
-
-@item @emph{Class}:
-Transformational function
-
-@item @emph{Syntax}:
-@code{RESULT = DOT_PRODUCT(VECTOR_A, VECTOR_B)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{VECTOR_A} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
-@item @var{VECTOR_B} @tab The type shall be numeric if @var{VECTOR_A} is of numeric type or @code{LOGICAL} if @var{VECTOR_A} is of type @code{LOGICAL}. @var{VECTOR_B} shall be a rank-one array.
-@end multitable
-
-@item @emph{Return value}:
-If the arguments are numeric, the return value is a scalar of numeric type,
-@code{INTEGER}, @code{REAL}, or @code{COMPLEX}. If the arguments are
-@code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}.
-
-@item @emph{Example}:
-@smallexample
-program test_dot_prod
- integer, dimension(3) :: a, b
- a = (/ 1, 2, 3 /)
- b = (/ 4, 5, 6 /)
- print '(3i3)', a
- print *
- print '(3i3)', b
- print *
- print *, dot_product(a,b)
-end program test_dot_prod
-@end smallexample
-@end table
-
-
-
-@node DPROD
-@section @code{DPROD} --- Double product function
-@fnindex DPROD
-@cindex product, double-precision
-
-@table @asis
-@item @emph{Description}:
-@code{DPROD(X,Y)} returns the product @code{X*Y}.
-
-@item @emph{Standard}:
-Fortran 77 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = DPROD(X, Y)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab The type shall be @code{REAL}.
-@item @var{Y} @tab The type shall be @code{REAL}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{REAL(8)}.
-
-@item @emph{Example}:
-@smallexample
-program test_dprod
- real :: x = 5.2
- real :: y = 2.3
- real(8) :: d
- d = dprod(x,y)
- print *, d
-end program test_dprod
-@end smallexample
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .23 .20 .33
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{DPROD(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
-@end multitable
-
-@end table
-
-
-@node DREAL
-@section @code{DREAL} --- Double real part function
-@fnindex DREAL
-@cindex complex numbers, real part
-
-@table @asis
-@item @emph{Description}:
-@code{DREAL(Z)} returns the real part of complex variable @var{Z}.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = DREAL(A)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{A} @tab The type shall be @code{COMPLEX(8)}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{REAL(8)}.
-
-@item @emph{Example}:
-@smallexample
-program test_dreal
- complex(8) :: z = (1.3_8,7.2_8)
- print *, dreal(z)
-end program test_dreal
-@end smallexample
-
-@item @emph{See also}:
-@ref{AIMAG}
-
-@end table
-
-
-
-@node DSHIFTL
-@section @code{DSHIFTL} --- Combined left shift
-@fnindex DSHIFTL
-@cindex left shift, combined
-@cindex shift, left
-
-@table @asis
-@item @emph{Description}:
-@code{DSHIFTL(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
-rightmost @var{SHIFT} bits of the result are the leftmost @var{SHIFT}
-bits of @var{J}, and the remaining bits are the rightmost bits of
-@var{I}.
-
-@item @emph{Standard}:
-Fortran 2008 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = DSHIFTL(I, J, SHIFT)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant.
-@item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant.
-If both @var{I} and @var{J} have integer type, then they shall have
-the same kind type parameter. @var{I} and @var{J} shall not both be
-BOZ constants.
-@item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall
-be nonnegative. If @var{I} is not a BOZ constant, then @var{SHIFT}
-shall be less than or equal to @code{BIT_SIZE(I)}; otherwise,
-@var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}.
-@end multitable
-
-@item @emph{Return value}:
-If either @var{I} or @var{J} is a BOZ constant, it is first converted
-as if by the intrinsic function @code{INT} to an integer type with the
-kind type parameter of the other.
-
-@item @emph{See also}:
-@ref{DSHIFTR}
-@end table
-
-
-@node DSHIFTR
-@section @code{DSHIFTR} --- Combined right shift
-@fnindex DSHIFTR
-@cindex right shift, combined
-@cindex shift, right
-
-@table @asis
-@item @emph{Description}:
-@code{DSHIFTR(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
-leftmost @var{SHIFT} bits of the result are the rightmost @var{SHIFT}
-bits of @var{I}, and the remaining bits are the leftmost bits of
-@var{J}.
-
-@item @emph{Standard}:
-Fortran 2008 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = DSHIFTR(I, J, SHIFT)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant.
-@item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant.
-If both @var{I} and @var{J} have integer type, then they shall have
-the same kind type parameter. @var{I} and @var{J} shall not both be
-BOZ constants.
-@item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall
-be nonnegative. If @var{I} is not a BOZ constant, then @var{SHIFT}
-shall be less than or equal to @code{BIT_SIZE(I)}; otherwise,
-@var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}.
-@end multitable
-
-@item @emph{Return value}:
-If either @var{I} or @var{J} is a BOZ constant, it is first converted
-as if by the intrinsic function @code{INT} to an integer type with the
-kind type parameter of the other.
-
-@item @emph{See also}:
-@ref{DSHIFTL}
-@end table
-
-
-@node DTIME
-@section @code{DTIME} --- Execution time subroutine (or function)
-@fnindex DTIME
-@cindex time, elapsed
-@cindex elapsed time
-
-@table @asis
-@item @emph{Description}:
-@code{DTIME(VALUES, TIME)} initially returns the number of seconds of runtime
-since the start of the process's execution in @var{TIME}. @var{VALUES}
-returns the user and system components of this time in @code{VALUES(1)} and
-@code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) +
-VALUES(2)}.
-
-Subsequent invocations of @code{DTIME} return values accumulated since the
-previous invocation.
-
-On some systems, the underlying timings are represented using types with
-sufficiently small limits that overflows (wrap around) are possible, such as
-32-bit types. Therefore, the values returned by this intrinsic might be, or
-become, negative, or numerically less than previous values, during a single
-run of the compiled program.
-
-Please note, that this implementation is thread safe if used within OpenMP
-directives, i.e., its state will be consistent while called from multiple
-threads. However, if @code{DTIME} is called from multiple threads, the result
-is still the time since the last invocation. This may not give the intended
-results. If possible, use @code{CPU_TIME} instead.
-
-This intrinsic is provided in both subroutine and function forms; however,
-only one form can be used in any given program unit.
-
-@var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
-
-@multitable @columnfractions .15 .70
-@item @code{VALUES(1)}: @tab User time in seconds.
-@item @code{VALUES(2)}: @tab System time in seconds.
-@item @code{TIME}: @tab Run time since start in seconds.
-@end multitable
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Subroutine, function
-
-@item @emph{Syntax}:
-@multitable @columnfractions .80
-@item @code{CALL DTIME(VALUES, TIME)}.
-@item @code{TIME = DTIME(VALUES)}, (not recommended).
-@end multitable
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
-@item @var{TIME}@tab The type shall be @code{REAL(4)}.
-@end multitable
-
-@item @emph{Return value}:
-Elapsed time in seconds since the last invocation or since the start of program
-execution if not called before.
-
-@item @emph{Example}:
-@smallexample
-program test_dtime
- integer(8) :: i, j
- real, dimension(2) :: tarray
- real :: result
- call dtime(tarray, result)
- print *, result
- print *, tarray(1)
- print *, tarray(2)
- do i=1,100000000 ! Just a delay
- j = i * i - i
- end do
- call dtime(tarray, result)
- print *, result
- print *, tarray(1)
- print *, tarray(2)
-end program test_dtime
-@end smallexample
-
-@item @emph{See also}:
-@ref{CPU_TIME}
-
-@end table
-
-
-
-@node EOSHIFT
-@section @code{EOSHIFT} --- End-off shift elements of an array
-@fnindex EOSHIFT
-@cindex array, shift
-
-@table @asis
-@item @emph{Description}:
-@code{EOSHIFT(ARRAY, SHIFT[, BOUNDARY, DIM])} performs an end-off shift on
-elements of @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is
-omitted it is taken to be @code{1}. @var{DIM} is a scalar of type
-@code{INTEGER} in the range of @math{1 \leq DIM \leq n)} where @math{n} is the
-rank of @var{ARRAY}. If the rank of @var{ARRAY} is one, then all elements of
-@var{ARRAY} are shifted by @var{SHIFT} places. If rank is greater than one,
-then all complete rank one sections of @var{ARRAY} along the given dimension are
-shifted. Elements shifted out one end of each rank one section are dropped. If
-@var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY}
-is copied back in the other end. If @var{BOUNDARY} is not present then the
-following are copied in depending on the type of @var{ARRAY}.
-
-@multitable @columnfractions .15 .80
-@item @emph{Array Type} @tab @emph{Boundary Value}
-@item Numeric @tab 0 of the type and kind of @var{ARRAY}.
-@item Logical @tab @code{.FALSE.}.
-@item Character(@var{len}) @tab @var{len} blanks.
-@end multitable
-
-@item @emph{Standard}:
-Fortran 90 and later
-
-@item @emph{Class}:
-Transformational function
-
-@item @emph{Syntax}:
-@code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{ARRAY} @tab May be any type, not scalar.
-@item @var{SHIFT} @tab The type shall be @code{INTEGER}.
-@item @var{BOUNDARY} @tab Same type as @var{ARRAY}.
-@item @var{DIM} @tab The type shall be @code{INTEGER}.
-@end multitable
-
-@item @emph{Return value}:
-Returns an array of same type and rank as the @var{ARRAY} argument.
-
-@item @emph{Example}:
-@smallexample
-program test_eoshift
- integer, dimension(3,3) :: a
- a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
- print '(3i3)', a(1,:)
- print '(3i3)', a(2,:)
- print '(3i3)', a(3,:)
- a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2)
- print *
- print '(3i3)', a(1,:)
- print '(3i3)', a(2,:)
- print '(3i3)', a(3,:)
-end program test_eoshift
-@end smallexample
-@end table
-
-
-
-@node EPSILON
-@section @code{EPSILON} --- Epsilon function
-@fnindex EPSILON
-@cindex model representation, epsilon
-
-@table @asis
-@item @emph{Description}:
-@code{EPSILON(X)} returns the smallest number @var{E} of the same kind
-as @var{X} such that @math{1 + E > 1}.
-
-@item @emph{Standard}:
-Fortran 90 and later
-
-@item @emph{Class}:
-Inquiry function
-
-@item @emph{Syntax}:
-@code{RESULT = EPSILON(X)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab The type shall be @code{REAL}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of same type as the argument.
-
-@item @emph{Example}:
-@smallexample
-program test_epsilon
- real :: x = 3.143
- real(8) :: y = 2.33
- print *, EPSILON(x)
- print *, EPSILON(y)
-end program test_epsilon
-@end smallexample
-@end table
-
-
-
-@node ERF
-@section @code{ERF} --- Error function
-@fnindex ERF
-@cindex error function
-
-@table @asis
-@item @emph{Description}:
-@code{ERF(X)} computes the error function of @var{X}.
-
-@item @emph{Standard}:
-Fortran 2008 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = ERF(X)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab The type shall be @code{REAL}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{REAL}, of the same kind as
-@var{X} and lies in the range @math{-1 \leq erf (x) \leq 1 }.
-
-@item @emph{Example}:
-@smallexample
-program test_erf
- real(8) :: x = 0.17_8
- x = erf(x)
-end program test_erf
-@end smallexample
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .23 .20 .33
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{DERF(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
-@end multitable
-@end table
-
-
-
-@node ERFC
-@section @code{ERFC} --- Error function
-@fnindex ERFC
-@cindex error function, complementary
-
-@table @asis
-@item @emph{Description}:
-@code{ERFC(X)} computes the complementary error function of @var{X}.
-
-@item @emph{Standard}:
-Fortran 2008 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = ERFC(X)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab The type shall be @code{REAL}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{REAL} and of the same kind as @var{X}.
-It lies in the range @math{ 0 \leq erfc (x) \leq 2 }.
-
-@item @emph{Example}:
-@smallexample
-program test_erfc
- real(8) :: x = 0.17_8
- x = erfc(x)
-end program test_erfc
-@end smallexample
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .23 .20 .33
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{DERFC(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
-@end multitable
-@end table
-
-
-
-@node ERFC_SCALED
-@section @code{ERFC_SCALED} --- Error function
-@fnindex ERFC_SCALED
-@cindex error function, complementary, exponentially-scaled
-
-@table @asis
-@item @emph{Description}:
-@code{ERFC_SCALED(X)} computes the exponentially-scaled complementary
-error function of @var{X}.
-
-@item @emph{Standard}:
-Fortran 2008 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = ERFC_SCALED(X)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab The type shall be @code{REAL}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{REAL} and of the same kind as @var{X}.
-
-@item @emph{Example}:
-@smallexample
-program test_erfc_scaled
- real(8) :: x = 0.17_8
- x = erfc_scaled(x)
-end program test_erfc_scaled
-@end smallexample
-@end table
-
-
-
-@node ETIME
-@section @code{ETIME} --- Execution time subroutine (or function)
-@fnindex ETIME
-@cindex time, elapsed
-
-@table @asis
-@item @emph{Description}:
-@code{ETIME(VALUES, TIME)} returns the number of seconds of runtime
-since the start of the process's execution in @var{TIME}. @var{VALUES}
-returns the user and system components of this time in @code{VALUES(1)} and
-@code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + VALUES(2)}.
-
-On some systems, the underlying timings are represented using types with
-sufficiently small limits that overflows (wrap around) are possible, such as
-32-bit types. Therefore, the values returned by this intrinsic might be, or
-become, negative, or numerically less than previous values, during a single
-run of the compiled program.
-
-This intrinsic is provided in both subroutine and function forms; however,
-only one form can be used in any given program unit.
-
-@var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
-
-@multitable @columnfractions .15 .70
-@item @code{VALUES(1)}: @tab User time in seconds.
-@item @code{VALUES(2)}: @tab System time in seconds.
-@item @code{TIME}: @tab Run time since start in seconds.
-@end multitable
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Subroutine, function
-
-@item @emph{Syntax}:
-@multitable @columnfractions .80
-@item @code{CALL ETIME(VALUES, TIME)}.
-@item @code{TIME = ETIME(VALUES)}, (not recommended).
-@end multitable
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
-@item @var{TIME}@tab The type shall be @code{REAL(4)}.
-@end multitable
-
-@item @emph{Return value}:
-Elapsed time in seconds since the start of program execution.
-
-@item @emph{Example}:
-@smallexample
-program test_etime
- integer(8) :: i, j
- real, dimension(2) :: tarray
- real :: result
- call ETIME(tarray, result)
- print *, result
- print *, tarray(1)
- print *, tarray(2)
- do i=1,100000000 ! Just a delay
- j = i * i - i
- end do
- call ETIME(tarray, result)
- print *, result
- print *, tarray(1)
- print *, tarray(2)
-end program test_etime
-@end smallexample
-
-@item @emph{See also}:
-@ref{CPU_TIME}
-
-@end table
-
-
-
-@node EVENT_QUERY
-@section @code{EVENT_QUERY} --- Query whether a coarray event has occurred
-@fnindex EVENT_QUERY
-@cindex Events, EVENT_QUERY
-
-@table @asis
-@item @emph{Description}:
-@code{EVENT_QUERY} assignes the number of events to @var{COUNT} which have been
-posted to the @var{EVENT} variable and not yet been removed by calling
-@code{EVENT WAIT}. When @var{STAT} is present and the invocation was successful,
-it is assigned the value 0. If it is present and the invocation has failed,
-it is assigned a positive value and @var{COUNT} is assigned the value @math{-1}.
-
-@item @emph{Standard}:
-TS 18508 or later
-
-@item @emph{Class}:
- subroutine
-
-@item @emph{Syntax}:
-@code{CALL EVENT_QUERY (EVENT, COUNT [, STAT])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{EVENT} @tab (intent(IN)) Scalar of type @code{EVENT_TYPE},
-defined in @code{ISO_FORTRAN_ENV}; shall not be coindexed.
-@item @var{COUNT} @tab (intent(out))Scalar integer with at least the
-precision of default integer.
-@item @var{STAT} @tab (optional) Scalar default-kind integer variable.
-@end multitable
-
-@item @emph{Example}:
-@smallexample
-program atomic
- use iso_fortran_env
- implicit none
- type(event_type) :: event_value_has_been_set[*]
- integer :: cnt
- if (this_image() == 1) then
- call event_query (event_value_has_been_set, cnt)
- if (cnt > 0) write(*,*) "Value has been set"
- elseif (this_image() == 2) then
- event post (event_value_has_been_set[1])
- end if
-end program atomic
-@end smallexample
-
-@end table
-
-
-
-@node EXECUTE_COMMAND_LINE
-@section @code{EXECUTE_COMMAND_LINE} --- Execute a shell command
-@fnindex EXECUTE_COMMAND_LINE
-@cindex system, system call
-@cindex command line
-
-@table @asis
-@item @emph{Description}:
-@code{EXECUTE_COMMAND_LINE} runs a shell command, synchronously or
-asynchronously.
-
-The @code{COMMAND} argument is passed to the shell and executed (The
-shell is @code{sh} on Unix systems, and @code{cmd.exe} on Windows.).
-If @code{WAIT} is present and has the value false, the execution of
-the command is asynchronous if the system supports it; otherwise, the
-command is executed synchronously using the C library's @code{system}
-call.
-
-The three last arguments allow the user to get status information. After
-synchronous execution, @code{EXITSTAT} contains the integer exit code of
-the command, as returned by @code{system}. @code{CMDSTAT} is set to zero
-if the command line was executed (whatever its exit status was).
-@code{CMDMSG} is assigned an error message if an error has occurred.
-
-Note that the @code{system} function need not be thread-safe. It is
-the responsibility of the user to ensure that @code{system} is not
-called concurrently.
-
-For asynchronous execution on supported targets, the POSIX
-@code{posix_spawn} or @code{fork} functions are used. Also, a signal
-handler for the @code{SIGCHLD} signal is installed.
-
-@item @emph{Standard}:
-Fortran 2008 and later
-
-@item @emph{Class}:
-Subroutine
-
-@item @emph{Syntax}:
-@code{CALL EXECUTE_COMMAND_LINE(COMMAND [, WAIT, EXITSTAT, CMDSTAT, CMDMSG ])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{COMMAND} @tab Shall be a default @code{CHARACTER} scalar.
-@item @var{WAIT} @tab (Optional) Shall be a default @code{LOGICAL} scalar.
-@item @var{EXITSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
-default kind.
-@item @var{CMDSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
-default kind.
-@item @var{CMDMSG} @tab (Optional) Shall be an @code{CHARACTER} scalar of the
-default kind.
-@end multitable
-
-@item @emph{Example}:
-@smallexample
-program test_exec
- integer :: i
-
- call execute_command_line ("external_prog.exe", exitstat=i)
- print *, "Exit status of external_prog.exe was ", i
-
- call execute_command_line ("reindex_files.exe", wait=.false.)
- print *, "Now reindexing files in the background"
-
-end program test_exec
-@end smallexample
-
-
-@item @emph{Note}:
-
-Because this intrinsic is implemented in terms of the @code{system}
-function call, its behavior with respect to signaling is processor
-dependent. In particular, on POSIX-compliant systems, the SIGINT and
-SIGQUIT signals will be ignored, and the SIGCHLD will be blocked. As
-such, if the parent process is terminated, the child process might not be
-terminated alongside.
-
-
-@item @emph{See also}:
-@ref{SYSTEM}
-@end table
-
-
-
-@node EXIT
-@section @code{EXIT} --- Exit the program with status.
-@fnindex EXIT
-@cindex program termination
-@cindex terminate program
-
-@table @asis
-@item @emph{Description}:
-@code{EXIT} causes immediate termination of the program with status. If status
-is omitted it returns the canonical @emph{success} for the system. All Fortran
-I/O units are closed.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Subroutine
-
-@item @emph{Syntax}:
-@code{CALL EXIT([STATUS])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind.
-@end multitable
-
-@item @emph{Return value}:
-@code{STATUS} is passed to the parent process on exit.
-
-@item @emph{Example}:
-@smallexample
-program test_exit
- integer :: STATUS = 0
- print *, 'This program is going to exit.'
- call EXIT(STATUS)
-end program test_exit
-@end smallexample
-
-@item @emph{See also}:
-@ref{ABORT}, @gol
-@ref{KILL}
-@end table
-
-
-
-@node EXP
-@section @code{EXP} --- Exponential function
-@fnindex EXP
-@fnindex DEXP
-@fnindex CEXP
-@fnindex ZEXP
-@fnindex CDEXP
-@cindex exponential function
-@cindex logarithm function, inverse
-
-@table @asis
-@item @emph{Description}:
-@code{EXP(X)} computes the base @math{e} exponential of @var{X}.
-
-@item @emph{Standard}:
-Fortran 77 and later, has overloads that are GNU extensions
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = EXP(X)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab The type shall be @code{REAL} or
-@code{COMPLEX}.
-@end multitable
-
-@item @emph{Return value}:
-The return value has same type and kind as @var{X}.
-
-@item @emph{Example}:
-@smallexample
-program test_exp
- real :: x = 1.0
- x = exp(x)
-end program test_exp
-@end smallexample
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .23 .20 .33
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{EXP(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
-@item @code{DEXP(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
-@item @code{CEXP(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
-@item @code{ZEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
-@item @code{CDEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
-@end multitable
-@end table
-
-
-
-@node EXPONENT
-@section @code{EXPONENT} --- Exponent function
-@fnindex EXPONENT
-@cindex real number, exponent
-@cindex floating point, exponent
-
-@table @asis
-@item @emph{Description}:
-@code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X}
-is zero the value returned is zero.
-
-@item @emph{Standard}:
-Fortran 90 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = EXPONENT(X)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab The type shall be @code{REAL}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type default @code{INTEGER}.
-
-@item @emph{Example}:
-@smallexample
-program test_exponent
- real :: x = 1.0
- integer :: i
- i = exponent(x)
- print *, i
- print *, exponent(0.0)
-end program test_exponent
-@end smallexample
-@end table
-
-
-
-@node EXTENDS_TYPE_OF
-@section @code{EXTENDS_TYPE_OF} --- Query dynamic type for extension
-@fnindex EXTENDS_TYPE_OF
-
-@table @asis
-@item @emph{Description}:
-Query dynamic type for extension.
-
-@item @emph{Standard}:
-Fortran 2003 and later
-
-@item @emph{Class}:
-Inquiry function
-
-@item @emph{Syntax}:
-@code{RESULT = EXTENDS_TYPE_OF(A, MOLD)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{A} @tab Shall be an object of extensible declared type or
-unlimited polymorphic.
-@item @var{MOLD} @tab Shall be an object of extensible declared type or
-unlimited polymorphic.
-@end multitable
-
-@item @emph{Return value}:
-The return value is a scalar of type default logical. It is true if and only if
-the dynamic type of A is an extension type of the dynamic type of MOLD.
-
-
-@item @emph{See also}:
-@ref{SAME_TYPE_AS}
-@end table
-
-
-
-@node FDATE
-@section @code{FDATE} --- Get the current time as a string
-@fnindex FDATE
-@cindex time, current
-@cindex current time
-@cindex date, current
-@cindex current date
-
-@table @asis
-@item @emph{Description}:
-@code{FDATE(DATE)} returns the current date (using the same format as
-@ref{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE,
-TIME())}.
-
-This intrinsic is provided in both subroutine and function forms; however,
-only one form can be used in any given program unit.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Subroutine, function
-
-@item @emph{Syntax}:
-@multitable @columnfractions .80
-@item @code{CALL FDATE(DATE)}.
-@item @code{DATE = FDATE()}.
-@end multitable
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{DATE}@tab The type shall be of type @code{CHARACTER} of the
-default kind. It is an @code{INTENT(OUT)} argument. If the length of
-this variable is too short for the date and time string to fit
-completely, it will be blank on procedure return.
-@end multitable
-
-@item @emph{Return value}:
-The current date and time as a string.
-
-@item @emph{Example}:
-@smallexample
-program test_fdate
- integer(8) :: i, j
- character(len=30) :: date
- call fdate(date)
- print *, 'Program started on ', date
- do i = 1, 100000000 ! Just a delay
- j = i * i - i
- end do
- call fdate(date)
- print *, 'Program ended on ', date
-end program test_fdate
-@end smallexample
-
-@item @emph{See also}:
-@ref{DATE_AND_TIME}, @gol
-@ref{CTIME}
-@end table
-
-
-@node FGET
-@section @code{FGET} --- Read a single character in stream mode from stdin
-@fnindex FGET
-@cindex read character, stream mode
-@cindex stream mode, read character
-@cindex file operation, read character
-
-@table @asis
-@item @emph{Description}:
-Read a single character in stream mode from stdin by bypassing normal
-formatted output. Stream I/O should not be mixed with normal record-oriented
-(formatted or unformatted) I/O on the same unit; the results are unpredictable.
-
-This intrinsic is provided in both subroutine and function forms; however,
-only one form can be used in any given program unit.
-
-Note that the @code{FGET} intrinsic is provided for backwards compatibility with
-@command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
-Programmers should consider the use of new stream IO feature in new code
-for future portability. See also @ref{Fortran 2003 status}.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Subroutine, function
-
-@item @emph{Syntax}:
-@multitable @columnfractions .80
-@item @code{CALL FGET(C [, STATUS])}
-@item @code{STATUS = FGET(C)}
-@end multitable
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{C} @tab The type shall be @code{CHARACTER} and of default
-kind.
-@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
-Returns 0 on success, -1 on end-of-file, and a system specific positive
-error code otherwise.
-@end multitable
-
-@item @emph{Example}:
-@smallexample
-PROGRAM test_fget
- INTEGER, PARAMETER :: strlen = 100
- INTEGER :: status, i = 1
- CHARACTER(len=strlen) :: str = ""
-
- WRITE (*,*) 'Enter text:'
- DO
- CALL fget(str(i:i), status)
- if (status /= 0 .OR. i > strlen) exit
- i = i + 1
- END DO
- WRITE (*,*) TRIM(str)
-END PROGRAM
-@end smallexample
-
-@item @emph{See also}:
-@ref{FGETC}, @gol
-@ref{FPUT}, @gol
-@ref{FPUTC}
-@end table
-
-
-
-@node FGETC
-@section @code{FGETC} --- Read a single character in stream mode
-@fnindex FGETC
-@cindex read character, stream mode
-@cindex stream mode, read character
-@cindex file operation, read character
-
-@table @asis
-@item @emph{Description}:
-Read a single character in stream mode by bypassing normal formatted output.
-Stream I/O should not be mixed with normal record-oriented (formatted or
-unformatted) I/O on the same unit; the results are unpredictable.
-
-This intrinsic is provided in both subroutine and function forms; however,
-only one form can be used in any given program unit.
-
-Note that the @code{FGET} intrinsic is provided for backwards compatibility
-with @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
-Programmers should consider the use of new stream IO feature in new code
-for future portability. See also @ref{Fortran 2003 status}.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Subroutine, function
-
-@item @emph{Syntax}:
-@multitable @columnfractions .80
-@item @code{CALL FGETC(UNIT, C [, STATUS])}
-@item @code{STATUS = FGETC(UNIT, C)}
-@end multitable
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{UNIT} @tab The type shall be @code{INTEGER}.
-@item @var{C} @tab The type shall be @code{CHARACTER} and of default
-kind.
-@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
-Returns 0 on success, -1 on end-of-file and a system specific positive
-error code otherwise.
-@end multitable
-
-@item @emph{Example}:
-@smallexample
-PROGRAM test_fgetc
- INTEGER :: fd = 42, status
- CHARACTER :: c
-
- OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD")
- DO
- CALL fgetc(fd, c, status)
- IF (status /= 0) EXIT
- call fput(c)
- END DO
- CLOSE(UNIT=fd)
-END PROGRAM
-@end smallexample
-
-@item @emph{See also}:
-@ref{FGET}, @gol
-@ref{FPUT}, @gol
-@ref{FPUTC}
-@end table
-
-@node FINDLOC
-@section @code{FINDLOC} --- Search an array for a value
-@fnindex FINDLOC
-@cindex findloc
-
-@table @asis
-@item @emph{Description}:
-Determines the location of the element in the array with the value
-given in the @var{VALUE} argument, or, if the @var{DIM} argument is
-supplied, determines the locations of the elements equal to the
-@var{VALUE} argument element along each
-row of the array in the @var{DIM} direction. If @var{MASK} is
-present, only the elements for which @var{MASK} is @code{.TRUE.} are
-considered. If more than one element in the array has the value
-@var{VALUE}, the location returned is that of the first such element
-in array element order if the @var{BACK} is not present or if it is
-@code{.FALSE.}. If @var{BACK} is true, the location returned is that
-of the last such element. If the array has zero size, or all of the
-elements of @var{MASK} are @code{.FALSE.}, then the result is an array
-of zeroes. Similarly, if @var{DIM} is supplied and all of the
-elements of @var{MASK} along a given row are zero, the result value
-for that row is zero.
-
-@item @emph{Standard}:
-Fortran 2008 and later.
-
-@item @emph{Class}:
-Transformational function
-
-@item @emph{Syntax}:
-@multitable @columnfractions .80
-@item @code{RESULT = FINDLOC(ARRAY, VALUE, DIM [, MASK] [,KIND] [,BACK])}
-@item @code{RESULT = FINDLOC(ARRAY, VALUE, [, MASK] [,KIND] [,BACK])}
-@end multitable
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{ARRAY} @tab Shall be an array of intrinsic type.
-@item @var{VALUE} @tab A scalar of intrinsic type which is in type
-conformance with @var{ARRAY}.
-@item @var{DIM} @tab (Optional) Shall be a scalar of type
-@code{INTEGER}, with a value between one and the rank of @var{ARRAY},
-inclusive. It may not be an optional dummy argument.
-@item @var{MASK} @tab (Optional) Shall be of type @code{LOGICAL},
-and conformable with @var{ARRAY}.
-@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
-expression indicating the kind parameter of the result.
-@item @var{BACK} @tab (Optional) A scalar of type @code{LOGICAL}.
-@end multitable
-
-@item @emph{Return value}:
-If @var{DIM} is absent, the result is a rank-one array with a length
-equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
-is an array with a rank one less than the rank of @var{ARRAY}, and a
-size corresponding to the size of @var{ARRAY} with the @var{DIM}
-dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
-of one, the result is a scalar. If the optional argument @var{KIND}
-is present, the result is an integer of kind @var{KIND}, otherwise it
-is of default kind.
-
-@item @emph{See also}:
-@ref{MAXLOC}, @gol
-@ref{MINLOC}
-
-@end table
-
-@node FLOOR
-@section @code{FLOOR} --- Integer floor function
-@fnindex FLOOR
-@cindex floor
-@cindex rounding, floor
-
-@table @asis
-@item @emph{Description}:
-@code{FLOOR(A)} returns the greatest integer less than or equal to @var{X}.
-
-@item @emph{Standard}:
-Fortran 95 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = FLOOR(A [, KIND])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{A} @tab The type shall be @code{REAL}.
-@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
-expression indicating the kind parameter of the result.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
-and of default-kind @code{INTEGER} otherwise.
-
-@item @emph{Example}:
-@smallexample
-program test_floor
- real :: x = 63.29
- real :: y = -63.59
- print *, floor(x) ! returns 63
- print *, floor(y) ! returns -64
-end program test_floor
-@end smallexample
-
-@item @emph{See also}:
-@ref{CEILING}, @gol
-@ref{NINT}
-@end table
-
-
-
-@node FLUSH
-@section @code{FLUSH} --- Flush I/O unit(s)
-@fnindex FLUSH
-@cindex file operation, flush
-
-@table @asis
-@item @emph{Description}:
-Flushes Fortran unit(s) currently open for output. Without the optional
-argument, all units are flushed, otherwise just the unit specified.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Subroutine
-
-@item @emph{Syntax}:
-@code{CALL FLUSH(UNIT)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}.
-@end multitable
-
-@item @emph{Note}:
-Beginning with the Fortran 2003 standard, there is a @code{FLUSH}
-statement that should be preferred over the @code{FLUSH} intrinsic.
-
-The @code{FLUSH} intrinsic and the Fortran 2003 @code{FLUSH} statement
-have identical effect: they flush the runtime library's I/O buffer so
-that the data becomes visible to other processes. This does not guarantee
-that the data is committed to disk.
-
-On POSIX systems, you can request that all data is transferred to the
-storage device by calling the @code{fsync} function, with the POSIX file
-descriptor of the I/O unit as argument (retrieved with GNU intrinsic
-@code{FNUM}). The following example shows how:
-
-@smallexample
- ! Declare the interface for POSIX fsync function
- interface
- function fsync (fd) bind(c,name="fsync")
- use iso_c_binding, only: c_int
- integer(c_int), value :: fd
- integer(c_int) :: fsync
- end function fsync
- end interface
-
- ! Variable declaration
- integer :: ret
-
- ! Opening unit 10
- open (10,file="foo")
-
- ! ...
- ! Perform I/O on unit 10
- ! ...
-
- ! Flush and sync
- flush(10)
- ret = fsync(fnum(10))
-
- ! Handle possible error
- if (ret /= 0) stop "Error calling FSYNC"
-@end smallexample
-
-@end table
-
-
-
-@node FNUM
-@section @code{FNUM} --- File number function
-@fnindex FNUM
-@cindex file operation, file number
-
-@table @asis
-@item @emph{Description}:
-@code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the
-open Fortran I/O unit @code{UNIT}.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Function
-
-@item @emph{Syntax}:
-@code{RESULT = FNUM(UNIT)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{UNIT} @tab The type shall be @code{INTEGER}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{INTEGER}
-
-@item @emph{Example}:
-@smallexample
-program test_fnum
- integer :: i
- open (unit=10, status = "scratch")
- i = fnum(10)
- print *, i
- close (10)
-end program test_fnum
-@end smallexample
-@end table
-
-
-
-@node FPUT
-@section @code{FPUT} --- Write a single character in stream mode to stdout
-@fnindex FPUT
-@cindex write character, stream mode
-@cindex stream mode, write character
-@cindex file operation, write character
-
-@table @asis
-@item @emph{Description}:
-Write a single character in stream mode to stdout by bypassing normal
-formatted output. Stream I/O should not be mixed with normal record-oriented
-(formatted or unformatted) I/O on the same unit; the results are unpredictable.
-
-This intrinsic is provided in both subroutine and function forms; however,
-only one form can be used in any given program unit.
-
-Note that the @code{FGET} intrinsic is provided for backwards compatibility with
-@command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
-Programmers should consider the use of new stream IO feature in new code
-for future portability. See also @ref{Fortran 2003 status}.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Subroutine, function
-
-@item @emph{Syntax}:
-@multitable @columnfractions .80
-@item @code{CALL FPUT(C [, STATUS])}
-@item @code{STATUS = FPUT(C)}
-@end multitable
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{C} @tab The type shall be @code{CHARACTER} and of default
-kind.
-@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
-Returns 0 on success, -1 on end-of-file and a system specific positive
-error code otherwise.
-@end multitable
-
-@item @emph{Example}:
-@smallexample
-PROGRAM test_fput
- CHARACTER(len=10) :: str = "gfortran"
- INTEGER :: i
- DO i = 1, len_trim(str)
- CALL fput(str(i:i))
- END DO
-END PROGRAM
-@end smallexample
-
-@item @emph{See also}:
-@ref{FPUTC}, @gol
-@ref{FGET}, @gol
-@ref{FGETC}
-@end table
-
-
-
-@node FPUTC
-@section @code{FPUTC} --- Write a single character in stream mode
-@fnindex FPUTC
-@cindex write character, stream mode
-@cindex stream mode, write character
-@cindex file operation, write character
-
-@table @asis
-@item @emph{Description}:
-Write a single character in stream mode by bypassing normal formatted
-output. Stream I/O should not be mixed with normal record-oriented
-(formatted or unformatted) I/O on the same unit; the results are unpredictable.
-
-This intrinsic is provided in both subroutine and function forms; however,
-only one form can be used in any given program unit.
-
-Note that the @code{FGET} intrinsic is provided for backwards compatibility with
-@command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
-Programmers should consider the use of new stream IO feature in new code
-for future portability. See also @ref{Fortran 2003 status}.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Subroutine, function
-
-@item @emph{Syntax}:
-@multitable @columnfractions .80
-@item @code{CALL FPUTC(UNIT, C [, STATUS])}
-@item @code{STATUS = FPUTC(UNIT, C)}
-@end multitable
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{UNIT} @tab The type shall be @code{INTEGER}.
-@item @var{C} @tab The type shall be @code{CHARACTER} and of default
-kind.
-@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
-Returns 0 on success, -1 on end-of-file and a system specific positive
-error code otherwise.
-@end multitable
-
-@item @emph{Example}:
-@smallexample
-PROGRAM test_fputc
- CHARACTER(len=10) :: str = "gfortran"
- INTEGER :: fd = 42, i
-
- OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW")
- DO i = 1, len_trim(str)
- CALL fputc(fd, str(i:i))
- END DO
- CLOSE(fd)
-END PROGRAM
-@end smallexample
-
-@item @emph{See also}:
-@ref{FPUT}, @gol
-@ref{FGET}, @gol
-@ref{FGETC}
-@end table
-
-
-
-@node FRACTION
-@section @code{FRACTION} --- Fractional part of the model representation
-@fnindex FRACTION
-@cindex real number, fraction
-@cindex floating point, fraction
-
-@table @asis
-@item @emph{Description}:
-@code{FRACTION(X)} returns the fractional part of the model
-representation of @code{X}.
-
-@item @emph{Standard}:
-Fortran 90 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{Y = FRACTION(X)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab The type of the argument shall be a @code{REAL}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of the same type and kind as the argument.
-The fractional part of the model representation of @code{X} is returned;
-it is @code{X * RADIX(X)**(-EXPONENT(X))}.
-
-@item @emph{Example}:
-@smallexample
-program test_fraction
- real :: x
- x = 178.1387e-4
- print *, fraction(x), x * radix(x)**(-exponent(x))
-end program test_fraction
-@end smallexample
-
-@end table
-
-
-
-@node FREE
-@section @code{FREE} --- Frees memory
-@fnindex FREE
-@cindex pointer, cray
-
-@table @asis
-@item @emph{Description}:
-Frees memory previously allocated by @code{MALLOC}. The @code{FREE}
-intrinsic is an extension intended to be used with Cray pointers, and is
-provided in GNU Fortran to allow user to compile legacy code. For
-new code using Fortran 95 pointers, the memory de-allocation intrinsic is
-@code{DEALLOCATE}.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Subroutine
-
-@item @emph{Syntax}:
-@code{CALL FREE(PTR)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the
-location of the memory that should be de-allocated.
-@end multitable
-
-@item @emph{Return value}:
-None
-
-@item @emph{Example}:
-See @code{MALLOC} for an example.
-
-@item @emph{See also}:
-@ref{MALLOC}
-@end table
-
-
-
-@node FSEEK
-@section @code{FSEEK} --- Low level file positioning subroutine
-@fnindex FSEEK
-@cindex file operation, seek
-@cindex file operation, position
-
-@table @asis
-@item @emph{Description}:
-Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE}
-is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET},
-if set to 1, @var{OFFSET} is taken to be relative to the current position
-@code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}.
-On error, @var{STATUS} is set to a nonzero value. If @var{STATUS} the seek
-fails silently.
-
-This intrinsic routine is not fully backwards compatible with @command{g77}.
-In @command{g77}, the @code{FSEEK} takes a statement label instead of a
-@var{STATUS} variable. If FSEEK is used in old code, change
-@smallexample
- CALL FSEEK(UNIT, OFFSET, WHENCE, *label)
-@end smallexample
-to
-@smallexample
- INTEGER :: status
- CALL FSEEK(UNIT, OFFSET, WHENCE, status)
- IF (status /= 0) GOTO label
-@end smallexample
-
-Please note that GNU Fortran provides the Fortran 2003 Stream facility.
-Programmers should consider the use of new stream IO feature in new code
-for future portability. See also @ref{Fortran 2003 status}.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Subroutine
-
-@item @emph{Syntax}:
-@code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{UNIT} @tab Shall be a scalar of type @code{INTEGER}.
-@item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}.
-@item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}.
-Its value shall be either 0, 1 or 2.
-@item @var{STATUS} @tab (Optional) shall be a scalar of type
-@code{INTEGER(4)}.
-@end multitable
-
-@item @emph{Example}:
-@smallexample
-PROGRAM test_fseek
- INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2
- INTEGER :: fd, offset, ierr
-
- ierr = 0
- offset = 5
- fd = 10
-
- OPEN(UNIT=fd, FILE="fseek.test")
- CALL FSEEK(fd, offset, SEEK_SET, ierr) ! move to OFFSET
- print *, FTELL(fd), ierr
-
- CALL FSEEK(fd, 0, SEEK_END, ierr) ! move to end
- print *, FTELL(fd), ierr
-
- CALL FSEEK(fd, 0, SEEK_SET, ierr) ! move to beginning
- print *, FTELL(fd), ierr
-
- CLOSE(UNIT=fd)
-END PROGRAM
-@end smallexample
-
-@item @emph{See also}:
-@ref{FTELL}
-@end table
-
-
-
-@node FSTAT
-@section @code{FSTAT} --- Get file status
-@fnindex FSTAT
-@cindex file system, file status
-
-@table @asis
-@item @emph{Description}:
-@code{FSTAT} is identical to @ref{STAT}, except that information about an
-already opened file is obtained.
-
-The elements in @code{VALUES} are the same as described by @ref{STAT}.
-
-This intrinsic is provided in both subroutine and function forms; however,
-only one form can be used in any given program unit.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Subroutine, function
-
-@item @emph{Syntax}:
-@multitable @columnfractions .80
-@item @code{CALL FSTAT(UNIT, VALUES [, STATUS])}
-@item @code{STATUS = FSTAT(UNIT, VALUES)}
-@end multitable
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{UNIT} @tab An open I/O unit number of type @code{INTEGER}.
-@item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
-@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
-on success and a system specific error code otherwise.
-@end multitable
-
-@item @emph{Example}:
-See @ref{STAT} for an example.
-
-@item @emph{See also}:
-To stat a link: @gol
-@ref{LSTAT} @gol
-To stat a file: @gol
-@ref{STAT}
-@end table
-
-
-
-@node FTELL
-@section @code{FTELL} --- Current stream position
-@fnindex FTELL
-@cindex file operation, position
-
-@table @asis
-@item @emph{Description}:
-Retrieves the current position within an open file.
-
-This intrinsic is provided in both subroutine and function forms; however,
-only one form can be used in any given program unit.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Subroutine, function
-
-@item @emph{Syntax}:
-@multitable @columnfractions .80
-@item @code{CALL FTELL(UNIT, OFFSET)}
-@item @code{OFFSET = FTELL(UNIT)}
-@end multitable
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{OFFSET} @tab Shall of type @code{INTEGER}.
-@item @var{UNIT} @tab Shall of type @code{INTEGER}.
-@end multitable
-
-@item @emph{Return value}:
-In either syntax, @var{OFFSET} is set to the current offset of unit
-number @var{UNIT}, or to @math{-1} if the unit is not currently open.
-
-@item @emph{Example}:
-@smallexample
-PROGRAM test_ftell
- INTEGER :: i
- OPEN(10, FILE="temp.dat")
- CALL ftell(10,i)
- WRITE(*,*) i
-END PROGRAM
-@end smallexample
-
-@item @emph{See also}:
-@ref{FSEEK}
-@end table
-
-
-
-@node GAMMA
-@section @code{GAMMA} --- Gamma function
-@fnindex GAMMA
-@fnindex DGAMMA
-@cindex Gamma function
-@cindex Factorial function
-
-@table @asis
-@item @emph{Description}:
-@code{GAMMA(X)} computes Gamma (@math{\Gamma}) of @var{X}. For positive,
-integer values of @var{X} the Gamma function simplifies to the factorial
-function @math{\Gamma(x)=(x-1)!}.
-
-@tex
-$$
-\Gamma(x) = \int_0^\infty t^{x-1}{\rm e}^{-t}\,{\rm d}t
-$$
-@end tex
-
-@item @emph{Standard}:
-Fortran 2008 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{X = GAMMA(X)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab Shall be of type @code{REAL} and neither zero
-nor a negative integer.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{REAL} of the same kind as @var{X}.
-
-@item @emph{Example}:
-@smallexample
-program test_gamma
- real :: x = 1.0
- x = gamma(x) ! returns 1.0
-end program test_gamma
-@end smallexample
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .23 .20 .33
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{DGAMMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
-@end multitable
-
-@item @emph{See also}:
-Logarithm of the Gamma function: @gol
-@ref{LOG_GAMMA}
-@end table
-
-
-
-@node GERROR
-@section @code{GERROR} --- Get last system error message
-@fnindex GERROR
-@cindex system, error handling
-
-@table @asis
-@item @emph{Description}:
-Returns the system error message corresponding to the last system error.
-This resembles the functionality of @code{strerror(3)} in C.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Subroutine
-
-@item @emph{Syntax}:
-@code{CALL GERROR(RESULT)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{RESULT} @tab Shall be of type @code{CHARACTER} and of default kind.
-@end multitable
-
-@item @emph{Example}:
-@smallexample
-PROGRAM test_gerror
- CHARACTER(len=100) :: msg
- CALL gerror(msg)
- WRITE(*,*) msg
-END PROGRAM
-@end smallexample
-
-@item @emph{See also}:
-@ref{IERRNO}, @gol
-@ref{PERROR}
-@end table
-
-
-
-@node GETARG
-@section @code{GETARG} --- Get command line arguments
-@fnindex GETARG
-@cindex command-line arguments
-@cindex arguments, to program
-
-@table @asis
-@item @emph{Description}:
-Retrieve the @var{POS}-th argument that was passed on the
-command line when the containing program was invoked.
-
-This intrinsic routine is provided for backwards compatibility with
-GNU Fortran 77. In new code, programmers should consider the use of
-the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003
-standard.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Subroutine
-
-@item @emph{Syntax}:
-@code{CALL GETARG(POS, VALUE)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{POS} @tab Shall be of type @code{INTEGER} and not wider than
-the default integer kind; @math{@var{POS} \geq 0}
-@item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default
-kind.
-@end multitable
-
-@item @emph{Return value}:
-After @code{GETARG} returns, the @var{VALUE} argument holds the
-@var{POS}th command line argument. If @var{VALUE} cannot hold the
-argument, it is truncated to fit the length of @var{VALUE}. If there are
-less than @var{POS} arguments specified at the command line, @var{VALUE}
-will be filled with blanks. If @math{@var{POS} = 0}, @var{VALUE} is set
-to the name of the program (on systems that support this feature).
-
-@item @emph{Example}:
-@smallexample
-PROGRAM test_getarg
- INTEGER :: i
- CHARACTER(len=32) :: arg
-
- DO i = 1, iargc()
- CALL getarg(i, arg)
- WRITE (*,*) arg
- END DO
-END PROGRAM
-@end smallexample
-
-@item @emph{See also}:
-GNU Fortran 77 compatibility function: @gol
-@ref{IARGC} @gol
-Fortran 2003 functions and subroutines: @gol
-@ref{GET_COMMAND}, @gol
-@ref{GET_COMMAND_ARGUMENT}, @gol
-@ref{COMMAND_ARGUMENT_COUNT}
-@end table
-
-
-
-@node GET_COMMAND
-@section @code{GET_COMMAND} --- Get the entire command line
-@fnindex GET_COMMAND
-@cindex command-line arguments
-@cindex arguments, to program
-
-@table @asis
-@item @emph{Description}:
-Retrieve the entire command line that was used to invoke the program.
-
-@item @emph{Standard}:
-Fortran 2003 and later
-
-@item @emph{Class}:
-Subroutine
-
-@item @emph{Syntax}:
-@code{CALL GET_COMMAND([COMMAND, LENGTH, STATUS])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{COMMAND} @tab (Optional) shall be of type @code{CHARACTER} and
-of default kind.
-@item @var{LENGTH} @tab (Optional) Shall be of type @code{INTEGER} and of
-default kind.
-@item @var{STATUS} @tab (Optional) Shall be of type @code{INTEGER} and of
-default kind.
-@end multitable
-
-@item @emph{Return value}:
-If @var{COMMAND} is present, stores the entire command line that was used
-to invoke the program in @var{COMMAND}. If @var{LENGTH} is present, it is
-assigned the length of the command line. If @var{STATUS} is present, it
-is assigned 0 upon success of the command, -1 if @var{COMMAND} is too
-short to store the command line, or a positive value in case of an error.
-
-@item @emph{Example}:
-@smallexample
-PROGRAM test_get_command
- CHARACTER(len=255) :: cmd
- CALL get_command(cmd)
- WRITE (*,*) TRIM(cmd)
-END PROGRAM
-@end smallexample
-
-@item @emph{See also}:
-@ref{GET_COMMAND_ARGUMENT}, @gol
-@ref{COMMAND_ARGUMENT_COUNT}
-@end table
-
-
-
-@node GET_COMMAND_ARGUMENT
-@section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments
-@fnindex GET_COMMAND_ARGUMENT
-@cindex command-line arguments
-@cindex arguments, to program
-
-@table @asis
-@item @emph{Description}:
-Retrieve the @var{NUMBER}-th argument that was passed on the
-command line when the containing program was invoked.
-
-@item @emph{Standard}:
-Fortran 2003 and later
-
-@item @emph{Class}:
-Subroutine
-
-@item @emph{Syntax}:
-@code{CALL GET_COMMAND_ARGUMENT(NUMBER [, VALUE, LENGTH, STATUS])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{NUMBER} @tab Shall be a scalar of type @code{INTEGER} and of
-default kind, @math{@var{NUMBER} \geq 0}
-@item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER}
-and of default kind.
-@item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER}
-and of default kind.
-@item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER}
-and of default kind.
-@end multitable
-
-@item @emph{Return value}:
-After @code{GET_COMMAND_ARGUMENT} returns, the @var{VALUE} argument holds the
-@var{NUMBER}-th command line argument. If @var{VALUE} cannot hold the argument, it is
-truncated to fit the length of @var{VALUE}. If there are less than @var{NUMBER}
-arguments specified at the command line, @var{VALUE} will be filled with blanks.
-If @math{@var{NUMBER} = 0}, @var{VALUE} is set to the name of the program (on
-systems that support this feature). The @var{LENGTH} argument contains the
-length of the @var{NUMBER}-th command line argument. If the argument retrieval
-fails, @var{STATUS} is a positive number; if @var{VALUE} contains a truncated
-command line argument, @var{STATUS} is -1; and otherwise the @var{STATUS} is
-zero.
-
-@item @emph{Example}:
-@smallexample
-PROGRAM test_get_command_argument
- INTEGER :: i
- CHARACTER(len=32) :: arg
-
- i = 0
- DO
- CALL get_command_argument(i, arg)
- IF (LEN_TRIM(arg) == 0) EXIT
-
- WRITE (*,*) TRIM(arg)
- i = i+1
- END DO
-END PROGRAM
-@end smallexample
-
-@item @emph{See also}:
-@ref{GET_COMMAND}, @gol
-@ref{COMMAND_ARGUMENT_COUNT}
-@end table
-
-
-
-@node GETCWD
-@section @code{GETCWD} --- Get current working directory
-@fnindex GETCWD
-@cindex system, working directory
-
-@table @asis
-@item @emph{Description}:
-Get current working directory.
-
-This intrinsic is provided in both subroutine and function forms; however,
-only one form can be used in any given program unit.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Subroutine, function
-
-@item @emph{Syntax}:
-@multitable @columnfractions .80
-@item @code{CALL GETCWD(C [, STATUS])}
-@item @code{STATUS = GETCWD(C)}
-@end multitable
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{C} @tab The type shall be @code{CHARACTER} and of default kind.
-@item @var{STATUS} @tab (Optional) status flag. Returns 0 on success,
-a system specific and nonzero error code otherwise.
-@end multitable
-
-@item @emph{Example}:
-@smallexample
-PROGRAM test_getcwd
- CHARACTER(len=255) :: cwd
- CALL getcwd(cwd)
- WRITE(*,*) TRIM(cwd)
-END PROGRAM
-@end smallexample
-
-@item @emph{See also}:
-@ref{CHDIR}
-@end table
-
-
-
-@node GETENV
-@section @code{GETENV} --- Get an environmental variable
-@fnindex GETENV
-@cindex environment variable
-
-@table @asis
-@item @emph{Description}:
-Get the @var{VALUE} of the environmental variable @var{NAME}.
-
-This intrinsic routine is provided for backwards compatibility with
-GNU Fortran 77. In new code, programmers should consider the use of
-the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran
-2003 standard.
-
-Note that @code{GETENV} need not be thread-safe. It is the
-responsibility of the user to ensure that the environment is not being
-updated concurrently with a call to the @code{GETENV} intrinsic.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Subroutine
-
-@item @emph{Syntax}:
-@code{CALL GETENV(NAME, VALUE)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{NAME} @tab Shall be of type @code{CHARACTER} and of default kind.
-@item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default kind.
-@end multitable
-
-@item @emph{Return value}:
-Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
-not large enough to hold the data, it is truncated. If @var{NAME}
-is not set, @var{VALUE} will be filled with blanks.
-
-@item @emph{Example}:
-@smallexample
-PROGRAM test_getenv
- CHARACTER(len=255) :: homedir
- CALL getenv("HOME", homedir)
- WRITE (*,*) TRIM(homedir)
-END PROGRAM
-@end smallexample
-
-@item @emph{See also}:
-@ref{GET_ENVIRONMENT_VARIABLE}
-@end table
-
-
-
-@node GET_ENVIRONMENT_VARIABLE
-@section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable
-@fnindex GET_ENVIRONMENT_VARIABLE
-@cindex environment variable
-
-@table @asis
-@item @emph{Description}:
-Get the @var{VALUE} of the environmental variable @var{NAME}.
-
-Note that @code{GET_ENVIRONMENT_VARIABLE} need not be thread-safe. It
-is the responsibility of the user to ensure that the environment is
-not being updated concurrently with a call to the
-@code{GET_ENVIRONMENT_VARIABLE} intrinsic.
-
-@item @emph{Standard}:
-Fortran 2003 and later
-
-@item @emph{Class}:
-Subroutine
-
-@item @emph{Syntax}:
-@code{CALL GET_ENVIRONMENT_VARIABLE(NAME[, VALUE, LENGTH, STATUS, TRIM_NAME)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{NAME} @tab Shall be a scalar of type @code{CHARACTER}
-and of default kind.
-@item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER}
-and of default kind.
-@item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER}
-and of default kind.
-@item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER}
-and of default kind.
-@item @var{TRIM_NAME} @tab (Optional) Shall be a scalar of type @code{LOGICAL}
-and of default kind.
-@end multitable
-
-@item @emph{Return value}:
-Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
-not large enough to hold the data, it is truncated. If @var{NAME}
-is not set, @var{VALUE} will be filled with blanks. Argument @var{LENGTH}
-contains the length needed for storing the environment variable @var{NAME}
-or zero if it is not present. @var{STATUS} is -1 if @var{VALUE} is present
-but too short for the environment variable; it is 1 if the environment
-variable does not exist and 2 if the processor does not support environment
-variables; in all other cases @var{STATUS} is zero. If @var{TRIM_NAME} is
-present with the value @code{.FALSE.}, the trailing blanks in @var{NAME}
-are significant; otherwise they are not part of the environment variable
-name.
-
-@item @emph{Example}:
-@smallexample
-PROGRAM test_getenv
- CHARACTER(len=255) :: homedir
- CALL get_environment_variable("HOME", homedir)
- WRITE (*,*) TRIM(homedir)
-END PROGRAM
-@end smallexample
-@end table
-
-
-
-@node GETGID
-@section @code{GETGID} --- Group ID function
-@fnindex GETGID
-@cindex system, group ID
-
-@table @asis
-@item @emph{Description}:
-Returns the numerical group ID of the current process.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Function
-
-@item @emph{Syntax}:
-@code{RESULT = GETGID()}
-
-@item @emph{Return value}:
-The return value of @code{GETGID} is an @code{INTEGER} of the default
-kind.
-
-
-@item @emph{Example}:
-See @code{GETPID} for an example.
-
-@item @emph{See also}:
-@ref{GETPID}, @gol
-@ref{GETUID}
-@end table
-
-
-
-@node GETLOG
-@section @code{GETLOG} --- Get login name
-@fnindex GETLOG
-@cindex system, login name
-@cindex login name
-
-@table @asis
-@item @emph{Description}:
-Gets the username under which the program is running.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Subroutine
-
-@item @emph{Syntax}:
-@code{CALL GETLOG(C)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{C} @tab Shall be of type @code{CHARACTER} and of default kind.
-@end multitable
-
-@item @emph{Return value}:
-Stores the current user name in @var{C}. (On systems where POSIX
-functions @code{geteuid} and @code{getpwuid} are not available, and
-the @code{getlogin} function is not implemented either, this will
-return a blank string.)
-
-@item @emph{Example}:
-@smallexample
-PROGRAM TEST_GETLOG
- CHARACTER(32) :: login
- CALL GETLOG(login)
- WRITE(*,*) login
-END PROGRAM
-@end smallexample
-
-@item @emph{See also}:
-@ref{GETUID}
-@end table
-
-
-
-@node GETPID
-@section @code{GETPID} --- Process ID function
-@fnindex GETPID
-@cindex system, process ID
-@cindex process ID
-
-@table @asis
-@item @emph{Description}:
-Returns the numerical process identifier of the current process.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Function
-
-@item @emph{Syntax}:
-@code{RESULT = GETPID()}
-
-@item @emph{Return value}:
-The return value of @code{GETPID} is an @code{INTEGER} of the default
-kind.
-
-
-@item @emph{Example}:
-@smallexample
-program info
- print *, "The current process ID is ", getpid()
- print *, "Your numerical user ID is ", getuid()
- print *, "Your numerical group ID is ", getgid()
-end program info
-@end smallexample
-
-@item @emph{See also}:
-@ref{GETGID}, @gol
-@ref{GETUID}
-@end table
-
-
-
-@node GETUID
-@section @code{GETUID} --- User ID function
-@fnindex GETUID
-@cindex system, user ID
-@cindex user id
-
-@table @asis
-@item @emph{Description}:
-Returns the numerical user ID of the current process.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Function
-
-@item @emph{Syntax}:
-@code{RESULT = GETUID()}
-
-@item @emph{Return value}:
-The return value of @code{GETUID} is an @code{INTEGER} of the default
-kind.
-
-
-@item @emph{Example}:
-See @code{GETPID} for an example.
-
-@item @emph{See also}:
-@ref{GETPID}, @gol
-@ref{GETLOG}
-@end table
-
-
-
-@node GMTIME
-@section @code{GMTIME} --- Convert time to GMT info
-@fnindex GMTIME
-@cindex time, conversion to GMT info
-
-@table @asis
-@item @emph{Description}:
-Given a system time value @var{TIME} (as provided by the @ref{TIME}
-intrinsic), fills @var{VALUES} with values extracted from it appropriate
-to the UTC time zone (Universal Coordinated Time, also known in some
-countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}.
-
-This intrinsic routine is provided for backwards compatibility with
-GNU Fortran 77. In new code, programmers should consider the use of
-the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95
-standard.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Subroutine
-
-@item @emph{Syntax}:
-@code{CALL GMTIME(TIME, VALUES)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{TIME} @tab An @code{INTEGER} scalar expression
-corresponding to a system time, with @code{INTENT(IN)}.
-@item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
-with @code{INTENT(OUT)}.
-@end multitable
-
-@item @emph{Return value}:
-The elements of @var{VALUES} are assigned as follows:
-@enumerate
-@item Seconds after the minute, range 0--59 or 0--61 to allow for leap
-seconds
-@item Minutes after the hour, range 0--59
-@item Hours past midnight, range 0--23
-@item Day of month, range 1--31
-@item Number of months since January, range 0--11
-@item Years since 1900
-@item Number of days since Sunday, range 0--6
-@item Days since January 1, range 0--365
-@item Daylight savings indicator: positive if daylight savings is in
-effect, zero if not, and negative if the information is not available.
-@end enumerate
-
-@item @emph{See also}:
-@ref{DATE_AND_TIME}, @gol
-@ref{CTIME}, @gol
-@ref{LTIME}, @gol
-@ref{TIME}, @gol
-@ref{TIME8}
-@end table
-
-
-
-@node HOSTNM
-@section @code{HOSTNM} --- Get system host name
-@fnindex HOSTNM
-@cindex system, host name
-
-@table @asis
-@item @emph{Description}:
-Retrieves the host name of the system on which the program is running.
-
-This intrinsic is provided in both subroutine and function forms; however,
-only one form can be used in any given program unit.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Subroutine, function
-
-@item @emph{Syntax}:
-@multitable @columnfractions .80
-@item @code{CALL HOSTNM(C [, STATUS])}
-@item @code{STATUS = HOSTNM(NAME)}
-@end multitable
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{C} @tab Shall of type @code{CHARACTER} and of default kind.
-@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
-Returns 0 on success, or a system specific error code otherwise.
-@end multitable
-
-@item @emph{Return value}:
-In either syntax, @var{NAME} is set to the current hostname if it can
-be obtained, or to a blank string otherwise.
-
-@end table
-
-
-
-@node HUGE
-@section @code{HUGE} --- Largest number of a kind
-@fnindex HUGE
-@cindex limits, largest number
-@cindex model representation, largest number
-
-@table @asis
-@item @emph{Description}:
-@code{HUGE(X)} returns the largest number that is not an infinity in
-the model of the type of @code{X}.
-
-@item @emph{Standard}:
-Fortran 90 and later
-
-@item @emph{Class}:
-Inquiry function
-
-@item @emph{Syntax}:
-@code{RESULT = HUGE(X)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of the same type and kind as @var{X}
-
-@item @emph{Example}:
-@smallexample
-program test_huge_tiny
- print *, huge(0), huge(0.0), huge(0.0d0)
- print *, tiny(0.0), tiny(0.0d0)
-end program test_huge_tiny
-@end smallexample
-@end table
-
-
-
-@node HYPOT
-@section @code{HYPOT} --- Euclidean distance function
-@fnindex HYPOT
-@cindex Euclidean distance
-
-@table @asis
-@item @emph{Description}:
-@code{HYPOT(X,Y)} is the Euclidean distance function. It is equal to
-@math{\sqrt{X^2 + Y^2}}, without undue underflow or overflow.
-
-@item @emph{Standard}:
-Fortran 2008 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = HYPOT(X, Y)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab The type shall be @code{REAL}.
-@item @var{Y} @tab The type and kind type parameter shall be the same as
-@var{X}.
-@end multitable
-
-@item @emph{Return value}:
-The return value has the same type and kind type parameter as @var{X}.
-
-@item @emph{Example}:
-@smallexample
-program test_hypot
- real(4) :: x = 1.e0_4, y = 0.5e0_4
- x = hypot(x,y)
-end program test_hypot
-@end smallexample
-@end table
-
-
-
-@node IACHAR
-@section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence
-@fnindex IACHAR
-@cindex @acronym{ASCII} collating sequence
-@cindex collating sequence, @acronym{ASCII}
-@cindex conversion, to integer
-
-@table @asis
-@item @emph{Description}:
-@code{IACHAR(C)} returns the code for the @acronym{ASCII} character
-in the first character position of @code{C}.
-
-@item @emph{Standard}:
-Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = IACHAR(C [, KIND])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
-@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
-expression indicating the kind parameter of the result.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{INTEGER} and of kind @var{KIND}. If
-@var{KIND} is absent, the return value is of default integer kind.
-
-@item @emph{Example}:
-@smallexample
-program test_iachar
- integer i
- i = iachar(' ')
-end program test_iachar
-@end smallexample
-
-@item @emph{Note}:
-See @ref{ICHAR} for a discussion of converting between numerical values
-and formatted string representations.
-
-@item @emph{See also}:
-@ref{ACHAR}, @gol
-@ref{CHAR}, @gol
-@ref{ICHAR}
-@end table
-
-
-
-@node IALL
-@section @code{IALL} --- Bitwise AND of array elements
-@fnindex IALL
-@cindex array, AND
-@cindex bits, AND of array elements
-
-@table @asis
-@item @emph{Description}:
-Reduces with bitwise AND the elements of @var{ARRAY} along dimension @var{DIM}
-if the corresponding element in @var{MASK} is @code{TRUE}.
-
-@item @emph{Standard}:
-Fortran 2008 and later
-
-@item @emph{Class}:
-Transformational function
-
-@item @emph{Syntax}:
-@multitable @columnfractions .80
-@item @code{RESULT = IALL(ARRAY[, MASK])}
-@item @code{RESULT = IALL(ARRAY, DIM[, MASK])}
-@end multitable
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
-@item @var{DIM} @tab (Optional) shall be a scalar of type
-@code{INTEGER} with a value in the range from 1 to n, where n
-equals the rank of @var{ARRAY}.
-@item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
-and either be a scalar or an array of the same shape as @var{ARRAY}.
-@end multitable
-
-@item @emph{Return value}:
-The result is of the same type as @var{ARRAY}.
-
-If @var{DIM} is absent, a scalar with the bitwise ALL of all elements in
-@var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
-the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
-dimension @var{DIM} dropped is returned.
-
-@item @emph{Example}:
-@smallexample
-PROGRAM test_iall
- INTEGER(1) :: a(2)
-
- a(1) = b'00100100'
- a(2) = b'01101010'
-
- ! prints 00100000
- PRINT '(b8.8)', IALL(a)
-END PROGRAM
-@end smallexample
-
-@item @emph{See also}:
-@ref{IANY}, @gol
-@ref{IPARITY}, @gol
-@ref{IAND}
-@end table
-
-
-
-@node IAND
-@section @code{IAND} --- Bitwise logical and
-@fnindex IAND
-@fnindex BIAND
-@fnindex IIAND
-@fnindex JIAND
-@fnindex KIAND
-@cindex bitwise logical and
-@cindex logical and, bitwise
-
-@table @asis
-@item @emph{Description}:
-Bitwise logical @code{AND}.
-
-@item @emph{Standard}:
-Fortran 90 and later, with boz-literal-constant Fortran 2008 and later, has overloads that are GNU extensions
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = IAND(I, J)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{I} @tab The type shall be @code{INTEGER} or a boz-literal-constant.
-@item @var{J} @tab The type shall be @code{INTEGER} with the same
-kind type parameter as @var{I} or a boz-literal-constant.
-@var{I} and @var{J} shall not both be boz-literal-constants.
-@end multitable
-
-@item @emph{Return value}:
-The return type is @code{INTEGER} with the kind type parameter of the
-arguments.
-A boz-literal-constant is converted to an @code{INTEGER} with the kind
-type parameter of the other argument as-if a call to @ref{INT} occurred.
-
-@item @emph{Example}:
-@smallexample
-PROGRAM test_iand
- INTEGER :: a, b
- DATA a / Z'F' /, b / Z'3' /
- WRITE (*,*) IAND(a, b)
-END PROGRAM
-@end smallexample
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .23 .20 .33
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{IAND(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later
-@item @code{BIAND(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
-@item @code{IIAND(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
-@item @code{JIAND(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
-@item @code{KIAND(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
-@end multitable
-
-@item @emph{See also}:
-@ref{IOR}, @gol
-@ref{IEOR}, @gol
-@ref{IBITS}, @gol
-@ref{IBSET}, @gol
-@ref{IBCLR}, @gol
-@ref{NOT}
-@end table
-
-
-
-@node IANY
-@section @code{IANY} --- Bitwise OR of array elements
-@fnindex IANY
-@cindex array, OR
-@cindex bits, OR of array elements
-
-@table @asis
-@item @emph{Description}:
-Reduces with bitwise OR (inclusive or) the elements of @var{ARRAY} along
-dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
-
-@item @emph{Standard}:
-Fortran 2008 and later
-
-@item @emph{Class}:
-Transformational function
-
-@item @emph{Syntax}:
-@multitable @columnfractions .80
-@item @code{RESULT = IANY(ARRAY[, MASK])}
-@item @code{RESULT = IANY(ARRAY, DIM[, MASK])}
-@end multitable
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
-@item @var{DIM} @tab (Optional) shall be a scalar of type
-@code{INTEGER} with a value in the range from 1 to n, where n
-equals the rank of @var{ARRAY}.
-@item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
-and either be a scalar or an array of the same shape as @var{ARRAY}.
-@end multitable
-
-@item @emph{Return value}:
-The result is of the same type as @var{ARRAY}.
-
-If @var{DIM} is absent, a scalar with the bitwise OR of all elements in
-@var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
-the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
-dimension @var{DIM} dropped is returned.
-
-@item @emph{Example}:
-@smallexample
-PROGRAM test_iany
- INTEGER(1) :: a(2)
-
- a(1) = b'00100100'
- a(2) = b'01101010'
-
- ! prints 01101110
- PRINT '(b8.8)', IANY(a)
-END PROGRAM
-@end smallexample
-
-@item @emph{See also}:
-@ref{IPARITY}, @gol
-@ref{IALL}, @gol
-@ref{IOR}
-@end table
-
-
-
-@node IARGC
-@section @code{IARGC} --- Get the number of command line arguments
-@fnindex IARGC
-@cindex command-line arguments
-@cindex command-line arguments, number of
-@cindex arguments, to program
-
-@table @asis
-@item @emph{Description}:
-@code{IARGC} returns the number of arguments passed on the
-command line when the containing program was invoked.
-
-This intrinsic routine is provided for backwards compatibility with
-GNU Fortran 77. In new code, programmers should consider the use of
-the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003
-standard.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Function
-
-@item @emph{Syntax}:
-@code{RESULT = IARGC()}
-
-@item @emph{Arguments}:
-None
-
-@item @emph{Return value}:
-The number of command line arguments, type @code{INTEGER(4)}.
-
-@item @emph{Example}:
-See @ref{GETARG}
-
-@item @emph{See also}:
-GNU Fortran 77 compatibility subroutine: @gol
-@ref{GETARG} @gol
-Fortran 2003 functions and subroutines: @gol
-@ref{GET_COMMAND}, @gol
-@ref{GET_COMMAND_ARGUMENT}, @gol
-@ref{COMMAND_ARGUMENT_COUNT}
-@end table
-
-
-
-@node IBCLR
-@section @code{IBCLR} --- Clear bit
-@fnindex IBCLR
-@fnindex BBCLR
-@fnindex IIBCLR
-@fnindex JIBCLR
-@fnindex KIBCLR
-@cindex bits, unset
-@cindex bits, clear
-
-@table @asis
-@item @emph{Description}:
-@code{IBCLR} returns the value of @var{I} with the bit at position
-@var{POS} set to zero.
-
-@item @emph{Standard}:
-Fortran 90 and later, has overloads that are GNU extensions
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = IBCLR(I, POS)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{I} @tab The type shall be @code{INTEGER}.
-@item @var{POS} @tab The type shall be @code{INTEGER}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{INTEGER} and of the same kind as
-@var{I}.
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .23 .20 .33
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{IBCLR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later
-@item @code{BBCLR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
-@item @code{IIBCLR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
-@item @code{JIBCLR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
-@item @code{KIBCLR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
-@end multitable
-
-@item @emph{See also}:
-@ref{IBITS}, @gol
-@ref{IBSET}, @gol
-@ref{IAND}, @gol
-@ref{IOR}, @gol
-@ref{IEOR}, @gol
-@ref{MVBITS}
-@end table
-
-
-
-@node IBITS
-@section @code{IBITS} --- Bit extraction
-@fnindex IBITS
-@fnindex BBITS
-@fnindex IIBITS
-@fnindex JIBITS
-@fnindex KIBITS
-@cindex bits, get
-@cindex bits, extract
-
-@table @asis
-@item @emph{Description}:
-@code{IBITS} extracts a field of length @var{LEN} from @var{I},
-starting from bit position @var{POS} and extending left for @var{LEN}
-bits. The result is right-justified and the remaining bits are
-zeroed. The value of @code{POS+LEN} must be less than or equal to the
-value @code{BIT_SIZE(I)}.
-
-@item @emph{Standard}:
-Fortran 90 and later, has overloads that are GNU extensions
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = IBITS(I, POS, LEN)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{I} @tab The type shall be @code{INTEGER}.
-@item @var{POS} @tab The type shall be @code{INTEGER}.
-@item @var{LEN} @tab The type shall be @code{INTEGER}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{INTEGER} and of the same kind as
-@var{I}.
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .23 .20 .33
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{IBITS(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later
-@item @code{BBITS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
-@item @code{IIBITS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
-@item @code{JIBITS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
-@item @code{KIBITS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
-@end multitable
-
-@item @emph{See also}:
-@ref{BIT_SIZE}, @gol
-@ref{IBCLR}, @gol
-@ref{IBSET}, @gol
-@ref{IAND}, @gol
-@ref{IOR}, @gol
-@ref{IEOR}
-@end table
-
-
-
-@node IBSET
-@section @code{IBSET} --- Set bit
-@fnindex IBSET
-@fnindex BBSET
-@fnindex IIBSET
-@fnindex JIBSET
-@fnindex KIBSET
-@cindex bits, set
-
-@table @asis
-@item @emph{Description}:
-@code{IBSET} returns the value of @var{I} with the bit at position
-@var{POS} set to one.
-
-@item @emph{Standard}:
-Fortran 90 and later, has overloads that are GNU extensions
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = IBSET(I, POS)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{I} @tab The type shall be @code{INTEGER}.
-@item @var{POS} @tab The type shall be @code{INTEGER}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{INTEGER} and of the same kind as
-@var{I}.
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .23 .20 .33
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{IBSET(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later
-@item @code{BBSET(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
-@item @code{IIBSET(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
-@item @code{JIBSET(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
-@item @code{KIBSET(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
-@end multitable
-
-@item @emph{See also}:
-@ref{IBCLR}, @gol
-@ref{IBITS}, @gol
-@ref{IAND}, @gol
-@ref{IOR}, @gol
-@ref{IEOR}, @gol
-@ref{MVBITS}
-@end table
-
-
-
-@node ICHAR
-@section @code{ICHAR} --- Character-to-integer conversion function
-@fnindex ICHAR
-@cindex conversion, to integer
-
-@table @asis
-@item @emph{Description}:
-@code{ICHAR(C)} returns the code for the character in the first character
-position of @code{C} in the system's native character set.
-The correspondence between characters and their codes is not necessarily
-the same across different GNU Fortran implementations.
-
-@item @emph{Standard}:
-Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = ICHAR(C [, KIND])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
-@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
-expression indicating the kind parameter of the result.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{INTEGER} and of kind @var{KIND}. If
-@var{KIND} is absent, the return value is of default integer kind.
-
-@item @emph{Example}:
-@smallexample
-program test_ichar
- integer i
- i = ichar(' ')
-end program test_ichar
-@end smallexample
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .23 .20 .33
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{ICHAR(C)} @tab @code{CHARACTER C} @tab @code{INTEGER(4)} @tab Fortran 77 and later
-@end multitable
-
-@item @emph{Note}:
-No intrinsic exists to convert between a numeric value and a formatted
-character string representation -- for instance, given the
-@code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or
-@code{REAL} value with the value 154, or vice versa. Instead, this
-functionality is provided by internal-file I/O, as in the following
-example:
-@smallexample
-program read_val
- integer value
- character(len=10) string, string2
- string = '154'
-
- ! Convert a string to a numeric value
- read (string,'(I10)') value
- print *, value
-
- ! Convert a value to a formatted string
- write (string2,'(I10)') value
- print *, string2
-end program read_val
-@end smallexample
-
-@item @emph{See also}:
-@ref{ACHAR}, @gol
-@ref{CHAR}, @gol
-@ref{IACHAR}
-@end table
-
-
-
-@node IDATE
-@section @code{IDATE} --- Get current local time subroutine (day/month/year)
-@fnindex IDATE
-@cindex date, current
-@cindex current date
-
-@table @asis
-@item @emph{Description}:
-@code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
-current local time. The day (in the range 1-31), month (in the range 1-12),
-and year appear in elements 1, 2, and 3 of @var{VALUES}, respectively.
-The year has four significant digits.
-
-This intrinsic routine is provided for backwards compatibility with
-GNU Fortran 77. In new code, programmers should consider the use of
-the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95
-standard.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Subroutine
-
-@item @emph{Syntax}:
-@code{CALL IDATE(VALUES)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} and
-the kind shall be the default integer kind.
-@end multitable
-
-@item @emph{Return value}:
-Does not return anything.
-
-@item @emph{Example}:
-@smallexample
-program test_idate
- integer, dimension(3) :: tarray
- call idate(tarray)
- print *, tarray(1)
- print *, tarray(2)
- print *, tarray(3)
-end program test_idate
-@end smallexample
-
-@item @emph{See also}:
-@ref{DATE_AND_TIME}
-@end table
-
-
-@node IEOR
-@section @code{IEOR} --- Bitwise logical exclusive or
-@fnindex IEOR
-@fnindex BIEOR
-@fnindex IIEOR
-@fnindex JIEOR
-@fnindex KIEOR
-@cindex bitwise logical exclusive or
-@cindex logical exclusive or, bitwise
-
-@table @asis
-@item @emph{Description}:
-@code{IEOR} returns the bitwise Boolean exclusive-OR of @var{I} and
-@var{J}.
-
-@item @emph{Standard}:
-Fortran 90 and later, with boz-literal-constant Fortran 2008 and later, has overloads that are GNU extensions
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = IEOR(I, J)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{I} @tab The type shall be @code{INTEGER} or a boz-literal-constant.
-@item @var{J} @tab The type shall be @code{INTEGER} with the same
-kind type parameter as @var{I} or a boz-literal-constant.
-@var{I} and @var{J} shall not both be boz-literal-constants.
-@end multitable
-
-@item @emph{Return value}:
-The return type is @code{INTEGER} with the kind type parameter of the
-arguments.
-A boz-literal-constant is converted to an @code{INTEGER} with the kind
-type parameter of the other argument as-if a call to @ref{INT} occurred.
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .23 .20 .33
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{IEOR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later
-@item @code{BIEOR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
-@item @code{IIEOR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
-@item @code{JIEOR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
-@item @code{KIEOR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
-@end multitable
-
-@item @emph{See also}:
-@ref{IOR}, @gol
-@ref{IAND}, @gol
-@ref{IBITS}, @gol
-@ref{IBSET}, @gol
-@ref{IBCLR}, @gol
-@ref{NOT}
-@end table
-
-
-
-@node IERRNO
-@section @code{IERRNO} --- Get the last system error number
-@fnindex IERRNO
-@cindex system, error handling
-
-@table @asis
-@item @emph{Description}:
-Returns the last system error number, as given by the C @code{errno}
-variable.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Function
-
-@item @emph{Syntax}:
-@code{RESULT = IERRNO()}
-
-@item @emph{Arguments}:
-None
-
-@item @emph{Return value}:
-The return value is of type @code{INTEGER} and of the default integer
-kind.
-
-@item @emph{See also}:
-@ref{PERROR}
-@end table
-
-
-
-@node IMAGE_INDEX
-@section @code{IMAGE_INDEX} --- Function that converts a cosubscript to an image index
-@fnindex IMAGE_INDEX
-@cindex coarray, @code{IMAGE_INDEX}
-@cindex images, cosubscript to image index conversion
-
-@table @asis
-@item @emph{Description}:
-Returns the image index belonging to a cosubscript.
-
-@item @emph{Standard}:
-Fortran 2008 and later
-
-@item @emph{Class}:
-Inquiry function.
-
-@item @emph{Syntax}:
-@code{RESULT = IMAGE_INDEX(COARRAY, SUB)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{COARRAY} @tab Coarray of any type.
-@item @var{SUB} @tab default integer rank-1 array of a size equal to
-the corank of @var{COARRAY}.
-@end multitable
-
-
-@item @emph{Return value}:
-Scalar default integer with the value of the image index which corresponds
-to the cosubscripts. For invalid cosubscripts the result is zero.
-
-@item @emph{Example}:
-@smallexample
-INTEGER :: array[2,-1:4,8,*]
-! Writes 28 (or 0 if there are fewer than 28 images)
-WRITE (*,*) IMAGE_INDEX (array, [2,0,3,1])
-@end smallexample
-
-@item @emph{See also}:
-@ref{THIS_IMAGE}, @gol
-@ref{NUM_IMAGES}
-@end table
-
-
-
-@node INDEX intrinsic
-@section @code{INDEX} --- Position of a substring within a string
-@fnindex INDEX
-@cindex substring position
-@cindex string, find substring
-
-@table @asis
-@item @emph{Description}:
-Returns the position of the start of the first occurrence of string
-@var{SUBSTRING} as a substring in @var{STRING}, counting from one. If
-@var{SUBSTRING} is not present in @var{STRING}, zero is returned. If
-the @var{BACK} argument is present and true, the return value is the
-start of the last occurrence rather than the first.
-
-@item @emph{Standard}:
-Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = INDEX(STRING, SUBSTRING [, BACK [, KIND]])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{STRING} @tab Shall be a scalar @code{CHARACTER}, with
-@code{INTENT(IN)}
-@item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER}, with
-@code{INTENT(IN)}
-@item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL}, with
-@code{INTENT(IN)}
-@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
-expression indicating the kind parameter of the result.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{INTEGER} and of kind @var{KIND}. If
-@var{KIND} is absent, the return value is of default integer kind.
-
-@item @emph{Specific names}:
-@multitable @columnfractions .35 .15 .17 .30
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{INDEX(STRING,SUBSTRING)} @tab @code{CHARACTER} @tab @code{INTEGER(4)} @tab Fortran 77 and later
-@end multitable
-
-@item @emph{See also}:
-@ref{SCAN}, @gol
-@ref{VERIFY}
-@end table
-
-
-
-@node INT
-@section @code{INT} --- Convert to integer type
-@fnindex INT
-@fnindex IFIX
-@fnindex IDINT
-@cindex conversion, to integer
-
-@table @asis
-@item @emph{Description}:
-Convert to integer type
-
-@item @emph{Standard}:
-Fortran 77 and later, with boz-literal-constant Fortran 2008 and later.
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = INT(A [, KIND))}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{A} @tab Shall be of type @code{INTEGER},
-@code{REAL}, or @code{COMPLEX} or a boz-literal-constant.
-@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
-expression indicating the kind parameter of the result.
-@end multitable
-
-@item @emph{Return value}:
-These functions return a @code{INTEGER} variable or array under
-the following rules:
-
-@table @asis
-@item (A)
-If @var{A} is of type @code{INTEGER}, @code{INT(A) = A}
-@item (B)
-If @var{A} is of type @code{REAL} and @math{|A| < 1}, @code{INT(A)}
-equals @code{0}. If @math{|A| \geq 1}, then @code{INT(A)} is the integer
-whose magnitude is the largest integer that does not exceed the magnitude
-of @var{A} and whose sign is the same as the sign of @var{A}.
-@item (C)
-If @var{A} is of type @code{COMPLEX}, rule B is applied to the real part of @var{A}.
-@end table
-
-@item @emph{Example}:
-@smallexample
-program test_int
- integer :: i = 42
- complex :: z = (-3.7, 1.0)
- print *, int(i)
- print *, int(z), int(z,8)
-end program
-@end smallexample
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .23 .20 .33
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{INT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
-@item @code{IFIX(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
-@item @code{IDINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 77 and later
-@end multitable
-
-@end table
-
-
-@node INT2
-@section @code{INT2} --- Convert to 16-bit integer type
-@fnindex INT2
-@cindex conversion, to integer
-
-@table @asis
-@item @emph{Description}:
-Convert to a @code{KIND=2} integer type. This is equivalent to the
-standard @code{INT} intrinsic with an optional argument of
-@code{KIND=2}, and is only included for backwards compatibility.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = INT2(A)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{A} @tab Shall be of type @code{INTEGER},
-@code{REAL}, or @code{COMPLEX}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is a @code{INTEGER(2)} variable.
-
-@item @emph{See also}:
-@ref{INT}, @gol
-@ref{INT8}
-@end table
-
-
-
-@node INT8
-@section @code{INT8} --- Convert to 64-bit integer type
-@fnindex INT8
-@cindex conversion, to integer
-
-@table @asis
-@item @emph{Description}:
-Convert to a @code{KIND=8} integer type. This is equivalent to the
-standard @code{INT} intrinsic with an optional argument of
-@code{KIND=8}, and is only included for backwards compatibility.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = INT8(A)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{A} @tab Shall be of type @code{INTEGER},
-@code{REAL}, or @code{COMPLEX}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is a @code{INTEGER(8)} variable.
-
-@item @emph{See also}:
-@ref{INT}, @gol
-@ref{INT2}
-@end table
-
-
-
-@node IOR
-@section @code{IOR} --- Bitwise logical or
-@fnindex IOR
-@fnindex BIOR
-@fnindex IIOR
-@fnindex JIOR
-@fnindex KIOR
-@cindex bitwise logical or
-@cindex logical or, bitwise
-
-@table @asis
-@item @emph{Description}:
-@code{IOR} returns the bitwise Boolean inclusive-OR of @var{I} and
-@var{J}.
-
-@item @emph{Standard}:
-Fortran 90 and later, with boz-literal-constant Fortran 2008 and later, has overloads that are GNU extensions
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = IOR(I, J)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{I} @tab The type shall be @code{INTEGER} or a boz-literal-constant.
-@item @var{J} @tab The type shall be @code{INTEGER} with the same
-kind type parameter as @var{I} or a boz-literal-constant.
-@var{I} and @var{J} shall not both be boz-literal-constants.
-@end multitable
-
-@item @emph{Return value}:
-The return type is @code{INTEGER} with the kind type parameter of the
-arguments.
-A boz-literal-constant is converted to an @code{INTEGER} with the kind
-type parameter of the other argument as-if a call to @ref{INT} occurred.
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .23 .20 .33
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{IOR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later
-@item @code{BIOR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
-@item @code{IIOR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
-@item @code{JIOR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
-@item @code{KIOR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
-@end multitable
-
-@item @emph{See also}:
-@ref{IEOR}, @gol
-@ref{IAND}, @gol
-@ref{IBITS}, @gol
-@ref{IBSET}, @gol
-@ref{IBCLR}, @gol
-@ref{NOT}
-@end table
-
-
-
-@node IPARITY
-@section @code{IPARITY} --- Bitwise XOR of array elements
-@fnindex IPARITY
-@cindex array, parity
-@cindex array, XOR
-@cindex bits, XOR of array elements
-
-@table @asis
-@item @emph{Description}:
-Reduces with bitwise XOR (exclusive or) the elements of @var{ARRAY} along
-dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
-
-@item @emph{Standard}:
-Fortran 2008 and later
-
-@item @emph{Class}:
-Transformational function
-
-@item @emph{Syntax}:
-@multitable @columnfractions .80
-@item @code{RESULT = IPARITY(ARRAY[, MASK])}
-@item @code{RESULT = IPARITY(ARRAY, DIM[, MASK])}
-@end multitable
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
-@item @var{DIM} @tab (Optional) shall be a scalar of type
-@code{INTEGER} with a value in the range from 1 to n, where n
-equals the rank of @var{ARRAY}.
-@item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
-and either be a scalar or an array of the same shape as @var{ARRAY}.
-@end multitable
-
-@item @emph{Return value}:
-The result is of the same type as @var{ARRAY}.
-
-If @var{DIM} is absent, a scalar with the bitwise XOR of all elements in
-@var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
-the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
-dimension @var{DIM} dropped is returned.
-
-@item @emph{Example}:
-@smallexample
-PROGRAM test_iparity
- INTEGER(1) :: a(2)
-
- a(1) = int(b'00100100', 1)
- a(2) = int(b'01101010', 1)
-
- ! prints 01001110
- PRINT '(b8.8)', IPARITY(a)
-END PROGRAM
-@end smallexample
-
-@item @emph{See also}:
-@ref{IANY}, @gol
-@ref{IALL}, @gol
-@ref{IEOR}, @gol
-@ref{PARITY}
-@end table
-
-
-
-@node IRAND
-@section @code{IRAND} --- Integer pseudo-random number
-@fnindex IRAND
-@cindex random number generation
-
-@table @asis
-@item @emph{Description}:
-@code{IRAND(FLAG)} returns a pseudo-random number from a uniform
-distribution between 0 and a system-dependent limit (which is in most
-cases 2147483647). If @var{FLAG} is 0, the next number
-in the current sequence is returned; if @var{FLAG} is 1, the generator
-is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
-it is used as a new seed with @code{SRAND}.
-
-This intrinsic routine is provided for backwards compatibility with
-GNU Fortran 77. It implements a simple modulo generator as provided
-by @command{g77}. For new code, one should consider the use of
-@ref{RANDOM_NUMBER} as it implements a superior algorithm.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Function
-
-@item @emph{Syntax}:
-@code{RESULT = IRAND(I)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of @code{INTEGER(kind=4)} type.
-
-@item @emph{Example}:
-@smallexample
-program test_irand
- integer,parameter :: seed = 86456
-
- call srand(seed)
- print *, irand(), irand(), irand(), irand()
- print *, irand(seed), irand(), irand(), irand()
-end program test_irand
-@end smallexample
-
-@end table
-
-
-
-@node IS_CONTIGUOUS
-@section @code{IS_CONTIGUOUS} --- Test whether an array is contiguous
-@fnindex IS_IOSTAT_EOR
-@cindex array, contiguity
-
-@table @asis
-@item @emph{Description}:
-@code{IS_CONTIGUOUS} tests whether an array is contiguous.
-
-@item @emph{Standard}:
-Fortran 2008 and later
-
-@item @emph{Class}:
-Inquiry function
-
-@item @emph{Syntax}:
-@code{RESULT = IS_CONTIGUOUS(ARRAY)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{ARRAY} @tab Shall be an array of any type.
-@end multitable
-
-@item @emph{Return value}:
-Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
-@var{ARRAY} is contiguous and false otherwise.
-
-@item @emph{Example}:
-@smallexample
-program test
- integer :: a(10)
- a = [1,2,3,4,5,6,7,8,9,10]
- call sub (a) ! every element, is contiguous
- call sub (a(::2)) ! every other element, is noncontiguous
-contains
- subroutine sub (x)
- integer :: x(:)
- if (is_contiguous (x)) then
- write (*,*) 'X is contiguous'
- else
- write (*,*) 'X is not contiguous'
- end if
- end subroutine sub
-end program test
-@end smallexample
-@end table
-
-
-
-@node IS_IOSTAT_END
-@section @code{IS_IOSTAT_END} --- Test for end-of-file value
-@fnindex IS_IOSTAT_END
-@cindex @code{IOSTAT}, end of file
-
-@table @asis
-@item @emph{Description}:
-@code{IS_IOSTAT_END} tests whether an variable has the value of the I/O
-status ``end of file''. The function is equivalent to comparing the variable
-with the @code{IOSTAT_END} parameter of the intrinsic module
-@code{ISO_FORTRAN_ENV}.
-
-@item @emph{Standard}:
-Fortran 2003 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = IS_IOSTAT_END(I)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{I} @tab Shall be of the type @code{INTEGER}.
-@end multitable
-
-@item @emph{Return value}:
-Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
-@var{I} has the value which indicates an end of file condition for
-@code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
-
-@item @emph{Example}:
-@smallexample
-PROGRAM iostat
- IMPLICIT NONE
- INTEGER :: stat, i
- OPEN(88, FILE='test.dat')
- READ(88, *, IOSTAT=stat) i
- IF(IS_IOSTAT_END(stat)) STOP 'END OF FILE'
-END PROGRAM
-@end smallexample
-@end table
-
-
-
-@node IS_IOSTAT_EOR
-@section @code{IS_IOSTAT_EOR} --- Test for end-of-record value
-@fnindex IS_IOSTAT_EOR
-@cindex @code{IOSTAT}, end of record
-
-@table @asis
-@item @emph{Description}:
-@code{IS_IOSTAT_EOR} tests whether an variable has the value of the I/O
-status ``end of record''. The function is equivalent to comparing the
-variable with the @code{IOSTAT_EOR} parameter of the intrinsic module
-@code{ISO_FORTRAN_ENV}.
-
-@item @emph{Standard}:
-Fortran 2003 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = IS_IOSTAT_EOR(I)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{I} @tab Shall be of the type @code{INTEGER}.
-@end multitable
-
-@item @emph{Return value}:
-Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
-@var{I} has the value which indicates an end of file condition for
-@code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
-
-@item @emph{Example}:
-@smallexample
-PROGRAM iostat
- IMPLICIT NONE
- INTEGER :: stat, i(50)
- OPEN(88, FILE='test.dat', FORM='UNFORMATTED')
- READ(88, IOSTAT=stat) i
- IF(IS_IOSTAT_EOR(stat)) STOP 'END OF RECORD'
-END PROGRAM
-@end smallexample
-@end table
-
-
-@node ISATTY
-@section @code{ISATTY} --- Whether a unit is a terminal device
-@fnindex ISATTY
-@cindex system, terminal
-
-@table @asis
-@item @emph{Description}:
-Determine whether a unit is connected to a terminal device.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Function
-
-@item @emph{Syntax}:
-@code{RESULT = ISATTY(UNIT)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
-@end multitable
-
-@item @emph{Return value}:
-Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal
-device, @code{.FALSE.} otherwise.
-
-@item @emph{Example}:
-@smallexample
-PROGRAM test_isatty
- INTEGER(kind=1) :: unit
- DO unit = 1, 10
- write(*,*) isatty(unit=unit)
- END DO
-END PROGRAM
-@end smallexample
-@item @emph{See also}:
-@ref{TTYNAM}
-@end table
-
-
-
-@node ISHFT
-@section @code{ISHFT} --- Shift bits
-@fnindex ISHFT
-@fnindex BSHFT
-@fnindex IISHFT
-@fnindex JISHFT
-@fnindex KISHFT
-@cindex bits, shift
-
-@table @asis
-@item @emph{Description}:
-@code{ISHFT} returns a value corresponding to @var{I} with all of the
-bits shifted @var{SHIFT} places. A value of @var{SHIFT} greater than
-zero corresponds to a left shift, a value of zero corresponds to no
-shift, and a value less than zero corresponds to a right shift. If the
-absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the
-value is undefined. Bits shifted out from the left end or right end are
-lost; zeros are shifted in from the opposite end.
-
-@item @emph{Standard}:
-Fortran 90 and later, has overloads that are GNU extensions
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = ISHFT(I, SHIFT)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{I} @tab The type shall be @code{INTEGER}.
-@item @var{SHIFT} @tab The type shall be @code{INTEGER}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{INTEGER} and of the same kind as
-@var{I}.
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .23 .20 .33
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{ISHFT(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later
-@item @code{BSHFT(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
-@item @code{IISHFT(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
-@item @code{JISHFT(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
-@item @code{KISHFT(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
-@end multitable
-
-@item @emph{See also}:
-@ref{ISHFTC}
-@end table
-
-
-
-@node ISHFTC
-@section @code{ISHFTC} --- Shift bits circularly
-@fnindex ISHFTC
-@fnindex BSHFTC
-@fnindex IISHFTC
-@fnindex JISHFTC
-@fnindex KISHFTC
-@cindex bits, shift circular
-
-@table @asis
-@item @emph{Description}:
-@code{ISHFTC} returns a value corresponding to @var{I} with the
-rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that
-is, bits shifted out one end are shifted into the opposite end. A value
-of @var{SHIFT} greater than zero corresponds to a left shift, a value of
-zero corresponds to no shift, and a value less than zero corresponds to
-a right shift. The absolute value of @var{SHIFT} must be less than
-@var{SIZE}. If the @var{SIZE} argument is omitted, it is taken to be
-equivalent to @code{BIT_SIZE(I)}.
-
-@item @emph{Standard}:
-Fortran 90 and later, has overloads that are GNU extensions
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = ISHFTC(I, SHIFT [, SIZE])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{I} @tab The type shall be @code{INTEGER}.
-@item @var{SHIFT} @tab The type shall be @code{INTEGER}.
-@item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER};
-the value must be greater than zero and less than or equal to
-@code{BIT_SIZE(I)}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{INTEGER} and of the same kind as
-@var{I}.
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .23 .20 .33
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{ISHFTC(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later
-@item @code{BSHFTC(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
-@item @code{IISHFTC(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
-@item @code{JISHFTC(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
-@item @code{KISHFTC(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
-@end multitable
-
-@item @emph{See also}:
-@ref{ISHFT}
-@end table
-
-
-
-@node ISNAN
-@section @code{ISNAN} --- Test for a NaN
-@fnindex ISNAN
-@cindex IEEE, ISNAN
-
-@table @asis
-@item @emph{Description}:
-@code{ISNAN} tests whether a floating-point value is an IEEE
-Not-a-Number (NaN).
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{ISNAN(X)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab Variable of the type @code{REAL}.
-
-@end multitable
-
-@item @emph{Return value}:
-Returns a default-kind @code{LOGICAL}. The returned value is @code{TRUE}
-if @var{X} is a NaN and @code{FALSE} otherwise.
-
-@item @emph{Example}:
-@smallexample
-program test_nan
- implicit none
- real :: x
- x = -1.0
- x = sqrt(x)
- if (isnan(x)) stop '"x" is a NaN'
-end program test_nan
-@end smallexample
-@end table
-
-
-
-@node ITIME
-@section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds)
-@fnindex ITIME
-@cindex time, current
-@cindex current time
-
-@table @asis
-@item @emph{Description}:
-@code{ITIME(VALUES)} Fills @var{VALUES} with the numerical values at the
-current local time. The hour (in the range 1-24), minute (in the range 1-60),
-and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{VALUES},
-respectively.
-
-This intrinsic routine is provided for backwards compatibility with
-GNU Fortran 77. In new code, programmers should consider the use of
-the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95
-standard.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Subroutine
-
-@item @emph{Syntax}:
-@code{CALL ITIME(VALUES)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)}
-and the kind shall be the default integer kind.
-@end multitable
-
-@item @emph{Return value}:
-Does not return anything.
-
-
-@item @emph{Example}:
-@smallexample
-program test_itime
- integer, dimension(3) :: tarray
- call itime(tarray)
- print *, tarray(1)
- print *, tarray(2)
- print *, tarray(3)
-end program test_itime
-@end smallexample
-
-@item @emph{See also}:
-@ref{DATE_AND_TIME}
-@end table
-
-
-
-@node KILL
-@section @code{KILL} --- Send a signal to a process
-@fnindex KILL
-
-@table @asis
-@item @emph{Description}:
-Sends the signal specified by @var{SIG} to the process @var{PID}.
-See @code{kill(2)}.
-
-This intrinsic is provided in both subroutine and function forms;
-however, only one form can be used in any given program unit.
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Subroutine, function
-
-@item @emph{Syntax}:
-@multitable @columnfractions .80
-@item @code{CALL KILL(PID, SIG [, STATUS])}
-@item @code{STATUS = KILL(PID, SIG)}
-@end multitable
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{PID} @tab Shall be a scalar @code{INTEGER} with @code{INTENT(IN)}.
-@item @var{SIG} @tab Shall be a scalar @code{INTEGER} with @code{INTENT(IN)}.
-@item @var{STATUS} @tab [Subroutine](Optional)
-Shall be a scalar @code{INTEGER}.
-Returns 0 on success; otherwise a system-specific error code is returned.
-@item @var{STATUS} @tab [Function] The kind type parameter is that of
-@code{pid}.
-Returns 0 on success; otherwise a system-specific error code is returned.
-@end multitable
-
-@item @emph{See also}:
-@ref{ABORT}, @gol
-@ref{EXIT}
-@end table
-
-
-@node KIND
-@section @code{KIND} --- Kind of an entity
-@fnindex KIND
-@cindex kind
-
-@table @asis
-@item @emph{Description}:
-@code{KIND(X)} returns the kind value of the entity @var{X}.
-
-@item @emph{Standard}:
-Fortran 95 and later
-
-@item @emph{Class}:
-Inquiry function
-
-@item @emph{Syntax}:
-@code{K = KIND(X)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER},
-@code{REAL}, @code{COMPLEX} or @code{CHARACTER}. It may be scalar or
-array valued.
-@end multitable
-
-@item @emph{Return value}:
-The return value is a scalar of type @code{INTEGER} and of the default
-integer kind.
-
-@item @emph{Example}:
-@smallexample
-program test_kind
- integer,parameter :: kc = kind(' ')
- integer,parameter :: kl = kind(.true.)
-
- print *, "The default character kind is ", kc
- print *, "The default logical kind is ", kl
-end program test_kind
-@end smallexample
-
-@end table
-
-
-
-@node LBOUND
-@section @code{LBOUND} --- Lower dimension bounds of an array
-@fnindex LBOUND
-@cindex array, lower bound
-
-@table @asis
-@item @emph{Description}:
-Returns the lower bounds of an array, or a single lower bound
-along the @var{DIM} dimension.
-@item @emph{Standard}:
-Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later
-
-@item @emph{Class}:
-Inquiry function
-
-@item @emph{Syntax}:
-@code{RESULT = LBOUND(ARRAY [, DIM [, KIND]])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{ARRAY} @tab Shall be an array, of any type.
-@item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
-@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
-expression indicating the kind parameter of the result.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{INTEGER} and of kind @var{KIND}. If
-@var{KIND} is absent, the return value is of default integer kind.
-If @var{DIM} is absent, the result is an array of the lower bounds of
-@var{ARRAY}. If @var{DIM} is present, the result is a scalar
-corresponding to the lower bound of the array along that dimension. If
-@var{ARRAY} is an expression rather than a whole array or array
-structure component, or if it has a zero extent along the relevant
-dimension, the lower bound is taken to be 1.
-
-@item @emph{See also}:
-@ref{UBOUND}, @gol
-@ref{LCOBOUND}
-@end table
-
-
-
-@node LCOBOUND
-@section @code{LCOBOUND} --- Lower codimension bounds of an array
-@fnindex LCOBOUND
-@cindex coarray, lower bound
-
-@table @asis
-@item @emph{Description}:
-Returns the lower bounds of a coarray, or a single lower cobound
-along the @var{DIM} codimension.
-@item @emph{Standard}:
-Fortran 2008 and later
-
-@item @emph{Class}:
-Inquiry function
-
-@item @emph{Syntax}:
-@code{RESULT = LCOBOUND(COARRAY [, DIM [, KIND]])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{ARRAY} @tab Shall be an coarray, of any type.
-@item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
-@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
-expression indicating the kind parameter of the result.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{INTEGER} and of kind @var{KIND}. If
-@var{KIND} is absent, the return value is of default integer kind.
-If @var{DIM} is absent, the result is an array of the lower cobounds of
-@var{COARRAY}. If @var{DIM} is present, the result is a scalar
-corresponding to the lower cobound of the array along that codimension.
-
-@item @emph{See also}:
-@ref{UCOBOUND}, @gol
-@ref{LBOUND}
-@end table
-
-
-
-@node LEADZ
-@section @code{LEADZ} --- Number of leading zero bits of an integer
-@fnindex LEADZ
-@cindex zero bits
-
-@table @asis
-@item @emph{Description}:
-@code{LEADZ} returns the number of leading zero bits of an integer.
-
-@item @emph{Standard}:
-Fortran 2008 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = LEADZ(I)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{I} @tab Shall be of type @code{INTEGER}.
-@end multitable
-
-@item @emph{Return value}:
-The type of the return value is the default @code{INTEGER}.
-If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
-
-@item @emph{Example}:
-@smallexample
-PROGRAM test_leadz
- WRITE (*,*) BIT_SIZE(1) ! prints 32
- WRITE (*,*) LEADZ(1) ! prints 31
-END PROGRAM
-@end smallexample
-
-@item @emph{See also}:
-@ref{BIT_SIZE}, @gol
-@ref{TRAILZ}, @gol
-@ref{POPCNT}, @gol
-@ref{POPPAR}
-@end table
-
-
-
-@node LEN
-@section @code{LEN} --- Length of a character entity
-@fnindex LEN
-@cindex string, length
-
-@table @asis
-@item @emph{Description}:
-Returns the length of a character string. If @var{STRING} is an array,
-the length of an element of @var{STRING} is returned. Note that
-@var{STRING} need not be defined when this intrinsic is invoked, since
-only the length, not the content, of @var{STRING} is needed.
-
-@item @emph{Standard}:
-Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
-
-@item @emph{Class}:
-Inquiry function
-
-@item @emph{Syntax}:
-@code{L = LEN(STRING [, KIND])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{STRING} @tab Shall be a scalar or array of type
-@code{CHARACTER}, with @code{INTENT(IN)}
-@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
-expression indicating the kind parameter of the result.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{INTEGER} and of kind @var{KIND}. If
-@var{KIND} is absent, the return value is of default integer kind.
-
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .23 .20 .33
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{LEN(STRING)} @tab @code{CHARACTER} @tab @code{INTEGER} @tab Fortran 77 and later
-@end multitable
-
-
-@item @emph{See also}:
-@ref{LEN_TRIM}, @gol
-@ref{ADJUSTL}, @gol
-@ref{ADJUSTR}
-@end table
-
-
-
-@node LEN_TRIM
-@section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters
-@fnindex LEN_TRIM
-@cindex string, length, without trailing whitespace
-
-@table @asis
-@item @emph{Description}:
-Returns the length of a character string, ignoring any trailing blanks.
-
-@item @emph{Standard}:
-Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = LEN_TRIM(STRING [, KIND])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
-with @code{INTENT(IN)}
-@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
-expression indicating the kind parameter of the result.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{INTEGER} and of kind @var{KIND}. If
-@var{KIND} is absent, the return value is of default integer kind.
-
-@item @emph{See also}:
-@ref{LEN}, @gol
-@ref{ADJUSTL}, @gol
-@ref{ADJUSTR}
-@end table
-
-
-
-@node LGE
-@section @code{LGE} --- Lexical greater than or equal
-@fnindex LGE
-@cindex lexical comparison of strings
-@cindex string, comparison
-
-@table @asis
-@item @emph{Description}:
-Determines whether one string is lexically greater than or equal to
-another string, where the two strings are interpreted as containing
-ASCII character codes. If the String A and String B are not the same
-length, the shorter is compared as if spaces were appended to it to form
-a value that has the same length as the longer.
-
-In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
-@code{LLE}, and @code{LLT} differ from the corresponding intrinsic
-operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
-that the latter use the processor's character ordering (which is not
-ASCII on some targets), whereas the former always use the ASCII
-ordering.
-
-@item @emph{Standard}:
-Fortran 77 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = LGE(STRING_A, STRING_B)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
-@item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
-@end multitable
-
-@item @emph{Return value}:
-Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.}
-otherwise, based on the ASCII ordering.
-
-@item @emph{Specific names}:
-@multitable @columnfractions .34 .16 .17 .30
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{LGE(STRING_A,STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
-@end multitable
-
-@item @emph{See also}:
-@ref{LGT}, @gol
-@ref{LLE}, @gol
-@ref{LLT}
-@end table
-
-
-
-@node LGT
-@section @code{LGT} --- Lexical greater than
-@fnindex LGT
-@cindex lexical comparison of strings
-@cindex string, comparison
-
-@table @asis
-@item @emph{Description}:
-Determines whether one string is lexically greater than another string,
-where the two strings are interpreted as containing ASCII character
-codes. If the String A and String B are not the same length, the
-shorter is compared as if spaces were appended to it to form a value
-that has the same length as the longer.
-
-In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
-@code{LLE}, and @code{LLT} differ from the corresponding intrinsic
-operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
-that the latter use the processor's character ordering (which is not
-ASCII on some targets), whereas the former always use the ASCII
-ordering.
-
-@item @emph{Standard}:
-Fortran 77 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = LGT(STRING_A, STRING_B)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
-@item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
-@end multitable
-
-@item @emph{Return value}:
-Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.}
-otherwise, based on the ASCII ordering.
-
-@item @emph{Specific names}:
-@multitable @columnfractions .34 .16 .17 .30
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{LGT(STRING_A,STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
-@end multitable
-
-@item @emph{See also}:
-@ref{LGE}, @gol
-@ref{LLE}, @gol
-@ref{LLT}
-@end table
-
-
-
-@node LINK
-@section @code{LINK} --- Create a hard link
-@fnindex LINK
-@cindex file system, create link
-@cindex file system, hard link
-
-@table @asis
-@item @emph{Description}:
-Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null
-character (@code{CHAR(0)}) can be used to mark the end of the names in
-@var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
-names are ignored. If the @var{STATUS} argument is supplied, it
-contains 0 on success or a nonzero error code upon return; see
-@code{link(2)}.
-
-This intrinsic is provided in both subroutine and function forms;
-however, only one form can be used in any given program unit.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Subroutine, function
-
-@item @emph{Syntax}:
-@multitable @columnfractions .80
-@item @code{CALL LINK(PATH1, PATH2 [, STATUS])}
-@item @code{STATUS = LINK(PATH1, PATH2)}
-@end multitable
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
-@item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
-@item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
-@end multitable
-
-@item @emph{See also}:
-@ref{SYMLNK}, @gol
-@ref{UNLINK}
-@end table
-
-
-
-@node LLE
-@section @code{LLE} --- Lexical less than or equal
-@fnindex LLE
-@cindex lexical comparison of strings
-@cindex string, comparison
-
-@table @asis
-@item @emph{Description}:
-Determines whether one string is lexically less than or equal to another
-string, where the two strings are interpreted as containing ASCII
-character codes. If the String A and String B are not the same length,
-the shorter is compared as if spaces were appended to it to form a value
-that has the same length as the longer.
-
-In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
-@code{LLE}, and @code{LLT} differ from the corresponding intrinsic
-operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
-that the latter use the processor's character ordering (which is not
-ASCII on some targets), whereas the former always use the ASCII
-ordering.
-
-@item @emph{Standard}:
-Fortran 77 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = LLE(STRING_A, STRING_B)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
-@item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
-@end multitable
-
-@item @emph{Return value}:
-Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.}
-otherwise, based on the ASCII ordering.
-
-@item @emph{Specific names}:
-@multitable @columnfractions .34 .16 .17 .30
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{LLE(STRING_A,STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
-@end multitable
-
-@item @emph{See also}:
-@ref{LGE}, @gol
-@ref{LGT}, @gol
-@ref{LLT}
-@end table
-
-
-
-@node LLT
-@section @code{LLT} --- Lexical less than
-@fnindex LLT
-@cindex lexical comparison of strings
-@cindex string, comparison
-
-@table @asis
-@item @emph{Description}:
-Determines whether one string is lexically less than another string,
-where the two strings are interpreted as containing ASCII character
-codes. If the String A and String B are not the same length, the
-shorter is compared as if spaces were appended to it to form a value
-that has the same length as the longer.
-
-In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
-@code{LLE}, and @code{LLT} differ from the corresponding intrinsic
-operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
-that the latter use the processor's character ordering (which is not
-ASCII on some targets), whereas the former always use the ASCII
-ordering.
-
-@item @emph{Standard}:
-Fortran 77 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = LLT(STRING_A, STRING_B)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
-@item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
-@end multitable
-
-@item @emph{Return value}:
-Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.}
-otherwise, based on the ASCII ordering.
-
-@item @emph{Specific names}:
-@multitable @columnfractions .34 .16 .17 .30
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{LLT(STRING_A,STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
-@end multitable
-
-@item @emph{See also}:
-@ref{LGE}, @gol
-@ref{LGT}, @gol
-@ref{LLE}
-@end table
-
-
-
-@node LNBLNK
-@section @code{LNBLNK} --- Index of the last non-blank character in a string
-@fnindex LNBLNK
-@cindex string, find non-blank character
-
-@table @asis
-@item @emph{Description}:
-Returns the length of a character string, ignoring any trailing blanks.
-This is identical to the standard @code{LEN_TRIM} intrinsic, and is only
-included for backwards compatibility.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = LNBLNK(STRING)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
-with @code{INTENT(IN)}
-@end multitable
-
-@item @emph{Return value}:
-The return value is of @code{INTEGER(kind=4)} type.
-
-@item @emph{See also}:
-@ref{INDEX intrinsic}, @gol
-@ref{LEN_TRIM}
-@end table
-
-
-
-@node LOC
-@section @code{LOC} --- Returns the address of a variable
-@fnindex LOC
-@cindex location of a variable in memory
-
-@table @asis
-@item @emph{Description}:
-@code{LOC(X)} returns the address of @var{X} as an integer.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Inquiry function
-
-@item @emph{Syntax}:
-@code{RESULT = LOC(X)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab Variable of any type.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{INTEGER}, with a @code{KIND}
-corresponding to the size (in bytes) of a memory address on the target
-machine.
-
-@item @emph{Example}:
-@smallexample
-program test_loc
- integer :: i
- real :: r
- i = loc(r)
- print *, i
-end program test_loc
-@end smallexample
-@end table
-
-
-
-@node LOG
-@section @code{LOG} --- Natural logarithm function
-@fnindex LOG
-@fnindex ALOG
-@fnindex DLOG
-@fnindex CLOG
-@fnindex ZLOG
-@fnindex CDLOG
-@cindex exponential function, inverse
-@cindex logarithm function
-@cindex natural logarithm function
-
-@table @asis
-@item @emph{Description}:
-@code{LOG(X)} computes the natural logarithm of @var{X}, i.e. the
-logarithm to the base @math{e}.
-
-@item @emph{Standard}:
-Fortran 77 and later, has GNU extensions
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = LOG(X)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab The type shall be @code{REAL} or
-@code{COMPLEX}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{REAL} or @code{COMPLEX}.
-The kind type parameter is the same as @var{X}.
-If @var{X} is @code{COMPLEX}, the imaginary part @math{\omega} is in the range
-@math{-\pi < \omega \leq \pi}.
-
-@item @emph{Example}:
-@smallexample
-program test_log
- real(8) :: x = 2.7182818284590451_8
- complex :: z = (1.0, 2.0)
- x = log(x) ! will yield (approximately) 1
- z = log(z)
-end program test_log
-@end smallexample
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .23 .20 .33
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{ALOG(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 or later
-@item @code{DLOG(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 or later
-@item @code{CLOG(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 or later
-@item @code{ZLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
-@item @code{CDLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
-@end multitable
-@end table
-
-
-
-@node LOG10
-@section @code{LOG10} --- Base 10 logarithm function
-@fnindex LOG10
-@fnindex ALOG10
-@fnindex DLOG10
-@cindex exponential function, inverse
-@cindex logarithm function with base 10
-@cindex base 10 logarithm function
-
-@table @asis
-@item @emph{Description}:
-@code{LOG10(X)} computes the base 10 logarithm of @var{X}.
-
-@item @emph{Standard}:
-Fortran 77 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = LOG10(X)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab The type shall be @code{REAL}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{REAL} or @code{COMPLEX}.
-The kind type parameter is the same as @var{X}.
-
-@item @emph{Example}:
-@smallexample
-program test_log10
- real(8) :: x = 10.0_8
- x = log10(x)
-end program test_log10
-@end smallexample
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .23 .20 .33
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{ALOG10(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
-@item @code{DLOG10(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
-@end multitable
-@end table
-
-
-
-@node LOG_GAMMA
-@section @code{LOG_GAMMA} --- Logarithm of the Gamma function
-@fnindex LOG_GAMMA
-@fnindex LGAMMA
-@fnindex ALGAMA
-@fnindex DLGAMA
-@cindex Gamma function, logarithm of
-
-@table @asis
-@item @emph{Description}:
-@code{LOG_GAMMA(X)} computes the natural logarithm of the absolute value
-of the Gamma (@math{\Gamma}) function.
-
-@item @emph{Standard}:
-Fortran 2008 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{X = LOG_GAMMA(X)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab Shall be of type @code{REAL} and neither zero
-nor a negative integer.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{REAL} of the same kind as @var{X}.
-
-@item @emph{Example}:
-@smallexample
-program test_log_gamma
- real :: x = 1.0
- x = lgamma(x) ! returns 0.0
-end program test_log_gamma
-@end smallexample
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .23 .20 .33
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{LGAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension
-@item @code{ALGAMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension
-@item @code{DLGAMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
-@end multitable
-
-@item @emph{See also}:
-Gamma function: @gol
-@ref{GAMMA}
-@end table
-
-
-
-@node LOGICAL
-@section @code{LOGICAL} --- Convert to logical type
-@fnindex LOGICAL
-@cindex conversion, to logical
-
-@table @asis
-@item @emph{Description}:
-Converts one kind of @code{LOGICAL} variable to another.
-
-@item @emph{Standard}:
-Fortran 90 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = LOGICAL(L [, KIND])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{L} @tab The type shall be @code{LOGICAL}.
-@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
-expression indicating the kind parameter of the result.
-@end multitable
-
-@item @emph{Return value}:
-The return value is a @code{LOGICAL} value equal to @var{L}, with a
-kind corresponding to @var{KIND}, or of the default logical kind if
-@var{KIND} is not given.
-
-@item @emph{See also}:
-@ref{INT}, @gol
-@ref{REAL}, @gol
-@ref{CMPLX}
-@end table
-
-
-
-@node LSHIFT
-@section @code{LSHIFT} --- Left shift bits
-@fnindex LSHIFT
-@cindex bits, shift left
-
-@table @asis
-@item @emph{Description}:
-@code{LSHIFT} returns a value corresponding to @var{I} with all of the
-bits shifted left by @var{SHIFT} places. @var{SHIFT} shall be
-nonnegative and less than or equal to @code{BIT_SIZE(I)}, otherwise
-the result value is undefined. Bits shifted out from the left end are
-lost; zeros are shifted in from the opposite end.
-
-This function has been superseded by the @code{ISHFT} intrinsic, which
-is standard in Fortran 95 and later, and the @code{SHIFTL} intrinsic,
-which is standard in Fortran 2008 and later.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = LSHIFT(I, SHIFT)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{I} @tab The type shall be @code{INTEGER}.
-@item @var{SHIFT} @tab The type shall be @code{INTEGER}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{INTEGER} and of the same kind as
-@var{I}.
-
-@item @emph{See also}:
-@ref{ISHFT}, @gol
-@ref{ISHFTC}, @gol
-@ref{RSHIFT}, @gol
-@ref{SHIFTA}, @gol
-@ref{SHIFTL}, @gol
-@ref{SHIFTR}
-@end table
-
-
-
-@node LSTAT
-@section @code{LSTAT} --- Get file status
-@fnindex LSTAT
-@cindex file system, file status
-
-@table @asis
-@item @emph{Description}:
-@code{LSTAT} is identical to @ref{STAT}, except that if path is a
-symbolic link, then the link itself is statted, not the file that it
-refers to.
-
-The elements in @code{VALUES} are the same as described by @ref{STAT}.
-
-This intrinsic is provided in both subroutine and function forms;
-however, only one form can be used in any given program unit.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Subroutine, function
-
-@item @emph{Syntax}:
-@multitable @columnfractions .80
-@item @code{CALL LSTAT(NAME, VALUES [, STATUS])}
-@item @code{STATUS = LSTAT(NAME, VALUES)}
-@end multitable
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{NAME} @tab The type shall be @code{CHARACTER} of the default
-kind, a valid path within the file system.
-@item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
-@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}.
-Returns 0 on success and a system specific error code otherwise.
-@end multitable
-
-@item @emph{Example}:
-See @ref{STAT} for an example.
-
-@item @emph{See also}:
-To stat an open file: @gol
-@ref{FSTAT} @gol
-To stat a file: @gol
-@ref{STAT}
-@end table
-
-
-
-@node LTIME
-@section @code{LTIME} --- Convert time to local time info
-@fnindex LTIME
-@cindex time, conversion to local time info
-
-@table @asis
-@item @emph{Description}:
-Given a system time value @var{TIME} (as provided by the @ref{TIME}
-intrinsic), fills @var{VALUES} with values extracted from it appropriate
-to the local time zone using @code{localtime(3)}.
-
-This intrinsic routine is provided for backwards compatibility with
-GNU Fortran 77. In new code, programmers should consider the use of
-the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95
-standard.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Subroutine
-
-@item @emph{Syntax}:
-@code{CALL LTIME(TIME, VALUES)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{TIME} @tab An @code{INTEGER} scalar expression
-corresponding to a system time, with @code{INTENT(IN)}.
-@item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
-with @code{INTENT(OUT)}.
-@end multitable
-
-@item @emph{Return value}:
-The elements of @var{VALUES} are assigned as follows:
-@enumerate
-@item Seconds after the minute, range 0--59 or 0--61 to allow for leap
-seconds
-@item Minutes after the hour, range 0--59
-@item Hours past midnight, range 0--23
-@item Day of month, range 1--31
-@item Number of months since January, range 0--11
-@item Years since 1900
-@item Number of days since Sunday, range 0--6
-@item Days since January 1, range 0--365
-@item Daylight savings indicator: positive if daylight savings is in
-effect, zero if not, and negative if the information is not available.
-@end enumerate
-
-@item @emph{See also}:
-@ref{DATE_AND_TIME}, @gol
-@ref{CTIME}, @gol
-@ref{GMTIME}, @gol
-@ref{TIME}, @gol
-@ref{TIME8}
-@end table
-
-
-
-@node MALLOC
-@section @code{MALLOC} --- Allocate dynamic memory
-@fnindex MALLOC
-@cindex pointer, cray
-
-@table @asis
-@item @emph{Description}:
-@code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and
-returns the address of the allocated memory. The @code{MALLOC} intrinsic
-is an extension intended to be used with Cray pointers, and is provided
-in GNU Fortran to allow the user to compile legacy code. For new code
-using Fortran 95 pointers, the memory allocation intrinsic is
-@code{ALLOCATE}.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Function
-
-@item @emph{Syntax}:
-@code{PTR = MALLOC(SIZE)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{SIZE} @tab The type shall be @code{INTEGER}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{INTEGER(K)}, with @var{K} such that
-variables of type @code{INTEGER(K)} have the same size as
-C pointers (@code{sizeof(void *)}).
-
-@item @emph{Example}:
-The following example demonstrates the use of @code{MALLOC} and
-@code{FREE} with Cray pointers.
-
-@smallexample
-program test_malloc
- implicit none
- integer i
- real*8 x(*), z
- pointer(ptr_x,x)
-
- ptr_x = malloc(20*8)
- do i = 1, 20
- x(i) = sqrt(1.0d0 / i)
- end do
- z = 0
- do i = 1, 20
- z = z + x(i)
- print *, z
- end do
- call free(ptr_x)
-end program test_malloc
-@end smallexample
-
-@item @emph{See also}:
-@ref{FREE}
-@end table
-
-
-
-@node MASKL
-@section @code{MASKL} --- Left justified mask
-@fnindex MASKL
-@cindex mask, left justified
-
-@table @asis
-@item @emph{Description}:
-@code{MASKL(I[, KIND])} has its leftmost @var{I} bits set to 1, and the
-remaining bits set to 0.
-
-@item @emph{Standard}:
-Fortran 2008 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = MASKL(I[, KIND])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{I} @tab Shall be of type @code{INTEGER}.
-@item @var{KIND} @tab Shall be a scalar constant expression of type
-@code{INTEGER}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{INTEGER}. If @var{KIND} is present, it
-specifies the kind value of the return type; otherwise, it is of the
-default integer kind.
-
-@item @emph{See also}:
-@ref{MASKR}
-@end table
-
-
-
-@node MASKR
-@section @code{MASKR} --- Right justified mask
-@fnindex MASKR
-@cindex mask, right justified
-
-@table @asis
-@item @emph{Description}:
-@code{MASKL(I[, KIND])} has its rightmost @var{I} bits set to 1, and the
-remaining bits set to 0.
-
-@item @emph{Standard}:
-Fortran 2008 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = MASKR(I[, KIND])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{I} @tab Shall be of type @code{INTEGER}.
-@item @var{KIND} @tab Shall be a scalar constant expression of type
-@code{INTEGER}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{INTEGER}. If @var{KIND} is present, it
-specifies the kind value of the return type; otherwise, it is of the
-default integer kind.
-
-@item @emph{See also}:
-@ref{MASKL}
-@end table
-
-
-
-@node MATMUL
-@section @code{MATMUL} --- matrix multiplication
-@fnindex MATMUL
-@cindex matrix multiplication
-@cindex product, matrix
-
-@table @asis
-@item @emph{Description}:
-Performs a matrix multiplication on numeric or logical arguments.
-
-@item @emph{Standard}:
-Fortran 90 and later
-
-@item @emph{Class}:
-Transformational function
-
-@item @emph{Syntax}:
-@code{RESULT = MATMUL(MATRIX_A, MATRIX_B)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{MATRIX_A} @tab An array of @code{INTEGER},
-@code{REAL}, @code{COMPLEX}, or @code{LOGICAL} type, with a rank of
-one or two.
-@item @var{MATRIX_B} @tab An array of @code{INTEGER},
-@code{REAL}, or @code{COMPLEX} type if @var{MATRIX_A} is of a numeric
-type; otherwise, an array of @code{LOGICAL} type. The rank shall be one
-or two, and the first (or only) dimension of @var{MATRIX_B} shall be
-equal to the last (or only) dimension of @var{MATRIX_A}.
-@var{MATRIX_A} and @var{MATRIX_B} shall not both be rank one arrays.
-@end multitable
-
-@item @emph{Return value}:
-The matrix product of @var{MATRIX_A} and @var{MATRIX_B}. The type and
-kind of the result follow the usual type and kind promotion rules, as
-for the @code{*} or @code{.AND.} operators.
-@end table
-
-
-
-@node MAX
-@section @code{MAX} --- Maximum value of an argument list
-@fnindex MAX
-@fnindex MAX0
-@fnindex AMAX0
-@fnindex MAX1
-@fnindex AMAX1
-@fnindex DMAX1
-@cindex maximum value
-
-@table @asis
-@item @emph{Description}:
-Returns the argument with the largest (most positive) value.
-
-@item @emph{Standard}:
-Fortran 77 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = MAX(A1, A2 [, A3 [, ...]])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{A1} @tab The type shall be @code{INTEGER} or
-@code{REAL}.
-@item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
-as @var{A1}. (As a GNU extension, arguments of different kinds are
-permitted.)
-@end multitable
-
-@item @emph{Return value}:
-The return value corresponds to the maximum value among the arguments,
-and has the same type and kind as the first argument.
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .23 .20 .33
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{MAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
-@item @code{AMAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(MAX(X))} @tab Fortran 77 and later
-@item @code{MAX1(A1)} @tab @code{REAL A1} @tab @code{INT(MAX(X))} @tab Fortran 77 and later
-@item @code{AMAX1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
-@item @code{DMAX1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
-@end multitable
-
-@item @emph{See also}:
-@ref{MAXLOC} @gol
-@ref{MAXVAL}, @gol
-@ref{MIN}
-@end table
-
-
-
-@node MAXEXPONENT
-@section @code{MAXEXPONENT} --- Maximum exponent of a real kind
-@fnindex MAXEXPONENT
-@cindex model representation, maximum exponent
-
-@table @asis
-@item @emph{Description}:
-@code{MAXEXPONENT(X)} returns the maximum exponent in the model of the
-type of @code{X}.
-
-@item @emph{Standard}:
-Fortran 90 and later
-
-@item @emph{Class}:
-Inquiry function
-
-@item @emph{Syntax}:
-@code{RESULT = MAXEXPONENT(X)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab Shall be of type @code{REAL}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{INTEGER} and of the default integer
-kind.
-
-@item @emph{Example}:
-@smallexample
-program exponents
- real(kind=4) :: x
- real(kind=8) :: y
-
- print *, minexponent(x), maxexponent(x)
- print *, minexponent(y), maxexponent(y)
-end program exponents
-@end smallexample
-@end table
-
-
-
-@node MAXLOC
-@section @code{MAXLOC} --- Location of the maximum value within an array
-@fnindex MAXLOC
-@cindex array, location of maximum element
-
-@table @asis
-@item @emph{Description}:
-Determines the location of the element in the array with the maximum
-value, or, if the @var{DIM} argument is supplied, determines the
-locations of the maximum element along each row of the array in the
-@var{DIM} direction. If @var{MASK} is present, only the elements for
-which @var{MASK} is @code{.TRUE.} are considered. If more than one
-element in the array has the maximum value, the location returned is
-that of the first such element in array element order if the
-@var{BACK} is not present, or is false; if @var{BACK} is true, the location
-returned is that of the last such element. If the array has zero
-size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
-the result is an array of zeroes. Similarly, if @var{DIM} is supplied
-and all of the elements of @var{MASK} along a given row are zero, the
-result value for that row is zero.
-
-@item @emph{Standard}:
-Fortran 95 and later; @var{ARRAY} of @code{CHARACTER} and the
-@var{KIND} argument are available in Fortran 2003 and later.
-The @var{BACK} argument is available in Fortran 2008 and later.
-
-@item @emph{Class}:
-Transformational function
-
-@item @emph{Syntax}:
-@multitable @columnfractions .80
-@item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK] [,KIND] [,BACK])}
-@item @code{RESULT = MAXLOC(ARRAY [, MASK] [,KIND] [,BACK])}
-@end multitable
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
-@code{REAL}.
-@item @var{DIM} @tab (Optional) Shall be a scalar of type
-@code{INTEGER}, with a value between one and the rank of @var{ARRAY},
-inclusive. It may not be an optional dummy argument.
-@item @var{MASK} @tab Shall be of type @code{LOGICAL},
-and conformable with @var{ARRAY}.
-@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
-expression indicating the kind parameter of the result.
-@item @var{BACK} @tab (Optional) A scalar of type @code{LOGICAL}.
-@end multitable
-
-@item @emph{Return value}:
-If @var{DIM} is absent, the result is a rank-one array with a length
-equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
-is an array with a rank one less than the rank of @var{ARRAY}, and a
-size corresponding to the size of @var{ARRAY} with the @var{DIM}
-dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
-of one, the result is a scalar. If the optional argument @var{KIND}
-is present, the result is an integer of kind @var{KIND}, otherwise it
-is of default kind.
-
-@item @emph{See also}:
-@ref{FINDLOC}, @gol
-@ref{MAX}, @gol
-@ref{MAXVAL}
-@end table
-
-
-
-@node MAXVAL
-@section @code{MAXVAL} --- Maximum value of an array
-@fnindex MAXVAL
-@cindex array, maximum value
-@cindex maximum value
-
-@table @asis
-@item @emph{Description}:
-Determines the maximum value of the elements in an array value, or, if
-the @var{DIM} argument is supplied, determines the maximum value along
-each row of the array in the @var{DIM} direction. If @var{MASK} is
-present, only the elements for which @var{MASK} is @code{.TRUE.} are
-considered. If the array has zero size, or all of the elements of
-@var{MASK} are @code{.FALSE.}, then the result is @code{-HUGE(ARRAY)}
-if @var{ARRAY} is numeric, or a string of nulls if @var{ARRAY} is of character
-type.
-
-@item @emph{Standard}:
-Fortran 90 and later
-
-@item @emph{Class}:
-Transformational function
-
-@item @emph{Syntax}:
-@multitable @columnfractions .80
-@item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])}
-@item @code{RESULT = MAXVAL(ARRAY [, MASK])}
-@end multitable
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
-@code{REAL}.
-@item @var{DIM} @tab (Optional) Shall be a scalar of type
-@code{INTEGER}, with a value between one and the rank of @var{ARRAY},
-inclusive. It may not be an optional dummy argument.
-@item @var{MASK} @tab (Optional) Shall be of type @code{LOGICAL},
-and conformable with @var{ARRAY}.
-@end multitable
-
-@item @emph{Return value}:
-If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
-is a scalar. If @var{DIM} is present, the result is an array with a
-rank one less than the rank of @var{ARRAY}, and a size corresponding to
-the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
-cases, the result is of the same type and kind as @var{ARRAY}.
-
-@item @emph{See also}:
-@ref{MAX}, @gol
-@ref{MAXLOC}
-@end table
-
-
-
-@node MCLOCK
-@section @code{MCLOCK} --- Time function
-@fnindex MCLOCK
-@cindex time, clock ticks
-@cindex clock ticks
-
-@table @asis
-@item @emph{Description}:
-Returns the number of clock ticks since the start of the process, based
-on the function @code{clock(3)} in the C standard library.
-
-This intrinsic is not fully portable, such as to systems with 32-bit
-@code{INTEGER} types but supporting times wider than 32 bits. Therefore,
-the values returned by this intrinsic might be, or become, negative, or
-numerically less than previous values, during a single run of the
-compiled program.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Function
-
-@item @emph{Syntax}:
-@code{RESULT = MCLOCK()}
-
-@item @emph{Return value}:
-The return value is a scalar of type @code{INTEGER(4)}, equal to the
-number of clock ticks since the start of the process, or @code{-1} if
-the system does not support @code{clock(3)}.
-
-@item @emph{See also}:
-@ref{CTIME}, @gol
-@ref{GMTIME}, @gol
-@ref{LTIME}, @gol
-@ref{MCLOCK}, @gol
-@ref{TIME}
-@end table
-
-
-
-@node MCLOCK8
-@section @code{MCLOCK8} --- Time function (64-bit)
-@fnindex MCLOCK8
-@cindex time, clock ticks
-@cindex clock ticks
-
-@table @asis
-@item @emph{Description}:
-Returns the number of clock ticks since the start of the process, based
-on the function @code{clock(3)} in the C standard library.
-
-@emph{Warning:} this intrinsic does not increase the range of the timing
-values over that returned by @code{clock(3)}. On a system with a 32-bit
-@code{clock(3)}, @code{MCLOCK8} will return a 32-bit value, even though
-it is converted to a 64-bit @code{INTEGER(8)} value. That means
-overflows of the 32-bit value can still occur. Therefore, the values
-returned by this intrinsic might be or become negative or numerically
-less than previous values during a single run of the compiled program.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Function
-
-@item @emph{Syntax}:
-@code{RESULT = MCLOCK8()}
-
-@item @emph{Return value}:
-The return value is a scalar of type @code{INTEGER(8)}, equal to the
-number of clock ticks since the start of the process, or @code{-1} if
-the system does not support @code{clock(3)}.
-
-@item @emph{See also}:
-@ref{CTIME}, @gol
-@ref{GMTIME}, @gol
-@ref{LTIME}, @gol
-@ref{MCLOCK}, @gol
-@ref{TIME8}
-@end table
-
-
-
-@node MERGE
-@section @code{MERGE} --- Merge variables
-@fnindex MERGE
-@cindex array, merge arrays
-@cindex array, combine arrays
-
-@table @asis
-@item @emph{Description}:
-Select values from two arrays according to a logical mask. The result
-is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to
-@var{FSOURCE} if it is @code{.FALSE.}.
-
-@item @emph{Standard}:
-Fortran 90 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{TSOURCE} @tab May be of any type.
-@item @var{FSOURCE} @tab Shall be of the same type and type parameters
-as @var{TSOURCE}.
-@item @var{MASK} @tab Shall be of type @code{LOGICAL}.
-@end multitable
-
-@item @emph{Return value}:
-The result is of the same type and type parameters as @var{TSOURCE}.
-
-@end table
-
-
-
-@node MERGE_BITS
-@section @code{MERGE_BITS} --- Merge of bits under mask
-@fnindex MERGE_BITS
-@cindex bits, merge
-
-@table @asis
-@item @emph{Description}:
-@code{MERGE_BITS(I, J, MASK)} merges the bits of @var{I} and @var{J}
-as determined by the mask. The i-th bit of the result is equal to the
-i-th bit of @var{I} if the i-th bit of @var{MASK} is 1; it is equal to
-the i-th bit of @var{J} otherwise.
-
-@item @emph{Standard}:
-Fortran 2008 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = MERGE_BITS(I, J, MASK)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{I} @tab Shall be of type @code{INTEGER} or a boz-literal-constant.
-@item @var{J} @tab Shall be of type @code{INTEGER} with the same
-kind type parameter as @var{I} or a boz-literal-constant.
-@var{I} and @var{J} shall not both be boz-literal-constants.
-@item @var{MASK} @tab Shall be of type @code{INTEGER} or a boz-literal-constant
-and of the same kind as @var{I}.
-@end multitable
-
-@item @emph{Return value}:
-The result is of the same type and kind as @var{I}.
-
-@end table
-
-
-
-@node MIN
-@section @code{MIN} --- Minimum value of an argument list
-@fnindex MIN
-@fnindex MIN0
-@fnindex AMIN0
-@fnindex MIN1
-@fnindex AMIN1
-@fnindex DMIN1
-@cindex minimum value
-
-@table @asis
-@item @emph{Description}:
-Returns the argument with the smallest (most negative) value.
-
-@item @emph{Standard}:
-Fortran 77 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = MIN(A1, A2 [, A3, ...])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{A1} @tab The type shall be @code{INTEGER} or
-@code{REAL}.
-@item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
-as @var{A1}. (As a GNU extension, arguments of different kinds are
-permitted.)
-@end multitable
-
-@item @emph{Return value}:
-The return value corresponds to the minimum value among the arguments,
-and has the same type and kind as the first argument.
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .23 .20 .33
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{MIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
-@item @code{AMIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
-@item @code{MIN1(A1)} @tab @code{REAL A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
-@item @code{AMIN1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
-@item @code{DMIN1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
-@end multitable
-
-@item @emph{See also}:
-@ref{MAX}, @gol
-@ref{MINLOC}, @gol
-@ref{MINVAL}
-@end table
-
-
-
-@node MINEXPONENT
-@section @code{MINEXPONENT} --- Minimum exponent of a real kind
-@fnindex MINEXPONENT
-@cindex model representation, minimum exponent
-
-@table @asis
-@item @emph{Description}:
-@code{MINEXPONENT(X)} returns the minimum exponent in the model of the
-type of @code{X}.
-
-@item @emph{Standard}:
-Fortran 90 and later
-
-@item @emph{Class}:
-Inquiry function
-
-@item @emph{Syntax}:
-@code{RESULT = MINEXPONENT(X)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab Shall be of type @code{REAL}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{INTEGER} and of the default integer
-kind.
-
-@item @emph{Example}:
-See @code{MAXEXPONENT} for an example.
-@end table
-
-
-
-@node MINLOC
-@section @code{MINLOC} --- Location of the minimum value within an array
-@fnindex MINLOC
-@cindex array, location of minimum element
-
-@table @asis
-@item @emph{Description}:
-Determines the location of the element in the array with the minimum
-value, or, if the @var{DIM} argument is supplied, determines the
-locations of the minimum element along each row of the array in the
-@var{DIM} direction. If @var{MASK} is present, only the elements for
-which @var{MASK} is @code{.TRUE.} are considered. If more than one
-element in the array has the minimum value, the location returned is
-that of the first such element in array element order if the
-@var{BACK} is not present, or is false; if @var{BACK} is true, the location
-returned is that of the last such element. If the array has
-zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
-the result is an array of zeroes. Similarly, if @var{DIM} is supplied
-and all of the elements of @var{MASK} along a given row are zero, the
-result value for that row is zero.
-
-@item @emph{Standard}:
-Fortran 90 and later; @var{ARRAY} of @code{CHARACTER} and the
-@var{KIND} argument are available in Fortran 2003 and later.
-The @var{BACK} argument is available in Fortran 2008 and later.
-
-@item @emph{Class}:
-Transformational function
-
-@item @emph{Syntax}:
-@multitable @columnfractions .80
-@item @code{RESULT = MINLOC(ARRAY, DIM [, MASK] [,KIND] [,BACK])}
-@item @code{RESULT = MINLOC(ARRAY [, MASK], [,KIND] [,BACK])}
-@end multitable
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
-@code{REAL} or @code{CHARACTER}.
-@item @var{DIM} @tab (Optional) Shall be a scalar of type
-@code{INTEGER}, with a value between one and the rank of @var{ARRAY},
-inclusive. It may not be an optional dummy argument.
-@item @var{MASK} @tab Shall be of type @code{LOGICAL},
-and conformable with @var{ARRAY}.
-@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
-expression indicating the kind parameter of the result.
-@item @var{BACK} @tab (Optional) A scalar of type @code{LOGICAL}.
-@end multitable
-
-@item @emph{Return value}:
-If @var{DIM} is absent, the result is a rank-one array with a length
-equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
-is an array with a rank one less than the rank of @var{ARRAY}, and a
-size corresponding to the size of @var{ARRAY} with the @var{DIM}
-dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
-of one, the result is a scalar. If the optional argument @var{KIND}
-is present, the result is an integer of kind @var{KIND}, otherwise it
-is of default kind.
-
-@item @emph{See also}:
-@ref{FINDLOC}, @gol
-@ref{MIN}, @gol
-@ref{MINVAL}
-@end table
-
-
-
-@node MINVAL
-@section @code{MINVAL} --- Minimum value of an array
-@fnindex MINVAL
-@cindex array, minimum value
-@cindex minimum value
-
-@table @asis
-@item @emph{Description}:
-Determines the minimum value of the elements in an array value, or, if
-the @var{DIM} argument is supplied, determines the minimum value along
-each row of the array in the @var{DIM} direction. If @var{MASK} is
-present, only the elements for which @var{MASK} is @code{.TRUE.} are
-considered. If the array has zero size, or all of the elements of
-@var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if
-@var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if
-@var{ARRAY} is of character type.
-
-@item @emph{Standard}:
-Fortran 90 and later
-
-@item @emph{Class}:
-Transformational function
-
-@item @emph{Syntax}:
-@multitable @columnfractions .80
-@item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])}
-@item @code{RESULT = MINVAL(ARRAY [, MASK])}
-@end multitable
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
-@code{REAL}.
-@item @var{DIM} @tab (Optional) Shall be a scalar of type
-@code{INTEGER}, with a value between one and the rank of @var{ARRAY},
-inclusive. It may not be an optional dummy argument.
-@item @var{MASK} @tab Shall be of type @code{LOGICAL},
-and conformable with @var{ARRAY}.
-@end multitable
-
-@item @emph{Return value}:
-If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
-is a scalar. If @var{DIM} is present, the result is an array with a
-rank one less than the rank of @var{ARRAY}, and a size corresponding to
-the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
-cases, the result is of the same type and kind as @var{ARRAY}.
-
-@item @emph{See also}:
-@ref{MIN}, @gol
-@ref{MINLOC}
-@end table
-
-
-
-@node MOD
-@section @code{MOD} --- Remainder function
-@fnindex MOD
-@fnindex AMOD
-@fnindex DMOD
-@fnindex BMOD
-@fnindex IMOD
-@fnindex JMOD
-@fnindex KMOD
-@cindex remainder
-@cindex division, remainder
-
-@table @asis
-@item @emph{Description}:
-@code{MOD(A,P)} computes the remainder of the division of A by P@.
-
-@item @emph{Standard}:
-Fortran 77 and later, has overloads that are GNU extensions
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = MOD(A, P)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}.
-@item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}
-and not equal to zero. (As a GNU extension, arguments of different kinds are
-permitted.)
-@end multitable
-
-@item @emph{Return value}:
-The return value is the result of @code{A - (INT(A/P) * P)}. The type
-and kind of the return value is the same as that of the arguments. The
-returned value has the same sign as A and a magnitude less than the
-magnitude of P. (As a GNU extension, kind is the largest kind of the actual
-arguments.)
-
-@item @emph{Example}:
-@smallexample
-program test_mod
- print *, mod(17,3)
- print *, mod(17.5,5.5)
- print *, mod(17.5d0,5.5)
- print *, mod(17.5,5.5d0)
-
- print *, mod(-17,3)
- print *, mod(-17.5,5.5)
- print *, mod(-17.5d0,5.5)
- print *, mod(-17.5,5.5d0)
-
- print *, mod(17,-3)
- print *, mod(17.5,-5.5)
- print *, mod(17.5d0,-5.5)
- print *, mod(17.5,-5.5d0)
-end program test_mod
-@end smallexample
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .25 .20 .31
-@headitem Name @tab Arguments @tab Return type @tab Standard
-@item @code{MOD(A,P)} @tab @code{INTEGER A,P} @tab @code{INTEGER} @tab Fortran 77 and later
-@item @code{AMOD(A,P)} @tab @code{REAL(4) A,P} @tab @code{REAL(4)} @tab Fortran 77 and later
-@item @code{DMOD(A,P)} @tab @code{REAL(8) A,P} @tab @code{REAL(8)} @tab Fortran 77 and later
-@item @code{BMOD(A,P)} @tab @code{INTEGER(1) A,P} @tab @code{INTEGER(1)} @tab GNU extension
-@item @code{IMOD(A,P)} @tab @code{INTEGER(2) A,P} @tab @code{INTEGER(2)} @tab GNU extension
-@item @code{JMOD(A,P)} @tab @code{INTEGER(4) A,P} @tab @code{INTEGER(4)} @tab GNU extension
-@item @code{KMOD(A,P)} @tab @code{INTEGER(8) A,P} @tab @code{INTEGER(8)} @tab GNU extension
-@end multitable
-
-@item @emph{See also}:
-@ref{MODULO}
-
-@end table
-
-
-
-@node MODULO
-@section @code{MODULO} --- Modulo function
-@fnindex MODULO
-@cindex modulo
-@cindex division, modulo
-
-@table @asis
-@item @emph{Description}:
-@code{MODULO(A,P)} computes the @var{A} modulo @var{P}.
-
-@item @emph{Standard}:
-Fortran 95 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = MODULO(A, P)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}.
-@item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}.
-It shall not be zero. (As a GNU extension, arguments of different kinds are
-permitted.)
-@end multitable
-
-@item @emph{Return value}:
-The type and kind of the result are those of the arguments. (As a GNU
-extension, kind is the largest kind of the actual arguments.)
-@table @asis
-@item If @var{A} and @var{P} are of type @code{INTEGER}:
-@code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where
-@var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P}
-(exclusive).
-@item If @var{A} and @var{P} are of type @code{REAL}:
-@code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}.
-@end table
-The returned value has the same sign as P and a magnitude less than
-the magnitude of P.
-
-@item @emph{Example}:
-@smallexample
-program test_modulo
- print *, modulo(17,3)
- print *, modulo(17.5,5.5)
-
- print *, modulo(-17,3)
- print *, modulo(-17.5,5.5)
-
- print *, modulo(17,-3)
- print *, modulo(17.5,-5.5)
-end program
-@end smallexample
-
-@item @emph{See also}:
-@ref{MOD}
-
-@end table
-
-
-
-@node MOVE_ALLOC
-@section @code{MOVE_ALLOC} --- Move allocation from one object to another
-@fnindex MOVE_ALLOC
-@cindex moving allocation
-@cindex allocation, moving
-
-@table @asis
-@item @emph{Description}:
-@code{MOVE_ALLOC(FROM, TO)} moves the allocation from @var{FROM} to
-@var{TO}. @var{FROM} will become deallocated in the process.
-
-@item @emph{Standard}:
-Fortran 2003 and later
-
-@item @emph{Class}:
-Pure subroutine
-
-@item @emph{Syntax}:
-@code{CALL MOVE_ALLOC(FROM, TO)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{FROM} @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be
-of any type and kind.
-@item @var{TO} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be
-of the same type, kind and rank as @var{FROM}.
-@end multitable
-
-@item @emph{Return value}:
-None
-
-@item @emph{Example}:
-@smallexample
-program test_move_alloc
- integer, allocatable :: a(:), b(:)
-
- allocate(a(3))
- a = [ 1, 2, 3 ]
- call move_alloc(a, b)
- print *, allocated(a), allocated(b)
- print *, b
-end program test_move_alloc
-@end smallexample
-@end table
-
-
-
-@node MVBITS
-@section @code{MVBITS} --- Move bits from one integer to another
-@fnindex MVBITS
-@fnindex BMVBITS
-@fnindex IMVBITS
-@fnindex JMVBITS
-@fnindex KMVBITS
-@cindex bits, move
-
-@table @asis
-@item @emph{Description}:
-Moves @var{LEN} bits from positions @var{FROMPOS} through
-@code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through
-@code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not
-affected by the movement of bits is unchanged. The values of
-@code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than
-@code{BIT_SIZE(FROM)}.
-
-@item @emph{Standard}:
-Fortran 90 and later, has overloads that are GNU extensions
-
-@item @emph{Class}:
-Elemental subroutine
-
-@item @emph{Syntax}:
-@code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{FROM} @tab The type shall be @code{INTEGER}.
-@item @var{FROMPOS} @tab The type shall be @code{INTEGER}.
-@item @var{LEN} @tab The type shall be @code{INTEGER}.
-@item @var{TO} @tab The type shall be @code{INTEGER}, of the
-same kind as @var{FROM}.
-@item @var{TOPOS} @tab The type shall be @code{INTEGER}.
-@end multitable
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .23 .20 .33
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{MVBITS(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later
-@item @code{BMVBITS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
-@item @code{IMVBITS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
-@item @code{JMVBITS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
-@item @code{KMVBITS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
-@end multitable
-
-@item @emph{See also}:
-@ref{IBCLR}, @gol
-@ref{IBSET}, @gol
-@ref{IBITS}, @gol
-@ref{IAND}, @gol
-@ref{IOR}, @gol
-@ref{IEOR}
-@end table
-
-
-
-@node NEAREST
-@section @code{NEAREST} --- Nearest representable number
-@fnindex NEAREST
-@cindex real number, nearest different
-@cindex floating point, nearest different
-
-@table @asis
-@item @emph{Description}:
-@code{NEAREST(X, S)} returns the processor-representable number nearest
-to @code{X} in the direction indicated by the sign of @code{S}.
-
-@item @emph{Standard}:
-Fortran 90 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = NEAREST(X, S)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab Shall be of type @code{REAL}.
-@item @var{S} @tab Shall be of type @code{REAL} and
-not equal to zero.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of the same type as @code{X}. If @code{S} is
-positive, @code{NEAREST} returns the processor-representable number
-greater than @code{X} and nearest to it. If @code{S} is negative,
-@code{NEAREST} returns the processor-representable number smaller than
-@code{X} and nearest to it.
-
-@item @emph{Example}:
-@smallexample
-program test_nearest
- real :: x, y
- x = nearest(42.0, 1.0)
- y = nearest(42.0, -1.0)
- write (*,"(3(G20.15))") x, y, x - y
-end program test_nearest
-@end smallexample
-@end table
-
-
-
-@node NEW_LINE
-@section @code{NEW_LINE} --- New line character
-@fnindex NEW_LINE
-@cindex newline
-@cindex output, newline
-
-@table @asis
-@item @emph{Description}:
-@code{NEW_LINE(C)} returns the new-line character.
-
-@item @emph{Standard}:
-Fortran 2003 and later
-
-@item @emph{Class}:
-Inquiry function
-
-@item @emph{Syntax}:
-@code{RESULT = NEW_LINE(C)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{C} @tab The argument shall be a scalar or array of the
-type @code{CHARACTER}.
-@end multitable
-
-@item @emph{Return value}:
-Returns a @var{CHARACTER} scalar of length one with the new-line character of
-the same kind as parameter @var{C}.
-
-@item @emph{Example}:
-@smallexample
-program newline
- implicit none
- write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.'
-end program newline
-@end smallexample
-@end table
-
-
-
-@node NINT
-@section @code{NINT} --- Nearest whole number
-@fnindex NINT
-@fnindex IDNINT
-@cindex rounding, nearest whole number
-
-@table @asis
-@item @emph{Description}:
-@code{NINT(A)} rounds its argument to the nearest whole number.
-
-@item @emph{Standard}:
-Fortran 77 and later, with @var{KIND} argument Fortran 90 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = NINT(A [, KIND])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{A} @tab The type of the argument shall be @code{REAL}.
-@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
-expression indicating the kind parameter of the result.
-@end multitable
-
-@item @emph{Return value}:
-Returns @var{A} with the fractional portion of its magnitude eliminated by
-rounding to the nearest whole number and with its sign preserved,
-converted to an @code{INTEGER} of the default kind.
-
-@item @emph{Example}:
-@smallexample
-program test_nint
- real(4) x4
- real(8) x8
- x4 = 1.234E0_4
- x8 = 4.321_8
- print *, nint(x4), idnint(x8)
-end program test_nint
-@end smallexample
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .23 .20 .33
-@headitem Name @tab Argument @tab Return Type @tab Standard
-@item @code{NINT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
-@item @code{IDNINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 77 and later
-@end multitable
-
-@item @emph{See also}:
-@ref{CEILING}, @gol
-@ref{FLOOR}
-@end table
-
-
-
-@node NORM2
-@section @code{NORM2} --- Euclidean vector norms
-@fnindex NORM2
-@cindex Euclidean vector norm
-@cindex L2 vector norm
-@cindex norm, Euclidean
-
-@table @asis
-@item @emph{Description}:
-Calculates the Euclidean vector norm (@math{L_2} norm)
-of @var{ARRAY} along dimension @var{DIM}.
-
-@item @emph{Standard}:
-Fortran 2008 and later
-
-@item @emph{Class}:
-Transformational function
-
-@item @emph{Syntax}:
-@multitable @columnfractions .80
-@item @code{RESULT = NORM2(ARRAY[, DIM])}
-@end multitable
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{ARRAY} @tab Shall be an array of type @code{REAL}
-@item @var{DIM} @tab (Optional) shall be a scalar of type
-@code{INTEGER} with a value in the range from 1 to n, where n
-equals the rank of @var{ARRAY}.
-@end multitable
-
-@item @emph{Return value}:
-The result is of the same type as @var{ARRAY}.
-
-If @var{DIM} is absent, a scalar with the square root of the sum of all
-elements in @var{ARRAY} squared is returned. Otherwise, an array of
-rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY}, and a
-shape similar to that of @var{ARRAY} with dimension @var{DIM} dropped
-is returned.
-
-@item @emph{Example}:
-@smallexample
-PROGRAM test_sum
- REAL :: x(5) = [ real :: 1, 2, 3, 4, 5 ]
- print *, NORM2(x) ! = sqrt(55.) ~ 7.416
-END PROGRAM
-@end smallexample
-@end table
-
-
-
-@node NOT
-@section @code{NOT} --- Logical negation
-@fnindex NOT
-@fnindex BNOT
-@fnindex INOT
-@fnindex JNOT
-@fnindex KNOT
-@cindex bits, negate
-@cindex bitwise logical not
-@cindex logical not, bitwise
-
-@table @asis
-@item @emph{Description}:
-@code{NOT} returns the bitwise Boolean inverse of @var{I}.
-
-@item @emph{Standard}:
-Fortran 90 and later, has overloads that are GNU extensions
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = NOT(I)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{I} @tab The type shall be @code{INTEGER}.
-@end multitable
-
-@item @emph{Return value}:
-The return type is @code{INTEGER}, of the same kind as the
-argument.
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .23 .20 .33
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{NOT(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
-@item @code{BNOT(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
-@item @code{INOT(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
-@item @code{JNOT(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
-@item @code{KNOT(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
-@end multitable
-
-@item @emph{See also}:
-@ref{IAND}, @gol
-@ref{IEOR}, @gol
-@ref{IOR}, @gol
-@ref{IBITS}, @gol
-@ref{IBSET}, @gol
-@ref{IBCLR}
-@end table
-
-
-
-@node NULL
-@section @code{NULL} --- Function that returns an disassociated pointer
-@fnindex NULL
-@cindex pointer, status
-@cindex pointer, disassociated
-
-@table @asis
-@item @emph{Description}:
-Returns a disassociated pointer.
-
-If @var{MOLD} is present, a disassociated pointer of the same type is
-returned, otherwise the type is determined by context.
-
-In Fortran 95, @var{MOLD} is optional. Please note that Fortran 2003
-includes cases where it is required.
-
-@item @emph{Standard}:
-Fortran 95 and later
-
-@item @emph{Class}:
-Transformational function
-
-@item @emph{Syntax}:
-@code{PTR => NULL([MOLD])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{MOLD} @tab (Optional) shall be a pointer of any association
-status and of any type.
-@end multitable
-
-@item @emph{Return value}:
-A disassociated pointer.
-
-@item @emph{Example}:
-@smallexample
-REAL, POINTER, DIMENSION(:) :: VEC => NULL ()
-@end smallexample
-
-@item @emph{See also}:
-@ref{ASSOCIATED}
-@end table
-
-
-
-@node NUM_IMAGES
-@section @code{NUM_IMAGES} --- Function that returns the number of images
-@fnindex NUM_IMAGES
-@cindex coarray, @code{NUM_IMAGES}
-@cindex images, number of
-
-@table @asis
-@item @emph{Description}:
-Returns the number of images.
-
-@item @emph{Standard}:
-Fortran 2008 and later. With @var{DISTANCE} or @var{FAILED} argument,
-Technical Specification (TS) 18508 or later
-
-
-@item @emph{Class}:
-Transformational function
-
-@item @emph{Syntax}:
-@code{RESULT = NUM_IMAGES(DISTANCE, FAILED)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{DISTANCE} @tab (optional, intent(in)) Nonnegative scalar integer
-@item @var{FAILED} @tab (optional, intent(in)) Scalar logical expression
-@end multitable
-
-@item @emph{Return value}:
-Scalar default-kind integer. If @var{DISTANCE} is not present or has value 0,
-the number of images in the current team is returned. For values smaller or
-equal distance to the initial team, it returns the number of images index
-on the ancestor team which has a distance of @var{DISTANCE} from the invoking
-team. If @var{DISTANCE} is larger than the distance to the initial team, the
-number of images of the initial team is returned. If @var{FAILED} is not present
-the total number of images is returned; if it has the value @code{.TRUE.},
-the number of failed images is returned, otherwise, the number of images which
-do have not the failed status.
-
-@item @emph{Example}:
-@smallexample
-INTEGER :: value[*]
-INTEGER :: i
-value = THIS_IMAGE()
-SYNC ALL
-IF (THIS_IMAGE() == 1) THEN
- DO i = 1, NUM_IMAGES()
- WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
- END DO
-END IF
-@end smallexample
-
-@item @emph{See also}:
-@ref{THIS_IMAGE}, @gol
-@ref{IMAGE_INDEX}
-@end table
-
-
-
-@node OR
-@section @code{OR} --- Bitwise logical OR
-@fnindex OR
-@cindex bitwise logical or
-@cindex logical or, bitwise
-
-@table @asis
-@item @emph{Description}:
-Bitwise logical @code{OR}.
-
-This intrinsic routine is provided for backwards compatibility with
-GNU Fortran 77. For integer arguments, programmers should consider
-the use of the @ref{IOR} intrinsic defined by the Fortran standard.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Function
-
-@item @emph{Syntax}:
-@code{RESULT = OR(I, J)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{I} @tab The type shall be either a scalar @code{INTEGER}
-type or a scalar @code{LOGICAL} type or a boz-literal-constant.
-@item @var{J} @tab The type shall be the same as the type of @var{I} or
-a boz-literal-constant. @var{I} and @var{J} shall not both be
-boz-literal-constants. If either @var{I} and @var{J} is a
-boz-literal-constant, then the other argument must be a scalar @code{INTEGER}.
-@end multitable
-
-@item @emph{Return value}:
-The return type is either a scalar @code{INTEGER} or a scalar
-@code{LOGICAL}. If the kind type parameters differ, then the
-smaller kind type is implicitly converted to larger kind, and the
-return has the larger kind. A boz-literal-constant is
-converted to an @code{INTEGER} with the kind type parameter of
-the other argument as-if a call to @ref{INT} occurred.
-
-@item @emph{Example}:
-@smallexample
-PROGRAM test_or
- LOGICAL :: T = .TRUE., F = .FALSE.
- INTEGER :: a, b
- DATA a / Z'F' /, b / Z'3' /
-
- WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F)
- WRITE (*,*) OR(a, b)
-END PROGRAM
-@end smallexample
-
-@item @emph{See also}:
-Fortran 95 elemental function: @gol
-@ref{IOR}
-@end table
-
-
-
-@node PACK
-@section @code{PACK} --- Pack an array into an array of rank one
-@fnindex PACK
-@cindex array, packing
-@cindex array, reduce dimension
-@cindex array, gather elements
-
-@table @asis
-@item @emph{Description}:
-Stores the elements of @var{ARRAY} in an array of rank one.
-
-The beginning of the resulting array is made up of elements whose @var{MASK}
-equals @code{TRUE}. Afterwards, positions are filled with elements taken from
-@var{VECTOR}.
-
-@item @emph{Standard}:
-Fortran 90 and later
-
-@item @emph{Class}:
-Transformational function
-
-@item @emph{Syntax}:
-@code{RESULT = PACK(ARRAY, MASK[,VECTOR])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{ARRAY} @tab Shall be an array of any type.
-@item @var{MASK} @tab Shall be an array of type @code{LOGICAL} and
-of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL}
-scalar.
-@item @var{VECTOR} @tab (Optional) shall be an array of the same type
-as @var{ARRAY} and of rank one. If present, the number of elements in
-@var{VECTOR} shall be equal to or greater than the number of true elements
-in @var{MASK}. If @var{MASK} is scalar, the number of elements in
-@var{VECTOR} shall be equal to or greater than the number of elements in
-@var{ARRAY}.
-@end multitable
-
-@item @emph{Return value}:
-The result is an array of rank one and the same type as that of @var{ARRAY}.
-If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the
-number of @code{TRUE} values in @var{MASK} otherwise.
-
-@item @emph{Example}:
-Gathering nonzero elements from an array:
-@smallexample
-PROGRAM test_pack_1
- INTEGER :: m(6)
- m = (/ 1, 0, 0, 0, 5, 0 /)
- WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0) ! "1 5"
-END PROGRAM
-@end smallexample
-
-Gathering nonzero elements from an array and appending elements from @var{VECTOR}:
-@smallexample
-PROGRAM test_pack_2
- INTEGER :: m(4)
- m = (/ 1, 0, 0, 2 /)
- ! The following results in "1 2 3 4"
- WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /))
-END PROGRAM
-@end smallexample
-
-@item @emph{See also}:
-@ref{UNPACK}
-@end table
-
-
-
-@node PARITY
-@section @code{PARITY} --- Reduction with exclusive OR
-@fnindex PARITY
-@cindex Parity
-@cindex Reduction, XOR
-@cindex XOR reduction
-
-@table @asis
-@item @emph{Description}:
-Calculates the parity, i.e. the reduction using @code{.XOR.},
-of @var{MASK} along dimension @var{DIM}.
-
-@item @emph{Standard}:
-Fortran 2008 and later
-
-@item @emph{Class}:
-Transformational function
-
-@item @emph{Syntax}:
-@multitable @columnfractions .80
-@item @code{RESULT = PARITY(MASK[, DIM])}
-@end multitable
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{MASK} @tab Shall be an array of type @code{LOGICAL}
-@item @var{DIM} @tab (Optional) shall be a scalar of type
-@code{INTEGER} with a value in the range from 1 to n, where n
-equals the rank of @var{MASK}.
-@end multitable
-
-@item @emph{Return value}:
-The result is of the same type as @var{MASK}.
-
-If @var{DIM} is absent, a scalar with the parity of all elements in
-@var{MASK} is returned, i.e. true if an odd number of elements is
-@code{.true.} and false otherwise. If @var{DIM} is present, an array
-of rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY},
-and a shape similar to that of @var{MASK} with dimension @var{DIM}
-dropped is returned.
-
-@item @emph{Example}:
-@smallexample
-PROGRAM test_sum
- LOGICAL :: x(2) = [ .true., .false. ]
- print *, PARITY(x) ! prints "T" (true).
-END PROGRAM
-@end smallexample
-@end table
-
-
-
-@node PERROR
-@section @code{PERROR} --- Print system error message
-@fnindex PERROR
-@cindex system, error handling
-
-@table @asis
-@item @emph{Description}:
-Prints (on the C @code{stderr} stream) a newline-terminated error
-message corresponding to the last system error. This is prefixed by
-@var{STRING}, a colon and a space. See @code{perror(3)}.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Subroutine
-
-@item @emph{Syntax}:
-@code{CALL PERROR(STRING)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{STRING} @tab A scalar of type @code{CHARACTER} and of the
-default kind.
-@end multitable
-
-@item @emph{See also}:
-@ref{IERRNO}
-@end table
-
-
-
-@node POPCNT
-@section @code{POPCNT} --- Number of bits set
-@fnindex POPCNT
-@cindex binary representation
-@cindex bits set
-
-@table @asis
-@item @emph{Description}:
-@code{POPCNT(I)} returns the number of bits set ('1' bits) in the binary
-representation of @code{I}.
-
-@item @emph{Standard}:
-Fortran 2008 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = POPCNT(I)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{I} @tab Shall be of type @code{INTEGER}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{INTEGER} and of the default integer
-kind.
-
-@item @emph{Example}:
-@smallexample
-program test_population
- print *, popcnt(127), poppar(127)
- print *, popcnt(huge(0_4)), poppar(huge(0_4))
- print *, popcnt(huge(0_8)), poppar(huge(0_8))
-end program test_population
-@end smallexample
-@item @emph{See also}:
-@ref{POPPAR}, @gol
-@ref{LEADZ}, @gol
-@ref{TRAILZ}
-@end table
-
-
-
-@node POPPAR
-@section @code{POPPAR} --- Parity of the number of bits set
-@fnindex POPPAR
-@cindex binary representation
-@cindex parity
-
-@table @asis
-@item @emph{Description}:
-@code{POPPAR(I)} returns parity of the integer @code{I}, i.e. the parity
-of the number of bits set ('1' bits) in the binary representation of
-@code{I}. It is equal to 0 if @code{I} has an even number of bits set,
-and 1 for an odd number of '1' bits.
-
-@item @emph{Standard}:
-Fortran 2008 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = POPPAR(I)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{I} @tab Shall be of type @code{INTEGER}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{INTEGER} and of the default integer
-kind.
-
-@item @emph{Example}:
-@smallexample
-program test_population
- print *, popcnt(127), poppar(127)
- print *, popcnt(huge(0_4)), poppar(huge(0_4))
- print *, popcnt(huge(0_8)), poppar(huge(0_8))
-end program test_population
-@end smallexample
-@item @emph{See also}:
-@ref{POPCNT}, @gol
-@ref{LEADZ}, @gol
-@ref{TRAILZ}
-@end table
-
-
-
-@node PRECISION
-@section @code{PRECISION} --- Decimal precision of a real kind
-@fnindex PRECISION
-@cindex model representation, precision
-
-@table @asis
-@item @emph{Description}:
-@code{PRECISION(X)} returns the decimal precision in the model of the
-type of @code{X}.
-
-@item @emph{Standard}:
-Fortran 90 and later
-
-@item @emph{Class}:
-Inquiry function
-
-@item @emph{Syntax}:
-@code{RESULT = PRECISION(X)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}. It may
-be scalar or valued.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{INTEGER} and of the default integer
-kind.
-
-@item @emph{Example}:
-@smallexample
-program prec_and_range
- real(kind=4) :: x(2)
- complex(kind=8) :: y
-
- print *, precision(x), range(x)
- print *, precision(y), range(y)
-end program prec_and_range
-@end smallexample
-@item @emph{See also}:
-@ref{SELECTED_REAL_KIND}, @gol
-@ref{RANGE}
-@end table
-
-
-
-@node PRESENT
-@section @code{PRESENT} --- Determine whether an optional dummy argument is specified
-@fnindex PRESENT
-
-@table @asis
-@item @emph{Description}:
-Determines whether an optional dummy argument is present.
-
-@item @emph{Standard}:
-Fortran 90 and later
-
-@item @emph{Class}:
-Inquiry function
-
-@item @emph{Syntax}:
-@code{RESULT = PRESENT(A)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{A} @tab May be of any type and may be a pointer, scalar or array
-value, or a dummy procedure. It shall be the name of an optional dummy argument
-accessible within the current subroutine or function.
-@end multitable
-
-@item @emph{Return value}:
-Returns either @code{TRUE} if the optional argument @var{A} is present, or
-@code{FALSE} otherwise.
-
-@item @emph{Example}:
-@smallexample
-PROGRAM test_present
- WRITE(*,*) f(), f(42) ! "F T"
-CONTAINS
- LOGICAL FUNCTION f(x)
- INTEGER, INTENT(IN), OPTIONAL :: x
- f = PRESENT(x)
- END FUNCTION
-END PROGRAM
-@end smallexample
-@end table
-
-
-
-@node PRODUCT
-@section @code{PRODUCT} --- Product of array elements
-@fnindex PRODUCT
-@cindex array, product
-@cindex array, multiply elements
-@cindex array, conditionally multiply elements
-@cindex multiply array elements
-
-@table @asis
-@item @emph{Description}:
-Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if
-the corresponding element in @var{MASK} is @code{TRUE}.
-
-@item @emph{Standard}:
-Fortran 90 and later
-
-@item @emph{Class}:
-Transformational function
-
-@item @emph{Syntax}:
-@multitable @columnfractions .80
-@item @code{RESULT = PRODUCT(ARRAY[, MASK])}
-@item @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])}
-@end multitable
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
-@code{REAL} or @code{COMPLEX}.
-@item @var{DIM} @tab (Optional) shall be a scalar of type
-@code{INTEGER} with a value in the range from 1 to n, where n
-equals the rank of @var{ARRAY}.
-@item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
-and either be a scalar or an array of the same shape as @var{ARRAY}.
-@end multitable
-
-@item @emph{Return value}:
-The result is of the same type as @var{ARRAY}.
-
-If @var{DIM} is absent, a scalar with the product of all elements in
-@var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
-the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
-dimension @var{DIM} dropped is returned.
-
-
-@item @emph{Example}:
-@smallexample
-PROGRAM test_product
- INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
- print *, PRODUCT(x) ! all elements, product = 120
- print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15
-END PROGRAM
-@end smallexample
-
-@item @emph{See also}:
-@ref{SUM}
-@end table
-
-
-
-@node RADIX
-@section @code{RADIX} --- Base of a model number
-@fnindex RADIX
-@cindex model representation, base
-@cindex model representation, radix
-
-@table @asis
-@item @emph{Description}:
-@code{RADIX(X)} returns the base of the model representing the entity @var{X}.
-
-@item @emph{Standard}:
-Fortran 90 and later
-
-@item @emph{Class}:
-Inquiry function
-
-@item @emph{Syntax}:
-@code{RESULT = RADIX(X)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL}
-@end multitable
-
-@item @emph{Return value}:
-The return value is a scalar of type @code{INTEGER} and of the default
-integer kind.
-
-@item @emph{Example}:
-@smallexample
-program test_radix
- print *, "The radix for the default integer kind is", radix(0)
- print *, "The radix for the default real kind is", radix(0.0)
-end program test_radix
-@end smallexample
-@item @emph{See also}:
-@ref{SELECTED_REAL_KIND}
-@end table
-
-
-
-@node RAN
-@section @code{RAN} --- Real pseudo-random number
-@fnindex RAN
-@cindex random number generation
-
-@table @asis
-@item @emph{Description}:
-For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is
-provided as an alias for @code{RAND}. See @ref{RAND} for complete
-documentation.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Function
-
-@item @emph{See also}:
-@ref{RAND}, @gol
-@ref{RANDOM_NUMBER}
-@end table
-
-
-
-@node RAND
-@section @code{RAND} --- Real pseudo-random number
-@fnindex RAND
-@cindex random number generation
-
-@table @asis
-@item @emph{Description}:
-@code{RAND(FLAG)} returns a pseudo-random number from a uniform
-distribution between 0 and 1. If @var{FLAG} is 0, the next number
-in the current sequence is returned; if @var{FLAG} is 1, the generator
-is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
-it is used as a new seed with @code{SRAND}.
-
-This intrinsic routine is provided for backwards compatibility with
-GNU Fortran 77. It implements a simple modulo generator as provided
-by @command{g77}. For new code, one should consider the use of
-@ref{RANDOM_NUMBER} as it implements a superior algorithm.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Function
-
-@item @emph{Syntax}:
-@code{RESULT = RAND(I)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of @code{REAL} type and the default kind.
-
-@item @emph{Example}:
-@smallexample
-program test_rand
- integer,parameter :: seed = 86456
-
- call srand(seed)
- print *, rand(), rand(), rand(), rand()
- print *, rand(seed), rand(), rand(), rand()
-end program test_rand
-@end smallexample
-
-@item @emph{See also}:
-@ref{SRAND}, @gol
-@ref{RANDOM_NUMBER}
-
-@end table
-
-
-@node RANDOM_INIT
-@section @code{RANDOM_INIT} --- Initialize a pseudo-random number generator
-@fnindex RANDOM_INIT
-@cindex random number generation, initialization
-
-@table @asis
-@item @emph{Description}:
-Initializes the state of the pseudorandom number generator used by
-@code{RANDOM_NUMBER}.
-
-@item @emph{Standard}:
-Fortran 2018
-
-@item @emph{Class}:
-Subroutine
-
-@item @emph{Syntax}:
-@code{CALL RANDOM_INIT(REPEATABLE, IMAGE_DISTINCT)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .25 .70
-@item @var{REPEATABLE} @tab Shall be a scalar with a @code{LOGICAL} type,
-and it is @code{INTENT(IN)}. If it is @code{.true.}, the seed is set to
-a processor-dependent value that is the same each time @code{RANDOM_INIT}
-is called from the same image. The term ``same image'' means a single
-instance of program execution. The sequence of random numbers is different
-for repeated execution of the program. If it is @code{.false.}, the seed
-is set to a processor-dependent value.
-@item @var{IMAGE_DISTINCT} @tab Shall be a scalar with a
-@code{LOGICAL} type, and it is @code{INTENT(IN)}. If it is @code{.true.},
-the seed is set to a processor-dependent value that is distinct from th
-seed set by a call to @code{RANDOM_INIT} in another image. If it is
-@code{.false.}, the seed is set to a value that does depend which image called
-@code{RANDOM_INIT}.
-@end multitable
-
-@item @emph{Example}:
-@smallexample
-program test_random_seed
- implicit none
- real x(3), y(3)
- call random_init(.true., .true.)
- call random_number(x)
- call random_init(.true., .true.)
- call random_number(y)
- ! x and y are the same sequence
- if (any(x /= y)) call abort
-end program test_random_seed
-@end smallexample
-
-@item @emph{See also}:
-@ref{RANDOM_NUMBER}, @gol
-@ref{RANDOM_SEED}
-@end table
-
-
-@node RANDOM_NUMBER
-@section @code{RANDOM_NUMBER} --- Pseudo-random number
-@fnindex RANDOM_NUMBER
-@cindex random number generation
-
-@table @asis
-@item @emph{Description}:
-Returns a single pseudorandom number or an array of pseudorandom numbers
-from the uniform distribution over the range @math{ 0 \leq x < 1}.
-
-The runtime-library implements the xoshiro256** pseudorandom number
-generator (PRNG). This generator has a period of @math{2^{256} - 1},
-and when using multiple threads up to @math{2^{128}} threads can each
-generate @math{2^{128}} random numbers before any aliasing occurs.
-
-Note that in a multi-threaded program (e.g. using OpenMP directives),
-each thread will have its own random number state. For details of the
-seeding procedure, see the documentation for the @code{RANDOM_SEED}
-intrinsic.
-
-
-@item @emph{Standard}:
-Fortran 90 and later
-
-@item @emph{Class}:
-Subroutine
-
-@item @emph{Syntax}:
-@code{CALL RANDOM_NUMBER(HARVEST)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL}.
-@end multitable
-
-@item @emph{Example}:
-@smallexample
-program test_random_number
- REAL :: r(5,5)
- CALL RANDOM_NUMBER(r)
-end program
-@end smallexample
-
-@item @emph{See also}:
-@ref{RANDOM_SEED}, @gol
-@ref{RANDOM_INIT}
-@end table
-
-
-
-@node RANDOM_SEED
-@section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence
-@fnindex RANDOM_SEED
-@cindex random number generation, seeding
-@cindex seeding a random number generator
-
-@table @asis
-@item @emph{Description}:
-Restarts or queries the state of the pseudorandom number generator used by
-@code{RANDOM_NUMBER}.
-
-If @code{RANDOM_SEED} is called without arguments, it is seeded with
-random data retrieved from the operating system.
-
-As an extension to the Fortran standard, the GFortran
-@code{RANDOM_NUMBER} supports multiple threads. Each thread in a
-multi-threaded program has its own seed. When @code{RANDOM_SEED} is
-called either without arguments or with the @var{PUT} argument, the
-given seed is copied into a master seed as well as the seed of the
-current thread. When a new thread uses @code{RANDOM_NUMBER} for the
-first time, the seed is copied from the master seed, and forwarded
-@math{N * 2^{128}} steps to guarantee that the random stream does not
-alias any other stream in the system, where @var{N} is the number of
-threads that have used @code{RANDOM_NUMBER} so far during the program
-execution.
-
-@item @emph{Standard}:
-Fortran 90 and later
-
-@item @emph{Class}:
-Subroutine
-
-@item @emph{Syntax}:
-@code{CALL RANDOM_SEED([SIZE, PUT, GET])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{SIZE} @tab (Optional) Shall be a scalar and of type default
-@code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size
-of the arrays used with the @var{PUT} and @var{GET} arguments.
-@item @var{PUT} @tab (Optional) Shall be an array of type default
-@code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of
-the array must be larger than or equal to the number returned by the
-@var{SIZE} argument.
-@item @var{GET} @tab (Optional) Shall be an array of type default
-@code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size
-of the array must be larger than or equal to the number returned by
-the @var{SIZE} argument.
-@end multitable
-
-@item @emph{Example}:
-@smallexample
-program test_random_seed
- implicit none
- integer, allocatable :: seed(:)
- integer :: n
-
- call random_seed(size = n)
- allocate(seed(n))
- call random_seed(get=seed)
- write (*, *) seed
-end program test_random_seed
-@end smallexample
-
-@item @emph{See also}:
-@ref{RANDOM_NUMBER}, @gol
-@ref{RANDOM_INIT}
-@end table
-
-
-
-@node RANGE
-@section @code{RANGE} --- Decimal exponent range
-@fnindex RANGE
-@cindex model representation, range
-
-@table @asis
-@item @emph{Description}:
-@code{RANGE(X)} returns the decimal exponent range in the model of the
-type of @code{X}.
-
-@item @emph{Standard}:
-Fortran 90 and later
-
-@item @emph{Class}:
-Inquiry function
-
-@item @emph{Syntax}:
-@code{RESULT = RANGE(X)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab Shall be of type @code{INTEGER}, @code{REAL}
-or @code{COMPLEX}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{INTEGER} and of the default integer
-kind.
-
-@item @emph{Example}:
-See @code{PRECISION} for an example.
-@item @emph{See also}:
-@ref{SELECTED_REAL_KIND}, @gol
-@ref{PRECISION}
-@end table
-
-
-
-@node RANK
-@section @code{RANK} --- Rank of a data object
-@fnindex RANK
-@cindex rank
-
-@table @asis
-@item @emph{Description}:
-@code{RANK(A)} returns the rank of a scalar or array data object.
-
-@item @emph{Standard}:
-Technical Specification (TS) 29113
-
-@item @emph{Class}:
-Inquiry function
-
-@item @emph{Syntax}:
-@code{RESULT = RANK(A)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{A} @tab can be of any type
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{INTEGER} and of the default integer
-kind. For arrays, their rank is returned; for scalars zero is returned.
-
-@item @emph{Example}:
-@smallexample
-program test_rank
- integer :: a
- real, allocatable :: b(:,:)
-
- print *, rank(a), rank(b) ! Prints: 0 2
-end program test_rank
-@end smallexample
-
-@end table
-
-
-
-@node REAL
-@section @code{REAL} --- Convert to real type
-@fnindex REAL
-@fnindex REALPART
-@fnindex FLOAT
-@fnindex DFLOAT
-@fnindex FLOATI
-@fnindex FLOATJ
-@fnindex FLOATK
-@fnindex SNGL
-@cindex conversion, to real
-@cindex complex numbers, real part
-
-@table @asis
-@item @emph{Description}:
-@code{REAL(A [, KIND])} converts its argument @var{A} to a real type. The
-@code{REALPART} function is provided for compatibility with @command{g77},
-and its use is strongly discouraged.
-
-@item @emph{Standard}:
-Fortran 77 and later, with @var{KIND} argument Fortran 90 and later, has GNU extensions
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@multitable @columnfractions .80
-@item @code{RESULT = REAL(A [, KIND])}
-@item @code{RESULT = REALPART(Z)}
-@end multitable
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{A} @tab Shall be @code{INTEGER}, @code{REAL}, or
-@code{COMPLEX}.
-@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
-expression indicating the kind parameter of the result.
-@end multitable
-
-@item @emph{Return value}:
-These functions return a @code{REAL} variable or array under
-the following rules:
-
-@table @asis
-@item (A)
-@code{REAL(A)} is converted to a default real type if @var{A} is an
-integer or real variable.
-@item (B)
-@code{REAL(A)} is converted to a real type with the kind type parameter
-of @var{A} if @var{A} is a complex variable.
-@item (C)
-@code{REAL(A, KIND)} is converted to a real type with kind type
-parameter @var{KIND} if @var{A} is a complex, integer, or real
-variable.
-@end table
-
-@item @emph{Example}:
-@smallexample
-program test_real
- complex :: x = (1.0, 2.0)
- print *, real(x), real(x,8), realpart(x)
-end program test_real
-@end smallexample
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .23 .20 .33
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{FLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(4)} @tab Fortran 77 and later
-@item @code{DFLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(8)} @tab GNU extension
-@item @code{FLOATI(A)} @tab @code{INTEGER(2)} @tab @code{REAL(4)} @tab GNU extension (-fdec)
-@item @code{FLOATJ(A)} @tab @code{INTEGER(4)} @tab @code{REAL(4)} @tab GNU extension (-fdec)
-@item @code{FLOATK(A)} @tab @code{INTEGER(8)} @tab @code{REAL(4)} @tab GNU extension (-fdec)
-@item @code{SNGL(A)} @tab @code{REAL(8)} @tab @code{REAL(4)} @tab Fortran 77 and later
-@end multitable
-
-
-@item @emph{See also}:
-@ref{DBLE}
-
-@end table
-
-
-
-@node RENAME
-@section @code{RENAME} --- Rename a file
-@fnindex RENAME
-@cindex file system, rename file
-
-@table @asis
-@item @emph{Description}:
-Renames a file from file @var{PATH1} to @var{PATH2}. A null
-character (@code{CHAR(0)}) can be used to mark the end of the names in
-@var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
-names are ignored. If the @var{STATUS} argument is supplied, it
-contains 0 on success or a nonzero error code upon return; see
-@code{rename(2)}.
-
-This intrinsic is provided in both subroutine and function forms;
-however, only one form can be used in any given program unit.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Subroutine, function
-
-@item @emph{Syntax}:
-@multitable @columnfractions .80
-@item @code{CALL RENAME(PATH1, PATH2 [, STATUS])}
-@item @code{STATUS = RENAME(PATH1, PATH2)}
-@end multitable
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
-@item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
-@item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
-@end multitable
-
-@item @emph{See also}:
-@ref{LINK}
-
-@end table
-
-
-
-@node REPEAT
-@section @code{REPEAT} --- Repeated string concatenation
-@fnindex REPEAT
-@cindex string, repeat
-@cindex string, concatenate
-
-@table @asis
-@item @emph{Description}:
-Concatenates @var{NCOPIES} copies of a string.
-
-@item @emph{Standard}:
-Fortran 90 and later
-
-@item @emph{Class}:
-Transformational function
-
-@item @emph{Syntax}:
-@code{RESULT = REPEAT(STRING, NCOPIES)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{STRING} @tab Shall be scalar and of type @code{CHARACTER}.
-@item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER}.
-@end multitable
-
-@item @emph{Return value}:
-A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies
-of @var{STRING}.
-
-@item @emph{Example}:
-@smallexample
-program test_repeat
- write(*,*) repeat("x", 5) ! "xxxxx"
-end program
-@end smallexample
-@end table
-
-
-
-@node RESHAPE
-@section @code{RESHAPE} --- Function to reshape an array
-@fnindex RESHAPE
-@cindex array, change dimensions
-@cindex array, transmogrify
-
-@table @asis
-@item @emph{Description}:
-Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary,
-the new array may be padded with elements from @var{PAD} or permuted
-as defined by @var{ORDER}.
-
-@item @emph{Standard}:
-Fortran 90 and later
-
-@item @emph{Class}:
-Transformational function
-
-@item @emph{Syntax}:
-@code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{SOURCE} @tab Shall be an array of any type.
-@item @var{SHAPE} @tab Shall be of type @code{INTEGER} and an
-array of rank one. Its values must be positive or zero.
-@item @var{PAD} @tab (Optional) shall be an array of the same
-type as @var{SOURCE}.
-@item @var{ORDER} @tab (Optional) shall be of type @code{INTEGER}
-and an array of the same shape as @var{SHAPE}. Its values shall
-be a permutation of the numbers from 1 to n, where n is the size of
-@var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall
-be assumed.
-@end multitable
-
-@item @emph{Return value}:
-The result is an array of shape @var{SHAPE} with the same type as
-@var{SOURCE}.
-
-@item @emph{Example}:
-@smallexample
-PROGRAM test_reshape
- INTEGER, DIMENSION(4) :: x
- WRITE(*,*) SHAPE(x) ! prints "4"
- WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/))) ! prints "2 2"
-END PROGRAM
-@end smallexample
-
-@item @emph{See also}:
-@ref{SHAPE}
-@end table
-
-
-
-@node RRSPACING
-@section @code{RRSPACING} --- Reciprocal of the relative spacing
-@fnindex RRSPACING
-@cindex real number, relative spacing
-@cindex floating point, relative spacing
-
-
-@table @asis
-@item @emph{Description}:
-@code{RRSPACING(X)} returns the reciprocal of the relative spacing of
-model numbers near @var{X}.
-
-@item @emph{Standard}:
-Fortran 90 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = RRSPACING(X)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab Shall be of type @code{REAL}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of the same type and kind as @var{X}.
-The value returned is equal to
-@code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}.
-
-@item @emph{See also}:
-@ref{SPACING}
-@end table
-
-
-
-@node RSHIFT
-@section @code{RSHIFT} --- Right shift bits
-@fnindex RSHIFT
-@cindex bits, shift right
-
-@table @asis
-@item @emph{Description}:
-@code{RSHIFT} returns a value corresponding to @var{I} with all of the
-bits shifted right by @var{SHIFT} places. @var{SHIFT} shall be
-nonnegative and less than or equal to @code{BIT_SIZE(I)}, otherwise
-the result value is undefined. Bits shifted out from the right end
-are lost. The fill is arithmetic: the bits shifted in from the left
-end are equal to the leftmost bit, which in two's complement
-representation is the sign bit.
-
-This function has been superseded by the @code{SHIFTA} intrinsic, which
-is standard in Fortran 2008 and later.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = RSHIFT(I, SHIFT)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{I} @tab The type shall be @code{INTEGER}.
-@item @var{SHIFT} @tab The type shall be @code{INTEGER}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{INTEGER} and of the same kind as
-@var{I}.
-
-@item @emph{See also}:
-@ref{ISHFT}, @gol
-@ref{ISHFTC}, @gol
-@ref{LSHIFT}, @gol
-@ref{SHIFTA}, @gol
-@ref{SHIFTR}, @gol
-@ref{SHIFTL}
-
-@end table
-
-
-
-@node SAME_TYPE_AS
-@section @code{SAME_TYPE_AS} --- Query dynamic types for equality
-@fnindex SAME_TYPE_AS
-
-@table @asis
-@item @emph{Description}:
-Query dynamic types for equality.
-
-@item @emph{Standard}:
-Fortran 2003 and later
-
-@item @emph{Class}:
-Inquiry function
-
-@item @emph{Syntax}:
-@code{RESULT = SAME_TYPE_AS(A, B)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{A} @tab Shall be an object of extensible declared type or
-unlimited polymorphic.
-@item @var{B} @tab Shall be an object of extensible declared type or
-unlimited polymorphic.
-@end multitable
-
-@item @emph{Return value}:
-The return value is a scalar of type default logical. It is true if and
-only if the dynamic type of A is the same as the dynamic type of B.
-
-@item @emph{See also}:
-@ref{EXTENDS_TYPE_OF}
-
-@end table
-
-
-
-@node SCALE
-@section @code{SCALE} --- Scale a real value
-@fnindex SCALE
-@cindex real number, scale
-@cindex floating point, scale
-
-@table @asis
-@item @emph{Description}:
-@code{SCALE(X,I)} returns @code{X * RADIX(X)**I}.
-
-@item @emph{Standard}:
-Fortran 90 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = SCALE(X, I)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab The type of the argument shall be a @code{REAL}.
-@item @var{I} @tab The type of the argument shall be a @code{INTEGER}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of the same type and kind as @var{X}.
-Its value is @code{X * RADIX(X)**I}.
-
-@item @emph{Example}:
-@smallexample
-program test_scale
- real :: x = 178.1387e-4
- integer :: i = 5
- print *, scale(x,i), x*radix(x)**i
-end program test_scale
-@end smallexample
-
-@end table
-
-
-
-@node SCAN
-@section @code{SCAN} --- Scan a string for the presence of a set of characters
-@fnindex SCAN
-@cindex string, find subset
-
-@table @asis
-@item @emph{Description}:
-Scans a @var{STRING} for any of the characters in a @var{SET}
-of characters.
-
-If @var{BACK} is either absent or equals @code{FALSE}, this function
-returns the position of the leftmost character of @var{STRING} that is
-in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
-is returned. If no character of @var{SET} is found in @var{STRING}, the
-result is zero.
-
-@item @emph{Standard}:
-Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = SCAN(STRING, SET[, BACK [, KIND]])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{STRING} @tab Shall be of type @code{CHARACTER}.
-@item @var{SET} @tab Shall be of type @code{CHARACTER}.
-@item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
-@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
-expression indicating the kind parameter of the result.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{INTEGER} and of kind @var{KIND}. If
-@var{KIND} is absent, the return value is of default integer kind.
-
-@item @emph{Example}:
-@smallexample
-PROGRAM test_scan
- WRITE(*,*) SCAN("FORTRAN", "AO") ! 2, found 'O'
- WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.) ! 6, found 'A'
- WRITE(*,*) SCAN("FORTRAN", "C++") ! 0, found none
-END PROGRAM
-@end smallexample
-
-@item @emph{See also}:
-@ref{INDEX intrinsic}, @gol
-@ref{VERIFY}
-@end table
-
-
-
-@node SECNDS
-@section @code{SECNDS} --- Time function
-@fnindex SECNDS
-@cindex time, elapsed
-@cindex elapsed time
-
-@table @asis
-@item @emph{Description}:
-@code{SECNDS(X)} gets the time in seconds from the real-time system clock.
-@var{X} is a reference time, also in seconds. If this is zero, the time in
-seconds from midnight is returned. This function is non-standard and its
-use is discouraged.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Function
-
-@item @emph{Syntax}:
-@code{RESULT = SECNDS (X)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{T} @tab Shall be of type @code{REAL(4)}.
-@item @var{X} @tab Shall be of type @code{REAL(4)}.
-@end multitable
-
-@item @emph{Return value}:
-None
-
-@item @emph{Example}:
-@smallexample
-program test_secnds
- integer :: i
- real(4) :: t1, t2
- print *, secnds (0.0) ! seconds since midnight
- t1 = secnds (0.0) ! reference time
- do i = 1, 10000000 ! do something
- end do
- t2 = secnds (t1) ! elapsed time
- print *, "Something took ", t2, " seconds."
-end program test_secnds
-@end smallexample
-@end table
-
-
-
-@node SECOND
-@section @code{SECOND} --- CPU time function
-@fnindex SECOND
-@cindex time, elapsed
-@cindex elapsed time
-
-@table @asis
-@item @emph{Description}:
-Returns a @code{REAL(4)} value representing the elapsed CPU time in
-seconds. This provides the same functionality as the standard
-@code{CPU_TIME} intrinsic, and is only included for backwards
-compatibility.
-
-This intrinsic is provided in both subroutine and function forms;
-however, only one form can be used in any given program unit.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Subroutine, function
-
-@item @emph{Syntax}:
-@multitable @columnfractions .80
-@item @code{CALL SECOND(TIME)}
-@item @code{TIME = SECOND()}
-@end multitable
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{TIME} @tab Shall be of type @code{REAL(4)}.
-@end multitable
-
-@item @emph{Return value}:
-In either syntax, @var{TIME} is set to the process's current runtime in
-seconds.
-
-@item @emph{See also}:
-@ref{CPU_TIME}
-
-@end table
-
-
-
-@node SELECTED_CHAR_KIND
-@section @code{SELECTED_CHAR_KIND} --- Choose character kind
-@fnindex SELECTED_CHAR_KIND
-@cindex character kind
-@cindex kind, character
-
-@table @asis
-@item @emph{Description}:
-
-@code{SELECTED_CHAR_KIND(NAME)} returns the kind value for the character
-set named @var{NAME}, if a character set with such a name is supported,
-or @math{-1} otherwise. Currently, supported character sets include
-``ASCII'' and ``DEFAULT'', which are equivalent, and ``ISO_10646''
-(Universal Character Set, UCS-4) which is commonly known as Unicode.
-
-@item @emph{Standard}:
-Fortran 2003 and later
-
-@item @emph{Class}:
-Transformational function
-
-@item @emph{Syntax}:
-@code{RESULT = SELECTED_CHAR_KIND(NAME)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{NAME} @tab Shall be a scalar and of the default character type.
-@end multitable
-
-@item @emph{Example}:
-@smallexample
-program character_kind
- use iso_fortran_env
- implicit none
- integer, parameter :: ascii = selected_char_kind ("ascii")
- integer, parameter :: ucs4 = selected_char_kind ('ISO_10646')
-
- character(kind=ascii, len=26) :: alphabet
- character(kind=ucs4, len=30) :: hello_world
-
- alphabet = ascii_"abcdefghijklmnopqrstuvwxyz"
- hello_world = ucs4_'Hello World and Ni Hao -- ' &
- // char (int (z'4F60'), ucs4) &
- // char (int (z'597D'), ucs4)
-
- write (*,*) alphabet
-
- open (output_unit, encoding='UTF-8')
- write (*,*) trim (hello_world)
-end program character_kind
-@end smallexample
-@end table
-
-
-
-@node SELECTED_INT_KIND
-@section @code{SELECTED_INT_KIND} --- Choose integer kind
-@fnindex SELECTED_INT_KIND
-@cindex integer kind
-@cindex kind, integer
-
-@table @asis
-@item @emph{Description}:
-@code{SELECTED_INT_KIND(R)} return the kind value of the smallest integer
-type that can represent all values ranging from @math{-10^R} (exclusive)
-to @math{10^R} (exclusive). If there is no integer kind that accommodates
-this range, @code{SELECTED_INT_KIND} returns @math{-1}.
-
-@item @emph{Standard}:
-Fortran 90 and later
-
-@item @emph{Class}:
-Transformational function
-
-@item @emph{Syntax}:
-@code{RESULT = SELECTED_INT_KIND(R)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{R} @tab Shall be a scalar and of type @code{INTEGER}.
-@end multitable
-
-@item @emph{Example}:
-@smallexample
-program large_integers
- integer,parameter :: k5 = selected_int_kind(5)
- integer,parameter :: k15 = selected_int_kind(15)
- integer(kind=k5) :: i5
- integer(kind=k15) :: i15
-
- print *, huge(i5), huge(i15)
-
- ! The following inequalities are always true
- print *, huge(i5) >= 10_k5**5-1
- print *, huge(i15) >= 10_k15**15-1
-end program large_integers
-@end smallexample
-@end table
-
-
-
-@node SELECTED_REAL_KIND
-@section @code{SELECTED_REAL_KIND} --- Choose real kind
-@fnindex SELECTED_REAL_KIND
-@cindex real kind
-@cindex kind, real
-@cindex radix, real
-
-@table @asis
-@item @emph{Description}:
-@code{SELECTED_REAL_KIND(P,R)} returns the kind value of a real data type
-with decimal precision of at least @code{P} digits, exponent range of
-at least @code{R}, and with a radix of @code{RADIX}.
-
-@item @emph{Standard}:
-Fortran 90 and later, with @code{RADIX} Fortran 2008 or later
-
-@item @emph{Class}:
-Transformational function
-
-@item @emph{Syntax}:
-@code{RESULT = SELECTED_REAL_KIND([P, R, RADIX])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
-@item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
-@item @var{RADIX} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
-@end multitable
-Before Fortran 2008, at least one of the arguments @var{R} or @var{P} shall
-be present; since Fortran 2008, they are assumed to be zero if absent.
-
-@item @emph{Return value}:
-
-@code{SELECTED_REAL_KIND} returns the value of the kind type parameter of
-a real data type with decimal precision of at least @code{P} digits, a
-decimal exponent range of at least @code{R}, and with the requested
-@code{RADIX}. If the @code{RADIX} parameter is absent, real kinds with
-any radix can be returned. If more than one real data type meet the
-criteria, the kind of the data type with the smallest decimal precision
-is returned. If no real data type matches the criteria, the result is
-@table @asis
-@item -1 if the processor does not support a real data type with a
-precision greater than or equal to @code{P}, but the @code{R} and
-@code{RADIX} requirements can be fulfilled
-@item -2 if the processor does not support a real type with an exponent
-range greater than or equal to @code{R}, but @code{P} and @code{RADIX}
-are fulfillable
-@item -3 if @code{RADIX} but not @code{P} and @code{R} requirements
-are fulfillable
-@item -4 if @code{RADIX} and either @code{P} or @code{R} requirements
-are fulfillable
-@item -5 if there is no real type with the given @code{RADIX}
-@end table
-
-@item @emph{Example}:
-@smallexample
-program real_kinds
- integer,parameter :: p6 = selected_real_kind(6)
- integer,parameter :: p10r100 = selected_real_kind(10,100)
- integer,parameter :: r400 = selected_real_kind(r=400)
- real(kind=p6) :: x
- real(kind=p10r100) :: y
- real(kind=r400) :: z
-
- print *, precision(x), range(x)
- print *, precision(y), range(y)
- print *, precision(z), range(z)
-end program real_kinds
-@end smallexample
-@item @emph{See also}:
-@ref{PRECISION}, @gol
-@ref{RANGE}, @gol
-@ref{RADIX}
-@end table
-
-
-
-@node SET_EXPONENT
-@section @code{SET_EXPONENT} --- Set the exponent of the model
-@fnindex SET_EXPONENT
-@cindex real number, set exponent
-@cindex floating point, set exponent
-
-@table @asis
-@item @emph{Description}:
-@code{SET_EXPONENT(X, I)} returns the real number whose fractional part
-is that of @var{X} and whose exponent part is @var{I}.
-
-@item @emph{Standard}:
-Fortran 90 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = SET_EXPONENT(X, I)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab Shall be of type @code{REAL}.
-@item @var{I} @tab Shall be of type @code{INTEGER}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of the same type and kind as @var{X}.
-The real number whose fractional part
-is that of @var{X} and whose exponent part if @var{I} is returned;
-it is @code{FRACTION(X) * RADIX(X)**I}.
-
-@item @emph{Example}:
-@smallexample
-PROGRAM test_setexp
- REAL :: x = 178.1387e-4
- INTEGER :: i = 17
- PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i
-END PROGRAM
-@end smallexample
-
-@end table
-
-
-
-@node SHAPE
-@section @code{SHAPE} --- Determine the shape of an array
-@fnindex SHAPE
-@cindex array, shape
-
-@table @asis
-@item @emph{Description}:
-Determines the shape of an array.
-
-@item @emph{Standard}:
-Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later
-
-@item @emph{Class}:
-Inquiry function
-
-@item @emph{Syntax}:
-@code{RESULT = SHAPE(SOURCE [, KIND])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{SOURCE} @tab Shall be an array or scalar of any type.
-If @var{SOURCE} is a pointer it must be associated and allocatable
-arrays must be allocated.
-@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
-expression indicating the kind parameter of the result.
-@end multitable
-
-@item @emph{Return value}:
-An @code{INTEGER} array of rank one with as many elements as @var{SOURCE}
-has dimensions. The elements of the resulting array correspond to the extend
-of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar,
-the result is the rank one array of size zero. If @var{KIND} is absent, the
-return value has the default integer kind otherwise the specified kind.
-
-@item @emph{Example}:
-@smallexample
-PROGRAM test_shape
- INTEGER, DIMENSION(-1:1, -1:2) :: A
- WRITE(*,*) SHAPE(A) ! (/ 3, 4 /)
- WRITE(*,*) SIZE(SHAPE(42)) ! (/ /)
-END PROGRAM
-@end smallexample
-
-@item @emph{See also}:
-@ref{RESHAPE}, @gol
-@ref{SIZE}
-@end table
-
-
-
-@node SHIFTA
-@section @code{SHIFTA} --- Right shift with fill
-@fnindex SHIFTA
-@cindex bits, shift right
-@cindex shift, right with fill
-
-@table @asis
-@item @emph{Description}:
-@code{SHIFTA} returns a value corresponding to @var{I} with all of the
-bits shifted right by @var{SHIFT} places. @var{SHIFT} that be
-nonnegative and less than or equal to @code{BIT_SIZE(I)}, otherwise
-the result value is undefined. Bits shifted out from the right end
-are lost. The fill is arithmetic: the bits shifted in from the left
-end are equal to the leftmost bit, which in two's complement
-representation is the sign bit.
-
-@item @emph{Standard}:
-Fortran 2008 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = SHIFTA(I, SHIFT)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{I} @tab The type shall be @code{INTEGER}.
-@item @var{SHIFT} @tab The type shall be @code{INTEGER}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{INTEGER} and of the same kind as
-@var{I}.
-
-@item @emph{See also}:
-@ref{SHIFTL}, @gol
-@ref{SHIFTR}
-@end table
-
-
-
-@node SHIFTL
-@section @code{SHIFTL} --- Left shift
-@fnindex SHIFTL
-@cindex bits, shift left
-@cindex shift, left
-
-@table @asis
-@item @emph{Description}:
-@code{SHIFTL} returns a value corresponding to @var{I} with all of the
-bits shifted left by @var{SHIFT} places. @var{SHIFT} shall be
-nonnegative and less than or equal to @code{BIT_SIZE(I)}, otherwise
-the result value is undefined. Bits shifted out from the left end are
-lost, and bits shifted in from the right end are set to 0.
-
-@item @emph{Standard}:
-Fortran 2008 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = SHIFTL(I, SHIFT)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{I} @tab The type shall be @code{INTEGER}.
-@item @var{SHIFT} @tab The type shall be @code{INTEGER}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{INTEGER} and of the same kind as
-@var{I}.
-
-@item @emph{See also}:
-@ref{SHIFTA}, @gol
-@ref{SHIFTR}
-@end table
-
-
-
-@node SHIFTR
-@section @code{SHIFTR} --- Right shift
-@fnindex SHIFTR
-@cindex bits, shift right
-@cindex shift, right
-
-@table @asis
-@item @emph{Description}:
-@code{SHIFTR} returns a value corresponding to @var{I} with all of the
-bits shifted right by @var{SHIFT} places. @var{SHIFT} shall be
-nonnegative and less than or equal to @code{BIT_SIZE(I)}, otherwise
-the result value is undefined. Bits shifted out from the right end
-are lost, and bits shifted in from the left end are set to 0.
-
-@item @emph{Standard}:
-Fortran 2008 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = SHIFTR(I, SHIFT)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{I} @tab The type shall be @code{INTEGER}.
-@item @var{SHIFT} @tab The type shall be @code{INTEGER}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{INTEGER} and of the same kind as
-@var{I}.
-
-@item @emph{See also}:
-@ref{SHIFTA}, @gol
-@ref{SHIFTL}
-@end table
-
-
-
-@node SIGN
-@section @code{SIGN} --- Sign copying function
-@fnindex SIGN
-@fnindex ISIGN
-@fnindex DSIGN
-@cindex sign copying
-
-@table @asis
-@item @emph{Description}:
-@code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}.
-
-@item @emph{Standard}:
-Fortran 77 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = SIGN(A, B)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL}
-@item @var{B} @tab Shall be of the same type and kind as @var{A}.
-@end multitable
-
-@item @emph{Return value}:
-The kind of the return value is that of @var{A} and @var{B}.
-If @math{B \ge 0} then the result is @code{ABS(A)}, else
-it is @code{-ABS(A)}.
-
-@item @emph{Example}:
-@smallexample
-program test_sign
- print *, sign(-12,1)
- print *, sign(-12,0)
- print *, sign(-12,-1)
-
- print *, sign(-12.,1.)
- print *, sign(-12.,0.)
- print *, sign(-12.,-1.)
-end program test_sign
-@end smallexample
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .26 .20 .30
-@headitem Name @tab Arguments @tab Return type @tab Standard
-@item @code{SIGN(A,B)} @tab @code{REAL(4) A, B} @tab @code{REAL(4)} @tab Fortran 77 and later
-@item @code{ISIGN(A,B)} @tab @code{INTEGER(4) A, B} @tab @code{INTEGER(4)} @tab Fortran 77 and later
-@item @code{DSIGN(A,B)} @tab @code{REAL(8) A, B} @tab @code{REAL(8)} @tab Fortran 77 and later
-@end multitable
-@end table
-
-
-
-@node SIGNAL
-@section @code{SIGNAL} --- Signal handling subroutine (or function)
-@fnindex SIGNAL
-@cindex system, signal handling
-
-@table @asis
-@item @emph{Description}:
-@code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine
-@var{HANDLER} to be executed with a single integer argument when signal
-@var{NUMBER} occurs. If @var{HANDLER} is an integer, it can be used to
-turn off handling of signal @var{NUMBER} or revert to its default
-action. See @code{signal(2)}.
-
-If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument
-is supplied, it is set to the value returned by @code{signal(2)}.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Subroutine, function
-
-@item @emph{Syntax}:
-@multitable @columnfractions .80
-@item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])}
-@item @code{STATUS = SIGNAL(NUMBER, HANDLER)}
-@end multitable
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)}
-@item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or
-@code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar.
-@code{INTEGER}. It is @code{INTENT(IN)}.
-@item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
-integer. It has @code{INTENT(OUT)}.
-@end multitable
-@c TODO: What should the interface of the handler be? Does it take arguments?
-
-@item @emph{Return value}:
-The @code{SIGNAL} function returns the value returned by @code{signal(2)}.
-
-@item @emph{Example}:
-@smallexample
-program test_signal
- intrinsic signal
- external handler_print
-
- call signal (12, handler_print)
- call signal (10, 1)
-
- call sleep (30)
-end program test_signal
-@end smallexample
-@end table
-
-
-
-@node SIN
-@section @code{SIN} --- Sine function
-@fnindex SIN
-@fnindex DSIN
-@fnindex CSIN
-@fnindex ZSIN
-@fnindex CDSIN
-@cindex trigonometric function, sine
-@cindex sine
-
-@table @asis
-@item @emph{Description}:
-@code{SIN(X)} computes the sine of @var{X}.
-
-@item @emph{Standard}:
-Fortran 77 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = SIN(X)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab The type shall be @code{REAL} or
-@code{COMPLEX}.
-@end multitable
-
-@item @emph{Return value}:
-The return value has same type and kind as @var{X}.
-
-@item @emph{Example}:
-@smallexample
-program test_sin
- real :: x = 0.0
- x = sin(x)
-end program test_sin
-@end smallexample
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .23 .20 .33
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{SIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
-@item @code{DSIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
-@item @code{CSIN(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
-@item @code{ZSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
-@item @code{CDSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
-@end multitable
-
-@item @emph{See also}:
-Inverse function: @gol
-@ref{ASIN} @gol
-Degrees function: @gol
-@ref{SIND}
-@end table
-
-
-
-@node SIND
-@section @code{SIND} --- Sine function, degrees
-@fnindex SIND
-@fnindex DSIND
-@fnindex CSIND
-@fnindex ZSIND
-@fnindex CDSIND
-@cindex trigonometric function, sine, degrees
-@cindex sine, degrees
-
-@table @asis
-@item @emph{Description}:
-@code{SIND(X)} computes the sine of @var{X} in degrees.
-
-This function is for compatibility only and should be avoided in favor of
-standard constructs wherever possible.
-
-@item @emph{Standard}:
-GNU extension, enabled with @option{-fdec-math}.
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = SIND(X)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab The type shall be @code{REAL} or
-@code{COMPLEX}.
-@end multitable
-
-@item @emph{Return value}:
-The return value has same type and kind as @var{X}, and its value is in degrees.
-
-@item @emph{Example}:
-@smallexample
-program test_sind
- real :: x = 0.0
- x = sind(x)
-end program test_sind
-@end smallexample
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .23 .20 .33
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{SIND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension
-@item @code{DSIND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
-@item @code{CSIND(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab GNU extension
-@item @code{ZSIND(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
-@item @code{CDSIND(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
-@end multitable
-
-@item @emph{See also}:
-Inverse function: @gol
-@ref{ASIND} @gol
-Radians function: @gol
-@ref{SIN} @gol
-@end table
-
-
-
-@node SINH
-@section @code{SINH} --- Hyperbolic sine function
-@fnindex SINH
-@fnindex DSINH
-@cindex hyperbolic sine
-@cindex hyperbolic function, sine
-@cindex sine, hyperbolic
-
-@table @asis
-@item @emph{Description}:
-@code{SINH(X)} computes the hyperbolic sine of @var{X}.
-
-@item @emph{Standard}:
-Fortran 90 and later, for a complex argument Fortran 2008 or later, has
-a GNU extension
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = SINH(X)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
-@end multitable
-
-@item @emph{Return value}:
-The return value has same type and kind as @var{X}.
-
-@item @emph{Example}:
-@smallexample
-program test_sinh
- real(8) :: x = - 1.0_8
- x = sinh(x)
-end program test_sinh
-@end smallexample
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .23 .20 .33
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{DSINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 90 and later
-@end multitable
-
-@item @emph{See also}:
-@ref{ASINH}
-@end table
-
-
-
-@node SIZE
-@section @code{SIZE} --- Determine the size of an array
-@fnindex SIZE
-@cindex array, size
-@cindex array, number of elements
-@cindex array, count elements
-
-@table @asis
-@item @emph{Description}:
-Determine the extent of @var{ARRAY} along a specified dimension @var{DIM},
-or the total number of elements in @var{ARRAY} if @var{DIM} is absent.
-
-@item @emph{Standard}:
-Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later
-
-@item @emph{Class}:
-Inquiry function
-
-@item @emph{Syntax}:
-@code{RESULT = SIZE(ARRAY[, DIM [, KIND]])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is
-a pointer it must be associated and allocatable arrays must be allocated.
-@item @var{DIM} @tab (Optional) shall be a scalar of type @code{INTEGER}
-and its value shall be in the range from 1 to n, where n equals the rank
-of @var{ARRAY}.
-@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
-expression indicating the kind parameter of the result.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{INTEGER} and of kind @var{KIND}. If
-@var{KIND} is absent, the return value is of default integer kind.
-
-@item @emph{Example}:
-@smallexample
-PROGRAM test_size
- WRITE(*,*) SIZE((/ 1, 2 /)) ! 2
-END PROGRAM
-@end smallexample
-
-@item @emph{See also}:
-@ref{SHAPE}, @gol
-@ref{RESHAPE}
-@end table
-
-
-@node SIZEOF
-@section @code{SIZEOF} --- Size in bytes of an expression
-@fnindex SIZEOF
-@cindex expression size
-@cindex size of an expression
-
-@table @asis
-@item @emph{Description}:
-@code{SIZEOF(X)} calculates the number of bytes of storage the
-expression @code{X} occupies.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Inquiry function
-
-@item @emph{Syntax}:
-@code{N = SIZEOF(X)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab The argument shall be of any type, rank or shape.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type integer and of the system-dependent kind
-@var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
-number of bytes occupied by the argument. If the argument has the
-@code{POINTER} attribute, the number of bytes of the storage area pointed
-to is returned. If the argument is of a derived type with @code{POINTER}
-or @code{ALLOCATABLE} components, the return value does not account for
-the sizes of the data pointed to by these components. If the argument is
-polymorphic, the size according to the dynamic type is returned. The argument
-may not be a procedure or procedure pointer. Note that the code assumes for
-arrays that those are contiguous; for contiguous arrays, it returns the
-storage or an array element multiplied by the size of the array.
-
-@item @emph{Example}:
-@smallexample
- integer :: i
- real :: r, s(5)
- print *, (sizeof(s)/sizeof(r) == 5)
- end
-@end smallexample
-The example will print @code{.TRUE.} unless you are using a platform
-where default @code{REAL} variables are unusually padded.
-
-@item @emph{See also}:
-@ref{C_SIZEOF}, @gol
-@ref{STORAGE_SIZE}
-@end table
-
-
-@node SLEEP
-@section @code{SLEEP} --- Sleep for the specified number of seconds
-@fnindex SLEEP
-@cindex delayed execution
-
-@table @asis
-@item @emph{Description}:
-Calling this subroutine causes the process to pause for @var{SECONDS} seconds.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Subroutine
-
-@item @emph{Syntax}:
-@code{CALL SLEEP(SECONDS)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{SECONDS} @tab The type shall be of default @code{INTEGER}.
-@end multitable
-
-@item @emph{Example}:
-@smallexample
-program test_sleep
- call sleep(5)
-end
-@end smallexample
-@end table
-
-
-
-@node SPACING
-@section @code{SPACING} --- Smallest distance between two numbers of a given type
-@fnindex SPACING
-@cindex real number, relative spacing
-@cindex floating point, relative spacing
-
-@table @asis
-@item @emph{Description}:
-Determines the distance between the argument @var{X} and the nearest
-adjacent number of the same type.
-
-@item @emph{Standard}:
-Fortran 90 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = SPACING(X)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab Shall be of type @code{REAL}.
-@end multitable
-
-@item @emph{Return value}:
-The result is of the same type as the input argument @var{X}.
-
-@item @emph{Example}:
-@smallexample
-PROGRAM test_spacing
- INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37)
- INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200)
-
- WRITE(*,*) spacing(1.0_SGL) ! "1.1920929E-07" on i686
- WRITE(*,*) spacing(1.0_DBL) ! "2.220446049250313E-016" on i686
-END PROGRAM
-@end smallexample
-
-@item @emph{See also}:
-@ref{RRSPACING}
-@end table
-
-
-
-@node SPREAD
-@section @code{SPREAD} --- Add a dimension to an array
-@fnindex SPREAD
-@cindex array, increase dimension
-@cindex array, duplicate elements
-@cindex array, duplicate dimensions
-
-@table @asis
-@item @emph{Description}:
-Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified
-dimension @var{DIM}.
-
-@item @emph{Standard}:
-Fortran 90 and later
-
-@item @emph{Class}:
-Transformational function
-
-@item @emph{Syntax}:
-@code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{SOURCE} @tab Shall be a scalar or an array of any type and
-a rank less than seven.
-@item @var{DIM} @tab Shall be a scalar of type @code{INTEGER} with a
-value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}.
-@item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}.
-@end multitable
-
-@item @emph{Return value}:
-The result is an array of the same type as @var{SOURCE} and has rank n+1
-where n equals the rank of @var{SOURCE}.
-
-@item @emph{Example}:
-@smallexample
-PROGRAM test_spread
- INTEGER :: a = 1, b(2) = (/ 1, 2 /)
- WRITE(*,*) SPREAD(A, 1, 2) ! "1 1"
- WRITE(*,*) SPREAD(B, 1, 2) ! "1 1 2 2"
-END PROGRAM
-@end smallexample
-
-@item @emph{See also}:
-@ref{UNPACK}
-@end table
-
-
-
-@node SQRT
-@section @code{SQRT} --- Square-root function
-@fnindex SQRT
-@fnindex DSQRT
-@fnindex CSQRT
-@fnindex ZSQRT
-@fnindex CDSQRT
-@cindex root
-@cindex square-root
-
-@table @asis
-@item @emph{Description}:
-@code{SQRT(X)} computes the square root of @var{X}.
-
-@item @emph{Standard}:
-Fortran 77 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = SQRT(X)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab The type shall be @code{REAL} or
-@code{COMPLEX}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{REAL} or @code{COMPLEX}.
-The kind type parameter is the same as @var{X}.
-
-@item @emph{Example}:
-@smallexample
-program test_sqrt
- real(8) :: x = 2.0_8
- complex :: z = (1.0, 2.0)
- x = sqrt(x)
- z = sqrt(z)
-end program test_sqrt
-@end smallexample
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .23 .20 .33
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{SQRT(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
-@item @code{DSQRT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
-@item @code{CSQRT(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
-@item @code{ZSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
-@item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
-@end multitable
-@end table
-
-
-
-@node SRAND
-@section @code{SRAND} --- Reinitialize the random number generator
-@fnindex SRAND
-@cindex random number generation, seeding
-@cindex seeding a random number generator
-
-@table @asis
-@item @emph{Description}:
-@code{SRAND} reinitializes the pseudo-random number generator
-called by @code{RAND} and @code{IRAND}. The new seed used by the
-generator is specified by the required argument @var{SEED}.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Subroutine
-
-@item @emph{Syntax}:
-@code{CALL SRAND(SEED)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}.
-@end multitable
-
-@item @emph{Return value}:
-Does not return anything.
-
-@item @emph{Example}:
-See @code{RAND} and @code{IRAND} for examples.
-
-@item @emph{Notes}:
-The Fortran standard specifies the intrinsic subroutines
-@code{RANDOM_SEED} to initialize the pseudo-random number
-generator and @code{RANDOM_NUMBER} to generate pseudo-random numbers.
-These subroutines should be used in new codes.
-
-Please note that in GNU Fortran, these two sets of intrinsics (@code{RAND},
-@code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and
-@code{RANDOM_SEED} on the other hand) access two independent
-pseudo-random number generators.
-
-@item @emph{See also}:
-@ref{RAND}, @gol
-@ref{RANDOM_SEED}, @gol
-@ref{RANDOM_NUMBER}
-@end table
-
-
-
-@node STAT
-@section @code{STAT} --- Get file status
-@fnindex STAT
-@cindex file system, file status
-
-@table @asis
-@item @emph{Description}:
-This function returns information about a file. No permissions are required on
-the file itself, but execute (search) permission is required on all of the
-directories in path that lead to the file.
-
-The elements that are obtained and stored in the array @code{VALUES}:
-@multitable @columnfractions .15 .70
-@item @code{VALUES(1)} @tab Device ID
-@item @code{VALUES(2)} @tab Inode number
-@item @code{VALUES(3)} @tab File mode
-@item @code{VALUES(4)} @tab Number of links
-@item @code{VALUES(5)} @tab Owner's uid
-@item @code{VALUES(6)} @tab Owner's gid
-@item @code{VALUES(7)} @tab ID of device containing directory entry for file (0 if not available)
-@item @code{VALUES(8)} @tab File size (bytes)
-@item @code{VALUES(9)} @tab Last access time
-@item @code{VALUES(10)} @tab Last modification time
-@item @code{VALUES(11)} @tab Last file status change time
-@item @code{VALUES(12)} @tab Preferred I/O block size (-1 if not available)
-@item @code{VALUES(13)} @tab Number of blocks allocated (-1 if not available)
-@end multitable
-
-Not all these elements are relevant on all systems.
-If an element is not relevant, it is returned as 0.
-
-This intrinsic is provided in both subroutine and function forms; however,
-only one form can be used in any given program unit.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Subroutine, function
-
-@item @emph{Syntax}:
-@multitable @columnfractions .80
-@item @code{CALL STAT(NAME, VALUES [, STATUS])}
-@item @code{STATUS = STAT(NAME, VALUES)}
-@end multitable
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{NAME} @tab The type shall be @code{CHARACTER}, of the
-default kind and a valid path within the file system.
-@item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
-@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
-on success and a system specific error code otherwise.
-@end multitable
-
-@item @emph{Example}:
-@smallexample
-PROGRAM test_stat
- INTEGER, DIMENSION(13) :: buff
- INTEGER :: status
-
- CALL STAT("/etc/passwd", buff, status)
-
- IF (status == 0) THEN
- WRITE (*, FMT="('Device ID:', T30, I19)") buff(1)
- WRITE (*, FMT="('Inode number:', T30, I19)") buff(2)
- WRITE (*, FMT="('File mode (octal):', T30, O19)") buff(3)
- WRITE (*, FMT="('Number of links:', T30, I19)") buff(4)
- WRITE (*, FMT="('Owner''s uid:', T30, I19)") buff(5)
- WRITE (*, FMT="('Owner''s gid:', T30, I19)") buff(6)
- WRITE (*, FMT="('Device where located:', T30, I19)") buff(7)
- WRITE (*, FMT="('File size:', T30, I19)") buff(8)
- WRITE (*, FMT="('Last access time:', T30, A19)") CTIME(buff(9))
- WRITE (*, FMT="('Last modification time', T30, A19)") CTIME(buff(10))
- WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11))
- WRITE (*, FMT="('Preferred block size:', T30, I19)") buff(12)
- WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13)
- END IF
-END PROGRAM
-@end smallexample
-
-@item @emph{See also}:
-To stat an open file: @gol
-@ref{FSTAT} @gol
-To stat a link: @gol
-@ref{LSTAT}
-@end table
-
-
-
-@node STORAGE_SIZE
-@section @code{STORAGE_SIZE} --- Storage size in bits
-@fnindex STORAGE_SIZE
-@cindex storage size
-
-@table @asis
-@item @emph{Description}:
-Returns the storage size of argument @var{A} in bits.
-@item @emph{Standard}:
-Fortran 2008 and later
-@item @emph{Class}:
-Inquiry function
-@item @emph{Syntax}:
-@code{RESULT = STORAGE_SIZE(A [, KIND])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{A} @tab Shall be a scalar or array of any type.
-@item @var{KIND} @tab (Optional) shall be a scalar integer constant expression.
-@end multitable
-
-@item @emph{Return Value}:
-The result is a scalar integer with the kind type parameter specified by KIND
-(or default integer type if KIND is missing). The result value is the size
-expressed in bits for an element of an array that has the dynamic type and type
-parameters of A.
-
-@item @emph{See also}:
-@ref{C_SIZEOF}, @gol
-@ref{SIZEOF}
-@end table
-
-
-
-@node SUM
-@section @code{SUM} --- Sum of array elements
-@fnindex SUM
-@cindex array, sum
-@cindex array, add elements
-@cindex array, conditionally add elements
-@cindex sum array elements
-
-@table @asis
-@item @emph{Description}:
-Adds the elements of @var{ARRAY} along dimension @var{DIM} if
-the corresponding element in @var{MASK} is @code{TRUE}.
-
-@item @emph{Standard}:
-Fortran 90 and later
-
-@item @emph{Class}:
-Transformational function
-
-@item @emph{Syntax}:
-@multitable @columnfractions .80
-@item @code{RESULT = SUM(ARRAY[, MASK])}
-@item @code{RESULT = SUM(ARRAY, DIM[, MASK])}
-@end multitable
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
-@code{REAL} or @code{COMPLEX}.
-@item @var{DIM} @tab (Optional) shall be a scalar of type
-@code{INTEGER} with a value in the range from 1 to n, where n
-equals the rank of @var{ARRAY}.
-@item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
-and either be a scalar or an array of the same shape as @var{ARRAY}.
-@end multitable
-
-@item @emph{Return value}:
-The result is of the same type as @var{ARRAY}.
-
-If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY}
-is returned. Otherwise, an array of rank n-1, where n equals the rank of
-@var{ARRAY}, and a shape similar to that of @var{ARRAY} with dimension @var{DIM}
-dropped is returned.
-
-@item @emph{Example}:
-@smallexample
-PROGRAM test_sum
- INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
- print *, SUM(x) ! all elements, sum = 15
- print *, SUM(x, MASK=MOD(x, 2)==1) ! odd elements, sum = 9
-END PROGRAM
-@end smallexample
-
-@item @emph{See also}:
-@ref{PRODUCT}
-@end table
-
-
-
-@node SYMLNK
-@section @code{SYMLNK} --- Create a symbolic link
-@fnindex SYMLNK
-@cindex file system, create link
-@cindex file system, soft link
-
-@table @asis
-@item @emph{Description}:
-Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null
-character (@code{CHAR(0)}) can be used to mark the end of the names in
-@var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
-names are ignored. If the @var{STATUS} argument is supplied, it
-contains 0 on success or a nonzero error code upon return; see
-@code{symlink(2)}. If the system does not supply @code{symlink(2)},
-@code{ENOSYS} is returned.
-
-This intrinsic is provided in both subroutine and function forms;
-however, only one form can be used in any given program unit.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Subroutine, function
-
-@item @emph{Syntax}:
-@multitable @columnfractions .80
-@item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])}
-@item @code{STATUS = SYMLNK(PATH1, PATH2)}
-@end multitable
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
-@item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
-@item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
-@end multitable
-
-@item @emph{See also}:
-@ref{LINK}, @gol
-@ref{UNLINK}
-@end table
-
-
-
-@node SYSTEM
-@section @code{SYSTEM} --- Execute a shell command
-@fnindex SYSTEM
-@cindex system, system call
-
-@table @asis
-@item @emph{Description}:
-Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If
-argument @var{STATUS} is present, it contains the value returned by
-@code{system(3)}, which is presumably 0 if the shell command succeeded.
-Note that which shell is used to invoke the command is system-dependent
-and environment-dependent.
-
-This intrinsic is provided in both subroutine and function forms;
-however, only one form can be used in any given program unit.
-
-Note that the @code{system} function need not be thread-safe. It is
-the responsibility of the user to ensure that @code{system} is not
-called concurrently.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Subroutine, function
-
-@item @emph{Syntax}:
-@multitable @columnfractions .80
-@item @code{CALL SYSTEM(COMMAND [, STATUS])}
-@item @code{STATUS = SYSTEM(COMMAND)}
-@end multitable
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type.
-@item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
-@end multitable
-
-@item @emph{See also}:
-@ref{EXECUTE_COMMAND_LINE}, which is part of the Fortran 2008 standard
-and should considered in new code for future portability.
-@end table
-
-
-
-@node SYSTEM_CLOCK
-@section @code{SYSTEM_CLOCK} --- Time function
-@fnindex SYSTEM_CLOCK
-@cindex time, clock ticks
-@cindex clock ticks
-
-@table @asis
-@item @emph{Description}:
-Determines the @var{COUNT} of a processor clock since an unspecified
-time in the past modulo @var{COUNT_MAX}, @var{COUNT_RATE} determines
-the number of clock ticks per second. If the platform supports a
-monotonic clock, that clock is used and can, depending on the platform
-clock implementation, provide up to nanosecond resolution. If a
-monotonic clock is not available, the implementation falls back to a
-realtime clock.
-
-@var{COUNT_RATE} is system dependent and can vary depending on the kind of
-the arguments. For @var{kind=4} arguments (and smaller integer kinds),
-@var{COUNT} represents milliseconds, while for @var{kind=8} arguments (and
-larger integer kinds), @var{COUNT} typically represents micro- or
-nanoseconds depending on resolution of the underlying platform clock.
-@var{COUNT_MAX} usually equals @code{HUGE(COUNT_MAX)}. Note that the
-millisecond resolution of the @var{kind=4} version implies that the
-@var{COUNT} will wrap around in roughly 25 days. In order to avoid issues
-with the wrap around and for more precise timing, please use the
-@var{kind=8} version.
-
-If there is no clock, or querying the clock fails, @var{COUNT} is set
-to @code{-HUGE(COUNT)}, and @var{COUNT_RATE} and @var{COUNT_MAX} are
-set to zero.
-
-When running on a platform using the GNU C library (glibc) version
-2.16 or older, or a derivative thereof, the high resolution monotonic
-clock is available only when linking with the @var{rt} library. This
-can be done explicitly by adding the @code{-lrt} flag when linking the
-application, but is also done implicitly when using OpenMP.
-
-On the Windows platform, the version with @var{kind=4} arguments uses
-the @code{GetTickCount} function, whereas the @var{kind=8} version
-uses @code{QueryPerformanceCounter} and
-@code{QueryPerformanceCounterFrequency}. For more information, and
-potential caveats, please see the platform documentation.
-
-@item @emph{Standard}:
-Fortran 90 and later
-
-@item @emph{Class}:
-Subroutine
-
-@item @emph{Syntax}:
-@code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .20 .65
-@item @var{COUNT} @tab (Optional) shall be a scalar of type
-@code{INTEGER} with @code{INTENT(OUT)}.
-@item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type
-@code{INTEGER} or @code{REAL}, with @code{INTENT(OUT)}.
-@item @var{COUNT_MAX} @tab (Optional) shall be a scalar of type
-@code{INTEGER} with @code{INTENT(OUT)}.
-@end multitable
-
-@item @emph{Example}:
-@smallexample
-PROGRAM test_system_clock
- INTEGER :: count, count_rate, count_max
- CALL SYSTEM_CLOCK(count, count_rate, count_max)
- WRITE(*,*) count, count_rate, count_max
-END PROGRAM
-@end smallexample
-
-@item @emph{See also}:
-@ref{DATE_AND_TIME}, @gol
-@ref{CPU_TIME}
-@end table
-
-
-
-@node TAN
-@section @code{TAN} --- Tangent function
-@fnindex TAN
-@fnindex DTAN
-@cindex trigonometric function, tangent
-@cindex tangent
-
-@table @asis
-@item @emph{Description}:
-@code{TAN(X)} computes the tangent of @var{X}.
-
-@item @emph{Standard}:
-Fortran 77 and later, for a complex argument Fortran 2008 or later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = TAN(X)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
-@end multitable
-
-@item @emph{Return value}:
-The return value has same type and kind as @var{X}, and its value is in radians.
-
-@item @emph{Example}:
-@smallexample
-program test_tan
- real(8) :: x = 0.165_8
- x = tan(x)
-end program test_tan
-@end smallexample
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .23 .20 .33
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{TAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
-@item @code{DTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
-@end multitable
-
-@item @emph{See also}:
-Inverse function: @gol
-@ref{ATAN} @gol
-Degrees function: @gol
-@ref{TAND}
-@end table
-
-
-
-@node TAND
-@section @code{TAND} --- Tangent function, degrees
-@fnindex TAND
-@fnindex DTAND
-@cindex trigonometric function, tangent, degrees
-@cindex tangent, degrees
-
-@table @asis
-@item @emph{Description}:
-@code{TAND(X)} computes the tangent of @var{X} in degrees.
-
-This function is for compatibility only and should be avoided in favor of
-standard constructs wherever possible.
-
-@item @emph{Standard}:
-GNU extension, enabled with @option{-fdec-math}.
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = TAND(X)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
-@end multitable
-
-@item @emph{Return value}:
-The return value has same type and kind as @var{X}, and its value is in degrees.
-
-@item @emph{Example}:
-@smallexample
-program test_tand
- real(8) :: x = 0.165_8
- x = tand(x)
-end program test_tand
-@end smallexample
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .23 .20 .33
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{TAND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension
-@item @code{DTAND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
-@end multitable
-
-@item @emph{See also}:
-Inverse function: @gol
-@ref{ATAND} @gol
-Radians function: @gol
-@ref{TAN}
-@end table
-
-
-
-@node TANH
-@section @code{TANH} --- Hyperbolic tangent function
-@fnindex TANH
-@fnindex DTANH
-@cindex hyperbolic tangent
-@cindex hyperbolic function, tangent
-@cindex tangent, hyperbolic
-
-@table @asis
-@item @emph{Description}:
-@code{TANH(X)} computes the hyperbolic tangent of @var{X}.
-
-@item @emph{Standard}:
-Fortran 77 and later, for a complex argument Fortran 2008 or later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{X = TANH(X)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
-@end multitable
-
-@item @emph{Return value}:
-The return value has same type and kind as @var{X}. If @var{X} is
-complex, the imaginary part of the result is in radians. If @var{X}
-is @code{REAL}, the return value lies in the range
-@math{ - 1 \leq tanh(x) \leq 1 }.
-
-@item @emph{Example}:
-@smallexample
-program test_tanh
- real(8) :: x = 2.1_8
- x = tanh(x)
-end program test_tanh
-@end smallexample
-
-@item @emph{Specific names}:
-@multitable @columnfractions .20 .23 .20 .33
-@headitem Name @tab Argument @tab Return type @tab Standard
-@item @code{TANH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
-@item @code{DTANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
-@end multitable
-
-@item @emph{See also}:
-@ref{ATANH}
-@end table
-
-
-
-@node THIS_IMAGE
-@section @code{THIS_IMAGE} --- Function that returns the cosubscript index of this image
-@fnindex THIS_IMAGE
-@cindex coarray, @code{THIS_IMAGE}
-@cindex images, index of this image
-
-@table @asis
-@item @emph{Description}:
-Returns the cosubscript for this image.
-
-@item @emph{Standard}:
-Fortran 2008 and later. With @var{DISTANCE} argument,
-Technical Specification (TS) 18508 or later
-
-@item @emph{Class}:
-Transformational function
-
-@item @emph{Syntax}:
-@multitable @columnfractions .80
-@item @code{RESULT = THIS_IMAGE()}
-@item @code{RESULT = THIS_IMAGE(DISTANCE)}
-@item @code{RESULT = THIS_IMAGE(COARRAY [, DIM])}
-@end multitable
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{DISTANCE} @tab (optional, intent(in)) Nonnegative scalar integer
-(not permitted together with @var{COARRAY}).
-@item @var{COARRAY} @tab Coarray of any type (optional; if @var{DIM}
-present, required).
-@item @var{DIM} @tab default integer scalar (optional). If present,
-@var{DIM} shall be between one and the corank of @var{COARRAY}.
-@end multitable
-
-
-@item @emph{Return value}:
-Default integer. If @var{COARRAY} is not present, it is scalar; if
-@var{DISTANCE} is not present or has value 0, its value is the image index on
-the invoking image for the current team, for values smaller or equal
-distance to the initial team, it returns the image index on the ancestor team
-which has a distance of @var{DISTANCE} from the invoking team. If
-@var{DISTANCE} is larger than the distance to the initial team, the image
-index of the initial team is returned. Otherwise when the @var{COARRAY} is
-present, if @var{DIM} is not present, a rank-1 array with corank elements is
-returned, containing the cosubscripts for @var{COARRAY} specifying the invoking
-image. If @var{DIM} is present, a scalar is returned, with the value of
-the @var{DIM} element of @code{THIS_IMAGE(COARRAY)}.
-
-@item @emph{Example}:
-@smallexample
-INTEGER :: value[*]
-INTEGER :: i
-value = THIS_IMAGE()
-SYNC ALL
-IF (THIS_IMAGE() == 1) THEN
- DO i = 1, NUM_IMAGES()
- WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
- END DO
-END IF
-
-! Check whether the current image is the initial image
-IF (THIS_IMAGE(HUGE(1)) /= THIS_IMAGE())
- error stop "something is rotten here"
-@end smallexample
-
-@item @emph{See also}:
-@ref{NUM_IMAGES}, @gol
-@ref{IMAGE_INDEX}
-@end table
-
-
-
-@node TIME
-@section @code{TIME} --- Time function
-@fnindex TIME
-@cindex time, current
-@cindex current time
-
-@table @asis
-@item @emph{Description}:
-Returns the current time encoded as an integer (in the manner of the
-function @code{time(3)} in the C standard library). This value is
-suitable for passing to @ref{CTIME}, @ref{GMTIME}, and @ref{LTIME}.
-
-This intrinsic is not fully portable, such as to systems with 32-bit
-@code{INTEGER} types but supporting times wider than 32 bits. Therefore,
-the values returned by this intrinsic might be, or become, negative, or
-numerically less than previous values, during a single run of the
-compiled program.
-
-See @ref{TIME8}, for information on a similar intrinsic that might be
-portable to more GNU Fortran implementations, though to fewer Fortran
-compilers.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Function
-
-@item @emph{Syntax}:
-@code{RESULT = TIME()}
-
-@item @emph{Return value}:
-The return value is a scalar of type @code{INTEGER(4)}.
-
-@item @emph{See also}:
-@ref{DATE_AND_TIME}, @gol
-@ref{CTIME}, @gol
-@ref{GMTIME}, @gol
-@ref{LTIME}, @gol
-@ref{MCLOCK}, @gol
-@ref{TIME8}
-@end table
-
-
-
-@node TIME8
-@section @code{TIME8} --- Time function (64-bit)
-@fnindex TIME8
-@cindex time, current
-@cindex current time
-
-@table @asis
-@item @emph{Description}:
-Returns the current time encoded as an integer (in the manner of the
-function @code{time(3)} in the C standard library). This value is
-suitable for passing to @ref{CTIME}, @ref{GMTIME}, and @ref{LTIME}.
-
-@emph{Warning:} this intrinsic does not increase the range of the timing
-values over that returned by @code{time(3)}. On a system with a 32-bit
-@code{time(3)}, @code{TIME8} will return a 32-bit value, even though
-it is converted to a 64-bit @code{INTEGER(8)} value. That means
-overflows of the 32-bit value can still occur. Therefore, the values
-returned by this intrinsic might be or become negative or numerically
-less than previous values during a single run of the compiled program.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Function
-
-@item @emph{Syntax}:
-@code{RESULT = TIME8()}
-
-@item @emph{Return value}:
-The return value is a scalar of type @code{INTEGER(8)}.
-
-@item @emph{See also}:
-@ref{DATE_AND_TIME}, @gol
-@ref{CTIME}, @gol
-@ref{GMTIME}, @gol
-@ref{LTIME}, @gol
-@ref{MCLOCK8}, @gol
-@ref{TIME}
-@end table
-
-
-
-@node TINY
-@section @code{TINY} --- Smallest positive number of a real kind
-@fnindex TINY
-@cindex limits, smallest number
-@cindex model representation, smallest number
-
-@table @asis
-@item @emph{Description}:
-@code{TINY(X)} returns the smallest positive (non zero) number
-in the model of the type of @code{X}.
-
-@item @emph{Standard}:
-Fortran 90 and later
-
-@item @emph{Class}:
-Inquiry function
-
-@item @emph{Syntax}:
-@code{RESULT = TINY(X)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{X} @tab Shall be of type @code{REAL}.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of the same type and kind as @var{X}
-
-@item @emph{Example}:
-See @code{HUGE} for an example.
-@end table
-
-
-
-@node TRAILZ
-@section @code{TRAILZ} --- Number of trailing zero bits of an integer
-@fnindex TRAILZ
-@cindex zero bits
-
-@table @asis
-@item @emph{Description}:
-@code{TRAILZ} returns the number of trailing zero bits of an integer.
-
-@item @emph{Standard}:
-Fortran 2008 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = TRAILZ(I)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{I} @tab Shall be of type @code{INTEGER}.
-@end multitable
-
-@item @emph{Return value}:
-The type of the return value is the default @code{INTEGER}.
-If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
-
-@item @emph{Example}:
-@smallexample
-PROGRAM test_trailz
- WRITE (*,*) TRAILZ(8) ! prints 3
-END PROGRAM
-@end smallexample
-
-@item @emph{See also}:
-@ref{BIT_SIZE}, @gol
-@ref{LEADZ}, @gol
-@ref{POPPAR}, @gol
-@ref{POPCNT}
-@end table
-
-
-
-@node TRANSFER
-@section @code{TRANSFER} --- Transfer bit patterns
-@fnindex TRANSFER
-@cindex bits, move
-@cindex type cast
-
-@table @asis
-@item @emph{Description}:
-Interprets the bitwise representation of @var{SOURCE} in memory as if it
-is the representation of a variable or array of the same type and type
-parameters as @var{MOLD}.
-
-This is approximately equivalent to the C concept of @emph{casting} one
-type to another.
-
-@item @emph{Standard}:
-Fortran 90 and later
-
-@item @emph{Class}:
-Transformational function
-
-@item @emph{Syntax}:
-@code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{SOURCE} @tab Shall be a scalar or an array of any type.
-@item @var{MOLD} @tab Shall be a scalar or an array of any type.
-@item @var{SIZE} @tab (Optional) shall be a scalar of type
-@code{INTEGER}.
-@end multitable
-
-@item @emph{Return value}:
-The result has the same type as @var{MOLD}, with the bit level
-representation of @var{SOURCE}. If @var{SIZE} is present, the result is
-a one-dimensional array of length @var{SIZE}. If @var{SIZE} is absent
-but @var{MOLD} is an array (of any size or shape), the result is a one-
-dimensional array of the minimum length needed to contain the entirety
-of the bitwise representation of @var{SOURCE}. If @var{SIZE} is absent
-and @var{MOLD} is a scalar, the result is a scalar.
-
-If the bitwise representation of the result is longer than that of
-@var{SOURCE}, then the leading bits of the result correspond to those of
-@var{SOURCE} and any trailing bits are filled arbitrarily.
-
-When the resulting bit representation does not correspond to a valid
-representation of a variable of the same type as @var{MOLD}, the results
-are undefined, and subsequent operations on the result cannot be
-guaranteed to produce sensible behavior. For example, it is possible to
-create @code{LOGICAL} variables for which @code{@var{VAR}} and
-@code{.NOT.@var{VAR}} both appear to be true.
-
-@item @emph{Example}:
-@smallexample
-PROGRAM test_transfer
- integer :: x = 2143289344
- print *, transfer(x, 1.0) ! prints "NaN" on i686
-END PROGRAM
-@end smallexample
-@end table
-
-
-
-@node TRANSPOSE
-@section @code{TRANSPOSE} --- Transpose an array of rank two
-@fnindex TRANSPOSE
-@cindex array, transpose
-@cindex matrix, transpose
-@cindex transpose
-
-@table @asis
-@item @emph{Description}:
-Transpose an array of rank two. Element (i, j) of the result has the value
-@code{MATRIX(j, i)}, for all i, j.
-
-@item @emph{Standard}:
-Fortran 90 and later
-
-@item @emph{Class}:
-Transformational function
-
-@item @emph{Syntax}:
-@code{RESULT = TRANSPOSE(MATRIX)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{MATRIX} @tab Shall be an array of any type and have a rank of two.
-@end multitable
-
-@item @emph{Return value}:
-The result has the same type as @var{MATRIX}, and has shape
-@code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}.
-@end table
-
-
-
-@node TRIM
-@section @code{TRIM} --- Remove trailing blank characters of a string
-@fnindex TRIM
-@cindex string, remove trailing whitespace
-
-@table @asis
-@item @emph{Description}:
-Removes trailing blank characters of a string.
-
-@item @emph{Standard}:
-Fortran 90 and later
-
-@item @emph{Class}:
-Transformational function
-
-@item @emph{Syntax}:
-@code{RESULT = TRIM(STRING)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}.
-@end multitable
-
-@item @emph{Return value}:
-A scalar of type @code{CHARACTER} which length is that of @var{STRING}
-less the number of trailing blanks.
-
-@item @emph{Example}:
-@smallexample
-PROGRAM test_trim
- CHARACTER(len=10), PARAMETER :: s = "GFORTRAN "
- WRITE(*,*) LEN(s), LEN(TRIM(s)) ! "10 8", with/without trailing blanks
-END PROGRAM
-@end smallexample
-
-@item @emph{See also}:
-@ref{ADJUSTL}, @gol
-@ref{ADJUSTR}
-@end table
-
-
-
-@node TTYNAM
-@section @code{TTYNAM} --- Get the name of a terminal device
-@fnindex TTYNAM
-@cindex system, terminal
-
-@table @asis
-@item @emph{Description}:
-Get the name of a terminal device. For more information,
-see @code{ttyname(3)}.
-
-This intrinsic is provided in both subroutine and function forms;
-however, only one form can be used in any given program unit.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Subroutine, function
-
-@item @emph{Syntax}:
-@multitable @columnfractions .80
-@item @code{CALL TTYNAM(UNIT, NAME)}
-@item @code{NAME = TTYNAM(UNIT)}
-@end multitable
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
-@item @var{NAME} @tab Shall be of type @code{CHARACTER}.
-@end multitable
-
-@item @emph{Example}:
-@smallexample
-PROGRAM test_ttynam
- INTEGER :: unit
- DO unit = 1, 10
- IF (isatty(unit=unit)) write(*,*) ttynam(unit)
- END DO
-END PROGRAM
-@end smallexample
-
-@item @emph{See also}:
-@ref{ISATTY}
-@end table
-
-
-
-@node UBOUND
-@section @code{UBOUND} --- Upper dimension bounds of an array
-@fnindex UBOUND
-@cindex array, upper bound
-
-@table @asis
-@item @emph{Description}:
-Returns the upper bounds of an array, or a single upper bound
-along the @var{DIM} dimension.
-@item @emph{Standard}:
-Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later
-
-@item @emph{Class}:
-Inquiry function
-
-@item @emph{Syntax}:
-@code{RESULT = UBOUND(ARRAY [, DIM [, KIND]])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{ARRAY} @tab Shall be an array, of any type.
-@item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
-@item @var{KIND}@tab (Optional) An @code{INTEGER} initialization
-expression indicating the kind parameter of the result.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{INTEGER} and of kind @var{KIND}. If
-@var{KIND} is absent, the return value is of default integer kind.
-If @var{DIM} is absent, the result is an array of the upper bounds of
-@var{ARRAY}. If @var{DIM} is present, the result is a scalar
-corresponding to the upper bound of the array along that dimension. If
-@var{ARRAY} is an expression rather than a whole array or array
-structure component, or if it has a zero extent along the relevant
-dimension, the upper bound is taken to be the number of elements along
-the relevant dimension.
-
-@item @emph{See also}:
-@ref{LBOUND}, @gol
-@ref{LCOBOUND}
-@end table
-
-
-
-@node UCOBOUND
-@section @code{UCOBOUND} --- Upper codimension bounds of an array
-@fnindex UCOBOUND
-@cindex coarray, upper bound
-
-@table @asis
-@item @emph{Description}:
-Returns the upper cobounds of a coarray, or a single upper cobound
-along the @var{DIM} codimension.
-@item @emph{Standard}:
-Fortran 2008 and later
-
-@item @emph{Class}:
-Inquiry function
-
-@item @emph{Syntax}:
-@code{RESULT = UCOBOUND(COARRAY [, DIM [, KIND]])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{ARRAY} @tab Shall be an coarray, of any type.
-@item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
-@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
-expression indicating the kind parameter of the result.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{INTEGER} and of kind @var{KIND}. If
-@var{KIND} is absent, the return value is of default integer kind.
-If @var{DIM} is absent, the result is an array of the lower cobounds of
-@var{COARRAY}. If @var{DIM} is present, the result is a scalar
-corresponding to the lower cobound of the array along that codimension.
-
-@item @emph{See also}:
-@ref{LCOBOUND}, @gol
-@ref{LBOUND}
-@end table
-
-
-
-@node UMASK
-@section @code{UMASK} --- Set the file creation mask
-@fnindex UMASK
-@cindex file system, file creation mask
-
-@table @asis
-@item @emph{Description}:
-Sets the file creation mask to @var{MASK}. If called as a function, it
-returns the old value. If called as a subroutine and argument @var{OLD}
-if it is supplied, it is set to the old value. See @code{umask(2)}.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Subroutine, function
-
-@item @emph{Syntax}:
-@multitable @columnfractions .80
-@item @code{CALL UMASK(MASK [, OLD])}
-@item @code{OLD = UMASK(MASK)}
-@end multitable
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{MASK} @tab Shall be a scalar of type @code{INTEGER}.
-@item @var{OLD} @tab (Optional) Shall be a scalar of type
-@code{INTEGER}.
-@end multitable
-
-@end table
-
-
-
-@node UNLINK
-@section @code{UNLINK} --- Remove a file from the file system
-@fnindex UNLINK
-@cindex file system, remove file
-
-@table @asis
-@item @emph{Description}:
-Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be
-used to mark the end of the name in @var{PATH}; otherwise, trailing
-blanks in the file name are ignored. If the @var{STATUS} argument is
-supplied, it contains 0 on success or a nonzero error code upon return;
-see @code{unlink(2)}.
-
-This intrinsic is provided in both subroutine and function forms;
-however, only one form can be used in any given program unit.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Subroutine, function
-
-@item @emph{Syntax}:
-@multitable @columnfractions .80
-@item @code{CALL UNLINK(PATH [, STATUS])}
-@item @code{STATUS = UNLINK(PATH)}
-@end multitable
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{PATH} @tab Shall be of default @code{CHARACTER} type.
-@item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
-@end multitable
-
-@item @emph{See also}:
-@ref{LINK}, @gol
-@ref{SYMLNK}
-@end table
-
-
-
-@node UNPACK
-@section @code{UNPACK} --- Unpack an array of rank one into an array
-@fnindex UNPACK
-@cindex array, unpacking
-@cindex array, increase dimension
-@cindex array, scatter elements
-
-@table @asis
-@item @emph{Description}:
-Store the elements of @var{VECTOR} in an array of higher rank.
-
-@item @emph{Standard}:
-Fortran 90 and later
-
-@item @emph{Class}:
-Transformational function
-
-@item @emph{Syntax}:
-@code{RESULT = UNPACK(VECTOR, MASK, FIELD)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{VECTOR} @tab Shall be an array of any type and rank one. It
-shall have at least as many elements as @var{MASK} has @code{TRUE} values.
-@item @var{MASK} @tab Shall be an array of type @code{LOGICAL}.
-@item @var{FIELD} @tab Shall be of the same type as @var{VECTOR} and have
-the same shape as @var{MASK}.
-@end multitable
-
-@item @emph{Return value}:
-The resulting array corresponds to @var{FIELD} with @code{TRUE} elements
-of @var{MASK} replaced by values from @var{VECTOR} in array element order.
-
-@item @emph{Example}:
-@smallexample
-PROGRAM test_unpack
- integer :: vector(2) = (/1,1/)
- logical :: mask(4) = (/ .TRUE., .FALSE., .FALSE., .TRUE. /)
- integer :: field(2,2) = 0, unity(2,2)
-
- ! result: unity matrix
- unity = unpack(vector, reshape(mask, (/2,2/)), field)
-END PROGRAM
-@end smallexample
-
-@item @emph{See also}:
-@ref{PACK}, @gol
-@ref{SPREAD}
-@end table
-
-
-
-@node VERIFY
-@section @code{VERIFY} --- Scan a string for characters not a given set
-@fnindex VERIFY
-@cindex string, find missing set
-
-@table @asis
-@item @emph{Description}:
-Verifies that all the characters in @var{STRING} belong to the set of
-characters in @var{SET}.
-
-If @var{BACK} is either absent or equals @code{FALSE}, this function
-returns the position of the leftmost character of @var{STRING} that is
-not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost
-position is returned. If all characters of @var{STRING} are found in
-@var{SET}, the result is zero.
-
-@item @emph{Standard}:
-Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later
-
-@item @emph{Class}:
-Elemental function
-
-@item @emph{Syntax}:
-@code{RESULT = VERIFY(STRING, SET[, BACK [, KIND]])}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{STRING} @tab Shall be of type @code{CHARACTER}.
-@item @var{SET} @tab Shall be of type @code{CHARACTER}.
-@item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
-@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
-expression indicating the kind parameter of the result.
-@end multitable
-
-@item @emph{Return value}:
-The return value is of type @code{INTEGER} and of kind @var{KIND}. If
-@var{KIND} is absent, the return value is of default integer kind.
-
-@item @emph{Example}:
-@smallexample
-PROGRAM test_verify
- WRITE(*,*) VERIFY("FORTRAN", "AO") ! 1, found 'F'
- WRITE(*,*) VERIFY("FORTRAN", "FOO") ! 3, found 'R'
- WRITE(*,*) VERIFY("FORTRAN", "C++") ! 1, found 'F'
- WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.) ! 7, found 'N'
- WRITE(*,*) VERIFY("FORTRAN", "FORTRAN") ! 0' found none
-END PROGRAM
-@end smallexample
-
-@item @emph{See also}:
-@ref{SCAN}, @gol
-@ref{INDEX intrinsic}
-@end table
-
-
-
-@node XOR
-@section @code{XOR} --- Bitwise logical exclusive OR
-@fnindex XOR
-@cindex bitwise logical exclusive or
-@cindex logical exclusive or, bitwise
-
-@table @asis
-@item @emph{Description}:
-Bitwise logical exclusive or.
-
-This intrinsic routine is provided for backwards compatibility with
-GNU Fortran 77. For integer arguments, programmers should consider
-the use of the @ref{IEOR} intrinsic and for logical arguments the
-@code{.NEQV.} operator, which are both defined by the Fortran standard.
-
-@item @emph{Standard}:
-GNU extension
-
-@item @emph{Class}:
-Function
-
-@item @emph{Syntax}:
-@code{RESULT = XOR(I, J)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{I} @tab The type shall be either a scalar @code{INTEGER}
-type or a scalar @code{LOGICAL} type or a boz-literal-constant.
-@item @var{J} @tab The type shall be the same as the type of @var{I} or
-a boz-literal-constant. @var{I} and @var{J} shall not both be
-boz-literal-constants. If either @var{I} and @var{J} is a
-boz-literal-constant, then the other argument must be a scalar @code{INTEGER}.
-@end multitable
-
-@item @emph{Return value}:
-The return type is either a scalar @code{INTEGER} or a scalar
-@code{LOGICAL}. If the kind type parameters differ, then the
-smaller kind type is implicitly converted to larger kind, and the
-return has the larger kind. A boz-literal-constant is
-converted to an @code{INTEGER} with the kind type parameter of
-the other argument as-if a call to @ref{INT} occurred.
-
-@item @emph{Example}:
-@smallexample
-PROGRAM test_xor
- LOGICAL :: T = .TRUE., F = .FALSE.
- INTEGER :: a, b
- DATA a / Z'F' /, b / Z'3' /
-
- WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F)
- WRITE (*,*) XOR(a, b)
-END PROGRAM
-@end smallexample
-
-@item @emph{See also}:
-Fortran 95 elemental function: @gol
-@ref{IEOR}
-@end table
-
-
-
-@node Intrinsic Modules
-@chapter Intrinsic Modules
-@cindex intrinsic Modules
-
-@menu
-* ISO_FORTRAN_ENV::
-* ISO_C_BINDING::
-* IEEE modules::
-* OpenMP Modules OMP_LIB and OMP_LIB_KINDS::
-* OpenACC Module OPENACC::
-@end menu
-
-@node ISO_FORTRAN_ENV
-@section @code{ISO_FORTRAN_ENV}
-@table @asis
-@item @emph{Standard}:
-Fortran 2003 and later, except when otherwise noted
-@end table
-
-The @code{ISO_FORTRAN_ENV} module provides the following scalar default-integer
-named constants:
-
-@table @asis
-@item @code{ATOMIC_INT_KIND}:
-Default-kind integer constant to be used as kind parameter when defining
-integer variables used in atomic operations. (Fortran 2008 or later.)
-
-@item @code{ATOMIC_LOGICAL_KIND}:
-Default-kind integer constant to be used as kind parameter when defining
-logical variables used in atomic operations. (Fortran 2008 or later.)
-
-@item @code{CHARACTER_KINDS}:
-Default-kind integer constant array of rank one containing the supported kind
-parameters of the @code{CHARACTER} type. (Fortran 2008 or later.)
-
-@item @code{CHARACTER_STORAGE_SIZE}:
-Size in bits of the character storage unit.
-
-@item @code{ERROR_UNIT}:
-Identifies the preconnected unit used for error reporting.
-
-@item @code{FILE_STORAGE_SIZE}:
-Size in bits of the file-storage unit.
-
-@item @code{INPUT_UNIT}:
-Identifies the preconnected unit identified by the asterisk
-(@code{*}) in @code{READ} statement.
-
-@item @code{INT8}, @code{INT16}, @code{INT32}, @code{INT64}:
-Kind type parameters to specify an INTEGER type with a storage
-size of 16, 32, and 64 bits. It is negative if a target platform
-does not support the particular kind. (Fortran 2008 or later.)
-
-@item @code{INTEGER_KINDS}:
-Default-kind integer constant array of rank one containing the supported kind
-parameters of the @code{INTEGER} type. (Fortran 2008 or later.)
-
-@item @code{IOSTAT_END}:
-The value assigned to the variable passed to the @code{IOSTAT=} specifier of
-an input/output statement if an end-of-file condition occurred.
-
-@item @code{IOSTAT_EOR}:
-The value assigned to the variable passed to the @code{IOSTAT=} specifier of
-an input/output statement if an end-of-record condition occurred.
-
-@item @code{IOSTAT_INQUIRE_INTERNAL_UNIT}:
-Scalar default-integer constant, used by @code{INQUIRE} for the
-@code{IOSTAT=} specifier to denote an that a unit number identifies an
-internal unit. (Fortran 2008 or later.)
-
-@item @code{NUMERIC_STORAGE_SIZE}:
-The size in bits of the numeric storage unit.
-
-@item @code{LOGICAL_KINDS}:
-Default-kind integer constant array of rank one containing the supported kind
-parameters of the @code{LOGICAL} type. (Fortran 2008 or later.)
-
-@item @code{OUTPUT_UNIT}:
-Identifies the preconnected unit identified by the asterisk
-(@code{*}) in @code{WRITE} statement.
-
-@item @code{REAL32}, @code{REAL64}, @code{REAL128}:
-Kind type parameters to specify a REAL type with a storage
-size of 32, 64, and 128 bits. It is negative if a target platform
-does not support the particular kind. (Fortran 2008 or later.)
-
-@item @code{REAL_KINDS}:
-Default-kind integer constant array of rank one containing the supported kind
-parameters of the @code{REAL} type. (Fortran 2008 or later.)
-
-@item @code{STAT_LOCKED}:
-Scalar default-integer constant used as STAT= return value by @code{LOCK} to
-denote that the lock variable is locked by the executing image. (Fortran 2008
-or later.)
-
-@item @code{STAT_LOCKED_OTHER_IMAGE}:
-Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
-denote that the lock variable is locked by another image. (Fortran 2008 or
-later.)
-
-@item @code{STAT_STOPPED_IMAGE}:
-Positive, scalar default-integer constant used as STAT= return value if the
-argument in the statement requires synchronisation with an image, which has
-initiated the termination of the execution. (Fortran 2008 or later.)
-
-@item @code{STAT_FAILED_IMAGE}:
-Positive, scalar default-integer constant used as STAT= return value if the
-argument in the statement requires communication with an image, which has
-is in the failed state. (TS 18508 or later.)
-
-@item @code{STAT_UNLOCKED}:
-Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
-denote that the lock variable is unlocked. (Fortran 2008 or later.)
-@end table
-
-The module provides the following derived type:
-
-@table @asis
-@item @code{LOCK_TYPE}:
-Derived type with private components to be use with the @code{LOCK} and
-@code{UNLOCK} statement. A variable of its type has to be always declared
-as coarray and may not appear in a variable-definition context.
-(Fortran 2008 or later.)
-@end table
-
-The module also provides the following intrinsic procedures:
-@ref{COMPILER_OPTIONS} and @ref{COMPILER_VERSION}.
-
-
-
-@node ISO_C_BINDING
-@section @code{ISO_C_BINDING}
-@table @asis
-@item @emph{Standard}:
-Fortran 2003 and later, GNU extensions
-@end table
-
-The following intrinsic procedures are provided by the module; their
-definition can be found in the section Intrinsic Procedures of this
-manual.
-
-@table @asis
-@item @code{C_ASSOCIATED}
-@item @code{C_F_POINTER}
-@item @code{C_F_PROCPOINTER}
-@item @code{C_FUNLOC}
-@item @code{C_LOC}
-@item @code{C_SIZEOF}
-@end table
-@c TODO: Vertical spacing between C_FUNLOC and C_LOC wrong in PDF,
-@c don't really know why.
-
-The @code{ISO_C_BINDING} module provides the following named constants of
-type default integer, which can be used as KIND type parameters.
-
-In addition to the integer named constants required by the Fortran 2003
-standard and @code{C_PTRDIFF_T} of TS 29113, GNU Fortran provides as an
-extension named constants for the 128-bit integer types supported by the
-C compiler: @code{C_INT128_T, C_INT_LEAST128_T, C_INT_FAST128_T}.
-Furthermore, if @code{_Float128} is supported in C, the named constants
-@code{C_FLOAT128} and @code{C_FLOAT128_COMPLEX} are defined.
-
-@multitable @columnfractions .19 .32 .34 .15
-@headitem Fortran Type @tab Named constant @tab C type @tab Extension
-@item @code{INTEGER}@tab @code{C_INT} @tab @code{int}
-@item @code{INTEGER}@tab @code{C_SHORT} @tab @code{short int}
-@item @code{INTEGER}@tab @code{C_LONG} @tab @code{long int}
-@item @code{INTEGER}@tab @code{C_LONG_LONG} @tab @code{long long int}
-@item @code{INTEGER}@tab @code{C_SIGNED_CHAR} @tab @code{signed char}/@code{unsigned char}
-@item @code{INTEGER}@tab @code{C_SIZE_T} @tab @code{size_t}
-@item @code{INTEGER}@tab @code{C_INT8_T} @tab @code{int8_t}
-@item @code{INTEGER}@tab @code{C_INT16_T} @tab @code{int16_t}
-@item @code{INTEGER}@tab @code{C_INT32_T} @tab @code{int32_t}
-@item @code{INTEGER}@tab @code{C_INT64_T} @tab @code{int64_t}
-@item @code{INTEGER}@tab @code{C_INT128_T} @tab @code{int128_t} @tab Ext.
-@item @code{INTEGER}@tab @code{C_INT_LEAST8_T} @tab @code{int_least8_t}
-@item @code{INTEGER}@tab @code{C_INT_LEAST16_T} @tab @code{int_least16_t}
-@item @code{INTEGER}@tab @code{C_INT_LEAST32_T} @tab @code{int_least32_t}
-@item @code{INTEGER}@tab @code{C_INT_LEAST64_T} @tab @code{int_least64_t}
-@item @code{INTEGER}@tab @code{C_INT_LEAST128_T}@tab @code{int_least128_t} @tab Ext.
-@item @code{INTEGER}@tab @code{C_INT_FAST8_T} @tab @code{int_fast8_t}
-@item @code{INTEGER}@tab @code{C_INT_FAST16_T} @tab @code{int_fast16_t}
-@item @code{INTEGER}@tab @code{C_INT_FAST32_T} @tab @code{int_fast32_t}
-@item @code{INTEGER}@tab @code{C_INT_FAST64_T} @tab @code{int_fast64_t}
-@item @code{INTEGER}@tab @code{C_INT_FAST128_T} @tab @code{int_fast128_t} @tab Ext.
-@item @code{INTEGER}@tab @code{C_INTMAX_T} @tab @code{intmax_t}
-@item @code{INTEGER}@tab @code{C_INTPTR_T} @tab @code{intptr_t}
-@item @code{INTEGER}@tab @code{C_PTRDIFF_T} @tab @code{ptrdiff_t} @tab TS 29113
-@item @code{REAL} @tab @code{C_FLOAT} @tab @code{float}
-@item @code{REAL} @tab @code{C_DOUBLE} @tab @code{double}
-@item @code{REAL} @tab @code{C_LONG_DOUBLE} @tab @code{long double}
-@item @code{REAL} @tab @code{C_FLOAT128} @tab @code{_Float128} @tab Ext.
-@item @code{COMPLEX}@tab @code{C_FLOAT_COMPLEX} @tab @code{float _Complex}
-@item @code{COMPLEX}@tab @code{C_DOUBLE_COMPLEX}@tab @code{double _Complex}
-@item @code{COMPLEX}@tab @code{C_LONG_DOUBLE_COMPLEX}@tab @code{long double _Complex}
-@item @code{COMPLEX}@tab @code{C_FLOAT128_COMPLEX} @tab @code{_Float128 _Complex} @tab Ext.
-@item @code{LOGICAL}@tab @code{C_BOOL} @tab @code{_Bool}
-@item @code{CHARACTER}@tab @code{C_CHAR} @tab @code{char}
-@end multitable
-
-Additionally, the following parameters of type @code{CHARACTER(KIND=C_CHAR)}
-are defined.
-
-@multitable @columnfractions .20 .45 .15
-@headitem Name @tab C definition @tab Value
-@item @code{C_NULL_CHAR} @tab null character @tab @code{'\0'}
-@item @code{C_ALERT} @tab alert @tab @code{'\a'}
-@item @code{C_BACKSPACE} @tab backspace @tab @code{'\b'}
-@item @code{C_FORM_FEED} @tab form feed @tab @code{'\f'}
-@item @code{C_NEW_LINE} @tab new line @tab @code{'\n'}
-@item @code{C_CARRIAGE_RETURN} @tab carriage return @tab @code{'\r'}
-@item @code{C_HORIZONTAL_TAB} @tab horizontal tab @tab @code{'\t'}
-@item @code{C_VERTICAL_TAB} @tab vertical tab @tab @code{'\v'}
-@end multitable
-
-Moreover, the following two named constants are defined:
-
-@multitable @columnfractions .20 .80
-@headitem Name @tab Type
-@item @code{C_NULL_PTR} @tab @code{C_PTR}
-@item @code{C_NULL_FUNPTR} @tab @code{C_FUNPTR}
-@end multitable
-
-Both are equivalent to the value @code{NULL} in C.
-
-
-
-@node IEEE modules
-@section IEEE modules: @code{IEEE_EXCEPTIONS}, @code{IEEE_ARITHMETIC}, and @code{IEEE_FEATURES}
-@table @asis
-@item @emph{Standard}:
-Fortran 2003 and later
-@end table
-
-The @code{IEEE_EXCEPTIONS}, @code{IEEE_ARITHMETIC}, and @code{IEEE_FEATURES}
-intrinsic modules provide support for exceptions and IEEE arithmetic, as
-defined in Fortran 2003 and later standards, and the IEC 60559:1989 standard
-(@emph{Binary floating-point arithmetic for microprocessor systems}). These
-modules are only provided on the following supported platforms:
-
-@itemize @bullet
-@item i386 and x86_64 processors
-@item platforms which use the GNU C Library (glibc)
-@item platforms with support for SysV/386 routines for floating point
-interface (including Solaris and BSDs)
-@item platforms with the AIX OS
-@end itemize
-
-For full compliance with the Fortran standards, code using the
-@code{IEEE_EXCEPTIONS} or @code{IEEE_ARITHMETIC} modules should be compiled
-with the following options: @code{-fno-unsafe-math-optimizations
--frounding-math -fsignaling-nans}.
-
-
-
-@node OpenMP Modules OMP_LIB and OMP_LIB_KINDS
-@section OpenMP Modules @code{OMP_LIB} and @code{OMP_LIB_KINDS}
-@table @asis
-@item @emph{Standard}:
-OpenMP Application Program Interface v4.5,
-OpenMP Application Program Interface v5.0 (partially supported) and
-OpenMP Application Program Interface v5.1 (partially supported).
-@end table
-
-The OpenMP Fortran runtime library routines are provided both in
-a form of two Fortran modules, named @code{OMP_LIB} and
-@code{OMP_LIB_KINDS}, and in a form of a Fortran @code{include} file named
-@file{omp_lib.h}. The procedures provided by @code{OMP_LIB} can be found
-in the @ref{Top,,Introduction,libgomp,GNU Offloading and Multi
-Processing Runtime Library} manual,
-the named constants defined in the modules are listed
-below.
-
-For details refer to the actual
-@uref{https://www.openmp.org/wp-content/uploads/openmp-4.5.pdf,
-OpenMP Application Program Interface v4.5} and
-@uref{https://www.openmp.org/wp-content/uploads/OpenMP-API-Specification-5.0.pdf,
-OpenMP Application Program Interface v5.0}.
-
-@code{OMP_LIB_KINDS} provides the following scalar default-integer
-named constants:
-
-@table @asis
-@item @code{omp_allocator_handle_kind}
-@item @code{omp_alloctrait_key_kind}
-@item @code{omp_alloctrait_val_kind}
-@item @code{omp_depend_kind}
-@item @code{omp_lock_kind}
-@item @code{omp_lock_hint_kind}
-@item @code{omp_nest_lock_kind}
-@item @code{omp_pause_resource_kind}
-@item @code{omp_memspace_handle_kind}
-@item @code{omp_proc_bind_kind}
-@item @code{omp_sched_kind}
-@item @code{omp_sync_hint_kind}
-@end table
-
-@code{OMP_LIB} provides the scalar default-integer
-named constant @code{openmp_version} with a value of the form
-@var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month
-of the OpenMP version; for OpenMP v4.5 the value is @code{201511}.
-
-The following derived type:
-
-@table @asis
-@item @code{omp_alloctrait}
-@end table
-
-The following scalar integer named constants of the
-kind @code{omp_sched_kind}:
-
-@table @asis
-@item @code{omp_sched_static}
-@item @code{omp_sched_dynamic}
-@item @code{omp_sched_guided}
-@item @code{omp_sched_auto}
-@end table
-
-And the following scalar integer named constants of the
-kind @code{omp_proc_bind_kind}:
-
-@table @asis
-@item @code{omp_proc_bind_false}
-@item @code{omp_proc_bind_true}
-@item @code{omp_proc_bind_primary}
-@item @code{omp_proc_bind_master}
-@item @code{omp_proc_bind_close}
-@item @code{omp_proc_bind_spread}
-@end table
-
-The following scalar integer named constants are of the
-kind @code{omp_lock_hint_kind}:
-
-@table @asis
-@item @code{omp_lock_hint_none}
-@item @code{omp_lock_hint_uncontended}
-@item @code{omp_lock_hint_contended}
-@item @code{omp_lock_hint_nonspeculative}
-@item @code{omp_lock_hint_speculative}
-@item @code{omp_sync_hint_none}
-@item @code{omp_sync_hint_uncontended}
-@item @code{omp_sync_hint_contended}
-@item @code{omp_sync_hint_nonspeculative}
-@item @code{omp_sync_hint_speculative}
-@end table
-
-And the following two scalar integer named constants are of the
-kind @code{omp_pause_resource_kind}:
-
-@table @asis
-@item @code{omp_pause_soft}
-@item @code{omp_pause_hard}
-@end table
-
-The following scalar integer named constants are of the kind
-@code{omp_alloctrait_key_kind}:
-
-@table @asis
-@item @code{omp_atk_sync_hint}
-@item @code{omp_atk_alignment}
-@item @code{omp_atk_access}
-@item @code{omp_atk_pool_size}
-@item @code{omp_atk_fallback}
-@item @code{omp_atk_fb_data}
-@item @code{omp_atk_pinned}
-@item @code{omp_atk_partition}
-@end table
-
-The following scalar integer named constants are of the kind
-@code{omp_alloctrait_val_kind}:
-
-@table @asis
-@code{omp_alloctrait_key_kind}:
-@item @code{omp_atv_default}
-@item @code{omp_atv_false}
-@item @code{omp_atv_true}
-@item @code{omp_atv_contended}
-@item @code{omp_atv_uncontended}
-@item @code{omp_atv_serialized}
-@item @code{omp_atv_sequential}
-@item @code{omp_atv_private}
-@item @code{omp_atv_all}
-@item @code{omp_atv_thread}
-@item @code{omp_atv_pteam}
-@item @code{omp_atv_cgroup}
-@item @code{omp_atv_default_mem_fb}
-@item @code{omp_atv_null_fb}
-@item @code{omp_atv_abort_fb}
-@item @code{omp_atv_allocator_fb}
-@item @code{omp_atv_environment}
-@item @code{omp_atv_nearest}
-@item @code{omp_atv_blocked}
-@end table
-
-The following scalar integer named constants are of the kind
-@code{omp_allocator_handle_kind}:
-
-@table @asis
-@item @code{omp_null_allocator}
-@item @code{omp_default_mem_alloc}
-@item @code{omp_large_cap_mem_alloc}
-@item @code{omp_const_mem_alloc}
-@item @code{omp_high_bw_mem_alloc}
-@item @code{omp_low_lat_mem_alloc}
-@item @code{omp_cgroup_mem_alloc}
-@item @code{omp_pteam_mem_alloc}
-@item @code{omp_thread_mem_alloc}
-@end table
-
-The following scalar integer named constants are of the kind
-@code{omp_memspace_handle_kind}:
-
-@table @asis
-@item @code{omp_default_mem_space}
-@item @code{omp_large_cap_mem_space}
-@item @code{omp_const_mem_space}
-@item @code{omp_high_bw_mem_space}
-@item @code{omp_low_lat_mem_space}
-@end table
-
-
-
-@node OpenACC Module OPENACC
-@section OpenACC Module @code{OPENACC}
-@table @asis
-@item @emph{Standard}:
-OpenACC Application Programming Interface v2.6
-@end table
-
-
-The OpenACC Fortran runtime library routines are provided both in a
-form of a Fortran 90 module, named @code{OPENACC}, and in form of a
-Fortran @code{include} file named @file{openacc_lib.h}. The
-procedures provided by @code{OPENACC} can be found in the
-@ref{Top,,Introduction,libgomp,GNU Offloading and Multi Processing
-Runtime Library} manual, the named constants defined in the modules
-are listed below.
-
-For details refer to the actual
-@uref{https://www.openacc.org/,
-OpenACC Application Programming Interface v2.6}.
-
-@code{OPENACC} provides the scalar default-integer
-named constant @code{openacc_version} with a value of the form
-@var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month
-of the OpenACC version; for OpenACC v2.6 the value is @code{201711}.
+++ /dev/null
-@c Copyright (C) 2004-2022 Free Software Foundation, Inc.
-@c This is part of the GNU Fortran manual.
-@c For copying conditions, see the file gfortran.texi.
-
-@ignore
-@c man begin COPYRIGHT
-Copyright @copyright{} 2004-2022 Free Software Foundation, Inc.
-
-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 the
-Invariant Sections being ``Funding Free Software'', the Front-Cover
-Texts being (a) (see below), and with the Back-Cover Texts being (b)
-(see below). A copy of the license is included in the gfdl(7) man page.
-
-(a) The FSF's Front-Cover Text is:
-
- A GNU Manual
-
-(b) The FSF's Back-Cover Text is:
-
- You have freedom to copy and modify this GNU Manual, like GNU
- software. Copies published by the Free Software Foundation raise
- funds for GNU development.
-@c man end
-@c Set file name and title for the man page.
-@setfilename gfortran
-@settitle GNU Fortran compiler.
-@c man begin SYNOPSIS
-gfortran [@option{-c}|@option{-S}|@option{-E}]
- [@option{-g}] [@option{-pg}] [@option{-O}@var{level}]
- [@option{-W}@var{warn}@dots{}] [@option{-pedantic}]
- [@option{-I}@var{dir}@dots{}] [@option{-L}@var{dir}@dots{}]
- [@option{-D}@var{macro}[=@var{defn}]@dots{}] [@option{-U}@var{macro}]
- [@option{-f}@var{option}@dots{}]
- [@option{-m}@var{machine-option}@dots{}]
- [@option{-o} @var{outfile}] @var{infile}@dots{}
-
-Only the most useful options are listed here; see below for the
-remainder.
-@c man end
-@c man begin SEEALSO
-gpl(7), gfdl(7), fsf-funding(7),
-cpp(1), gcov(1), gcc(1), as(1), ld(1), gdb(1), dbx(1)
-and the Info entries for @file{gcc}, @file{cpp}, @file{gfortran}, @file{as},
-@file{ld}, @file{binutils} and @file{gdb}.
-@c man end
-@c man begin BUGS
-For instructions on reporting bugs, see
-@w{@value{BUGURL}}.
-@c man end
-@c man begin AUTHOR
-See the Info entry for @command{gfortran} for contributors to GCC and
-GNU Fortran.
-@c man end
-@end ignore
-
-@node Invoking GNU Fortran
-@chapter GNU Fortran Command Options
-@cindex GNU Fortran command options
-@cindex command options
-@cindex options, @command{gfortran} command
-
-@c man begin DESCRIPTION
-
-The @command{gfortran} command supports all the options supported by the
-@command{gcc} command. Only options specific to GNU Fortran are documented
-here.
-
-@xref{Invoking GCC,,GCC Command Options,gcc,Using the GNU Compiler
-Collection (GCC)}, for information
-on the non-Fortran-specific aspects of the @command{gcc} command (and,
-therefore, the @command{gfortran} command).
-
-@cindex options, negative forms
-All GCC and GNU Fortran options
-are accepted both by @command{gfortran} and by @command{gcc}
-(as well as any other drivers built at the same time,
-such as @command{g++}),
-since adding GNU Fortran to the GCC distribution
-enables acceptance of GNU Fortran options
-by all of the relevant drivers.
-
-In some cases, options have positive and negative forms;
-the negative form of @option{-ffoo} would be @option{-fno-foo}.
-This manual documents only one of these two forms, whichever
-one is not the default.
-@c man end
-
-@menu
-* Option Summary:: Brief list of all @command{gfortran} options,
- without explanations.
-* Fortran Dialect Options:: Controlling the variant of Fortran language
- compiled.
-* Preprocessing Options:: Enable and customize preprocessing.
-* Error and Warning Options:: How picky should the compiler be?
-* Debugging Options:: Symbol tables, measurements, and debugging dumps.
-* Directory Options:: Where to find module files
-* Link Options :: Influencing the linking step
-* Runtime Options:: Influencing runtime behavior
-* Code Gen Options:: Specifying conventions for function calls, data layout
- and register usage.
-* Interoperability Options:: Options for interoperability with other
- languages.
-* Environment Variables:: Environment variables that affect @command{gfortran}.
-@end menu
-
-@node Option Summary
-@section Option summary
-
-@c man begin OPTIONS
-
-Here is a summary of all the options specific to GNU Fortran, grouped
-by type. Explanations are in the following sections.
-
-@table @emph
-@item Fortran Language Options
-@xref{Fortran Dialect Options,,Options controlling Fortran dialect}.
-@gccoptlist{-fall-intrinsics -fallow-argument-mismatch -fallow-invalid-boz @gol
--fbackslash -fcray-pointer -fd-lines-as-code -fd-lines-as-comments @gol
--fdec -fdec-char-conversions -fdec-structure -fdec-intrinsic-ints @gol
--fdec-static -fdec-math -fdec-include -fdec-format-defaults @gol
--fdec-blank-format-item -fdefault-double-8 -fdefault-integer-8 @gol
--fdefault-real-8 -fdefault-real-10 -fdefault-real-16 -fdollar-ok @gol
--ffixed-line-length-@var{n} -ffixed-line-length-none -fpad-source @gol
--ffree-form -ffree-line-length-@var{n} -ffree-line-length-none @gol
--fimplicit-none -finteger-4-integer-8 -fmax-identifier-length @gol
--fmodule-private -ffixed-form -fno-range-check -fopenacc -fopenmp @gol
--freal-4-real-10 -freal-4-real-16 -freal-4-real-8 -freal-8-real-10 @gol
--freal-8-real-16 -freal-8-real-4 -std=@var{std} -ftest-forall-temp
-}
-
-@item Preprocessing Options
-@xref{Preprocessing Options,,Enable and customize preprocessing}.
-@gccoptlist{-A-@var{question}@r{[}=@var{answer}@r{]}
--A@var{question}=@var{answer} -C -CC -D@var{macro}@r{[}=@var{defn}@r{]}
--H -P @gol
--U@var{macro} -cpp -dD -dI -dM -dN -dU -fworking-directory
--imultilib @var{dir} @gol
--iprefix @var{file} -iquote -isysroot @var{dir} -isystem @var{dir} -nocpp
--nostdinc @gol
--undef
-}
-
-@item Error and Warning Options
-@xref{Error and Warning Options,,Options to request or suppress errors
-and warnings}.
-@gccoptlist{-Waliasing -Wall -Wampersand -Warray-bounds @gol
--Wc-binding-type -Wcharacter-truncation -Wconversion @gol
--Wdo-subscript -Wfunction-elimination -Wimplicit-interface @gol
--Wimplicit-procedure -Wintrinsic-shadow -Wuse-without-only @gol
--Wintrinsics-std -Wline-truncation -Wno-align-commons @gol
--Wno-overwrite-recursive -Wno-tabs -Wreal-q-constant -Wsurprising @gol
--Wunderflow -Wunused-parameter -Wrealloc-lhs -Wrealloc-lhs-all @gol
--Wfrontend-loop-interchange -Wtarget-lifetime -fmax-errors=@var{n} @gol
--fsyntax-only -pedantic @gol
--pedantic-errors @gol
-}
-
-@item Debugging Options
-@xref{Debugging Options,,Options for debugging your program or GNU Fortran}.
-@gccoptlist{-fbacktrace -fdump-fortran-optimized -fdump-fortran-original @gol
--fdebug-aux-vars -fdump-fortran-global -fdump-parse-tree -ffpe-trap=@var{list} @gol
--ffpe-summary=@var{list}
-}
-
-@item Directory Options
-@xref{Directory Options,,Options for directory search}.
-@gccoptlist{-I@var{dir} -J@var{dir} -fintrinsic-modules-path @var{dir}}
-
-@item Link Options
-@xref{Link Options,,Options for influencing the linking step}.
-@gccoptlist{-static-libgfortran -static-libquadmath}
-
-@item Runtime Options
-@xref{Runtime Options,,Options for influencing runtime behavior}.
-@gccoptlist{-fconvert=@var{conversion} -fmax-subrecord-length=@var{length} @gol
--frecord-marker=@var{length} -fsign-zero
-}
-
-@item Interoperability Options
-@xref{Interoperability Options,,Options for interoperability}.
-@gccoptlist{-fc-prototypes -fc-prototypes-external}
-
-@item Code Generation Options
-@xref{Code Gen Options,,Options for code generation conventions}.
-@gccoptlist{-faggressive-function-elimination -fblas-matmul-limit=@var{n} @gol
--fbounds-check -ftail-call-workaround -ftail-call-workaround=@var{n} @gol
--fcheck-array-temporaries @gol
--fcheck=@var{<all|array-temps|bits|bounds|do|mem|pointer|recursion>} @gol
--fcoarray=@var{<none|single|lib>} -fexternal-blas -ff2c @gol
--ffrontend-loop-interchange -ffrontend-optimize @gol
--finit-character=@var{n} -finit-integer=@var{n} -finit-local-zero @gol
--finit-derived -finit-logical=@var{<true|false>} @gol
--finit-real=@var{<zero|inf|-inf|nan|snan>}
--finline-matmul-limit=@var{n} @gol
--finline-arg-packing -fmax-array-constructor=@var{n} @gol
--fmax-stack-var-size=@var{n} -fno-align-commons -fno-automatic @gol
--fno-protect-parens -fno-underscoring -fsecond-underscore @gol
--fpack-derived -frealloc-lhs -frecursive -frepack-arrays @gol
--fshort-enums -fstack-arrays
-}
-@end table
-
-@node Fortran Dialect Options
-@section Options controlling Fortran dialect
-@cindex dialect options
-@cindex language, dialect options
-@cindex options, dialect
-
-The following options control the details of the Fortran dialect
-accepted by the compiler:
-
-@table @gcctabopt
-@item -ffree-form
-@itemx -ffixed-form
-@opindex @code{ffree-form}
-@opindex @code{ffixed-form}
-@cindex options, Fortran dialect
-@cindex file format, free
-@cindex file format, fixed
-Specify the layout used by the source file. The free form layout
-was introduced in Fortran 90. Fixed form was traditionally used in
-older Fortran programs. When neither option is specified, the source
-form is determined by the file extension.
-
-@item -fall-intrinsics
-@opindex @code{fall-intrinsics}
-This option causes all intrinsic procedures (including the GNU-specific
-extensions) to be accepted. This can be useful with @option{-std=} to
-force standard-compliance but get access to the full range of intrinsics
-available with @command{gfortran}. As a consequence, @option{-Wintrinsics-std}
-will be ignored and no user-defined procedure with the same name as any
-intrinsic will be called except when it is explicitly declared @code{EXTERNAL}.
-
-@item -fallow-argument-mismatch
-@opindex @code{fallow-argument-mismatch}
-Some code contains calls to external procedures with mismatches
-between the calls and the procedure definition, or with mismatches
-between different calls. Such code is non-conforming, and will usually
-be flagged with an error. This options degrades the error to a
-warning, which can only be disabled by disabling all warnings via
-@option{-w}. Only a single occurrence per argument is flagged by this
-warning. @option{-fallow-argument-mismatch} is implied by
-@option{-std=legacy}.
-
-Using this option is @emph{strongly} discouraged. It is possible to
-provide standard-conforming code which allows different types of
-arguments by using an explicit interface and @code{TYPE(*)}.
-
-@item -fallow-invalid-boz
-@opindex @code{allow-invalid-boz}
-A BOZ literal constant can occur in a limited number of contexts in
-standard conforming Fortran. This option degrades an error condition
-to a warning, and allows a BOZ literal constant to appear where the
-Fortran standard would otherwise prohibit its use.
-
-@item -fd-lines-as-code
-@itemx -fd-lines-as-comments
-@opindex @code{fd-lines-as-code}
-@opindex @code{fd-lines-as-comments}
-Enable special treatment for lines beginning with @code{d} or @code{D}
-in fixed form sources. If the @option{-fd-lines-as-code} option is
-given they are treated as if the first column contained a blank. If the
-@option{-fd-lines-as-comments} option is given, they are treated as
-comment lines.
-
-@item -fdec
-@opindex @code{fdec}
-DEC compatibility mode. Enables extensions and other features that mimic
-the default behavior of older compilers (such as DEC).
-These features are non-standard and should be avoided at all costs.
-For details on GNU Fortran's implementation of these extensions see the
-full documentation.
-
-Other flags enabled by this switch are:
-@option{-fdollar-ok} @option{-fcray-pointer} @option{-fdec-char-conversions}
-@option{-fdec-structure} @option{-fdec-intrinsic-ints} @option{-fdec-static}
-@option{-fdec-math} @option{-fdec-include} @option{-fdec-blank-format-item}
-@option{-fdec-format-defaults}
-
-If @option{-fd-lines-as-code}/@option{-fd-lines-as-comments} are unset, then
-@option{-fdec} also sets @option{-fd-lines-as-comments}.
-
-@item -fdec-char-conversions
-@opindex @code{fdec-char-conversions}
-Enable the use of character literals in assignments and @code{DATA} statements
-for non-character variables.
-
-@item -fdec-structure
-@opindex @code{fdec-structure}
-Enable DEC @code{STRUCTURE} and @code{RECORD} as well as @code{UNION},
-@code{MAP}, and dot ('.') as a member separator (in addition to '%'). This is
-provided for compatibility only; Fortran 90 derived types should be used
-instead where possible.
-
-@item -fdec-intrinsic-ints
-@opindex @code{fdec-intrinsic-ints}
-Enable B/I/J/K kind variants of existing integer functions (e.g. BIAND, IIAND,
-JIAND, etc...). For a complete list of intrinsics see the full documentation.
-
-@item -fdec-math
-@opindex @code{fdec-math}
-Enable legacy math intrinsics such as COTAN and degree-valued trigonometric
-functions (e.g. TAND, ATAND, etc...) for compatability with older code.
-
-@item -fdec-static
-@opindex @code{fdec-static}
-Enable DEC-style STATIC and AUTOMATIC attributes to explicitly specify
-the storage of variables and other objects.
-
-@item -fdec-include
-@opindex @code{fdec-include}
-Enable parsing of INCLUDE as a statement in addition to parsing it as
-INCLUDE line. When parsed as INCLUDE statement, INCLUDE does not have to
-be on a single line and can use line continuations.
-
-@item -fdec-format-defaults
-@opindex @code{fdec-format-defaults}
-Enable format specifiers F, G and I to be used without width specifiers,
-default widths will be used instead.
-
-@item -fdec-blank-format-item
-@opindex @code{fdec-blank-format-item}
-Enable a blank format item at the end of a format specification i.e. nothing
-following the final comma.
-
-@item -fdollar-ok
-@opindex @code{fdollar-ok}
-@cindex @code{$}
-@cindex symbol names
-@cindex character set
-Allow @samp{$} as a valid non-first character in a symbol name. Symbols
-that start with @samp{$} are rejected since it is unclear which rules to
-apply to implicit typing as different vendors implement different rules.
-Using @samp{$} in @code{IMPLICIT} statements is also rejected.
-
-@item -fbackslash
-@opindex @code{backslash}
-@cindex backslash
-@cindex escape characters
-Change the interpretation of backslashes in string literals from a single
-backslash character to ``C-style'' escape characters. The following
-combinations are expanded @code{\a}, @code{\b}, @code{\f}, @code{\n},
-@code{\r}, @code{\t}, @code{\v}, @code{\\}, and @code{\0} to the ASCII
-characters alert, backspace, form feed, newline, carriage return,
-horizontal tab, vertical tab, backslash, and NUL, respectively.
-Additionally, @code{\x}@var{nn}, @code{\u}@var{nnnn} and
-@code{\U}@var{nnnnnnnn} (where each @var{n} is a hexadecimal digit) are
-translated into the Unicode characters corresponding to the specified code
-points. All other combinations of a character preceded by \ are
-unexpanded.
-
-@item -fmodule-private
-@opindex @code{fmodule-private}
-@cindex module entities
-@cindex private
-Set the default accessibility of module entities to @code{PRIVATE}.
-Use-associated entities will not be accessible unless they are explicitly
-declared as @code{PUBLIC}.
-
-@item -ffixed-line-length-@var{n}
-@opindex @code{ffixed-line-length-}@var{n}
-@cindex file format, fixed
-Set column after which characters are ignored in typical fixed-form
-lines in the source file, and, unless @code{-fno-pad-source}, through which
-spaces are assumed (as if padded to that length) after the ends of short
-fixed-form lines.
-
-Popular values for @var{n} include 72 (the
-standard and the default), 80 (card image), and 132 (corresponding
-to ``extended-source'' options in some popular compilers).
-@var{n} may also be @samp{none}, meaning that the entire line is meaningful
-and that continued character constants never have implicit spaces appended
-to them to fill out the line.
-@option{-ffixed-line-length-0} means the same thing as
-@option{-ffixed-line-length-none}.
-
-@item -fno-pad-source
-@opindex @code{fpad-source}
-By default fixed-form lines have spaces assumed (as if padded to that length)
-after the ends of short fixed-form lines. This is not done either if
-@option{-ffixed-line-length-0}, @option{-ffixed-line-length-none} or
-if @option{-fno-pad-source} option is used. With any of those options
-continued character constants never have implicit spaces appended
-to them to fill out the line.
-
-@item -ffree-line-length-@var{n}
-@opindex @code{ffree-line-length-}@var{n}
-@cindex file format, free
-Set column after which characters are ignored in typical free-form
-lines in the source file. The default value is 132.
-@var{n} may be @samp{none}, meaning that the entire line is meaningful.
-@option{-ffree-line-length-0} means the same thing as
-@option{-ffree-line-length-none}.
-
-@item -fmax-identifier-length=@var{n}
-@opindex @code{fmax-identifier-length=}@var{n}
-Specify the maximum allowed identifier length. Typical values are
-31 (Fortran 95) and 63 (Fortran 2003 and later).
-
-@item -fimplicit-none
-@opindex @code{fimplicit-none}
-Specify that no implicit typing is allowed, unless overridden by explicit
-@code{IMPLICIT} statements. This is the equivalent of adding
-@code{implicit none} to the start of every procedure.
-
-@item -fcray-pointer
-@opindex @code{fcray-pointer}
-Enable the Cray pointer extension, which provides C-like pointer
-functionality.
-
-@item -fopenacc
-@opindex @code{fopenacc}
-@cindex OpenACC
-Enable the OpenACC extensions. This includes OpenACC @code{!$acc}
-directives in free form and @code{c$acc}, @code{*$acc} and
-@code{!$acc} directives in fixed form, @code{!$} conditional
-compilation sentinels in free form and @code{c$}, @code{*$} and
-@code{!$} sentinels in fixed form, and when linking arranges for the
-OpenACC runtime library to be linked in.
-
-@item -fopenmp
-@opindex @code{fopenmp}
-@cindex OpenMP
-Enable the OpenMP extensions. This includes OpenMP @code{!$omp} directives
-in free form
-and @code{c$omp}, @code{*$omp} and @code{!$omp} directives in fixed form,
-@code{!$} conditional compilation sentinels in free form
-and @code{c$}, @code{*$} and @code{!$} sentinels in fixed form,
-and when linking arranges for the OpenMP runtime library to be linked
-in. The option @option{-fopenmp} implies @option{-frecursive}.
-
-@item -fno-range-check
-@opindex @code{frange-check}
-Disable range checking on results of simplification of constant
-expressions during compilation. For example, GNU Fortran will give
-an error at compile time when simplifying @code{a = 1. / 0}.
-With this option, no error will be given and @code{a} will be assigned
-the value @code{+Infinity}. If an expression evaluates to a value
-outside of the relevant range of [@code{-HUGE()}:@code{HUGE()}],
-then the expression will be replaced by @code{-Inf} or @code{+Inf}
-as appropriate.
-Similarly, @code{DATA i/Z'FFFFFFFF'/} will result in an integer overflow
-on most systems, but with @option{-fno-range-check} the value will
-``wrap around'' and @code{i} will be initialized to @math{-1} instead.
-
-@item -fdefault-integer-8
-@opindex @code{fdefault-integer-8}
-Set the default integer and logical types to an 8 byte wide type. This option
-also affects the kind of integer constants like @code{42}. Unlike
-@option{-finteger-4-integer-8}, it does not promote variables with explicit
-kind declaration.
-
-@item -fdefault-real-8
-@opindex @code{fdefault-real-8}
-Set the default real type to an 8 byte wide type. This option also affects
-the kind of non-double real constants like @code{1.0}. This option promotes
-the default width of @code{DOUBLE PRECISION} and double real constants
-like @code{1.d0} to 16 bytes if possible. If @code{-fdefault-double-8}
-is given along with @code{fdefault-real-8}, @code{DOUBLE PRECISION}
-and double real constants are not promoted. Unlike @option{-freal-4-real-8},
-@code{fdefault-real-8} does not promote variables with explicit kind
-declarations.
-
-@item -fdefault-real-10
-@opindex @code{fdefault-real-10}
-Set the default real type to an 10 byte wide type. This option also affects
-the kind of non-double real constants like @code{1.0}. This option promotes
-the default width of @code{DOUBLE PRECISION} and double real constants
-like @code{1.d0} to 16 bytes if possible. If @code{-fdefault-double-8}
-is given along with @code{fdefault-real-10}, @code{DOUBLE PRECISION}
-and double real constants are not promoted. Unlike @option{-freal-4-real-10},
-@code{fdefault-real-10} does not promote variables with explicit kind
-declarations.
-
-@item -fdefault-real-16
-@opindex @code{fdefault-real-16}
-Set the default real type to an 16 byte wide type. This option also affects
-the kind of non-double real constants like @code{1.0}. This option promotes
-the default width of @code{DOUBLE PRECISION} and double real constants
-like @code{1.d0} to 16 bytes if possible. If @code{-fdefault-double-8}
-is given along with @code{fdefault-real-16}, @code{DOUBLE PRECISION}
-and double real constants are not promoted. Unlike @option{-freal-4-real-16},
-@code{fdefault-real-16} does not promote variables with explicit kind
-declarations.
-
-@item -fdefault-double-8
-@opindex @code{fdefault-double-8}
-Set the @code{DOUBLE PRECISION} type and double real constants
-like @code{1.d0} to an 8 byte wide type. Do nothing if this
-is already the default. This option prevents @option{-fdefault-real-8},
-@option{-fdefault-real-10}, and @option{-fdefault-real-16},
-from promoting @code{DOUBLE PRECISION} and double real constants like
-@code{1.d0} to 16 bytes.
-
-@item -finteger-4-integer-8
-@opindex @code{finteger-4-integer-8}
-Promote all @code{INTEGER(KIND=4)} entities to an @code{INTEGER(KIND=8)}
-entities. If @code{KIND=8} is unavailable, then an error will be issued.
-This option should be used with care and may not be suitable for your codes.
-Areas of possible concern include calls to external procedures,
-alignment in @code{EQUIVALENCE} and/or @code{COMMON}, generic interfaces,
-BOZ literal constant conversion, and I/O. Inspection of the intermediate
-representation of the translated Fortran code, produced by
-@option{-fdump-tree-original}, is suggested.
-
-@item -freal-4-real-8
-@itemx -freal-4-real-10
-@itemx -freal-4-real-16
-@itemx -freal-8-real-4
-@itemx -freal-8-real-10
-@itemx -freal-8-real-16
-@opindex @code{freal-4-real-8}
-@opindex @code{freal-4-real-10}
-@opindex @code{freal-4-real-16}
-@opindex @code{freal-8-real-4}
-@opindex @code{freal-8-real-10}
-@opindex @code{freal-8-real-16}
-@cindex options, real kind type promotion
-Promote all @code{REAL(KIND=M)} entities to @code{REAL(KIND=N)} entities.
-If @code{REAL(KIND=N)} is unavailable, then an error will be issued.
-The @code{-freal-4-} flags also affect the default real kind and the
-@code{-freal-8-} flags also the double-precision real kind. All other
-real-kind types are unaffected by this option. The promotion is also
-applied to real literal constants of default and double-precision kind
-and a specified kind number of 4 or 8, respectively.
-However, @code{-fdefault-real-8}, @code{-fdefault-real-10},
-@code{-fdefault-real-10}, and @code{-fdefault-double-8} take precedence
-for the default and double-precision real kinds, both for real literal
-constants and for declarations without a kind number.
-Note that for @code{REAL(KIND=KIND(1.0))} the literal may get promoted and
-then the result may get promoted again.
-These options should be used with care and may not be suitable for your
-codes. Areas of possible concern include calls to external procedures,
-alignment in @code{EQUIVALENCE} and/or @code{COMMON}, generic interfaces,
-BOZ literal constant conversion, and I/O and calls to intrinsic procedures
-when passing a value to the @code{kind=} dummy argument. Inspection of the
-intermediate representation of the translated Fortran code, produced by
-@option{-fdump-fortran-original} or @option{-fdump-tree-original}, is suggested.
-
-@item -std=@var{std}
-@opindex @code{std=}@var{std} option
-Specify the standard to which the program is expected to conform,
-which may be one of @samp{f95}, @samp{f2003}, @samp{f2008},
-@samp{f2018}, @samp{gnu}, or @samp{legacy}. The default value for
-@var{std} is @samp{gnu}, which specifies a superset of the latest
-Fortran standard that includes all of the extensions supported by GNU
-Fortran, although warnings will be given for obsolete extensions not
-recommended for use in new code. The @samp{legacy} value is
-equivalent but without the warnings for obsolete extensions, and may
-be useful for old non-standard programs. The @samp{f95},
-@samp{f2003}, @samp{f2008}, and @samp{f2018} values specify strict
-conformance to the Fortran 95, Fortran 2003, Fortran 2008 and Fortran
-2018 standards, respectively; errors are given for all extensions
-beyond the relevant language standard, and warnings are given for the
-Fortran 77 features that are permitted but obsolescent in later
-standards. The deprecated option @samp{-std=f2008ts} acts as an alias for
-@samp{-std=f2018}. It is only present for backwards compatibility with
-earlier gfortran versions and should not be used any more.
-
-@item -ftest-forall-temp
-@opindex @code{ftest-forall-temp}
-Enhance test coverage by forcing most forall assignments to use temporary.
-
-@end table
-
-@node Preprocessing Options
-@section Enable and customize preprocessing
-@cindex preprocessor
-@cindex options, preprocessor
-@cindex CPP
-@cindex FPP
-@cindex Conditional compilation
-@cindex Preprocessing
-@cindex preprocessor, include file handling
-
-Many Fortran compilers including GNU Fortran allow passing the source code
-through a C preprocessor (CPP; sometimes also called the Fortran preprocessor,
-FPP) to allow for conditional compilation. In the case of GNU Fortran,
-this is the GNU C Preprocessor in the traditional mode. On systems with
-case-preserving file names, the preprocessor is automatically invoked if the
-filename extension is @file{.F}, @file{.FOR}, @file{.FTN}, @file{.fpp},
-@file{.FPP}, @file{.F90}, @file{.F95}, @file{.F03} or @file{.F08}. To manually
-invoke the preprocessor on any file, use @option{-cpp}, to disable
-preprocessing on files where the preprocessor is run automatically, use
-@option{-nocpp}.
-
-If a preprocessed file includes another file with the Fortran @code{INCLUDE}
-statement, the included file is not preprocessed. To preprocess included
-files, use the equivalent preprocessor statement @code{#include}.
-
-If GNU Fortran invokes the preprocessor, @code{__GFORTRAN__}
-is defined. The macros @code{__GNUC__}, @code{__GNUC_MINOR__} and
-@code{__GNUC_PATCHLEVEL__} can be used to determine the version of the
-compiler. See @ref{Top,,Overview,cpp,The C Preprocessor} for details.
-
-GNU Fortran supports a number of @code{INTEGER} and @code{REAL} kind types
-in additional to the kind types required by the Fortran standard.
-The availability of any given kind type is architecture dependent. The
-following pre-defined preprocessor macros can be used to conditionally
-include code for these additional kind types: @code{__GFC_INT_1__},
-@code{__GFC_INT_2__}, @code{__GFC_INT_8__}, @code{__GFC_INT_16__},
-@code{__GFC_REAL_10__}, and @code{__GFC_REAL_16__}.
-
-While CPP is the de-facto standard for preprocessing Fortran code,
-Part 3 of the Fortran 95 standard (ISO/IEC 1539-3:1998) defines
-Conditional Compilation, which is not widely used and not directly
-supported by the GNU Fortran compiler. You can use the program coco
-to preprocess such files (@uref{http://www.daniellnagle.com/coco.html}).
-
-The following options control preprocessing of Fortran code:
-
-@table @gcctabopt
-@item -cpp
-@itemx -nocpp
-@opindex @code{cpp}
-@opindex @code{fpp}
-@cindex preprocessor, enable
-@cindex preprocessor, disable
-Enable preprocessing. The preprocessor is automatically invoked if
-the file extension is @file{.fpp}, @file{.FPP}, @file{.F}, @file{.FOR},
-@file{.FTN}, @file{.F90}, @file{.F95}, @file{.F03} or @file{.F08}. Use
-this option to manually enable preprocessing of any kind of Fortran file.
-
-To disable preprocessing of files with any of the above listed extensions,
-use the negative form: @option{-nocpp}.
-
-The preprocessor is run in traditional mode. Any restrictions of the
-file-format, especially the limits on line length, apply for
-preprocessed output as well, so it might be advisable to use the
-@option{-ffree-line-length-none} or @option{-ffixed-line-length-none}
-options.
-
-@item -dM
-@opindex @code{dM}
-@cindex preprocessor, debugging
-@cindex debugging, preprocessor
-Instead of the normal output, generate a list of @code{'#define'}
-directives for all the macros defined during the execution of the
-preprocessor, including predefined macros. This gives you a way
-of finding out what is predefined in your version of the preprocessor.
-Assuming you have no file @file{foo.f90}, the command
-@smallexample
- touch foo.f90; gfortran -cpp -E -dM foo.f90
-@end smallexample
-will show all the predefined macros.
-
-@item -dD
-@opindex @code{dD}
-@cindex preprocessor, debugging
-@cindex debugging, preprocessor
-Like @option{-dM} except in two respects: it does not include the
-predefined macros, and it outputs both the @code{#define} directives
-and the result of preprocessing. Both kinds of output go to the
-standard output file.
-
-@item -dN
-@opindex @code{dN}
-@cindex preprocessor, debugging
-@cindex debugging, preprocessor
-Like @option{-dD}, but emit only the macro names, not their expansions.
-
-@item -dU
-@opindex @code{dU}
-@cindex preprocessor, debugging
-@cindex debugging, preprocessor
-Like @option{dD} except that only macros that are expanded, or whose
-definedness is tested in preprocessor directives, are output; the
-output is delayed until the use or test of the macro; and @code{'#undef'}
-directives are also output for macros tested but undefined at the time.
-
-@item -dI
-@opindex @code{dI}
-@cindex preprocessor, debugging
-@cindex debugging, preprocessor
-Output @code{'#include'} directives in addition to the result
-of preprocessing.
-
-@item -fworking-directory
-@opindex @code{fworking-directory}
-@cindex preprocessor, working directory
-Enable generation of linemarkers in the preprocessor output that will
-let the compiler know the current working directory at the time of
-preprocessing. When this option is enabled, the preprocessor will emit,
-after the initial linemarker, a second linemarker with the current
-working directory followed by two slashes. GCC will use this directory,
-when it is present in the preprocessed input, as the directory emitted
-as the current working directory in some debugging information formats.
-This option is implicitly enabled if debugging information is enabled,
-but this can be inhibited with the negated form
-@option{-fno-working-directory}. If the @option{-P} flag is present
-in the command line, this option has no effect, since no @code{#line}
-directives are emitted whatsoever.
-
-@item -idirafter @var{dir}
-@opindex @code{idirafter @var{dir}}
-@cindex preprocessing, include path
-Search @var{dir} for include files, but do it after all directories
-specified with @option{-I} and the standard system directories have
-been exhausted. @var{dir} is treated as a system include directory.
-If dir begins with @code{=}, then the @code{=} will be replaced by
-the sysroot prefix; see @option{--sysroot} and @option{-isysroot}.
-
-@item -imultilib @var{dir}
-@opindex @code{imultilib @var{dir}}
-@cindex preprocessing, include path
-Use @var{dir} as a subdirectory of the directory containing target-specific
-C++ headers.
-
-@item -iprefix @var{prefix}
-@opindex @code{iprefix @var{prefix}}
-@cindex preprocessing, include path
-Specify @var{prefix} as the prefix for subsequent @option{-iwithprefix}
-options. If the @var{prefix} represents a directory, you should include
-the final @code{'/'}.
-
-@item -isysroot @var{dir}
-@opindex @code{isysroot @var{dir}}
-@cindex preprocessing, include path
-This option is like the @option{--sysroot} option, but applies only to
-header files. See the @option{--sysroot} option for more information.
-
-@item -iquote @var{dir}
-@opindex @code{iquote @var{dir}}
-@cindex preprocessing, include path
-Search @var{dir} only for header files requested with @code{#include "file"};
-they are not searched for @code{#include <file>}, before all directories
-specified by @option{-I} and before the standard system directories. If
-@var{dir} begins with @code{=}, then the @code{=} will be replaced by the
-sysroot prefix; see @option{--sysroot} and @option{-isysroot}.
-
-@item -isystem @var{dir}
-@opindex @code{isystem @var{dir}}
-@cindex preprocessing, include path
-Search @var{dir} for header files, after all directories specified by
-@option{-I} but before the standard system directories. Mark it as a
-system directory, so that it gets the same special treatment as is
-applied to the standard system directories. If @var{dir} begins with
-@code{=}, then the @code{=} will be replaced by the sysroot prefix;
-see @option{--sysroot} and @option{-isysroot}.
-
-@item -nostdinc
-@opindex @code{nostdinc}
-Do not search the standard system directories for header files. Only
-the directories you have specified with @option{-I} options (and the
-directory of the current file, if appropriate) are searched.
-
-@item -undef
-@opindex @code{undef}
-Do not predefine any system-specific or GCC-specific macros.
-The standard predefined macros remain defined.
-
-@item -A@var{predicate}=@var{answer}
-@opindex @code{A@var{predicate}=@var{answer}}
-@cindex preprocessing, assertion
-Make an assertion with the predicate @var{predicate} and answer @var{answer}.
-This form is preferred to the older form -A predicate(answer), which is still
-supported, because it does not use shell special characters.
-
-@item -A-@var{predicate}=@var{answer}
-@opindex @code{A-@var{predicate}=@var{answer}}
-@cindex preprocessing, assertion
-Cancel an assertion with the predicate @var{predicate} and answer @var{answer}.
-
-@item -C
-@opindex @code{C}
-@cindex preprocessing, keep comments
-Do not discard comments. All comments are passed through to the output
-file, except for comments in processed directives, which are deleted
-along with the directive.
-
-You should be prepared for side effects when using @option{-C}; it causes
-the preprocessor to treat comments as tokens in their own right. For example,
-comments appearing at the start of what would be a directive line have the
-effect of turning that line into an ordinary source line, since the first
-token on the line is no longer a @code{'#'}.
-
-Warning: this currently handles C-Style comments only. The preprocessor
-does not yet recognize Fortran-style comments.
-
-@item -CC
-@opindex @code{CC}
-@cindex preprocessing, keep comments
-Do not discard comments, including during macro expansion. This is like
-@option{-C}, except that comments contained within macros are also passed
-through to the output file where the macro is expanded.
-
-In addition to the side-effects of the @option{-C} option, the @option{-CC}
-option causes all C++-style comments inside a macro to be converted to C-style
-comments. This is to prevent later use of that macro from inadvertently
-commenting out the remainder of the source line. The @option{-CC} option
-is generally used to support lint comments.
-
-Warning: this currently handles C- and C++-Style comments only. The
-preprocessor does not yet recognize Fortran-style comments.
-
-@item -D@var{name}
-@opindex @code{D@var{name}}
-@cindex preprocessing, define macros
-Predefine name as a macro, with definition @code{1}.
-
-@item -D@var{name}=@var{definition}
-@opindex @code{D@var{name}=@var{definition}}
-@cindex preprocessing, define macros
-The contents of @var{definition} are tokenized and processed as if they
-appeared during translation phase three in a @code{'#define'} directive.
-In particular, the definition will be truncated by embedded newline
-characters.
-
-If you are invoking the preprocessor from a shell or shell-like program
-you may need to use the shell's quoting syntax to protect characters such
-as spaces that have a meaning in the shell syntax.
-
-If you wish to define a function-like macro on the command line, write
-its argument list with surrounding parentheses before the equals sign
-(if any). Parentheses are meaningful to most shells, so you will need
-to quote the option. With sh and csh, @code{-D'name(args...)=definition'}
-works.
-
-@option{-D} and @option{-U} options are processed in the order they are
-given on the command line. All -imacros file and -include file options
-are processed after all -D and -U options.
-
-@item -H
-@opindex @code{H}
-Print the name of each header file used, in addition to other normal
-activities. Each name is indented to show how deep in the @code{'#include'}
-stack it is.
-
-@item -P
-@opindex @code{P}
-@cindex preprocessing, no linemarkers
-Inhibit generation of linemarkers in the output from the preprocessor.
-This might be useful when running the preprocessor on something that
-is not C code, and will be sent to a program which might be confused
-by the linemarkers.
-
-@item -U@var{name}
-@opindex @code{U@var{name}}
-@cindex preprocessing, undefine macros
-Cancel any previous definition of @var{name}, either built in or provided
-with a @option{-D} option.
-@end table
-
-
-@node Error and Warning Options
-@section Options to request or suppress errors and warnings
-@cindex options, warnings
-@cindex options, errors
-@cindex warnings, suppressing
-@cindex messages, error
-@cindex messages, warning
-@cindex suppressing warnings
-
-Errors are diagnostic messages that report that the GNU Fortran compiler
-cannot compile the relevant piece of source code. The compiler will
-continue to process the program in an attempt to report further errors
-to aid in debugging, but will not produce any compiled output.
-
-Warnings are diagnostic messages that report constructions which
-are not inherently erroneous but which are risky or suggest there is
-likely to be a bug in the program. Unless @option{-Werror} is specified,
-they do not prevent compilation of the program.
-
-You can request many specific warnings with options beginning @option{-W},
-for example @option{-Wimplicit} to request warnings on implicit
-declarations. Each of these specific warning options also has a
-negative form beginning @option{-Wno-} to turn off warnings;
-for example, @option{-Wno-implicit}. This manual lists only one of the
-two forms, whichever is not the default.
-
-These options control the amount and kinds of errors and warnings produced
-by GNU Fortran:
-
-@table @gcctabopt
-@item -fmax-errors=@var{n}
-@opindex @code{fmax-errors=}@var{n}
-@cindex errors, limiting
-Limits the maximum number of error messages to @var{n}, at which point
-GNU Fortran bails out rather than attempting to continue processing the
-source code. If @var{n} is 0, there is no limit on the number of error
-messages produced.
-
-@item -fsyntax-only
-@opindex @code{fsyntax-only}
-@cindex syntax checking
-Check the code for syntax errors, but do not actually compile it. This
-will generate module files for each module present in the code, but no
-other output file.
-
-@item -Wpedantic
-@itemx -pedantic
-@opindex @code{pedantic}
-@opindex @code{Wpedantic}
-Issue warnings for uses of extensions to Fortran.
-@option{-pedantic} also applies to C-language constructs where they
-occur in GNU Fortran source files, such as use of @samp{\e} in a
-character constant within a directive like @code{#include}.
-
-Valid Fortran programs should compile properly with or without
-this option.
-However, without this option, certain GNU extensions and traditional
-Fortran features are supported as well.
-With this option, many of them are rejected.
-
-Some users try to use @option{-pedantic} to check programs for conformance.
-They soon find that it does not do quite what they want---it finds some
-nonstandard practices, but not all.
-However, improvements to GNU Fortran in this area are welcome.
-
-This should be used in conjunction with @option{-std=f95},
-@option{-std=f2003}, @option{-std=f2008} or @option{-std=f2018}.
-
-@item -pedantic-errors
-@opindex @code{pedantic-errors}
-Like @option{-pedantic}, except that errors are produced rather than
-warnings.
-
-@item -Wall
-@opindex @code{Wall}
-@cindex all warnings
-@cindex warnings, all
-Enables commonly used warning options pertaining to usage that
-we recommend avoiding and that we believe are easy to avoid.
-This currently includes @option{-Waliasing}, @option{-Wampersand},
-@option{-Wconversion}, @option{-Wsurprising}, @option{-Wc-binding-type},
-@option{-Wintrinsics-std}, @option{-Wtabs}, @option{-Wintrinsic-shadow},
-@option{-Wline-truncation}, @option{-Wtarget-lifetime},
-@option{-Winteger-division}, @option{-Wreal-q-constant}, @option{-Wunused}
-and @option{-Wundefined-do-loop}.
-
-@item -Waliasing
-@opindex @code{Waliasing}
-@cindex aliasing
-@cindex warnings, aliasing
-Warn about possible aliasing of dummy arguments. Specifically, it warns
-if the same actual argument is associated with a dummy argument with
-@code{INTENT(IN)} and a dummy argument with @code{INTENT(OUT)} in a call
-with an explicit interface.
-
-The following example will trigger the warning.
-@smallexample
- interface
- subroutine bar(a,b)
- integer, intent(in) :: a
- integer, intent(out) :: b
- end subroutine
- end interface
- integer :: a
-
- call bar(a,a)
-@end smallexample
-
-@item -Wampersand
-@opindex @code{Wampersand}
-@cindex warnings, ampersand
-@cindex @code{&}
-Warn about missing ampersand in continued character constants. The
-warning is given with @option{-Wampersand}, @option{-pedantic},
-@option{-std=f95}, @option{-std=f2003}, @option{-std=f2008} and
-@option{-std=f2018}. Note: With no ampersand given in a continued
-character constant, GNU Fortran assumes continuation at the first
-non-comment, non-whitespace character after the ampersand that
-initiated the continuation.
-
-@item -Warray-temporaries
-@opindex @code{Warray-temporaries}
-@cindex warnings, array temporaries
-Warn about array temporaries generated by the compiler. The information
-generated by this warning is sometimes useful in optimization, in order to
-avoid such temporaries.
-
-@item -Wc-binding-type
-@opindex @code{Wc-binding-type}
-@cindex warning, C binding type
-Warn if the a variable might not be C interoperable. In particular, warn if
-the variable has been declared using an intrinsic type with default kind
-instead of using a kind parameter defined for C interoperability in the
-intrinsic @code{ISO_C_Binding} module. This option is implied by
-@option{-Wall}.
-
-@item -Wcharacter-truncation
-@opindex @code{Wcharacter-truncation}
-@cindex warnings, character truncation
-Warn when a character assignment will truncate the assigned string.
-
-@item -Wline-truncation
-@opindex @code{Wline-truncation}
-@cindex warnings, line truncation
-Warn when a source code line will be truncated. This option is
-implied by @option{-Wall}. For free-form source code, the default is
-@option{-Werror=line-truncation} such that truncations are reported as
-error.
-
-@item -Wconversion
-@opindex @code{Wconversion}
-@cindex warnings, conversion
-@cindex conversion
-Warn about implicit conversions that are likely to change the value of
-the expression after conversion. Implied by @option{-Wall}.
-
-@item -Wconversion-extra
-@opindex @code{Wconversion-extra}
-@cindex warnings, conversion
-@cindex conversion
-Warn about implicit conversions between different types and kinds. This
-option does @emph{not} imply @option{-Wconversion}.
-
-@item -Wextra
-@opindex @code{Wextra}
-@cindex extra warnings
-@cindex warnings, extra
-Enables some warning options for usages of language features which
-may be problematic. This currently includes @option{-Wcompare-reals},
-@option{-Wunused-parameter} and @option{-Wdo-subscript}.
-
-@item -Wfrontend-loop-interchange
-@opindex @code{Wfrontend-loop-interchange}
-@cindex warnings, loop interchange
-@cindex loop interchange, warning
-Warn when using @option{-ffrontend-loop-interchange} for performing loop
-interchanges.
-
-@item -Wimplicit-interface
-@opindex @code{Wimplicit-interface}
-@cindex warnings, implicit interface
-Warn if a procedure is called without an explicit interface.
-Note this only checks that an explicit interface is present. It does not
-check that the declared interfaces are consistent across program units.
-
-@item -Wimplicit-procedure
-@opindex @code{Wimplicit-procedure}
-@cindex warnings, implicit procedure
-Warn if a procedure is called that has neither an explicit interface
-nor has been declared as @code{EXTERNAL}.
-
-@item -Winteger-division
-@opindex @code{Winteger-division}
-@cindex warnings, integer division
-@cindex warnings, division of integers
-Warn if a constant integer division truncates its result.
-As an example, 3/5 evaluates to 0.
-
-@item -Wintrinsics-std
-@opindex @code{Wintrinsics-std}
-@cindex warnings, non-standard intrinsics
-@cindex warnings, intrinsics of other standards
-Warn if @command{gfortran} finds a procedure named like an intrinsic not
-available in the currently selected standard (with @option{-std}) and treats
-it as @code{EXTERNAL} procedure because of this. @option{-fall-intrinsics} can
-be used to never trigger this behavior and always link to the intrinsic
-regardless of the selected standard.
-
-@item -Wno-overwrite-recursive
-@opindex @code{Woverwrite-recursive}
-@cindex warnings, overwrite recursive
-Do not warn when @option{-fno-automatic} is used with @option{-frecursive}. Recursion
-will be broken if the relevant local variables do not have the attribute
-@code{AUTOMATIC} explicitly declared. This option can be used to suppress the warning
-when it is known that recursion is not broken. Useful for build environments that use
-@option{-Werror}.
-
-@item -Wreal-q-constant
-@opindex @code{Wreal-q-constant}
-@cindex warnings, @code{q} exponent-letter
-Produce a warning if a real-literal-constant contains a @code{q}
-exponent-letter.
-
-@item -Wsurprising
-@opindex @code{Wsurprising}
-@cindex warnings, suspicious code
-Produce a warning when ``suspicious'' code constructs are encountered.
-While technically legal these usually indicate that an error has been made.
-
-This currently produces a warning under the following circumstances:
-
-@itemize @bullet
-@item
-An INTEGER SELECT construct has a CASE that can never be matched as its
-lower value is greater than its upper value.
-
-@item
-A LOGICAL SELECT construct has three CASE statements.
-
-@item
-A TRANSFER specifies a source that is shorter than the destination.
-
-@item
-The type of a function result is declared more than once with the same type. If
-@option{-pedantic} or standard-conforming mode is enabled, this is an error.
-
-@item
-A @code{CHARACTER} variable is declared with negative length.
-
-@item
-With @option{-fopenmp}, for fixed-form source code, when an @code{omx}
-vendor-extension sentinel is encountered. (The equivalent @code{ompx},
-used in free-form source code, is diagnosed by default.)
-@end itemize
-
-@item -Wtabs
-@opindex @code{Wtabs}
-@cindex warnings, tabs
-@cindex tabulators
-By default, tabs are accepted as whitespace, but tabs are not members
-of the Fortran Character Set. For continuation lines, a tab followed
-by a digit between 1 and 9 is supported. @option{-Wtabs} will cause a
-warning to be issued if a tab is encountered. Note, @option{-Wtabs} is
-active for @option{-pedantic}, @option{-std=f95}, @option{-std=f2003},
-@option{-std=f2008}, @option{-std=f2018} and
-@option{-Wall}.
-
-@item -Wundefined-do-loop
-@opindex @code{Wundefined-do-loop}
-@cindex warnings, undefined do loop
-Warn if a DO loop with step either 1 or -1 yields an underflow or an overflow
-during iteration of an induction variable of the loop.
-This option is implied by @option{-Wall}.
-
-@item -Wunderflow
-@opindex @code{Wunderflow}
-@cindex warnings, underflow
-@cindex underflow
-Produce a warning when numerical constant expressions are
-encountered, which yield an UNDERFLOW during compilation. Enabled by default.
-
-@item -Wintrinsic-shadow
-@opindex @code{Wintrinsic-shadow}
-@cindex warnings, intrinsic
-@cindex intrinsic
-Warn if a user-defined procedure or module procedure has the same name as an
-intrinsic; in this case, an explicit interface or @code{EXTERNAL} or
-@code{INTRINSIC} declaration might be needed to get calls later resolved to
-the desired intrinsic/procedure. This option is implied by @option{-Wall}.
-
-@item -Wuse-without-only
-@opindex @code{Wuse-without-only}
-@cindex warnings, use statements
-@cindex intrinsic
-Warn if a @code{USE} statement has no @code{ONLY} qualifier and
-thus implicitly imports all public entities of the used module.
-
-@item -Wunused-dummy-argument
-@opindex @code{Wunused-dummy-argument}
-@cindex warnings, unused dummy argument
-@cindex unused dummy argument
-@cindex dummy argument, unused
-Warn about unused dummy arguments. This option is implied by @option{-Wall}.
-
-@item -Wunused-parameter
-@opindex @code{Wunused-parameter}
-@cindex warnings, unused parameter
-@cindex unused parameter
-Contrary to @command{gcc}'s meaning of @option{-Wunused-parameter},
-@command{gfortran}'s implementation of this option does not warn
-about unused dummy arguments (see @option{-Wunused-dummy-argument}),
-but about unused @code{PARAMETER} values. @option{-Wunused-parameter}
-is implied by @option{-Wextra} if also @option{-Wunused} or
-@option{-Wall} is used.
-
-@item -Walign-commons
-@opindex @code{Walign-commons}
-@cindex warnings, alignment of @code{COMMON} blocks
-@cindex alignment of @code{COMMON} blocks
-By default, @command{gfortran} warns about any occasion of variables being
-padded for proper alignment inside a @code{COMMON} block. This warning can be turned
-off via @option{-Wno-align-commons}. See also @option{-falign-commons}.
-
-@item -Wfunction-elimination
-@opindex @code{Wfunction-elimination}
-@cindex function elimination
-@cindex warnings, function elimination
-Warn if any calls to impure functions are eliminated by the optimizations
-enabled by the @option{-ffrontend-optimize} option.
-This option is implied by @option{-Wextra}.
-
-@item -Wrealloc-lhs
-@opindex @code{Wrealloc-lhs}
-@cindex Reallocate the LHS in assignments, notification
-Warn when the compiler might insert code to for allocation or reallocation of
-an allocatable array variable of intrinsic type in intrinsic assignments. In
-hot loops, the Fortran 2003 reallocation feature may reduce the performance.
-If the array is already allocated with the correct shape, consider using a
-whole-array array-spec (e.g. @code{(:,:,:)}) for the variable on the left-hand
-side to prevent the reallocation check. Note that in some cases the warning
-is shown, even if the compiler will optimize reallocation checks away. For
-instance, when the right-hand side contains the same variable multiplied by
-a scalar. See also @option{-frealloc-lhs}.
-
-@item -Wrealloc-lhs-all
-@opindex @code{Wrealloc-lhs-all}
-Warn when the compiler inserts code to for allocation or reallocation of an
-allocatable variable; this includes scalars and derived types.
-
-@item -Wcompare-reals
-@opindex @code{Wcompare-reals}
-Warn when comparing real or complex types for equality or inequality.
-This option is implied by @option{-Wextra}.
-
-@item -Wtarget-lifetime
-@opindex @code{Wtargt-lifetime}
-Warn if the pointer in a pointer assignment might be longer than the its
-target. This option is implied by @option{-Wall}.
-
-@item -Wzerotrip
-@opindex @code{Wzerotrip}
-Warn if a @code{DO} loop is known to execute zero times at compile
-time. This option is implied by @option{-Wall}.
-
-@item -Wdo-subscript
-@opindex @code{Wdo-subscript}
-Warn if an array subscript inside a DO loop could lead to an
-out-of-bounds access even if the compiler cannot prove that the
-statement is actually executed, in cases like
-@smallexample
- real a(3)
- do i=1,4
- if (condition(i)) then
- a(i) = 1.2
- end if
- end do
-@end smallexample
-This option is implied by @option{-Wextra}.
-
-@item -Werror
-@opindex @code{Werror}
-@cindex warnings, to errors
-Turns all warnings into errors.
-@end table
-
-@xref{Warning Options,,Options to Request or Suppress Errors and
-Warnings, gcc,Using the GNU Compiler Collection (GCC)}, for information on
-more options offered by the GBE shared by @command{gfortran}, @command{gcc}
-and other GNU compilers.
-
-Some of these have no effect when compiling programs written in Fortran.
-
-@node Debugging Options
-@section Options for debugging your program or GNU Fortran
-@cindex options, debugging
-@cindex debugging information options
-
-GNU Fortran has various special options that are used for debugging
-either your program or the GNU Fortran compiler.
-
-@table @gcctabopt
-@item -fdump-fortran-original
-@opindex @code{fdump-fortran-original}
-Output the internal parse tree after translating the source program
-into internal representation. This option is mostly useful for
-debugging the GNU Fortran compiler itself. The output generated by
-this option might change between releases. This option may also
-generate internal compiler errors for features which have only
-recently been added.
-
-@item -fdump-fortran-optimized
-@opindex @code{fdump-fortran-optimized}
-Output the parse tree after front-end optimization. Mostly useful for
-debugging the GNU Fortran compiler itself. The output generated by
-this option might change between releases. This option may also
-generate internal compiler errors for features which have only
-recently been added.
-
-@item -fdump-parse-tree
-@opindex @code{fdump-parse-tree}
-Output the internal parse tree after translating the source program
-into internal representation. Mostly useful for debugging the GNU
-Fortran compiler itself. The output generated by this option might
-change between releases. This option may also generate internal
-compiler errors for features which have only recently been added. This
-option is deprecated; use @code{-fdump-fortran-original} instead.
-
-@item -fdebug-aux-vars
-@opindex @code{fdebug-aux-vars}
-Renames internal variables created by the gfortran front end and makes
-them accessible to a debugger. The name of the internal variables then
-start with upper-case letters followed by an underscore. This option is
-useful for debugging the compiler's code generation together with
-@code{-fdump-tree-original} and enabling debugging of the executable
-program by using @code{-g} or @code{-ggdb3}.
-
-@item -fdump-fortran-global
-@opindex @code{fdump-fortran-global}
-Output a list of the global identifiers after translating into
-middle-end representation. Mostly useful for debugging the GNU Fortran
-compiler itself. The output generated by this option might change
-between releases. This option may also generate internal compiler
-errors for features which have only recently been added.
-
-@item -ffpe-trap=@var{list}
-@opindex @code{ffpe-trap=}@var{list}
-Specify a list of floating point exception traps to enable. On most
-systems, if a floating point exception occurs and the trap for that
-exception is enabled, a SIGFPE signal will be sent and the program
-being aborted, producing a core file useful for debugging. @var{list}
-is a (possibly empty) comma-separated list of the following
-exceptions: @samp{invalid} (invalid floating point operation, such as
-@code{SQRT(-1.0)}), @samp{zero} (division by zero), @samp{overflow}
-(overflow in a floating point operation), @samp{underflow} (underflow
-in a floating point operation), @samp{inexact} (loss of precision
-during operation), and @samp{denormal} (operation performed on a
-denormal value). The first five exceptions correspond to the five
-IEEE 754 exceptions, whereas the last one (@samp{denormal}) is not
-part of the IEEE 754 standard but is available on some common
-architectures such as x86.
-
-The first three exceptions (@samp{invalid}, @samp{zero}, and
-@samp{overflow}) often indicate serious errors, and unless the program
-has provisions for dealing with these exceptions, enabling traps for
-these three exceptions is probably a good idea.
-
-If the option is used more than once in the command line, the lists will
-be joined: '@code{ffpe-trap=}@var{list1} @code{ffpe-trap=}@var{list2}'
-is equivalent to @code{ffpe-trap=}@var{list1},@var{list2}.
-
-Note that once enabled an exception cannot be disabled (no negative form).
-
-Many, if not most, floating point operations incur loss of precision
-due to rounding, and hence the @code{ffpe-trap=inexact} is likely to
-be uninteresting in practice.
-
-By default no exception traps are enabled.
-
-@item -ffpe-summary=@var{list}
-@opindex @code{ffpe-summary=}@var{list}
-Specify a list of floating-point exceptions, whose flag status is printed
-to @code{ERROR_UNIT} when invoking @code{STOP} and @code{ERROR STOP}.
-@var{list} can be either @samp{none}, @samp{all} or a comma-separated list
-of the following exceptions: @samp{invalid}, @samp{zero}, @samp{overflow},
-@samp{underflow}, @samp{inexact} and @samp{denormal}. (See
-@option{-ffpe-trap} for a description of the exceptions.)
-
-If the option is used more than once in the command line, only the
-last one will be used.
-
-By default, a summary for all exceptions but @samp{inexact} is shown.
-
-@item -fno-backtrace
-@opindex @code{fno-backtrace}
-@cindex backtrace
-@cindex trace
-When a serious runtime error is encountered or a deadly signal is
-emitted (segmentation fault, illegal instruction, bus error,
-floating-point exception, and the other POSIX signals that have the
-action @samp{core}), the Fortran runtime library tries to output a
-backtrace of the error. @code{-fno-backtrace} disables the backtrace
-generation. This option only has influence for compilation of the
-Fortran main program.
-
-@end table
-
-@xref{Debugging Options,,Options for Debugging Your Program or GCC,
-gcc,Using the GNU Compiler Collection (GCC)}, for more information on
-debugging options.
-
-@node Directory Options
-@section Options for directory search
-@cindex directory, options
-@cindex options, directory search
-@cindex search path
-@cindex @code{INCLUDE} directive
-@cindex directive, @code{INCLUDE}
-These options affect how GNU Fortran searches
-for files specified by the @code{INCLUDE} directive and where it searches
-for previously compiled modules.
-
-It also affects the search paths used by @command{cpp} when used to preprocess
-Fortran source.
-
-@table @gcctabopt
-@item -I@var{dir}
-@opindex @code{I}@var{dir}
-@cindex directory, search paths for inclusion
-@cindex inclusion, directory search paths for
-@cindex search paths, for included files
-@cindex paths, search
-@cindex module search path
-These affect interpretation of the @code{INCLUDE} directive
-(as well as of the @code{#include} directive of the @command{cpp}
-preprocessor).
-
-Also note that the general behavior of @option{-I} and
-@code{INCLUDE} is pretty much the same as of @option{-I} with
-@code{#include} in the @command{cpp} preprocessor, with regard to
-looking for @file{header.gcc} files and other such things.
-
-This path is also used to search for @file{.mod} files when previously
-compiled modules are required by a @code{USE} statement.
-
-@xref{Directory Options,,Options for Directory Search,
-gcc,Using the GNU Compiler Collection (GCC)}, for information on the
-@option{-I} option.
-
-@item -J@var{dir}
-@opindex @code{J}@var{dir}
-@opindex @code{M}@var{dir}
-@cindex paths, search
-@cindex module search path
-This option specifies where to put @file{.mod} files for compiled modules.
-It is also added to the list of directories to searched by an @code{USE}
-statement.
-
-The default is the current directory.
-
-@item -fintrinsic-modules-path @var{dir}
-@opindex @code{fintrinsic-modules-path} @var{dir}
-@cindex paths, search
-@cindex module search path
-This option specifies the location of pre-compiled intrinsic modules, if
-they are not in the default location expected by the compiler.
-@end table
-
-@node Link Options
-@section Influencing the linking step
-@cindex options, linking
-@cindex linking, static
-
-These options come into play when the compiler links object files into an
-executable output file. They are meaningless if the compiler is not doing
-a link step.
-
-@table @gcctabopt
-@item -static-libgfortran
-@opindex @code{static-libgfortran}
-On systems that provide @file{libgfortran} as a shared and a static
-library, this option forces the use of the static version. If no
-shared version of @file{libgfortran} was built when the compiler was
-configured, this option has no effect.
-@end table
-
-
-@table @gcctabopt
-@item -static-libquadmath
-@opindex @code{static-libquadmath}
-On systems that provide @file{libquadmath} as a shared and a static
-library, this option forces the use of the static version. If no
-shared version of @file{libquadmath} was built when the compiler was
-configured, this option has no effect.
-
-Please note that the @file{libquadmath} runtime library is licensed under the
-GNU Lesser General Public License (LGPL), and linking it statically introduces
-requirements when redistributing the resulting binaries.
-@end table
-
-
-@node Runtime Options
-@section Influencing runtime behavior
-@cindex options, runtime
-
-These options affect the runtime behavior of programs compiled with GNU Fortran.
-
-@table @gcctabopt
-@item -fconvert=@var{conversion}
-@opindex @code{fconvert=}@var{conversion}
-Specify the representation of data for unformatted files. Valid
-values for conversion on most systems are: @samp{native}, the default;
-@samp{swap}, swap between big- and little-endian; @samp{big-endian}, use
-big-endian representation for unformatted files; @samp{little-endian}, use
-little-endian representation for unformatted files.
-
-On POWER systems which suppport @option{-mabi=ieeelongdouble},
-there are additional options, which can be combined with others with
-commas. Those are
-@itemize @w{}
-@item @option{-fconvert=r16_ieee} Use IEEE 128-bit format for
-@code{REAL(KIND=16)}.
-@item @option{-fconvert=r16_ibm} Use IBM long double format for
-@code{REAL(KIND=16)}.
-@end itemize
-
-@emph{This option has an effect only when used in the main program.
-The @code{CONVERT} specifier and the GFORTRAN_CONVERT_UNIT environment
-variable override the default specified by @option{-fconvert}.}
-
-@item -frecord-marker=@var{length}
-@opindex @code{frecord-marker=}@var{length}
-Specify the length of record markers for unformatted files.
-Valid values for @var{length} are 4 and 8. Default is 4.
-@emph{This is different from previous versions of @command{gfortran}},
-which specified a default record marker length of 8 on most
-systems. If you want to read or write files compatible
-with earlier versions of @command{gfortran}, use @option{-frecord-marker=8}.
-
-@item -fmax-subrecord-length=@var{length}
-@opindex @code{fmax-subrecord-length=}@var{length}
-Specify the maximum length for a subrecord. The maximum permitted
-value for length is 2147483639, which is also the default. Only
-really useful for use by the gfortran testsuite.
-
-@item -fsign-zero
-@opindex @code{fsign-zero}
-When enabled, floating point numbers of value zero with the sign bit set
-are written as negative number in formatted output and treated as
-negative in the @code{SIGN} intrinsic. @option{-fno-sign-zero} does not
-print the negative sign of zero values (or values rounded to zero for I/O)
-and regards zero as positive number in the @code{SIGN} intrinsic for
-compatibility with Fortran 77. The default is @option{-fsign-zero}.
-@end table
-
-@node Code Gen Options
-@section Options for code generation conventions
-@cindex code generation, conventions
-@cindex options, code generation
-@cindex options, run-time
-
-These machine-independent options control the interface conventions
-used in code generation.
-
-Most of them have both positive and negative forms; the negative form
-of @option{-ffoo} would be @option{-fno-foo}. In the table below, only
-one of the forms is listed---the one which is not the default. You
-can figure out the other form by either removing @option{no-} or adding
-it.
-
-@table @gcctabopt
-@item -fno-automatic
-@opindex @code{fno-automatic}
-@cindex @code{SAVE} statement
-@cindex statement, @code{SAVE}
-Treat each program unit (except those marked as RECURSIVE) as if the
-@code{SAVE} statement were specified for every local variable and array
-referenced in it. Does not affect common blocks. (Some Fortran compilers
-provide this option under the name @option{-static} or @option{-save}.)
-The default, which is @option{-fautomatic}, uses the stack for local
-variables smaller than the value given by @option{-fmax-stack-var-size}.
-Use the option @option{-frecursive} to use no static memory.
-
-Local variables or arrays having an explicit @code{SAVE} attribute are
-silently ignored unless the @option{-pedantic} option is added.
-
-@item -ff2c
-@opindex ff2c
-@cindex calling convention
-@cindex @command{f2c} calling convention
-@cindex @command{g77} calling convention
-@cindex libf2c calling convention
-Generate code designed to be compatible with code generated
-by @command{g77} and @command{f2c}.
-
-The calling conventions used by @command{g77} (originally implemented
-in @command{f2c}) require functions that return type
-default @code{REAL} to actually return the C type @code{double}, and
-functions that return type @code{COMPLEX} to return the values via an
-extra argument in the calling sequence that points to where to
-store the return value. Under the default GNU calling conventions, such
-functions simply return their results as they would in GNU
-C---default @code{REAL} functions return the C type @code{float}, and
-@code{COMPLEX} functions return the GNU C type @code{complex}.
-Additionally, this option implies the @option{-fsecond-underscore}
-option, unless @option{-fno-second-underscore} is explicitly requested.
-
-This does not affect the generation of code that interfaces with
-the @command{libgfortran} library.
-
-@emph{Caution:} It is not a good idea to mix Fortran code compiled with
-@option{-ff2c} with code compiled with the default @option{-fno-f2c}
-calling conventions as, calling @code{COMPLEX} or default @code{REAL}
-functions between program parts which were compiled with different
-calling conventions will break at execution time.
-
-@emph{Caution:} This will break code which passes intrinsic functions
-of type default @code{REAL} or @code{COMPLEX} as actual arguments, as
-the library implementations use the @option{-fno-f2c} calling conventions.
-
-@item -fno-underscoring
-@opindex @code{fno-underscoring}
-@cindex underscore
-@cindex symbol names, underscores
-@cindex transforming symbol names
-@cindex symbol names, transforming
-Do not transform names of entities specified in the Fortran
-source file by appending underscores to them.
-
-With @option{-funderscoring} in effect, GNU Fortran appends one
-underscore to external names with no underscores. This is done to ensure
-compatibility with code produced by many UNIX Fortran compilers.
-
-@emph{Caution}: The default behavior of GNU Fortran is
-incompatible with @command{f2c} and @command{g77}, please use the
-@option{-ff2c} option if you want object files compiled with
-GNU Fortran to be compatible with object code created with these
-tools.
-
-Use of @option{-fno-underscoring} is not recommended unless you are
-experimenting with issues such as integration of GNU Fortran into
-existing system environments (vis-@`{a}-vis existing libraries, tools,
-and so on).
-
-For example, with @option{-funderscoring}, and assuming that @code{j()} and
-@code{max_count()} are external functions while @code{my_var} and
-@code{lvar} are local variables, a statement like
-@smallexample
-I = J() + MAX_COUNT (MY_VAR, LVAR)
-@end smallexample
-@noindent
-is implemented as something akin to:
-@smallexample
-i = j_() + max_count__(&my_var__, &lvar);
-@end smallexample
-
-With @option{-fno-underscoring}, the same statement is implemented as:
-
-@smallexample
-i = j() + max_count(&my_var, &lvar);
-@end smallexample
-
-Use of @option{-fno-underscoring} allows direct specification of
-user-defined names while debugging and when interfacing GNU Fortran
-code with other languages.
-
-Note that just because the names match does @emph{not} mean that the
-interface implemented by GNU Fortran for an external name matches the
-interface implemented by some other language for that same name.
-That is, getting code produced by GNU Fortran to link to code produced
-by some other compiler using this or any other method can be only a
-small part of the overall solution---getting the code generated by
-both compilers to agree on issues other than naming can require
-significant effort, and, unlike naming disagreements, linkers normally
-cannot detect disagreements in these other areas.
-
-Also, note that with @option{-fno-underscoring}, the lack of appended
-underscores introduces the very real possibility that a user-defined
-external name will conflict with a name in a system library, which
-could make finding unresolved-reference bugs quite difficult in some
-cases---they might occur at program run time, and show up only as
-buggy behavior at run time.
-
-In future versions of GNU Fortran we hope to improve naming and linking
-issues so that debugging always involves using the names as they appear
-in the source, even if the names as seen by the linker are mangled to
-prevent accidental linking between procedures with incompatible
-interfaces.
-
-@item -fsecond-underscore
-@opindex @code{fsecond-underscore}
-@cindex underscore
-@cindex symbol names, underscores
-@cindex transforming symbol names
-@cindex symbol names, transforming
-@cindex @command{f2c} calling convention
-@cindex @command{g77} calling convention
-@cindex libf2c calling convention
-By default, GNU Fortran appends an underscore to external
-names. If this option is used GNU Fortran appends two
-underscores to names with underscores and one underscore to external names
-with no underscores. GNU Fortran also appends two underscores to
-internal names with underscores to avoid naming collisions with external
-names.
-
-This option has no effect if @option{-fno-underscoring} is
-in effect. It is implied by the @option{-ff2c} option.
-
-Otherwise, with this option, an external name such as @code{MAX_COUNT}
-is implemented as a reference to the link-time external symbol
-@code{max_count__}, instead of @code{max_count_}. This is required
-for compatibility with @command{g77} and @command{f2c}, and is implied
-by use of the @option{-ff2c} option.
-
-@item -fcoarray=@var{<keyword>}
-@opindex @code{fcoarray}
-@cindex coarrays
-
-@table @asis
-@item @samp{none}
-Disable coarray support; using coarray declarations and image-control
-statements will produce a compile-time error. (Default)
-
-@item @samp{single}
-Single-image mode, i.e. @code{num_images()} is always one.
-
-@item @samp{lib}
-Library-based coarray parallelization; a suitable GNU Fortran coarray
-library needs to be linked.
-@end table
-
-
-@item -fcheck=@var{<keyword>}
-@opindex @code{fcheck}
-@cindex array, bounds checking
-@cindex bit intrinsics checking
-@cindex bounds checking
-@cindex pointer checking
-@cindex memory checking
-@cindex range checking
-@cindex subscript checking
-@cindex checking subscripts
-@cindex run-time checking
-@cindex checking array temporaries
-
-Enable the generation of run-time checks; the argument shall be
-a comma-delimited list of the following keywords. Prefixing a check with
-@option{no-} disables it if it was activated by a previous specification.
-
-@table @asis
-@item @samp{all}
-Enable all run-time test of @option{-fcheck}.
-
-@item @samp{array-temps}
-Warns at run time when for passing an actual argument a temporary array
-had to be generated. The information generated by this warning is
-sometimes useful in optimization, in order to avoid such temporaries.
-
-Note: The warning is only printed once per location.
-
-@item @samp{bits}
-Enable generation of run-time checks for invalid arguments to the bit
-manipulation intrinsics.
-
-@item @samp{bounds}
-Enable generation of run-time checks for array subscripts
-and against the declared minimum and maximum values. It also
-checks array indices for assumed and deferred
-shape arrays against the actual allocated bounds and ensures that all string
-lengths are equal for character array constructors without an explicit
-typespec.
-
-Some checks require that @option{-fcheck=bounds} is set for
-the compilation of the main program.
-
-Note: In the future this may also include other forms of checking, e.g.,
-checking substring references.
-
-@item @samp{do}
-Enable generation of run-time checks for invalid modification of loop
-iteration variables.
-
-@item @samp{mem}
-Enable generation of run-time checks for memory allocation.
-Note: This option does not affect explicit allocations using the
-@code{ALLOCATE} statement, which will be always checked.
-
-@item @samp{pointer}
-Enable generation of run-time checks for pointers and allocatables.
-
-@item @samp{recursion}
-Enable generation of run-time checks for recursively called subroutines and
-functions which are not marked as recursive. See also @option{-frecursive}.
-Note: This check does not work for OpenMP programs and is disabled if used
-together with @option{-frecursive} and @option{-fopenmp}.
-@end table
-
-Example: Assuming you have a file @file{foo.f90}, the command
-@smallexample
- gfortran -fcheck=all,no-array-temps foo.f90
-@end smallexample
-will compile the file with all checks enabled as specified above except
-warnings for generated array temporaries.
-
-
-@item -fbounds-check
-@opindex @code{fbounds-check}
-@c Note: This option is also referred in gcc's manpage
-Deprecated alias for @option{-fcheck=bounds}.
-
-@item -ftail-call-workaround
-@itemx -ftail-call-workaround=@var{n}
-@opindex @code{tail-call-workaround}
-Some C interfaces to Fortran codes violate the gfortran ABI by
-omitting the hidden character length arguments as described in
-@xref{Argument passing conventions}. This can lead to crashes
-because pushing arguments for tail calls can overflow the stack.
-
-To provide a workaround for existing binary packages, this option
-disables tail call optimization for gfortran procedures with character
-arguments. With @option{-ftail-call-workaround=2} tail call optimization
-is disabled in all gfortran procedures with character arguments,
-with @option{-ftail-call-workaround=1} or equivalent
-@option{-ftail-call-workaround} only in gfortran procedures with character
-arguments that call implicitly prototyped procedures.
-
-Using this option can lead to problems including crashes due to
-insufficient stack space.
-
-It is @emph{very strongly} recommended to fix the code in question.
-The @option{-fc-prototypes-external} option can be used to generate
-prototypes which conform to gfortran's ABI, for inclusion in the
-source code.
-
-Support for this option will likely be withdrawn in a future release
-of gfortran.
-
-The negative form, @option{-fno-tail-call-workaround} or equivalent
-@option{-ftail-call-workaround=0}, can be used to disable this option.
-
-Default is currently @option{-ftail-call-workaround}, this will change
-in future releases.
-
-@item -fcheck-array-temporaries
-@opindex @code{fcheck-array-temporaries}
-Deprecated alias for @option{-fcheck=array-temps}.
-
-@item -fmax-array-constructor=@var{n}
-@opindex @code{fmax-array-constructor}
-This option can be used to increase the upper limit permitted in
-array constructors. The code below requires this option to expand
-the array at compile time.
-
-@smallexample
-program test
-implicit none
-integer j
-integer, parameter :: n = 100000
-integer, parameter :: i(n) = (/ (2*j, j = 1, n) /)
-print '(10(I0,1X))', i
-end program test
-@end smallexample
-
-@emph{Caution: This option can lead to long compile times and excessively
-large object files.}
-
-The default value for @var{n} is 65535.
-
-
-@item -fmax-stack-var-size=@var{n}
-@opindex @code{fmax-stack-var-size}
-This option specifies the size in bytes of the largest array that will be put
-on the stack; if the size is exceeded static memory is used (except in
-procedures marked as RECURSIVE). Use the option @option{-frecursive} to
-allow for recursive procedures which do not have a RECURSIVE attribute or
-for parallel programs. Use @option{-fno-automatic} to never use the stack.
-
-This option currently only affects local arrays declared with constant
-bounds, and may not apply to all character variables.
-Future versions of GNU Fortran may improve this behavior.
-
-The default value for @var{n} is 65536.
-
-@item -fstack-arrays
-@opindex @code{fstack-arrays}
-Adding this option will make the Fortran compiler put all arrays of
-unknown size and array temporaries onto stack memory. If your program uses very
-large local arrays it is possible that you will have to extend your runtime
-limits for stack memory on some operating systems. This flag is enabled
-by default at optimization level @option{-Ofast} unless
-@option{-fmax-stack-var-size} is specified.
-
-@item -fpack-derived
-@opindex @code{fpack-derived}
-@cindex structure packing
-This option tells GNU Fortran to pack derived type members as closely as
-possible. Code compiled with this option is likely to be incompatible
-with code compiled without this option, and may execute slower.
-
-@item -frepack-arrays
-@opindex @code{frepack-arrays}
-@cindex repacking arrays
-In some circumstances GNU Fortran may pass assumed shape array
-sections via a descriptor describing a noncontiguous area of memory.
-This option adds code to the function prologue to repack the data into
-a contiguous block at runtime.
-
-This should result in faster accesses to the array. However it can introduce
-significant overhead to the function call, especially when the passed data
-is noncontiguous.
-
-@item -fshort-enums
-@opindex @code{fshort-enums}
-This option is provided for interoperability with C code that was
-compiled with the @option{-fshort-enums} option. It will make
-GNU Fortran choose the smallest @code{INTEGER} kind a given
-enumerator set will fit in, and give all its enumerators this kind.
-
-@item -finline-arg-packing
-@opindex @code{finline-arg-packing}
-When passing an assumed-shape argument of a procedure as actual
-argument to an assumed-size or explicit size or as argument to a
-procedure that does not have an explicit interface, the argument may
-have to be packed, that is put into contiguous memory. An example is
-the call to @code{foo} in
-@smallexample
- subroutine foo(a)
- real, dimension(*) :: a
- end subroutine foo
- subroutine bar(b)
- real, dimension(:) :: b
- call foo(b)
- end subroutine bar
-@end smallexample
-
-When @option{-finline-arg-packing} is in effect, this packing will be
-performed by inline code. This allows for more optimization while
-increasing code size.
-
-@option{-finline-arg-packing} is implied by any of the @option{-O} options
-except when optimizing for size via @option{-Os}. If the code
-contains a very large number of argument that have to be packed, code
-size and also compilation time may become excessive. If that is the
-case, it may be better to disable this option. Instances of packing
-can be found by using @option{-Warray-temporaries}.
-
-@item -fexternal-blas
-@opindex @code{fexternal-blas}
-This option will make @command{gfortran} generate calls to BLAS functions
-for some matrix operations like @code{MATMUL}, instead of using our own
-algorithms, if the size of the matrices involved is larger than a given
-limit (see @option{-fblas-matmul-limit}). This may be profitable if an
-optimized vendor BLAS library is available. The BLAS library will have
-to be specified at link time.
-
-@item -fblas-matmul-limit=@var{n}
-@opindex @code{fblas-matmul-limit}
-Only significant when @option{-fexternal-blas} is in effect.
-Matrix multiplication of matrices with size larger than (or equal to) @var{n}
-will be performed by calls to BLAS functions, while others will be
-handled by @command{gfortran} internal algorithms. If the matrices
-involved are not square, the size comparison is performed using the
-geometric mean of the dimensions of the argument and result matrices.
-
-The default value for @var{n} is 30.
-
-@item -finline-matmul-limit=@var{n}
-@opindex @code{finline-matmul-limit}
-When front-end optimization is active, some calls to the @code{MATMUL}
-intrinsic function will be inlined. This may result in code size
-increase if the size of the matrix cannot be determined at compile
-time, as code for both cases is generated. Setting
-@code{-finline-matmul-limit=0} will disable inlining in all cases.
-Setting this option with a value of @var{n} will produce inline code
-for matrices with size up to @var{n}. If the matrices involved are not
-square, the size comparison is performed using the geometric mean of
-the dimensions of the argument and result matrices.
-
-The default value for @var{n} is 30. The @code{-fblas-matmul-limit}
-can be used to change this value.
-
-@item -frecursive
-@opindex @code{frecursive}
-Allow indirect recursion by forcing all local arrays to be allocated
-on the stack. This flag cannot be used together with
-@option{-fmax-stack-var-size=} or @option{-fno-automatic}.
-
-@item -finit-local-zero
-@itemx -finit-derived
-@itemx -finit-integer=@var{n}
-@itemx -finit-real=@var{<zero|inf|-inf|nan|snan>}
-@itemx -finit-logical=@var{<true|false>}
-@itemx -finit-character=@var{n}
-@opindex @code{finit-local-zero}
-@opindex @code{finit-derived}
-@opindex @code{finit-integer}
-@opindex @code{finit-real}
-@opindex @code{finit-logical}
-@opindex @code{finit-character}
-The @option{-finit-local-zero} option instructs the compiler to
-initialize local @code{INTEGER}, @code{REAL}, and @code{COMPLEX}
-variables to zero, @code{LOGICAL} variables to false, and
-@code{CHARACTER} variables to a string of null bytes. Finer-grained
-initialization options are provided by the
-@option{-finit-integer=@var{n}},
-@option{-finit-real=@var{<zero|inf|-inf|nan|snan>}} (which also initializes
-the real and imaginary parts of local @code{COMPLEX} variables),
-@option{-finit-logical=@var{<true|false>}}, and
-@option{-finit-character=@var{n}} (where @var{n} is an ASCII character
-value) options.
-
-With @option{-finit-derived}, components of derived type variables will be
-initialized according to these flags. Components whose type is not covered by
-an explicit @option{-finit-*} flag will be treated as described above with
-@option{-finit-local-zero}.
-
-These options do not initialize
-@itemize @bullet
-@item
-objects with the POINTER attribute
-@item
-allocatable arrays
-@item
-variables that appear in an @code{EQUIVALENCE} statement.
-@end itemize
-(These limitations may be removed in future releases).
-
-Note that the @option{-finit-real=nan} option initializes @code{REAL}
-and @code{COMPLEX} variables with a quiet NaN. For a signalling NaN
-use @option{-finit-real=snan}; note, however, that compile-time
-optimizations may convert them into quiet NaN and that trapping
-needs to be enabled (e.g. via @option{-ffpe-trap}).
-
-The @option{-finit-integer} option will parse the value into an
-integer of type @code{INTEGER(kind=C_LONG)} on the host. Said value
-is then assigned to the integer variables in the Fortran code, which
-might result in wraparound if the value is too large for the kind.
-
-Finally, note that enabling any of the @option{-finit-*} options will
-silence warnings that would have been emitted by @option{-Wuninitialized}
-for the affected local variables.
-
-@item -falign-commons
-@opindex @code{falign-commons}
-@cindex alignment of @code{COMMON} blocks
-By default, @command{gfortran} enforces proper alignment of all variables in a
-@code{COMMON} block by padding them as needed. On certain platforms this is mandatory,
-on others it increases performance. If a @code{COMMON} block is not declared with
-consistent data types everywhere, this padding can cause trouble, and
-@option{-fno-align-commons} can be used to disable automatic alignment. The
-same form of this option should be used for all files that share a @code{COMMON} block.
-To avoid potential alignment issues in @code{COMMON} blocks, it is recommended to order
-objects from largest to smallest.
-
-@item -fno-protect-parens
-@opindex @code{fno-protect-parens}
-@cindex re-association of parenthesized expressions
-By default the parentheses in expression are honored for all optimization
-levels such that the compiler does not do any re-association. Using
-@option{-fno-protect-parens} allows the compiler to reorder @code{REAL} and
-@code{COMPLEX} expressions to produce faster code. Note that for the re-association
-optimization @option{-fno-signed-zeros} and @option{-fno-trapping-math}
-need to be in effect. The parentheses protection is enabled by default, unless
-@option{-Ofast} is given.
-
-@item -frealloc-lhs
-@opindex @code{frealloc-lhs}
-@cindex Reallocate the LHS in assignments
-An allocatable left-hand side of an intrinsic assignment is automatically
-(re)allocated if it is either unallocated or has a different shape. The
-option is enabled by default except when @option{-std=f95} is given. See
-also @option{-Wrealloc-lhs}.
-
-@item -faggressive-function-elimination
-@opindex @code{faggressive-function-elimination}
-@cindex Elimination of functions with identical argument lists
-Functions with identical argument lists are eliminated within
-statements, regardless of whether these functions are marked
-@code{PURE} or not. For example, in
-@smallexample
- a = f(b,c) + f(b,c)
-@end smallexample
-there will only be a single call to @code{f}. This option only works
-if @option{-ffrontend-optimize} is in effect.
-
-@item -ffrontend-optimize
-@opindex @code{frontend-optimize}
-@cindex Front-end optimization
-This option performs front-end optimization, based on manipulating
-parts the Fortran parse tree. Enabled by default by any @option{-O} option
-except @option{-O0} and @option{-Og}. Optimizations enabled by this option
-include:
-@itemize @bullet
-@item inlining calls to @code{MATMUL},
-@item elimination of identical function calls within expressions,
-@item removing unnecessary calls to @code{TRIM} in comparisons and assignments,
-@item replacing @code{TRIM(a)} with @code{a(1:LEN_TRIM(a))} and
-@item short-circuiting of logical operators (@code{.AND.} and @code{.OR.}).
-@end itemize
-It can be deselected by specifying @option{-fno-frontend-optimize}.
-
-@item -ffrontend-loop-interchange
-@opindex @code{frontend-loop-interchange}
-@cindex loop interchange, Fortran
-Attempt to interchange loops in the Fortran front end where
-profitable. Enabled by default by any @option{-O} option.
-At the moment, this option only affects @code{FORALL} and
-@code{DO CONCURRENT} statements with several forall triplets.
-@end table
-
-@xref{Code Gen Options,,Options for Code Generation Conventions,
-gcc,Using the GNU Compiler Collection (GCC)}, for information on more options
-offered by the GBE
-shared by @command{gfortran}, @command{gcc}, and other GNU compilers.
-
-@c man end
-
-@node Interoperability Options
-@section Options for interoperability with other languages
-
-@table @asis
-
-@item -fc-prototypes
-@opindex @code{c-prototypes}
-@cindex Generating C prototypes from Fortran BIND(C) enteties
-This option will generate C prototypes from @code{BIND(C)} variable
-declarations, types and procedure interfaces and writes them to
-standard output. @code{ENUM} is not yet supported.
-
-The generated prototypes may need inclusion of an appropriate header,
-such as @code{<stdint.h>} or @code{<stdlib.h>}. For types which are
-not specified using the appropriate kind from the @code{iso_c_binding}
-module, a warning is added as a comment to the code.
-
-For function pointers, a pointer to a function returning @code{int}
-without an explicit argument list is generated.
-
-Example of use:
-@smallexample
-$ gfortran -fc-prototypes -fsyntax-only foo.f90 > foo.h
-@end smallexample
-where the C code intended for interoperating with the Fortran code
-then uses @code{#include "foo.h"}.
-
-@item -fc-prototypes-external
-@opindex @code{c-prototypes-external}
-@cindex Generating C prototypes from external procedures
-This option will generate C prototypes from external functions and
-subroutines and write them to standard output. This may be useful for
-making sure that C bindings to Fortran code are correct. This option
-does not generate prototypes for @code{BIND(C)} procedures, use
-@option{-fc-prototypes} for that.
-
-The generated prototypes may need inclusion of an appropriate
-header, such as @code{<stdint.h>} or @code{<stdlib.h>}.
-
-This is primarily meant for legacy code to ensure that existing C
-bindings match what @command{gfortran} emits. The generated C
-prototypes should be correct for the current version of the compiler,
-but may not match what other compilers or earlier versions of
-@command{gfortran} need. For new developments, use of the
-@code{BIND(C)} features is recommended.
-
-Example of use:
-@smallexample
-$ gfortran -fc-prototypes-external -fsyntax-only foo.f > foo.h
-@end smallexample
-where the C code intended for interoperating with the Fortran code
-then uses @code{#include "foo.h"}.
-@end table
-
-@node Environment Variables
-@section Environment variables affecting @command{gfortran}
-@cindex environment variable
-
-@c man begin ENVIRONMENT
-
-The @command{gfortran} compiler currently does not make use of any environment
-variables to control its operation above and beyond those
-that affect the operation of @command{gcc}.
-
-@xref{Environment Variables,,Environment Variables Affecting GCC,
-gcc,Using the GNU Compiler Collection (GCC)}, for information on environment
-variables.
-
-@xref{Runtime}, for environment variables that affect the
-run-time behavior of programs compiled with GNU Fortran.
-@c man end
+++ /dev/null
-\input texinfo @c -*-texinfo-*-
-@setfilename gccgo.info
-@settitle The GNU Go Compiler
-
-@c Merge the standard indexes into a single one.
-@syncodeindex fn cp
-@syncodeindex vr cp
-@syncodeindex ky cp
-@syncodeindex pg cp
-@syncodeindex tp cp
-
-@include gcc-common.texi
-
-@c Copyright years for this manual.
-@set copyrights-go 2010-2022
-
-@copying
-@c man begin COPYRIGHT
-Copyright @copyright{} @value{copyrights-go} Free Software Foundation, Inc.
-
-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, the Front-Cover Texts being (a) (see below), and
-with the Back-Cover Texts being (b) (see below).
-A copy of the license is included in the
-@c man end
-section entitled ``GNU Free Documentation License''.
-@ignore
-@c man begin COPYRIGHT
-man page gfdl(7).
-@c man end
-@end ignore
-
-@c man begin COPYRIGHT
-
-(a) The FSF's Front-Cover Text is:
-
- A GNU Manual
-
-(b) The FSF's Back-Cover Text is:
-
- You have freedom to copy and modify this GNU Manual, like GNU
- software. Copies published by the Free Software Foundation raise
- funds for GNU development.
-@c man end
-@end copying
-
-@ifinfo
-@format
-@dircategory Software development
-@direntry
-* Gccgo: (gccgo). A GCC-based compiler for the Go language
-@end direntry
-@end format
-
-@insertcopying
-@end ifinfo
-
-@titlepage
-@title The GNU Go Compiler
-@versionsubtitle
-@author Ian Lance Taylor
-
-@page
-@vskip 0pt plus 1filll
-Published by the Free Software Foundation @*
-51 Franklin Street, Fifth Floor@*
-Boston, MA 02110-1301, USA@*
-@sp 1
-@insertcopying
-@end titlepage
-@contents
-@page
-
-@node Top
-@top Introduction
-
-This manual describes how to use @command{gccgo}, the GNU compiler for
-the Go programming language. This manual is specifically about
-@command{gccgo}. For more information about the Go programming
-language in general, including language specifications and standard
-package documentation, see @uref{https://golang.org/}.
-
-@menu
-* Copying:: The GNU General Public License.
-* GNU Free Documentation License::
- How you can share and copy this manual.
-* Invoking gccgo:: How to run gccgo.
-* Import and Export:: Importing and exporting package data.
-* Compiler Directives:: Comments to control compilation.
-* C Interoperability:: Calling C from Go and vice-versa.
-* Index:: Index.
-@end menu
-
-
-@include gpl_v3.texi
-
-@include fdl.texi
-
-
-@node Invoking gccgo
-@chapter Invoking gccgo
-
-@c man title gccgo A GCC-based compiler for the Go language
-
-@ignore
-@c man begin SYNOPSIS gccgo
-gccgo [@option{-c}|@option{-S}]
- [@option{-g}] [@option{-pg}] [@option{-O}@var{level}]
- [@option{-I}@var{dir}@dots{}] [@option{-L}@var{dir}@dots{}]
- [@option{-o} @var{outfile}] @var{infile}@dots{}
-
-Only the most useful options are listed here; see below for the
-remainder.
-@c man end
-@c man begin SEEALSO
-gpl(7), gfdl(7), fsf-funding(7), gcc(1)
-and the Info entries for @file{gccgo} and @file{gcc}.
-@c man end
-@end ignore
-
-@c man begin DESCRIPTION gccgo
-
-The @command{gccgo} command is a frontend to @command{gcc} and
-supports many of the same options. @xref{Option Summary, , Option
-Summary, gcc, Using the GNU Compiler Collection (GCC)}. This manual
-only documents the options specific to @command{gccgo}.
-
-The @command{gccgo} command may be used to compile Go source code into
-an object file, link a collection of object files together, or do both
-in sequence.
-
-Go source code is compiled as packages. A package consists of one or
-more Go source files. All the files in a single package must be
-compiled together, by passing all the files as arguments to
-@command{gccgo}. A single invocation of @command{gccgo} may only
-compile a single package.
-
-One Go package may @code{import} a different Go package. The imported
-package must have already been compiled; @command{gccgo} will read
-the import data directly from the compiled package. When this package
-is later linked, the compiled form of the package must be included in
-the link command.
-
-Go programs must generally be compiled with debugging information, and
-@option{-g1} is the default as described below. Stripping a Go
-program will generally cause it to misbehave or fail.
-
-@c man end
-
-@c man begin OPTIONS gccgo
-
-@table @gcctabopt
-@item -I@var{dir}
-@cindex @option{-I}
-Specify a directory to use when searching for an import package at
-compile time.
-
-@item -L@var{dir}
-@cindex @option{-L}
-When linking, specify a library search directory, as with
-@command{gcc}.
-
-@item -fgo-pkgpath=@var{string}
-@cindex @option{-fgo-pkgpath}
-Set the package path to use. This sets the value returned by the
-PkgPath method of reflect.Type objects. It is also used for the names
-of globally visible symbols. The argument to this option should
-normally be the string that will be used to import this package after
-it has been installed; in other words, a pathname within the
-directories specified by the @option{-I} option.
-
-@item -fgo-prefix=@var{string}
-@cindex @option{-fgo-prefix}
-An alternative to @option{-fgo-pkgpath}. The argument will be
-combined with the package name from the source file to produce the
-package path. If @option{-fgo-pkgpath} is used, @option{-fgo-prefix}
-will be ignored.
-
-Go permits a single program to include more than one package with the
-same name in the @code{package} clause in the source file, though
-obviously the two packages must be imported using different pathnames.
-In order for this to work with @command{gccgo}, either
-@option{-fgo-pkgpath} or @option{-fgo-prefix} must be specified when
-compiling a package.
-
-Using either @option{-fgo-pkgpath} or @option{-fgo-prefix} disables
-the special treatment of the @code{main} package and permits that
-package to be imported like any other.
-
-@item -fgo-relative-import-path=@var{dir}
-@cindex @option{-fgo-relative-import-path}
-A relative import is an import that starts with @file{./} or
-@file{../}. If this option is used, @command{gccgo} will use
-@var{dir} as a prefix for the relative import when searching for it.
-
-@item -frequire-return-statement
-@itemx -fno-require-return-statement
-@cindex @option{-frequire-return-statement}
-@cindex @option{-fno-require-return-statement}
-By default @command{gccgo} will warn about functions which have one or
-more return parameters but lack an explicit @code{return} statement.
-This warning may be disabled using
-@option{-fno-require-return-statement}.
-
-@item -fgo-check-divide-zero
-@cindex @option{-fgo-check-divide-zero}
-@cindex @option{-fno-go-check-divide-zero}
-Add explicit checks for division by zero. In Go a division (or
-modulos) by zero causes a panic. On Unix systems this is detected in
-the runtime by catching the @code{SIGFPE} signal. Some processors,
-such as PowerPC, do not generate a SIGFPE on division by zero. Some
-runtimes do not generate a signal that can be caught. On those
-systems, this option may be used. Or the checks may be removed via
-@option{-fno-go-check-divide-zero}. This option is currently on by
-default, but in the future may be off by default on systems that do
-not require it.
-
-@item -fgo-check-divide-overflow
-@cindex @option{-fgo-check-divide-overflow}
-@cindex @option{-fno-go-check-divide-overflow}
-Add explicit checks for division overflow. For example, division
-overflow occurs when computing @code{INT_MIN / -1}. In Go this should
-be wrapped, to produce @code{INT_MIN}. Some processors, such as x86,
-generate a trap on division overflow. On those systems, this option
-may be used. Or the checks may be removed via
-@option{-fno-go-check-divide-overflow}. This option is currently on
-by default, but in the future may be off by default on systems that do
-not require it.
-
-@item -fno-go-optimize-allocs
-@cindex @option{-fno-go-optimize-allocs}
-Disable escape analysis, which tries to allocate objects on the stack
-rather than the heap.
-
-@item -fgo-debug-escape@var{n}
-@cindex @option{-fgo-debug-escape}
-Output escape analysis debugging information. Larger values of
-@var{n} generate more information.
-
-@item -fgo-debug-escape-hash=@var{n}
-@cindex @option{-fgo-debug-escape-hash}
-A hash value to debug escape analysis. @var{n} is a binary string.
-This runs escape analysis only on functions whose names hash to values
-that match the given suffix @var{n}. This can be used to binary
-search across functions to uncover escape analysis bugs.
-
-@item -fgo-debug-optimization
-@cindex @option{-fgo-debug-optimization}
-@cindex @option{-fno-go-debug-optimization}
-Output optimization diagnostics.
-
-@item -fgo-c-header=@var{file}
-@cindex @option{-fgo-c-header}
-Write top-level named Go struct definitions to @var{file} as C code.
-This is used when compiling the runtime package.
-
-@item -fgo-compiling-runtime
-@cindex @option{-fgo-compiling-runtime}
-Apply special rules for compiling the runtime package. Implicit
-memory allocation is forbidden. Some additional compiler directives
-are supported.
-
-@item -fgo-embedcfg=@var{file}
-@cindex @option{-fgo-embedcfg}
-Identify a JSON file used to map patterns used with special
-@code{//go:embed} comments to the files named by the patterns. The
-JSON file should have two components: @code{Patterns} maps each
-pattern to a list of file names, and @code{Files} maps each file name
-to a full path to the file. This option is intended for use by the
-@command{go} command to implement @code{//go:embed}.
-
-@item -g
-@cindex @option{-g for gccgo}
-This is the standard @command{gcc} option (@pxref{Debugging Options, ,
-Debugging Options, gcc, Using the GNU Compiler Collection (GCC)}). It
-is mentioned here because by default @command{gccgo} turns on
-debugging information generation with the equivalent of the standard
-option @option{-g1}. This is because Go programs require debugging
-information to be available in order to get backtrace information. An
-explicit @option{-g0} may be used to disable the generation of
-debugging information, in which case certain standard library
-functions, such as @code{runtime.Callers}, will not operate correctly.
-@end table
-
-@c man end
-
-@node Import and Export
-@chapter Import and Export
-
-When @command{gccgo} compiles a package which exports anything, the
-export information will be stored directly in the object file. When a
-package is imported, @command{gccgo} must be able to find the file.
-
-@cindex @file{.gox}
-When Go code imports the package @file{@var{gopackage}}, @command{gccgo}
-will look for the import data using the following filenames, using the
-first one that it finds.
-
-@table @file
-@item @var{gopackage}.gox
-@item lib@var{gopackage}.so
-@item lib@var{gopackage}.a
-@item @var{gopackage}.o
-@end table
-
-The compiler will search for these files in the directories named by
-any @option{-I} options, in order in which the directories appear on
-the command line. The compiler will then search several standard
-system directories. Finally the compiler will search the current
-directory (to search the current directory earlier, use @samp{-I.}).
-
-The compiler will extract the export information directly from the
-compiled object file. The file @file{@var{gopackage}.gox} will
-typically contain nothing but export data. This can be generated from
-@file{@var{gopackage}.o} via
-
-@smallexample
-objcopy -j .go_export @var{gopackage}.o @var{gopackage}.gox
-@end smallexample
-
-For example, it may be desirable to extract the export information
-from several different packages into their independent
-@file{@var{gopackage}.gox} files, and then to combine the different
-package object files together into a single shared library or archive.
-
-At link time you must explicitly tell @command{gccgo} which files to
-link together into the executable, as is usual with @command{gcc}.
-This is different from the behavior of other Go compilers.
-
-@node Compiler Directives
-@chapter Compiler Directives
-
-The Go compiler supports a few compiler directives. A compiler
-directive uses a @code{//} comment at the start of a line. There must
-be no space between the @code{//} and the name of the directive.
-
-@table @code
-@item //line @var{file}:@var{line}
-The @code{//line} directive specifies that the source line that
-follows should be recorded as having come from the given file path and
-line number. Successive lines are recorded using increasing line
-numbers, until the next directive. This directive typically appears
-in machine-generated code, so that compilers and debuggers will show
-lines in the original input to the generator.
-
-@item //extern @var{extern_name}
-The @code{extern} directive sets the externally visible name of the
-next function declaration. See @ref{Function Names}.
-
-@item //go:compile @var{go_name} @var{extern_name}
-The @code{go:compile} directives sets the externally visible name of a
-function definition or declaration. See @ref{Function Names}.
-
-@item //go:noescape
-The @code{//go:noescape} directive specifies that the next declaration
-in the file, which must be a func without a body (meaning that it has
-an implementation not written in Go) does not allow any of the
-pointers passed as arguments to escape into the heap or into the
-values returned from the function. This information can be used during
-the compiler's escape analysis of Go code calling the function.
-
-@item //go:nosplit
-The @code{//go:nosplit} directive specifies that the next function
-declared in the file must not include a stack overflow check. This is
-most commonly used by low-level runtime sources invoked at times when
-it is unsafe for the calling goroutine to be preempted.
-
-@item //go:noinline
-The @code{//go:noinline} directive specifies that the next function
-defined in the file may not be inlined.
-
-@end table
-
-@node C Interoperability
-@chapter C Interoperability
-
-When using @command{gccgo} there is limited interoperability with C,
-or with C++ code compiled using @code{extern "C"}.
-
-This information is provided largely for documentation purposes. For
-ordinary use it is best to build programs with the go tool and then
-use @code{import "C"}, as described at
-@url{https://golang.org/cmd/cgo}.
-
-@menu
-* C Type Interoperability:: How C and Go types match up.
-* Function Names:: How Go functions are named.
-@end menu
-
-@node C Type Interoperability
-@section C Type Interoperability
-
-Basic types map directly: an @code{int} in Go is an @code{int} in C,
-etc. Go @code{byte} is equivalent to C @code{unsigned char}.
-Pointers in Go are pointers in C. A Go @code{struct} is the same as C
-@code{struct} with the same field names and types.
-
-@cindex @code{string} in C
-The Go @code{string} type is currently defined as a two-element
-structure:
-
-@smallexample
-struct __go_string @{
- const unsigned char *__data;
- int __length;
-@};
-@end smallexample
-
-You can't pass arrays between C and Go. However, a pointer to an
-array in Go is equivalent to a C pointer to the equivalent of the
-element type. For example, Go @code{*[10]int} is equivalent to C
-@code{int*}, assuming that the C pointer does point to 10 elements.
-
-@cindex @code{slice} in C
-A slice in Go is a structure. The current definition is:
-
-@smallexample
-struct __go_slice @{
- void *__values;
- int __count;
- int __capacity;
-@};
-@end smallexample
-
-The type of a Go function with no receiver is equivalent to a C
-function whose parameter types are equivalent. When a Go function
-returns more than one value, the C function returns a struct. For
-example, these functions have equivalent types:
-
-@smallexample
-func GoFunction(int) (int, float)
-struct @{ int i; float f; @} CFunction(int)
-@end smallexample
-
-A pointer to a Go function is equivalent to a pointer to a C function
-when the functions have equivalent types.
-
-Go @code{interface}, @code{channel}, and @code{map} types have no
-corresponding C type (@code{interface} is a two-element struct and
-@code{channel} and @code{map} are pointers to structs in C, but the
-structs are deliberately undocumented). C @code{enum} types
-correspond to some integer type, but precisely which one is difficult
-to predict in general; use a cast. C @code{union} types have no
-corresponding Go type. C @code{struct} types containing bitfields
-have no corresponding Go type. C++ @code{class} types have no
-corresponding Go type.
-
-Memory allocation is completely different between C and Go, as Go uses
-garbage collection. The exact guidelines in this area are
-undetermined, but it is likely that it will be permitted to pass a
-pointer to allocated memory from C to Go. The responsibility of
-eventually freeing the pointer will remain with C side, and of course
-if the C side frees the pointer while the Go side still has a copy the
-program will fail. When passing a pointer from Go to C, the Go
-function must retain a visible copy of it in some Go variable.
-Otherwise the Go garbage collector may delete the pointer while the C
-function is still using it.
-
-@node Function Names
-@section Function Names
-
-@cindex @code{extern}
-@cindex external names
-Go code can call C functions directly using the @code{//extern} or
-@code{//go:linkname} compiler directives. An @code{//extern}
-directive must be at the beginning of the line and must start with
-@code{//extern}. This must be followed by a space and then the
-external name of the function. The function declaration must be on
-the line immediately after the comment. For example, here is how the
-C function @code{open} can be declared in Go:
-
-@smallexample
-//extern open
-func c_open(name *byte, mode int, perm int) int
-@end smallexample
-
-You can do the same thing using the @code{//go:linkname} compiler
-directive. The @code{//go:linkname} directive must be at the start of
-the line. It is followed by whitespace, the name of the Go function,
-more whitespace, and the external name of the function. Unlike
-@code{//extern}, @code{//go:linkname} does not need to appear
-immediately adjacent to the function definition or declaration.
-
-@smallexample
-//go:linkname c_open open
-func c_open(name *byte, mode int, perm int) int
-@end smallexample
-
-The C function naturally expects a nul terminated string, which in Go
-is equivalent to a pointer to an array (not a slice!) of @code{byte}
-with a terminating zero byte. So a sample call from Go would look
-like (after importing the @code{os} package):
-
-@smallexample
-var name = [4]byte@{'f', 'o', 'o', 0@};
-i := c_open(&name[0], os.O_RDONLY, 0);
-@end smallexample
-
-Note that this serves as an example only. To open a file in Go please
-use Go's @code{os.Open} function instead.
-
-The name of Go functions accessed from C is subject to change. At
-present the name of a Go function that does not have a receiver is
-@code{pkgpath.Functionname}. The @var{pkgpath} is set by the
-@option{-fgo-pkgpath} option used when the package is compiled; if the
-option is not used, the default is @code{go.@var{packagename}}. To
-call the function from C you must set the name using the @command{gcc}
-@code{__asm__} extension.
-
-@smallexample
-extern int go_function(int) __asm__ ("mypkgpath.Function");
-@end smallexample
-
-@node Index
-@unnumbered Index
-
-@printindex cp
-
-@bye
+++ /dev/null
-\input texinfo @c -*-texinfo-*-
-
-@c %**start of header
-@setfilename libgomp.info
-@settitle GNU libgomp
-@c %**end of header
-
-
-@copying
-Copyright @copyright{} 2006-2022 Free Software Foundation, Inc.
-
-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 the
-Invariant Sections being ``Funding Free Software'', the Front-Cover
-texts being (a) (see below), and with the Back-Cover Texts being (b)
-(see below). A copy of the license is included in the section entitled
-``GNU Free Documentation License''.
-
-(a) The FSF's Front-Cover Text is:
-
- A GNU Manual
-
-(b) The FSF's Back-Cover Text is:
-
- You have freedom to copy and modify this GNU Manual, like GNU
- software. Copies published by the Free Software Foundation raise
- funds for GNU development.
-@end copying
-
-@ifinfo
-@dircategory GNU Libraries
-@direntry
-* libgomp: (libgomp). GNU Offloading and Multi Processing Runtime Library.
-@end direntry
-
-This manual documents libgomp, the GNU Offloading and Multi Processing
-Runtime library. This is the GNU implementation of the OpenMP and
-OpenACC APIs for parallel and accelerator programming in C/C++ and
-Fortran.
-
-Published by the Free Software Foundation
-51 Franklin Street, Fifth Floor
-Boston, MA 02110-1301 USA
-
-@insertcopying
-@end ifinfo
-
-
-@setchapternewpage odd
-
-@titlepage
-@title GNU Offloading and Multi Processing Runtime Library
-@subtitle The GNU OpenMP and OpenACC Implementation
-@page
-@vskip 0pt plus 1filll
-@comment For the @value{version-GCC} Version*
-@sp 1
-Published by the Free Software Foundation @*
-51 Franklin Street, Fifth Floor@*
-Boston, MA 02110-1301, USA@*
-@sp 1
-@insertcopying
-@end titlepage
-
-@summarycontents
-@contents
-@page
-
-
-@node Top, Enabling OpenMP
-@top Introduction
-@cindex Introduction
-
-This manual documents the usage of libgomp, the GNU Offloading and
-Multi Processing Runtime Library. This includes the GNU
-implementation of the @uref{https://www.openmp.org, OpenMP} Application
-Programming Interface (API) for multi-platform shared-memory parallel
-programming in C/C++ and Fortran, and the GNU implementation of the
-@uref{https://www.openacc.org, OpenACC} Application Programming
-Interface (API) for offloading of code to accelerator devices in C/C++
-and Fortran.
-
-Originally, libgomp implemented the GNU OpenMP Runtime Library. Based
-on this, support for OpenACC and offloading (both OpenACC and OpenMP
-4's target construct) has been added later on, and the library's name
-changed to GNU Offloading and Multi Processing Runtime Library.
-
-
-
-@comment
-@comment When you add a new menu item, please keep the right hand
-@comment aligned to the same column. Do not use tabs. This provides
-@comment better formatting.
-@comment
-@menu
-* Enabling OpenMP:: How to enable OpenMP for your applications.
-* OpenMP Implementation Status:: List of implemented features by OpenMP version
-* OpenMP Runtime Library Routines: Runtime Library Routines.
- The OpenMP runtime application programming
- interface.
-* OpenMP Environment Variables: Environment Variables.
- Influencing OpenMP runtime behavior with
- environment variables.
-* Enabling OpenACC:: How to enable OpenACC for your
- applications.
-* OpenACC Runtime Library Routines:: The OpenACC runtime application
- programming interface.
-* OpenACC Environment Variables:: Influencing OpenACC runtime behavior with
- environment variables.
-* CUDA Streams Usage:: Notes on the implementation of
- asynchronous operations.
-* OpenACC Library Interoperability:: OpenACC library interoperability with the
- NVIDIA CUBLAS library.
-* OpenACC Profiling Interface::
-* OpenMP-Implementation Specifics:: Notes specifics of this OpenMP
- implementation
-* Offload-Target Specifics:: Notes on offload-target specific internals
-* The libgomp ABI:: Notes on the external ABI presented by libgomp.
-* Reporting Bugs:: How to report bugs in the GNU Offloading and
- Multi Processing Runtime Library.
-* Copying:: GNU general public license says
- how you can copy and share libgomp.
-* GNU Free Documentation License::
- How you can copy and share this manual.
-* Funding:: How to help assure continued work for free
- software.
-* Library Index:: Index of this documentation.
-@end menu
-
-
-@c ---------------------------------------------------------------------
-@c Enabling OpenMP
-@c ---------------------------------------------------------------------
-
-@node Enabling OpenMP
-@chapter Enabling OpenMP
-
-To activate the OpenMP extensions for C/C++ and Fortran, the compile-time
-flag @command{-fopenmp} must be specified. This enables the OpenMP directive
-@code{#pragma omp} in C/C++ and @code{!$omp} directives in free form,
-@code{c$omp}, @code{*$omp} and @code{!$omp} directives in fixed form,
-@code{!$} conditional compilation sentinels in free form and @code{c$},
-@code{*$} and @code{!$} sentinels in fixed form, for Fortran. The flag also
-arranges for automatic linking of the OpenMP runtime library
-(@ref{Runtime Library Routines}).
-
-A complete description of all OpenMP directives may be found in the
-@uref{https://www.openmp.org, OpenMP Application Program Interface} manuals.
-See also @ref{OpenMP Implementation Status}.
-
-
-@c ---------------------------------------------------------------------
-@c OpenMP Implementation Status
-@c ---------------------------------------------------------------------
-
-@node OpenMP Implementation Status
-@chapter OpenMP Implementation Status
-
-@menu
-* OpenMP 4.5:: Feature completion status to 4.5 specification
-* OpenMP 5.0:: Feature completion status to 5.0 specification
-* OpenMP 5.1:: Feature completion status to 5.1 specification
-* OpenMP 5.2:: Feature completion status to 5.2 specification
-@end menu
-
-The @code{_OPENMP} preprocessor macro and Fortran's @code{openmp_version}
-parameter, provided by @code{omp_lib.h} and the @code{omp_lib} module, have
-the value @code{201511} (i.e. OpenMP 4.5).
-
-@node OpenMP 4.5
-@section OpenMP 4.5
-
-The OpenMP 4.5 specification is fully supported.
-
-@node OpenMP 5.0
-@section OpenMP 5.0
-
-@unnumberedsubsec New features listed in Appendix B of the OpenMP specification
-@c This list is sorted as in OpenMP 5.1's B.3 not as in OpenMP 5.0's B.2
-
-@multitable @columnfractions .60 .10 .25
-@headitem Description @tab Status @tab Comments
-@item Array shaping @tab N @tab
-@item Array sections with non-unit strides in C and C++ @tab N @tab
-@item Iterators @tab Y @tab
-@item @code{metadirective} directive @tab N @tab
-@item @code{declare variant} directive
- @tab P @tab @emph{simd} traits not handled correctly
-@item @emph{target-offload-var} ICV and @code{OMP_TARGET_OFFLOAD}
- env variable @tab Y @tab
-@item Nested-parallel changes to @emph{max-active-levels-var} ICV @tab Y @tab
-@item @code{requires} directive @tab P
- @tab complete but no non-host devices provides @code{unified_address},
- @code{unified_shared_memory} or @code{reverse_offload}
-@item @code{teams} construct outside an enclosing target region @tab Y @tab
-@item Non-rectangular loop nests @tab Y @tab
-@item @code{!=} as relational-op in canonical loop form for C/C++ @tab Y @tab
-@item @code{nonmonotonic} as default loop schedule modifier for worksharing-loop
- constructs @tab Y @tab
-@item Collapse of associated loops that are imperfectly nested loops @tab N @tab
-@item Clauses @code{if}, @code{nontemporal} and @code{order(concurrent)} in
- @code{simd} construct @tab Y @tab
-@item @code{atomic} constructs in @code{simd} @tab Y @tab
-@item @code{loop} construct @tab Y @tab
-@item @code{order(concurrent)} clause @tab Y @tab
-@item @code{scan} directive and @code{in_scan} modifier for the
- @code{reduction} clause @tab Y @tab
-@item @code{in_reduction} clause on @code{task} constructs @tab Y @tab
-@item @code{in_reduction} clause on @code{target} constructs @tab P
- @tab @code{nowait} only stub
-@item @code{task_reduction} clause with @code{taskgroup} @tab Y @tab
-@item @code{task} modifier to @code{reduction} clause @tab Y @tab
-@item @code{affinity} clause to @code{task} construct @tab Y @tab Stub only
-@item @code{detach} clause to @code{task} construct @tab Y @tab
-@item @code{omp_fulfill_event} runtime routine @tab Y @tab
-@item @code{reduction} and @code{in_reduction} clauses on @code{taskloop}
- and @code{taskloop simd} constructs @tab Y @tab
-@item @code{taskloop} construct cancelable by @code{cancel} construct
- @tab Y @tab
-@item @code{mutexinoutset} @emph{dependence-type} for @code{depend} clause
- @tab Y @tab
-@item Predefined memory spaces, memory allocators, allocator traits
- @tab Y @tab Some are only stubs
-@item Memory management routines @tab Y @tab
-@item @code{allocate} directive @tab N @tab
-@item @code{allocate} clause @tab P @tab Initial support
-@item @code{use_device_addr} clause on @code{target data} @tab Y @tab
-@item @code{ancestor} modifier on @code{device} clause
- @tab Y @tab See comment for @code{requires}
-@item Implicit declare target directive @tab Y @tab
-@item Discontiguous array section with @code{target update} construct
- @tab N @tab
-@item C/C++'s lvalue expressions in @code{to}, @code{from}
- and @code{map} clauses @tab N @tab
-@item C/C++'s lvalue expressions in @code{depend} clauses @tab Y @tab
-@item Nested @code{declare target} directive @tab Y @tab
-@item Combined @code{master} constructs @tab Y @tab
-@item @code{depend} clause on @code{taskwait} @tab Y @tab
-@item Weak memory ordering clauses on @code{atomic} and @code{flush} construct
- @tab Y @tab
-@item @code{hint} clause on the @code{atomic} construct @tab Y @tab Stub only
-@item @code{depobj} construct and depend objects @tab Y @tab
-@item Lock hints were renamed to synchronization hints @tab Y @tab
-@item @code{conditional} modifier to @code{lastprivate} clause @tab Y @tab
-@item Map-order clarifications @tab P @tab
-@item @code{close} @emph{map-type-modifier} @tab Y @tab
-@item Mapping C/C++ pointer variables and to assign the address of
- device memory mapped by an array section @tab P @tab
-@item Mapping of Fortran pointer and allocatable variables, including pointer
- and allocatable components of variables
- @tab P @tab Mapping of vars with allocatable components unsupported
-@item @code{defaultmap} extensions @tab Y @tab
-@item @code{declare mapper} directive @tab N @tab
-@item @code{omp_get_supported_active_levels} routine @tab Y @tab
-@item Runtime routines and environment variables to display runtime thread
- affinity information @tab Y @tab
-@item @code{omp_pause_resource} and @code{omp_pause_resource_all} runtime
- routines @tab Y @tab
-@item @code{omp_get_device_num} runtime routine @tab Y @tab
-@item OMPT interface @tab N @tab
-@item OMPD interface @tab N @tab
-@end multitable
-
-@unnumberedsubsec Other new OpenMP 5.0 features
-
-@multitable @columnfractions .60 .10 .25
-@headitem Description @tab Status @tab Comments
-@item Supporting C++'s range-based for loop @tab Y @tab
-@end multitable
-
-
-@node OpenMP 5.1
-@section OpenMP 5.1
-
-@unnumberedsubsec New features listed in Appendix B of the OpenMP specification
-
-@multitable @columnfractions .60 .10 .25
-@headitem Description @tab Status @tab Comments
-@item OpenMP directive as C++ attribute specifiers @tab Y @tab
-@item @code{omp_all_memory} reserved locator @tab Y @tab
-@item @emph{target_device trait} in OpenMP Context @tab N @tab
-@item @code{target_device} selector set in context selectors @tab N @tab
-@item C/C++'s @code{declare variant} directive: elision support of
- preprocessed code @tab N @tab
-@item @code{declare variant}: new clauses @code{adjust_args} and
- @code{append_args} @tab N @tab
-@item @code{dispatch} construct @tab N @tab
-@item device-specific ICV settings with environment variables @tab Y @tab
-@item @code{assume} directive @tab Y @tab
-@item @code{nothing} directive @tab Y @tab
-@item @code{error} directive @tab Y @tab
-@item @code{masked} construct @tab Y @tab
-@item @code{scope} directive @tab Y @tab
-@item Loop transformation constructs @tab N @tab
-@item @code{strict} modifier in the @code{grainsize} and @code{num_tasks}
- clauses of the @code{taskloop} construct @tab Y @tab
-@item @code{align} clause/modifier in @code{allocate} directive/clause
- and @code{allocator} directive @tab P @tab C/C++ on clause only
-@item @code{thread_limit} clause to @code{target} construct @tab Y @tab
-@item @code{has_device_addr} clause to @code{target} construct @tab Y @tab
-@item Iterators in @code{target update} motion clauses and @code{map}
- clauses @tab N @tab
-@item Indirect calls to the device version of a procedure or function in
- @code{target} regions @tab N @tab
-@item @code{interop} directive @tab N @tab
-@item @code{omp_interop_t} object support in runtime routines @tab N @tab
-@item @code{nowait} clause in @code{taskwait} directive @tab Y @tab
-@item Extensions to the @code{atomic} directive @tab Y @tab
-@item @code{seq_cst} clause on a @code{flush} construct @tab Y @tab
-@item @code{inoutset} argument to the @code{depend} clause @tab Y @tab
-@item @code{private} and @code{firstprivate} argument to @code{default}
- clause in C and C++ @tab Y @tab
-@item @code{present} argument to @code{defaultmap} clause @tab N @tab
-@item @code{omp_set_num_teams}, @code{omp_set_teams_thread_limit},
- @code{omp_get_max_teams}, @code{omp_get_teams_thread_limit} runtime
- routines @tab Y @tab
-@item @code{omp_target_is_accessible} runtime routine @tab Y @tab
-@item @code{omp_target_memcpy_async} and @code{omp_target_memcpy_rect_async}
- runtime routines @tab Y @tab
-@item @code{omp_get_mapped_ptr} runtime routine @tab Y @tab
-@item @code{omp_calloc}, @code{omp_realloc}, @code{omp_aligned_alloc} and
- @code{omp_aligned_calloc} runtime routines @tab Y @tab
-@item @code{omp_alloctrait_key_t} enum: @code{omp_atv_serialized} added,
- @code{omp_atv_default} changed @tab Y @tab
-@item @code{omp_display_env} runtime routine @tab Y @tab
-@item @code{ompt_scope_endpoint_t} enum: @code{ompt_scope_beginend} @tab N @tab
-@item @code{ompt_sync_region_t} enum additions @tab N @tab
-@item @code{ompt_state_t} enum: @code{ompt_state_wait_barrier_implementation}
- and @code{ompt_state_wait_barrier_teams} @tab N @tab
-@item @code{ompt_callback_target_data_op_emi_t},
- @code{ompt_callback_target_emi_t}, @code{ompt_callback_target_map_emi_t}
- and @code{ompt_callback_target_submit_emi_t} @tab N @tab
-@item @code{ompt_callback_error_t} type @tab N @tab
-@item @code{OMP_PLACES} syntax extensions @tab Y @tab
-@item @code{OMP_NUM_TEAMS} and @code{OMP_TEAMS_THREAD_LIMIT} environment
- variables @tab Y @tab
-@end multitable
-
-@unnumberedsubsec Other new OpenMP 5.1 features
-
-@multitable @columnfractions .60 .10 .25
-@headitem Description @tab Status @tab Comments
-@item Support of strictly structured blocks in Fortran @tab Y @tab
-@item Support of structured block sequences in C/C++ @tab Y @tab
-@item @code{unconstrained} and @code{reproducible} modifiers on @code{order}
- clause @tab Y @tab
-@item Support @code{begin/end declare target} syntax in C/C++ @tab Y @tab
-@item Pointer predetermined firstprivate getting initialized
-to address of matching mapped list item per 5.1, Sect. 2.21.7.2 @tab N @tab
-@item For Fortran, diagnose placing declarative before/between @code{USE},
- @code{IMPORT}, and @code{IMPLICIT} as invalid @tab N @tab
-@end multitable
-
-
-@node OpenMP 5.2
-@section OpenMP 5.2
-
-@unnumberedsubsec New features listed in Appendix B of the OpenMP specification
-
-@multitable @columnfractions .60 .10 .25
-@headitem Description @tab Status @tab Comments
-@item @code{omp_in_explicit_task} routine and @emph{explicit-task-var} ICV
- @tab Y @tab
-@item @code{omp}/@code{ompx}/@code{omx} sentinels and @code{omp_}/@code{ompx_}
- namespaces @tab N/A
- @tab warning for @code{ompx/omx} sentinels@footnote{The @code{ompx}
- sentinel as C/C++ pragma and C++ attributes are warned for with
- @code{-Wunknown-pragmas} (implied by @code{-Wall}) and @code{-Wattributes}
- (enabled by default), respectively; for Fortran free-source code, there is
- a warning enabled by default and, for fixed-source code, the @code{omx}
- sentinel is warned for with with @code{-Wsurprising} (enabled by
- @code{-Wall}). Unknown clauses are always rejected with an error.}
-@item Clauses on @code{end} directive can be on directive @tab N @tab
-@item Deprecation of no-argument @code{destroy} clause on @code{depobj}
- @tab N @tab
-@item @code{linear} clause syntax changes and @code{step} modifier @tab Y @tab
-@item Deprecation of minus operator for reductions @tab N @tab
-@item Deprecation of separating @code{map} modifiers without comma @tab N @tab
-@item @code{declare mapper} with iterator and @code{present} modifiers
- @tab N @tab
-@item If a matching mapped list item is not found in the data environment, the
- pointer retains its original value @tab N @tab
-@item New @code{enter} clause as alias for @code{to} on declare target directive
- @tab Y @tab
-@item Deprecation of @code{to} clause on declare target directive @tab N @tab
-@item Extended list of directives permitted in Fortran pure procedures
- @tab N @tab
-@item New @code{allocators} directive for Fortran @tab N @tab
-@item Deprecation of @code{allocate} directive for Fortran
- allocatables/pointers @tab N @tab
-@item Optional paired @code{end} directive with @code{dispatch} @tab N @tab
-@item New @code{memspace} and @code{traits} modifiers for @code{uses_allocators}
- @tab N @tab
-@item Deprecation of traits array following the allocator_handle expression in
- @code{uses_allocators} @tab N @tab
-@item New @code{otherwise} clause as alias for @code{default} on metadirectives
- @tab N @tab
-@item Deprecation of @code{default} clause on metadirectives @tab N @tab
-@item Deprecation of delimited form of @code{declare target} @tab N @tab
-@item Reproducible semantics changed for @code{order(concurrent)} @tab N @tab
-@item @code{allocate} and @code{firstprivate} clauses on @code{scope}
- @tab Y @tab
-@item @code{ompt_callback_work} @tab N @tab
-@item Default map-type for @code{map} clause in @code{target enter/exit data}
- @tab Y @tab
-@item New @code{doacross} clause as alias for @code{depend} with
- @code{source}/@code{sink} modifier @tab Y @tab
-@item Deprecation of @code{depend} with @code{source}/@code{sink} modifier
- @tab N @tab
-@item @code{omp_cur_iteration} keyword @tab Y @tab
-@end multitable
-
-@unnumberedsubsec Other new OpenMP 5.2 features
-
-@multitable @columnfractions .60 .10 .25
-@headitem Description @tab Status @tab Comments
-@item For Fortran, optional comma between directive and clause @tab N @tab
-@item Conforming device numbers and @code{omp_initial_device} and
- @code{omp_invalid_device} enum/PARAMETER @tab Y @tab
-@item Initial value of @emph{default-device-var} ICV with
- @code{OMP_TARGET_OFFLOAD=mandatory} @tab N @tab
-@item @emph{interop_types} in any position of the modifier list for the @code{init} clause
- of the @code{interop} construct @tab N @tab
-@end multitable
-
-
-@c ---------------------------------------------------------------------
-@c OpenMP Runtime Library Routines
-@c ---------------------------------------------------------------------
-
-@node Runtime Library Routines
-@chapter OpenMP Runtime Library Routines
-
-The runtime routines described here are defined by Section 3 of the OpenMP
-specification in version 4.5. The routines are structured in following
-three parts:
-
-@menu
-Control threads, processors and the parallel environment. They have C
-linkage, and do not throw exceptions.
-
-* omp_get_active_level:: Number of active parallel regions
-* omp_get_ancestor_thread_num:: Ancestor thread ID
-* omp_get_cancellation:: Whether cancellation support is enabled
-* omp_get_default_device:: Get the default device for target regions
-* omp_get_device_num:: Get device that current thread is running on
-* omp_get_dynamic:: Dynamic teams setting
-* omp_get_initial_device:: Device number of host device
-* omp_get_level:: Number of parallel regions
-* omp_get_max_active_levels:: Current maximum number of active regions
-* omp_get_max_task_priority:: Maximum task priority value that can be set
-* omp_get_max_teams:: Maximum number of teams for teams region
-* omp_get_max_threads:: Maximum number of threads of parallel region
-* omp_get_nested:: Nested parallel regions
-* omp_get_num_devices:: Number of target devices
-* omp_get_num_procs:: Number of processors online
-* omp_get_num_teams:: Number of teams
-* omp_get_num_threads:: Size of the active team
-* omp_get_proc_bind:: Whether theads may be moved between CPUs
-* omp_get_schedule:: Obtain the runtime scheduling method
-* omp_get_supported_active_levels:: Maximum number of active regions supported
-* omp_get_team_num:: Get team number
-* omp_get_team_size:: Number of threads in a team
-* omp_get_teams_thread_limit:: Maximum number of threads imposed by teams
-* omp_get_thread_limit:: Maximum number of threads
-* omp_get_thread_num:: Current thread ID
-* omp_in_parallel:: Whether a parallel region is active
-* omp_in_final:: Whether in final or included task region
-* omp_is_initial_device:: Whether executing on the host device
-* omp_set_default_device:: Set the default device for target regions
-* omp_set_dynamic:: Enable/disable dynamic teams
-* omp_set_max_active_levels:: Limits the number of active parallel regions
-* omp_set_nested:: Enable/disable nested parallel regions
-* omp_set_num_teams:: Set upper teams limit for teams region
-* omp_set_num_threads:: Set upper team size limit
-* omp_set_schedule:: Set the runtime scheduling method
-* omp_set_teams_thread_limit:: Set upper thread limit for teams construct
-
-Initialize, set, test, unset and destroy simple and nested locks.
-
-* omp_init_lock:: Initialize simple lock
-* omp_set_lock:: Wait for and set simple lock
-* omp_test_lock:: Test and set simple lock if available
-* omp_unset_lock:: Unset simple lock
-* omp_destroy_lock:: Destroy simple lock
-* omp_init_nest_lock:: Initialize nested lock
-* omp_set_nest_lock:: Wait for and set simple lock
-* omp_test_nest_lock:: Test and set nested lock if available
-* omp_unset_nest_lock:: Unset nested lock
-* omp_destroy_nest_lock:: Destroy nested lock
-
-Portable, thread-based, wall clock timer.
-
-* omp_get_wtick:: Get timer precision.
-* omp_get_wtime:: Elapsed wall clock time.
-
-Support for event objects.
-
-* omp_fulfill_event:: Fulfill and destroy an OpenMP event.
-@end menu
-
-
-
-@node omp_get_active_level
-@section @code{omp_get_active_level} -- Number of parallel regions
-@table @asis
-@item @emph{Description}:
-This function returns the nesting level for the active parallel blocks,
-which enclose the calling call.
-
-@item @emph{C/C++}
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{int omp_get_active_level(void);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{integer function omp_get_active_level()}
-@end multitable
-
-@item @emph{See also}:
-@ref{omp_get_level}, @ref{omp_get_max_active_levels}, @ref{omp_set_max_active_levels}
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.20.
-@end table
-
-
-
-@node omp_get_ancestor_thread_num
-@section @code{omp_get_ancestor_thread_num} -- Ancestor thread ID
-@table @asis
-@item @emph{Description}:
-This function returns the thread identification number for the given
-nesting level of the current thread. For values of @var{level} outside
-zero to @code{omp_get_level} -1 is returned; if @var{level} is
-@code{omp_get_level} the result is identical to @code{omp_get_thread_num}.
-
-@item @emph{C/C++}
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{int omp_get_ancestor_thread_num(int level);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{integer function omp_get_ancestor_thread_num(level)}
-@item @tab @code{integer level}
-@end multitable
-
-@item @emph{See also}:
-@ref{omp_get_level}, @ref{omp_get_thread_num}, @ref{omp_get_team_size}
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.18.
-@end table
-
-
-
-@node omp_get_cancellation
-@section @code{omp_get_cancellation} -- Whether cancellation support is enabled
-@table @asis
-@item @emph{Description}:
-This function returns @code{true} if cancellation is activated, @code{false}
-otherwise. Here, @code{true} and @code{false} represent their language-specific
-counterparts. Unless @env{OMP_CANCELLATION} is set true, cancellations are
-deactivated.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{int omp_get_cancellation(void);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{logical function omp_get_cancellation()}
-@end multitable
-
-@item @emph{See also}:
-@ref{OMP_CANCELLATION}
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.9.
-@end table
-
-
-
-@node omp_get_default_device
-@section @code{omp_get_default_device} -- Get the default device for target regions
-@table @asis
-@item @emph{Description}:
-Get the default device for target regions without device clause.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{int omp_get_default_device(void);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{integer function omp_get_default_device()}
-@end multitable
-
-@item @emph{See also}:
-@ref{OMP_DEFAULT_DEVICE}, @ref{omp_set_default_device}
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.30.
-@end table
-
-
-
-@node omp_get_device_num
-@section @code{omp_get_device_num} -- Return device number of current device
-@table @asis
-@item @emph{Description}:
-This function returns a device number that represents the device that the
-current thread is executing on. For OpenMP 5.0, this must be equal to the
-value returned by the @code{omp_get_initial_device} function when called
-from the host.
-
-@item @emph{C/C++}
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{int omp_get_device_num(void);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{integer function omp_get_device_num()}
-@end multitable
-
-@item @emph{See also}:
-@ref{omp_get_initial_device}
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v5.0}, Section 3.2.37.
-@end table
-
-
-
-@node omp_get_dynamic
-@section @code{omp_get_dynamic} -- Dynamic teams setting
-@table @asis
-@item @emph{Description}:
-This function returns @code{true} if enabled, @code{false} otherwise.
-Here, @code{true} and @code{false} represent their language-specific
-counterparts.
-
-The dynamic team setting may be initialized at startup by the
-@env{OMP_DYNAMIC} environment variable or at runtime using
-@code{omp_set_dynamic}. If undefined, dynamic adjustment is
-disabled by default.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{int omp_get_dynamic(void);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{logical function omp_get_dynamic()}
-@end multitable
-
-@item @emph{See also}:
-@ref{omp_set_dynamic}, @ref{OMP_DYNAMIC}
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.8.
-@end table
-
-
-
-@node omp_get_initial_device
-@section @code{omp_get_initial_device} -- Return device number of initial device
-@table @asis
-@item @emph{Description}:
-This function returns a device number that represents the host device.
-For OpenMP 5.1, this must be equal to the value returned by the
-@code{omp_get_num_devices} function.
-
-@item @emph{C/C++}
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{int omp_get_initial_device(void);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{integer function omp_get_initial_device()}
-@end multitable
-
-@item @emph{See also}:
-@ref{omp_get_num_devices}
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.35.
-@end table
-
-
-
-@node omp_get_level
-@section @code{omp_get_level} -- Obtain the current nesting level
-@table @asis
-@item @emph{Description}:
-This function returns the nesting level for the parallel blocks,
-which enclose the calling call.
-
-@item @emph{C/C++}
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{int omp_get_level(void);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{integer function omp_level()}
-@end multitable
-
-@item @emph{See also}:
-@ref{omp_get_active_level}
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.17.
-@end table
-
-
-
-@node omp_get_max_active_levels
-@section @code{omp_get_max_active_levels} -- Current maximum number of active regions
-@table @asis
-@item @emph{Description}:
-This function obtains the maximum allowed number of nested, active parallel regions.
-
-@item @emph{C/C++}
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{int omp_get_max_active_levels(void);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{integer function omp_get_max_active_levels()}
-@end multitable
-
-@item @emph{See also}:
-@ref{omp_set_max_active_levels}, @ref{omp_get_active_level}
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.16.
-@end table
-
-
-@node omp_get_max_task_priority
-@section @code{omp_get_max_task_priority} -- Maximum priority value
-that can be set for tasks.
-@table @asis
-@item @emph{Description}:
-This function obtains the maximum allowed priority number for tasks.
-
-@item @emph{C/C++}
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{int omp_get_max_task_priority(void);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{integer function omp_get_max_task_priority()}
-@end multitable
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.29.
-@end table
-
-
-@node omp_get_max_teams
-@section @code{omp_get_max_teams} -- Maximum number of teams of teams region
-@table @asis
-@item @emph{Description}:
-Return the maximum number of teams used for the teams region
-that does not use the clause @code{num_teams}.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{int omp_get_max_teams(void);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{integer function omp_get_max_teams()}
-@end multitable
-
-@item @emph{See also}:
-@ref{omp_set_num_teams}, @ref{omp_get_num_teams}
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v5.1}, Section 3.4.4.
-@end table
-
-
-
-@node omp_get_max_threads
-@section @code{omp_get_max_threads} -- Maximum number of threads of parallel region
-@table @asis
-@item @emph{Description}:
-Return the maximum number of threads used for the current parallel region
-that does not use the clause @code{num_threads}.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{int omp_get_max_threads(void);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{integer function omp_get_max_threads()}
-@end multitable
-
-@item @emph{See also}:
-@ref{omp_set_num_threads}, @ref{omp_set_dynamic}, @ref{omp_get_thread_limit}
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.3.
-@end table
-
-
-
-@node omp_get_nested
-@section @code{omp_get_nested} -- Nested parallel regions
-@table @asis
-@item @emph{Description}:
-This function returns @code{true} if nested parallel regions are
-enabled, @code{false} otherwise. Here, @code{true} and @code{false}
-represent their language-specific counterparts.
-
-The state of nested parallel regions at startup depends on several
-environment variables. If @env{OMP_MAX_ACTIVE_LEVELS} is defined
-and is set to greater than one, then nested parallel regions will be
-enabled. If not defined, then the value of the @env{OMP_NESTED}
-environment variable will be followed if defined. If neither are
-defined, then if either @env{OMP_NUM_THREADS} or @env{OMP_PROC_BIND}
-are defined with a list of more than one value, then nested parallel
-regions are enabled. If none of these are defined, then nested parallel
-regions are disabled by default.
-
-Nested parallel regions can be enabled or disabled at runtime using
-@code{omp_set_nested}, or by setting the maximum number of nested
-regions with @code{omp_set_max_active_levels} to one to disable, or
-above one to enable.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{int omp_get_nested(void);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{logical function omp_get_nested()}
-@end multitable
-
-@item @emph{See also}:
-@ref{omp_set_max_active_levels}, @ref{omp_set_nested},
-@ref{OMP_MAX_ACTIVE_LEVELS}, @ref{OMP_NESTED}
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.11.
-@end table
-
-
-
-@node omp_get_num_devices
-@section @code{omp_get_num_devices} -- Number of target devices
-@table @asis
-@item @emph{Description}:
-Returns the number of target devices.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{int omp_get_num_devices(void);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{integer function omp_get_num_devices()}
-@end multitable
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.31.
-@end table
-
-
-
-@node omp_get_num_procs
-@section @code{omp_get_num_procs} -- Number of processors online
-@table @asis
-@item @emph{Description}:
-Returns the number of processors online on that device.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{int omp_get_num_procs(void);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{integer function omp_get_num_procs()}
-@end multitable
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.5.
-@end table
-
-
-
-@node omp_get_num_teams
-@section @code{omp_get_num_teams} -- Number of teams
-@table @asis
-@item @emph{Description}:
-Returns the number of teams in the current team region.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{int omp_get_num_teams(void);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{integer function omp_get_num_teams()}
-@end multitable
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.32.
-@end table
-
-
-
-@node omp_get_num_threads
-@section @code{omp_get_num_threads} -- Size of the active team
-@table @asis
-@item @emph{Description}:
-Returns the number of threads in the current team. In a sequential section of
-the program @code{omp_get_num_threads} returns 1.
-
-The default team size may be initialized at startup by the
-@env{OMP_NUM_THREADS} environment variable. At runtime, the size
-of the current team may be set either by the @code{NUM_THREADS}
-clause or by @code{omp_set_num_threads}. If none of the above were
-used to define a specific value and @env{OMP_DYNAMIC} is disabled,
-one thread per CPU online is used.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{int omp_get_num_threads(void);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{integer function omp_get_num_threads()}
-@end multitable
-
-@item @emph{See also}:
-@ref{omp_get_max_threads}, @ref{omp_set_num_threads}, @ref{OMP_NUM_THREADS}
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.2.
-@end table
-
-
-
-@node omp_get_proc_bind
-@section @code{omp_get_proc_bind} -- Whether theads may be moved between CPUs
-@table @asis
-@item @emph{Description}:
-This functions returns the currently active thread affinity policy, which is
-set via @env{OMP_PROC_BIND}. Possible values are @code{omp_proc_bind_false},
-@code{omp_proc_bind_true}, @code{omp_proc_bind_primary},
-@code{omp_proc_bind_master}, @code{omp_proc_bind_close} and @code{omp_proc_bind_spread},
-where @code{omp_proc_bind_master} is an alias for @code{omp_proc_bind_primary}.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{omp_proc_bind_t omp_get_proc_bind(void);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{integer(kind=omp_proc_bind_kind) function omp_get_proc_bind()}
-@end multitable
-
-@item @emph{See also}:
-@ref{OMP_PROC_BIND}, @ref{OMP_PLACES}, @ref{GOMP_CPU_AFFINITY},
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.22.
-@end table
-
-
-
-@node omp_get_schedule
-@section @code{omp_get_schedule} -- Obtain the runtime scheduling method
-@table @asis
-@item @emph{Description}:
-Obtain the runtime scheduling method. The @var{kind} argument will be
-set to the value @code{omp_sched_static}, @code{omp_sched_dynamic},
-@code{omp_sched_guided} or @code{omp_sched_auto}. The second argument,
-@var{chunk_size}, is set to the chunk size.
-
-@item @emph{C/C++}
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{void omp_get_schedule(omp_sched_t *kind, int *chunk_size);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{subroutine omp_get_schedule(kind, chunk_size)}
-@item @tab @code{integer(kind=omp_sched_kind) kind}
-@item @tab @code{integer chunk_size}
-@end multitable
-
-@item @emph{See also}:
-@ref{omp_set_schedule}, @ref{OMP_SCHEDULE}
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.13.
-@end table
-
-
-@node omp_get_supported_active_levels
-@section @code{omp_get_supported_active_levels} -- Maximum number of active regions supported
-@table @asis
-@item @emph{Description}:
-This function returns the maximum number of nested, active parallel regions
-supported by this implementation.
-
-@item @emph{C/C++}
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{int omp_get_supported_active_levels(void);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{integer function omp_get_supported_active_levels()}
-@end multitable
-
-@item @emph{See also}:
-@ref{omp_get_max_active_levels}, @ref{omp_set_max_active_levels}
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v5.0}, Section 3.2.15.
-@end table
-
-
-
-@node omp_get_team_num
-@section @code{omp_get_team_num} -- Get team number
-@table @asis
-@item @emph{Description}:
-Returns the team number of the calling thread.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{int omp_get_team_num(void);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{integer function omp_get_team_num()}
-@end multitable
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.33.
-@end table
-
-
-
-@node omp_get_team_size
-@section @code{omp_get_team_size} -- Number of threads in a team
-@table @asis
-@item @emph{Description}:
-This function returns the number of threads in a thread team to which
-either the current thread or its ancestor belongs. For values of @var{level}
-outside zero to @code{omp_get_level}, -1 is returned; if @var{level} is zero,
-1 is returned, and for @code{omp_get_level}, the result is identical
-to @code{omp_get_num_threads}.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{int omp_get_team_size(int level);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{integer function omp_get_team_size(level)}
-@item @tab @code{integer level}
-@end multitable
-
-@item @emph{See also}:
-@ref{omp_get_num_threads}, @ref{omp_get_level}, @ref{omp_get_ancestor_thread_num}
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.19.
-@end table
-
-
-
-@node omp_get_teams_thread_limit
-@section @code{omp_get_teams_thread_limit} -- Maximum number of threads imposed by teams
-@table @asis
-@item @emph{Description}:
-Return the maximum number of threads that will be able to participate in
-each team created by a teams construct.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{int omp_get_teams_thread_limit(void);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{integer function omp_get_teams_thread_limit()}
-@end multitable
-
-@item @emph{See also}:
-@ref{omp_set_teams_thread_limit}, @ref{OMP_TEAMS_THREAD_LIMIT}
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v5.1}, Section 3.4.6.
-@end table
-
-
-
-@node omp_get_thread_limit
-@section @code{omp_get_thread_limit} -- Maximum number of threads
-@table @asis
-@item @emph{Description}:
-Return the maximum number of threads of the program.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{int omp_get_thread_limit(void);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{integer function omp_get_thread_limit()}
-@end multitable
-
-@item @emph{See also}:
-@ref{omp_get_max_threads}, @ref{OMP_THREAD_LIMIT}
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.14.
-@end table
-
-
-
-@node omp_get_thread_num
-@section @code{omp_get_thread_num} -- Current thread ID
-@table @asis
-@item @emph{Description}:
-Returns a unique thread identification number within the current team.
-In a sequential parts of the program, @code{omp_get_thread_num}
-always returns 0. In parallel regions the return value varies
-from 0 to @code{omp_get_num_threads}-1 inclusive. The return
-value of the primary thread of a team is always 0.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{int omp_get_thread_num(void);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{integer function omp_get_thread_num()}
-@end multitable
-
-@item @emph{See also}:
-@ref{omp_get_num_threads}, @ref{omp_get_ancestor_thread_num}
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.4.
-@end table
-
-
-
-@node omp_in_parallel
-@section @code{omp_in_parallel} -- Whether a parallel region is active
-@table @asis
-@item @emph{Description}:
-This function returns @code{true} if currently running in parallel,
-@code{false} otherwise. Here, @code{true} and @code{false} represent
-their language-specific counterparts.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{int omp_in_parallel(void);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{logical function omp_in_parallel()}
-@end multitable
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.6.
-@end table
-
-
-@node omp_in_final
-@section @code{omp_in_final} -- Whether in final or included task region
-@table @asis
-@item @emph{Description}:
-This function returns @code{true} if currently running in a final
-or included task region, @code{false} otherwise. Here, @code{true}
-and @code{false} represent their language-specific counterparts.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{int omp_in_final(void);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{logical function omp_in_final()}
-@end multitable
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.21.
-@end table
-
-
-
-@node omp_is_initial_device
-@section @code{omp_is_initial_device} -- Whether executing on the host device
-@table @asis
-@item @emph{Description}:
-This function returns @code{true} if currently running on the host device,
-@code{false} otherwise. Here, @code{true} and @code{false} represent
-their language-specific counterparts.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{int omp_is_initial_device(void);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{logical function omp_is_initial_device()}
-@end multitable
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.34.
-@end table
-
-
-
-@node omp_set_default_device
-@section @code{omp_set_default_device} -- Set the default device for target regions
-@table @asis
-@item @emph{Description}:
-Set the default device for target regions without device clause. The argument
-shall be a nonnegative device number.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{void omp_set_default_device(int device_num);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{subroutine omp_set_default_device(device_num)}
-@item @tab @code{integer device_num}
-@end multitable
-
-@item @emph{See also}:
-@ref{OMP_DEFAULT_DEVICE}, @ref{omp_get_default_device}
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.29.
-@end table
-
-
-
-@node omp_set_dynamic
-@section @code{omp_set_dynamic} -- Enable/disable dynamic teams
-@table @asis
-@item @emph{Description}:
-Enable or disable the dynamic adjustment of the number of threads
-within a team. The function takes the language-specific equivalent
-of @code{true} and @code{false}, where @code{true} enables dynamic
-adjustment of team sizes and @code{false} disables it.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{void omp_set_dynamic(int dynamic_threads);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{subroutine omp_set_dynamic(dynamic_threads)}
-@item @tab @code{logical, intent(in) :: dynamic_threads}
-@end multitable
-
-@item @emph{See also}:
-@ref{OMP_DYNAMIC}, @ref{omp_get_dynamic}
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.7.
-@end table
-
-
-
-@node omp_set_max_active_levels
-@section @code{omp_set_max_active_levels} -- Limits the number of active parallel regions
-@table @asis
-@item @emph{Description}:
-This function limits the maximum allowed number of nested, active
-parallel regions. @var{max_levels} must be less or equal to
-the value returned by @code{omp_get_supported_active_levels}.
-
-@item @emph{C/C++}
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{void omp_set_max_active_levels(int max_levels);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{subroutine omp_set_max_active_levels(max_levels)}
-@item @tab @code{integer max_levels}
-@end multitable
-
-@item @emph{See also}:
-@ref{omp_get_max_active_levels}, @ref{omp_get_active_level},
-@ref{omp_get_supported_active_levels}
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.15.
-@end table
-
-
-
-@node omp_set_nested
-@section @code{omp_set_nested} -- Enable/disable nested parallel regions
-@table @asis
-@item @emph{Description}:
-Enable or disable nested parallel regions, i.e., whether team members
-are allowed to create new teams. The function takes the language-specific
-equivalent of @code{true} and @code{false}, where @code{true} enables
-dynamic adjustment of team sizes and @code{false} disables it.
-
-Enabling nested parallel regions will also set the maximum number of
-active nested regions to the maximum supported. Disabling nested parallel
-regions will set the maximum number of active nested regions to one.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{void omp_set_nested(int nested);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{subroutine omp_set_nested(nested)}
-@item @tab @code{logical, intent(in) :: nested}
-@end multitable
-
-@item @emph{See also}:
-@ref{omp_get_nested}, @ref{omp_set_max_active_levels},
-@ref{OMP_MAX_ACTIVE_LEVELS}, @ref{OMP_NESTED}
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.10.
-@end table
-
-
-
-@node omp_set_num_teams
-@section @code{omp_set_num_teams} -- Set upper teams limit for teams construct
-@table @asis
-@item @emph{Description}:
-Specifies the upper bound for number of teams created by the teams construct
-which does not specify a @code{num_teams} clause. The
-argument of @code{omp_set_num_teams} shall be a positive integer.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{void omp_set_num_teams(int num_teams);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{subroutine omp_set_num_teams(num_teams)}
-@item @tab @code{integer, intent(in) :: num_teams}
-@end multitable
-
-@item @emph{See also}:
-@ref{OMP_NUM_TEAMS}, @ref{omp_get_num_teams}, @ref{omp_get_max_teams}
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v5.1}, Section 3.4.3.
-@end table
-
-
-
-@node omp_set_num_threads
-@section @code{omp_set_num_threads} -- Set upper team size limit
-@table @asis
-@item @emph{Description}:
-Specifies the number of threads used by default in subsequent parallel
-sections, if those do not specify a @code{num_threads} clause. The
-argument of @code{omp_set_num_threads} shall be a positive integer.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{void omp_set_num_threads(int num_threads);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{subroutine omp_set_num_threads(num_threads)}
-@item @tab @code{integer, intent(in) :: num_threads}
-@end multitable
-
-@item @emph{See also}:
-@ref{OMP_NUM_THREADS}, @ref{omp_get_num_threads}, @ref{omp_get_max_threads}
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.1.
-@end table
-
-
-
-@node omp_set_schedule
-@section @code{omp_set_schedule} -- Set the runtime scheduling method
-@table @asis
-@item @emph{Description}:
-Sets the runtime scheduling method. The @var{kind} argument can have the
-value @code{omp_sched_static}, @code{omp_sched_dynamic},
-@code{omp_sched_guided} or @code{omp_sched_auto}. Except for
-@code{omp_sched_auto}, the chunk size is set to the value of
-@var{chunk_size} if positive, or to the default value if zero or negative.
-For @code{omp_sched_auto} the @var{chunk_size} argument is ignored.
-
-@item @emph{C/C++}
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{void omp_set_schedule(omp_sched_t kind, int chunk_size);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{subroutine omp_set_schedule(kind, chunk_size)}
-@item @tab @code{integer(kind=omp_sched_kind) kind}
-@item @tab @code{integer chunk_size}
-@end multitable
-
-@item @emph{See also}:
-@ref{omp_get_schedule}
-@ref{OMP_SCHEDULE}
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.12.
-@end table
-
-
-
-@node omp_set_teams_thread_limit
-@section @code{omp_set_teams_thread_limit} -- Set upper thread limit for teams construct
-@table @asis
-@item @emph{Description}:
-Specifies the upper bound for number of threads that will be available
-for each team created by the teams construct which does not specify a
-@code{thread_limit} clause. The argument of
-@code{omp_set_teams_thread_limit} shall be a positive integer.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{void omp_set_teams_thread_limit(int thread_limit);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{subroutine omp_set_teams_thread_limit(thread_limit)}
-@item @tab @code{integer, intent(in) :: thread_limit}
-@end multitable
-
-@item @emph{See also}:
-@ref{OMP_TEAMS_THREAD_LIMIT}, @ref{omp_get_teams_thread_limit}, @ref{omp_get_thread_limit}
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v5.1}, Section 3.4.5.
-@end table
-
-
-
-@node omp_init_lock
-@section @code{omp_init_lock} -- Initialize simple lock
-@table @asis
-@item @emph{Description}:
-Initialize a simple lock. After initialization, the lock is in
-an unlocked state.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{void omp_init_lock(omp_lock_t *lock);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{subroutine omp_init_lock(svar)}
-@item @tab @code{integer(omp_lock_kind), intent(out) :: svar}
-@end multitable
-
-@item @emph{See also}:
-@ref{omp_destroy_lock}
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.3.1.
-@end table
-
-
-
-@node omp_set_lock
-@section @code{omp_set_lock} -- Wait for and set simple lock
-@table @asis
-@item @emph{Description}:
-Before setting a simple lock, the lock variable must be initialized by
-@code{omp_init_lock}. The calling thread is blocked until the lock
-is available. If the lock is already held by the current thread,
-a deadlock occurs.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{void omp_set_lock(omp_lock_t *lock);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{subroutine omp_set_lock(svar)}
-@item @tab @code{integer(omp_lock_kind), intent(inout) :: svar}
-@end multitable
-
-@item @emph{See also}:
-@ref{omp_init_lock}, @ref{omp_test_lock}, @ref{omp_unset_lock}
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.3.4.
-@end table
-
-
-
-@node omp_test_lock
-@section @code{omp_test_lock} -- Test and set simple lock if available
-@table @asis
-@item @emph{Description}:
-Before setting a simple lock, the lock variable must be initialized by
-@code{omp_init_lock}. Contrary to @code{omp_set_lock}, @code{omp_test_lock}
-does not block if the lock is not available. This function returns
-@code{true} upon success, @code{false} otherwise. Here, @code{true} and
-@code{false} represent their language-specific counterparts.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{int omp_test_lock(omp_lock_t *lock);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{logical function omp_test_lock(svar)}
-@item @tab @code{integer(omp_lock_kind), intent(inout) :: svar}
-@end multitable
-
-@item @emph{See also}:
-@ref{omp_init_lock}, @ref{omp_set_lock}, @ref{omp_set_lock}
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.3.6.
-@end table
-
-
-
-@node omp_unset_lock
-@section @code{omp_unset_lock} -- Unset simple lock
-@table @asis
-@item @emph{Description}:
-A simple lock about to be unset must have been locked by @code{omp_set_lock}
-or @code{omp_test_lock} before. In addition, the lock must be held by the
-thread calling @code{omp_unset_lock}. Then, the lock becomes unlocked. If one
-or more threads attempted to set the lock before, one of them is chosen to,
-again, set the lock to itself.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{void omp_unset_lock(omp_lock_t *lock);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{subroutine omp_unset_lock(svar)}
-@item @tab @code{integer(omp_lock_kind), intent(inout) :: svar}
-@end multitable
-
-@item @emph{See also}:
-@ref{omp_set_lock}, @ref{omp_test_lock}
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.3.5.
-@end table
-
-
-
-@node omp_destroy_lock
-@section @code{omp_destroy_lock} -- Destroy simple lock
-@table @asis
-@item @emph{Description}:
-Destroy a simple lock. In order to be destroyed, a simple lock must be
-in the unlocked state.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{void omp_destroy_lock(omp_lock_t *lock);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{subroutine omp_destroy_lock(svar)}
-@item @tab @code{integer(omp_lock_kind), intent(inout) :: svar}
-@end multitable
-
-@item @emph{See also}:
-@ref{omp_init_lock}
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.3.3.
-@end table
-
-
-
-@node omp_init_nest_lock
-@section @code{omp_init_nest_lock} -- Initialize nested lock
-@table @asis
-@item @emph{Description}:
-Initialize a nested lock. After initialization, the lock is in
-an unlocked state and the nesting count is set to zero.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{void omp_init_nest_lock(omp_nest_lock_t *lock);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{subroutine omp_init_nest_lock(nvar)}
-@item @tab @code{integer(omp_nest_lock_kind), intent(out) :: nvar}
-@end multitable
-
-@item @emph{See also}:
-@ref{omp_destroy_nest_lock}
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.3.1.
-@end table
-
-
-@node omp_set_nest_lock
-@section @code{omp_set_nest_lock} -- Wait for and set nested lock
-@table @asis
-@item @emph{Description}:
-Before setting a nested lock, the lock variable must be initialized by
-@code{omp_init_nest_lock}. The calling thread is blocked until the lock
-is available. If the lock is already held by the current thread, the
-nesting count for the lock is incremented.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{void omp_set_nest_lock(omp_nest_lock_t *lock);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{subroutine omp_set_nest_lock(nvar)}
-@item @tab @code{integer(omp_nest_lock_kind), intent(inout) :: nvar}
-@end multitable
-
-@item @emph{See also}:
-@ref{omp_init_nest_lock}, @ref{omp_unset_nest_lock}
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.3.4.
-@end table
-
-
-
-@node omp_test_nest_lock
-@section @code{omp_test_nest_lock} -- Test and set nested lock if available
-@table @asis
-@item @emph{Description}:
-Before setting a nested lock, the lock variable must be initialized by
-@code{omp_init_nest_lock}. Contrary to @code{omp_set_nest_lock},
-@code{omp_test_nest_lock} does not block if the lock is not available.
-If the lock is already held by the current thread, the new nesting count
-is returned. Otherwise, the return value equals zero.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{int omp_test_nest_lock(omp_nest_lock_t *lock);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{logical function omp_test_nest_lock(nvar)}
-@item @tab @code{integer(omp_nest_lock_kind), intent(inout) :: nvar}
-@end multitable
-
-
-@item @emph{See also}:
-@ref{omp_init_lock}, @ref{omp_set_lock}, @ref{omp_set_lock}
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.3.6.
-@end table
-
-
-
-@node omp_unset_nest_lock
-@section @code{omp_unset_nest_lock} -- Unset nested lock
-@table @asis
-@item @emph{Description}:
-A nested lock about to be unset must have been locked by @code{omp_set_nested_lock}
-or @code{omp_test_nested_lock} before. In addition, the lock must be held by the
-thread calling @code{omp_unset_nested_lock}. If the nesting count drops to zero, the
-lock becomes unlocked. If one ore more threads attempted to set the lock before,
-one of them is chosen to, again, set the lock to itself.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{void omp_unset_nest_lock(omp_nest_lock_t *lock);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{subroutine omp_unset_nest_lock(nvar)}
-@item @tab @code{integer(omp_nest_lock_kind), intent(inout) :: nvar}
-@end multitable
-
-@item @emph{See also}:
-@ref{omp_set_nest_lock}
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.3.5.
-@end table
-
-
-
-@node omp_destroy_nest_lock
-@section @code{omp_destroy_nest_lock} -- Destroy nested lock
-@table @asis
-@item @emph{Description}:
-Destroy a nested lock. In order to be destroyed, a nested lock must be
-in the unlocked state and its nesting count must equal zero.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{void omp_destroy_nest_lock(omp_nest_lock_t *);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{subroutine omp_destroy_nest_lock(nvar)}
-@item @tab @code{integer(omp_nest_lock_kind), intent(inout) :: nvar}
-@end multitable
-
-@item @emph{See also}:
-@ref{omp_init_lock}
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.3.3.
-@end table
-
-
-
-@node omp_get_wtick
-@section @code{omp_get_wtick} -- Get timer precision
-@table @asis
-@item @emph{Description}:
-Gets the timer precision, i.e., the number of seconds between two
-successive clock ticks.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{double omp_get_wtick(void);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{double precision function omp_get_wtick()}
-@end multitable
-
-@item @emph{See also}:
-@ref{omp_get_wtime}
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.4.2.
-@end table
-
-
-
-@node omp_get_wtime
-@section @code{omp_get_wtime} -- Elapsed wall clock time
-@table @asis
-@item @emph{Description}:
-Elapsed wall clock time in seconds. The time is measured per thread, no
-guarantee can be made that two distinct threads measure the same time.
-Time is measured from some "time in the past", which is an arbitrary time
-guaranteed not to change during the execution of the program.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{double omp_get_wtime(void);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{double precision function omp_get_wtime()}
-@end multitable
-
-@item @emph{See also}:
-@ref{omp_get_wtick}
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.4.1.
-@end table
-
-
-
-@node omp_fulfill_event
-@section @code{omp_fulfill_event} -- Fulfill and destroy an OpenMP event
-@table @asis
-@item @emph{Description}:
-Fulfill the event associated with the event handle argument. Currently, it
-is only used to fulfill events generated by detach clauses on task
-constructs - the effect of fulfilling the event is to allow the task to
-complete.
-
-The result of calling @code{omp_fulfill_event} with an event handle other
-than that generated by a detach clause is undefined. Calling it with an
-event handle that has already been fulfilled is also undefined.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{void omp_fulfill_event(omp_event_handle_t event);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{subroutine omp_fulfill_event(event)}
-@item @tab @code{integer (kind=omp_event_handle_kind) :: event}
-@end multitable
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v5.0}, Section 3.5.1.
-@end table
-
-
-
-@c ---------------------------------------------------------------------
-@c OpenMP Environment Variables
-@c ---------------------------------------------------------------------
-
-@node Environment Variables
-@chapter OpenMP Environment Variables
-
-The environment variables which beginning with @env{OMP_} are defined by
-section 4 of the OpenMP specification in version 4.5, while those
-beginning with @env{GOMP_} are GNU extensions.
-
-@menu
-* OMP_CANCELLATION:: Set whether cancellation is activated
-* OMP_DISPLAY_ENV:: Show OpenMP version and environment variables
-* OMP_DEFAULT_DEVICE:: Set the device used in target regions
-* OMP_DYNAMIC:: Dynamic adjustment of threads
-* OMP_MAX_ACTIVE_LEVELS:: Set the maximum number of nested parallel regions
-* OMP_MAX_TASK_PRIORITY:: Set the maximum task priority value
-* OMP_NESTED:: Nested parallel regions
-* OMP_NUM_TEAMS:: Specifies the number of teams to use by teams region
-* OMP_NUM_THREADS:: Specifies the number of threads to use
-* OMP_PROC_BIND:: Whether theads may be moved between CPUs
-* OMP_PLACES:: Specifies on which CPUs the theads should be placed
-* OMP_STACKSIZE:: Set default thread stack size
-* OMP_SCHEDULE:: How threads are scheduled
-* OMP_TARGET_OFFLOAD:: Controls offloading behaviour
-* OMP_TEAMS_THREAD_LIMIT:: Set the maximum number of threads imposed by teams
-* OMP_THREAD_LIMIT:: Set the maximum number of threads
-* OMP_WAIT_POLICY:: How waiting threads are handled
-* GOMP_CPU_AFFINITY:: Bind threads to specific CPUs
-* GOMP_DEBUG:: Enable debugging output
-* GOMP_STACKSIZE:: Set default thread stack size
-* GOMP_SPINCOUNT:: Set the busy-wait spin count
-* GOMP_RTEMS_THREAD_POOLS:: Set the RTEMS specific thread pools
-@end menu
-
-
-@node OMP_CANCELLATION
-@section @env{OMP_CANCELLATION} -- Set whether cancellation is activated
-@cindex Environment Variable
-@table @asis
-@item @emph{Description}:
-If set to @code{TRUE}, the cancellation is activated. If set to @code{FALSE} or
-if unset, cancellation is disabled and the @code{cancel} construct is ignored.
-
-@item @emph{See also}:
-@ref{omp_get_cancellation}
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 4.11
-@end table
-
-
-
-@node OMP_DISPLAY_ENV
-@section @env{OMP_DISPLAY_ENV} -- Show OpenMP version and environment variables
-@cindex Environment Variable
-@table @asis
-@item @emph{Description}:
-If set to @code{TRUE}, the OpenMP version number and the values
-associated with the OpenMP environment variables are printed to @code{stderr}.
-If set to @code{VERBOSE}, it additionally shows the value of the environment
-variables which are GNU extensions. If undefined or set to @code{FALSE},
-this information will not be shown.
-
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 4.12
-@end table
-
-
-
-@node OMP_DEFAULT_DEVICE
-@section @env{OMP_DEFAULT_DEVICE} -- Set the device used in target regions
-@cindex Environment Variable
-@table @asis
-@item @emph{Description}:
-Set to choose the device which is used in a @code{target} region, unless the
-value is overridden by @code{omp_set_default_device} or by a @code{device}
-clause. The value shall be the nonnegative device number. If no device with
-the given device number exists, the code is executed on the host. If unset,
-device number 0 will be used.
-
-
-@item @emph{See also}:
-@ref{omp_get_default_device}, @ref{omp_set_default_device},
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 4.13
-@end table
-
-
-
-@node OMP_DYNAMIC
-@section @env{OMP_DYNAMIC} -- Dynamic adjustment of threads
-@cindex Environment Variable
-@table @asis
-@item @emph{Description}:
-Enable or disable the dynamic adjustment of the number of threads
-within a team. The value of this environment variable shall be
-@code{TRUE} or @code{FALSE}. If undefined, dynamic adjustment is
-disabled by default.
-
-@item @emph{See also}:
-@ref{omp_set_dynamic}
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 4.3
-@end table
-
-
-
-@node OMP_MAX_ACTIVE_LEVELS
-@section @env{OMP_MAX_ACTIVE_LEVELS} -- Set the maximum number of nested parallel regions
-@cindex Environment Variable
-@table @asis
-@item @emph{Description}:
-Specifies the initial value for the maximum number of nested parallel
-regions. The value of this variable shall be a positive integer.
-If undefined, then if @env{OMP_NESTED} is defined and set to true, or
-if @env{OMP_NUM_THREADS} or @env{OMP_PROC_BIND} are defined and set to
-a list with more than one item, the maximum number of nested parallel
-regions will be initialized to the largest number supported, otherwise
-it will be set to one.
-
-@item @emph{See also}:
-@ref{omp_set_max_active_levels}, @ref{OMP_NESTED}
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 4.9
-@end table
-
-
-
-@node OMP_MAX_TASK_PRIORITY
-@section @env{OMP_MAX_TASK_PRIORITY} -- Set the maximum priority
-number that can be set for a task.
-@cindex Environment Variable
-@table @asis
-@item @emph{Description}:
-Specifies the initial value for the maximum priority value that can be
-set for a task. The value of this variable shall be a non-negative
-integer, and zero is allowed. If undefined, the default priority is
-0.
-
-@item @emph{See also}:
-@ref{omp_get_max_task_priority}
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 4.14
-@end table
-
-
-
-@node OMP_NESTED
-@section @env{OMP_NESTED} -- Nested parallel regions
-@cindex Environment Variable
-@cindex Implementation specific setting
-@table @asis
-@item @emph{Description}:
-Enable or disable nested parallel regions, i.e., whether team members
-are allowed to create new teams. The value of this environment variable
-shall be @code{TRUE} or @code{FALSE}. If set to @code{TRUE}, the number
-of maximum active nested regions supported will by default be set to the
-maximum supported, otherwise it will be set to one. If
-@env{OMP_MAX_ACTIVE_LEVELS} is defined, its setting will override this
-setting. If both are undefined, nested parallel regions are enabled if
-@env{OMP_NUM_THREADS} or @env{OMP_PROC_BINDS} are defined to a list with
-more than one item, otherwise they are disabled by default.
-
-@item @emph{See also}:
-@ref{omp_set_max_active_levels}, @ref{omp_set_nested}
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 4.6
-@end table
-
-
-
-@node OMP_NUM_TEAMS
-@section @env{OMP_NUM_TEAMS} -- Specifies the number of teams to use by teams region
-@cindex Environment Variable
-@table @asis
-@item @emph{Description}:
-Specifies the upper bound for number of teams to use in teams regions
-without explicit @code{num_teams} clause. The value of this variable shall
-be a positive integer. If undefined it defaults to 0 which means
-implementation defined upper bound.
-
-@item @emph{See also}:
-@ref{omp_set_num_teams}
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v5.1}, Section 6.23
-@end table
-
-
-
-@node OMP_NUM_THREADS
-@section @env{OMP_NUM_THREADS} -- Specifies the number of threads to use
-@cindex Environment Variable
-@cindex Implementation specific setting
-@table @asis
-@item @emph{Description}:
-Specifies the default number of threads to use in parallel regions. The
-value of this variable shall be a comma-separated list of positive integers;
-the value specifies the number of threads to use for the corresponding nested
-level. Specifying more than one item in the list will automatically enable
-nesting by default. If undefined one thread per CPU is used.
-
-@item @emph{See also}:
-@ref{omp_set_num_threads}, @ref{OMP_NESTED}
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 4.2
-@end table
-
-
-
-@node OMP_PROC_BIND
-@section @env{OMP_PROC_BIND} -- Whether theads may be moved between CPUs
-@cindex Environment Variable
-@table @asis
-@item @emph{Description}:
-Specifies whether threads may be moved between processors. If set to
-@code{TRUE}, OpenMP theads should not be moved; if set to @code{FALSE}
-they may be moved. Alternatively, a comma separated list with the
-values @code{PRIMARY}, @code{MASTER}, @code{CLOSE} and @code{SPREAD} can
-be used to specify the thread affinity policy for the corresponding nesting
-level. With @code{PRIMARY} and @code{MASTER} the worker threads are in the
-same place partition as the primary thread. With @code{CLOSE} those are
-kept close to the primary thread in contiguous place partitions. And
-with @code{SPREAD} a sparse distribution
-across the place partitions is used. Specifying more than one item in the
-list will automatically enable nesting by default.
-
-When undefined, @env{OMP_PROC_BIND} defaults to @code{TRUE} when
-@env{OMP_PLACES} or @env{GOMP_CPU_AFFINITY} is set and @code{FALSE} otherwise.
-
-@item @emph{See also}:
-@ref{omp_get_proc_bind}, @ref{GOMP_CPU_AFFINITY},
-@ref{OMP_NESTED}, @ref{OMP_PLACES}
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 4.4
-@end table
-
-
-
-@node OMP_PLACES
-@section @env{OMP_PLACES} -- Specifies on which CPUs the theads should be placed
-@cindex Environment Variable
-@table @asis
-@item @emph{Description}:
-The thread placement can be either specified using an abstract name or by an
-explicit list of the places. The abstract names @code{threads}, @code{cores},
-@code{sockets}, @code{ll_caches} and @code{numa_domains} can be optionally
-followed by a positive number in parentheses, which denotes the how many places
-shall be created. With @code{threads} each place corresponds to a single
-hardware thread; @code{cores} to a single core with the corresponding number of
-hardware threads; with @code{sockets} the place corresponds to a single
-socket; with @code{ll_caches} to a set of cores that shares the last level
-cache on the device; and @code{numa_domains} to a set of cores for which their
-closest memory on the device is the same memory and at a similar distance from
-the cores. The resulting placement can be shown by setting the
-@env{OMP_DISPLAY_ENV} environment variable.
-
-Alternatively, the placement can be specified explicitly as comma-separated
-list of places. A place is specified by set of nonnegative numbers in curly
-braces, denoting the hardware threads. The curly braces can be omitted
-when only a single number has been specified. The hardware threads
-belonging to a place can either be specified as comma-separated list of
-nonnegative thread numbers or using an interval. Multiple places can also be
-either specified by a comma-separated list of places or by an interval. To
-specify an interval, a colon followed by the count is placed after
-the hardware thread number or the place. Optionally, the length can be
-followed by a colon and the stride number -- otherwise a unit stride is
-assumed. Placing an exclamation mark (@code{!}) directly before a curly
-brace or numbers inside the curly braces (excluding intervals) will
-exclude those hardware threads.
-
-For instance, the following specifies the same places list:
-@code{"@{0,1,2@}, @{3,4,6@}, @{7,8,9@}, @{10,11,12@}"};
-@code{"@{0:3@}, @{3:3@}, @{7:3@}, @{10:3@}"}; and @code{"@{0:2@}:4:3"}.
-
-If @env{OMP_PLACES} and @env{GOMP_CPU_AFFINITY} are unset and
-@env{OMP_PROC_BIND} is either unset or @code{false}, threads may be moved
-between CPUs following no placement policy.
-
-@item @emph{See also}:
-@ref{OMP_PROC_BIND}, @ref{GOMP_CPU_AFFINITY}, @ref{omp_get_proc_bind},
-@ref{OMP_DISPLAY_ENV}
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 4.5
-@end table
-
-
-
-@node OMP_STACKSIZE
-@section @env{OMP_STACKSIZE} -- Set default thread stack size
-@cindex Environment Variable
-@table @asis
-@item @emph{Description}:
-Set the default thread stack size in kilobytes, unless the number
-is suffixed by @code{B}, @code{K}, @code{M} or @code{G}, in which
-case the size is, respectively, in bytes, kilobytes, megabytes
-or gigabytes. This is different from @code{pthread_attr_setstacksize}
-which gets the number of bytes as an argument. If the stack size cannot
-be set due to system constraints, an error is reported and the initial
-stack size is left unchanged. If undefined, the stack size is system
-dependent.
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 4.7
-@end table
-
-
-
-@node OMP_SCHEDULE
-@section @env{OMP_SCHEDULE} -- How threads are scheduled
-@cindex Environment Variable
-@cindex Implementation specific setting
-@table @asis
-@item @emph{Description}:
-Allows to specify @code{schedule type} and @code{chunk size}.
-The value of the variable shall have the form: @code{type[,chunk]} where
-@code{type} is one of @code{static}, @code{dynamic}, @code{guided} or @code{auto}
-The optional @code{chunk} size shall be a positive integer. If undefined,
-dynamic scheduling and a chunk size of 1 is used.
-
-@item @emph{See also}:
-@ref{omp_set_schedule}
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Sections 2.7.1.1 and 4.1
-@end table
-
-
-
-@node OMP_TARGET_OFFLOAD
-@section @env{OMP_TARGET_OFFLOAD} -- Controls offloading behaviour
-@cindex Environment Variable
-@cindex Implementation specific setting
-@table @asis
-@item @emph{Description}:
-Specifies the behaviour with regard to offloading code to a device. This
-variable can be set to one of three values - @code{MANDATORY}, @code{DISABLED}
-or @code{DEFAULT}.
-
-If set to @code{MANDATORY}, the program will terminate with an error if
-the offload device is not present or is not supported. If set to
-@code{DISABLED}, then offloading is disabled and all code will run on the
-host. If set to @code{DEFAULT}, the program will try offloading to the
-device first, then fall back to running code on the host if it cannot.
-
-If undefined, then the program will behave as if @code{DEFAULT} was set.
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v5.0}, Section 6.17
-@end table
-
-
-
-@node OMP_TEAMS_THREAD_LIMIT
-@section @env{OMP_TEAMS_THREAD_LIMIT} -- Set the maximum number of threads imposed by teams
-@cindex Environment Variable
-@table @asis
-@item @emph{Description}:
-Specifies an upper bound for the number of threads to use by each contention
-group created by a teams construct without explicit @code{thread_limit}
-clause. The value of this variable shall be a positive integer. If undefined,
-the value of 0 is used which stands for an implementation defined upper
-limit.
-
-@item @emph{See also}:
-@ref{OMP_THREAD_LIMIT}, @ref{omp_set_teams_thread_limit}
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v5.1}, Section 6.24
-@end table
-
-
-
-@node OMP_THREAD_LIMIT
-@section @env{OMP_THREAD_LIMIT} -- Set the maximum number of threads
-@cindex Environment Variable
-@table @asis
-@item @emph{Description}:
-Specifies the number of threads to use for the whole program. The
-value of this variable shall be a positive integer. If undefined,
-the number of threads is not limited.
-
-@item @emph{See also}:
-@ref{OMP_NUM_THREADS}, @ref{omp_get_thread_limit}
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 4.10
-@end table
-
-
-
-@node OMP_WAIT_POLICY
-@section @env{OMP_WAIT_POLICY} -- How waiting threads are handled
-@cindex Environment Variable
-@table @asis
-@item @emph{Description}:
-Specifies whether waiting threads should be active or passive. If
-the value is @code{PASSIVE}, waiting threads should not consume CPU
-power while waiting; while the value is @code{ACTIVE} specifies that
-they should. If undefined, threads wait actively for a short time
-before waiting passively.
-
-@item @emph{See also}:
-@ref{GOMP_SPINCOUNT}
-
-@item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 4.8
-@end table
-
-
-
-@node GOMP_CPU_AFFINITY
-@section @env{GOMP_CPU_AFFINITY} -- Bind threads to specific CPUs
-@cindex Environment Variable
-@table @asis
-@item @emph{Description}:
-Binds threads to specific CPUs. The variable should contain a space-separated
-or comma-separated list of CPUs. This list may contain different kinds of
-entries: either single CPU numbers in any order, a range of CPUs (M-N)
-or a range with some stride (M-N:S). CPU numbers are zero based. For example,
-@code{GOMP_CPU_AFFINITY="0 3 1-2 4-15:2"} will bind the initial thread
-to CPU 0, the second to CPU 3, the third to CPU 1, the fourth to
-CPU 2, the fifth to CPU 4, the sixth through tenth to CPUs 6, 8, 10, 12,
-and 14 respectively and then start assigning back from the beginning of
-the list. @code{GOMP_CPU_AFFINITY=0} binds all threads to CPU 0.
-
-There is no libgomp library routine to determine whether a CPU affinity
-specification is in effect. As a workaround, language-specific library
-functions, e.g., @code{getenv} in C or @code{GET_ENVIRONMENT_VARIABLE} in
-Fortran, may be used to query the setting of the @code{GOMP_CPU_AFFINITY}
-environment variable. A defined CPU affinity on startup cannot be changed
-or disabled during the runtime of the application.
-
-If both @env{GOMP_CPU_AFFINITY} and @env{OMP_PROC_BIND} are set,
-@env{OMP_PROC_BIND} has a higher precedence. If neither has been set and
-@env{OMP_PROC_BIND} is unset, or when @env{OMP_PROC_BIND} is set to
-@code{FALSE}, the host system will handle the assignment of threads to CPUs.
-
-@item @emph{See also}:
-@ref{OMP_PLACES}, @ref{OMP_PROC_BIND}
-@end table
-
-
-
-@node GOMP_DEBUG
-@section @env{GOMP_DEBUG} -- Enable debugging output
-@cindex Environment Variable
-@table @asis
-@item @emph{Description}:
-Enable debugging output. The variable should be set to @code{0}
-(disabled, also the default if not set), or @code{1} (enabled).
-
-If enabled, some debugging output will be printed during execution.
-This is currently not specified in more detail, and subject to change.
-@end table
-
-
-
-@node GOMP_STACKSIZE
-@section @env{GOMP_STACKSIZE} -- Set default thread stack size
-@cindex Environment Variable
-@cindex Implementation specific setting
-@table @asis
-@item @emph{Description}:
-Set the default thread stack size in kilobytes. This is different from
-@code{pthread_attr_setstacksize} which gets the number of bytes as an
-argument. If the stack size cannot be set due to system constraints, an
-error is reported and the initial stack size is left unchanged. If undefined,
-the stack size is system dependent.
-
-@item @emph{See also}:
-@ref{OMP_STACKSIZE}
-
-@item @emph{Reference}:
-@uref{https://gcc.gnu.org/ml/gcc-patches/2006-06/msg00493.html,
-GCC Patches Mailinglist},
-@uref{https://gcc.gnu.org/ml/gcc-patches/2006-06/msg00496.html,
-GCC Patches Mailinglist}
-@end table
-
-
-
-@node GOMP_SPINCOUNT
-@section @env{GOMP_SPINCOUNT} -- Set the busy-wait spin count
-@cindex Environment Variable
-@cindex Implementation specific setting
-@table @asis
-@item @emph{Description}:
-Determines how long a threads waits actively with consuming CPU power
-before waiting passively without consuming CPU power. The value may be
-either @code{INFINITE}, @code{INFINITY} to always wait actively or an
-integer which gives the number of spins of the busy-wait loop. The
-integer may optionally be followed by the following suffixes acting
-as multiplication factors: @code{k} (kilo, thousand), @code{M} (mega,
-million), @code{G} (giga, billion), or @code{T} (tera, trillion).
-If undefined, 0 is used when @env{OMP_WAIT_POLICY} is @code{PASSIVE},
-300,000 is used when @env{OMP_WAIT_POLICY} is undefined and
-30 billion is used when @env{OMP_WAIT_POLICY} is @code{ACTIVE}.
-If there are more OpenMP threads than available CPUs, 1000 and 100
-spins are used for @env{OMP_WAIT_POLICY} being @code{ACTIVE} or
-undefined, respectively; unless the @env{GOMP_SPINCOUNT} is lower
-or @env{OMP_WAIT_POLICY} is @code{PASSIVE}.
-
-@item @emph{See also}:
-@ref{OMP_WAIT_POLICY}
-@end table
-
-
-
-@node GOMP_RTEMS_THREAD_POOLS
-@section @env{GOMP_RTEMS_THREAD_POOLS} -- Set the RTEMS specific thread pools
-@cindex Environment Variable
-@cindex Implementation specific setting
-@table @asis
-@item @emph{Description}:
-This environment variable is only used on the RTEMS real-time operating system.
-It determines the scheduler instance specific thread pools. The format for
-@env{GOMP_RTEMS_THREAD_POOLS} is a list of optional
-@code{<thread-pool-count>[$<priority>]@@<scheduler-name>} configurations
-separated by @code{:} where:
-@itemize @bullet
-@item @code{<thread-pool-count>} is the thread pool count for this scheduler
-instance.
-@item @code{$<priority>} is an optional priority for the worker threads of a
-thread pool according to @code{pthread_setschedparam}. In case a priority
-value is omitted, then a worker thread will inherit the priority of the OpenMP
-primary thread that created it. The priority of the worker thread is not
-changed after creation, even if a new OpenMP primary thread using the worker has
-a different priority.
-@item @code{@@<scheduler-name>} is the scheduler instance name according to the
-RTEMS application configuration.
-@end itemize
-In case no thread pool configuration is specified for a scheduler instance,
-then each OpenMP primary thread of this scheduler instance will use its own
-dynamically allocated thread pool. To limit the worker thread count of the
-thread pools, each OpenMP primary thread must call @code{omp_set_num_threads}.
-@item @emph{Example}:
-Lets suppose we have three scheduler instances @code{IO}, @code{WRK0}, and
-@code{WRK1} with @env{GOMP_RTEMS_THREAD_POOLS} set to
-@code{"1@@WRK0:3$4@@WRK1"}. Then there are no thread pool restrictions for
-scheduler instance @code{IO}. In the scheduler instance @code{WRK0} there is
-one thread pool available. Since no priority is specified for this scheduler
-instance, the worker thread inherits the priority of the OpenMP primary thread
-that created it. In the scheduler instance @code{WRK1} there are three thread
-pools available and their worker threads run at priority four.
-@end table
-
-
-
-@c ---------------------------------------------------------------------
-@c Enabling OpenACC
-@c ---------------------------------------------------------------------
-
-@node Enabling OpenACC
-@chapter Enabling OpenACC
-
-To activate the OpenACC extensions for C/C++ and Fortran, the compile-time
-flag @option{-fopenacc} must be specified. This enables the OpenACC directive
-@code{#pragma acc} in C/C++ and @code{!$acc} directives in free form,
-@code{c$acc}, @code{*$acc} and @code{!$acc} directives in fixed form,
-@code{!$} conditional compilation sentinels in free form and @code{c$},
-@code{*$} and @code{!$} sentinels in fixed form, for Fortran. The flag also
-arranges for automatic linking of the OpenACC runtime library
-(@ref{OpenACC Runtime Library Routines}).
-
-See @uref{https://gcc.gnu.org/wiki/OpenACC} for more information.
-
-A complete description of all OpenACC directives accepted may be found in
-the @uref{https://www.openacc.org, OpenACC} Application Programming
-Interface manual, version 2.6.
-
-
-
-@c ---------------------------------------------------------------------
-@c OpenACC Runtime Library Routines
-@c ---------------------------------------------------------------------
-
-@node OpenACC Runtime Library Routines
-@chapter OpenACC Runtime Library Routines
-
-The runtime routines described here are defined by section 3 of the OpenACC
-specifications in version 2.6.
-They have C linkage, and do not throw exceptions.
-Generally, they are available only for the host, with the exception of
-@code{acc_on_device}, which is available for both the host and the
-acceleration device.
-
-@menu
-* acc_get_num_devices:: Get number of devices for the given device
- type.
-* acc_set_device_type:: Set type of device accelerator to use.
-* acc_get_device_type:: Get type of device accelerator to be used.
-* acc_set_device_num:: Set device number to use.
-* acc_get_device_num:: Get device number to be used.
-* acc_get_property:: Get device property.
-* acc_async_test:: Tests for completion of a specific asynchronous
- operation.
-* acc_async_test_all:: Tests for completion of all asynchronous
- operations.
-* acc_wait:: Wait for completion of a specific asynchronous
- operation.
-* acc_wait_all:: Waits for completion of all asynchronous
- operations.
-* acc_wait_all_async:: Wait for completion of all asynchronous
- operations.
-* acc_wait_async:: Wait for completion of asynchronous operations.
-* acc_init:: Initialize runtime for a specific device type.
-* acc_shutdown:: Shuts down the runtime for a specific device
- type.
-* acc_on_device:: Whether executing on a particular device
-* acc_malloc:: Allocate device memory.
-* acc_free:: Free device memory.
-* acc_copyin:: Allocate device memory and copy host memory to
- it.
-* acc_present_or_copyin:: If the data is not present on the device,
- allocate device memory and copy from host
- memory.
-* acc_create:: Allocate device memory and map it to host
- memory.
-* acc_present_or_create:: If the data is not present on the device,
- allocate device memory and map it to host
- memory.
-* acc_copyout:: Copy device memory to host memory.
-* acc_delete:: Free device memory.
-* acc_update_device:: Update device memory from mapped host memory.
-* acc_update_self:: Update host memory from mapped device memory.
-* acc_map_data:: Map previously allocated device memory to host
- memory.
-* acc_unmap_data:: Unmap device memory from host memory.
-* acc_deviceptr:: Get device pointer associated with specific
- host address.
-* acc_hostptr:: Get host pointer associated with specific
- device address.
-* acc_is_present:: Indicate whether host variable / array is
- present on device.
-* acc_memcpy_to_device:: Copy host memory to device memory.
-* acc_memcpy_from_device:: Copy device memory to host memory.
-* acc_attach:: Let device pointer point to device-pointer target.
-* acc_detach:: Let device pointer point to host-pointer target.
-
-API routines for target platforms.
-
-* acc_get_current_cuda_device:: Get CUDA device handle.
-* acc_get_current_cuda_context::Get CUDA context handle.
-* acc_get_cuda_stream:: Get CUDA stream handle.
-* acc_set_cuda_stream:: Set CUDA stream handle.
-
-API routines for the OpenACC Profiling Interface.
-
-* acc_prof_register:: Register callbacks.
-* acc_prof_unregister:: Unregister callbacks.
-* acc_prof_lookup:: Obtain inquiry functions.
-* acc_register_library:: Library registration.
-@end menu
-
-
-
-@node acc_get_num_devices
-@section @code{acc_get_num_devices} -- Get number of devices for given device type
-@table @asis
-@item @emph{Description}
-This function returns a value indicating the number of devices available
-for the device type specified in @var{devicetype}.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{int acc_get_num_devices(acc_device_t devicetype);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{integer function acc_get_num_devices(devicetype)}
-@item @tab @code{integer(kind=acc_device_kind) devicetype}
-@end multitable
-
-@item @emph{Reference}:
-@uref{https://www.openacc.org, OpenACC specification v2.6}, section
-3.2.1.
-@end table
-
-
-
-@node acc_set_device_type
-@section @code{acc_set_device_type} -- Set type of device accelerator to use.
-@table @asis
-@item @emph{Description}
-This function indicates to the runtime library which device type, specified
-in @var{devicetype}, to use when executing a parallel or kernels region.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{acc_set_device_type(acc_device_t devicetype);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{subroutine acc_set_device_type(devicetype)}
-@item @tab @code{integer(kind=acc_device_kind) devicetype}
-@end multitable
-
-@item @emph{Reference}:
-@uref{https://www.openacc.org, OpenACC specification v2.6}, section
-3.2.2.
-@end table
-
-
-
-@node acc_get_device_type
-@section @code{acc_get_device_type} -- Get type of device accelerator to be used.
-@table @asis
-@item @emph{Description}
-This function returns what device type will be used when executing a
-parallel or kernels region.
-
-This function returns @code{acc_device_none} if
-@code{acc_get_device_type} is called from
-@code{acc_ev_device_init_start}, @code{acc_ev_device_init_end}
-callbacks of the OpenACC Profiling Interface (@ref{OpenACC Profiling
-Interface}), that is, if the device is currently being initialized.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{acc_device_t acc_get_device_type(void);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{function acc_get_device_type(void)}
-@item @tab @code{integer(kind=acc_device_kind) acc_get_device_type}
-@end multitable
-
-@item @emph{Reference}:
-@uref{https://www.openacc.org, OpenACC specification v2.6}, section
-3.2.3.
-@end table
-
-
-
-@node acc_set_device_num
-@section @code{acc_set_device_num} -- Set device number to use.
-@table @asis
-@item @emph{Description}
-This function will indicate to the runtime which device number,
-specified by @var{devicenum}, associated with the specified device
-type @var{devicetype}.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{acc_set_device_num(int devicenum, acc_device_t devicetype);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{subroutine acc_set_device_num(devicenum, devicetype)}
-@item @tab @code{integer devicenum}
-@item @tab @code{integer(kind=acc_device_kind) devicetype}
-@end multitable
-
-@item @emph{Reference}:
-@uref{https://www.openacc.org, OpenACC specification v2.6}, section
-3.2.4.
-@end table
-
-
-
-@node acc_get_device_num
-@section @code{acc_get_device_num} -- Get device number to be used.
-@table @asis
-@item @emph{Description}
-This function returns which device number associated with the specified device
-type @var{devicetype}, will be used when executing a parallel or kernels
-region.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{int acc_get_device_num(acc_device_t devicetype);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{function acc_get_device_num(devicetype)}
-@item @tab @code{integer(kind=acc_device_kind) devicetype}
-@item @tab @code{integer acc_get_device_num}
-@end multitable
-
-@item @emph{Reference}:
-@uref{https://www.openacc.org, OpenACC specification v2.6}, section
-3.2.5.
-@end table
-
-
-
-@node acc_get_property
-@section @code{acc_get_property} -- Get device property.
-@cindex acc_get_property
-@cindex acc_get_property_string
-@table @asis
-@item @emph{Description}
-These routines return the value of the specified @var{property} for the
-device being queried according to @var{devicenum} and @var{devicetype}.
-Integer-valued and string-valued properties are returned by
-@code{acc_get_property} and @code{acc_get_property_string} respectively.
-The Fortran @code{acc_get_property_string} subroutine returns the string
-retrieved in its fourth argument while the remaining entry points are
-functions, which pass the return value as their result.
-
-Note for Fortran, only: the OpenACC technical committee corrected and, hence,
-modified the interface introduced in OpenACC 2.6. The kind-value parameter
-@code{acc_device_property} has been renamed to @code{acc_device_property_kind}
-for consistency and the return type of the @code{acc_get_property} function is
-now a @code{c_size_t} integer instead of a @code{acc_device_property} integer.
-The parameter @code{acc_device_property} will continue to be provided,
-but might be removed in a future version of GCC.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{size_t acc_get_property(int devicenum, acc_device_t devicetype, acc_device_property_t property);}
-@item @emph{Prototype}: @tab @code{const char *acc_get_property_string(int devicenum, acc_device_t devicetype, acc_device_property_t property);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{function acc_get_property(devicenum, devicetype, property)}
-@item @emph{Interface}: @tab @code{subroutine acc_get_property_string(devicenum, devicetype, property, string)}
-@item @tab @code{use ISO_C_Binding, only: c_size_t}
-@item @tab @code{integer devicenum}
-@item @tab @code{integer(kind=acc_device_kind) devicetype}
-@item @tab @code{integer(kind=acc_device_property_kind) property}
-@item @tab @code{integer(kind=c_size_t) acc_get_property}
-@item @tab @code{character(*) string}
-@end multitable
-
-@item @emph{Reference}:
-@uref{https://www.openacc.org, OpenACC specification v2.6}, section
-3.2.6.
-@end table
-
-
-
-@node acc_async_test
-@section @code{acc_async_test} -- Test for completion of a specific asynchronous operation.
-@table @asis
-@item @emph{Description}
-This function tests for completion of the asynchronous operation specified
-in @var{arg}. In C/C++, a non-zero value will be returned to indicate
-the specified asynchronous operation has completed. While Fortran will return
-a @code{true}. If the asynchronous operation has not completed, C/C++ returns
-a zero and Fortran returns a @code{false}.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{int acc_async_test(int arg);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{function acc_async_test(arg)}
-@item @tab @code{integer(kind=acc_handle_kind) arg}
-@item @tab @code{logical acc_async_test}
-@end multitable
-
-@item @emph{Reference}:
-@uref{https://www.openacc.org, OpenACC specification v2.6}, section
-3.2.9.
-@end table
-
-
-
-@node acc_async_test_all
-@section @code{acc_async_test_all} -- Tests for completion of all asynchronous operations.
-@table @asis
-@item @emph{Description}
-This function tests for completion of all asynchronous operations.
-In C/C++, a non-zero value will be returned to indicate all asynchronous
-operations have completed. While Fortran will return a @code{true}. If
-any asynchronous operation has not completed, C/C++ returns a zero and
-Fortran returns a @code{false}.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{int acc_async_test_all(void);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{function acc_async_test()}
-@item @tab @code{logical acc_get_device_num}
-@end multitable
-
-@item @emph{Reference}:
-@uref{https://www.openacc.org, OpenACC specification v2.6}, section
-3.2.10.
-@end table
-
-
-
-@node acc_wait
-@section @code{acc_wait} -- Wait for completion of a specific asynchronous operation.
-@table @asis
-@item @emph{Description}
-This function waits for completion of the asynchronous operation
-specified in @var{arg}.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{acc_wait(arg);}
-@item @emph{Prototype (OpenACC 1.0 compatibility)}: @tab @code{acc_async_wait(arg);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{subroutine acc_wait(arg)}
-@item @tab @code{integer(acc_handle_kind) arg}
-@item @emph{Interface (OpenACC 1.0 compatibility)}: @tab @code{subroutine acc_async_wait(arg)}
-@item @tab @code{integer(acc_handle_kind) arg}
-@end multitable
-
-@item @emph{Reference}:
-@uref{https://www.openacc.org, OpenACC specification v2.6}, section
-3.2.11.
-@end table
-
-
-
-@node acc_wait_all
-@section @code{acc_wait_all} -- Waits for completion of all asynchronous operations.
-@table @asis
-@item @emph{Description}
-This function waits for the completion of all asynchronous operations.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{acc_wait_all(void);}
-@item @emph{Prototype (OpenACC 1.0 compatibility)}: @tab @code{acc_async_wait_all(void);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{subroutine acc_wait_all()}
-@item @emph{Interface (OpenACC 1.0 compatibility)}: @tab @code{subroutine acc_async_wait_all()}
-@end multitable
-
-@item @emph{Reference}:
-@uref{https://www.openacc.org, OpenACC specification v2.6}, section
-3.2.13.
-@end table
-
-
-
-@node acc_wait_all_async
-@section @code{acc_wait_all_async} -- Wait for completion of all asynchronous operations.
-@table @asis
-@item @emph{Description}
-This function enqueues a wait operation on the queue @var{async} for any
-and all asynchronous operations that have been previously enqueued on
-any queue.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{acc_wait_all_async(int async);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{subroutine acc_wait_all_async(async)}
-@item @tab @code{integer(acc_handle_kind) async}
-@end multitable
-
-@item @emph{Reference}:
-@uref{https://www.openacc.org, OpenACC specification v2.6}, section
-3.2.14.
-@end table
-
-
-
-@node acc_wait_async
-@section @code{acc_wait_async} -- Wait for completion of asynchronous operations.
-@table @asis
-@item @emph{Description}
-This function enqueues a wait operation on queue @var{async} for any and all
-asynchronous operations enqueued on queue @var{arg}.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{acc_wait_async(int arg, int async);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{subroutine acc_wait_async(arg, async)}
-@item @tab @code{integer(acc_handle_kind) arg, async}
-@end multitable
-
-@item @emph{Reference}:
-@uref{https://www.openacc.org, OpenACC specification v2.6}, section
-3.2.12.
-@end table
-
-
-
-@node acc_init
-@section @code{acc_init} -- Initialize runtime for a specific device type.
-@table @asis
-@item @emph{Description}
-This function initializes the runtime for the device type specified in
-@var{devicetype}.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{acc_init(acc_device_t devicetype);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{subroutine acc_init(devicetype)}
-@item @tab @code{integer(acc_device_kind) devicetype}
-@end multitable
-
-@item @emph{Reference}:
-@uref{https://www.openacc.org, OpenACC specification v2.6}, section
-3.2.7.
-@end table
-
-
-
-@node acc_shutdown
-@section @code{acc_shutdown} -- Shuts down the runtime for a specific device type.
-@table @asis
-@item @emph{Description}
-This function shuts down the runtime for the device type specified in
-@var{devicetype}.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{acc_shutdown(acc_device_t devicetype);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{subroutine acc_shutdown(devicetype)}
-@item @tab @code{integer(acc_device_kind) devicetype}
-@end multitable
-
-@item @emph{Reference}:
-@uref{https://www.openacc.org, OpenACC specification v2.6}, section
-3.2.8.
-@end table
-
-
-
-@node acc_on_device
-@section @code{acc_on_device} -- Whether executing on a particular device
-@table @asis
-@item @emph{Description}:
-This function returns whether the program is executing on a particular
-device specified in @var{devicetype}. In C/C++ a non-zero value is
-returned to indicate the device is executing on the specified device type.
-In Fortran, @code{true} will be returned. If the program is not executing
-on the specified device type C/C++ will return a zero, while Fortran will
-return @code{false}.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{acc_on_device(acc_device_t devicetype);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{function acc_on_device(devicetype)}
-@item @tab @code{integer(acc_device_kind) devicetype}
-@item @tab @code{logical acc_on_device}
-@end multitable
-
-
-@item @emph{Reference}:
-@uref{https://www.openacc.org, OpenACC specification v2.6}, section
-3.2.17.
-@end table
-
-
-
-@node acc_malloc
-@section @code{acc_malloc} -- Allocate device memory.
-@table @asis
-@item @emph{Description}
-This function allocates @var{len} bytes of device memory. It returns
-the device address of the allocated memory.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{d_void* acc_malloc(size_t len);}
-@end multitable
-
-@item @emph{Reference}:
-@uref{https://www.openacc.org, OpenACC specification v2.6}, section
-3.2.18.
-@end table
-
-
-
-@node acc_free
-@section @code{acc_free} -- Free device memory.
-@table @asis
-@item @emph{Description}
-Free previously allocated device memory at the device address @code{a}.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{acc_free(d_void *a);}
-@end multitable
-
-@item @emph{Reference}:
-@uref{https://www.openacc.org, OpenACC specification v2.6}, section
-3.2.19.
-@end table
-
-
-
-@node acc_copyin
-@section @code{acc_copyin} -- Allocate device memory and copy host memory to it.
-@table @asis
-@item @emph{Description}
-In C/C++, this function allocates @var{len} bytes of device memory
-and maps it to the specified host address in @var{a}. The device
-address of the newly allocated device memory is returned.
-
-In Fortran, two (2) forms are supported. In the first form, @var{a} specifies
-a contiguous array section. The second form @var{a} specifies a
-variable or array element and @var{len} specifies the length in bytes.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{void *acc_copyin(h_void *a, size_t len);}
-@item @emph{Prototype}: @tab @code{void *acc_copyin_async(h_void *a, size_t len, int async);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{subroutine acc_copyin(a)}
-@item @tab @code{type, dimension(:[,:]...) :: a}
-@item @emph{Interface}: @tab @code{subroutine acc_copyin(a, len)}
-@item @tab @code{type, dimension(:[,:]...) :: a}
-@item @tab @code{integer len}
-@item @emph{Interface}: @tab @code{subroutine acc_copyin_async(a, async)}
-@item @tab @code{type, dimension(:[,:]...) :: a}
-@item @tab @code{integer(acc_handle_kind) :: async}
-@item @emph{Interface}: @tab @code{subroutine acc_copyin_async(a, len, async)}
-@item @tab @code{type, dimension(:[,:]...) :: a}
-@item @tab @code{integer len}
-@item @tab @code{integer(acc_handle_kind) :: async}
-@end multitable
-
-@item @emph{Reference}:
-@uref{https://www.openacc.org, OpenACC specification v2.6}, section
-3.2.20.
-@end table
-
-
-
-@node acc_present_or_copyin
-@section @code{acc_present_or_copyin} -- If the data is not present on the device, allocate device memory and copy from host memory.
-@table @asis
-@item @emph{Description}
-This function tests if the host data specified by @var{a} and of length
-@var{len} is present or not. If it is not present, then device memory
-will be allocated and the host memory copied. The device address of
-the newly allocated device memory is returned.
-
-In Fortran, two (2) forms are supported. In the first form, @var{a} specifies
-a contiguous array section. The second form @var{a} specifies a variable or
-array element and @var{len} specifies the length in bytes.
-
-Note that @code{acc_present_or_copyin} and @code{acc_pcopyin} exist for
-backward compatibility with OpenACC 2.0; use @ref{acc_copyin} instead.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{void *acc_present_or_copyin(h_void *a, size_t len);}
-@item @emph{Prototype}: @tab @code{void *acc_pcopyin(h_void *a, size_t len);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{subroutine acc_present_or_copyin(a)}
-@item @tab @code{type, dimension(:[,:]...) :: a}
-@item @emph{Interface}: @tab @code{subroutine acc_present_or_copyin(a, len)}
-@item @tab @code{type, dimension(:[,:]...) :: a}
-@item @tab @code{integer len}
-@item @emph{Interface}: @tab @code{subroutine acc_pcopyin(a)}
-@item @tab @code{type, dimension(:[,:]...) :: a}
-@item @emph{Interface}: @tab @code{subroutine acc_pcopyin(a, len)}
-@item @tab @code{type, dimension(:[,:]...) :: a}
-@item @tab @code{integer len}
-@end multitable
-
-@item @emph{Reference}:
-@uref{https://www.openacc.org, OpenACC specification v2.6}, section
-3.2.20.
-@end table
-
-
-
-@node acc_create
-@section @code{acc_create} -- Allocate device memory and map it to host memory.
-@table @asis
-@item @emph{Description}
-This function allocates device memory and maps it to host memory specified
-by the host address @var{a} with a length of @var{len} bytes. In C/C++,
-the function returns the device address of the allocated device memory.
-
-In Fortran, two (2) forms are supported. In the first form, @var{a} specifies
-a contiguous array section. The second form @var{a} specifies a variable or
-array element and @var{len} specifies the length in bytes.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{void *acc_create(h_void *a, size_t len);}
-@item @emph{Prototype}: @tab @code{void *acc_create_async(h_void *a, size_t len, int async);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{subroutine acc_create(a)}
-@item @tab @code{type, dimension(:[,:]...) :: a}
-@item @emph{Interface}: @tab @code{subroutine acc_create(a, len)}
-@item @tab @code{type, dimension(:[,:]...) :: a}
-@item @tab @code{integer len}
-@item @emph{Interface}: @tab @code{subroutine acc_create_async(a, async)}
-@item @tab @code{type, dimension(:[,:]...) :: a}
-@item @tab @code{integer(acc_handle_kind) :: async}
-@item @emph{Interface}: @tab @code{subroutine acc_create_async(a, len, async)}
-@item @tab @code{type, dimension(:[,:]...) :: a}
-@item @tab @code{integer len}
-@item @tab @code{integer(acc_handle_kind) :: async}
-@end multitable
-
-@item @emph{Reference}:
-@uref{https://www.openacc.org, OpenACC specification v2.6}, section
-3.2.21.
-@end table
-
-
-
-@node acc_present_or_create
-@section @code{acc_present_or_create} -- If the data is not present on the device, allocate device memory and map it to host memory.
-@table @asis
-@item @emph{Description}
-This function tests if the host data specified by @var{a} and of length
-@var{len} is present or not. If it is not present, then device memory
-will be allocated and mapped to host memory. In C/C++, the device address
-of the newly allocated device memory is returned.
-
-In Fortran, two (2) forms are supported. In the first form, @var{a} specifies
-a contiguous array section. The second form @var{a} specifies a variable or
-array element and @var{len} specifies the length in bytes.
-
-Note that @code{acc_present_or_create} and @code{acc_pcreate} exist for
-backward compatibility with OpenACC 2.0; use @ref{acc_create} instead.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{void *acc_present_or_create(h_void *a, size_t len)}
-@item @emph{Prototype}: @tab @code{void *acc_pcreate(h_void *a, size_t len)}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{subroutine acc_present_or_create(a)}
-@item @tab @code{type, dimension(:[,:]...) :: a}
-@item @emph{Interface}: @tab @code{subroutine acc_present_or_create(a, len)}
-@item @tab @code{type, dimension(:[,:]...) :: a}
-@item @tab @code{integer len}
-@item @emph{Interface}: @tab @code{subroutine acc_pcreate(a)}
-@item @tab @code{type, dimension(:[,:]...) :: a}
-@item @emph{Interface}: @tab @code{subroutine acc_pcreate(a, len)}
-@item @tab @code{type, dimension(:[,:]...) :: a}
-@item @tab @code{integer len}
-@end multitable
-
-@item @emph{Reference}:
-@uref{https://www.openacc.org, OpenACC specification v2.6}, section
-3.2.21.
-@end table
-
-
-
-@node acc_copyout
-@section @code{acc_copyout} -- Copy device memory to host memory.
-@table @asis
-@item @emph{Description}
-This function copies mapped device memory to host memory which is specified
-by host address @var{a} for a length @var{len} bytes in C/C++.
-
-In Fortran, two (2) forms are supported. In the first form, @var{a} specifies
-a contiguous array section. The second form @var{a} specifies a variable or
-array element and @var{len} specifies the length in bytes.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{acc_copyout(h_void *a, size_t len);}
-@item @emph{Prototype}: @tab @code{acc_copyout_async(h_void *a, size_t len, int async);}
-@item @emph{Prototype}: @tab @code{acc_copyout_finalize(h_void *a, size_t len);}
-@item @emph{Prototype}: @tab @code{acc_copyout_finalize_async(h_void *a, size_t len, int async);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{subroutine acc_copyout(a)}
-@item @tab @code{type, dimension(:[,:]...) :: a}
-@item @emph{Interface}: @tab @code{subroutine acc_copyout(a, len)}
-@item @tab @code{type, dimension(:[,:]...) :: a}
-@item @tab @code{integer len}
-@item @emph{Interface}: @tab @code{subroutine acc_copyout_async(a, async)}
-@item @tab @code{type, dimension(:[,:]...) :: a}
-@item @tab @code{integer(acc_handle_kind) :: async}
-@item @emph{Interface}: @tab @code{subroutine acc_copyout_async(a, len, async)}
-@item @tab @code{type, dimension(:[,:]...) :: a}
-@item @tab @code{integer len}
-@item @tab @code{integer(acc_handle_kind) :: async}
-@item @emph{Interface}: @tab @code{subroutine acc_copyout_finalize(a)}
-@item @tab @code{type, dimension(:[,:]...) :: a}
-@item @emph{Interface}: @tab @code{subroutine acc_copyout_finalize(a, len)}
-@item @tab @code{type, dimension(:[,:]...) :: a}
-@item @tab @code{integer len}
-@item @emph{Interface}: @tab @code{subroutine acc_copyout_finalize_async(a, async)}
-@item @tab @code{type, dimension(:[,:]...) :: a}
-@item @tab @code{integer(acc_handle_kind) :: async}
-@item @emph{Interface}: @tab @code{subroutine acc_copyout_finalize_async(a, len, async)}
-@item @tab @code{type, dimension(:[,:]...) :: a}
-@item @tab @code{integer len}
-@item @tab @code{integer(acc_handle_kind) :: async}
-@end multitable
-
-@item @emph{Reference}:
-@uref{https://www.openacc.org, OpenACC specification v2.6}, section
-3.2.22.
-@end table
-
-
-
-@node acc_delete
-@section @code{acc_delete} -- Free device memory.
-@table @asis
-@item @emph{Description}
-This function frees previously allocated device memory specified by
-the device address @var{a} and the length of @var{len} bytes.
-
-In Fortran, two (2) forms are supported. In the first form, @var{a} specifies
-a contiguous array section. The second form @var{a} specifies a variable or
-array element and @var{len} specifies the length in bytes.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{acc_delete(h_void *a, size_t len);}
-@item @emph{Prototype}: @tab @code{acc_delete_async(h_void *a, size_t len, int async);}
-@item @emph{Prototype}: @tab @code{acc_delete_finalize(h_void *a, size_t len);}
-@item @emph{Prototype}: @tab @code{acc_delete_finalize_async(h_void *a, size_t len, int async);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{subroutine acc_delete(a)}
-@item @tab @code{type, dimension(:[,:]...) :: a}
-@item @emph{Interface}: @tab @code{subroutine acc_delete(a, len)}
-@item @tab @code{type, dimension(:[,:]...) :: a}
-@item @tab @code{integer len}
-@item @emph{Interface}: @tab @code{subroutine acc_delete_async(a, async)}
-@item @tab @code{type, dimension(:[,:]...) :: a}
-@item @tab @code{integer(acc_handle_kind) :: async}
-@item @emph{Interface}: @tab @code{subroutine acc_delete_async(a, len, async)}
-@item @tab @code{type, dimension(:[,:]...) :: a}
-@item @tab @code{integer len}
-@item @tab @code{integer(acc_handle_kind) :: async}
-@item @emph{Interface}: @tab @code{subroutine acc_delete_finalize(a)}
-@item @tab @code{type, dimension(:[,:]...) :: a}
-@item @emph{Interface}: @tab @code{subroutine acc_delete_finalize(a, len)}
-@item @tab @code{type, dimension(:[,:]...) :: a}
-@item @tab @code{integer len}
-@item @emph{Interface}: @tab @code{subroutine acc_delete_async_finalize(a, async)}
-@item @tab @code{type, dimension(:[,:]...) :: a}
-@item @tab @code{integer(acc_handle_kind) :: async}
-@item @emph{Interface}: @tab @code{subroutine acc_delete_async_finalize(a, len, async)}
-@item @tab @code{type, dimension(:[,:]...) :: a}
-@item @tab @code{integer len}
-@item @tab @code{integer(acc_handle_kind) :: async}
-@end multitable
-
-@item @emph{Reference}:
-@uref{https://www.openacc.org, OpenACC specification v2.6}, section
-3.2.23.
-@end table
-
-
-
-@node acc_update_device
-@section @code{acc_update_device} -- Update device memory from mapped host memory.
-@table @asis
-@item @emph{Description}
-This function updates the device copy from the previously mapped host memory.
-The host memory is specified with the host address @var{a} and a length of
-@var{len} bytes.
-
-In Fortran, two (2) forms are supported. In the first form, @var{a} specifies
-a contiguous array section. The second form @var{a} specifies a variable or
-array element and @var{len} specifies the length in bytes.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{acc_update_device(h_void *a, size_t len);}
-@item @emph{Prototype}: @tab @code{acc_update_device(h_void *a, size_t len, async);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{subroutine acc_update_device(a)}
-@item @tab @code{type, dimension(:[,:]...) :: a}
-@item @emph{Interface}: @tab @code{subroutine acc_update_device(a, len)}
-@item @tab @code{type, dimension(:[,:]...) :: a}
-@item @tab @code{integer len}
-@item @emph{Interface}: @tab @code{subroutine acc_update_device_async(a, async)}
-@item @tab @code{type, dimension(:[,:]...) :: a}
-@item @tab @code{integer(acc_handle_kind) :: async}
-@item @emph{Interface}: @tab @code{subroutine acc_update_device_async(a, len, async)}
-@item @tab @code{type, dimension(:[,:]...) :: a}
-@item @tab @code{integer len}
-@item @tab @code{integer(acc_handle_kind) :: async}
-@end multitable
-
-@item @emph{Reference}:
-@uref{https://www.openacc.org, OpenACC specification v2.6}, section
-3.2.24.
-@end table
-
-
-
-@node acc_update_self
-@section @code{acc_update_self} -- Update host memory from mapped device memory.
-@table @asis
-@item @emph{Description}
-This function updates the host copy from the previously mapped device memory.
-The host memory is specified with the host address @var{a} and a length of
-@var{len} bytes.
-
-In Fortran, two (2) forms are supported. In the first form, @var{a} specifies
-a contiguous array section. The second form @var{a} specifies a variable or
-array element and @var{len} specifies the length in bytes.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{acc_update_self(h_void *a, size_t len);}
-@item @emph{Prototype}: @tab @code{acc_update_self_async(h_void *a, size_t len, int async);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{subroutine acc_update_self(a)}
-@item @tab @code{type, dimension(:[,:]...) :: a}
-@item @emph{Interface}: @tab @code{subroutine acc_update_self(a, len)}
-@item @tab @code{type, dimension(:[,:]...) :: a}
-@item @tab @code{integer len}
-@item @emph{Interface}: @tab @code{subroutine acc_update_self_async(a, async)}
-@item @tab @code{type, dimension(:[,:]...) :: a}
-@item @tab @code{integer(acc_handle_kind) :: async}
-@item @emph{Interface}: @tab @code{subroutine acc_update_self_async(a, len, async)}
-@item @tab @code{type, dimension(:[,:]...) :: a}
-@item @tab @code{integer len}
-@item @tab @code{integer(acc_handle_kind) :: async}
-@end multitable
-
-@item @emph{Reference}:
-@uref{https://www.openacc.org, OpenACC specification v2.6}, section
-3.2.25.
-@end table
-
-
-
-@node acc_map_data
-@section @code{acc_map_data} -- Map previously allocated device memory to host memory.
-@table @asis
-@item @emph{Description}
-This function maps previously allocated device and host memory. The device
-memory is specified with the device address @var{d}. The host memory is
-specified with the host address @var{h} and a length of @var{len}.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{acc_map_data(h_void *h, d_void *d, size_t len);}
-@end multitable
-
-@item @emph{Reference}:
-@uref{https://www.openacc.org, OpenACC specification v2.6}, section
-3.2.26.
-@end table
-
-
-
-@node acc_unmap_data
-@section @code{acc_unmap_data} -- Unmap device memory from host memory.
-@table @asis
-@item @emph{Description}
-This function unmaps previously mapped device and host memory. The latter
-specified by @var{h}.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{acc_unmap_data(h_void *h);}
-@end multitable
-
-@item @emph{Reference}:
-@uref{https://www.openacc.org, OpenACC specification v2.6}, section
-3.2.27.
-@end table
-
-
-
-@node acc_deviceptr
-@section @code{acc_deviceptr} -- Get device pointer associated with specific host address.
-@table @asis
-@item @emph{Description}
-This function returns the device address that has been mapped to the
-host address specified by @var{h}.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{void *acc_deviceptr(h_void *h);}
-@end multitable
-
-@item @emph{Reference}:
-@uref{https://www.openacc.org, OpenACC specification v2.6}, section
-3.2.28.
-@end table
-
-
-
-@node acc_hostptr
-@section @code{acc_hostptr} -- Get host pointer associated with specific device address.
-@table @asis
-@item @emph{Description}
-This function returns the host address that has been mapped to the
-device address specified by @var{d}.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{void *acc_hostptr(d_void *d);}
-@end multitable
-
-@item @emph{Reference}:
-@uref{https://www.openacc.org, OpenACC specification v2.6}, section
-3.2.29.
-@end table
-
-
-
-@node acc_is_present
-@section @code{acc_is_present} -- Indicate whether host variable / array is present on device.
-@table @asis
-@item @emph{Description}
-This function indicates whether the specified host address in @var{a} and a
-length of @var{len} bytes is present on the device. In C/C++, a non-zero
-value is returned to indicate the presence of the mapped memory on the
-device. A zero is returned to indicate the memory is not mapped on the
-device.
-
-In Fortran, two (2) forms are supported. In the first form, @var{a} specifies
-a contiguous array section. The second form @var{a} specifies a variable or
-array element and @var{len} specifies the length in bytes. If the host
-memory is mapped to device memory, then a @code{true} is returned. Otherwise,
-a @code{false} is return to indicate the mapped memory is not present.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{int acc_is_present(h_void *a, size_t len);}
-@end multitable
-
-@item @emph{Fortran}:
-@multitable @columnfractions .20 .80
-@item @emph{Interface}: @tab @code{function acc_is_present(a)}
-@item @tab @code{type, dimension(:[,:]...) :: a}
-@item @tab @code{logical acc_is_present}
-@item @emph{Interface}: @tab @code{function acc_is_present(a, len)}
-@item @tab @code{type, dimension(:[,:]...) :: a}
-@item @tab @code{integer len}
-@item @tab @code{logical acc_is_present}
-@end multitable
-
-@item @emph{Reference}:
-@uref{https://www.openacc.org, OpenACC specification v2.6}, section
-3.2.30.
-@end table
-
-
-
-@node acc_memcpy_to_device
-@section @code{acc_memcpy_to_device} -- Copy host memory to device memory.
-@table @asis
-@item @emph{Description}
-This function copies host memory specified by host address of @var{src} to
-device memory specified by the device address @var{dest} for a length of
-@var{bytes} bytes.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{acc_memcpy_to_device(d_void *dest, h_void *src, size_t bytes);}
-@end multitable
-
-@item @emph{Reference}:
-@uref{https://www.openacc.org, OpenACC specification v2.6}, section
-3.2.31.
-@end table
-
-
-
-@node acc_memcpy_from_device
-@section @code{acc_memcpy_from_device} -- Copy device memory to host memory.
-@table @asis
-@item @emph{Description}
-This function copies host memory specified by host address of @var{src} from
-device memory specified by the device address @var{dest} for a length of
-@var{bytes} bytes.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{acc_memcpy_from_device(d_void *dest, h_void *src, size_t bytes);}
-@end multitable
-
-@item @emph{Reference}:
-@uref{https://www.openacc.org, OpenACC specification v2.6}, section
-3.2.32.
-@end table
-
-
-
-@node acc_attach
-@section @code{acc_attach} -- Let device pointer point to device-pointer target.
-@table @asis
-@item @emph{Description}
-This function updates a pointer on the device from pointing to a host-pointer
-address to pointing to the corresponding device data.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{acc_attach(h_void **ptr);}
-@item @emph{Prototype}: @tab @code{acc_attach_async(h_void **ptr, int async);}
-@end multitable
-
-@item @emph{Reference}:
-@uref{https://www.openacc.org, OpenACC specification v2.6}, section
-3.2.34.
-@end table
-
-
-
-@node acc_detach
-@section @code{acc_detach} -- Let device pointer point to host-pointer target.
-@table @asis
-@item @emph{Description}
-This function updates a pointer on the device from pointing to a device-pointer
-address to pointing to the corresponding host data.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{acc_detach(h_void **ptr);}
-@item @emph{Prototype}: @tab @code{acc_detach_async(h_void **ptr, int async);}
-@item @emph{Prototype}: @tab @code{acc_detach_finalize(h_void **ptr);}
-@item @emph{Prototype}: @tab @code{acc_detach_finalize_async(h_void **ptr, int async);}
-@end multitable
-
-@item @emph{Reference}:
-@uref{https://www.openacc.org, OpenACC specification v2.6}, section
-3.2.35.
-@end table
-
-
-
-@node acc_get_current_cuda_device
-@section @code{acc_get_current_cuda_device} -- Get CUDA device handle.
-@table @asis
-@item @emph{Description}
-This function returns the CUDA device handle. This handle is the same
-as used by the CUDA Runtime or Driver API's.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{void *acc_get_current_cuda_device(void);}
-@end multitable
-
-@item @emph{Reference}:
-@uref{https://www.openacc.org, OpenACC specification v2.6}, section
-A.2.1.1.
-@end table
-
-
-
-@node acc_get_current_cuda_context
-@section @code{acc_get_current_cuda_context} -- Get CUDA context handle.
-@table @asis
-@item @emph{Description}
-This function returns the CUDA context handle. This handle is the same
-as used by the CUDA Runtime or Driver API's.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{void *acc_get_current_cuda_context(void);}
-@end multitable
-
-@item @emph{Reference}:
-@uref{https://www.openacc.org, OpenACC specification v2.6}, section
-A.2.1.2.
-@end table
-
-
-
-@node acc_get_cuda_stream
-@section @code{acc_get_cuda_stream} -- Get CUDA stream handle.
-@table @asis
-@item @emph{Description}
-This function returns the CUDA stream handle for the queue @var{async}.
-This handle is the same as used by the CUDA Runtime or Driver API's.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{void *acc_get_cuda_stream(int async);}
-@end multitable
-
-@item @emph{Reference}:
-@uref{https://www.openacc.org, OpenACC specification v2.6}, section
-A.2.1.3.
-@end table
-
-
-
-@node acc_set_cuda_stream
-@section @code{acc_set_cuda_stream} -- Set CUDA stream handle.
-@table @asis
-@item @emph{Description}
-This function associates the stream handle specified by @var{stream} with
-the queue @var{async}.
-
-This cannot be used to change the stream handle associated with
-@code{acc_async_sync}.
-
-The return value is not specified.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{int acc_set_cuda_stream(int async, void *stream);}
-@end multitable
-
-@item @emph{Reference}:
-@uref{https://www.openacc.org, OpenACC specification v2.6}, section
-A.2.1.4.
-@end table
-
-
-
-@node acc_prof_register
-@section @code{acc_prof_register} -- Register callbacks.
-@table @asis
-@item @emph{Description}:
-This function registers callbacks.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{void acc_prof_register (acc_event_t, acc_prof_callback, acc_register_t);}
-@end multitable
-
-@item @emph{See also}:
-@ref{OpenACC Profiling Interface}
-
-@item @emph{Reference}:
-@uref{https://www.openacc.org, OpenACC specification v2.6}, section
-5.3.
-@end table
-
-
-
-@node acc_prof_unregister
-@section @code{acc_prof_unregister} -- Unregister callbacks.
-@table @asis
-@item @emph{Description}:
-This function unregisters callbacks.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{void acc_prof_unregister (acc_event_t, acc_prof_callback, acc_register_t);}
-@end multitable
-
-@item @emph{See also}:
-@ref{OpenACC Profiling Interface}
-
-@item @emph{Reference}:
-@uref{https://www.openacc.org, OpenACC specification v2.6}, section
-5.3.
-@end table
-
-
-
-@node acc_prof_lookup
-@section @code{acc_prof_lookup} -- Obtain inquiry functions.
-@table @asis
-@item @emph{Description}:
-Function to obtain inquiry functions.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{acc_query_fn acc_prof_lookup (const char *);}
-@end multitable
-
-@item @emph{See also}:
-@ref{OpenACC Profiling Interface}
-
-@item @emph{Reference}:
-@uref{https://www.openacc.org, OpenACC specification v2.6}, section
-5.3.
-@end table
-
-
-
-@node acc_register_library
-@section @code{acc_register_library} -- Library registration.
-@table @asis
-@item @emph{Description}:
-Function for library registration.
-
-@item @emph{C/C++}:
-@multitable @columnfractions .20 .80
-@item @emph{Prototype}: @tab @code{void acc_register_library (acc_prof_reg, acc_prof_reg, acc_prof_lookup_func);}
-@end multitable
-
-@item @emph{See also}:
-@ref{OpenACC Profiling Interface}, @ref{ACC_PROFLIB}
-
-@item @emph{Reference}:
-@uref{https://www.openacc.org, OpenACC specification v2.6}, section
-5.3.
-@end table
-
-
-
-@c ---------------------------------------------------------------------
-@c OpenACC Environment Variables
-@c ---------------------------------------------------------------------
-
-@node OpenACC Environment Variables
-@chapter OpenACC Environment Variables
-
-The variables @env{ACC_DEVICE_TYPE} and @env{ACC_DEVICE_NUM}
-are defined by section 4 of the OpenACC specification in version 2.0.
-The variable @env{ACC_PROFLIB}
-is defined by section 4 of the OpenACC specification in version 2.6.
-The variable @env{GCC_ACC_NOTIFY} is used for diagnostic purposes.
-
-@menu
-* ACC_DEVICE_TYPE::
-* ACC_DEVICE_NUM::
-* ACC_PROFLIB::
-* GCC_ACC_NOTIFY::
-@end menu
-
-
-
-@node ACC_DEVICE_TYPE
-@section @code{ACC_DEVICE_TYPE}
-@table @asis
-@item @emph{Reference}:
-@uref{https://www.openacc.org, OpenACC specification v2.6}, section
-4.1.
-@end table
-
-
-
-@node ACC_DEVICE_NUM
-@section @code{ACC_DEVICE_NUM}
-@table @asis
-@item @emph{Reference}:
-@uref{https://www.openacc.org, OpenACC specification v2.6}, section
-4.2.
-@end table
-
-
-
-@node ACC_PROFLIB
-@section @code{ACC_PROFLIB}
-@table @asis
-@item @emph{See also}:
-@ref{acc_register_library}, @ref{OpenACC Profiling Interface}
-
-@item @emph{Reference}:
-@uref{https://www.openacc.org, OpenACC specification v2.6}, section
-4.3.
-@end table
-
-
-
-@node GCC_ACC_NOTIFY
-@section @code{GCC_ACC_NOTIFY}
-@table @asis
-@item @emph{Description}:
-Print debug information pertaining to the accelerator.
-@end table
-
-
-
-@c ---------------------------------------------------------------------
-@c CUDA Streams Usage
-@c ---------------------------------------------------------------------
-
-@node CUDA Streams Usage
-@chapter CUDA Streams Usage
-
-This applies to the @code{nvptx} plugin only.
-
-The library provides elements that perform asynchronous movement of
-data and asynchronous operation of computing constructs. This
-asynchronous functionality is implemented by making use of CUDA
-streams@footnote{See "Stream Management" in "CUDA Driver API",
-TRM-06703-001, Version 5.5, for additional information}.
-
-The primary means by that the asynchronous functionality is accessed
-is through the use of those OpenACC directives which make use of the
-@code{async} and @code{wait} clauses. When the @code{async} clause is
-first used with a directive, it creates a CUDA stream. If an
-@code{async-argument} is used with the @code{async} clause, then the
-stream is associated with the specified @code{async-argument}.
-
-Following the creation of an association between a CUDA stream and the
-@code{async-argument} of an @code{async} clause, both the @code{wait}
-clause and the @code{wait} directive can be used. When either the
-clause or directive is used after stream creation, it creates a
-rendezvous point whereby execution waits until all operations
-associated with the @code{async-argument}, that is, stream, have
-completed.
-
-Normally, the management of the streams that are created as a result of
-using the @code{async} clause, is done without any intervention by the
-caller. This implies the association between the @code{async-argument}
-and the CUDA stream will be maintained for the lifetime of the program.
-However, this association can be changed through the use of the library
-function @code{acc_set_cuda_stream}. When the function
-@code{acc_set_cuda_stream} is called, the CUDA stream that was
-originally associated with the @code{async} clause will be destroyed.
-Caution should be taken when changing the association as subsequent
-references to the @code{async-argument} refer to a different
-CUDA stream.
-
-
-
-@c ---------------------------------------------------------------------
-@c OpenACC Library Interoperability
-@c ---------------------------------------------------------------------
-
-@node OpenACC Library Interoperability
-@chapter OpenACC Library Interoperability
-
-@section Introduction
-
-The OpenACC library uses the CUDA Driver API, and may interact with
-programs that use the Runtime library directly, or another library
-based on the Runtime library, e.g., CUBLAS@footnote{See section 2.26,
-"Interactions with the CUDA Driver API" in
-"CUDA Runtime API", Version 5.5, and section 2.27, "VDPAU
-Interoperability", in "CUDA Driver API", TRM-06703-001, Version 5.5,
-for additional information on library interoperability.}.
-This chapter describes the use cases and what changes are
-required in order to use both the OpenACC library and the CUBLAS and Runtime
-libraries within a program.
-
-@section First invocation: NVIDIA CUBLAS library API
-
-In this first use case (see below), a function in the CUBLAS library is called
-prior to any of the functions in the OpenACC library. More specifically, the
-function @code{cublasCreate()}.
-
-When invoked, the function initializes the library and allocates the
-hardware resources on the host and the device on behalf of the caller. Once
-the initialization and allocation has completed, a handle is returned to the
-caller. The OpenACC library also requires initialization and allocation of
-hardware resources. Since the CUBLAS library has already allocated the
-hardware resources for the device, all that is left to do is to initialize
-the OpenACC library and acquire the hardware resources on the host.
-
-Prior to calling the OpenACC function that initializes the library and
-allocate the host hardware resources, you need to acquire the device number
-that was allocated during the call to @code{cublasCreate()}. The invoking of the
-runtime library function @code{cudaGetDevice()} accomplishes this. Once
-acquired, the device number is passed along with the device type as
-parameters to the OpenACC library function @code{acc_set_device_num()}.
-
-Once the call to @code{acc_set_device_num()} has completed, the OpenACC
-library uses the context that was created during the call to
-@code{cublasCreate()}. In other words, both libraries will be sharing the
-same context.
-
-@smallexample
- /* Create the handle */
- s = cublasCreate(&h);
- if (s != CUBLAS_STATUS_SUCCESS)
- @{
- fprintf(stderr, "cublasCreate failed %d\n", s);
- exit(EXIT_FAILURE);
- @}
-
- /* Get the device number */
- e = cudaGetDevice(&dev);
- if (e != cudaSuccess)
- @{
- fprintf(stderr, "cudaGetDevice failed %d\n", e);
- exit(EXIT_FAILURE);
- @}
-
- /* Initialize OpenACC library and use device 'dev' */
- acc_set_device_num(dev, acc_device_nvidia);
-
-@end smallexample
-@center Use Case 1
-
-@section First invocation: OpenACC library API
-
-In this second use case (see below), a function in the OpenACC library is
-called prior to any of the functions in the CUBLAS library. More specificially,
-the function @code{acc_set_device_num()}.
-
-In the use case presented here, the function @code{acc_set_device_num()}
-is used to both initialize the OpenACC library and allocate the hardware
-resources on the host and the device. In the call to the function, the
-call parameters specify which device to use and what device
-type to use, i.e., @code{acc_device_nvidia}. It should be noted that this
-is but one method to initialize the OpenACC library and allocate the
-appropriate hardware resources. Other methods are available through the
-use of environment variables and these will be discussed in the next section.
-
-Once the call to @code{acc_set_device_num()} has completed, other OpenACC
-functions can be called as seen with multiple calls being made to
-@code{acc_copyin()}. In addition, calls can be made to functions in the
-CUBLAS library. In the use case a call to @code{cublasCreate()} is made
-subsequent to the calls to @code{acc_copyin()}.
-As seen in the previous use case, a call to @code{cublasCreate()}
-initializes the CUBLAS library and allocates the hardware resources on the
-host and the device. However, since the device has already been allocated,
-@code{cublasCreate()} will only initialize the CUBLAS library and allocate
-the appropriate hardware resources on the host. The context that was created
-as part of the OpenACC initialization is shared with the CUBLAS library,
-similarly to the first use case.
-
-@smallexample
- dev = 0;
-
- acc_set_device_num(dev, acc_device_nvidia);
-
- /* Copy the first set to the device */
- d_X = acc_copyin(&h_X[0], N * sizeof (float));
- if (d_X == NULL)
- @{
- fprintf(stderr, "copyin error h_X\n");
- exit(EXIT_FAILURE);
- @}
-
- /* Copy the second set to the device */
- d_Y = acc_copyin(&h_Y1[0], N * sizeof (float));
- if (d_Y == NULL)
- @{
- fprintf(stderr, "copyin error h_Y1\n");
- exit(EXIT_FAILURE);
- @}
-
- /* Create the handle */
- s = cublasCreate(&h);
- if (s != CUBLAS_STATUS_SUCCESS)
- @{
- fprintf(stderr, "cublasCreate failed %d\n", s);
- exit(EXIT_FAILURE);
- @}
-
- /* Perform saxpy using CUBLAS library function */
- s = cublasSaxpy(h, N, &alpha, d_X, 1, d_Y, 1);
- if (s != CUBLAS_STATUS_SUCCESS)
- @{
- fprintf(stderr, "cublasSaxpy failed %d\n", s);
- exit(EXIT_FAILURE);
- @}
-
- /* Copy the results from the device */
- acc_memcpy_from_device(&h_Y1[0], d_Y, N * sizeof (float));
-
-@end smallexample
-@center Use Case 2
-
-@section OpenACC library and environment variables
-
-There are two environment variables associated with the OpenACC library
-that may be used to control the device type and device number:
-@env{ACC_DEVICE_TYPE} and @env{ACC_DEVICE_NUM}, respectively. These two
-environment variables can be used as an alternative to calling
-@code{acc_set_device_num()}. As seen in the second use case, the device
-type and device number were specified using @code{acc_set_device_num()}.
-If however, the aforementioned environment variables were set, then the
-call to @code{acc_set_device_num()} would not be required.
-
-
-The use of the environment variables is only relevant when an OpenACC function
-is called prior to a call to @code{cudaCreate()}. If @code{cudaCreate()}
-is called prior to a call to an OpenACC function, then you must call
-@code{acc_set_device_num()}@footnote{More complete information
-about @env{ACC_DEVICE_TYPE} and @env{ACC_DEVICE_NUM} can be found in
-sections 4.1 and 4.2 of the @uref{https://www.openacc.org, OpenACC}
-Application Programming Interface”, Version 2.6.}
-
-
-
-@c ---------------------------------------------------------------------
-@c OpenACC Profiling Interface
-@c ---------------------------------------------------------------------
-
-@node OpenACC Profiling Interface
-@chapter OpenACC Profiling Interface
-
-@section Implementation Status and Implementation-Defined Behavior
-
-We're implementing the OpenACC Profiling Interface as defined by the
-OpenACC 2.6 specification. We're clarifying some aspects here as
-@emph{implementation-defined behavior}, while they're still under
-discussion within the OpenACC Technical Committee.
-
-This implementation is tuned to keep the performance impact as low as
-possible for the (very common) case that the Profiling Interface is
-not enabled. This is relevant, as the Profiling Interface affects all
-the @emph{hot} code paths (in the target code, not in the offloaded
-code). Users of the OpenACC Profiling Interface can be expected to
-understand that performance will be impacted to some degree once the
-Profiling Interface has gotten enabled: for example, because of the
-@emph{runtime} (libgomp) calling into a third-party @emph{library} for
-every event that has been registered.
-
-We're not yet accounting for the fact that @cite{OpenACC events may
-occur during event processing}.
-We just handle one case specially, as required by CUDA 9.0
-@command{nvprof}, that @code{acc_get_device_type}
-(@ref{acc_get_device_type})) may be called from
-@code{acc_ev_device_init_start}, @code{acc_ev_device_init_end}
-callbacks.
-
-We're not yet implementing initialization via a
-@code{acc_register_library} function that is either statically linked
-in, or dynamically via @env{LD_PRELOAD}.
-Initialization via @code{acc_register_library} functions dynamically
-loaded via the @env{ACC_PROFLIB} environment variable does work, as
-does directly calling @code{acc_prof_register},
-@code{acc_prof_unregister}, @code{acc_prof_lookup}.
-
-As currently there are no inquiry functions defined, calls to
-@code{acc_prof_lookup} will always return @code{NULL}.
-
-There aren't separate @emph{start}, @emph{stop} events defined for the
-event types @code{acc_ev_create}, @code{acc_ev_delete},
-@code{acc_ev_alloc}, @code{acc_ev_free}. It's not clear if these
-should be triggered before or after the actual device-specific call is
-made. We trigger them after.
-
-Remarks about data provided to callbacks:
-
-@table @asis
-
-@item @code{acc_prof_info.event_type}
-It's not clear if for @emph{nested} event callbacks (for example,
-@code{acc_ev_enqueue_launch_start} as part of a parent compute
-construct), this should be set for the nested event
-(@code{acc_ev_enqueue_launch_start}), or if the value of the parent
-construct should remain (@code{acc_ev_compute_construct_start}). In
-this implementation, the value will generally correspond to the
-innermost nested event type.
-
-@item @code{acc_prof_info.device_type}
-@itemize
-
-@item
-For @code{acc_ev_compute_construct_start}, and in presence of an
-@code{if} clause with @emph{false} argument, this will still refer to
-the offloading device type.
-It's not clear if that's the expected behavior.
-
-@item
-Complementary to the item before, for
-@code{acc_ev_compute_construct_end}, this is set to
-@code{acc_device_host} in presence of an @code{if} clause with
-@emph{false} argument.
-It's not clear if that's the expected behavior.
-
-@end itemize
-
-@item @code{acc_prof_info.thread_id}
-Always @code{-1}; not yet implemented.
-
-@item @code{acc_prof_info.async}
-@itemize
-
-@item
-Not yet implemented correctly for
-@code{acc_ev_compute_construct_start}.
-
-@item
-In a compute construct, for host-fallback
-execution/@code{acc_device_host} it will always be
-@code{acc_async_sync}.
-It's not clear if that's the expected behavior.
-
-@item
-For @code{acc_ev_device_init_start} and @code{acc_ev_device_init_end},
-it will always be @code{acc_async_sync}.
-It's not clear if that's the expected behavior.
-
-@end itemize
-
-@item @code{acc_prof_info.async_queue}
-There is no @cite{limited number of asynchronous queues} in libgomp.
-This will always have the same value as @code{acc_prof_info.async}.
-
-@item @code{acc_prof_info.src_file}
-Always @code{NULL}; not yet implemented.
-
-@item @code{acc_prof_info.func_name}
-Always @code{NULL}; not yet implemented.
-
-@item @code{acc_prof_info.line_no}
-Always @code{-1}; not yet implemented.
-
-@item @code{acc_prof_info.end_line_no}
-Always @code{-1}; not yet implemented.
-
-@item @code{acc_prof_info.func_line_no}
-Always @code{-1}; not yet implemented.
-
-@item @code{acc_prof_info.func_end_line_no}
-Always @code{-1}; not yet implemented.
-
-@item @code{acc_event_info.event_type}, @code{acc_event_info.*.event_type}
-Relating to @code{acc_prof_info.event_type} discussed above, in this
-implementation, this will always be the same value as
-@code{acc_prof_info.event_type}.
-
-@item @code{acc_event_info.*.parent_construct}
-@itemize
-
-@item
-Will be @code{acc_construct_parallel} for all OpenACC compute
-constructs as well as many OpenACC Runtime API calls; should be the
-one matching the actual construct, or
-@code{acc_construct_runtime_api}, respectively.
-
-@item
-Will be @code{acc_construct_enter_data} or
-@code{acc_construct_exit_data} when processing variable mappings
-specified in OpenACC @emph{declare} directives; should be
-@code{acc_construct_declare}.
-
-@item
-For implicit @code{acc_ev_device_init_start},
-@code{acc_ev_device_init_end}, and explicit as well as implicit
-@code{acc_ev_alloc}, @code{acc_ev_free},
-@code{acc_ev_enqueue_upload_start}, @code{acc_ev_enqueue_upload_end},
-@code{acc_ev_enqueue_download_start}, and
-@code{acc_ev_enqueue_download_end}, will be
-@code{acc_construct_parallel}; should reflect the real parent
-construct.
-
-@end itemize
-
-@item @code{acc_event_info.*.implicit}
-For @code{acc_ev_alloc}, @code{acc_ev_free},
-@code{acc_ev_enqueue_upload_start}, @code{acc_ev_enqueue_upload_end},
-@code{acc_ev_enqueue_download_start}, and
-@code{acc_ev_enqueue_download_end}, this currently will be @code{1}
-also for explicit usage.
-
-@item @code{acc_event_info.data_event.var_name}
-Always @code{NULL}; not yet implemented.
-
-@item @code{acc_event_info.data_event.host_ptr}
-For @code{acc_ev_alloc}, and @code{acc_ev_free}, this is always
-@code{NULL}.
-
-@item @code{typedef union acc_api_info}
-@dots{} as printed in @cite{5.2.3. Third Argument: API-Specific
-Information}. This should obviously be @code{typedef @emph{struct}
-acc_api_info}.
-
-@item @code{acc_api_info.device_api}
-Possibly not yet implemented correctly for
-@code{acc_ev_compute_construct_start},
-@code{acc_ev_device_init_start}, @code{acc_ev_device_init_end}:
-will always be @code{acc_device_api_none} for these event types.
-For @code{acc_ev_enter_data_start}, it will be
-@code{acc_device_api_none} in some cases.
-
-@item @code{acc_api_info.device_type}
-Always the same as @code{acc_prof_info.device_type}.
-
-@item @code{acc_api_info.vendor}
-Always @code{-1}; not yet implemented.
-
-@item @code{acc_api_info.device_handle}
-Always @code{NULL}; not yet implemented.
-
-@item @code{acc_api_info.context_handle}
-Always @code{NULL}; not yet implemented.
-
-@item @code{acc_api_info.async_handle}
-Always @code{NULL}; not yet implemented.
-
-@end table
-
-Remarks about certain event types:
-
-@table @asis
-
-@item @code{acc_ev_device_init_start}, @code{acc_ev_device_init_end}
-@itemize
-
-@item
-@c See 'DEVICE_INIT_INSIDE_COMPUTE_CONSTRUCT' in
-@c 'libgomp.oacc-c-c++-common/acc_prof-kernels-1.c',
-@c 'libgomp.oacc-c-c++-common/acc_prof-parallel-1.c'.
-When a compute construct triggers implicit
-@code{acc_ev_device_init_start} and @code{acc_ev_device_init_end}
-events, they currently aren't @emph{nested within} the corresponding
-@code{acc_ev_compute_construct_start} and
-@code{acc_ev_compute_construct_end}, but they're currently observed
-@emph{before} @code{acc_ev_compute_construct_start}.
-It's not clear what to do: the standard asks us provide a lot of
-details to the @code{acc_ev_compute_construct_start} callback, without
-(implicitly) initializing a device before?
-
-@item
-Callbacks for these event types will not be invoked for calls to the
-@code{acc_set_device_type} and @code{acc_set_device_num} functions.
-It's not clear if they should be.
-
-@end itemize
-
-@item @code{acc_ev_enter_data_start}, @code{acc_ev_enter_data_end}, @code{acc_ev_exit_data_start}, @code{acc_ev_exit_data_end}
-@itemize
-
-@item
-Callbacks for these event types will also be invoked for OpenACC
-@emph{host_data} constructs.
-It's not clear if they should be.
-
-@item
-Callbacks for these event types will also be invoked when processing
-variable mappings specified in OpenACC @emph{declare} directives.
-It's not clear if they should be.
-
-@end itemize
-
-@end table
-
-Callbacks for the following event types will be invoked, but dispatch
-and information provided therein has not yet been thoroughly reviewed:
-
-@itemize
-@item @code{acc_ev_alloc}
-@item @code{acc_ev_free}
-@item @code{acc_ev_update_start}, @code{acc_ev_update_end}
-@item @code{acc_ev_enqueue_upload_start}, @code{acc_ev_enqueue_upload_end}
-@item @code{acc_ev_enqueue_download_start}, @code{acc_ev_enqueue_download_end}
-@end itemize
-
-During device initialization, and finalization, respectively,
-callbacks for the following event types will not yet be invoked:
-
-@itemize
-@item @code{acc_ev_alloc}
-@item @code{acc_ev_free}
-@end itemize
-
-Callbacks for the following event types have not yet been implemented,
-so currently won't be invoked:
-
-@itemize
-@item @code{acc_ev_device_shutdown_start}, @code{acc_ev_device_shutdown_end}
-@item @code{acc_ev_runtime_shutdown}
-@item @code{acc_ev_create}, @code{acc_ev_delete}
-@item @code{acc_ev_wait_start}, @code{acc_ev_wait_end}
-@end itemize
-
-For the following runtime library functions, not all expected
-callbacks will be invoked (mostly concerning implicit device
-initialization):
-
-@itemize
-@item @code{acc_get_num_devices}
-@item @code{acc_set_device_type}
-@item @code{acc_get_device_type}
-@item @code{acc_set_device_num}
-@item @code{acc_get_device_num}
-@item @code{acc_init}
-@item @code{acc_shutdown}
-@end itemize
-
-Aside from implicit device initialization, for the following runtime
-library functions, no callbacks will be invoked for shared-memory
-offloading devices (it's not clear if they should be):
-
-@itemize
-@item @code{acc_malloc}
-@item @code{acc_free}
-@item @code{acc_copyin}, @code{acc_present_or_copyin}, @code{acc_copyin_async}
-@item @code{acc_create}, @code{acc_present_or_create}, @code{acc_create_async}
-@item @code{acc_copyout}, @code{acc_copyout_async}, @code{acc_copyout_finalize}, @code{acc_copyout_finalize_async}
-@item @code{acc_delete}, @code{acc_delete_async}, @code{acc_delete_finalize}, @code{acc_delete_finalize_async}
-@item @code{acc_update_device}, @code{acc_update_device_async}
-@item @code{acc_update_self}, @code{acc_update_self_async}
-@item @code{acc_map_data}, @code{acc_unmap_data}
-@item @code{acc_memcpy_to_device}, @code{acc_memcpy_to_device_async}
-@item @code{acc_memcpy_from_device}, @code{acc_memcpy_from_device_async}
-@end itemize
-
-@c ---------------------------------------------------------------------
-@c OpenMP-Implementation Specifics
-@c ---------------------------------------------------------------------
-
-@node OpenMP-Implementation Specifics
-@chapter OpenMP-Implementation Specifics
-
-@menu
-* OpenMP Context Selectors::
-* Memory allocation with libmemkind::
-@end menu
-
-@node OpenMP Context Selectors
-@section OpenMP Context Selectors
-
-@code{vendor} is always @code{gnu}. References are to the GCC manual.
-
-@multitable @columnfractions .60 .10 .25
-@headitem @code{arch} @tab @code{kind} @tab @code{isa}
-@item @code{x86}, @code{x86_64}, @code{i386}, @code{i486},
- @code{i586}, @code{i686}, @code{ia32}
- @tab @code{host}
- @tab See @code{-m...} flags in ``x86 Options'' (without @code{-m})
-@item @code{amdgcn}, @code{gcn}
- @tab @code{gpu}
- @tab See @code{-march=} in ``AMD GCN Options''
-@item @code{nvptx}
- @tab @code{gpu}
- @tab See @code{-march=} in ``Nvidia PTX Options''
-@end multitable
-
-@node Memory allocation with libmemkind
-@section Memory allocation with libmemkind
-
-On Linux systems, where the @uref{https://github.com/memkind/memkind, memkind
-library} (@code{libmemkind.so.0}) is available at runtime, it is used when
-creating memory allocators requesting
-
-@itemize
-@item the memory space @code{omp_high_bw_mem_space}
-@item the memory space @code{omp_large_cap_mem_space}
-@item the partition trait @code{omp_atv_interleaved}
-@end itemize
-
-
-@c ---------------------------------------------------------------------
-@c Offload-Target Specifics
-@c ---------------------------------------------------------------------
-
-@node Offload-Target Specifics
-@chapter Offload-Target Specifics
-
-The following sections present notes on the offload-target specifics
-
-@menu
-* AMD Radeon::
-* nvptx::
-@end menu
-
-@node AMD Radeon
-@section AMD Radeon (GCN)
-
-On the hardware side, there is the hierarchy (fine to coarse):
-@itemize
-@item work item (thread)
-@item wavefront
-@item work group
-@item compute unite (CU)
-@end itemize
-
-All OpenMP and OpenACC levels are used, i.e.
-@itemize
-@item OpenMP's simd and OpenACC's vector map to work items (thread)
-@item OpenMP's threads (``parallel'') and OpenACC's workers map
- to wavefronts
-@item OpenMP's teams and OpenACC's gang use a threadpool with the
- size of the number of teams or gangs, respectively.
-@end itemize
-
-The used sizes are
-@itemize
-@item Number of teams is the specified @code{num_teams} (OpenMP) or
- @code{num_gangs} (OpenACC) or otherwise the number of CU
-@item Number of wavefronts is 4 for gfx900 and 16 otherwise;
- @code{num_threads} (OpenMP) and @code{num_workers} (OpenACC)
- overrides this if smaller.
-@item The wavefront has 102 scalars and 64 vectors
-@item Number of workitems is always 64
-@item The hardware permits maximally 40 workgroups/CU and
- 16 wavefronts/workgroup up to a limit of 40 wavefronts in total per CU.
-@item 80 scalars registers and 24 vector registers in non-kernel functions
- (the chosen procedure-calling API).
-@item For the kernel itself: as many as register pressure demands (number of
- teams and number of threads, scaled down if registers are exhausted)
-@end itemize
-
-The implementation remark:
-@itemize
-@item I/O within OpenMP target regions and OpenACC parallel/kernels is supported
- using the C library @code{printf} functions and the Fortran
- @code{print}/@code{write} statements.
-@end itemize
-
-
-
-@node nvptx
-@section nvptx
-
-On the hardware side, there is the hierarchy (fine to coarse):
-@itemize
-@item thread
-@item warp
-@item thread block
-@item streaming multiprocessor
-@end itemize
-
-All OpenMP and OpenACC levels are used, i.e.
-@itemize
-@item OpenMP's simd and OpenACC's vector map to threads
-@item OpenMP's threads (``parallel'') and OpenACC's workers map to warps
-@item OpenMP's teams and OpenACC's gang use a threadpool with the
- size of the number of teams or gangs, respectively.
-@end itemize
-
-The used sizes are
-@itemize
-@item The @code{warp_size} is always 32
-@item CUDA kernel launched: @code{dim=@{#teams,1,1@}, blocks=@{#threads,warp_size,1@}}.
-@end itemize
-
-Additional information can be obtained by setting the environment variable to
-@code{GOMP_DEBUG=1} (very verbose; grep for @code{kernel.*launch} for launch
-parameters).
-
-GCC generates generic PTX ISA code, which is just-in-time compiled by CUDA,
-which caches the JIT in the user's directory (see CUDA documentation; can be
-tuned by the environment variables @code{CUDA_CACHE_@{DISABLE,MAXSIZE,PATH@}}.
-
-Note: While PTX ISA is generic, the @code{-mptx=} and @code{-march=} commandline
-options still affect the used PTX ISA code and, thus, the requirments on
-CUDA version and hardware.
-
-The implementation remark:
-@itemize
-@item I/O within OpenMP target regions and OpenACC parallel/kernels is supported
- using the C library @code{printf} functions. Note that the Fortran
- @code{print}/@code{write} statements are not supported, yet.
-@item Compilation OpenMP code that contains @code{requires reverse_offload}
- requires at least @code{-march=sm_35}, compiling for @code{-march=sm_30}
- is not supported.
-@end itemize
-
-
-@c ---------------------------------------------------------------------
-@c The libgomp ABI
-@c ---------------------------------------------------------------------
-
-@node The libgomp ABI
-@chapter The libgomp ABI
-
-The following sections present notes on the external ABI as
-presented by libgomp. Only maintainers should need them.
-
-@menu
-* Implementing MASTER construct::
-* Implementing CRITICAL construct::
-* Implementing ATOMIC construct::
-* Implementing FLUSH construct::
-* Implementing BARRIER construct::
-* Implementing THREADPRIVATE construct::
-* Implementing PRIVATE clause::
-* Implementing FIRSTPRIVATE LASTPRIVATE COPYIN and COPYPRIVATE clauses::
-* Implementing REDUCTION clause::
-* Implementing PARALLEL construct::
-* Implementing FOR construct::
-* Implementing ORDERED construct::
-* Implementing SECTIONS construct::
-* Implementing SINGLE construct::
-* Implementing OpenACC's PARALLEL construct::
-@end menu
-
-
-@node Implementing MASTER construct
-@section Implementing MASTER construct
-
-@smallexample
-if (omp_get_thread_num () == 0)
- block
-@end smallexample
-
-Alternately, we generate two copies of the parallel subfunction
-and only include this in the version run by the primary thread.
-Surely this is not worthwhile though...
-
-
-
-@node Implementing CRITICAL construct
-@section Implementing CRITICAL construct
-
-Without a specified name,
-
-@smallexample
- void GOMP_critical_start (void);
- void GOMP_critical_end (void);
-@end smallexample
-
-so that we don't get COPY relocations from libgomp to the main
-application.
-
-With a specified name, use omp_set_lock and omp_unset_lock with
-name being transformed into a variable declared like
-
-@smallexample
- omp_lock_t gomp_critical_user_<name> __attribute__((common))
-@end smallexample
-
-Ideally the ABI would specify that all zero is a valid unlocked
-state, and so we wouldn't need to initialize this at
-startup.
-
-
-
-@node Implementing ATOMIC construct
-@section Implementing ATOMIC construct
-
-The target should implement the @code{__sync} builtins.
-
-Failing that we could add
-
-@smallexample
- void GOMP_atomic_enter (void)
- void GOMP_atomic_exit (void)
-@end smallexample
-
-which reuses the regular lock code, but with yet another lock
-object private to the library.
-
-
-
-@node Implementing FLUSH construct
-@section Implementing FLUSH construct
-
-Expands to the @code{__sync_synchronize} builtin.
-
-
-
-@node Implementing BARRIER construct
-@section Implementing BARRIER construct
-
-@smallexample
- void GOMP_barrier (void)
-@end smallexample
-
-
-@node Implementing THREADPRIVATE construct
-@section Implementing THREADPRIVATE construct
-
-In _most_ cases we can map this directly to @code{__thread}. Except
-that OMP allows constructors for C++ objects. We can either
-refuse to support this (how often is it used?) or we can
-implement something akin to .ctors.
-
-Even more ideally, this ctor feature is handled by extensions
-to the main pthreads library. Failing that, we can have a set
-of entry points to register ctor functions to be called.
-
-
-
-@node Implementing PRIVATE clause
-@section Implementing PRIVATE clause
-
-In association with a PARALLEL, or within the lexical extent
-of a PARALLEL block, the variable becomes a local variable in
-the parallel subfunction.
-
-In association with FOR or SECTIONS blocks, create a new
-automatic variable within the current function. This preserves
-the semantic of new variable creation.
-
-
-
-@node Implementing FIRSTPRIVATE LASTPRIVATE COPYIN and COPYPRIVATE clauses
-@section Implementing FIRSTPRIVATE LASTPRIVATE COPYIN and COPYPRIVATE clauses
-
-This seems simple enough for PARALLEL blocks. Create a private
-struct for communicating between the parent and subfunction.
-In the parent, copy in values for scalar and "small" structs;
-copy in addresses for others TREE_ADDRESSABLE types. In the
-subfunction, copy the value into the local variable.
-
-It is not clear what to do with bare FOR or SECTION blocks.
-The only thing I can figure is that we do something like:
-
-@smallexample
-#pragma omp for firstprivate(x) lastprivate(y)
-for (int i = 0; i < n; ++i)
- body;
-@end smallexample
-
-which becomes
-
-@smallexample
-@{
- int x = x, y;
-
- // for stuff
-
- if (i == n)
- y = y;
-@}
-@end smallexample
-
-where the "x=x" and "y=y" assignments actually have different
-uids for the two variables, i.e. not something you could write
-directly in C. Presumably this only makes sense if the "outer"
-x and y are global variables.
-
-COPYPRIVATE would work the same way, except the structure
-broadcast would have to happen via SINGLE machinery instead.
-
-
-
-@node Implementing REDUCTION clause
-@section Implementing REDUCTION clause
-
-The private struct mentioned in the previous section should have
-a pointer to an array of the type of the variable, indexed by the
-thread's @var{team_id}. The thread stores its final value into the
-array, and after the barrier, the primary thread iterates over the
-array to collect the values.
-
-
-@node Implementing PARALLEL construct
-@section Implementing PARALLEL construct
-
-@smallexample
- #pragma omp parallel
- @{
- body;
- @}
-@end smallexample
-
-becomes
-
-@smallexample
- void subfunction (void *data)
- @{
- use data;
- body;
- @}
-
- setup data;
- GOMP_parallel_start (subfunction, &data, num_threads);
- subfunction (&data);
- GOMP_parallel_end ();
-@end smallexample
-
-@smallexample
- void GOMP_parallel_start (void (*fn)(void *), void *data, unsigned num_threads)
-@end smallexample
-
-The @var{FN} argument is the subfunction to be run in parallel.
-
-The @var{DATA} argument is a pointer to a structure used to
-communicate data in and out of the subfunction, as discussed
-above with respect to FIRSTPRIVATE et al.
-
-The @var{NUM_THREADS} argument is 1 if an IF clause is present
-and false, or the value of the NUM_THREADS clause, if
-present, or 0.
-
-The function needs to create the appropriate number of
-threads and/or launch them from the dock. It needs to
-create the team structure and assign team ids.
-
-@smallexample
- void GOMP_parallel_end (void)
-@end smallexample
-
-Tears down the team and returns us to the previous @code{omp_in_parallel()} state.
-
-
-
-@node Implementing FOR construct
-@section Implementing FOR construct
-
-@smallexample
- #pragma omp parallel for
- for (i = lb; i <= ub; i++)
- body;
-@end smallexample
-
-becomes
-
-@smallexample
- void subfunction (void *data)
- @{
- long _s0, _e0;
- while (GOMP_loop_static_next (&_s0, &_e0))
- @{
- long _e1 = _e0, i;
- for (i = _s0; i < _e1; i++)
- body;
- @}
- GOMP_loop_end_nowait ();
- @}
-
- GOMP_parallel_loop_static (subfunction, NULL, 0, lb, ub+1, 1, 0);
- subfunction (NULL);
- GOMP_parallel_end ();
-@end smallexample
-
-@smallexample
- #pragma omp for schedule(runtime)
- for (i = 0; i < n; i++)
- body;
-@end smallexample
-
-becomes
-
-@smallexample
- @{
- long i, _s0, _e0;
- if (GOMP_loop_runtime_start (0, n, 1, &_s0, &_e0))
- do @{
- long _e1 = _e0;
- for (i = _s0, i < _e0; i++)
- body;
- @} while (GOMP_loop_runtime_next (&_s0, _&e0));
- GOMP_loop_end ();
- @}
-@end smallexample
-
-Note that while it looks like there is trickiness to propagating
-a non-constant STEP, there isn't really. We're explicitly allowed
-to evaluate it as many times as we want, and any variables involved
-should automatically be handled as PRIVATE or SHARED like any other
-variables. So the expression should remain evaluable in the
-subfunction. We can also pull it into a local variable if we like,
-but since its supposed to remain unchanged, we can also not if we like.
-
-If we have SCHEDULE(STATIC), and no ORDERED, then we ought to be
-able to get away with no work-sharing context at all, since we can
-simply perform the arithmetic directly in each thread to divide up
-the iterations. Which would mean that we wouldn't need to call any
-of these routines.
-
-There are separate routines for handling loops with an ORDERED
-clause. Bookkeeping for that is non-trivial...
-
-
-
-@node Implementing ORDERED construct
-@section Implementing ORDERED construct
-
-@smallexample
- void GOMP_ordered_start (void)
- void GOMP_ordered_end (void)
-@end smallexample
-
-
-
-@node Implementing SECTIONS construct
-@section Implementing SECTIONS construct
-
-A block as
-
-@smallexample
- #pragma omp sections
- @{
- #pragma omp section
- stmt1;
- #pragma omp section
- stmt2;
- #pragma omp section
- stmt3;
- @}
-@end smallexample
-
-becomes
-
-@smallexample
- for (i = GOMP_sections_start (3); i != 0; i = GOMP_sections_next ())
- switch (i)
- @{
- case 1:
- stmt1;
- break;
- case 2:
- stmt2;
- break;
- case 3:
- stmt3;
- break;
- @}
- GOMP_barrier ();
-@end smallexample
-
-
-@node Implementing SINGLE construct
-@section Implementing SINGLE construct
-
-A block like
-
-@smallexample
- #pragma omp single
- @{
- body;
- @}
-@end smallexample
-
-becomes
-
-@smallexample
- if (GOMP_single_start ())
- body;
- GOMP_barrier ();
-@end smallexample
-
-while
-
-@smallexample
- #pragma omp single copyprivate(x)
- body;
-@end smallexample
-
-becomes
-
-@smallexample
- datap = GOMP_single_copy_start ();
- if (datap == NULL)
- @{
- body;
- data.x = x;
- GOMP_single_copy_end (&data);
- @}
- else
- x = datap->x;
- GOMP_barrier ();
-@end smallexample
-
-
-
-@node Implementing OpenACC's PARALLEL construct
-@section Implementing OpenACC's PARALLEL construct
-
-@smallexample
- void GOACC_parallel ()
-@end smallexample
-
-
-
-@c ---------------------------------------------------------------------
-@c Reporting Bugs
-@c ---------------------------------------------------------------------
-
-@node Reporting Bugs
-@chapter Reporting Bugs
-
-Bugs in the GNU Offloading and Multi Processing Runtime Library should
-be reported via @uref{https://gcc.gnu.org/bugzilla/, Bugzilla}. Please add
-"openacc", or "openmp", or both to the keywords field in the bug
-report, as appropriate.
-
-
-
-@c ---------------------------------------------------------------------
-@c GNU General Public License
-@c ---------------------------------------------------------------------
-
-@include gpl_v3.texi
-
-
-
-@c ---------------------------------------------------------------------
-@c GNU Free Documentation License
-@c ---------------------------------------------------------------------
-
-@include fdl.texi
-
-
-
-@c ---------------------------------------------------------------------
-@c Funding Free Software
-@c ---------------------------------------------------------------------
-
-@include funding.texi
-
-@c ---------------------------------------------------------------------
-@c Index
-@c ---------------------------------------------------------------------
-
-@node Library Index
-@unnumbered Library Index
-
-@printindex cp
-
-@bye
+++ /dev/null
-@c This file is designed to be included in manuals that use
-@c expandargv.
-
-@item @@@var{file}
-Read command-line options from @var{file}. The options read are
-inserted in place of the original @@@var{file} option. If @var{file}
-does not exist, or cannot be read, then the option will be treated
-literally, and not removed.
-
-Options in @var{file} are separated by whitespace. A whitespace
-character may be included in an option by surrounding the entire
-option in either single or double quotes. Any character (including a
-backslash) may be included by prefixing the character to be included
-with a backslash. The @var{file} may itself contain additional
-@@@var{file} options; any such options will be processed recursively.
+++ /dev/null
-@node Library Copying
-@appendixsec GNU LESSER GENERAL PUBLIC LICENSE
-
-@cindex LGPL, Lesser General Public License
-@center Version 2.1, February 1999
-
-@display
-Copyright @copyright{} 1991-2022 Free Software Foundation, Inc.
-51 Franklin Street - Fifth Floor, Boston, MA 02110-1301, USA
-
-Everyone is permitted to copy and distribute verbatim copies
-of this license document, but changing it is not allowed.
-
-[This is the first released version of the Lesser GPL. It also counts
-as the successor of the GNU Library Public License, version 2, hence the
-version number 2.1.]
-@end display
-
-@appendixsubsec Preamble
-
- The licenses for most software are designed to take away your
-freedom to share and change it. By contrast, the GNU General Public
-Licenses are intended to guarantee your freedom to share and change
-free software---to make sure the software is free for all its users.
-
- This license, the Lesser General Public License, applies to some
-specially designated software---typically libraries---of the Free
-Software Foundation and other authors who decide to use it. You can use
-it too, but we suggest you first think carefully about whether this
-license or the ordinary General Public License is the better strategy to
-use in any particular case, based on the explanations below.
-
- When we speak of free software, we are referring to freedom of use,
-not price. Our General Public Licenses are designed to make sure that
-you have the freedom to distribute copies of free software (and charge
-for this service if you wish); that you receive source code or can get
-it if you want it; that you can change the software and use pieces of it
-in new free programs; and that you are informed that you can do these
-things.
-
- To protect your rights, we need to make restrictions that forbid
-distributors to deny you these rights or to ask you to surrender these
-rights. These restrictions translate to certain responsibilities for
-you if you distribute copies of the library or if you modify it.
-
- For example, if you distribute copies of the library, whether gratis
-or for a fee, you must give the recipients all the rights that we gave
-you. You must make sure that they, too, receive or can get the source
-code. If you link other code with the library, you must provide
-complete object files to the recipients, so that they can relink them
-with the library after making changes to the library and recompiling
-it. And you must show them these terms so they know their rights.
-
- We protect your rights with a two-step method: (1) we copyright the
-library, and (2) we offer you this license, which gives you legal
-permission to copy, distribute and/or modify the library.
-
- To protect each distributor, we want to make it very clear that
-there is no warranty for the free library. Also, if the library is
-modified by someone else and passed on, the recipients should know
-that what they have is not the original version, so that the original
-author's reputation will not be affected by problems that might be
-introduced by others.
-
- Finally, software patents pose a constant threat to the existence of
-any free program. We wish to make sure that a company cannot
-effectively restrict the users of a free program by obtaining a
-restrictive license from a patent holder. Therefore, we insist that
-any patent license obtained for a version of the library must be
-consistent with the full freedom of use specified in this license.
-
- Most GNU software, including some libraries, is covered by the
-ordinary GNU General Public License. This license, the GNU Lesser
-General Public License, applies to certain designated libraries, and
-is quite different from the ordinary General Public License. We use
-this license for certain libraries in order to permit linking those
-libraries into non-free programs.
-
- When a program is linked with a library, whether statically or using
-a shared library, the combination of the two is legally speaking a
-combined work, a derivative of the original library. The ordinary
-General Public License therefore permits such linking only if the
-entire combination fits its criteria of freedom. The Lesser General
-Public License permits more lax criteria for linking other code with
-the library.
-
- We call this license the @dfn{Lesser} General Public License because it
-does @emph{Less} to protect the user's freedom than the ordinary General
-Public License. It also provides other free software developers Less
-of an advantage over competing non-free programs. These disadvantages
-are the reason we use the ordinary General Public License for many
-libraries. However, the Lesser license provides advantages in certain
-special circumstances.
-
- For example, on rare occasions, there may be a special need to
-encourage the widest possible use of a certain library, so that it becomes
-a de-facto standard. To achieve this, non-free programs must be
-allowed to use the library. A more frequent case is that a free
-library does the same job as widely used non-free libraries. In this
-case, there is little to gain by limiting the free library to free
-software only, so we use the Lesser General Public License.
-
- In other cases, permission to use a particular library in non-free
-programs enables a greater number of people to use a large body of
-free software. For example, permission to use the GNU C Library in
-non-free programs enables many more people to use the whole GNU
-operating system, as well as its variant, the GNU/Linux operating
-system.
-
- Although the Lesser General Public License is Less protective of the
-users' freedom, it does ensure that the user of a program that is
-linked with the Library has the freedom and the wherewithal to run
-that program using a modified version of the Library.
-
- The precise terms and conditions for copying, distribution and
-modification follow. Pay close attention to the difference between a
-``work based on the library'' and a ``work that uses the library''. The
-former contains code derived from the library, whereas the latter must
-be combined with the library in order to run.
-
-@iftex
-@appendixsubsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
-@end iftex
-@ifinfo
-@center GNU LESSER GENERAL PUBLIC LICENSE
-@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
-@end ifinfo
-
-@enumerate 0
-@item
-This License Agreement applies to any software library or other program
-which contains a notice placed by the copyright holder or other
-authorized party saying it may be distributed under the terms of this
-Lesser General Public License (also called ``this License''). Each
-licensee is addressed as ``you''.
-
- A ``library'' means a collection of software functions and/or data
-prepared so as to be conveniently linked with application programs
-(which use some of those functions and data) to form executables.
-
- The ``Library'', below, refers to any such software library or work
-which has been distributed under these terms. A ``work based on the
-Library'' means either the Library or any derivative work under
-copyright law: that is to say, a work containing the Library or a
-portion of it, either verbatim or with modifications and/or translated
-straightforwardly into another language. (Hereinafter, translation is
-included without limitation in the term ``modification''.)
-
- ``Source code'' for a work means the preferred form of the work for
-making modifications to it. For a library, complete source code means
-all the source code for all modules it contains, plus any associated
-interface definition files, plus the scripts used to control compilation
-and installation of the library.
-
- Activities other than copying, distribution and modification are not
-covered by this License; they are outside its scope. The act of
-running a program using the Library is not restricted, and output from
-such a program is covered only if its contents constitute a work based
-on the Library (independent of the use of the Library in a tool for
-writing it). Whether that is true depends on what the Library does
-and what the program that uses the Library does.
-
-@item
-You may copy and distribute verbatim copies of the Library's
-complete source code as you receive it, in any medium, provided that
-you conspicuously and appropriately publish on each copy an
-appropriate copyright notice and disclaimer of warranty; keep intact
-all the notices that refer to this License and to the absence of any
-warranty; and distribute a copy of this License along with the
-Library.
-
- You may charge a fee for the physical act of transferring a copy,
-and you may at your option offer warranty protection in exchange for a
-fee.
-
-@item
-You may modify your copy or copies of the Library or any portion
-of it, thus forming a work based on the Library, and copy and
-distribute such modifications or work under the terms of Section 1
-above, provided that you also meet all of these conditions:
-
-@enumerate a
-@item
-The modified work must itself be a software library.
-
-@item
-You must cause the files modified to carry prominent notices
-stating that you changed the files and the date of any change.
-
-@item
-You must cause the whole of the work to be licensed at no
-charge to all third parties under the terms of this License.
-
-@item
-If a facility in the modified Library refers to a function or a
-table of data to be supplied by an application program that uses
-the facility, other than as an argument passed when the facility
-is invoked, then you must make a good faith effort to ensure that,
-in the event an application does not supply such function or
-table, the facility still operates, and performs whatever part of
-its purpose remains meaningful.
-
-(For example, a function in a library to compute square roots has
-a purpose that is entirely well-defined independent of the
-application. Therefore, Subsection 2d requires that any
-application-supplied function or table used by this function must
-be optional: if the application does not supply it, the square
-root function must still compute square roots.)
-@end enumerate
-
-These requirements apply to the modified work as a whole. If
-identifiable sections of that work are not derived from the Library,
-and can be reasonably considered independent and separate works in
-themselves, then this License, and its terms, do not apply to those
-sections when you distribute them as separate works. But when you
-distribute the same sections as part of a whole which is a work based
-on the Library, the distribution of the whole must be on the terms of
-this License, whose permissions for other licensees extend to the
-entire whole, and thus to each and every part regardless of who wrote
-it.
-
-Thus, it is not the intent of this section to claim rights or contest
-your rights to work written entirely by you; rather, the intent is to
-exercise the right to control the distribution of derivative or
-collective works based on the Library.
-
-In addition, mere aggregation of another work not based on the Library
-with the Library (or with a work based on the Library) on a volume of
-a storage or distribution medium does not bring the other work under
-the scope of this License.
-
-@item
-You may opt to apply the terms of the ordinary GNU General Public
-License instead of this License to a given copy of the Library. To do
-this, you must alter all the notices that refer to this License, so
-that they refer to the ordinary GNU General Public License, version 2,
-instead of to this License. (If a newer version than version 2 of the
-ordinary GNU General Public License has appeared, then you can specify
-that version instead if you wish.) Do not make any other change in
-these notices.
-
- Once this change is made in a given copy, it is irreversible for
-that copy, so the ordinary GNU General Public License applies to all
-subsequent copies and derivative works made from that copy.
-
- This option is useful when you wish to copy part of the code of
-the Library into a program that is not a library.
-
-@item
-You may copy and distribute the Library (or a portion or
-derivative of it, under Section 2) in object code or executable form
-under the terms of Sections 1 and 2 above provided that you accompany
-it with the complete corresponding machine-readable source code, which
-must be distributed under the terms of Sections 1 and 2 above on a
-medium customarily used for software interchange.
-
- If distribution of object code is made by offering access to copy
-from a designated place, then offering equivalent access to copy the
-source code from the same place satisfies the requirement to
-distribute the source code, even though third parties are not
-compelled to copy the source along with the object code.
-
-@item
-A program that contains no derivative of any portion of the
-Library, but is designed to work with the Library by being compiled or
-linked with it, is called a ``work that uses the Library''. Such a
-work, in isolation, is not a derivative work of the Library, and
-therefore falls outside the scope of this License.
-
- However, linking a ``work that uses the Library'' with the Library
-creates an executable that is a derivative of the Library (because it
-contains portions of the Library), rather than a ``work that uses the
-library''. The executable is therefore covered by this License.
-Section 6 states terms for distribution of such executables.
-
- When a ``work that uses the Library'' uses material from a header file
-that is part of the Library, the object code for the work may be a
-derivative work of the Library even though the source code is not.
-Whether this is true is especially significant if the work can be
-linked without the Library, or if the work is itself a library. The
-threshold for this to be true is not precisely defined by law.
-
- If such an object file uses only numerical parameters, data
-structure layouts and accessors, and small macros and small inline
-functions (ten lines or less in length), then the use of the object
-file is unrestricted, regardless of whether it is legally a derivative
-work. (Executables containing this object code plus portions of the
-Library will still fall under Section 6.)
-
- Otherwise, if the work is a derivative of the Library, you may
-distribute the object code for the work under the terms of Section 6.
-Any executables containing that work also fall under Section 6,
-whether or not they are linked directly with the Library itself.
-
-@item
-As an exception to the Sections above, you may also combine or
-link a ``work that uses the Library'' with the Library to produce a
-work containing portions of the Library, and distribute that work
-under terms of your choice, provided that the terms permit
-modification of the work for the customer's own use and reverse
-engineering for debugging such modifications.
-
- You must give prominent notice with each copy of the work that the
-Library is used in it and that the Library and its use are covered by
-this License. You must supply a copy of this License. If the work
-during execution displays copyright notices, you must include the
-copyright notice for the Library among them, as well as a reference
-directing the user to the copy of this License. Also, you must do one
-of these things:
-
-@enumerate a
-@item
-Accompany the work with the complete corresponding
-machine-readable source code for the Library including whatever
-changes were used in the work (which must be distributed under
-Sections 1 and 2 above); and, if the work is an executable linked
-with the Library, with the complete machine-readable ``work that
-uses the Library'', as object code and/or source code, so that the
-user can modify the Library and then relink to produce a modified
-executable containing the modified Library. (It is understood
-that the user who changes the contents of definitions files in the
-Library will not necessarily be able to recompile the application
-to use the modified definitions.)
-
-@item
-Use a suitable shared library mechanism for linking with the Library. A
-suitable mechanism is one that (1) uses at run time a copy of the
-library already present on the user's computer system, rather than
-copying library functions into the executable, and (2) will operate
-properly with a modified version of the library, if the user installs
-one, as long as the modified version is interface-compatible with the
-version that the work was made with.
-
-@item
-Accompany the work with a written offer, valid for at
-least three years, to give the same user the materials
-specified in Subsection 6a, above, for a charge no more
-than the cost of performing this distribution.
-
-@item
-If distribution of the work is made by offering access to copy
-from a designated place, offer equivalent access to copy the above
-specified materials from the same place.
-
-@item
-Verify that the user has already received a copy of these
-materials or that you have already sent this user a copy.
-@end enumerate
-
- For an executable, the required form of the ``work that uses the
-Library'' must include any data and utility programs needed for
-reproducing the executable from it. However, as a special exception,
-the materials to be distributed need not include anything that is
-normally distributed (in either source or binary form) with the major
-components (compiler, kernel, and so on) of the operating system on
-which the executable runs, unless that component itself accompanies the
-executable.
-
- It may happen that this requirement contradicts the license
-restrictions of other proprietary libraries that do not normally
-accompany the operating system. Such a contradiction means you cannot
-use both them and the Library together in an executable that you
-distribute.
-
-@item
-You may place library facilities that are a work based on the
-Library side-by-side in a single library together with other library
-facilities not covered by this License, and distribute such a combined
-library, provided that the separate distribution of the work based on
-the Library and of the other library facilities is otherwise
-permitted, and provided that you do these two things:
-
-@enumerate a
-@item
-Accompany the combined library with a copy of the same work
-based on the Library, uncombined with any other library
-facilities. This must be distributed under the terms of the
-Sections above.
-
-@item
-Give prominent notice with the combined library of the fact
-that part of it is a work based on the Library, and explaining
-where to find the accompanying uncombined form of the same work.
-@end enumerate
-
-@item
-You may not copy, modify, sublicense, link with, or distribute
-the Library except as expressly provided under this License. Any
-attempt otherwise to copy, modify, sublicense, link with, or
-distribute the Library is void, and will automatically terminate your
-rights under this License. However, parties who have received copies,
-or rights, from you under this License will not have their licenses
-terminated so long as such parties remain in full compliance.
-
-@item
-You are not required to accept this License, since you have not
-signed it. However, nothing else grants you permission to modify or
-distribute the Library or its derivative works. These actions are
-prohibited by law if you do not accept this License. Therefore, by
-modifying or distributing the Library (or any work based on the
-Library), you indicate your acceptance of this License to do so, and
-all its terms and conditions for copying, distributing or modifying
-the Library or works based on it.
-
-@item
-Each time you redistribute the Library (or any work based on the
-Library), the recipient automatically receives a license from the
-original licensor to copy, distribute, link with or modify the Library
-subject to these terms and conditions. You may not impose any further
-restrictions on the recipients' exercise of the rights granted herein.
-You are not responsible for enforcing compliance by third parties with
-this License.
-
-@item
-If, as a consequence of a court judgment or allegation of patent
-infringement or for any other reason (not limited to patent issues),
-conditions are imposed on you (whether by court order, agreement or
-otherwise) that contradict the conditions of this License, they do not
-excuse you from the conditions of this License. If you cannot
-distribute so as to satisfy simultaneously your obligations under this
-License and any other pertinent obligations, then as a consequence you
-may not distribute the Library at all. For example, if a patent
-license would not permit royalty-free redistribution of the Library by
-all those who receive copies directly or indirectly through you, then
-the only way you could satisfy both it and this License would be to
-refrain entirely from distribution of the Library.
-
-If any portion of this section is held invalid or unenforceable under any
-particular circumstance, the balance of the section is intended to apply,
-and the section as a whole is intended to apply in other circumstances.
-
-It is not the purpose of this section to induce you to infringe any
-patents or other property right claims or to contest validity of any
-such claims; this section has the sole purpose of protecting the
-integrity of the free software distribution system which is
-implemented by public license practices. Many people have made
-generous contributions to the wide range of software distributed
-through that system in reliance on consistent application of that
-system; it is up to the author/donor to decide if he or she is willing
-to distribute software through any other system and a licensee cannot
-impose that choice.
-
-This section is intended to make thoroughly clear what is believed to
-be a consequence of the rest of this License.
-
-@item
-If the distribution and/or use of the Library is restricted in
-certain countries either by patents or by copyrighted interfaces, the
-original copyright holder who places the Library under this License may add
-an explicit geographical distribution limitation excluding those countries,
-so that distribution is permitted only in or among countries not thus
-excluded. In such case, this License incorporates the limitation as if
-written in the body of this License.
-
-@item
-The Free Software Foundation may publish revised and/or new
-versions of the Lesser General Public 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.
-
-Each version is given a distinguishing version number. If the Library
-specifies a version number of this License which applies to it and
-``any later version'', you have the option of following the terms and
-conditions either of that version or of any later version published by
-the Free Software Foundation. If the Library does not specify a
-license version number, you may choose any version ever published by
-the Free Software Foundation.
-
-@item
-If you wish to incorporate parts of the Library into other free
-programs whose distribution conditions are incompatible with these,
-write to the author to ask for permission. For software which is
-copyrighted by the Free Software Foundation, write to the Free
-Software Foundation; we sometimes make exceptions for this. Our
-decision will be guided by the two goals of preserving the free status
-of all derivatives of our free software and of promoting the sharing
-and reuse of software generally.
-
-@center NO WARRANTY
-
-@item
-BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO
-WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
-EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
-OTHER PARTIES PROVIDE THE LIBRARY ``AS IS'' WITHOUT WARRANTY OF ANY
-KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
-IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
-PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
-LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME
-THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
-
-@item
-IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
-WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
-AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU
-FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
-CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
-LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
-RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
-FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
-SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
-DAMAGES.
-@end enumerate
-
-@iftex
-@heading END OF TERMS AND CONDITIONS
-@end iftex
-@ifinfo
-@center END OF TERMS AND CONDITIONS
-@end ifinfo
-
-@page
-@appendixsubsec How to Apply These Terms to Your New Libraries
-
- If you develop a new library, and you want it to be of the greatest
-possible use to the public, we recommend making it free software that
-everyone can redistribute and change. You can do so by permitting
-redistribution under these terms (or, alternatively, under the terms of the
-ordinary General Public License).
-
- To apply these terms, attach the following notices to the library. It is
-safest to attach them to the start of each source file to most effectively
-convey the exclusion of warranty; and each file should have at least the
-``copyright'' line and a pointer to where the full notice is found.
-
-@smallexample
-@var{one line to give the library's name and an idea of what it does.}
-Copyright (C) @var{year} @var{name of author}
-
-This library is free software; you can redistribute it and/or modify it
-under the terms of the GNU Lesser General Public License as published by
-the Free Software Foundation; either version 2.1 of the License, or (at
-your option) any later version.
-
-This library is distributed in the hope that it will be useful, but
-WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
-Lesser General Public License for more details.
-
-You should have received a copy of the GNU Lesser General Public
-License along with this library; if not, write to the Free Software
-Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
-USA.
-@end smallexample
-
-Also add information on how to contact you by electronic and paper mail.
-
-You should also get your employer (if you work as a programmer) or your
-school, if any, to sign a ``copyright disclaimer'' for the library, if
-necessary. Here is a sample; alter the names:
-
-@smallexample
-Yoyodyne, Inc., hereby disclaims all copyright interest in the library
-`Frob' (a library for tweaking knobs) written by James Random Hacker.
-
-@var{signature of Ty Coon}, 1 April 1990
-Ty Coon, President of Vice
-@end smallexample
-
-That's all there is to it!
+++ /dev/null
-@c Automatically generated from *.c and others (the comments before
-@c each entry tell you which file and where in that file). DO NOT EDIT!
-@c Edit the *.c files, configure with --enable-maintainer-mode,
-@c run 'make stamp-functions' and gather-docs will build a new copy.
-
-@c alloca.c:26
-@deftypefn Replacement void* alloca (size_t @var{size})
-
-This function allocates memory which will be automatically reclaimed
-after the procedure exits. The @libib{} implementation does not free
-the memory immediately but will do so eventually during subsequent
-calls to this function. Memory is allocated using @code{xmalloc} under
-normal circumstances.
-
-The header file @file{alloca-conf.h} can be used in conjunction with the
-GNU Autoconf test @code{AC_FUNC_ALLOCA} to test for and properly make
-available this function. The @code{AC_FUNC_ALLOCA} test requires that
-client code use a block of preprocessor code to be safe (see the Autoconf
-manual for more); this header incorporates that logic and more, including
-the possibility of a GCC built-in function.
-
-@end deftypefn
-
-@c asprintf.c:32
-@deftypefn Extension int asprintf (char **@var{resptr}, const char *@var{format}, ...)
-
-Like @code{sprintf}, but instead of passing a pointer to a buffer, you
-pass a pointer to a pointer. This function will compute the size of
-the buffer needed, allocate memory with @code{malloc}, and store a
-pointer to the allocated memory in @code{*@var{resptr}}. The value
-returned is the same as @code{sprintf} would return. If memory could
-not be allocated, minus one is returned and @code{NULL} is stored in
-@code{*@var{resptr}}.
-
-@end deftypefn
-
-@c atexit.c:6
-@deftypefn Supplemental int atexit (void (*@var{f})())
-
-Causes function @var{f} to be called at exit. Returns 0.
-
-@end deftypefn
-
-@c basename.c:6
-@deftypefn Supplemental char* basename (const char *@var{name})
-
-Returns a pointer to the last component of pathname @var{name}.
-Behavior is undefined if the pathname ends in a directory separator.
-
-@end deftypefn
-
-@c bcmp.c:6
-@deftypefn Supplemental int bcmp (char *@var{x}, char *@var{y}, int @var{count})
-
-Compares the first @var{count} bytes of two areas of memory. Returns
-zero if they are the same, nonzero otherwise. Returns zero if
-@var{count} is zero. A nonzero result only indicates a difference,
-it does not indicate any sorting order (say, by having a positive
-result mean @var{x} sorts before @var{y}).
-
-@end deftypefn
-
-@c bcopy.c:3
-@deftypefn Supplemental void bcopy (char *@var{in}, char *@var{out}, int @var{length})
-
-Copies @var{length} bytes from memory region @var{in} to region
-@var{out}. The use of @code{bcopy} is deprecated in new programs.
-
-@end deftypefn
-
-@c bsearch.c:33
-@deftypefn Supplemental void* bsearch (const void *@var{key}, @
- const void *@var{base}, size_t @var{nmemb}, size_t @var{size}, @
- int (*@var{compar})(const void *, const void *))
-
-Performs a search over an array of @var{nmemb} elements pointed to by
-@var{base} for a member that matches the object pointed to by @var{key}.
-The size of each member is specified by @var{size}. The array contents
-should be sorted in ascending order according to the @var{compar}
-comparison function. This routine should take two arguments pointing to
-the @var{key} and to an array member, in that order, and should return an
-integer less than, equal to, or greater than zero if the @var{key} object
-is respectively less than, matching, or greater than the array member.
-
-@end deftypefn
-
-@c bsearch_r.c:33
-@deftypefn Supplemental void* bsearch_r (const void *@var{key}, @
- const void *@var{base}, size_t @var{nmemb}, size_t @var{size}, @
- int (*@var{compar})(const void *, const void *, void *), void *@var{arg})
-
-Performs a search over an array of @var{nmemb} elements pointed to by
-@var{base} for a member that matches the object pointed to by @var{key}.
-The size of each member is specified by @var{size}. The array contents
-should be sorted in ascending order according to the @var{compar}
-comparison function. This routine should take three arguments: the first
-two point to the @var{key} and to an array member, and the last is passed
-down unchanged from @code{bsearch_r}'s last argument. It should return an
-integer less than, equal to, or greater than zero if the @var{key} object
-is respectively less than, matching, or greater than the array member.
-
-@end deftypefn
-
-@c argv.c:138
-@deftypefn Extension char** buildargv (char *@var{sp})
-
-Given a pointer to a string, parse the string extracting fields
-separated by whitespace and optionally enclosed within either single
-or double quotes (which are stripped off), and build a vector of
-pointers to copies of the string for each field. The input string
-remains unchanged. The last element of the vector is followed by a
-@code{NULL} element.
-
-All of the memory for the pointer array and copies of the string
-is obtained from @code{xmalloc}. All of the memory can be returned to the
-system with the single function call @code{freeargv}, which takes the
-returned result of @code{buildargv}, as it's argument.
-
-Returns a pointer to the argument vector if successful. Returns
-@code{NULL} if @var{sp} is @code{NULL} or if there is insufficient
-memory to complete building the argument vector.
-
-If the input is a null string (as opposed to a @code{NULL} pointer),
-then buildarg returns an argument vector that has one arg, a null
-string.
-
-@end deftypefn
-
-@c bzero.c:6
-@deftypefn Supplemental void bzero (char *@var{mem}, int @var{count})
-
-Zeros @var{count} bytes starting at @var{mem}. Use of this function
-is deprecated in favor of @code{memset}.
-
-@end deftypefn
-
-@c calloc.c:6
-@deftypefn Supplemental void* calloc (size_t @var{nelem}, size_t @var{elsize})
-
-Uses @code{malloc} to allocate storage for @var{nelem} objects of
-@var{elsize} bytes each, then zeros the memory.
-
-@end deftypefn
-
-@c filename_cmp.c:201
-@deftypefn Extension int canonical_filename_eq (const char *@var{a}, const char *@var{b})
-
-Return non-zero if file names @var{a} and @var{b} are equivalent.
-This function compares the canonical versions of the filenames as returned by
-@code{lrealpath()}, so that so that different file names pointing to the same
-underlying file are treated as being identical.
-
-@end deftypefn
-
-@c choose-temp.c:45
-@deftypefn Extension char* choose_temp_base (void)
-
-Return a prefix for temporary file names or @code{NULL} if unable to
-find one. The current directory is chosen if all else fails so the
-program is exited if a temporary directory can't be found (@code{mktemp}
-fails). The buffer for the result is obtained with @code{xmalloc}.
-
-This function is provided for backwards compatibility only. Its use is
-not recommended.
-
-@end deftypefn
-
-@c make-temp-file.c:95
-@deftypefn Replacement const char* choose_tmpdir ()
-
-Returns a pointer to a directory path suitable for creating temporary
-files in.
-
-@end deftypefn
-
-@c clock.c:27
-@deftypefn Supplemental long clock (void)
-
-Returns an approximation of the CPU time used by the process as a
-@code{clock_t}; divide this number by @samp{CLOCKS_PER_SEC} to get the
-number of seconds used.
-
-@end deftypefn
-
-@c concat.c:24
-@deftypefn Extension char* concat (const char *@var{s1}, const char *@var{s2}, @
- @dots{}, @code{NULL})
-
-Concatenate zero or more of strings and return the result in freshly
-@code{xmalloc}ed memory. The argument list is terminated by the first
-@code{NULL} pointer encountered. Pointers to empty strings are ignored.
-
-@end deftypefn
-
-@c argv.c:495
-@deftypefn Extension int countargv (char * const *@var{argv})
-
-Return the number of elements in @var{argv}.
-Returns zero if @var{argv} is NULL.
-
-@end deftypefn
-
-@c crc32.c:140
-@deftypefn Extension {unsigned int} crc32 (const unsigned char *@var{buf}, @
- int @var{len}, unsigned int @var{init})
-
-Compute the 32-bit CRC of @var{buf} which has length @var{len}. The
-starting value is @var{init}; this may be used to compute the CRC of
-data split across multiple buffers by passing the return value of each
-call as the @var{init} parameter of the next.
-
-This is used by the @command{gdb} remote protocol for the @samp{qCRC}
-command. In order to get the same results as gdb for a block of data,
-you must pass the first CRC parameter as @code{0xffffffff}.
-
-This CRC can be specified as:
-
- Width : 32
- Poly : 0x04c11db7
- Init : parameter, typically 0xffffffff
- RefIn : false
- RefOut : false
- XorOut : 0
-
-This differs from the "standard" CRC-32 algorithm in that the values
-are not reflected, and there is no final XOR value. These differences
-make it easy to compose the values of multiple blocks.
-
-@end deftypefn
-
-@c argv.c:59
-@deftypefn Extension char** dupargv (char * const *@var{vector})
-
-Duplicate an argument vector. Simply scans through @var{vector},
-duplicating each argument until the terminating @code{NULL} is found.
-Returns a pointer to the argument vector if successful. Returns
-@code{NULL} if there is insufficient memory to complete building the
-argument vector.
-
-@end deftypefn
-
-@c strerror.c:572
-@deftypefn Extension int errno_max (void)
-
-Returns the maximum @code{errno} value for which a corresponding
-symbolic name or message is available. Note that in the case where we
-use the @code{sys_errlist} supplied by the system, it is possible for
-there to be more symbolic names than messages, or vice versa. In
-fact, the manual page for @code{perror(3C)} explicitly warns that one
-should check the size of the table (@code{sys_nerr}) before indexing
-it, since new error codes may be added to the system before they are
-added to the table. Thus @code{sys_nerr} might be smaller than value
-implied by the largest @code{errno} value defined in @code{<errno.h>}.
-
-We return the maximum value that can be used to obtain a meaningful
-symbolic name or message.
-
-@end deftypefn
-
-@c argv.c:352
-@deftypefn Extension void expandargv (int *@var{argcp}, char ***@var{argvp})
-
-The @var{argcp} and @code{argvp} arguments are pointers to the usual
-@code{argc} and @code{argv} arguments to @code{main}. This function
-looks for arguments that begin with the character @samp{@@}. Any such
-arguments are interpreted as ``response files''. The contents of the
-response file are interpreted as additional command line options. In
-particular, the file is separated into whitespace-separated strings;
-each such string is taken as a command-line option. The new options
-are inserted in place of the option naming the response file, and
-@code{*argcp} and @code{*argvp} will be updated. If the value of
-@code{*argvp} is modified by this function, then the new value has
-been dynamically allocated and can be deallocated by the caller with
-@code{freeargv}. However, most callers will simply call
-@code{expandargv} near the beginning of @code{main} and allow the
-operating system to free the memory when the program exits.
-
-@end deftypefn
-
-@c fdmatch.c:23
-@deftypefn Extension int fdmatch (int @var{fd1}, int @var{fd2})
-
-Check to see if two open file descriptors refer to the same file.
-This is useful, for example, when we have an open file descriptor for
-an unnamed file, and the name of a file that we believe to correspond
-to that fd. This can happen when we are exec'd with an already open
-file (@code{stdout} for example) or from the SVR4 @file{/proc} calls
-that return open file descriptors for mapped address spaces. All we
-have to do is open the file by name and check the two file descriptors
-for a match, which is done by comparing major and minor device numbers
-and inode numbers.
-
-@end deftypefn
-
-@c fopen_unlocked.c:49
-@deftypefn Extension {FILE *} fdopen_unlocked (int @var{fildes}, @
- const char * @var{mode})
-
-Opens and returns a @code{FILE} pointer via @code{fdopen}. If the
-operating system supports it, ensure that the stream is setup to avoid
-any multi-threaded locking. Otherwise return the @code{FILE} pointer
-unchanged.
-
-@end deftypefn
-
-@c ffs.c:3
-@deftypefn Supplemental int ffs (int @var{valu})
-
-Find the first (least significant) bit set in @var{valu}. Bits are
-numbered from right to left, starting with bit 1 (corresponding to the
-value 1). If @var{valu} is zero, zero is returned.
-
-@end deftypefn
-
-@c filename_cmp.c:37
-@deftypefn Extension int filename_cmp (const char *@var{s1}, const char *@var{s2})
-
-Return zero if the two file names @var{s1} and @var{s2} are equivalent.
-If not equivalent, the returned value is similar to what @code{strcmp}
-would return. In other words, it returns a negative value if @var{s1}
-is less than @var{s2}, or a positive value if @var{s2} is greater than
-@var{s2}.
-
-This function does not normalize file names. As a result, this function
-will treat filenames that are spelled differently as different even in
-the case when the two filenames point to the same underlying file.
-However, it does handle the fact that on DOS-like file systems, forward
-and backward slashes are equal.
-
-@end deftypefn
-
-@c filename_cmp.c:183
-@deftypefn Extension int filename_eq (const void *@var{s1}, const void *@var{s2})
-
-Return non-zero if file names @var{s1} and @var{s2} are equivalent.
-This function is for use with hashtab.c hash tables.
-
-@end deftypefn
-
-@c filename_cmp.c:152
-@deftypefn Extension hashval_t filename_hash (const void *@var{s})
-
-Return the hash value for file name @var{s} that will be compared
-using filename_cmp.
-This function is for use with hashtab.c hash tables.
-
-@end deftypefn
-
-@c filename_cmp.c:94
-@deftypefn Extension int filename_ncmp (const char *@var{s1}, const char *@var{s2}, size_t @var{n})
-
-Return zero if the two file names @var{s1} and @var{s2} are equivalent
-in range @var{n}.
-If not equivalent, the returned value is similar to what @code{strncmp}
-would return. In other words, it returns a negative value if @var{s1}
-is less than @var{s2}, or a positive value if @var{s2} is greater than
-@var{s2}.
-
-This function does not normalize file names. As a result, this function
-will treat filenames that are spelled differently as different even in
-the case when the two filenames point to the same underlying file.
-However, it does handle the fact that on DOS-like file systems, forward
-and backward slashes are equal.
-
-@end deftypefn
-
-@c fnmatch.txh:1
-@deftypefn Replacement int fnmatch (const char *@var{pattern}, @
- const char *@var{string}, int @var{flags})
-
-Matches @var{string} against @var{pattern}, returning zero if it
-matches, @code{FNM_NOMATCH} if not. @var{pattern} may contain the
-wildcards @code{?} to match any one character, @code{*} to match any
-zero or more characters, or a set of alternate characters in square
-brackets, like @samp{[a-gt8]}, which match one character (@code{a}
-through @code{g}, or @code{t}, or @code{8}, in this example) if that one
-character is in the set. A set may be inverted (i.e., match anything
-except what's in the set) by giving @code{^} or @code{!} as the first
-character in the set. To include those characters in the set, list them
-as anything other than the first character of the set. To include a
-dash in the set, list it last in the set. A backslash character makes
-the following character not special, so for example you could match
-against a literal asterisk with @samp{\*}. To match a literal
-backslash, use @samp{\\}.
-
-@code{flags} controls various aspects of the matching process, and is a
-boolean OR of zero or more of the following values (defined in
-@code{<fnmatch.h>}):
-
-@table @code
-
-@item FNM_PATHNAME
-@itemx FNM_FILE_NAME
-@var{string} is assumed to be a path name. No wildcard will ever match
-@code{/}.
-
-@item FNM_NOESCAPE
-Do not interpret backslashes as quoting the following special character.
-
-@item FNM_PERIOD
-A leading period (at the beginning of @var{string}, or if
-@code{FNM_PATHNAME} after a slash) is not matched by @code{*} or
-@code{?} but must be matched explicitly.
-
-@item FNM_LEADING_DIR
-Means that @var{string} also matches @var{pattern} if some initial part
-of @var{string} matches, and is followed by @code{/} and zero or more
-characters. For example, @samp{foo*} would match either @samp{foobar}
-or @samp{foobar/grill}.
-
-@item FNM_CASEFOLD
-Ignores case when performing the comparison.
-
-@end table
-
-@end deftypefn
-
-@c fopen_unlocked.c:39
-@deftypefn Extension {FILE *} fopen_unlocked (const char *@var{path}, @
- const char * @var{mode})
-
-Opens and returns a @code{FILE} pointer via @code{fopen}. If the
-operating system supports it, ensure that the stream is setup to avoid
-any multi-threaded locking. Otherwise return the @code{FILE} pointer
-unchanged.
-
-@end deftypefn
-
-@c argv.c:93
-@deftypefn Extension void freeargv (char **@var{vector})
-
-Free an argument vector that was built using @code{buildargv}. Simply
-scans through @var{vector}, freeing the memory for each argument until
-the terminating @code{NULL} is found, and then frees @var{vector}
-itself.
-
-@end deftypefn
-
-@c fopen_unlocked.c:59
-@deftypefn Extension {FILE *} freopen_unlocked (const char * @var{path}, @
- const char * @var{mode}, FILE * @var{stream})
-
-Opens and returns a @code{FILE} pointer via @code{freopen}. If the
-operating system supports it, ensure that the stream is setup to avoid
-any multi-threaded locking. Otherwise return the @code{FILE} pointer
-unchanged.
-
-@end deftypefn
-
-@c getruntime.c:86
-@deftypefn Replacement long get_run_time (void)
-
-Returns the time used so far, in microseconds. If possible, this is
-the time used by this process, else it is the elapsed time since the
-process started.
-
-@end deftypefn
-
-@c getcwd.c:6
-@deftypefn Supplemental char* getcwd (char *@var{pathname}, int @var{len})
-
-Copy the absolute pathname for the current working directory into
-@var{pathname}, which is assumed to point to a buffer of at least
-@var{len} bytes, and return a pointer to the buffer. If the current
-directory's path doesn't fit in @var{len} characters, the result is
-@code{NULL} and @code{errno} is set. If @var{pathname} is a null pointer,
-@code{getcwd} will obtain @var{len} bytes of space using
-@code{malloc}.
-
-@end deftypefn
-
-@c getpagesize.c:5
-@deftypefn Supplemental int getpagesize (void)
-
-Returns the number of bytes in a page of memory. This is the
-granularity of many of the system memory management routines. No
-guarantee is made as to whether or not it is the same as the basic
-memory management hardware page size.
-
-@end deftypefn
-
-@c getpwd.c:5
-@deftypefn Supplemental char* getpwd (void)
-
-Returns the current working directory. This implementation caches the
-result on the assumption that the process will not call @code{chdir}
-between calls to @code{getpwd}.
-
-@end deftypefn
-
-@c gettimeofday.c:12
-@deftypefn Supplemental int gettimeofday (struct timeval *@var{tp}, void *@var{tz})
-
-Writes the current time to @var{tp}. This implementation requires
-that @var{tz} be NULL. Returns 0 on success, -1 on failure.
-
-@end deftypefn
-
-@c hex.c:33
-@deftypefn Extension void hex_init (void)
-
-Initializes the array mapping the current character set to
-corresponding hex values. This function must be called before any
-call to @code{hex_p} or @code{hex_value}. If you fail to call it, a
-default ASCII-based table will normally be used on ASCII systems.
-
-@end deftypefn
-
-@c hex.c:42
-@deftypefn Extension int hex_p (int @var{c})
-
-Evaluates to non-zero if the given character is a valid hex character,
-or zero if it is not. Note that the value you pass will be cast to
-@code{unsigned char} within the macro.
-
-@end deftypefn
-
-@c hex.c:50
-@deftypefn Extension {unsigned int} hex_value (int @var{c})
-
-Returns the numeric equivalent of the given character when interpreted
-as a hexadecimal digit. The result is undefined if you pass an
-invalid hex digit. Note that the value you pass will be cast to
-@code{unsigned char} within the macro.
-
-The @code{hex_value} macro returns @code{unsigned int}, rather than
-signed @code{int}, to make it easier to use in parsing addresses from
-hex dump files: a signed @code{int} would be sign-extended when
-converted to a wider unsigned type --- like @code{bfd_vma}, on some
-systems.
-
-@end deftypefn
-
-@c safe-ctype.c:24
-@defvr Extension HOST_CHARSET
-This macro indicates the basic character set and encoding used by the
-host: more precisely, the encoding used for character constants in
-preprocessor @samp{#if} statements (the C "execution character set").
-It is defined by @file{safe-ctype.h}, and will be an integer constant
-with one of the following values:
-
-@ftable @code
-@item HOST_CHARSET_UNKNOWN
-The host character set is unknown - that is, not one of the next two
-possibilities.
-
-@item HOST_CHARSET_ASCII
-The host character set is ASCII.
-
-@item HOST_CHARSET_EBCDIC
-The host character set is some variant of EBCDIC. (Only one of the
-nineteen EBCDIC varying characters is tested; exercise caution.)
-@end ftable
-@end defvr
-
-@c hashtab.c:327
-@deftypefn Supplemental htab_t htab_create_typed_alloc (size_t @var{size}, @
-htab_hash @var{hash_f}, htab_eq @var{eq_f}, htab_del @var{del_f}, @
-htab_alloc @var{alloc_tab_f}, htab_alloc @var{alloc_f}, @
-htab_free @var{free_f})
-
-This function creates a hash table that uses two different allocators
-@var{alloc_tab_f} and @var{alloc_f} to use for allocating the table itself
-and its entries respectively. This is useful when variables of different
-types need to be allocated with different allocators.
-
-The created hash table is slightly larger than @var{size} and it is
-initially empty (all the hash table entries are @code{HTAB_EMPTY_ENTRY}).
-The function returns the created hash table, or @code{NULL} if memory
-allocation fails.
-
-@end deftypefn
-
-@c index.c:5
-@deftypefn Supplemental char* index (char *@var{s}, int @var{c})
-
-Returns a pointer to the first occurrence of the character @var{c} in
-the string @var{s}, or @code{NULL} if not found. The use of @code{index} is
-deprecated in new programs in favor of @code{strchr}.
-
-@end deftypefn
-
-@c insque.c:6
-@deftypefn Supplemental void insque (struct qelem *@var{elem}, @
- struct qelem *@var{pred})
-@deftypefnx Supplemental void remque (struct qelem *@var{elem})
-
-Routines to manipulate queues built from doubly linked lists. The
-@code{insque} routine inserts @var{elem} in the queue immediately
-after @var{pred}. The @code{remque} routine removes @var{elem} from
-its containing queue. These routines expect to be passed pointers to
-structures which have as their first members a forward pointer and a
-back pointer, like this prototype (although no prototype is provided):
-
-@example
-struct qelem @{
- struct qelem *q_forw;
- struct qelem *q_back;
- char q_data[];
-@};
-@end example
-
-@end deftypefn
-
-@c safe-ctype.c:45
-@deffn Extension ISALPHA (@var{c})
-@deffnx Extension ISALNUM (@var{c})
-@deffnx Extension ISBLANK (@var{c})
-@deffnx Extension ISCNTRL (@var{c})
-@deffnx Extension ISDIGIT (@var{c})
-@deffnx Extension ISGRAPH (@var{c})
-@deffnx Extension ISLOWER (@var{c})
-@deffnx Extension ISPRINT (@var{c})
-@deffnx Extension ISPUNCT (@var{c})
-@deffnx Extension ISSPACE (@var{c})
-@deffnx Extension ISUPPER (@var{c})
-@deffnx Extension ISXDIGIT (@var{c})
-
-These twelve macros are defined by @file{safe-ctype.h}. Each has the
-same meaning as the corresponding macro (with name in lowercase)
-defined by the standard header @file{ctype.h}. For example,
-@code{ISALPHA} returns true for alphabetic characters and false for
-others. However, there are two differences between these macros and
-those provided by @file{ctype.h}:
-
-@itemize @bullet
-@item These macros are guaranteed to have well-defined behavior for all
-values representable by @code{signed char} and @code{unsigned char}, and
-for @code{EOF}.
-
-@item These macros ignore the current locale; they are true for these
-fixed sets of characters:
-@multitable {@code{XDIGIT}} {yada yada yada yada yada yada yada yada}
-@item @code{ALPHA} @tab @kbd{A-Za-z}
-@item @code{ALNUM} @tab @kbd{A-Za-z0-9}
-@item @code{BLANK} @tab @kbd{space tab}
-@item @code{CNTRL} @tab @code{!PRINT}
-@item @code{DIGIT} @tab @kbd{0-9}
-@item @code{GRAPH} @tab @code{ALNUM || PUNCT}
-@item @code{LOWER} @tab @kbd{a-z}
-@item @code{PRINT} @tab @code{GRAPH ||} @kbd{space}
-@item @code{PUNCT} @tab @kbd{`~!@@#$%^&*()_-=+[@{]@}\|;:'",<.>/?}
-@item @code{SPACE} @tab @kbd{space tab \n \r \f \v}
-@item @code{UPPER} @tab @kbd{A-Z}
-@item @code{XDIGIT} @tab @kbd{0-9A-Fa-f}
-@end multitable
-
-Note that, if the host character set is ASCII or a superset thereof,
-all these macros will return false for all values of @code{char} outside
-the range of 7-bit ASCII. In particular, both ISPRINT and ISCNTRL return
-false for characters with numeric values from 128 to 255.
-@end itemize
-@end deffn
-
-@c safe-ctype.c:94
-@deffn Extension ISIDNUM (@var{c})
-@deffnx Extension ISIDST (@var{c})
-@deffnx Extension IS_VSPACE (@var{c})
-@deffnx Extension IS_NVSPACE (@var{c})
-@deffnx Extension IS_SPACE_OR_NUL (@var{c})
-@deffnx Extension IS_ISOBASIC (@var{c})
-These six macros are defined by @file{safe-ctype.h} and provide
-additional character classes which are useful when doing lexical
-analysis of C or similar languages. They are true for the following
-sets of characters:
-
-@multitable {@code{SPACE_OR_NUL}} {yada yada yada yada yada yada yada yada}
-@item @code{IDNUM} @tab @kbd{A-Za-z0-9_}
-@item @code{IDST} @tab @kbd{A-Za-z_}
-@item @code{VSPACE} @tab @kbd{\r \n}
-@item @code{NVSPACE} @tab @kbd{space tab \f \v \0}
-@item @code{SPACE_OR_NUL} @tab @code{VSPACE || NVSPACE}
-@item @code{ISOBASIC} @tab @code{VSPACE || NVSPACE || PRINT}
-@end multitable
-@end deffn
-
-@c lbasename.c:23
-@deftypefn Replacement {const char*} lbasename (const char *@var{name})
-
-Given a pointer to a string containing a typical pathname
-(@samp{/usr/src/cmd/ls/ls.c} for example), returns a pointer to the
-last component of the pathname (@samp{ls.c} in this case). The
-returned pointer is guaranteed to lie within the original
-string. This latter fact is not true of many vendor C
-libraries, which return special strings or modify the passed
-strings for particular input.
-
-In particular, the empty string returns the same empty string,
-and a path ending in @code{/} returns the empty string after it.
-
-@end deftypefn
-
-@c lrealpath.c:25
-@deftypefn Replacement {const char*} lrealpath (const char *@var{name})
-
-Given a pointer to a string containing a pathname, returns a canonical
-version of the filename. Symlinks will be resolved, and ``.'' and ``..''
-components will be simplified. The returned value will be allocated using
-@code{malloc}, or @code{NULL} will be returned on a memory allocation error.
-
-@end deftypefn
-
-@c make-relative-prefix.c:23
-@deftypefn Extension {const char*} make_relative_prefix (const char *@var{progname}, @
- const char *@var{bin_prefix}, const char *@var{prefix})
-
-Given three paths @var{progname}, @var{bin_prefix}, @var{prefix},
-return the path that is in the same position relative to
-@var{progname}'s directory as @var{prefix} is relative to
-@var{bin_prefix}. That is, a string starting with the directory
-portion of @var{progname}, followed by a relative pathname of the
-difference between @var{bin_prefix} and @var{prefix}.
-
-If @var{progname} does not contain any directory separators,
-@code{make_relative_prefix} will search @env{PATH} to find a program
-named @var{progname}. Also, if @var{progname} is a symbolic link,
-the symbolic link will be resolved.
-
-For example, if @var{bin_prefix} is @code{/alpha/beta/gamma/gcc/delta},
-@var{prefix} is @code{/alpha/beta/gamma/omega/}, and @var{progname} is
-@code{/red/green/blue/gcc}, then this function will return
-@code{/red/green/blue/../../omega/}.
-
-The return value is normally allocated via @code{malloc}. If no
-relative prefix can be found, return @code{NULL}.
-
-@end deftypefn
-
-@c make-temp-file.c:173
-@deftypefn Replacement char* make_temp_file (const char *@var{suffix})
-
-Return a temporary file name (as a string) or @code{NULL} if unable to
-create one. @var{suffix} is a suffix to append to the file name. The
-string is @code{malloc}ed, and the temporary file has been created.
-
-@end deftypefn
-
-@c memchr.c:3
-@deftypefn Supplemental void* memchr (const void *@var{s}, int @var{c}, @
- size_t @var{n})
-
-This function searches memory starting at @code{*@var{s}} for the
-character @var{c}. The search only ends with the first occurrence of
-@var{c}, or after @var{length} characters; in particular, a null
-character does not terminate the search. If the character @var{c} is
-found within @var{length} characters of @code{*@var{s}}, a pointer
-to the character is returned. If @var{c} is not found, then @code{NULL} is
-returned.
-
-@end deftypefn
-
-@c memcmp.c:6
-@deftypefn Supplemental int memcmp (const void *@var{x}, const void *@var{y}, @
- size_t @var{count})
-
-Compares the first @var{count} bytes of two areas of memory. Returns
-zero if they are the same, a value less than zero if @var{x} is
-lexically less than @var{y}, or a value greater than zero if @var{x}
-is lexically greater than @var{y}. Note that lexical order is determined
-as if comparing unsigned char arrays.
-
-@end deftypefn
-
-@c memcpy.c:6
-@deftypefn Supplemental void* memcpy (void *@var{out}, const void *@var{in}, @
- size_t @var{length})
-
-Copies @var{length} bytes from memory region @var{in} to region
-@var{out}. Returns a pointer to @var{out}.
-
-@end deftypefn
-
-@c memmem.c:20
-@deftypefn Supplemental void* memmem (const void *@var{haystack}, @
- size_t @var{haystack_len} const void *@var{needle}, size_t @var{needle_len})
-
-Returns a pointer to the first occurrence of @var{needle} (length
-@var{needle_len}) in @var{haystack} (length @var{haystack_len}).
-Returns @code{NULL} if not found.
-
-@end deftypefn
-
-@c memmove.c:6
-@deftypefn Supplemental void* memmove (void *@var{from}, const void *@var{to}, @
- size_t @var{count})
-
-Copies @var{count} bytes from memory area @var{from} to memory area
-@var{to}, returning a pointer to @var{to}.
-
-@end deftypefn
-
-@c mempcpy.c:23
-@deftypefn Supplemental void* mempcpy (void *@var{out}, const void *@var{in}, @
- size_t @var{length})
-
-Copies @var{length} bytes from memory region @var{in} to region
-@var{out}. Returns a pointer to @var{out} + @var{length}.
-
-@end deftypefn
-
-@c memset.c:6
-@deftypefn Supplemental void* memset (void *@var{s}, int @var{c}, @
- size_t @var{count})
-
-Sets the first @var{count} bytes of @var{s} to the constant byte
-@var{c}, returning a pointer to @var{s}.
-
-@end deftypefn
-
-@c mkstemps.c:60
-@deftypefn Replacement int mkstemps (char *@var{pattern}, int @var{suffix_len})
-
-Generate a unique temporary file name from @var{pattern}.
-@var{pattern} has the form:
-
-@example
- @var{path}/ccXXXXXX@var{suffix}
-@end example
-
-@var{suffix_len} tells us how long @var{suffix} is (it can be zero
-length). The last six characters of @var{pattern} before @var{suffix}
-must be @samp{XXXXXX}; they are replaced with a string that makes the
-filename unique. Returns a file descriptor open on the file for
-reading and writing.
-
-@end deftypefn
-
-@c pexecute.txh:278
-@deftypefn Extension void pex_free (struct pex_obj @var{obj})
-
-Clean up and free all data associated with @var{obj}. If you have not
-yet called @code{pex_get_times} or @code{pex_get_status}, this will
-try to kill the subprocesses.
-
-@end deftypefn
-
-@c pexecute.txh:251
-@deftypefn Extension int pex_get_status (struct pex_obj *@var{obj}, @
- int @var{count}, int *@var{vector})
-
-Returns the exit status of all programs run using @var{obj}.
-@var{count} is the number of results expected. The results will be
-placed into @var{vector}. The results are in the order of the calls
-to @code{pex_run}. Returns 0 on error, 1 on success.
-
-@end deftypefn
-
-@c pexecute.txh:261
-@deftypefn Extension int pex_get_times (struct pex_obj *@var{obj}, @
- int @var{count}, struct pex_time *@var{vector})
-
-Returns the process execution times of all programs run using
-@var{obj}. @var{count} is the number of results expected. The
-results will be placed into @var{vector}. The results are in the
-order of the calls to @code{pex_run}. Returns 0 on error, 1 on
-success.
-
-@code{struct pex_time} has the following fields of the type
-@code{unsigned long}: @code{user_seconds},
-@code{user_microseconds}, @code{system_seconds},
-@code{system_microseconds}. On systems which do not support reporting
-process times, all the fields will be set to @code{0}.
-
-@end deftypefn
-
-@c pexecute.txh:2
-@deftypefn Extension {struct pex_obj *} pex_init (int @var{flags}, @
- const char *@var{pname}, const char *@var{tempbase})
-
-Prepare to execute one or more programs, with standard output of each
-program fed to standard input of the next. This is a system
-independent interface to execute a pipeline.
-
-@var{flags} is a bitwise combination of the following:
-
-@table @code
-
-@vindex PEX_RECORD_TIMES
-@item PEX_RECORD_TIMES
-Record subprocess times if possible.
-
-@vindex PEX_USE_PIPES
-@item PEX_USE_PIPES
-Use pipes for communication between processes, if possible.
-
-@vindex PEX_SAVE_TEMPS
-@item PEX_SAVE_TEMPS
-Don't delete temporary files used for communication between
-processes.
-
-@end table
-
-@var{pname} is the name of program to be executed, used in error
-messages. @var{tempbase} is a base name to use for any required
-temporary files; it may be @code{NULL} to use a randomly chosen name.
-
-@end deftypefn
-
-@c pexecute.txh:161
-@deftypefn Extension {FILE *} pex_input_file (struct pex_obj *@var{obj}, @
- int @var{flags}, const char *@var{in_name})
-
-Return a stream for a temporary file to pass to the first program in
-the pipeline as input.
-
-The name of the input file is chosen according to the same rules
-@code{pex_run} uses to choose output file names, based on
-@var{in_name}, @var{obj} and the @code{PEX_SUFFIX} bit in @var{flags}.
-
-Don't call @code{fclose} on the returned stream; the first call to
-@code{pex_run} closes it automatically.
-
-If @var{flags} includes @code{PEX_BINARY_OUTPUT}, open the stream in
-binary mode; otherwise, open it in the default mode. Including
-@code{PEX_BINARY_OUTPUT} in @var{flags} has no effect on Unix.
-@end deftypefn
-
-@c pexecute.txh:179
-@deftypefn Extension {FILE *} pex_input_pipe (struct pex_obj *@var{obj}, @
- int @var{binary})
-
-Return a stream @var{fp} for a pipe connected to the standard input of
-the first program in the pipeline; @var{fp} is opened for writing.
-You must have passed @code{PEX_USE_PIPES} to the @code{pex_init} call
-that returned @var{obj}.
-
-You must close @var{fp} using @code{fclose} yourself when you have
-finished writing data to the pipeline.
-
-The file descriptor underlying @var{fp} is marked not to be inherited
-by child processes.
-
-On systems that do not support pipes, this function returns
-@code{NULL}, and sets @code{errno} to @code{EINVAL}. If you would
-like to write code that is portable to all systems the @code{pex}
-functions support, consider using @code{pex_input_file} instead.
-
-There are two opportunities for deadlock using
-@code{pex_input_pipe}:
-
-@itemize @bullet
-@item
-Most systems' pipes can buffer only a fixed amount of data; a process
-that writes to a full pipe blocks. Thus, if you write to @file{fp}
-before starting the first process, you run the risk of blocking when
-there is no child process yet to read the data and allow you to
-continue. @code{pex_input_pipe} makes no promises about the
-size of the pipe's buffer, so if you need to write any data at all
-before starting the first process in the pipeline, consider using
-@code{pex_input_file} instead.
-
-@item
-Using @code{pex_input_pipe} and @code{pex_read_output} together
-may also cause deadlock. If the output pipe fills up, so that each
-program in the pipeline is waiting for the next to read more data, and
-you fill the input pipe by writing more data to @var{fp}, then there
-is no way to make progress: the only process that could read data from
-the output pipe is you, but you are blocked on the input pipe.
-
-@end itemize
-
-@end deftypefn
-
-@c pexecute.txh:286
-@deftypefn Extension {const char *} pex_one (int @var{flags}, @
- const char *@var{executable}, char * const *@var{argv}, @
- const char *@var{pname}, const char *@var{outname}, const char *@var{errname}, @
- int *@var{status}, int *@var{err})
-
-An interface to permit the easy execution of a
-single program. The return value and most of the parameters are as
-for a call to @code{pex_run}. @var{flags} is restricted to a
-combination of @code{PEX_SEARCH}, @code{PEX_STDERR_TO_STDOUT}, and
-@code{PEX_BINARY_OUTPUT}. @var{outname} is interpreted as if
-@code{PEX_LAST} were set. On a successful return, @code{*@var{status}} will
-be set to the exit status of the program.
-
-@end deftypefn
-
-@c pexecute.txh:237
-@deftypefn Extension {FILE *} pex_read_err (struct pex_obj *@var{obj}, @
- int @var{binary})
-
-Returns a @code{FILE} pointer which may be used to read the standard
-error of the last program in the pipeline. When this is used,
-@code{PEX_LAST} should not be used in a call to @code{pex_run}. After
-this is called, @code{pex_run} may no longer be called with the same
-@var{obj}. @var{binary} should be non-zero if the file should be
-opened in binary mode. Don't call @code{fclose} on the returned file;
-it will be closed by @code{pex_free}.
-
-@end deftypefn
-
-@c pexecute.txh:224
-@deftypefn Extension {FILE *} pex_read_output (struct pex_obj *@var{obj}, @
- int @var{binary})
-
-Returns a @code{FILE} pointer which may be used to read the standard
-output of the last program in the pipeline. When this is used,
-@code{PEX_LAST} should not be used in a call to @code{pex_run}. After
-this is called, @code{pex_run} may no longer be called with the same
-@var{obj}. @var{binary} should be non-zero if the file should be
-opened in binary mode. Don't call @code{fclose} on the returned file;
-it will be closed by @code{pex_free}.
-
-@end deftypefn
-
-@c pexecute.txh:34
-@deftypefn Extension {const char *} pex_run (struct pex_obj *@var{obj}, @
- int @var{flags}, const char *@var{executable}, char * const *@var{argv}, @
- const char *@var{outname}, const char *@var{errname}, int *@var{err})
-
-Execute one program in a pipeline. On success this returns
-@code{NULL}. On failure it returns an error message, a statically
-allocated string.
-
-@var{obj} is returned by a previous call to @code{pex_init}.
-
-@var{flags} is a bitwise combination of the following:
-
-@table @code
-
-@vindex PEX_LAST
-@item PEX_LAST
-This must be set on the last program in the pipeline. In particular,
-it should be set when executing a single program. The standard output
-of the program will be sent to @var{outname}, or, if @var{outname} is
-@code{NULL}, to the standard output of the calling program. Do @emph{not}
-set this bit if you want to call @code{pex_read_output}
-(described below). After a call to @code{pex_run} with this bit set,
-@var{pex_run} may no longer be called with the same @var{obj}.
-
-@vindex PEX_SEARCH
-@item PEX_SEARCH
-Search for the program using the user's executable search path.
-
-@vindex PEX_SUFFIX
-@item PEX_SUFFIX
-@var{outname} is a suffix. See the description of @var{outname},
-below.
-
-@vindex PEX_STDERR_TO_STDOUT
-@item PEX_STDERR_TO_STDOUT
-Send the program's standard error to standard output, if possible.
-
-@vindex PEX_BINARY_INPUT
-@vindex PEX_BINARY_OUTPUT
-@vindex PEX_BINARY_ERROR
-@item PEX_BINARY_INPUT
-@itemx PEX_BINARY_OUTPUT
-@itemx PEX_BINARY_ERROR
-The standard input (output or error) of the program should be read (written) in
-binary mode rather than text mode. These flags are ignored on systems
-which do not distinguish binary mode and text mode, such as Unix. For
-proper behavior these flags should match appropriately---a call to
-@code{pex_run} using @code{PEX_BINARY_OUTPUT} should be followed by a
-call using @code{PEX_BINARY_INPUT}.
-
-@vindex PEX_STDERR_TO_PIPE
-@item PEX_STDERR_TO_PIPE
-Send the program's standard error to a pipe, if possible. This flag
-cannot be specified together with @code{PEX_STDERR_TO_STDOUT}. This
-flag can be specified only on the last program in pipeline.
-
-@end table
-
-@var{executable} is the program to execute. @var{argv} is the set of
-arguments to pass to the program; normally @code{@var{argv}[0]} will
-be a copy of @var{executable}.
-
-@var{outname} is used to set the name of the file to use for standard
-output. There are two cases in which no output file will be used:
-
-@enumerate
-@item
-if @code{PEX_LAST} is not set in @var{flags}, and @code{PEX_USE_PIPES}
-was set in the call to @code{pex_init}, and the system supports pipes
-
-@item
-if @code{PEX_LAST} is set in @var{flags}, and @var{outname} is
-@code{NULL}
-@end enumerate
-
-@noindent
-Otherwise the code will use a file to hold standard
-output. If @code{PEX_LAST} is not set, this file is considered to be
-a temporary file, and it will be removed when no longer needed, unless
-@code{PEX_SAVE_TEMPS} was set in the call to @code{pex_init}.
-
-There are two cases to consider when setting the name of the file to
-hold standard output.
-
-@enumerate
-@item
-@code{PEX_SUFFIX} is set in @var{flags}. In this case
-@var{outname} may not be @code{NULL}. If the @var{tempbase} parameter
-to @code{pex_init} was not @code{NULL}, then the output file name is
-the concatenation of @var{tempbase} and @var{outname}. If
-@var{tempbase} was @code{NULL}, then the output file name is a random
-file name ending in @var{outname}.
-
-@item
-@code{PEX_SUFFIX} was not set in @var{flags}. In this
-case, if @var{outname} is not @code{NULL}, it is used as the output
-file name. If @var{outname} is @code{NULL}, and @var{tempbase} was
-not NULL, the output file name is randomly chosen using
-@var{tempbase}. Otherwise the output file name is chosen completely
-at random.
-@end enumerate
-
-@var{errname} is the file name to use for standard error output. If
-it is @code{NULL}, standard error is the same as the caller's.
-Otherwise, standard error is written to the named file.
-
-On an error return, the code sets @code{*@var{err}} to an @code{errno}
-value, or to 0 if there is no relevant @code{errno}.
-
-@end deftypefn
-
-@c pexecute.txh:145
-@deftypefn Extension {const char *} pex_run_in_environment (struct pex_obj *@var{obj}, @
- int @var{flags}, const char *@var{executable}, char * const *@var{argv}, @
- char * const *@var{env}, int @var{env_size}, const char *@var{outname}, @
- const char *@var{errname}, int *@var{err})
-
-Execute one program in a pipeline, permitting the environment for the
-program to be specified. Behaviour and parameters not listed below are
-as for @code{pex_run}.
-
-@var{env} is the environment for the child process, specified as an array of
-character pointers. Each element of the array should point to a string of the
-form @code{VAR=VALUE}, with the exception of the last element that must be
-@code{NULL}.
-
-@end deftypefn
-
-@c pexecute.txh:301
-@deftypefn Extension int pexecute (const char *@var{program}, @
- char * const *@var{argv}, const char *@var{this_pname}, @
- const char *@var{temp_base}, char **@var{errmsg_fmt}, @
- char **@var{errmsg_arg}, int @var{flags})
-
-This is the old interface to execute one or more programs. It is
-still supported for compatibility purposes, but is no longer
-documented.
-
-@end deftypefn
-
-@c strsignal.c:541
-@deftypefn Supplemental void psignal (int @var{signo}, char *@var{message})
-
-Print @var{message} to the standard error, followed by a colon,
-followed by the description of the signal specified by @var{signo},
-followed by a newline.
-
-@end deftypefn
-
-@c putenv.c:21
-@deftypefn Supplemental int putenv (const char *@var{string})
-
-Uses @code{setenv} or @code{unsetenv} to put @var{string} into
-the environment or remove it. If @var{string} is of the form
-@samp{name=value} the string is added; if no @samp{=} is present the
-name is unset/removed.
-
-@end deftypefn
-
-@c pexecute.txh:312
-@deftypefn Extension int pwait (int @var{pid}, int *@var{status}, int @var{flags})
-
-Another part of the old execution interface.
-
-@end deftypefn
-
-@c random.c:39
-@deftypefn Supplement {long int} random (void)
-@deftypefnx Supplement void srandom (unsigned int @var{seed})
-@deftypefnx Supplement void* initstate (unsigned int @var{seed}, @
- void *@var{arg_state}, unsigned long @var{n})
-@deftypefnx Supplement void* setstate (void *@var{arg_state})
-
-Random number functions. @code{random} returns a random number in the
-range 0 to @code{LONG_MAX}. @code{srandom} initializes the random
-number generator to some starting point determined by @var{seed}
-(else, the values returned by @code{random} are always the same for each
-run of the program). @code{initstate} and @code{setstate} allow fine-grained
-control over the state of the random number generator.
-
-@end deftypefn
-
-@c concat.c:160
-@deftypefn Extension char* reconcat (char *@var{optr}, const char *@var{s1}, @
- @dots{}, @code{NULL})
-
-Same as @code{concat}, except that if @var{optr} is not @code{NULL} it
-is freed after the string is created. This is intended to be useful
-when you're extending an existing string or building up a string in a
-loop:
-
-@example
- str = reconcat (str, "pre-", str, NULL);
-@end example
-
-@end deftypefn
-
-@c rename.c:6
-@deftypefn Supplemental int rename (const char *@var{old}, const char *@var{new})
-
-Renames a file from @var{old} to @var{new}. If @var{new} already
-exists, it is removed.
-
-@end deftypefn
-
-@c rindex.c:5
-@deftypefn Supplemental char* rindex (const char *@var{s}, int @var{c})
-
-Returns a pointer to the last occurrence of the character @var{c} in
-the string @var{s}, or @code{NULL} if not found. The use of @code{rindex} is
-deprecated in new programs in favor of @code{strrchr}.
-
-@end deftypefn
-
-@c setenv.c:22
-@deftypefn Supplemental int setenv (const char *@var{name}, @
- const char *@var{value}, int @var{overwrite})
-@deftypefnx Supplemental void unsetenv (const char *@var{name})
-
-@code{setenv} adds @var{name} to the environment with value
-@var{value}. If the name was already present in the environment,
-the new value will be stored only if @var{overwrite} is nonzero.
-The companion @code{unsetenv} function removes @var{name} from the
-environment. This implementation is not safe for multithreaded code.
-
-@end deftypefn
-
-@c setproctitle.c:31
-@deftypefn Supplemental void setproctitle (const char *@var{fmt}, ...)
-
-Set the title of a process to @var{fmt}. va args not supported for now,
-but defined for compatibility with BSD.
-
-@end deftypefn
-
-@c strsignal.c:348
-@deftypefn Extension int signo_max (void)
-
-Returns the maximum signal value for which a corresponding symbolic
-name or message is available. Note that in the case where we use the
-@code{sys_siglist} supplied by the system, it is possible for there to
-be more symbolic names than messages, or vice versa. In fact, the
-manual page for @code{psignal(3b)} explicitly warns that one should
-check the size of the table (@code{NSIG}) before indexing it, since
-new signal codes may be added to the system before they are added to
-the table. Thus @code{NSIG} might be smaller than value implied by
-the largest signo value defined in @code{<signal.h>}.
-
-We return the maximum value that can be used to obtain a meaningful
-symbolic name or message.
-
-@end deftypefn
-
-@c sigsetmask.c:8
-@deftypefn Supplemental int sigsetmask (int @var{set})
-
-Sets the signal mask to the one provided in @var{set} and returns
-the old mask (which, for libiberty's implementation, will always
-be the value @code{1}).
-
-@end deftypefn
-
-@c simple-object.txh:96
-@deftypefn Extension {const char *} simple_object_attributes_compare @
- (simple_object_attributes *@var{attrs1}, simple_object_attributes *@var{attrs2}, @
- int *@var{err})
-
-Compare @var{attrs1} and @var{attrs2}. If they could be linked
-together without error, return @code{NULL}. Otherwise, return an
-error message and set @code{*@var{err}} to an errno value or @code{0}
-if there is no relevant errno.
-
-@end deftypefn
-
-@c simple-object.txh:81
-@deftypefn Extension {simple_object_attributes *} simple_object_fetch_attributes @
- (simple_object_read *@var{simple_object}, const char **@var{errmsg}, int *@var{err})
-
-Fetch the attributes of @var{simple_object}. The attributes are
-internal information such as the format of the object file, or the
-architecture it was compiled for. This information will persist until
-@code{simple_object_attributes_release} is called, even if
-@var{simple_object} itself is released.
-
-On error this returns @code{NULL}, sets @code{*@var{errmsg}} to an
-error message, and sets @code{*@var{err}} to an errno value or
-@code{0} if there is no relevant errno.
-
-@end deftypefn
-
-@c simple-object.txh:49
-@deftypefn Extension {int} simple_object_find_section @
- (simple_object_read *@var{simple_object} off_t *@var{offset}, @
- off_t *@var{length}, const char **@var{errmsg}, int *@var{err})
-
-Look for the section @var{name} in @var{simple_object}. This returns
-information for the first section with that name.
-
-If found, return 1 and set @code{*@var{offset}} to the offset in the
-file of the section contents and set @code{*@var{length}} to the
-length of the section contents. The value in @code{*@var{offset}}
-will be relative to the offset passed to
-@code{simple_object_open_read}.
-
-If the section is not found, and no error occurs,
-@code{simple_object_find_section} returns @code{0} and set
-@code{*@var{errmsg}} to @code{NULL}.
-
-If an error occurs, @code{simple_object_find_section} returns
-@code{0}, sets @code{*@var{errmsg}} to an error message, and sets
-@code{*@var{err}} to an errno value or @code{0} if there is no
-relevant errno.
-
-@end deftypefn
-
-@c simple-object.txh:27
-@deftypefn Extension {const char *} simple_object_find_sections @
- (simple_object_read *@var{simple_object}, int (*@var{pfn}) (void *@var{data}, @
- const char *@var{name}, off_t @var{offset}, off_t @var{length}), @
- void *@var{data}, int *@var{err})
-
-This function calls @var{pfn} for each section in @var{simple_object}.
-It calls @var{pfn} with the section name, the offset within the file
-of the section contents, and the length of the section contents. The
-offset within the file is relative to the offset passed to
-@code{simple_object_open_read}. The @var{data} argument to this
-function is passed along to @var{pfn}.
-
-If @var{pfn} returns @code{0}, the loop over the sections stops and
-@code{simple_object_find_sections} returns. If @var{pfn} returns some
-other value, the loop continues.
-
-On success @code{simple_object_find_sections} returns. On error it
-returns an error string, and sets @code{*@var{err}} to an errno value
-or @code{0} if there is no relevant errno.
-
-@end deftypefn
-
-@c simple-object.txh:2
-@deftypefn Extension {simple_object_read *} simple_object_open_read @
- (int @var{descriptor}, off_t @var{offset}, const char *{segment_name}, @
- const char **@var{errmsg}, int *@var{err})
-
-Opens an object file for reading. Creates and returns an
-@code{simple_object_read} pointer which may be passed to other
-functions to extract data from the object file.
-
-@var{descriptor} holds a file descriptor which permits reading.
-
-@var{offset} is the offset into the file; this will be @code{0} in the
-normal case, but may be a different value when reading an object file
-in an archive file.
-
-@var{segment_name} is only used with the Mach-O file format used on
-Darwin aka Mac OS X. It is required on that platform, and means to
-only look at sections within the segment with that name. The
-parameter is ignored on other systems.
-
-If an error occurs, this functions returns @code{NULL} and sets
-@code{*@var{errmsg}} to an error string and sets @code{*@var{err}} to
-an errno value or @code{0} if there is no relevant errno.
-
-@end deftypefn
-
-@c simple-object.txh:107
-@deftypefn Extension {void} simple_object_release_attributes @
- (simple_object_attributes *@var{attrs})
-
-Release all resources associated with @var{attrs}.
-
-@end deftypefn
-
-@c simple-object.txh:73
-@deftypefn Extension {void} simple_object_release_read @
- (simple_object_read *@var{simple_object})
-
-Release all resources associated with @var{simple_object}. This does
-not close the file descriptor.
-
-@end deftypefn
-
-@c simple-object.txh:184
-@deftypefn Extension {void} simple_object_release_write @
- (simple_object_write *@var{simple_object})
-
-Release all resources associated with @var{simple_object}.
-
-@end deftypefn
-
-@c simple-object.txh:114
-@deftypefn Extension {simple_object_write *} simple_object_start_write @
- (simple_object_attributes @var{attrs}, const char *@var{segment_name}, @
- const char **@var{errmsg}, int *@var{err})
-
-Start creating a new object file using the object file format
-described in @var{attrs}. You must fetch attribute information from
-an existing object file before you can create a new one. There is
-currently no support for creating an object file de novo.
-
-@var{segment_name} is only used with Mach-O as found on Darwin aka Mac
-OS X. The parameter is required on that target. It means that all
-sections are created within the named segment. It is ignored for
-other object file formats.
-
-On error @code{simple_object_start_write} returns @code{NULL}, sets
-@code{*@var{ERRMSG}} to an error message, and sets @code{*@var{err}}
-to an errno value or @code{0} if there is no relevant errno.
-
-@end deftypefn
-
-@c simple-object.txh:153
-@deftypefn Extension {const char *} simple_object_write_add_data @
- (simple_object_write *@var{simple_object}, @
- simple_object_write_section *@var{section}, const void *@var{buffer}, @
- size_t @var{size}, int @var{copy}, int *@var{err})
-
-Add data @var{buffer}/@var{size} to @var{section} in
-@var{simple_object}. If @var{copy} is non-zero, the data will be
-copied into memory if necessary. If @var{copy} is zero, @var{buffer}
-must persist until @code{simple_object_write_to_file} is called. is
-released.
-
-On success this returns @code{NULL}. On error this returns an error
-message, and sets @code{*@var{err}} to an errno value or 0 if there is
-no relevant erro.
-
-@end deftypefn
-
-@c simple-object.txh:134
-@deftypefn Extension {simple_object_write_section *} simple_object_write_create_section @
- (simple_object_write *@var{simple_object}, const char *@var{name}, @
- unsigned int @var{align}, const char **@var{errmsg}, int *@var{err})
-
-Add a section to @var{simple_object}. @var{name} is the name of the
-new section. @var{align} is the required alignment expressed as the
-number of required low-order 0 bits (e.g., 2 for alignment to a 32-bit
-boundary).
-
-The section is created as containing data, readable, not writable, not
-executable, not loaded at runtime. The section is not written to the
-file until @code{simple_object_write_to_file} is called.
-
-On error this returns @code{NULL}, sets @code{*@var{errmsg}} to an
-error message, and sets @code{*@var{err}} to an errno value or
-@code{0} if there is no relevant errno.
-
-@end deftypefn
-
-@c simple-object.txh:170
-@deftypefn Extension {const char *} simple_object_write_to_file @
- (simple_object_write *@var{simple_object}, int @var{descriptor}, int *@var{err})
-
-Write the complete object file to @var{descriptor}, an open file
-descriptor. This writes out all the data accumulated by calls to
-@code{simple_object_write_create_section} and
-@var{simple_object_write_add_data}.
-
-This returns @code{NULL} on success. On error this returns an error
-message and sets @code{*@var{err}} to an errno value or @code{0} if
-there is no relevant errno.
-
-@end deftypefn
-
-@c snprintf.c:28
-@deftypefn Supplemental int snprintf (char *@var{buf}, size_t @var{n}, @
- const char *@var{format}, ...)
-
-This function is similar to @code{sprintf}, but it will write to
-@var{buf} at most @code{@var{n}-1} bytes of text, followed by a
-terminating null byte, for a total of @var{n} bytes.
-On error the return value is -1, otherwise it returns the number of
-bytes, not including the terminating null byte, that would have been
-written had @var{n} been sufficiently large, regardless of the actual
-value of @var{n}. Note some pre-C99 system libraries do not implement
-this correctly so users cannot generally rely on the return value if
-the system version of this function is used.
-
-@end deftypefn
-
-@c spaces.c:22
-@deftypefn Extension char* spaces (int @var{count})
-
-Returns a pointer to a memory region filled with the specified
-number of spaces and null terminated. The returned pointer is
-valid until at least the next call.
-
-@end deftypefn
-
-@c splay-tree.c:305
-@deftypefn Supplemental splay_tree splay_tree_new_with_typed_alloc @
-(splay_tree_compare_fn @var{compare_fn}, @
-splay_tree_delete_key_fn @var{delete_key_fn}, @
-splay_tree_delete_value_fn @var{delete_value_fn}, @
-splay_tree_allocate_fn @var{tree_allocate_fn}, @
-splay_tree_allocate_fn @var{node_allocate_fn}, @
-splay_tree_deallocate_fn @var{deallocate_fn}, @
-void * @var{allocate_data})
-
-This function creates a splay tree that uses two different allocators
-@var{tree_allocate_fn} and @var{node_allocate_fn} to use for allocating the
-tree itself and its nodes respectively. This is useful when variables of
-different types need to be allocated with different allocators.
-
-The splay tree will use @var{compare_fn} to compare nodes,
-@var{delete_key_fn} to deallocate keys, and @var{delete_value_fn} to
-deallocate values. Keys and values will be deallocated when the
-tree is deleted using splay_tree_delete or when a node is removed
-using splay_tree_remove. splay_tree_insert will release the previously
-inserted key and value using @var{delete_key_fn} and @var{delete_value_fn}
-if the inserted key is already found in the tree.
-
-@end deftypefn
-
-@c stack-limit.c:28
-@deftypefn Extension void stack_limit_increase (unsigned long @var{pref})
-
-Attempt to increase stack size limit to @var{pref} bytes if possible.
-
-@end deftypefn
-
-@c stpcpy.c:23
-@deftypefn Supplemental char* stpcpy (char *@var{dst}, const char *@var{src})
-
-Copies the string @var{src} into @var{dst}. Returns a pointer to
-@var{dst} + strlen(@var{src}).
-
-@end deftypefn
-
-@c stpncpy.c:23
-@deftypefn Supplemental char* stpncpy (char *@var{dst}, const char *@var{src}, @
- size_t @var{len})
-
-Copies the string @var{src} into @var{dst}, copying exactly @var{len}
-and padding with zeros if necessary. If @var{len} < strlen(@var{src})
-then return @var{dst} + @var{len}, otherwise returns @var{dst} +
-strlen(@var{src}).
-
-@end deftypefn
-
-@c strcasecmp.c:15
-@deftypefn Supplemental int strcasecmp (const char *@var{s1}, const char *@var{s2})
-
-A case-insensitive @code{strcmp}.
-
-@end deftypefn
-
-@c strchr.c:6
-@deftypefn Supplemental char* strchr (const char *@var{s}, int @var{c})
-
-Returns a pointer to the first occurrence of the character @var{c} in
-the string @var{s}, or @code{NULL} if not found. If @var{c} is itself the
-null character, the results are undefined.
-
-@end deftypefn
-
-@c strdup.c:3
-@deftypefn Supplemental char* strdup (const char *@var{s})
-
-Returns a pointer to a copy of @var{s} in memory obtained from
-@code{malloc}, or @code{NULL} if insufficient memory was available.
-
-@end deftypefn
-
-@c strerror.c:675
-@deftypefn Replacement {const char*} strerrno (int @var{errnum})
-
-Given an error number returned from a system call (typically returned
-in @code{errno}), returns a pointer to a string containing the
-symbolic name of that error number, as found in @code{<errno.h>}.
-
-If the supplied error number is within the valid range of indices for
-symbolic names, but no name is available for the particular error
-number, then returns the string @samp{Error @var{num}}, where @var{num}
-is the error number.
-
-If the supplied error number is not within the range of valid
-indices, then returns @code{NULL}.
-
-The contents of the location pointed to are only guaranteed to be
-valid until the next call to @code{strerrno}.
-
-@end deftypefn
-
-@c strerror.c:608
-@deftypefn Supplemental char* strerror (int @var{errnoval})
-
-Maps an @code{errno} number to an error message string, the contents
-of which are implementation defined. On systems which have the
-external variables @code{sys_nerr} and @code{sys_errlist}, these
-strings will be the same as the ones used by @code{perror}.
-
-If the supplied error number is within the valid range of indices for
-the @code{sys_errlist}, but no message is available for the particular
-error number, then returns the string @samp{Error @var{num}}, where
-@var{num} is the error number.
-
-If the supplied error number is not a valid index into
-@code{sys_errlist}, returns @code{NULL}.
-
-The returned string is only guaranteed to be valid only until the
-next call to @code{strerror}.
-
-@end deftypefn
-
-@c strncasecmp.c:15
-@deftypefn Supplemental int strncasecmp (const char *@var{s1}, const char *@var{s2})
-
-A case-insensitive @code{strncmp}.
-
-@end deftypefn
-
-@c strncmp.c:6
-@deftypefn Supplemental int strncmp (const char *@var{s1}, @
- const char *@var{s2}, size_t @var{n})
-
-Compares the first @var{n} bytes of two strings, returning a value as
-@code{strcmp}.
-
-@end deftypefn
-
-@c strndup.c:23
-@deftypefn Extension char* strndup (const char *@var{s}, size_t @var{n})
-
-Returns a pointer to a copy of @var{s} with at most @var{n} characters
-in memory obtained from @code{malloc}, or @code{NULL} if insufficient
-memory was available. The result is always NUL terminated.
-
-@end deftypefn
-
-@c strnlen.c:6
-@deftypefn Supplemental size_t strnlen (const char *@var{s}, size_t @var{maxlen})
-
-Returns the length of @var{s}, as with @code{strlen}, but never looks
-past the first @var{maxlen} characters in the string. If there is no
-'\0' character in the first @var{maxlen} characters, returns
-@var{maxlen}.
-
-@end deftypefn
-
-@c strrchr.c:6
-@deftypefn Supplemental char* strrchr (const char *@var{s}, int @var{c})
-
-Returns a pointer to the last occurrence of the character @var{c} in
-the string @var{s}, or @code{NULL} if not found. If @var{c} is itself the
-null character, the results are undefined.
-
-@end deftypefn
-
-@c strsignal.c:383
-@deftypefn Supplemental {const char *} strsignal (int @var{signo})
-
-Maps an signal number to an signal message string, the contents of
-which are implementation defined. On systems which have the external
-variable @code{sys_siglist}, these strings will be the same as the
-ones used by @code{psignal()}.
-
-If the supplied signal number is within the valid range of indices for
-the @code{sys_siglist}, but no message is available for the particular
-signal number, then returns the string @samp{Signal @var{num}}, where
-@var{num} is the signal number.
-
-If the supplied signal number is not a valid index into
-@code{sys_siglist}, returns @code{NULL}.
-
-The returned string is only guaranteed to be valid only until the next
-call to @code{strsignal}.
-
-@end deftypefn
-
-@c strsignal.c:448
-@deftypefn Extension {const char*} strsigno (int @var{signo})
-
-Given an signal number, returns a pointer to a string containing the
-symbolic name of that signal number, as found in @code{<signal.h>}.
-
-If the supplied signal number is within the valid range of indices for
-symbolic names, but no name is available for the particular signal
-number, then returns the string @samp{Signal @var{num}}, where
-@var{num} is the signal number.
-
-If the supplied signal number is not within the range of valid
-indices, then returns @code{NULL}.
-
-The contents of the location pointed to are only guaranteed to be
-valid until the next call to @code{strsigno}.
-
-@end deftypefn
-
-@c strstr.c:6
-@deftypefn Supplemental char* strstr (const char *@var{string}, const char *@var{sub})
-
-This function searches for the substring @var{sub} in the string
-@var{string}, not including the terminating null characters. A pointer
-to the first occurrence of @var{sub} is returned, or @code{NULL} if the
-substring is absent. If @var{sub} points to a string with zero
-length, the function returns @var{string}.
-
-@end deftypefn
-
-@c strtod.c:27
-@deftypefn Supplemental double strtod (const char *@var{string}, @
- char **@var{endptr})
-
-This ISO C function converts the initial portion of @var{string} to a
-@code{double}. If @var{endptr} is not @code{NULL}, a pointer to the
-character after the last character used in the conversion is stored in
-the location referenced by @var{endptr}. If no conversion is
-performed, zero is returned and the value of @var{string} is stored in
-the location referenced by @var{endptr}.
-
-@end deftypefn
-
-@c strerror.c:734
-@deftypefn Extension int strtoerrno (const char *@var{name})
-
-Given the symbolic name of a error number (e.g., @code{EACCES}), map it
-to an errno value. If no translation is found, returns 0.
-
-@end deftypefn
-
-@c strtol.c:33
-@deftypefn Supplemental {long int} strtol (const char *@var{string}, @
- char **@var{endptr}, int @var{base})
-@deftypefnx Supplemental {unsigned long int} strtoul (const char *@var{string}, @
- char **@var{endptr}, int @var{base})
-
-The @code{strtol} function converts the string in @var{string} to a
-long integer value according to the given @var{base}, which must be
-between 2 and 36 inclusive, or be the special value 0. If @var{base}
-is 0, @code{strtol} will look for the prefixes @code{0} and @code{0x}
-to indicate bases 8 and 16, respectively, else default to base 10.
-When the base is 16 (either explicitly or implicitly), a prefix of
-@code{0x} is allowed. The handling of @var{endptr} is as that of
-@code{strtod} above. The @code{strtoul} function is the same, except
-that the converted value is unsigned.
-
-@end deftypefn
-
-@c strtoll.c:33
-@deftypefn Supplemental {long long int} strtoll (const char *@var{string}, @
- char **@var{endptr}, int @var{base})
-@deftypefnx Supplemental {unsigned long long int} strtoull (@
- const char *@var{string}, char **@var{endptr}, int @var{base})
-
-The @code{strtoll} function converts the string in @var{string} to a
-long long integer value according to the given @var{base}, which must be
-between 2 and 36 inclusive, or be the special value 0. If @var{base}
-is 0, @code{strtoll} will look for the prefixes @code{0} and @code{0x}
-to indicate bases 8 and 16, respectively, else default to base 10.
-When the base is 16 (either explicitly or implicitly), a prefix of
-@code{0x} is allowed. The handling of @var{endptr} is as that of
-@code{strtod} above. The @code{strtoull} function is the same, except
-that the converted value is unsigned.
-
-@end deftypefn
-
-@c strsignal.c:502
-@deftypefn Extension int strtosigno (const char *@var{name})
-
-Given the symbolic name of a signal, map it to a signal number. If no
-translation is found, returns 0.
-
-@end deftypefn
-
-@c strverscmp.c:25
-@deftypefun int strverscmp (const char *@var{s1}, const char *@var{s2})
-The @code{strverscmp} function compares the string @var{s1} against
-@var{s2}, considering them as holding indices/version numbers. Return
-value follows the same conventions as found in the @code{strverscmp}
-function. In fact, if @var{s1} and @var{s2} contain no digits,
-@code{strverscmp} behaves like @code{strcmp}.
-
-Basically, we compare strings normally (character by character), until
-we find a digit in each string - then we enter a special comparison
-mode, where each sequence of digits is taken as a whole. If we reach the
-end of these two parts without noticing a difference, we return to the
-standard comparison mode. There are two types of numeric parts:
-"integral" and "fractional" (those begin with a '0'). The types
-of the numeric parts affect the way we sort them:
-
-@itemize @bullet
-@item
-integral/integral: we compare values as you would expect.
-
-@item
-fractional/integral: the fractional part is less than the integral one.
-Again, no surprise.
-
-@item
-fractional/fractional: the things become a bit more complex.
-If the common prefix contains only leading zeroes, the longest part is less
-than the other one; else the comparison behaves normally.
-@end itemize
-
-@smallexample
-strverscmp ("no digit", "no digit")
- @result{} 0 // @r{same behavior as strcmp.}
-strverscmp ("item#99", "item#100")
- @result{} <0 // @r{same prefix, but 99 < 100.}
-strverscmp ("alpha1", "alpha001")
- @result{} >0 // @r{fractional part inferior to integral one.}
-strverscmp ("part1_f012", "part1_f01")
- @result{} >0 // @r{two fractional parts.}
-strverscmp ("foo.009", "foo.0")
- @result{} <0 // @r{idem, but with leading zeroes only.}
-@end smallexample
-
-This function is especially useful when dealing with filename sorting,
-because filenames frequently hold indices/version numbers.
-@end deftypefun
-
-@c timeval-utils.c:43
-@deftypefn Extension void timeval_add (struct timeval *@var{a}, @
- struct timeval *@var{b}, struct timeval *@var{result})
-
-Adds @var{a} to @var{b} and stores the result in @var{result}.
-
-@end deftypefn
-
-@c timeval-utils.c:67
-@deftypefn Extension void timeval_sub (struct timeval *@var{a}, @
- struct timeval *@var{b}, struct timeval *@var{result})
-
-Subtracts @var{b} from @var{a} and stores the result in @var{result}.
-
-@end deftypefn
-
-@c tmpnam.c:3
-@deftypefn Supplemental char* tmpnam (char *@var{s})
-
-This function attempts to create a name for a temporary file, which
-will be a valid file name yet not exist when @code{tmpnam} checks for
-it. @var{s} must point to a buffer of at least @code{L_tmpnam} bytes,
-or be @code{NULL}. Use of this function creates a security risk, and it must
-not be used in new projects. Use @code{mkstemp} instead.
-
-@end deftypefn
-
-@c unlink-if-ordinary.c:27
-@deftypefn Supplemental int unlink_if_ordinary (const char*)
-
-Unlinks the named file, unless it is special (e.g. a device file).
-Returns 0 when the file was unlinked, a negative value (and errno set) when
-there was an error deleting the file, and a positive value if no attempt
-was made to unlink the file because it is special.
-
-@end deftypefn
-
-@c fopen_unlocked.c:31
-@deftypefn Extension void unlock_std_streams (void)
-
-If the OS supports it, ensure that the standard I/O streams,
-@code{stdin}, @code{stdout} and @code{stderr} are setup to avoid any
-multi-threaded locking. Otherwise do nothing.
-
-@end deftypefn
-
-@c fopen_unlocked.c:23
-@deftypefn Extension void unlock_stream (FILE * @var{stream})
-
-If the OS supports it, ensure that the supplied stream is setup to
-avoid any multi-threaded locking. Otherwise leave the @code{FILE}
-pointer unchanged. If the @var{stream} is @code{NULL} do nothing.
-
-@end deftypefn
-
-@c vasprintf.c:47
-@deftypefn Extension int vasprintf (char **@var{resptr}, @
- const char *@var{format}, va_list @var{args})
-
-Like @code{vsprintf}, but instead of passing a pointer to a buffer,
-you pass a pointer to a pointer. This function will compute the size
-of the buffer needed, allocate memory with @code{malloc}, and store a
-pointer to the allocated memory in @code{*@var{resptr}}. The value
-returned is the same as @code{vsprintf} would return. If memory could
-not be allocated, minus one is returned and @code{NULL} is stored in
-@code{*@var{resptr}}.
-
-@end deftypefn
-
-@c vfork.c:6
-@deftypefn Supplemental int vfork (void)
-
-Emulates @code{vfork} by calling @code{fork} and returning its value.
-
-@end deftypefn
-
-@c vprintf.c:3
-@deftypefn Supplemental int vprintf (const char *@var{format}, va_list @var{ap})
-@deftypefnx Supplemental int vfprintf (FILE *@var{stream}, @
- const char *@var{format}, va_list @var{ap})
-@deftypefnx Supplemental int vsprintf (char *@var{str}, @
- const char *@var{format}, va_list @var{ap})
-
-These functions are the same as @code{printf}, @code{fprintf}, and
-@code{sprintf}, respectively, except that they are called with a
-@code{va_list} instead of a variable number of arguments. Note that
-they do not call @code{va_end}; this is the application's
-responsibility. In @libib{} they are implemented in terms of the
-nonstandard but common function @code{_doprnt}.
-
-@end deftypefn
-
-@c vsnprintf.c:28
-@deftypefn Supplemental int vsnprintf (char *@var{buf}, size_t @var{n}, @
- const char *@var{format}, va_list @var{ap})
-
-This function is similar to @code{vsprintf}, but it will write to
-@var{buf} at most @code{@var{n}-1} bytes of text, followed by a
-terminating null byte, for a total of @var{n} bytes. On error the
-return value is -1, otherwise it returns the number of characters that
-would have been printed had @var{n} been sufficiently large,
-regardless of the actual value of @var{n}. Note some pre-C99 system
-libraries do not implement this correctly so users cannot generally
-rely on the return value if the system version of this function is
-used.
-
-@end deftypefn
-
-@c waitpid.c:3
-@deftypefn Supplemental int waitpid (int @var{pid}, int *@var{status}, int)
-
-This is a wrapper around the @code{wait} function. Any ``special''
-values of @var{pid} depend on your implementation of @code{wait}, as
-does the return value. The third argument is unused in @libib{}.
-
-@end deftypefn
-
-@c argv.c:289
-@deftypefn Extension int writeargv (char * const *@var{argv}, FILE *@var{file})
-
-Write each member of ARGV, handling all necessary quoting, to the file
-named by FILE, separated by whitespace. Return 0 on success, non-zero
-if an error occurred while writing to FILE.
-
-@end deftypefn
-
-@c xasprintf.c:31
-@deftypefn Replacement char* xasprintf (const char *@var{format}, ...)
-
-Print to allocated string without fail. If @code{xasprintf} fails,
-this will print a message to @code{stderr} (using the name set by
-@code{xmalloc_set_program_name}, if any) and then call @code{xexit}.
-
-@end deftypefn
-
-@c xatexit.c:11
-@deftypefun int xatexit (void (*@var{fn}) (void))
-
-Behaves as the standard @code{atexit} function, but with no limit on
-the number of registered functions. Returns 0 on success, or @minus{}1 on
-failure. If you use @code{xatexit} to register functions, you must use
-@code{xexit} to terminate your program.
-
-@end deftypefun
-
-@c xmalloc.c:38
-@deftypefn Replacement void* xcalloc (size_t @var{nelem}, size_t @var{elsize})
-
-Allocate memory without fail, and set it to zero. This routine functions
-like @code{calloc}, but will behave the same as @code{xmalloc} if memory
-cannot be found.
-
-@end deftypefn
-
-@c xexit.c:22
-@deftypefn Replacement void xexit (int @var{code})
-
-Terminates the program. If any functions have been registered with
-the @code{xatexit} replacement function, they will be called first.
-Termination is handled via the system's normal @code{exit} call.
-
-@end deftypefn
-
-@c xmalloc.c:22
-@deftypefn Replacement void* xmalloc (size_t)
-
-Allocate memory without fail. If @code{malloc} fails, this will print
-a message to @code{stderr} (using the name set by
-@code{xmalloc_set_program_name},
-if any) and then call @code{xexit}. Note that it is therefore safe for
-a program to contain @code{#define malloc xmalloc} in its source.
-
-@end deftypefn
-
-@c xmalloc.c:53
-@deftypefn Replacement void xmalloc_failed (size_t)
-
-This function is not meant to be called by client code, and is listed
-here for completeness only. If any of the allocation routines fail, this
-function will be called to print an error message and terminate execution.
-
-@end deftypefn
-
-@c xmalloc.c:46
-@deftypefn Replacement void xmalloc_set_program_name (const char *@var{name})
-
-You can use this to set the name of the program used by
-@code{xmalloc_failed} when printing a failure message.
-
-@end deftypefn
-
-@c xmemdup.c:7
-@deftypefn Replacement void* xmemdup (void *@var{input}, @
- size_t @var{copy_size}, size_t @var{alloc_size})
-
-Duplicates a region of memory without fail. First, @var{alloc_size} bytes
-are allocated, then @var{copy_size} bytes from @var{input} are copied into
-it, and the new memory is returned. If fewer bytes are copied than were
-allocated, the remaining memory is zeroed.
-
-@end deftypefn
-
-@c xmalloc.c:32
-@deftypefn Replacement void* xrealloc (void *@var{ptr}, size_t @var{size})
-Reallocate memory without fail. This routine functions like @code{realloc},
-but will behave the same as @code{xmalloc} if memory cannot be found.
-
-@end deftypefn
-
-@c xstrdup.c:7
-@deftypefn Replacement char* xstrdup (const char *@var{s})
-
-Duplicates a character string without fail, using @code{xmalloc} to
-obtain memory.
-
-@end deftypefn
-
-@c xstrerror.c:7
-@deftypefn Replacement char* xstrerror (int @var{errnum})
-
-Behaves exactly like the standard @code{strerror} function, but
-will never return a @code{NULL} pointer.
-
-@end deftypefn
-
-@c xstrndup.c:23
-@deftypefn Replacement char* xstrndup (const char *@var{s}, size_t @var{n})
-
-Returns a pointer to a copy of @var{s} with at most @var{n} characters
-without fail, using @code{xmalloc} to obtain memory. The result is
-always NUL terminated.
-
-@end deftypefn
-
-@c xvasprintf.c:38
-@deftypefn Replacement char* xvasprintf (const char *@var{format}, va_list @var{args})
-
-Print to allocated string without fail. If @code{xvasprintf} fails,
-this will print a message to @code{stderr} (using the name set by
-@code{xmalloc_set_program_name}, if any) and then call @code{xexit}.
-
-@end deftypefn
-
-
+++ /dev/null
-\input texinfo @c -*-texinfo-*-
-@c %**start of header
-@setfilename libiberty.info
-@settitle @sc{gnu} libiberty
-@c %**end of header
-
-@syncodeindex fn cp
-@syncodeindex vr cp
-@syncodeindex pg cp
-
-@finalout
-@c %**end of header
-
-@dircategory GNU libraries
-@direntry
-* Libiberty: (libiberty). Library of utility functions which
- are missing or broken on some systems.
-@end direntry
-
-@macro libib
-@code{libiberty}
-@end macro
-
-@ifinfo
-This manual describes the GNU @libib library of utility subroutines.
-
-Copyright @copyright{} 2001-2022 Free Software Foundation, Inc.
-
- 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 no Front-Cover Texts, and with no
- Back-Cover Texts. A copy of the license is included in the
- section entitled ``GNU Free Documentation License''.
-
-@ignore
-Permission is granted to process this file through TeX and print the
-results, provided the printed document carries a copying permission
-notice identical to this one except for the removal of this paragraph
-(this paragraph not being relevant to the printed manual).
-
-@end ignore
-@end ifinfo
-
-
-@titlepage
-@title @sc{gnu} libiberty
-@author Phil Edwards et al.
-@page
-
-
-@vskip 0pt plus 1filll
-Copyright @copyright{} 2001-2022 Free Software Foundation, Inc.
-
- 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 no Front-Cover Texts, and with no
- Back-Cover Texts. A copy of the license is included in the
- section entitled ``GNU Free Documentation License''.
-
-@end titlepage
-@contents
-@page
-
-@ifnottex
-@node Top,Using,,
-@top Introduction
-
-The @libib{} library is a collection of subroutines used by various
-GNU programs. It is available under the Library General Public
-License; for more information, see @ref{Library Copying}.
-
-@end ifnottex
-
-@menu
-* Using:: How to use libiberty in your code.
-
-* Overview:: Overview of available function groups.
-
-* Functions:: Available functions, macros, and global variables.
-
-* Licenses:: The various licenses under which libiberty sources are
- distributed.
-
-* Index:: Index of functions and categories.
-@end menu
-
-@node Using
-@chapter Using
-@cindex using libiberty
-@cindex libiberty usage
-@cindex how to use
-
-@c THIS SECTION IS CRAP AND NEEDS REWRITING BADLY.
-
-To date, @libib{} is generally not installed on its own. It has evolved
-over years but does not have its own version number nor release schedule.
-
-Possibly the easiest way to use @libib{} in your projects is to drop the
-@libib{} code into your project's sources, and to build the library along
-with your own sources; the library would then be linked in at the end. This
-prevents any possible version mismatches with other copies of libiberty
-elsewhere on the system.
-
-Passing @option{--enable-install-libiberty} to the @command{configure}
-script when building @libib{} causes the header files and archive library
-to be installed when @kbd{make install} is run. This option also takes
-an (optional) argument to specify the installation location, in the same
-manner as @option{--prefix}.
-
-For your own projects, an approach which offers stability and flexibility
-is to include @libib{} with your code, but allow the end user to optionally
-choose to use a previously-installed version instead. In this way the
-user may choose (for example) to install @libib{} as part of GCC, and use
-that version for all software built with that compiler. (This approach
-has proven useful with software using the GNU @code{readline} library.)
-
-Making use of @libib{} code usually requires that you include one or more
-header files from the @libib{} distribution. (They will be named as
-necessary in the function descriptions.) At link time, you will need to
-add @option{-liberty} to your link command invocation.
-
-
-@node Overview
-@chapter Overview
-
-Functions contained in @libib{} can be divided into three general categories.
-
-
-@menu
-* Supplemental Functions:: Providing functions which don't exist
- on older operating systems.
-
-* Replacement Functions:: These functions are sometimes buggy or
- unpredictable on some operating systems.
-
-* Extensions:: Functions which provide useful extensions
- or safety wrappers around existing code.
-@end menu
-
-@node Supplemental Functions
-@section Supplemental Functions
-@cindex supplemental functions
-@cindex functions, supplemental
-@cindex functions, missing
-
-Certain operating systems do not provide functions which have since
-become standardized, or at least common. For example, the Single
-Unix Specification Version 2 requires that the @code{basename}
-function be provided, but an OS which predates that specification
-might not have this function. This should not prevent well-written
-code from running on such a system.
-
-Similarly, some functions exist only among a particular ``flavor''
-or ``family'' of operating systems. As an example, the @code{bzero}
-function is often not present on systems outside the BSD-derived
-family of systems.
-
-Many such functions are provided in @libib{}. They are quickly
-listed here with little description, as systems which lack them
-become less and less common. Each function @var{foo} is implemented
-in @file{@var{foo}.c} but not declared in any @libib{} header file; more
-comments and caveats for each function's implementation are often
-available in the source file. Generally, the function can simply
-be declared as @code{extern}.
-
-
-
-@node Replacement Functions
-@section Replacement Functions
-@cindex replacement functions
-@cindex functions, replacement
-
-Some functions have extremely limited implementations on different
-platforms. Other functions are tedious to use correctly; for example,
-proper use of @code{malloc} calls for the return value to be checked and
-appropriate action taken if memory has been exhausted. A group of
-``replacement functions'' is available in @libib{} to address these issues
-for some of the most commonly used subroutines.
-
-All of these functions are declared in the @file{libiberty.h} header
-file. Many of the implementations will use preprocessor macros set by
-GNU Autoconf, if you decide to make use of that program. Some of these
-functions may call one another.
-
-
-@menu
-* Memory Allocation:: Testing and handling failed memory
- requests automatically.
-* Exit Handlers:: Calling routines on program exit.
-* Error Reporting:: Mapping errno and signal numbers to
- more useful string formats.
-@end menu
-
-@node Memory Allocation
-@subsection Memory Allocation
-@cindex memory allocation
-
-The functions beginning with the letter @samp{x} are wrappers around
-standard functions; the functions provided by the system environment
-are called and their results checked before the results are passed back
-to client code. If the standard functions fail, these wrappers will
-terminate the program. Thus, these versions can be used with impunity.
-
-
-@node Exit Handlers
-@subsection Exit Handlers
-@cindex exit handlers
-
-The existence and implementation of the @code{atexit} routine varies
-amongst the flavors of Unix. @libib{} provides an unvarying dependable
-implementation via @code{xatexit} and @code{xexit}.
-
-
-@node Error Reporting
-@subsection Error Reporting
-@cindex error reporting
-
-These are a set of routines to facilitate programming with the system
-@code{errno} interface. The @libib{} source file @file{strerror.c}
-contains a good deal of documentation for these functions.
-
-@c signal stuff
-
-
-@node Extensions
-@section Extensions
-@cindex extensions
-@cindex functions, extension
-
-@libib{} includes additional functionality above and beyond standard
-functions, which has proven generically useful in GNU programs, such as
-obstacks and regex. These functions are often copied from other
-projects as they gain popularity, and are included here to provide a
-central location from which to use, maintain, and distribute them.
-
-@menu
-* Obstacks:: Stacks of arbitrary objects.
-@end menu
-
-@c This is generated from the glibc manual using contrib/make-obstacks-texi.pl
-@include obstacks.texi
-
-@node Functions
-@chapter Function, Variable, and Macro Listing.
-@include functions.texi
-
-@node Licenses
-@appendix Licenses
-
-@menu
-
-* Library Copying:: The GNU Library General Public License
-* BSD:: Regents of the University of California
-
-@end menu
-
-@c This takes care of Library Copying. It is the copying-lib.texi from the
-@c GNU web site, with its @node line altered to make makeinfo shut up.
-@include copying-lib.texi
-
-@page
-@node BSD
-@appendixsec BSD
-
-Copyright @copyright{} 1990 Regents of the University of California.
-All rights reserved.
-
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions
-are met:
-
-@enumerate
-
-@item
-Redistributions of source code must retain the above copyright
-notice, this list of conditions and the following disclaimer.
-
-@item
-Redistributions in binary form must reproduce the above copyright
-notice, this list of conditions and the following disclaimer in the
-documentation and/or other materials provided with the distribution.
-
-@item
-[rescinded 22 July 1999]
-
-@item
-Neither the name of the University nor the names of its contributors
-may be used to endorse or promote products derived from this software
-without specific prior written permission.
-
-@end enumerate
-
-THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
-ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
-ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
-FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
-OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
-HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
-LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
-OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
-SUCH DAMAGE.
-
-@node Index
-@unnumbered Index
-
-@printindex cp
-
-@bye
-
+++ /dev/null
-@node Obstacks
-@subsection Obstacks
-@cindex obstacks
-
-An @dfn{obstack} is a pool of memory containing a stack of objects. You
-can create any number of separate obstacks, and then allocate objects in
-specified obstacks. Within each obstack, the last object allocated must
-always be the first one freed, but distinct obstacks are independent of
-each other.
-
-Aside from this one constraint of order of freeing, obstacks are totally
-general: an obstack can contain any number of objects of any size. They
-are implemented with macros, so allocation is usually very fast as long as
-the objects are usually small. And the only space overhead per object is
-the padding needed to start each object on a suitable boundary.
-
-@menu
-* Creating Obstacks:: How to declare an obstack in your program.
-* Preparing for Obstacks:: Preparations needed before you can
- use obstacks.
-* Allocation in an Obstack:: Allocating objects in an obstack.
-* Freeing Obstack Objects:: Freeing objects in an obstack.
-* Obstack Functions:: The obstack functions are really macros.
-* Growing Objects:: Making an object bigger by stages.
-* Extra Fast Growing:: Extra-high-efficiency (though more
- complicated) growing objects.
-* Status of an Obstack:: Inquiries about the status of an obstack.
-* Obstacks Data Alignment:: Controlling alignment of objects in obstacks.
-* Obstack Chunks:: How obstacks obtain and release chunks;
- efficiency considerations.
-* Summary of Obstacks::
-@end menu
-
-@node Creating Obstacks
-@subsubsection Creating Obstacks
-
-The utilities for manipulating obstacks are declared in the header
-file @file{obstack.h}.
-@pindex obstack.h
-
-@comment obstack.h
-@comment GNU
-@deftp {Data Type} {struct obstack}
-An obstack is represented by a data structure of type @code{struct
-obstack}. This structure has a small fixed size; it records the status
-of the obstack and how to find the space in which objects are allocated.
-It does not contain any of the objects themselves. You should not try
-to access the contents of the structure directly; use only the macros
-described in this chapter.
-@end deftp
-
-You can declare variables of type @code{struct obstack} and use them as
-obstacks, or you can allocate obstacks dynamically like any other kind
-of object. Dynamic allocation of obstacks allows your program to have a
-variable number of different stacks. (You can even allocate an
-obstack structure in another obstack, but this is rarely useful.)
-
-All the macros that work with obstacks require you to specify which
-obstack to use. You do this with a pointer of type @code{struct obstack
-*}. In the following, we often say ``an obstack'' when strictly
-speaking the object at hand is such a pointer.
-
-The objects in the obstack are packed into large blocks called
-@dfn{chunks}. The @code{struct obstack} structure points to a chain of
-the chunks currently in use.
-
-The obstack library obtains a new chunk whenever you allocate an object
-that won't fit in the previous chunk. Since the obstack library manages
-chunks automatically, you don't need to pay much attention to them, but
-you do need to supply a function which the obstack library should use to
-get a chunk. Usually you supply a function which uses @code{malloc}
-directly or indirectly. You must also supply a function to free a chunk.
-These matters are described in the following section.
-
-@node Preparing for Obstacks
-@subsubsection Preparing for Using Obstacks
-
-Each source file in which you plan to use obstacks
-must include the header file @file{obstack.h}, like this:
-
-@smallexample
-#include <obstack.h>
-@end smallexample
-
-@findex obstack_chunk_alloc
-@findex obstack_chunk_free
-Also, if the source file uses the macro @code{obstack_init}, it must
-declare or define two macros that will be called by the
-obstack library. One, @code{obstack_chunk_alloc}, is used to allocate
-the chunks of memory into which objects are packed. The other,
-@code{obstack_chunk_free}, is used to return chunks when the objects in
-them are freed. These macros should appear before any use of obstacks
-in the source file.
-
-Usually these are defined to use @code{malloc} via the intermediary
-@code{xmalloc} (@pxref{Unconstrained Allocation, , , libc, The GNU C Library Reference Manual}). This is done with
-the following pair of macro definitions:
-
-@smallexample
-#define obstack_chunk_alloc xmalloc
-#define obstack_chunk_free free
-@end smallexample
-
-@noindent
-Though the memory you get using obstacks really comes from @code{malloc},
-using obstacks is faster because @code{malloc} is called less often, for
-larger blocks of memory. @xref{Obstack Chunks}, for full details.
-
-At run time, before the program can use a @code{struct obstack} object
-as an obstack, it must initialize the obstack by calling
-@code{obstack_init} or one of its variants, @code{obstack_begin},
-@code{obstack_specify_allocation}, or
-@code{obstack_specify_allocation_with_arg}.
-
-@comment obstack.h
-@comment GNU
-@deftypefun int obstack_init (struct obstack *@var{obstack-ptr})
-Initialize obstack @var{obstack-ptr} for allocation of objects. This
-macro calls the obstack's @code{obstack_chunk_alloc} function. If
-allocation of memory fails, the function pointed to by
-@code{obstack_alloc_failed_handler} is called. The @code{obstack_init}
-macro always returns 1 (Compatibility notice: Former versions of
-obstack returned 0 if allocation failed).
-@end deftypefun
-
-Here are two examples of how to allocate the space for an obstack and
-initialize it. First, an obstack that is a static variable:
-
-@smallexample
-static struct obstack myobstack;
-@dots{}
-obstack_init (&myobstack);
-@end smallexample
-
-@noindent
-Second, an obstack that is itself dynamically allocated:
-
-@smallexample
-struct obstack *myobstack_ptr
- = (struct obstack *) xmalloc (sizeof (struct obstack));
-
-obstack_init (myobstack_ptr);
-@end smallexample
-
-@comment obstack.h
-@comment GNU
-@deftypefun int obstack_begin (struct obstack *@var{obstack-ptr}, size_t chunk_size)
-Like @code{obstack_init}, but specify chunks to be at least
-@var{chunk_size} bytes in size.
-@end deftypefun
-
-@comment obstack.h
-@comment GNU
-@deftypefun int obstack_specify_allocation (struct obstack *@var{obstack-ptr}, size_t chunk_size, size_t alignment, void *(*chunkfun) (size_t), void (*freefun) (void *))
-Like @code{obstack_init}, specifying chunk size, chunk
-alignment, and memory allocation functions. A @var{chunk_size} or
-@var{alignment} of zero results in the default size or alignment
-respectively being used.
-@end deftypefun
-
-@comment obstack.h
-@comment GNU
-@deftypefun int obstack_specify_allocation_with_arg (struct obstack *@var{obstack-ptr}, size_t chunk_size, size_t alignment, void *(*chunkfun) (void *, size_t), void (*freefun) (void *, void *), void *arg)
-Like @code{obstack_specify_allocation}, but specifying memory
-allocation functions that take an extra first argument, @var{arg}.
-@end deftypefun
-
-@comment obstack.h
-@comment GNU
-@defvar obstack_alloc_failed_handler
-The value of this variable is a pointer to a function that
-@code{obstack} uses when @code{obstack_chunk_alloc} fails to allocate
-memory. The default action is to print a message and abort.
-You should supply a function that either calls @code{exit}
-(@pxref{Program Termination, , , libc, The GNU C Library Reference Manual}) or @code{longjmp} (@pxref{Non-Local
-Exits, , , libc, The GNU C Library Reference Manual}) and doesn't return.
-
-@smallexample
-void my_obstack_alloc_failed (void)
-@dots{}
-obstack_alloc_failed_handler = &my_obstack_alloc_failed;
-@end smallexample
-
-@end defvar
-
-@node Allocation in an Obstack
-@subsubsection Allocation in an Obstack
-@cindex allocation (obstacks)
-
-The most direct way to allocate an object in an obstack is with
-@code{obstack_alloc}, which is invoked almost like @code{malloc}.
-
-@comment obstack.h
-@comment GNU
-@deftypefun {void *} obstack_alloc (struct obstack *@var{obstack-ptr}, size_t @var{size})
-This allocates an uninitialized block of @var{size} bytes in an obstack
-and returns its address. Here @var{obstack-ptr} specifies which obstack
-to allocate the block in; it is the address of the @code{struct obstack}
-object which represents the obstack. Each obstack macro
-requires you to specify an @var{obstack-ptr} as the first argument.
-
-This macro calls the obstack's @code{obstack_chunk_alloc} function if
-it needs to allocate a new chunk of memory; it calls
-@code{obstack_alloc_failed_handler} if allocation of memory by
-@code{obstack_chunk_alloc} failed.
-@end deftypefun
-
-For example, here is a function that allocates a copy of a string @var{str}
-in a specific obstack, which is in the variable @code{string_obstack}:
-
-@smallexample
-struct obstack string_obstack;
-
-char *
-copystring (char *string)
-@{
- size_t len = strlen (string) + 1;
- char *s = (char *) obstack_alloc (&string_obstack, len);
- memcpy (s, string, len);
- return s;
-@}
-@end smallexample
-
-To allocate a block with specified contents, use the macro @code{obstack_copy}.
-
-@comment obstack.h
-@comment GNU
-@deftypefun {void *} obstack_copy (struct obstack *@var{obstack-ptr}, void *@var{address}, size_t @var{size})
-This allocates a block and initializes it by copying @var{size}
-bytes of data starting at @var{address}. It calls
-@code{obstack_alloc_failed_handler} if allocation of memory by
-@code{obstack_chunk_alloc} failed.
-@end deftypefun
-
-@comment obstack.h
-@comment GNU
-@deftypefun {void *} obstack_copy0 (struct obstack *@var{obstack-ptr}, void *@var{address}, size_t @var{size})
-Like @code{obstack_copy}, but appends an extra byte containing a null
-character. This extra byte is not counted in the argument @var{size}.
-@end deftypefun
-
-The @code{obstack_copy0} macro is convenient for copying a sequence
-of characters into an obstack as a null-terminated string. Here is an
-example of its use:
-
-@smallexample
-char *
-obstack_savestring (char *addr, size_t size)
-@{
- return obstack_copy0 (&myobstack, addr, size);
-@}
-@end smallexample
-
-@noindent
-Contrast this with the previous example of @code{savestring} using
-@code{malloc} (@pxref{Basic Allocation, , , libc, The GNU C Library Reference Manual}).
-
-@node Freeing Obstack Objects
-@subsubsection Freeing Objects in an Obstack
-@cindex freeing (obstacks)
-
-To free an object allocated in an obstack, use the macro
-@code{obstack_free}. Since the obstack is a stack of objects, freeing
-one object automatically frees all other objects allocated more recently
-in the same obstack.
-
-@comment obstack.h
-@comment GNU
-@deftypefun void obstack_free (struct obstack *@var{obstack-ptr}, void *@var{object})
-If @var{object} is a null pointer, everything allocated in the obstack
-is freed. Otherwise, @var{object} must be the address of an object
-allocated in the obstack. Then @var{object} is freed, along with
-everything allocated in @var{obstack} since @var{object}.
-@end deftypefun
-
-Note that if @var{object} is a null pointer, the result is an
-uninitialized obstack. To free all memory in an obstack but leave it
-valid for further allocation, call @code{obstack_free} with the address
-of the first object allocated on the obstack:
-
-@smallexample
-obstack_free (obstack_ptr, first_object_allocated_ptr);
-@end smallexample
-
-Recall that the objects in an obstack are grouped into chunks. When all
-the objects in a chunk become free, the obstack library automatically
-frees the chunk (@pxref{Preparing for Obstacks}). Then other
-obstacks, or non-obstack allocation, can reuse the space of the chunk.
-
-@node Obstack Functions
-@subsubsection Obstack Functions and Macros
-@cindex macros
-
-The interfaces for using obstacks are shown here as functions to
-specify the return type and argument types, but they are really
-defined as macros. This means that the arguments don't actually have
-types, but they generally behave as if they have the types shown.
-You can call these macros like functions, but you cannot use them in
-any other way (for example, you cannot take their address).
-
-Calling the macros requires a special precaution: namely, the first
-operand (the obstack pointer) may not contain any side effects, because
-it may be computed more than once. For example, if you write this:
-
-@smallexample
-obstack_alloc (get_obstack (), 4);
-@end smallexample
-
-@noindent
-you will find that @code{get_obstack} may be called several times.
-If you use @code{*obstack_list_ptr++} as the obstack pointer argument,
-you will get very strange results since the incrementation may occur
-several times.
-
-If you use the GNU C compiler, this precaution is not necessary, because
-various language extensions in GNU C permit defining the macros so as to
-compute each argument only once.
-
-Note that arguments other than the first will only be evaluated once,
-even when not using GNU C.
-
-@code{obstack.h} does declare a number of functions,
-@code{_obstack_begin}, @code{_obstack_begin_1},
-@code{_obstack_newchunk}, @code{_obstack_free}, and
-@code{_obstack_memory_used}. You should not call these directly.
-
-@node Growing Objects
-@subsubsection Growing Objects
-@cindex growing objects (in obstacks)
-@cindex changing the size of a block (obstacks)
-
-Because memory in obstack chunks is used sequentially, it is possible to
-build up an object step by step, adding one or more bytes at a time to the
-end of the object. With this technique, you do not need to know how much
-data you will put in the object until you come to the end of it. We call
-this the technique of @dfn{growing objects}. The special macros
-for adding data to the growing object are described in this section.
-
-You don't need to do anything special when you start to grow an object.
-Using one of the macros to add data to the object automatically
-starts it. However, it is necessary to say explicitly when the object is
-finished. This is done with @code{obstack_finish}.
-
-The actual address of the object thus built up is not known until the
-object is finished. Until then, it always remains possible that you will
-add so much data that the object must be copied into a new chunk.
-
-While the obstack is in use for a growing object, you cannot use it for
-ordinary allocation of another object. If you try to do so, the space
-already added to the growing object will become part of the other object.
-
-@comment obstack.h
-@comment GNU
-@deftypefun void obstack_blank (struct obstack *@var{obstack-ptr}, size_t @var{size})
-The most basic macro for adding to a growing object is
-@code{obstack_blank}, which adds space without initializing it.
-@end deftypefun
-
-@comment obstack.h
-@comment GNU
-@deftypefun void obstack_grow (struct obstack *@var{obstack-ptr}, void *@var{data}, size_t @var{size})
-To add a block of initialized space, use @code{obstack_grow}, which is
-the growing-object analogue of @code{obstack_copy}. It adds @var{size}
-bytes of data to the growing object, copying the contents from
-@var{data}.
-@end deftypefun
-
-@comment obstack.h
-@comment GNU
-@deftypefun void obstack_grow0 (struct obstack *@var{obstack-ptr}, void *@var{data}, size_t @var{size})
-This is the growing-object analogue of @code{obstack_copy0}. It adds
-@var{size} bytes copied from @var{data}, followed by an additional null
-character.
-@end deftypefun
-
-@comment obstack.h
-@comment GNU
-@deftypefun void obstack_1grow (struct obstack *@var{obstack-ptr}, char @var{c})
-To add one character at a time, use @code{obstack_1grow}.
-It adds a single byte containing @var{c} to the growing object.
-@end deftypefun
-
-@comment obstack.h
-@comment GNU
-@deftypefun void obstack_ptr_grow (struct obstack *@var{obstack-ptr}, void *@var{data})
-Adding the value of a pointer one can use
-@code{obstack_ptr_grow}. It adds @code{sizeof (void *)} bytes
-containing the value of @var{data}.
-@end deftypefun
-
-@comment obstack.h
-@comment GNU
-@deftypefun void obstack_int_grow (struct obstack *@var{obstack-ptr}, int @var{data})
-A single value of type @code{int} can be added by using
-@code{obstack_int_grow}. It adds @code{sizeof (int)} bytes to
-the growing object and initializes them with the value of @var{data}.
-@end deftypefun
-
-@comment obstack.h
-@comment GNU
-@deftypefun {void *} obstack_finish (struct obstack *@var{obstack-ptr})
-When you are finished growing the object, use
-@code{obstack_finish} to close it off and return its final address.
-
-Once you have finished the object, the obstack is available for ordinary
-allocation or for growing another object.
-@end deftypefun
-
-When you build an object by growing it, you will probably need to know
-afterward how long it became. You need not keep track of this as you grow
-the object, because you can find out the length from the obstack
-with @code{obstack_object_size}, before finishing the object.
-
-@comment obstack.h
-@comment GNU
-@deftypefun size_t obstack_object_size (struct obstack *@var{obstack-ptr})
-This macro returns the current size of the growing object, in bytes.
-Remember to call @code{obstack_object_size} @emph{before} finishing the object.
-After it is finished, @code{obstack_object_size} will return zero.
-@end deftypefun
-
-If you have started growing an object and wish to cancel it, you should
-finish it and then free it, like this:
-
-@smallexample
-obstack_free (obstack_ptr, obstack_finish (obstack_ptr));
-@end smallexample
-
-@noindent
-This has no effect if no object was growing.
-
-@node Extra Fast Growing
-@subsubsection Extra Fast Growing Objects
-@cindex efficiency and obstacks
-
-The usual macros for growing objects incur overhead for checking
-whether there is room for the new growth in the current chunk. If you
-are frequently constructing objects in small steps of growth, this
-overhead can be significant.
-
-You can reduce the overhead by using special ``fast growth''
-macros that grow the object without checking. In order to have a
-robust program, you must do the checking yourself. If you do this checking
-in the simplest way each time you are about to add data to the object, you
-have not saved anything, because that is what the ordinary growth
-macros do. But if you can arrange to check less often, or check
-more efficiently, then you make the program faster.
-
-@code{obstack_room} returns the amount of room available
-in the current chunk.
-
-@comment obstack.h
-@comment GNU
-@deftypefun size_t obstack_room (struct obstack *@var{obstack-ptr})
-This returns the number of bytes that can be added safely to the current
-growing object (or to an object about to be started) in obstack
-@var{obstack} using the fast growth macros.
-@end deftypefun
-
-While you know there is room, you can use these fast growth macros
-for adding data to a growing object:
-
-@comment obstack.h
-@comment GNU
-@deftypefun void obstack_1grow_fast (struct obstack *@var{obstack-ptr}, char @var{c})
-@code{obstack_1grow_fast} adds one byte containing the
-character @var{c} to the growing object in obstack @var{obstack-ptr}.
-@end deftypefun
-
-@comment obstack.h
-@comment GNU
-@deftypefun void obstack_ptr_grow_fast (struct obstack *@var{obstack-ptr}, void *@var{data})
-@code{obstack_ptr_grow_fast} adds @code{sizeof (void *)}
-bytes containing the value of @var{data} to the growing object in
-obstack @var{obstack-ptr}.
-@end deftypefun
-
-@comment obstack.h
-@comment GNU
-@deftypefun void obstack_int_grow_fast (struct obstack *@var{obstack-ptr}, int @var{data})
-@code{obstack_int_grow_fast} adds @code{sizeof (int)} bytes
-containing the value of @var{data} to the growing object in obstack
-@var{obstack-ptr}.
-@end deftypefun
-
-@comment obstack.h
-@comment GNU
-@deftypefun void obstack_blank_fast (struct obstack *@var{obstack-ptr}, size_t @var{size})
-@code{obstack_blank_fast} adds @var{size} bytes to the
-growing object in obstack @var{obstack-ptr} without initializing them.
-@end deftypefun
-
-When you check for space using @code{obstack_room} and there is not
-enough room for what you want to add, the fast growth macros
-are not safe. In this case, simply use the corresponding ordinary
-growth macro instead. Very soon this will copy the object to a
-new chunk; then there will be lots of room available again.
-
-So, each time you use an ordinary growth macro, check afterward for
-sufficient space using @code{obstack_room}. Once the object is copied
-to a new chunk, there will be plenty of space again, so the program will
-start using the fast growth macros again.
-
-Here is an example:
-
-@smallexample
-@group
-void
-add_string (struct obstack *obstack, const char *ptr, size_t len)
-@{
- while (len > 0)
- @{
- size_t room = obstack_room (obstack);
- if (room == 0)
- @{
- /* @r{Not enough room. Add one character slowly,}
- @r{which may copy to a new chunk and make room.} */
- obstack_1grow (obstack, *ptr++);
- len--;
- @}
- else
- @{
- if (room > len)
- room = len;
- /* @r{Add fast as much as we have room for.} */
- len -= room;
- while (room-- > 0)
- obstack_1grow_fast (obstack, *ptr++);
- @}
- @}
-@}
-@end group
-@end smallexample
-
-@cindex shrinking objects
-You can use @code{obstack_blank_fast} with a ``negative'' size
-argument to make the current object smaller. Just don't try to shrink
-it beyond zero length---there's no telling what will happen if you do
-that. Earlier versions of obstacks allowed you to use
-@code{obstack_blank} to shrink objects. This will no longer work.
-
-@node Status of an Obstack
-@subsubsection Status of an Obstack
-@cindex obstack status
-@cindex status of obstack
-
-Here are macros that provide information on the current status of
-allocation in an obstack. You can use them to learn about an object while
-still growing it.
-
-@comment obstack.h
-@comment GNU
-@deftypefun {void *} obstack_base (struct obstack *@var{obstack-ptr})
-This macro returns the tentative address of the beginning of the
-currently growing object in @var{obstack-ptr}. If you finish the object
-immediately, it will have that address. If you make it larger first, it
-may outgrow the current chunk---then its address will change!
-
-If no object is growing, this value says where the next object you
-allocate will start (once again assuming it fits in the current
-chunk).
-@end deftypefun
-
-@comment obstack.h
-@comment GNU
-@deftypefun {void *} obstack_next_free (struct obstack *@var{obstack-ptr})
-This macro returns the address of the first free byte in the current
-chunk of obstack @var{obstack-ptr}. This is the end of the currently
-growing object. If no object is growing, @code{obstack_next_free}
-returns the same value as @code{obstack_base}.
-@end deftypefun
-
-@comment obstack.h
-@comment GNU
-@deftypefun size_t obstack_object_size (struct obstack *@var{obstack-ptr})
-This macro returns the size in bytes of the currently growing object.
-This is equivalent to
-
-@smallexample
-((size_t) (obstack_next_free (@var{obstack-ptr}) - obstack_base (@var{obstack-ptr})))
-@end smallexample
-@end deftypefun
-
-@node Obstacks Data Alignment
-@subsubsection Alignment of Data in Obstacks
-@cindex alignment (in obstacks)
-
-Each obstack has an @dfn{alignment boundary}; each object allocated in
-the obstack automatically starts on an address that is a multiple of the
-specified boundary. By default, this boundary is aligned so that
-the object can hold any type of data.
-
-To access an obstack's alignment boundary, use the macro
-@code{obstack_alignment_mask}.
-
-@comment obstack.h
-@comment GNU
-@deftypefn Macro size_t obstack_alignment_mask (struct obstack *@var{obstack-ptr})
-The value is a bit mask; a bit that is 1 indicates that the corresponding
-bit in the address of an object should be 0. The mask value should be one
-less than a power of 2; the effect is that all object addresses are
-multiples of that power of 2. The default value of the mask is a value
-that allows aligned objects to hold any type of data: for example, if
-its value is 3, any type of data can be stored at locations whose
-addresses are multiples of 4. A mask value of 0 means an object can start
-on any multiple of 1 (that is, no alignment is required).
-
-The expansion of the macro @code{obstack_alignment_mask} is an lvalue,
-so you can alter the mask by assignment. For example, this statement:
-
-@smallexample
-obstack_alignment_mask (obstack_ptr) = 0;
-@end smallexample
-
-@noindent
-has the effect of turning off alignment processing in the specified obstack.
-@end deftypefn
-
-Note that a change in alignment mask does not take effect until
-@emph{after} the next time an object is allocated or finished in the
-obstack. If you are not growing an object, you can make the new
-alignment mask take effect immediately by calling @code{obstack_finish}.
-This will finish a zero-length object and then do proper alignment for
-the next object.
-
-@node Obstack Chunks
-@subsubsection Obstack Chunks
-@cindex efficiency of chunks
-@cindex chunks
-
-Obstacks work by allocating space for themselves in large chunks, and
-then parceling out space in the chunks to satisfy your requests. Chunks
-are normally 4096 bytes long unless you specify a different chunk size.
-The chunk size includes 8 bytes of overhead that are not actually used
-for storing objects. Regardless of the specified size, longer chunks
-will be allocated when necessary for long objects.
-
-The obstack library allocates chunks by calling the function
-@code{obstack_chunk_alloc}, which you must define. When a chunk is no
-longer needed because you have freed all the objects in it, the obstack
-library frees the chunk by calling @code{obstack_chunk_free}, which you
-must also define.
-
-These two must be defined (as macros) or declared (as functions) in each
-source file that uses @code{obstack_init} (@pxref{Creating Obstacks}).
-Most often they are defined as macros like this:
-
-@smallexample
-#define obstack_chunk_alloc malloc
-#define obstack_chunk_free free
-@end smallexample
-
-Note that these are simple macros (no arguments). Macro definitions with
-arguments will not work! It is necessary that @code{obstack_chunk_alloc}
-or @code{obstack_chunk_free}, alone, expand into a function name if it is
-not itself a function name.
-
-If you allocate chunks with @code{malloc}, the chunk size should be a
-power of 2. The default chunk size, 4096, was chosen because it is long
-enough to satisfy many typical requests on the obstack yet short enough
-not to waste too much memory in the portion of the last chunk not yet used.
-
-@comment obstack.h
-@comment GNU
-@deftypefn Macro size_t obstack_chunk_size (struct obstack *@var{obstack-ptr})
-This returns the chunk size of the given obstack.
-@end deftypefn
-
-Since this macro expands to an lvalue, you can specify a new chunk size by
-assigning it a new value. Doing so does not affect the chunks already
-allocated, but will change the size of chunks allocated for that particular
-obstack in the future. It is unlikely to be useful to make the chunk size
-smaller, but making it larger might improve efficiency if you are
-allocating many objects whose size is comparable to the chunk size. Here
-is how to do so cleanly:
-
-@smallexample
-if (obstack_chunk_size (obstack_ptr) < @var{new-chunk-size})
- obstack_chunk_size (obstack_ptr) = @var{new-chunk-size};
-@end smallexample
-
-@node Summary of Obstacks
-@subsubsection Summary of Obstack Macros
-
-Here is a summary of all the macros associated with obstacks. Each
-takes the address of an obstack (@code{struct obstack *}) as its first
-argument.
-
-@table @code
-@item int obstack_init (struct obstack *@var{obstack-ptr})
-Initialize use of an obstack. @xref{Creating Obstacks}.
-
-@item int obstack_begin (struct obstack *@var{obstack-ptr}, size_t chunk_size)
-Initialize use of an obstack, with an initial chunk of
-@var{chunk_size} bytes.
-
-@item int obstack_specify_allocation (struct obstack *@var{obstack-ptr}, size_t chunk_size, size_t alignment, void *(*chunkfun) (size_t), void (*freefun) (void *))
-Initialize use of an obstack, specifying intial chunk size, chunk
-alignment, and memory allocation functions.
-
-@item int obstack_specify_allocation_with_arg (struct obstack *@var{obstack-ptr}, size_t chunk_size, size_t alignment, void *(*chunkfun) (void *, size_t), void (*freefun) (void *, void *), void *arg)
-Like @code{obstack_specify_allocation}, but specifying memory
-allocation functions that take an extra first argument, @var{arg}.
-
-@item void *obstack_alloc (struct obstack *@var{obstack-ptr}, size_t @var{size})
-Allocate an object of @var{size} uninitialized bytes.
-@xref{Allocation in an Obstack}.
-
-@item void *obstack_copy (struct obstack *@var{obstack-ptr}, void *@var{address}, size_t @var{size})
-Allocate an object of @var{size} bytes, with contents copied from
-@var{address}. @xref{Allocation in an Obstack}.
-
-@item void *obstack_copy0 (struct obstack *@var{obstack-ptr}, void *@var{address}, size_t @var{size})
-Allocate an object of @var{size}+1 bytes, with @var{size} of them copied
-from @var{address}, followed by a null character at the end.
-@xref{Allocation in an Obstack}.
-
-@item void obstack_free (struct obstack *@var{obstack-ptr}, void *@var{object})
-Free @var{object} (and everything allocated in the specified obstack
-more recently than @var{object}). @xref{Freeing Obstack Objects}.
-
-@item void obstack_blank (struct obstack *@var{obstack-ptr}, size_t @var{size})
-Add @var{size} uninitialized bytes to a growing object.
-@xref{Growing Objects}.
-
-@item void obstack_grow (struct obstack *@var{obstack-ptr}, void *@var{address}, size_t @var{size})
-Add @var{size} bytes, copied from @var{address}, to a growing object.
-@xref{Growing Objects}.
-
-@item void obstack_grow0 (struct obstack *@var{obstack-ptr}, void *@var{address}, size_t @var{size})
-Add @var{size} bytes, copied from @var{address}, to a growing object,
-and then add another byte containing a null character. @xref{Growing
-Objects}.
-
-@item void obstack_1grow (struct obstack *@var{obstack-ptr}, char @var{data-char})
-Add one byte containing @var{data-char} to a growing object.
-@xref{Growing Objects}.
-
-@item void *obstack_finish (struct obstack *@var{obstack-ptr})
-Finalize the object that is growing and return its permanent address.
-@xref{Growing Objects}.
-
-@item size_t obstack_object_size (struct obstack *@var{obstack-ptr})
-Get the current size of the currently growing object. @xref{Growing
-Objects}.
-
-@item void obstack_blank_fast (struct obstack *@var{obstack-ptr}, size_t @var{size})
-Add @var{size} uninitialized bytes to a growing object without checking
-that there is enough room. @xref{Extra Fast Growing}.
-
-@item void obstack_1grow_fast (struct obstack *@var{obstack-ptr}, char @var{data-char})
-Add one byte containing @var{data-char} to a growing object without
-checking that there is enough room. @xref{Extra Fast Growing}.
-
-@item size_t obstack_room (struct obstack *@var{obstack-ptr})
-Get the amount of room now available for growing the current object.
-@xref{Extra Fast Growing}.
-
-@item size_t obstack_alignment_mask (struct obstack *@var{obstack-ptr})
-The mask used for aligning the beginning of an object. This is an
-lvalue. @xref{Obstacks Data Alignment}.
-
-@item size_t obstack_chunk_size (struct obstack *@var{obstack-ptr})
-The size for allocating chunks. This is an lvalue. @xref{Obstack Chunks}.
-
-@item void *obstack_base (struct obstack *@var{obstack-ptr})
-Tentative starting address of the currently growing object.
-@xref{Status of an Obstack}.
-
-@item void *obstack_next_free (struct obstack *@var{obstack-ptr})
-Address just after the end of the currently growing object.
-@xref{Status of an Obstack}.
-@end table
-
+++ /dev/null
-\input texinfo @c -*-texinfo-*-
-
-@c %**start of header
-@setfilename libitm.info
-@settitle GNU libitm
-@c %**end of header
-
-
-@copying
-Copyright @copyright{} 2011-2022 Free Software Foundation, Inc.
-
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.2 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 copying
-
-@ifinfo
-@dircategory GNU Libraries
-@direntry
-* libitm: (libitm). GNU Transactional Memory Library
-@end direntry
-
-This manual documents the GNU Transactional Memory Library.
-
-@insertcopying
-@end ifinfo
-
-
-@setchapternewpage odd
-
-@titlepage
-@title The GNU Transactional Memory Library
-@page
-@vskip 0pt plus 1filll
-@comment For the @value{version-GCC} Version*
-@sp 1
-@insertcopying
-@end titlepage
-
-@summarycontents
-@contents
-@page
-
-
-@node Top
-@top Introduction
-@cindex Introduction
-
-This manual documents the usage and internals of libitm, the GNU Transactional
-Memory Library. It provides transaction support for accesses to a process'
-memory, enabling easy-to-use synchronization of accesses to shared memory by
-several threads.
-
-
-@comment
-@comment When you add a new menu item, please keep the right hand
-@comment aligned to the same column. Do not use tabs. This provides
-@comment better formatting.
-@comment
-@menu
-* Enabling libitm:: How to enable libitm for your applications.
-* C/C++ Language Constructs for TM::
- Notes on the language-level interface supported
- by gcc.
-* The libitm ABI:: Notes on the external ABI provided by libitm.
-* Internals:: Notes on libitm's internal synchronization.
-* GNU Free Documentation License::
- How you can copy and share this manual.
-* Library Index:: Index of this documentation.
-@end menu
-
-
-@c ---------------------------------------------------------------------
-@c Enabling libitm
-@c ---------------------------------------------------------------------
-
-@node Enabling libitm
-@chapter Enabling libitm
-
-To activate support for TM in C/C++, the compile-time flag @option{-fgnu-tm}
-must be specified. This enables TM language-level constructs such as
-transaction statements (e.g., @code{__transaction_atomic}, @pxref{C/C++
-Language Constructs for TM} for details).
-
-@c ---------------------------------------------------------------------
-@c C/C++ Language Constructs for TM
-@c ---------------------------------------------------------------------
-
-@node C/C++ Language Constructs for TM
-@chapter C/C++ Language Constructs for TM
-
-Transactions are supported in C++ and C in the form of transaction statements,
-transaction expressions, and function transactions. In the following example,
-both @code{a} and @code{b} will be read and the difference will be written to
-@code{c}, all atomically and isolated from other transactions:
-
-@example
-__transaction_atomic @{ c = a - b; @}
-@end example
-
-Therefore, another thread can use the following code to concurrently update
-@code{b} without ever causing @code{c} to hold a negative value (and without
-having to use other synchronization constructs such as locks or C++11
-atomics):
-
-@example
-__transaction_atomic @{ if (a > b) b++; @}
-@end example
-
-GCC follows the @uref{https://sites.google.com/site/tmforcplusplus/, Draft
-Specification of Transactional Language Constructs for C++ (v1.1)} in its
-implementation of transactions.
-
-The precise semantics of transactions are defined in terms of the C++11/C11
-memory model (see the specification). Roughly, transactions provide
-synchronization guarantees that are similar to what would be guaranteed when
-using a single global lock as a guard for all transactions. Note that like
-other synchronization constructs in C/C++, transactions rely on a
-data-race-free program (e.g., a nontransactional write that is concurrent
-with a transactional read to the same memory location is a data race).
-
-@c ---------------------------------------------------------------------
-@c The libitm ABI
-@c ---------------------------------------------------------------------
-
-@node The libitm ABI
-@chapter The libitm ABI
-
-The ABI provided by libitm is basically equal to the Linux variant of Intel's
-current TM ABI specification document (Revision 1.1, May 6 2009) but with the
-differences listed in this chapter. It would be good if these changes would
-eventually be merged into a future version of this specification. To ease
-look-up, the following subsections mirror the structure of this specification.
-
-@section [No changes] Objectives
-@section [No changes] Non-objectives
-
-@section Library design principles
-@subsection [No changes] Calling conventions
-@subsection [No changes] TM library algorithms
-@subsection [No changes] Optimized load and store routines
-@subsection [No changes] Aligned load and store routines
-
-@subsection Data logging functions
-
-The memory locations accessed with transactional loads and stores and the
-memory locations whose values are logged must not overlap. This required
-separation only extends to the scope of the execution of one transaction
-including all the executions of all nested transactions.
-
-The compiler must be consistent (within the scope of a single transaction)
-about which memory locations are shared and which are not shared with other
-threads (i.e., data must be accessed either transactionally or
-nontransactionally). Otherwise, non-write-through TM algorithms would not work.
-
-For memory locations on the stack, this requirement extends to only the
-lifetime of the stack frame that the memory location belongs to (or the
-lifetime of the transaction, whichever is shorter). Thus, memory that is
-reused for several stack frames could be target of both data logging and
-transactional accesses; however, this is harmless because these stack frames'
-lifetimes will end before the transaction finishes.
-
-@subsection [No changes] Scatter/gather calls
-@subsection [No changes] Serial and irrevocable mode
-@subsection [No changes] Transaction descriptor
-@subsection Store allocation
-
-There is no @code{getTransaction} function.
-
-@subsection [No changes] Naming conventions
-
-@subsection Function pointer encryption
-
-Currently, this is not implemented.
-
-
-@section Types and macros list
-
-@code{_ITM_codeProperties} has changed, @pxref{txn-code-properties,,Starting a
-transaction}.
-@code{_ITM_srcLocation} is not used.
-
-
-@section Function list
-
-@subsection Initialization and finalization functions
-These functions are not part of the ABI.
-
-@subsection [No changes] Version checking
-@subsection [No changes] Error reporting
-@subsection [No changes] inTransaction call
-
-@subsection State manipulation functions
-There is no @code{getTransaction} function. Transaction identifiers for
-nested transactions will be ordered but not necessarily sequential (i.e., for
-a nested transaction's identifier @var{IN} and its enclosing transaction's
-identifier @var{IE}, it is guaranteed that @math{IN >= IE}).
-
-@subsection [No changes] Source locations
-
-@subsection Starting a transaction
-
-@subsubsection Transaction code properties
-
-@anchor{txn-code-properties}
-The bit @code{hasNoXMMUpdate} is instead called @code{hasNoVectorUpdate}.
-Iff it is set, vector register save/restore is not necessary for any target
-machine.
-
-The @code{hasNoFloatUpdate} bit (@code{0x0010}) is new. Iff it is set, floating
-point register save/restore is not necessary for any target machine.
-
-@code{undoLogCode} is not supported and a fatal runtime error will be raised
-if this bit is set. It is not properly defined in the ABI why barriers
-other than undo logging are not present; Are they not necessary (e.g., a
-transaction operating purely on thread-local data) or have they been omitted by
-the compiler because it thinks that some kind of global synchronization
-(e.g., serial mode) might perform better? The specification suggests that the
-latter might be the case, but the former seems to be more useful.
-
-The @code{readOnly} bit (@code{0x4000}) is new. @strong{TODO} Lexical or dynamic
-scope?
-
-@code{hasNoRetry} is not supported. If this bit is not set, but
-@code{hasNoAbort} is set, the library can assume that transaction
-rollback will not be requested.
-
-It would be useful if the absence of externally-triggered rollbacks would be
-reported for the dynamic scope as well, not just for the lexical scope
-(@code{hasNoAbort}). Without this, a library cannot exploit this together
-with flat nesting.
-
-@code{exceptionBlock} is not supported because exception blocks are not used.
-
-@subsubsection [No changes] Windows exception state
-@subsubsection [No changes] Other machine state
-
-@subsubsection [No changes] Results from beginTransaction
-
-@subsection Aborting a transaction
-
-@code{_ITM_rollbackTransaction} is not supported. @code{_ITM_abortTransaction}
-is supported but the abort reasons @code{exceptionBlockAbort},
-@code{TMConflict}, and @code{userRetry} are not supported. There are no
-exception blocks in general, so the related cases also do not have to be
-considered. To encode @code{__transaction_cancel [[outer]]}, compilers must
-set the new @code{outerAbort} bit (@code{0x10}) additionally to the
-@code{userAbort} bit in the abort reason.
-
-@subsection Committing a transaction
-
-The exception handling (EH) scheme is different. The Intel ABI requires the
-@code{_ITM_tryCommitTransaction} function that will return even when the
-commit failed and will have to be matched with calls to either
-@code{_ITM_abortTransaction} or @code{_ITM_commitTransaction}. In contrast,
-gcc relies on transactional wrappers for the functions of the Exception
-Handling ABI and on one additional commit function (shown below). This allows
-the TM to keep track of EH internally and thus it does not have to embed the
-cleanup of EH state into the existing EH code in the program.
-@code{_ITM_tryCommitTransaction} is not supported.
-@code{_ITM_commitTransactionToId} is also not supported because the
-propagation of thrown exceptions will not bypass commits of nested
-transactions.
-
-@example
-void _ITM_commitTransactionEH(void *exc_ptr) ITM_REGPARM;
-void *_ITM_cxa_allocate_exception (size_t);
-void _ITM_cxa_free_exception (void *exc_ptr);
-void _ITM_cxa_throw (void *obj, void *tinfo, void (*dest) (void *));
-void *_ITM_cxa_begin_catch (void *exc_ptr);
-void _ITM_cxa_end_catch (void);
-@end example
-
-The EH scheme changed in version 6 of GCC. Previously, the compiler
-added a call to @code{_ITM_commitTransactionEH} to commit a transaction if
-an exception could be in flight at this position in the code; @code{exc_ptr} is
-the address of the current exception and must be non-zero. Now, the
-compiler must catch all exceptions that are about to be thrown out of a
-transaction and call @code{_ITM_commitTransactionEH} from the catch clause,
-with @code{exc_ptr} being zero.
-
-Note that the old EH scheme never worked completely in GCC's implementation;
-libitm currently does not try to be compatible with the old scheme.
-
-The @code{_ITM_cxa...} functions are transactional wrappers for the respective
-@code{__cxa...} functions and must be called instead of these in transactional
-code. @code{_ITM_cxa_free_exception} is new in GCC 6.
-
-To support this EH scheme, libstdc++ needs to provide one additional function
-(@code{_cxa_tm_cleanup}), which is used by the TM to clean up the exception
-handling state while rolling back a transaction:
-
-@example
-void __cxa_tm_cleanup (void *unthrown_obj, void *cleanup_exc,
- unsigned int caught_count);
-@end example
-
-Since GCC 6, @code{unthrown_obj} is not used anymore and always null;
-prior to that, @code{unthrown_obj} is non-null if the program called
-@code{__cxa_allocate_exception} for this exception but did not yet called
-@code{__cxa_throw} for it. @code{cleanup_exc} is non-null if the program is
-currently processing a cleanup along an exception path but has not caught this
-exception yet. @code{caught_count} is the nesting depth of
-@code{__cxa_begin_catch} within the transaction (which can be counted by the TM
-using @code{_ITM_cxa_begin_catch} and @code{_ITM_cxa_end_catch});
-@code{__cxa_tm_cleanup} then performs rollback by essentially performing
-@code{__cxa_end_catch} that many times.
-
-
-
-@subsection Exception handling support
-
-Currently, there is no support for functionality like
-@code{__transaction_cancel throw} as described in the C++ TM specification.
-Supporting this should be possible with the EH scheme explained previously
-because via the transactional wrappers for the EH ABI, the TM is able to
-observe and intercept EH.
-
-
-@subsection [No changes] Transition to serial--irrevocable mode
-@subsection [No changes] Data transfer functions
-@subsection [No changes] Transactional memory copies
-
-@subsection Transactional versions of memmove
-
-If either the source or destination memory region is to be accessed
-nontransactionally, then source and destination regions must not be
-overlapping. The respective @code{_ITM_memmove} functions are still
-available but a fatal runtime error will be raised if such regions do overlap.
-To support this functionality, the ABI would have to specify how the
-intersection of the regions has to be accessed (i.e., transactionally or
-nontransactionally).
-
-@subsection [No changes] Transactional versions of memset
-@subsection [No changes] Logging functions
-
-@subsection User-registered commit and undo actions
-
-Commit actions will get executed in the same order in which the respective
-calls to @code{_ITM_addUserCommitAction} happened. Only
-@code{_ITM_noTransactionId} is allowed as value for the
-@code{resumingTransactionId} argument. Commit actions get executed after
-privatization safety has been ensured.
-
-Undo actions will get executed in reverse order compared to the order in which
-the respective calls to @code{_ITM_addUserUndoAction} happened. The ordering of
-undo actions w.r.t. the roll-back of other actions (e.g., data transfers or
-memory allocations) is undefined.
-
-@code{_ITM_getThreadnum} is not supported currently because its only purpose
-is to provide a thread ID that matches some assumed performance tuning output,
-but this output is not part of the ABI nor further defined by it.
-
-@code{_ITM_dropReferences} is not supported currently because its semantics and
-the intention behind it is not entirely clear. The
-specification suggests that this function is necessary because of certain
-orderings of data transfer undos and the releasing of memory regions (i.e.,
-privatization). However, this ordering is never defined, nor is the ordering of
-dropping references w.r.t. other events.
-
-@subsection [New] Transactional indirect calls
-
-Indirect calls (i.e., calls through a function pointer) within transactions
-should execute the transactional clone of the original function (i.e., a clone
-of the original that has been fully instrumented to use the TM runtime), if
-such a clone is available. The runtime provides two functions to
-register/deregister clone tables:
-
-@example
-struct clone_entry
-@{
- void *orig, *clone;
-@};
-
-void _ITM_registerTMCloneTable (clone_entry *table, size_t entries);
-void _ITM_deregisterTMCloneTable (clone_entry *table);
-@end example
-
-Registered tables must be writable by the TM runtime, and must be live
-throughout the life-time of the TM runtime.
-
-@strong{TODO} The intention was always to drop the registration functions
-entirely, and create a new ELF Phdr describing the linker-sorted table. Much
-like what currently happens for @code{PT_GNU_EH_FRAME}.
-This work kept getting bogged down in how to represent the @var{N} different
-code generation variants. We clearly needed at least two---SW and HW
-transactional clones---but there was always a suggestion of more variants for
-different TM assumptions/invariants.
-
-The compiler can then use two TM runtime functions to perform indirect calls in
-transactions:
-@example
-void *_ITM_getTMCloneOrIrrevocable (void *function) ITM_REGPARM;
-void *_ITM_getTMCloneSafe (void *function) ITM_REGPARM;
-@end example
-
-If there is a registered clone for supplied function, both will return a
-pointer to the clone. If not, the first runtime function will attempt to switch
-to serial--irrevocable mode and return the original pointer, whereas the second
-will raise a fatal runtime error.
-
-@subsection [New] Transactional dynamic memory management
-
-@example
-void *_ITM_malloc (size_t)
- __attribute__((__malloc__)) ITM_PURE;
-void *_ITM_calloc (size_t, size_t)
- __attribute__((__malloc__)) ITM_PURE;
-void _ITM_free (void *) ITM_PURE;
-@end example
-
-These functions are essentially transactional wrappers for @code{malloc},
-@code{calloc}, and @code{free}. Within transactions, the compiler should
-replace calls to the original functions with calls to the wrapper functions.
-
-libitm also provides transactional clones of C++ memory management functions
-such as global operator new and delete. They are part of libitm for historic
-reasons but do not need to be part of this ABI.
-
-
-@section [No changes] Future Enhancements to the ABI
-
-@section Sample code
-
-The code examples might not be correct w.r.t. the current version of the ABI,
-especially everything related to exception handling.
-
-
-@section [New] Memory model
-
-The ABI should define a memory model and the ordering that is guaranteed for
-data transfers and commit/undo actions, or at least refer to another memory
-model that needs to be preserved. Without that, the compiler cannot ensure the
-memory model specified on the level of the programming language (e.g., by the
-C++ TM specification).
-
-For example, if a transactional load is ordered before another load/store, then
-the TM runtime must also ensure this ordering when accessing shared state. If
-not, this might break the kind of publication safety used in the C++ TM
-specification. Likewise, the TM runtime must ensure privatization safety.
-
-
-
-@c ---------------------------------------------------------------------
-@c Internals
-@c ---------------------------------------------------------------------
-
-@node Internals
-@chapter Internals
-
-@section TM methods and method groups
-
-libitm supports several ways of synchronizing transactions with each other.
-These TM methods (or TM algorithms) are implemented in the form of
-subclasses of @code{abi_dispatch}, which provide methods for
-transactional loads and stores as well as callbacks for rollback and commit.
-All methods that are compatible with each other (i.e., that let concurrently
-running transactions still synchronize correctly even if different methods
-are used) belong to the same TM method group. Pointers to TM methods can be
-obtained using the factory methods prefixed with @code{dispatch_} in
-@file{libitm_i.h}. There are two special methods, @code{dispatch_serial} and
-@code{dispatch_serialirr}, that are compatible with all methods because they
-run transactions completely in serial mode.
-
-@subsection TM method life cycle
-
-The state of TM methods does not change after construction, but they do alter
-the state of transactions that use this method. However, because
-per-transaction data gets used by several methods, @code{gtm_thread} is
-responsible for setting an initial state that is useful for all methods.
-After that, methods are responsible for resetting/clearing this state on each
-rollback or commit (of outermost transactions), so that the transaction
-executed next is not affected by the previous transaction.
-
-There is also global state associated with each method group, which is
-initialized and shut down (@code{method_group::init()} and @code{fini()})
-when switching between method groups (see @file{retry.cc}).
-
-@subsection Selecting the default method
-
-The default method that libitm uses for freshly started transactions (but
-not necessarily for restarted transactions) can be set via an environment
-variable (@env{ITM_DEFAULT_METHOD}), whose value should be equal to the name
-of one of the factory methods returning abi_dispatch subclasses but without
-the "dispatch_" prefix (e.g., "serialirr" instead of
-@code{GTM::dispatch_serialirr()}).
-
-Note that this environment variable is only a hint for libitm and might not
-be supported in the future.
-
-
-@section Nesting: flat vs. closed
-
-We support two different kinds of nesting of transactions. In the case of
-@emph{flat nesting}, the nesting structure is flattened and all nested
-transactions are subsumed by the enclosing transaction. In contrast,
-with @emph{closed nesting}, nested transactions that have not yet committed
-can be rolled back separately from the enclosing transactions; when they
-commit, they are subsumed by the enclosing transaction, and their effects
-will be finally committed when the outermost transaction commits.
-@emph{Open nesting} (where nested transactions can commit independently of the
-enclosing transactions) are not supported.
-
-Flat nesting is the default nesting mode, but closed nesting is supported and
-used when transactions contain user-controlled aborts
-(@code{__transaction_cancel} statements). We assume that user-controlled
-aborts are rare in typical code and used mostly in exceptional situations.
-Thus, it makes more sense to use flat nesting by default to avoid the
-performance overhead of the additional checkpoints required for closed
-nesting. User-controlled aborts will correctly abort the innermost enclosing
-transaction, whereas the whole (i.e., outermost) transaction will be restarted
-otherwise (e.g., when a transaction encounters data conflicts during
-optimistic execution).
-
-
-@section Locking conventions
-
-This section documents the locking scheme and rules for all uses of locking
-in libitm. We have to support serial(-irrevocable) mode, which is implemented
-using a global lock as explained next (called the @emph{serial lock}). To
-simplify the overall design, we use the same lock as catch-all locking
-mechanism for other infrequent tasks such as (de)registering clone tables or
-threads. Besides the serial lock, there are @emph{per-method-group locks} that
-are managed by specific method groups (i.e., groups of similar TM concurrency
-control algorithms), and lock-like constructs for quiescence-based operations
-such as ensuring privatization safety.
-
-Thus, the actions that participate in the libitm-internal locking are either
-@emph{active transactions} that do not run in serial mode, @emph{serial
-transactions} (which (are about to) run in serial mode), and management tasks
-that do not execute within a transaction but have acquired the serial mode
-like a serial transaction would do (e.g., to be able to register threads with
-libitm). Transactions become active as soon as they have successfully used the
-serial lock to announce this globally (@pxref{serial-lock-impl,,Serial lock
-implementation}). Likewise, transactions become serial transactions as soon as
-they have acquired the exclusive rights provided by the serial lock (i.e.,
-serial mode, which also means that there are no other concurrent active or
-serial transactions). Note that active transactions can become serial
-transactions when they enter serial mode during the runtime of the
-transaction.
-
-@subsection State-to-lock mapping
-
-Application data is protected by the serial lock if there is a serial
-transaction and no concurrently running active transaction (i.e., non-serial).
-Otherwise, application data is protected by the currently selected method
-group, which might use per-method-group locks or other mechanisms. Also note
-that application data that is about to be privatized might not be allowed to be
-accessed by nontransactional code until privatization safety has been ensured;
-the details of this are handled by the current method group.
-
-libitm-internal state is either protected by the serial lock or accessed
-through custom concurrent code. The latter applies to the public/shared part
-of a transaction object and most typical method-group-specific state.
-
-The former category (protected by the serial lock) includes:
-@itemize @bullet
-@item The list of active threads that have used transactions.
-@item The tables that map functions to their transactional clones.
-@item The current selection of which method group to use.
-@item Some method-group-specific data, or invariants of this data. For example,
-resetting a method group to its initial state is handled by switching to the
-same method group, so the serial lock protects such resetting as well.
-@end itemize
-In general, such state is immutable whenever there exists an active
-(non-serial) transaction. If there is no active transaction, a serial
-transaction (or a thread that is not currently executing a transaction but has
-acquired the serial lock) is allowed to modify this state (but must of course
-be careful to not surprise the current method group's implementation with such
-modifications).
-
-@subsection Lock acquisition order
-
-To prevent deadlocks, locks acquisition must happen in a globally agreed-upon
-order. Note that this applies to other forms of blocking too, but does not
-necessarily apply to lock acquisitions that do not block (e.g., trylock()
-calls that do not get retried forever). Note that serial transactions are
-never return back to active transactions until the transaction has committed.
-Likewise, active transactions stay active until they have committed.
-Per-method-group locks are typically also not released before commit.
-
-Lock acquisition / blocking rules:
-@itemize @bullet
-
-@item Transactions must become active or serial before they are allowed to
-use method-group-specific locks or blocking (i.e., the serial lock must be
-acquired before those other locks, either in serial or nonserial mode).
-
-@item Any number of threads that do not currently run active transactions can
-block while trying to get the serial lock in exclusive mode. Note that active
-transactions must not block when trying to upgrade to serial mode unless there
-is no other transaction that is trying that (the latter is ensured by the
-serial lock implementation.
-
-@item Method groups must prevent deadlocks on their locks. In particular, they
-must also be prepared for another active transaction that has acquired
-method-group-specific locks but is blocked during an attempt to upgrade to
-being a serial transaction. See below for details.
-
-@item Serial transactions can acquire method-group-specific locks because there
-will be no other active nor serial transaction.
-
-@end itemize
-
-There is no single rule for per-method-group blocking because this depends on
-when a TM method might acquire locks. If no active transaction can upgrade to
-being a serial transaction after it has acquired per-method-group locks (e.g.,
-when those locks are only acquired during an attempt to commit), then the TM
-method does not need to consider a potential deadlock due to serial mode.
-
-If there can be upgrades to serial mode after the acquisition of
-per-method-group locks, then TM methods need to avoid those deadlocks:
-@itemize @bullet
-@item When upgrading to a serial transaction, after acquiring exclusive rights
-to the serial lock but before waiting for concurrent active transactions to
-finish (@pxref{serial-lock-impl,,Serial lock implementation} for details),
-we have to wake up all active transactions waiting on the upgrader's
-per-method-group locks.
-@item Active transactions blocking on per-method-group locks need to check the
-serial lock and abort if there is a pending serial transaction.
-@item Lost wake-ups have to be prevented (e.g., by changing a bit in each
-per-method-group lock before doing the wake-up, and only blocking on this lock
-using a futex if this bit is not group).
-@end itemize
-
-@strong{TODO}: Can reuse serial lock for gl-*? And if we can, does it make
-sense to introduce further complexity in the serial lock? For gl-*, we can
-really only avoid an abort if we do -wb and -vbv.
-
-
-@subsection Serial lock implementation
-@anchor{serial-lock-impl}
-
-The serial lock implementation is optimized towards assuming that serial
-transactions are infrequent and not the common case. However, the performance
-of entering serial mode can matter because when only few transactions are run
-concurrently or if there are few threads, then it can be efficient to run
-transactions serially.
-
-The serial lock is similar to a multi-reader-single-writer lock in that there
-can be several active transactions but only one serial transaction. However,
-we do want to avoid contention (in the lock implementation) between active
-transactions, so we split up the reader side of the lock into per-transaction
-flags that are true iff the transaction is active. The exclusive writer side
-remains a shared single flag, which is acquired using a CAS, for example.
-On the fast-path, the serial lock then works similar to Dekker's algorithm but
-with several reader flags that a serial transaction would have to check.
-A serial transaction thus requires a list of all threads with potentially
-active transactions; we can use the serial lock itself to protect this list
-(i.e., only threads that have acquired the serial lock can modify this list).
-
-We want starvation-freedom for the serial lock to allow for using it to ensure
-progress for potentially starved transactions (@pxref{progress-guarantees,,
-Progress Guarantees} for details). However, this is currently not enforced by
-the implementation of the serial lock.
-
-Here is pseudo-code for the read/write fast paths of acquiring the serial
-lock (read-to-write upgrade is similar to write_lock:
-@example
-// read_lock:
-tx->shared_state |= active;
-__sync_synchronize(); // or STLD membar, or C++0x seq-cst fence
-while (!serial_lock.exclusive)
- if (spinning_for_too_long) goto slowpath;
-
-// write_lock:
-if (CAS(&serial_lock.exclusive, 0, this) != 0)
- goto slowpath; // writer-writer contention
-// need a membar here, but CAS already has full membar semantics
-bool need_blocking = false;
-for (t: all txns)
- @{
- for (;t->shared_state & active;)
- if (spinning_for_too_long) @{ need_blocking = true; break; @}
- @}
-if (need_blocking) goto slowpath;
-@end example
-
-Releasing a lock in this spin-lock version then just consists of resetting
-@code{tx->shared_state} to inactive or clearing @code{serial_lock.exclusive}.
-
-However, we can't rely on a pure spinlock because we need to get the OS
-involved at some time (e.g., when there are more threads than CPUs to run on).
-Therefore, the real implementation falls back to a blocking slow path, either
-based on pthread mutexes or Linux futexes.
-
-
-@subsection Reentrancy
-
-libitm has to consider the following cases of reentrancy:
-@itemize @bullet
-
-@item Transaction calls unsafe code that starts a new transaction: The outer
-transaction will become a serial transaction before executing unsafe code.
-Therefore, nesting within serial transactions must work, even if the nested
-transaction is called from within uninstrumented code.
-
-@item Transaction calls either a transactional wrapper or safe code, which in
-turn starts a new transaction: It is not yet defined in the specification
-whether this is allowed. Thus, it is undefined whether libitm supports this.
-
-@item Code that starts new transactions might be called from within any part
-of libitm: This kind of reentrancy would likely be rather complex and can
-probably be avoided. Therefore, it is not supported.
-
-@end itemize
-
-@subsection Privatization safety
-
-Privatization safety is ensured by libitm using a quiescence-based approach.
-Basically, a privatizing transaction waits until all concurrent active
-transactions will either have finished (are not active anymore) or operate on
-a sufficiently recent snapshot to not access the privatized data anymore. This
-happens after the privatizing transaction has stopped being an active
-transaction, so waiting for quiescence does not contribute to deadlocks.
-
-In method groups that need to ensure publication safety explicitly, active
-transactions maintain a flag or timestamp in the public/shared part of the
-transaction descriptor. Before blocking, privatizers need to let the other
-transactions know that they should wake up the privatizer.
-
-@strong{TODO} Ho to implement the waiters? Should those flags be
-per-transaction or at a central place? We want to avoid one wake/wait call
-per active transactions, so we might want to use either a tree or combining
-to reduce the syscall overhead, or rather spin for a long amount of time
-instead of doing blocking. Also, it would be good if only the last transaction
-that the privatizer waits for would do the wake-up.
-
-@subsection Progress guarantees
-@anchor{progress-guarantees}
-
-Transactions that do not make progress when using the current TM method will
-eventually try to execute in serial mode. Thus, the serial lock's progress
-guarantees determine the progress guarantees of the whole TM. Obviously, we at
-least need deadlock-freedom for the serial lock, but it would also be good to
-provide starvation-freedom (informally, all threads will finish executing a
-transaction eventually iff they get enough cycles).
-
-However, the scheduling of transactions (e.g., thread scheduling by the OS)
-also affects the handling of progress guarantees by the TM. First, the TM
-can only guarantee deadlock-freedom if threads do not get stopped. Likewise,
-low-priority threads can starve if they do not get scheduled when other
-high-priority threads get those cycles instead.
-
-If all threads get scheduled eventually, correct lock implementations will
-provide deadlock-freedom, but might not provide starvation-freedom. We can
-either enforce the latter in the TM's lock implementation, or assume that
-the scheduling is sufficiently random to yield a probabilistic guarantee that
-no thread will starve (because eventually, a transaction will encounter a
-scheduling that will allow it to run). This can indeed work well in practice
-but is not necessarily guaranteed to work (e.g., simple spin locks can be
-pretty efficient).
-
-Because enforcing stronger progress guarantees in the TM has a higher runtime
-overhead, we focus on deadlock-freedom right now and assume that the threads
-will get scheduled eventually by the OS (but don't consider threads with
-different priorities). We should support starvation-freedom for serial
-transactions in the future. Everything beyond that is highly related to proper
-contention management across all of the TM (including with TM method to
-choose), and is future work.
-
-@strong{TODO} Handling thread priorities: We want to avoid priority inversion
-but it's unclear how often that actually matters in practice. Workloads that
-have threads with different priorities will likely also require lower latency
-or higher throughput for high-priority threads. Therefore, it probably makes
-not that much sense (except for eventual progress guarantees) to use
-priority inheritance until the TM has priority-aware contention management.
-
-
-@c ---------------------------------------------------------------------
-@c GNU Free Documentation License
-@c ---------------------------------------------------------------------
-
-@include fdl.texi
-
-@c ---------------------------------------------------------------------
-@c Index
-@c ---------------------------------------------------------------------
-
-@node Library Index
-@unnumbered Library Index
-
-@printindex cp
-
-@bye
+++ /dev/null
-\input texinfo @c -*-texinfo-*-
-
-@c %**start of header
-@setfilename libquadmath.info
-@settitle GCC libquadmath
-@c %**end of header
-
-@copying
-Copyright @copyright{} 2010-2022 Free Software Foundation, Inc.
-
-@quotation
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.2 or
-any later version published by the Free Software Foundation; with no
-Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
-and with the Back-Cover Texts as in (a) below. A copy of the
-license is included in the section entitled ``GNU Free Documentation
-License.''
-
-(a) The FSF's Back-Cover Text is: ``You have the freedom to
-copy and modify this GNU manual.
-@end quotation
-@end copying
-
-@ifinfo
-@dircategory GNU Libraries
-@direntry
-* libquadmath: (libquadmath). GCC Quad-Precision Math Library
-@end direntry
-
-This manual documents the GCC Quad-Precision Math Library API.
-
-Published by the Free Software Foundation
-51 Franklin Street, Fifth Floor
-Boston, MA 02110-1301 USA
-
-@insertcopying
-@end ifinfo
-
-
-@setchapternewpage odd
-
-@titlepage
-@title The GCC Quad-Precision Math Library
-@page
-@vskip 0pt plus 1filll
-@comment For the @value{version-GCC} Version*
-@sp 1
-Published by the Free Software Foundation @*
-51 Franklin Street, Fifth Floor@*
-Boston, MA 02110-1301, USA@*
-@sp 1
-@insertcopying
-@end titlepage
-
-@summarycontents
-@contents
-@page
-
-
-@node Top
-@top Introduction
-@cindex Introduction
-
-This manual documents the usage of libquadmath, the GCC Quad-Precision
-Math Library Application Programming Interface (API).
-
-
-@comment
-@comment When you add a new menu item, please keep the right hand
-@comment aligned to the same column. Do not use tabs. This provides
-@comment better formatting.
-@comment
-@menu
-* Typedef and constants:: Defined data types and constants
-* Math Library Routines:: The Libquadmath math runtime application
- programming interface.
-* I/O Library Routines:: The Libquadmath I/O runtime application
- programming interface.
-* GNU Free Documentation License::
- How you can copy and share this manual.
-* Reporting Bugs:: How to report bugs in GCC Libquadmath.
-@c * Index:: Index of this documentation.
-@end menu
-
-
-@c ---------------------------------------------------------------------
-@c Defined macros
-@c ---------------------------------------------------------------------
-
-@node Typedef and constants
-@chapter Typedef and constants
-
-The following data type has been defined via @code{typedef}.
-
-@table @asis
-@item @code{__complex128}: @code{__float128}-based complex number
-@end table
-
-The following macros are defined, which give the numeric limits of the
-@code{__float128} data type.
-
-@table @asis
-@item @code{FLT128_MAX}: largest finite number
-@item @code{FLT128_MIN}: smallest positive number with full precision
-@item @code{FLT128_EPSILON}: difference between 1 and the next larger
- representable number
-@item @code{FLT128_DENORM_MIN}: smallest positive denormalized number
-@item @code{FLT128_MANT_DIG}: number of digits in the mantissa (bit precision)
-@item @code{FLT128_MIN_EXP}: maximal negative exponent
-@item @code{FLT128_MAX_EXP}: maximal positive exponent
-@item @code{FLT128_DIG}: number of decimal digits in the mantissa
-@item @code{FLT128_MIN_10_EXP}: maximal negative decimal exponent
-@item @code{FLT128_MAX_10_EXP}: maximal positive decimal exponent
-@end table
-
-The following mathematical constants of type @code{__float128} are defined.
-
-@table @asis
-@item @code{M_Eq}: the constant e (Euler's number)
-@item @code{M_LOG2Eq}: binary logarithm of 2
-@item @code{M_LOG10Eq}: common, decimal logarithm of 2
-@item @code{M_LN2q}: natural logarithm of 2
-@item @code{M_LN10q}: natural logarithm of 10
-@item @code{M_PIq}: pi
-@item @code{M_PI_2q}: pi divided by two
-@item @code{M_PI_4q}: pi divided by four
-@item @code{M_1_PIq}: one over pi
-@item @code{M_2_PIq}: one over two pi
-@item @code{M_2_SQRTPIq}: two over square root of pi
-@item @code{M_SQRT2q}: square root of 2
-@item @code{M_SQRT1_2q}: one over square root of 2
-@end table
-
-
-@c ---------------------------------------------------------------------
-@c Math routines
-@c ---------------------------------------------------------------------
-
-@node Math Library Routines
-@chapter Math Library Routines
-
-The following mathematical functions are available:
-
-@table @asis
-@item @code{acosq}: arc cosine function
-@item @code{acoshq}: inverse hyperbolic cosine function
-@item @code{asinq}: arc sine function
-@item @code{asinhq}: inverse hyperbolic sine function
-@item @code{atanq}: arc tangent function
-@item @code{atanhq}: inverse hyperbolic tangent function
-@item @code{atan2q}: arc tangent function
-@item @code{cbrtq}: cube root function
-@item @code{ceilq}: ceiling value function
-@item @code{copysignq}: copy sign of a number
-@item @code{coshq}: hyperbolic cosine function
-@item @code{cosq}: cosine function
-@item @code{erfq}: error function
-@item @code{erfcq}: complementary error function
-@item @code{exp2q}: base 2 exponential function
-@item @code{expq}: exponential function
-@item @code{expm1q}: exponential minus 1 function
-@need 800
-@item @code{fabsq}: absolute value function
-@item @code{fdimq}: positive difference function
-@item @code{finiteq}: check finiteness of value
-@item @code{floorq}: floor value function
-@item @code{fmaq}: fused multiply and add
-@item @code{fmaxq}: determine maximum of two values
-@item @code{fminq}: determine minimum of two values
-@item @code{fmodq}: remainder value function
-@item @code{frexpq}: extract mantissa and exponent
-@item @code{hypotq}: Eucledian distance function
-@item @code{ilogbq}: get exponent of the value
-@item @code{isinfq}: check for infinity
-@item @code{isnanq}: check for not a number
-@item @code{issignalingq}: check for signaling not a number
-@item @code{j0q}: Bessel function of the first kind, first order
-@item @code{j1q}: Bessel function of the first kind, second order
-@item @code{jnq}: Bessel function of the first kind, @var{n}-th order
-@item @code{ldexpq}: load exponent of the value
-@item @code{lgammaq}: logarithmic gamma function
-@item @code{llrintq}: round to nearest integer value
-@item @code{llroundq}: round to nearest integer value away from zero
-@item @code{logbq}: get exponent of the value
-@item @code{logq}: natural logarithm function
-@item @code{log10q}: base 10 logarithm function
-@item @code{log1pq}: compute natural logarithm of the value plus one
-@item @code{log2q}: base 2 logarithm function
-@need 800
-@item @code{lrintq}: round to nearest integer value
-@item @code{lroundq}: round to nearest integer value away from zero
-@item @code{modfq}: decompose the floating-point number
-@item @code{nanq}: return quiet NaN
-@item @code{nearbyintq}: round to nearest integer
-@item @code{nextafterq}: next representable floating-point number
-@item @code{powq}: power function
-@item @code{remainderq}: remainder function
-@item @code{remquoq}: remainder and part of quotient
-@item @code{rintq}: round-to-nearest integral value
-@item @code{roundq}: round-to-nearest integral value, return @code{__float128}
-@item @code{scalblnq}: compute exponent using @code{FLT_RADIX}
-@item @code{scalbnq}: compute exponent using @code{FLT_RADIX}
-@item @code{signbitq}: return sign bit
-@item @code{sincosq}: calculate sine and cosine simultaneously
-@item @code{sinhq}: hyperbolic sine function
-@item @code{sinq}: sine function
-@item @code{sqrtq}: square root function
-@item @code{tanq}: tangent function
-@item @code{tanhq}: hyperbolic tangent function
-@need 800
-@item @code{tgammaq}: true gamma function
-@item @code{truncq}: round to integer, towards zero
-@item @code{y0q}: Bessel function of the second kind, first order
-@item @code{y1q}: Bessel function of the second kind, second order
-@item @code{ynq}: Bessel function of the second kind, @var{n}-th order
-@item @code{cabsq} complex absolute value function
-@item @code{cargq}: calculate the argument
-@item @code{cimagq} imaginary part of complex number
-@item @code{crealq}: real part of complex number
-@item @code{cacoshq}: complex arc hyperbolic cosine function
-@item @code{cacosq}: complex arc cosine function
-@item @code{casinhq}: complex arc hyperbolic sine function
-@item @code{casinq}: complex arc sine function
-@item @code{catanhq}: complex arc hyperbolic tangent function
-@item @code{catanq}: complex arc tangent function
-@item @code{ccosq} complex cosine function:
-@item @code{ccoshq}: complex hyperbolic cosine function
-@item @code{cexpq}: complex exponential function
-@need 800
-@item @code{cexpiq}: computes the exponential function of ``i'' times a
- real value
-@item @code{clogq}: complex natural logarithm
-@item @code{clog10q}: complex base 10 logarithm
-@item @code{conjq}: complex conjugate function
-@item @code{cpowq}: complex power function
-@item @code{cprojq}: project into Riemann Sphere
-@item @code{csinq}: complex sine function
-@item @code{csinhq}: complex hyperbolic sine function
-@item @code{csqrtq}: complex square root
-@item @code{ctanq}: complex tangent function
-@item @code{ctanhq}: complex hyperbolic tangent function
-@end table
-
-
-@c ---------------------------------------------------------------------
-@c I/O routines
-@c ---------------------------------------------------------------------
-
-@node I/O Library Routines
-@chapter I/O Library Routines
-
-@menu
-* @code{strtoflt128}: strtoflt128, Convert from string
-* @code{quadmath_snprintf}: quadmath_snprintf, Convert to string
-@end menu
-
-
-@node strtoflt128
-@section @code{strtoflt128} --- Convert from string
-
-The function @code{strtoflt128} converts a string into a
-@code{__float128} number.
-
-@table @asis
-@item Syntax
-@code{__float128 strtoflt128 (const char *s, char **sp)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{s} @tab input string
-@item @var{sp} @tab the address of the next character in the string
-@end multitable
-
-The argument @var{sp} contains, if not @code{NULL}, the address of the
-next character following the parts of the string, which have been read.
-
-@item Example
-@smallexample
-#include <quadmath.h>
-
-int main ()
-@{
- __float128 r;
-
- r = strtoflt128 ("1.2345678", NULL);
-
- return 0;
-@}
-@end smallexample
-@end table
-
-
-@node quadmath_snprintf
-@section @code{quadmath_snprintf} --- Convert to string
-
-The function @code{quadmath_snprintf} converts a @code{__float128} floating-point
-number into a string. It is a specialized alternative to @code{snprintf}, where
-the format string is restricted to a single conversion specifier with @code{Q}
-modifier and conversion specifier @code{e}, @code{E}, @code{f}, @code{F}, @code{g},
-@code{G}, @code{a} or @code{A}, with no extra characters before or after the
-conversion specifier. The @code{%m$} or @code{*m$} style must not be used in
-the format.
-
-@table @asis
-@item Syntax
-@code{int quadmath_snprintf (char *s, size_t size, const char *format, ...)}
-
-@item @emph{Arguments}:
-@multitable @columnfractions .15 .70
-@item @var{s} @tab output string
-@item @var{size} @tab byte size of the string, including trailing NUL
-@item @var{format} @tab conversion specifier string
-@end multitable
-
-@item Note
-On some targets when supported by the C library hooks are installed
-for @code{printf} family of functions, so that @code{printf ("%Qe", 1.2Q);}
-etc.@: works too.
-
-@item Example
-@smallexample
-#include <quadmath.h>
-#include <stdlib.h>
-#include <stdio.h>
-
-int main ()
-@{
- __float128 r;
- int prec = 20;
- int width = 46;
- char buf[128];
-
- r = 2.0q;
- r = sqrtq (r);
- int n = quadmath_snprintf (buf, sizeof buf, "%+-#*.20Qe", width, r);
- if ((size_t) n < sizeof buf)
- printf ("%s\n", buf);
- /* Prints: +1.41421356237309504880e+00 */
- quadmath_snprintf (buf, sizeof buf, "%Qa", r);
- if ((size_t) n < sizeof buf)
- printf ("%s\n", buf);
- /* Prints: 0x1.6a09e667f3bcc908b2fb1366ea96p+0 */
- n = quadmath_snprintf (NULL, 0, "%+-#46.*Qe", prec, r);
- if (n > -1)
- @{
- char *str = malloc (n + 1);
- if (str)
- @{
- quadmath_snprintf (str, n + 1, "%+-#46.*Qe", prec, r);
- printf ("%s\n", str);
- /* Prints: +1.41421356237309504880e+00 */
- @}
- free (str);
- @}
- return 0;
-@}
-@end smallexample
-
-@end table
-
-
-@c ---------------------------------------------------------------------
-@c GNU Free Documentation License
-@c ---------------------------------------------------------------------
-
-@include fdl.texi
-
-@c ---------------------------------------------------------------------
-@c Reporting Bugs
-@c ---------------------------------------------------------------------
-
-@c For BUGURL
-@include libquadmath-vers.texi
-
-@node Reporting Bugs
-@chapter Reporting Bugs
-
-Bugs in the GCC Quad-Precision Math Library implementation should be
-reported via @value{BUGURL}.
-
-
-@c ---------------------------------------------------------------------
-@c Index
-@c ---------------------------------------------------------------------
-
-@c @node Index
-@c @unnumbered Index
-@c
-@c @printindex cp
-
-@bye
projects / people / ms / gcc.git / commitdiff
